Headless Kit v0.2.2

Contributing

Thinking about contributing to the project, but don't know where to start? You're in the right place!

We'll get you up in shape in no time, and ready to hop into the Qwik UI code cave.

The Qwik UI Code Cave

There are two projects we currently work on:

Qwik UI Headless

Don't know what a headless library is? This might help.

Fluffy.

A styled copy paste library with TailwindCSS inspired by Shadcn.

There's a lot of stuff here!

Yep, 99% of the time you're gonna be in two directories:

website - apps/website

packages - packages/kit-headless or packages/kit-fluffy

Which component should I work on?

Feel free to work on anything that doesn't have a stable tag on it! The components with the most priority have the planned or draft tags beside them.

Headless

Check out the introduction section to see the principles of Qwik UI, and the project goals. As a heads up, those may change over time with more discussion!

I don't know anything about accessibility, can I still contribute?

Of course! Neither did we before starting this project. Our go-to resource is the Aria Authoring Practices Guide. Find the component you're going for, and read through the component guide.

We also have plenty of other accessibility resources you can skim through. Feel free to ask questions!

When is a headless component beta?

It has features

It can be used for most common use cases, and maybe some advanced ones (if you'd like to go further).

What I like to do is look at other places around the web and see how things work! What kind of features do they have? Does someone already have a need for this in the Qwik community? How would I go about approaching this?

We also take inspiration from awesome headless libraries in other communities. For example, like the popular headless libraries below:

I love going through these projects and understanding the why and what problems they solve. What kinda features do all of them have in common? How do they name things? What conventions do they use? How satisfied are people consuming it?

I think this is a good way to figure out what to work on. That said, we also want to keep things simple, and not add features unless we know there is a demand for them (hence looking for similarities).

Tests

Tests ensure we can sleep sound at night and know that our component behavior is working as intended. Part of the Qwik core team, Shai Reznik (and also a contributor here!) talks a lot about test driven development.

TDD Process

We currently use playwright for testing.

Shai also has a testing course that Qwik UI contributors get access to for the price of FREE! Don't hesitate to reach out.

Docs

We use MDX for interactive markdown.

You can find the headless docs here.

When creating the docs, we have a showcase component, which gives typescript support, a component preview of your example, and automatically updates the code example as you edit it! 🤯

The same thing goes for our snippet component, which is for showing code blocks only.

Docs Components

We also have more docs components to make your life easier! Some examples being:

Notes

API table

PropTypeDescription
behavior
string

Determines whether the Accordion will open one or multiple items at a time.

onSelectedIndexChange$
function

An event hook that gets notified whenever the selected index changes.

onFocusIndexChange$
function

An event hook that gets notified whenever the focus index changes.

Feature list

Component status banner

WARNING: This component is in
Draft
status. This means that it is still in development and may have bugs or missing features. It is not intended to be used in production. You may use it for testing purposes.

info popup (uses the popover)

What if I only want to do docs contributions, is that ok?

Absolutely, documentation is a critical part of the project, and something that can be very much improved! I recommend checking out Sarah Rainsberg's Docs Guide, it's partly towards Astro, but is also a great general resource for writing good documentation.

Where should I learn the Qwik parts?

If you find yourself stuck on a certain pattern, try taking a look through Qwik UI beta components. For example, the modal component would be a good one to look through.

We're also happy to help! We love experimenting with things and having a blast while doing it.

What's something I should avoid?

useVisibleTask$. It's an escape hatch, and for 95% of UI components I can promise you that it's not needed.

You're pretty much saying "hey Qwik! All those benefits you do to lazy load and delay the execution of code? Let's throw those away".

Instead, look at it this way:

Where does my user interact with things? And how can I make sure that we can delay the execution of that code until the user ABSOLUTELY needs it.

Here's a code example I've seen in the Qwik discord. The developer is trying to make sure that an open menu navbar is closed when the window is resized over 1248px

useVisibleTask$(({ cleanup }) => {
  const updateDocumentClass = () => {
    if (menuOpen.value && window.innerWidth > 1248) {
      menuOpen.value = false;
      document.documentElement.classList.remove('modal-open');
    }
  };
 
  window.addEventListener('resize', updateDocumentClass);
 
  cleanup(() => {
    window.removeEventListener('resize', updateDocumentClass);
  });
});

Because this code is directly tied to an event, we should not be using a visible task. We could achieve the same result with:

useOnWindow('resize', $(() => {
  if (menuOpen.value && window.innerWidth > 1248) {
    menuOpen.value = false;
    document.documentElement.classList.remove('modal-open');
  }
});

We promise that creating ui elements gets easier once you have a clear mental model for API's like useTask$. Here are some alternatives to explore.

We want to squeeze as much possible performance out of Qwik, and stay with the principle that things execute on interaction. This allows consumers to have a fast app without even trying!

How do I make a PR?

We cover it in-depth in the contributing guide here.

That's it!

Hopefully you should have enough to get up and running with Qwik UI Headless, if you have any questions don't let us stop you from reaching out, and happy building :qwik:

If you'd like to work on the styled library that's entirely a possibility too, there's currently documentation on the headless is all.