Conventions

Writing documentation

Docs are a great way to understand things better, and also help others, but not all of us like writing docs, or are great writers.

Luckily, Sarah Rainsberger has a great talk on writing docs.

The Astro docs guide from Sarah has been Jack's go-to resource for writing docs. It mentions Astro, but the principles and style guide apply to most documentation.

• Docs are not "good" or "bad"
• Docs are not "complete"
• Docs are not "final"

The question to ask yourself is:

• Are these docs helpful?

Documenting things is a small sacrifice for a big benefit down the road. Whether that's for your future self, career, or for others.

Sig Suffix

Every signal (useComputed$, useSignal, useBoundSignal) should have a Sig suffix. This is to help prevent confusion between form controls with .value

const isSelectedSig = useSignal(false);

Signal props and the bind convention

The bind:x API's that expect a signal are really just a prop. The convention is to use bind: for signals, to stay consistent with Qwik's API (which was inspired by frameworks like Svelte and Angular).

<Select.Root bind:value={selectedValueSig} />

You also get typescript autocomplete for each bind on the component!

It is a requirement that you handle both signal based and value based state for each component.

Events

Naming

The most important event that handles the value change should always be named onChange$ on the Root piece.

Any other events should be named like on<EventName>Change$.

Ex: Listening to when the actual selected value changed

<Select.Root onChange$={...} />

Ex: Listening to when the Select popover is open

<Select.Root onOpenChange$={...} />

Event handling

All events, or functions inside the component should have a $ at the end of the name.

It is also preferred to use a reference to the QRL in the JSX rather than inlining the function.

const handleClick$ = $(() => {
    // do something
})

// Do this:
<button onClick$={[handleClick$, props.onClick$]}>
    <Slot />
</button>

// Not this:
<button onClick$={[() => {
    // do something
}, props.onClick$]}>
    <Slot />
</button>

Data Attributes

Each component should have an identifier data attribute.

Ex: data-qds-select-root

We use this both for styling (layout / behavioral css), and for testing.