@lumiose/ui 0.0.0-stage → 0.1.1

package/dist/checkbox/checkbox.script.ts

@@ -0,0 +1,225 @@
+// The client script of Checkbox, Checkbox Group, Radio Group and Switch (decision-62, decision-63).
+// They render native inputs, which toggle, submit, reset and validate on their own, in server HTML
+// and without JavaScript. This script closes the gaps next to Base UI (doc-9 sections 10 to 12):
+//
+// - Indeterminate: a checkbox's `indeterminate` is a property only, so the server renders
+//   `data-indeterminate` and the script turns it into the property (mixed for assistive
+//   technology, `:indeterminate` for CSS) and drops the attribute. Islands set the property.
+// - A parent checkbox (`data-parent`) in a Checkbox Group, after Base UI's: it is checked,
+//   unchecked or indeterminate as its group's checkboxes are, disabled ones counted (as the server
+//   counts them). Toggling it goes from a partial selection to all, then none, then back to the
+//   selection the user last made with the checkboxes; disabled checkboxes keep their state
+//   (TASK-458). Its `aria-controls` names the checkboxes. It has no `name`, so it is never
+//   submitted.
+// - Read-only (`aria-readonly="true"` on the input, or on a radio group): a click, Space or an arrow
+//   key does not change it. Native `readonly` does not apply to checkboxes and radios.
+// - A Radio Group's arrow keys, after the APG: Down and Right (Left right to left) check the next
+//   enabled radio, Up and Left the previous one, around the ends and past disabled radios. Native
+//   radios do it too, but not the same everywhere: WebKit stops at the ends and does not mirror
+//   Left and Right right to left (TASK-424).
+// - `data-unchecked-value` (a Checkbox's or Switch's `uncheckedValue`): an unchecked, enabled box
+//   with a name submits that value, appended to the form's data (the `formdata` event), so it
+//   comes after the form's other values. Without the script it submits nothing, as natively.
+//
+// It must not import `lumiose`: server-rendered pages load it without the runtime.
+
+// A form's controls and descendants, read through the prototypes: a control named `elements` or
+// `querySelectorAll` shadows the form's own member (DOM clobbering, TASK-473 L9).
+const formElements = (form: HTMLFormElement): HTMLFormControlsCollection =>
+  Object.getOwnPropertyDescriptor(HTMLFormElement.prototype, "elements")!.get!.call(form);
+const formQuery = <E extends Element>(form: HTMLFormElement, selectors: string) =>
+  Element.prototype.querySelectorAll.call(form, selectors) as NodeListOf<E>;
+
+const BOX = "input[type=checkbox]";
+
+/** Checkboxes the server rendered indeterminate: a form reset puts them back (TASK-446, L11). */
+const mixed = new WeakSet<HTMLInputElement>();
+
+/** The fieldset a checkbox belongs to, for a group. */
+const groupOf = (input: Element) => input.closest("fieldset");
+
+/** The group's checkboxes a parent follows: not parents, not nested; disabled ones included. */
+function children(group: HTMLFieldSetElement): HTMLInputElement[] {
+  return [...group.querySelectorAll<HTMLInputElement>(`${BOX}:not([data-parent])`)].filter(
+    (input) => groupOf(input) === group,
+  );
+}
+
+/** Each group's checked boxes as the user last chose them, one at a time: a parent restores it. */
+const chosen = new WeakMap<HTMLFieldSetElement, HTMLInputElement[]>();
+
+const same = (a: HTMLInputElement[], b: HTMLInputElement[]) =>
+  a.length === b.length && a.every((box) => b.includes(box));
+
+/** A parent's toggle: a partial choice → all → none → the choice again (Base UI's cycle). */
+function cycle(group: HTMLFieldSetElement): void {
+  const boxes = children(group);
+  const now = boxes.filter((box) => box.checked);
+  // Disabled boxes keep their state: "none" keeps the checked ones, "all" leaves out the others.
+  const none = boxes.filter((box) => box.disabled && box.checked);
+  const all = boxes.filter((box) => !box.disabled || box.checked);
+  const choice = chosen.get(group) ?? now;
+  const partial = choice.length > 0 && choice.length < all.length;
+  let next: HTMLInputElement[];
+  if (!partial) next = same(now, all) ? none : all;
+  else if (same(now, all)) next = none;
+  else if (same(now, none)) next = choice;
+  else next = all;
+  for (const box of boxes) if (!box.disabled) box.checked = next.includes(box);
+}
+
+/** Sets the group's parent checkboxes from their children. */
+function follow(group: HTMLFieldSetElement): void {
+  const boxes = children(group);
+  const checked = boxes.filter((input) => input.checked).length;
+  for (const parent of group.querySelectorAll<HTMLInputElement>(`${BOX}[data-parent]`)) {
+    if (groupOf(parent) !== group) continue;
+    parent.checked = boxes.length > 0 && checked === boxes.length;
+    parent.indeterminate = checked > 0 && checked < boxes.length;
+  }
+}
+
+const readOnly = (input: HTMLInputElement) =>
+  input.getAttribute("aria-readonly") === "true" ||
+  input.closest("[role=radiogroup]")?.getAttribute("aria-readonly") === "true";
+
+document.addEventListener(
+  "click",
+  (event) => {
+    const input = event.target;
+    if (!(input instanceof HTMLInputElement) || !/^(checkbox|radio)$/.test(input.type)) return;
+    // Cancelling the click undoes the toggle, for the mouse, a label, Space and the arrow keys.
+    if (readOnly(input)) event.preventDefault();
+  },
+  true,
+);
+
+document.addEventListener(
+  "change",
+  (event) => {
+    const input = event.target;
+    if (!(input instanceof HTMLInputElement) || input.type !== "checkbox") return;
+    // A toggle ends the server's indeterminate state.
+    input.removeAttribute("data-indeterminate");
+    const group = groupOf(input);
+    if (!group) return;
+    if (input.hasAttribute("data-parent")) cycle(group);
+    else
+      chosen.set(
+        group,
+        children(group).filter((box) => box.checked),
+      );
+    // Before the group's own `change` listener, which reads the checkboxes.
+    follow(group);
+  },
+  true,
+);
+
+// `formdata` does not bubble: a capturing listener sees it.
+document.addEventListener(
+  "formdata",
+  (event) => {
+    const form = event.target as HTMLFormElement;
+    for (const input of formElements(form)) {
+      if (
+        input instanceof HTMLInputElement &&
+        input.type === "checkbox" &&
+        input.hasAttribute("data-unchecked-value") &&
+        input.name &&
+        !input.checked &&
+        !input.matches(":disabled")
+      ) {
+        event.formData.append(input.name, input.getAttribute("data-unchecked-value")!);
+      }
+    }
+  },
+  true,
+);
+
+document.addEventListener("keydown", (event) => {
+  const radio = event.target;
+  if (!(radio instanceof HTMLInputElement) || radio.type !== "radio" || event.defaultPrevented) {
+    return;
+  }
+  if (event.altKey || event.ctrlKey || event.metaKey || event.isComposing) return;
+  const group = radio.closest<HTMLElement>("[role=radiogroup]");
+  if (!group) return;
+  const rtl = getComputedStyle(radio).direction === "rtl";
+  const steps: Record<string, number> = {
+    ArrowDown: 1,
+    ArrowUp: -1,
+    ArrowRight: rtl ? -1 : 1,
+    ArrowLeft: rtl ? 1 : -1,
+  };
+  const step = steps[event.key];
+  if (!step) return;
+  const radios = [...group.querySelectorAll<HTMLInputElement>("input[type=radio]")].filter(
+    (each) =>
+      each.name === radio.name &&
+      each.closest("[role=radiogroup]") === group &&
+      !each.matches(":disabled"),
+  );
+  const at = radios.indexOf(radio);
+  if (at === -1) return;
+  event.preventDefault();
+  const next = radios[(at + step + radios.length) % radios.length]!;
+  next.focus();
+  // Checks it, with `input` and `change`; a read-only group cancels the click (above).
+  if (next !== radio) next.click();
+});
+
+document.addEventListener("reset", (event) => {
+  const form = event.target as HTMLFormElement;
+  // The checkboxes take their default state after the event.
+  setTimeout(() => {
+    for (const input of formQuery<HTMLInputElement>(form, BOX)) {
+      if (mixed.has(input)) input.indeterminate = true;
+    }
+    for (const parent of formQuery<HTMLInputElement>(form, `${BOX}[data-parent]`)) {
+      const group = groupOf(parent);
+      if (!group) continue;
+      chosen.delete(group);
+      follow(group);
+    }
+  });
+});
+
+// Shift+Tab into a radio group with nothing checked lands on its last radio in Chromium and
+// WebKit: the first enabled one takes focus instead, as Tab gives it (TASK-446, L13).
+document.addEventListener("focusin", (event) => {
+  const radio = event.target;
+  if (!(radio instanceof HTMLInputElement) || radio.type !== "radio") return;
+  const group = radio.closest<HTMLElement>("[role=radiogroup]");
+  if (!group || group.contains(event.relatedTarget as Node | null)) return;
+  const radios = [...group.querySelectorAll<HTMLInputElement>("input[type=radio]")].filter(
+    (each) => each.name === radio.name && each.closest("[role=radiogroup]") === group,
+  );
+  if (radios.some((each) => each.checked)) return;
+  const first = radios.find((each) => !each.matches(":disabled"));
+  if (first && first !== radio) first.focus();
+});
+
+function start() {
+  for (const input of document.querySelectorAll<HTMLInputElement>(`${BOX}[data-indeterminate]`)) {
+    // From here on the property, and `:indeterminate`, hold the state.
+    input.indeterminate = true;
+    if (!input.hasAttribute("data-parent")) mixed.add(input);
+    input.removeAttribute("data-indeterminate");
+  }
+  // A parent names its checkboxes as they are, ids of their own included.
+  for (const parent of document.querySelectorAll<HTMLInputElement>(`${BOX}[data-parent]`)) {
+    const group = groupOf(parent);
+    if (!group) continue;
+    const ids = children(group)
+      .map((box) => box.id)
+      .filter(Boolean);
+    if (ids.length > 0) parent.setAttribute("aria-controls", ids.join(" "));
+  }
+}
+if (document.readyState === "loading") {
+  document.addEventListener("DOMContentLoaded", start, { once: true });
+} else queueMicrotask(start);
+
+// A module, so it runs once per page whoever imports it.
+// oxlint-disable-next-line unicorn/require-module-specifiers
+export {};

package/dist/checkbox/checkbox.tsx

@@ -0,0 +1,156 @@
+// Checkbox (decision-62, TASK-366): a native `<input type="checkbox">`, after Base UI's Checkbox.
+// The platform toggles it with Space and a label click, submits its value when checked, resets it
+// with its form and validates `required`, in server HTML and without JavaScript. Inside a Field it
+// takes the field's id, name and ARIA references; inside a CheckboxGroup, its checked state and
+// name. checkbox.script.ts (decision-63) adds the indeterminate state of server HTML, the parent
+// checkbox of a group and read-only.
+import { effect, isServer, ref, untrack, useContext } from "lumiose";
+import { fieldProps, useField, useFormValues } from "../field/context.ts";
+import checkboxScript from "./checkbox.script.ts?client";
+import { CheckboxGroupContext, optionId, type CheckboxGroupContextValue } from "./context.ts";
+import { afterFormReset, onFormReset } from "../form/reset.ts";
+
+/**
+ * The native checkbox props Root passes through (`name`, `required`, `disabled`, `form`, `id`,
+ * `class`, `aria-*`, events), without the brand of intrinsic elements' props, so that
+ * `bind:checked` applies to Root.
+ */
+type InputProps = Omit<
+  JSX.IntrinsicElements["input"],
+  symbol | "type" | "checked" | "value" | "bind:checked" | "bind:value" | "readonly"
+>;
+
+/**
+ * `Checkbox.Root` renders an `<input type="checkbox">`. `bind:checked={signal}` stands in for
+ * `checked` and `onCheckedChange`.
+ */
+export type CheckboxRootProps = InputProps & {
+  /** Checks (`true`) or unchecks it when it changes. Pair it with `onCheckedChange`. */
+  checked?: boolean;
+  /** Whether it starts checked when `checked` is left out; a form reset goes back to it. */
+  defaultChecked?: boolean;
+  /** Called after the user checks or unchecks it. */
+  onCheckedChange?: (checked: boolean) => void;
+  /**
+   * Shows it as neither checked nor unchecked (`:indeterminate`, mixed for assistive technology)
+   * until the user toggles it.
+   */
+  indeterminate?: boolean;
+  /**
+   * The value it submits when checked (default `"on"`), and its identity in a CheckboxGroup's
+   * `value`.
+   */
+  value?: string;
+  /**
+   * The "select all" checkbox of a CheckboxGroup: it checks every checkbox of the group, and is
+   * checked, unchecked or indeterminate as they are. It is not submitted.
+   */
+  parent?: boolean;
+  /** It cannot be toggled, but stays focusable and is submitted (`aria-readonly`). */
+  readOnly?: boolean;
+  /**
+   * The value it submits when unchecked; by default an unchecked checkbox submits nothing. Needs
+   * the client script (`data-unchecked-value`).
+   */
+  uncheckedValue?: string;
+};
+
+/** A parent's `aria-controls`: its group's checkboxes, from `allValues` (TASK-458). */
+const controls = (group: CheckboxGroupContextValue) =>
+  (group.allValues() ?? []).map((value) => optionId(group, value)).join(" ") || undefined;
+
+function Root({
+  checked,
+  defaultChecked,
+  onCheckedChange,
+  indeterminate,
+  value,
+  parent,
+  readOnly,
+  uncheckedValue,
+  ...rest
+}: CheckboxRootProps) {
+  // Indeterminate in server HTML, parent checkboxes and read-only; the page loads it once.
+  checkboxScript();
+  const field = useField();
+  const group = useContext(CheckboxGroupContext);
+  // A failed submission's values (a Form's `values`): checked when they hold its value (TASK-430).
+  const sent =
+    group || parent
+      ? undefined
+      : useFormValues(
+          untrack(() => rest.name ?? field?.name()),
+          untrack(() => rest.disabled),
+        );
+  const initial = untrack(() => (sent ? sent.includes(value ?? "on") : defaultChecked));
+  /** A parent's state from the group: checked when every value is, mixed when some are. */
+  const parentState = () => {
+    const all = group?.allValues() ?? [];
+    const on = all.filter((each) => group!.values().includes(each)).length;
+    return { checked: all.length > 0 && on === all.length, mixed: on > 0 && on < all.length };
+  };
+  const isChecked = () => {
+    if (checked !== undefined) return checked;
+    if (group && parent) return parentState().checked;
+    if (group && value !== undefined) return group.values().includes(value);
+    return initial;
+  };
+  const isMixed = () =>
+    indeterminate === true || (group !== undefined && parent === true && parentState().mixed);
+  // `indeterminate` is a property only: the server writes `data-indeterminate`, which the script
+  // turns into the property; in the browser the component sets it.
+  const input = ref<HTMLInputElement>();
+  // A reset makes a checkbox the user toggled indeterminate again, as it started (TASK-446, L11).
+  afterFormReset(input, () => {
+    const element = input();
+    if (element) element.indeterminate = untrack(isMixed);
+  });
+  // A form reset fires no `change`: the reset state goes to `onCheckedChange` (TASK-435). In a
+  // group, the group reports it.
+  if (onCheckedChange && !group && !parent) {
+    onFormReset(input, () => input()!.checked, onCheckedChange);
+  }
+  effect(() => {
+    const element = input();
+    if (element) element.indeterminate = isMixed();
+  });
+  return (
+    <input
+      {...rest}
+      // In a group the group takes the field's id and ARIA references (TASK-439, M25).
+      {...(group ? {} : fieldProps(field, rest))}
+      ref={(element: HTMLInputElement) => {
+        input(element);
+        rest.ref?.(element);
+      }}
+      type="checkbox"
+      // In a group, `<group>-<value>`, which a parent's `aria-controls` names (TASK-458).
+      {...(group && !parent && value !== undefined && rest.id === undefined
+        ? { id: optionId(group, value) }
+        : {})}
+      {...(group && parent ? { "aria-controls": controls(group) } : {})}
+      // A parent is never submitted.
+      name={parent ? undefined : (rest.name ?? group?.name() ?? field?.name())}
+      value={value}
+      checked={isChecked()}
+      data-indeterminate={isServer && isMixed() ? "" : undefined}
+      data-parent={parent ? "" : undefined}
+      aria-readonly={readOnly ? "true" : undefined}
+      data-unchecked-value={uncheckedValue}
+      on:change={(event: Event) =>
+        onCheckedChange?.((event.currentTarget as HTMLInputElement).checked)
+      }
+    />
+  );
+}
+
+/**
+ * A native checkbox. Unstyled: style it through `class` and `:checked`, `:indeterminate`,
+ * `:disabled` and `:focus-visible` (with `appearance: none` to draw your own box).
+ *
+ * @example
+ * <label>
+ *   <Checkbox.Root name="terms" required /> I accept the terms
+ * </label>
+ */
+export const Checkbox = { Root };

package/dist/checkbox/context.ts

@@ -0,0 +1,17 @@
+// The context a CheckboxGroup gives its checkboxes: the selected values, every value (for a parent
+// checkbox) and the name they submit under.
+import { createContext } from "lumiose";
+
+export interface CheckboxGroupContextValue {
+  /** The group's id: its checkboxes' ids are `<id>-<value>`, which a parent's `aria-controls` names. */
+  id: string;
+  values: () => readonly string[];
+  allValues: () => readonly string[] | undefined;
+  name: () => string | undefined;
+}
+
+export const CheckboxGroupContext = createContext<CheckboxGroupContextValue>();
+
+/** The id of a group's checkbox of `value`: ids may not hold spaces. */
+export const optionId = (group: CheckboxGroupContextValue, value: string) =>
+  `${group.id}-${encodeURIComponent(value).replaceAll("%", "_")}`;

package/dist/checkbox-group/checkbox-group.tsx

@@ -0,0 +1,111 @@
+// CheckboxGroup (decision-62, TASK-366): a native `<fieldset>` of checkboxes that share a name and
+// a value (the checked ones' values), after Base UI's CheckboxGroup. The form submits each checked
+// box under the name, and a disabled group disables them all, without JavaScript. A parent
+// checkbox (`Checkbox.Root parent`) checks them all; checkbox.script.ts keeps it in step.
+import { effect, ref, signal, untrack, useId } from "lumiose";
+import checkboxScript from "../checkbox/checkbox.script.ts?client";
+import { CheckboxGroupContext } from "../checkbox/context.ts";
+import { describedBy, labelledBy, useField, useFormValues } from "../field/context.ts";
+import { onFormReset } from "../form/reset.ts";
+
+/** The fieldset props CheckboxGroup passes through, without the brand of intrinsic elements' props. */
+type FieldsetProps = Omit<JSX.IntrinsicElements["fieldset"], symbol>;
+
+/**
+ * `CheckboxGroup` renders a `<fieldset>`; name it with a `Fieldset.Legend` inside.
+ * `bind:value={signal}` stands in for `value` and `onValueChange`.
+ */
+export type CheckboxGroupProps = FieldsetProps & {
+  /** Checks the checkboxes with these values when it changes. Pair it with `onValueChange`. */
+  value?: string[];
+  /** The values checked at first, when `value` is left out. */
+  defaultValue?: string[];
+  /** Called with the checked values after the user checks or unchecks one. */
+  onValueChange?: (value: string[]) => void;
+  /** Every checkbox's value: a parent checkbox is checked when all of them are. */
+  allValues?: string[];
+  /** The name the checkboxes submit their values under, unless they have their own. */
+  name?: string;
+};
+
+/**
+ * A group of checkboxes with one value, the list of the checked ones, and an optional parent
+ * checkbox that checks them all.
+ *
+ * @example
+ * <CheckboxGroup name="toppings" defaultValue={["cheese"]}>
+ *   <Fieldset.Legend>Toppings</Fieldset.Legend>
+ *   <label><Checkbox.Root value="cheese" /> Cheese</label>
+ *   <label><Checkbox.Root value="olives" /> Olives</label>
+ * </CheckboxGroup>
+ */
+/** The values of the checked boxes: the DOM holds the state, a parent's toggle included. */
+const checked = (group: HTMLFieldSetElement) =>
+  [...group.querySelectorAll<HTMLInputElement>("input[type=checkbox]:not([data-parent])")]
+    .filter((input) => input.closest("fieldset") === group && input.checked)
+    .map((input) => input.value);
+
+export function CheckboxGroup({
+  value,
+  defaultValue,
+  onValueChange,
+  allValues,
+  name,
+  children,
+  ...rest
+}: CheckboxGroupProps) {
+  checkboxScript();
+  // In a field, the group takes the field's wiring, not each checkbox (TASK-439, M25).
+  const field = useField();
+  // A failed submission's values (a Form's `values`) replace the default (TASK-430).
+  const sent = useFormValues(
+    untrack(() => name ?? field?.name()),
+    untrack(() => rest.disabled),
+  );
+  const values = signal<readonly string[]>(untrack(() => value ?? sent ?? defaultValue ?? []));
+  // The `value` prop drives the checkboxes when it changes.
+  effect(() => {
+    const next = value;
+    if (next !== undefined) values.set(next);
+  });
+  const id = useId();
+  const context = {
+    id,
+    values,
+    allValues: () => allValues,
+    name: () => name ?? field?.name(),
+  };
+  const report = (next: string[]) => {
+    values.set(next);
+    onValueChange?.(next);
+  };
+  // A form reset puts the boxes back without a `change`: the group follows it (TASK-435).
+  const group = ref<HTMLFieldSetElement>();
+  onFormReset(group, () => checked(group()!), report);
+  return (
+    <CheckboxGroupContext value={context}>
+      <fieldset
+        {...rest}
+        ref={(element: HTMLFieldSetElement) => {
+          group(element);
+          rest.ref?.(element);
+        }}
+        // Explicit, so Field's script describes and marks the group as one, as a radiogroup.
+        role="group"
+        disabled={rest.disabled || field?.disabled() || undefined}
+        aria-labelledby={
+          rest["aria-labelledby"] ?? (rest["aria-label"] ? undefined : labelledBy(field))
+        }
+        aria-describedby={rest["aria-describedby"] ?? (field ? describedBy(field) : undefined)}
+        aria-invalid={rest["aria-invalid"] ?? (field?.invalid() ? "true" : undefined)}
+        on:change={(event: Event) => {
+          if (!(event.target as Element).matches("input[type=checkbox]")) return;
+          // checkbox.script.ts ran first, for a parent's toggle.
+          report(checked(event.currentTarget as HTMLFieldSetElement));
+        }}
+      >
+        {children}
+      </fieldset>
+    </CheckboxGroupContext>
+  );
+}

package/dist/collapsible/collapsible.css

@@ -0,0 +1,12 @@
+/*
+ * Collapsible is a native <details>: the browser shows and hides its panel. What it needs on top:
+ * a disabled trigger (aria-disabled, which a <summary> has instead of `disabled`) ignores the
+ * pointer, also before the client script loads.
+ */
+@layer lu.core, lu.theme;
+
+@layer lu.core {
+  summary[aria-disabled="true"] {
+    pointer-events: none;
+  }
+}

package/dist/collapsible/collapsible.script.ts

@@ -0,0 +1,7 @@
+// Collapsible's client script (decision-62, decision-63): the component works without it, as a
+// native `<details>`; on a page that renders one, it runs once and adds the panel's open and close
+// measurements and the disabled trigger (./panel.ts), for every Collapsible and Accordion panel.
+// It must not import `lumiose`: server-rendered pages load it without the runtime.
+import { watchPanels } from "./panel.ts";
+
+watchPanels();