@lumiose/ui 0.0.0-stage → 0.1.0

package/docs/checkbox-group.md

@@ -0,0 +1,112 @@
+# Checkbox Group
+
+> A group of checkboxes with one value, the list of the checked ones, after Base UI's CheckboxGroup: a native `<fieldset>` whose checkboxes share a name, so the form submits each checked value and a disabled group disables them all, without JavaScript. A parent checkbox checks them all and shows checked, mixed or unchecked as they are; `bind:value` keeps a signal in sync.
+
+```ts
+import { CheckboxGroup, Checkbox, Fieldset } from "@lumiose/ui"; // or "@lumiose/ui/checkbox-group"
+import "@lumiose/ui/themes/default.css"; // optional: the default theme
+```
+
+## Anatomy
+
+```tsx
+<CheckboxGroup>
+  <Fieldset.Legend />
+  <Checkbox.Root parent />
+  <Checkbox.Root />
+</CheckboxGroup>
+```
+
+| Part            | Renders                                                                             |
+| --------------- | ----------------------------------------------------------------------------------- |
+| `CheckboxGroup` | `<fieldset>` around the checkboxes; a `Fieldset.Legend` first inside names it.      |
+| `Checkbox.Root` | A [Checkbox](checkbox.md) of the group, checked when its `value` is in the group's. |
+
+## API
+
+### CheckboxGroup
+
+| Prop            | Type                        | Default |                                                                                        |
+| --------------- | --------------------------- | ------- | -------------------------------------------------------------------------------------- |
+| `value`         | `string[]`                  |         | Checks the checkboxes with these values when it changes. Pair it with `onValueChange`. |
+| `defaultValue`  | `string[]`                  | `[]`    | The values checked at first.                                                           |
+| `onValueChange` | `(value: string[]) => void` |         | Called with the checked values after the user checks or unchecks one.                  |
+| `bind:value`    | `Signal<string[]>`          |         | Stands in for `value` and `onValueChange`.                                             |
+| `allValues`     | `string[]`                  |         | Every checkbox's value: the parent checkbox's state in server HTML.                    |
+| `name`          | `string`                    |         | The name the checkboxes submit under, unless they have their own.                      |
+| `disabled`      | `boolean`                   | `false` | Disables every checkbox (a disabled fieldset).                                         |
+
+Every other `<fieldset>` prop passes through.
+
+**Differences from Base UI's CheckboxGroup.** It renders a `<fieldset>`, so a legend names it and
+`disabled` is native. `name` is added: Base UI gives each checkbox its own. A parent checkbox
+needs only `parent` here, not a controlled group, since the script runs it from the DOM. There is
+no `required` (one box checked at least), as in Base UI: HTML has no such constraint for a group,
+so it would work only with a script and an unlocalized message of ours. Check it in the form
+action instead and return the message with `fail()`: it renders with the page, without JavaScript
+too.
+
+## Example
+
+Toppings in a server-rendered form, with a "select all" box:
+
+```tsx check
+import { Checkbox, CheckboxGroup, Fieldset } from "@lumiose/ui";
+
+const TOPPINGS = ["Cheese", "Olives", "Peppers"];
+
+export function ToppingsGroup() {
+  return (
+    <CheckboxGroup
+      name="toppings"
+      defaultValue={["Cheese"]}
+      allValues={TOPPINGS}
+      class="lu-fieldset"
+    >
+      <Fieldset.Legend>Toppings</Fieldset.Legend>
+      <label>
+        <Checkbox.Root parent class="lu-checkbox" /> All toppings
+      </label>
+      {TOPPINGS.map((topping) => (
+        <label>
+          <Checkbox.Root value={topping} class="lu-checkbox" /> {topping}
+        </label>
+      ))}
+    </CheckboxGroup>
+  );
+}
+```
+
+## Styling
+
+**With the default theme**, put `lu-fieldset` on the group and `lu-checkbox` on each checkbox
+([Checkbox](checkbox.md#styling)). Style a parent checkbox with `[data-parent]` if it should look
+different.
+
+CheckboxGroup ships no stylesheet: it needs none to work.
+
+## Keyboard and focus
+
+Each checkbox is its own tab stop; Space toggles the focused one. The parent is checked, mixed or
+unchecked as all, some or none of the group's checkboxes are, disabled ones counted (as the server
+counts them, from `allValues`). Toggling it goes, as Base UI's, from a partial selection to all,
+then to none, then back to the selection the user last made with the checkboxes; disabled
+checkboxes keep their state through it. Its `aria-controls` names the checkboxes, whose ids are
+the group's and their values (`<id>-<value>`) unless you give them your own.
+
+## Without JavaScript, and the client script
+
+The checkboxes are native: they toggle, submit under the group's name and reset with no script.
+The parent checkbox shows its server state and is never submitted, but checks nothing until the
+shared checkbox script (1.0 kB brotli, [Checkbox](checkbox.md#without-javascript-and-the-client-script))
+runs.
+
+## Browser support
+
+Every supported browser.
+
+## Related
+
+- [Checkbox](checkbox.md): the checkboxes, `indeterminate` and `readOnly`.
+- [Fieldset](fieldset.md): the legend.
+- [Radio Group](radio-group.md): one value out of several.

package/docs/checkbox.md

@@ -0,0 +1,133 @@
+# Checkbox
+
+> A native `<input type="checkbox">`, after Base UI's Checkbox: Space and a label click toggle it, the form submits its value when checked, reset and `required` work, in server HTML and without JavaScript. `indeterminate`, `readOnly`, the parent checkbox of a [Checkbox Group](checkbox-group.md) and `bind:checked` come on top, with a 1.0 kB script shared with Radio Group and Switch.
+
+```ts
+import { Checkbox } from "@lumiose/ui"; // or "@lumiose/ui/checkbox"
+import "@lumiose/ui/themes/default.css"; // optional: the default theme
+```
+
+## Anatomy
+
+```tsx
+<label>
+  <Checkbox.Root /> Label
+</label>
+```
+
+| Part   | Renders                                                                                                           |
+| ------ | ----------------------------------------------------------------------------------------------------------------- |
+| `Root` | `<input type="checkbox">`; `data-indeterminate` in server HTML while indeterminate, `aria-readonly` if read-only. |
+
+Name it with a wrapping `<label>`, a `<label for>`, a `Field.Label`, or `aria-label`.
+
+## API
+
+### Checkbox.Root
+
+| Prop              | Type                         | Default |                                                                                                                         |
+| ----------------- | ---------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------- |
+| `checked`         | `boolean`                    |         | Checks or unchecks it when it changes. Pair it with `onCheckedChange`.                                                  |
+| `defaultChecked`  | `boolean`                    | `false` | Whether it starts checked; a form reset goes back to it.                                                                |
+| `onCheckedChange` | `(checked: boolean) => void` |         | Called after the user checks or unchecks it.                                                                            |
+| `bind:checked`    | `Signal<boolean>`            |         | Stands in for `checked` and `onCheckedChange`.                                                                          |
+| `indeterminate`   | `boolean`                    | `false` | Neither checked nor unchecked (mixed for assistive technology) until the user toggles it, and again after a form reset. |
+| `value`           | `string`                     | `"on"`  | What it submits when checked, and its identity in a Checkbox Group.                                                     |
+| `parent`          | `boolean`                    | `false` | The "select all" checkbox of a Checkbox Group: it checks them all and follows them. Never submitted.                    |
+| `readOnly`        | `boolean`                    | `false` | It cannot be toggled, but stays focusable and is submitted.                                                             |
+| `uncheckedValue`  | `string`                     |         | What it submits when unchecked (by the script); by default an unchecked box submits nothing.                            |
+
+Every other native prop passes through: `name`, `required`, `disabled`, `form`, `id`, `class`,
+`aria-*`. Inside a Field it takes the field's `id`, `name`, `aria-describedby` and
+`aria-invalid`; inside a Checkbox Group, its `checked` state and `name`.
+
+**Differences from Base UI's Checkbox.** The box is the native input, so there is no
+`Checkbox.Indicator`: draw the box and its mark with `appearance: none` and `::before` (as the
+default theme does). There is no `nativeButton` or `inputRef`. `uncheckedValue` needs the client
+script: without it an unchecked box submits nothing, as a native one does.
+
+## Example
+
+In an island, bound to a signal:
+
+```tsx check
+import { Checkbox } from "@lumiose/ui";
+import { signal } from "lumiose";
+
+export function NewsletterOptIn() {
+  const subscribed = signal(false);
+  return (
+    <p>
+      <label>
+        <Checkbox.Root name="newsletter" bind:checked={subscribed} class="lu-checkbox" /> Send me
+        the newsletter
+      </label>{" "}
+      {subscribed() ? "Thanks!" : ""}
+    </p>
+  );
+}
+```
+
+## Styling
+
+**With the default theme**, put `lu-checkbox` on `Root`: an 18px box drawn by `::before` inside a
+24px target, a ✓ when checked and a dash when indeterminate (a symbol, not only a colour), the
+primary colour for both, a focus ring, a red border with `aria-invalid="true"`.
+
+**With your own CSS**, style the input and its state: `:checked`, `:indeterminate` (and
+`[data-indeterminate]` before the script runs), `:disabled`, `:focus-visible`,
+`[aria-readonly="true"]`, `[aria-invalid="true"]`.
+
+```css
+.checkbox {
+  appearance: none;
+  inline-size: 1.25rem;
+  block-size: 1.25rem;
+  border: 1px solid #85858e;
+  border-radius: 0.25rem;
+}
+.checkbox:checked {
+  background: #2563eb;
+}
+.checkbox:checked::before {
+  content: "✓" / "";
+  color: #fff;
+}
+```
+
+Checkbox ships no stylesheet: it needs none to work.
+
+## Keyboard and focus
+
+| Key   | Does                                                   |
+| ----- | ------------------------------------------------------ |
+| Space | Toggles it (not when read-only).                       |
+| Tab   | Moves to the next control: a checkbox is one tab stop. |
+
+Enter does not toggle it. A click on its label toggles it too.
+
+## Without JavaScript, and the client script
+
+A native checkbox: toggling, submission, `required`, reset and `disabled` (its own or a fieldset's)
+work with no script.
+
+A page that renders a Checkbox, Checkbox Group, Radio Group or Switch loads one 1.0 kB (brotli)
+script once, without the Lumiose runtime; islands bundle it. It turns server HTML's
+`data-indeterminate` into the `indeterminate` property (which has no attribute), makes read-only
+inputs ignore clicks, Space and the label, runs the parent checkbox of a group and a [Radio
+Group](radio-group.md)'s arrow keys, and adds an
+unchecked box's `uncheckedValue` (`data-unchecked-value`) to its form's data (the `formdata`
+event, so it comes after the form's other values; a disabled box submits nothing). Without it, an
+indeterminate box shows unchecked (the theme still draws it mixed), a read-only one toggles, and
+an unchecked one submits nothing: treat a missing value as unchecked on the server too.
+
+## Browser support
+
+Native checkboxes, `:indeterminate` and `appearance: none` with `::before`: every supported
+browser.
+
+## Related
+
+- [Checkbox Group](checkbox-group.md): several checkboxes with one value and a parent checkbox.
+- [Switch](switch.md): on and off for a setting that applies at once.
+- [Field](field.md): a label, a description and errors for a checkbox.

package/docs/collapsible.md

@@ -0,0 +1,165 @@
+# Collapsible
+
+> A panel that its trigger shows and hides: a native `<details>` whose `<summary>` is the trigger, so it works in server HTML with no JavaScript, keeps the browser's keyboard handling, and opens when find-in-page or a link lands inside it. A 0.7 kB script adds Base UI's animation hooks. `bind:open` (or `open` and `onOpenChange`) keeps a signal in sync in islands.
+
+```ts
+import { Collapsible } from "@lumiose/ui"; // or "@lumiose/ui/collapsible"
+import "@lumiose/ui/collapsible.css"; // a disabled trigger ignores the pointer
+import "@lumiose/ui/themes/default.css"; // optional: the default theme
+```
+
+## Anatomy
+
+```tsx
+<Collapsible.Root>
+  <Collapsible.Trigger />
+  <Collapsible.Panel />
+</Collapsible.Root>
+```
+
+| Part      | Renders                                                                                     |
+| --------- | ------------------------------------------------------------------------------------------- |
+| `Root`    | `<details>`, `open` while the panel shows.                                                  |
+| `Trigger` | `<summary aria-controls="…">`, the first child of `Root`: it opens and closes the panel.    |
+| `Panel`   | `<div>`, the rest of the `<details>`: the browser hides it while the `<details>` is closed. |
+
+The browser exposes the `<summary>` as a button with its expanded state, so the trigger has no
+`aria-expanded` of its own. HTML allows one heading inside a `<summary>`, for a trigger that
+titles a section (Accordion renders its headings that way).
+
+## API
+
+### Collapsible.Root
+
+| Prop           | Type                      | Default |                                                                                                                                                   |
+| -------------- | ------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `open`         | `boolean`                 |         | Opens or closes the panel when it changes. Server HTML starts as it says.                                                                         |
+| `defaultOpen`  | `boolean`                 | `false` | Whether the panel starts open, when there is no `open`.                                                                                           |
+| `onOpenChange` | `(open: boolean) => void` |         | Called after the panel opens or closes, whatever did it: the trigger, find-in-page, a link, another item of its `name`; not when it renders open. |
+| `bind:open`    | `Signal<boolean>`         |         | Stands in for `open` and `onOpenChange`.                                                                                                          |
+| `disabled`     | `boolean`                 | `false` | The trigger takes no focus and does not toggle the panel.                                                                                         |
+
+Without `open`, `onOpenChange` or `bind:open` the element keeps its own state. `Root` takes the
+props of a `<details>` too: `name` makes collapsibles with the same name an exclusive group, where
+opening one closes the others.
+
+### The other parts
+
+Each part takes the props of the element it renders (`class`, `style`, `aria-*`, `data-*`, event
+handlers, `ref`) and passes them through. The `Trigger`'s `id` names it, and the `Panel` points at
+it; the `Panel` keeps its own `id`, which the trigger points at (see [Ids](README.md#ids)), and
+`aria-controls` stays the trigger's own.
+
+- **`Trigger`**: a disabled trigger gets `aria-disabled="true"` and `tabindex="-1"`.
+- **`Panel`**: the client script sets `--lu-collapsible-panel-height` and `--lu-collapsible-panel-width`
+  on it while it opens and closes, and `data-starting-style` and `data-ending-style`
+  ([Styling](#styling)).
+
+## Example
+
+A section in a server-rendered page, with no island, styled by the default theme:
+
+```tsx check
+import { Collapsible } from "@lumiose/ui";
+
+export function RecoveryKeys() {
+  return (
+    <Collapsible.Root class="lu-collapsible">
+      <Collapsible.Trigger>Recovery keys</Collapsible.Trigger>
+      <Collapsible.Panel>
+        <p>Store these keys somewhere safe: each one lets you back in once.</p>
+      </Collapsible.Panel>
+    </Collapsible.Root>
+  );
+}
+```
+
+In an island, bound to a signal: `bind:open={open}` is short for `open={open()}` plus
+`onOpenChange={(next) => open.set(next)}`.
+
+```tsx check
+import { Collapsible } from "@lumiose/ui";
+import { signal } from "lumiose";
+
+export function AdvancedOptions() {
+  const open = signal(false);
+  return (
+    <>
+      <Collapsible.Root class="lu-collapsible" bind:open={open}>
+        <Collapsible.Trigger>Advanced options</Collapsible.Trigger>
+        <Collapsible.Panel>Proxy, timeouts and retries.</Collapsible.Panel>
+      </Collapsible.Root>
+      <p>{open() ? "Showing the advanced options" : "Advanced options hidden"}</p>
+    </>
+  );
+}
+```
+
+## Styling
+
+**With the default theme**, put `lu-collapsible` on `Root`: the trigger becomes a row with a
+chevron that turns while the panel is open, and the panel's height animates.
+
+**With your own CSS**, style the parts through `class` and `[open]` on the root. The client script
+gives the panel what Base UI's does, for an open and close animation: `--lu-collapsible-panel-height`
+(the content's height in pixels while it moves, `auto` once open), `data-starting-style` for the
+frame an opening starts from and `data-ending-style` while it closes. The browser hides the panel
+as soon as the `<details>` closes, so keep it visible while it closes with a transition on
+`::details-content`:
+
+```css
+.collapsible > .panel {
+  overflow: hidden;
+  block-size: var(--lu-collapsible-panel-height, auto);
+  transition: block-size 200ms ease-out;
+}
+.collapsible > .panel:is([data-starting-style], [data-ending-style]) {
+  block-size: 0;
+}
+.collapsible::details-content {
+  transition: content-visibility 200ms allow-discrete;
+}
+```
+
+A panel rendered open does not animate. `@lumiose/ui/collapsible.css` holds one rule, in the
+`lu.core` layer: a disabled trigger (`summary[aria-disabled="true"]`) ignores the pointer.
+
+## Keyboard and focus
+
+| Key          | Does                                                                |
+| ------------ | ------------------------------------------------------------------- |
+| Enter, Space | On the trigger: opens or closes the panel.                          |
+| Tab          | Moves to the trigger, then into the open panel's focusable content. |
+
+The trigger is a `<summary>`, so the browser handles its keys and its focus. A disabled trigger is
+out of the tab order.
+
+## Without JavaScript, and the client script
+
+Opening and closing, the exclusive group of a `name`, and find-in-page are HTML features: a
+Collapsible in a server-rendered page works before any script loads, and with none. A disabled
+trigger ignores the pointer through CSS. `open`, `onOpenChange` and `bind:open` need the component
+to run in an island.
+
+A page that renders a `Collapsible` loads a 0.7 kB (brotli) module once, without the Lumiose
+runtime; islands bundle it. It covers every Collapsible and [Accordion](accordion.md) panel on the
+page:
+
+- the animation hooks above, set on every opening and closing, whatever caused it (the trigger,
+  find-in-page, a link, the `open` prop, another item of the group);
+- a disabled trigger does not toggle, also from the keyboard.
+
+## Browser support
+
+- **`<details>` and `<summary>`**: every browser. **`name`** (exclusive groups): Chrome 120,
+  Firefox 130, Safari 17.2.
+- **Find-in-page and links into a closed panel** open it: Chrome 97, Firefox 139. Safari has not
+  shipped it yet (WebKit bug 304174): there, find-in-page skips a closed panel.
+- **`::details-content`**, which the closing transition needs: Chrome 131, Firefox 143, Safari
+  18.4. Elsewhere the panel disappears at once when it closes.
+
+## Related
+
+- [Accordion](accordion.md): a stack of collapsible items, with arrow keys between them.
+- [UI components](README.md): the approach, styling and the other components.
+- [Theming](theming.md): the default theme's classes and custom properties.