@lumiose/ui 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Javi Aguilar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,54 @@
-# Temporary Holding Version
+# @lumiose/ui
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Accessible, unstyled UI primitives for [Lumiose](https://github.com/itsjavi/lumiose): native
+elements first (`<dialog>`, popover, invoker commands, CSS anchor positioning), light-DOM custom
+elements (`lu-*`) only where the platform falls short, server-rendered without hydration. Parts
+follow [Base UI](https://base-ui.com)'s anatomy; the approach is [Timeless](https://timeless.build)'s.
+
+**In development**: not on npm yet. It keeps its own 0.x versions, apart from the version the other
+Lumiose packages share.
+
+```tsx
+import { Dialog } from "@lumiose/ui";
+import "@lumiose/ui/styles.css"; // only the CSS the components need to work (`lu.core` layer)
+import "@lumiose/ui/themes/default.css"; // optional look: `--lu-` custom properties, light and dark
+
+<Dialog.Root role="alertdialog">
+  <Dialog.Trigger class="lu-button">Delete project…</Dialog.Trigger>
+  <Dialog.Popup class="lu-dialog">
+    <Dialog.Title>Delete project?</Dialog.Title>
+    <Dialog.Description>This removes the project and its deployments.</Dialog.Description>
+    <footer>
+      <Dialog.Close class="lu-button" value="cancel">
+        Cancel
+      </Dialog.Close>
+      <Dialog.Close class="lu-button" data-variant="destructive" value="delete">
+        Delete
+      </Dialog.Close>
+    </footer>
+  </Dialog.Popup>
+</Dialog.Root>;
+```
+
+The package ships its `.tsx` and `.css` sources, which the app's Lumiose compiler compiles for the
+server and the browser. Docs ship with it, for this version: `docs/` (`docs/llms.txt` indexes them;
+in a project, `node_modules/@lumiose/ui/docs/`), and `lumiose docs ui` prints them.
+
+- `pnpm --filter @lumiose/ui test`: unit tests (server rendering and the DOM, Vitest).
+- `pnpm --filter @lumiose/ui size`: JavaScript and CSS per component.
+- `pnpm --filter @lumiose-examples/ui-e2e test:e2e`: keyboard contracts, focus, axe and behaviour
+  without JavaScript, in Chromium; `test:e2e:browsers` runs them in Firefox and WebKit (CI's
+  ui-browsers workflow).
+
+## Writing a component
+
+The contract is decision-62 (native elements first, Base UI's anatomy, lowercase events, `bind:`,
+the `lu.core` layer, WCAG 2.2 AA) and each docs page follows `docs/dialog.md` (decision-64).
+
+- **A `lu-` element's getters have setters, or no prop shares their name.** On a custom element,
+  Lumiose sends a JSX prop to the element's property of that name when it has one (React 19's
+  rule; see the web components guide). A getter without a setter makes that assignment throw, and
+  the island's hydration fails. Read an attribute the component renders through a private getter
+  (`get #min()`) or another name. `src/elements.dom.test.ts` checks the attributes each component
+  writes on its `<lu-…>` tags against its element's read-only properties; props that pass through a
+  spread (`{...rest}`) are yours to check.

package/dist/accordion/accordion.css

@@ -0,0 +1,20 @@
+/*
+ * Accordion's items are native <details>: the browser shows and hides their panels. What they need
+ * on top: `<lu-accordion>`, a custom element, is inline until styled: it is a block, like the
+ * `<div>` it stands for; the heading inside a trigger stays on the same line as the <summary>'s
+ * marker; and a disabled trigger (aria-disabled) ignores the pointer, also before the client
+ * script loads.
+ */
+@layer lu.core, lu.theme;
+
+@layer lu.core {
+  lu-accordion {
+    display: block;
+  }
+  lu-accordion > details > summary > :is(h1, h2, h3, h4, h5, h6) {
+    display: inline;
+  }
+  summary[aria-disabled="true"] {
+    pointer-events: none;
+  }
+}

package/dist/accordion/accordion.script.ts

@@ -0,0 +1,66 @@
+// Accordion's client script (decision-62, decision-63): defines `<lu-accordion>`, the light-DOM
+// element that Accordion.Root renders, and starts the panels' animation hooks and disabled triggers
+// (../collapsible/panel.ts). The items are native `<details>` right inside it, so opening and
+// closing, the exclusive group (`name`) and find-in-page need no script. The element adds the
+// optional keys of the APG Accordion pattern, as Base UI and Zag have them (doc-9 §9):
+//
+// - Down and Up move focus to the next and the previous trigger (Right and Left when the root has
+//   `data-orientation="horizontal"`, swapped in right-to-left); Home and End to the first and the
+//   last. Focus loops unless the root has `data-loop-focus="false"`.
+// - Disabled triggers (`aria-disabled="true"`) are skipped.
+//
+// It must not import `lumiose`: server-rendered pages load it without the runtime.
+import { watchPanels } from "../collapsible/panel.ts";
+
+watchPanels();
+
+const enabled = (trigger: HTMLElement) => trigger.getAttribute("aria-disabled") !== "true";
+
+export class LuAccordion extends HTMLElement {
+  /** The triggers of its own items, in order. */
+  get triggers(): HTMLElement[] {
+    return [...this.querySelectorAll<HTMLElement>(":scope > details > summary")];
+  }
+
+  connectedCallback() {
+    this.addEventListener("keydown", this.#onKeyDown);
+  }
+
+  disconnectedCallback() {
+    this.removeEventListener("keydown", this.#onKeyDown);
+  }
+
+  #onKeyDown = (event: KeyboardEvent) => {
+    if (event.altKey || event.ctrlKey || event.metaKey || event.shiftKey) return;
+    const triggers = this.triggers;
+    const current = triggers.indexOf(event.target as HTMLElement);
+    if (current === -1) return;
+    const horizontal = this.dataset["orientation"] === "horizontal";
+    const rtl = getComputedStyle(this).direction === "rtl";
+    const forward = horizontal ? (rtl ? "ArrowLeft" : "ArrowRight") : "ArrowDown";
+    const backward = horizontal ? (rtl ? "ArrowRight" : "ArrowLeft") : "ArrowUp";
+    const loop = this.dataset["loopFocus"] !== "false";
+    const usable = triggers.filter(enabled);
+    let next: HTMLElement | undefined;
+    if (event.key === "Home") next = usable[0];
+    else if (event.key === "End") next = usable.at(-1);
+    else if (event.key === forward || event.key === backward) {
+      const step = event.key === forward ? 1 : -1;
+      for (let at = current + step; ; at += step) {
+        if (at < 0 || at >= triggers.length) {
+          if (!loop) break;
+          at = at < 0 ? triggers.length - 1 : 0;
+        }
+        if (at === current) break;
+        if (enabled(triggers[at]!)) {
+          next = triggers[at];
+          break;
+        }
+      }
+    } else return;
+    event.preventDefault();
+    next?.focus();
+  };
+}
+
+if (!customElements.get("lu-accordion")) customElements.define("lu-accordion", LuAccordion);

package/dist/accordion/accordion.tsx

@@ -0,0 +1,288 @@
+// Accordion (decision-62, TASK-370): Root renders `<lu-accordion>`, and each item is a native
+// `<details>` with its `<summary>` as the trigger, so items open and close in server HTML with no
+// JavaScript, find-in-page opens them, and one open item at a time is the browser's exclusive
+// group (`name`). The element's script (accordion.script.ts) adds the arrow keys, Home and End of
+// the APG Accordion pattern and Base UI's animation hooks. The items' `toggle` events are the
+// single source of `onValueChange`. Ported from Timeless's approach (https://timeless.build).
+import {
+  createContext,
+  effect,
+  onCleanup,
+  ref,
+  signal,
+  untrack,
+  useContext,
+  useId,
+  type Signal,
+} from "lumiose";
+import defineAccordion from "./accordion.script.ts?client";
+import type { LuAccordion } from "./accordion.script.ts";
+
+declare module "lumiose/jsx-runtime" {
+  namespace JSX {
+    interface IntrinsicElements {
+      /** Accordion.Root's element: it moves focus between its items' triggers. */
+      "lu-accordion": JSX.HTMLProps<LuAccordion>;
+    }
+  }
+}
+
+/**
+ * The element props Root passes to `<lu-accordion>` (`class`, `style`, `data-*`, `aria-*`,
+ * events), without the brand of intrinsic elements' props, so that `bind:value` applies to Root.
+ */
+type ElementProps = {
+  [
+    K in keyof JSX.HTMLProps<LuAccordion> as K extends string ? K : never
+  ]: JSX.HTMLProps<LuAccordion>[K];
+};
+
+/**
+ * `Accordion.Root` renders `<lu-accordion>`, with the element props it is given.
+ * `bind:value={signal}` stands in for `value` and `onValueChange`.
+ */
+export interface AccordionRootProps extends Omit<ElementProps, "children"> {
+  /**
+   * The values of the open items: opens and closes them when it changes. Pair it with
+   * `onValueChange` to keep a signal in sync; leave both out and the items keep their own state.
+   */
+  value?: string[];
+  /** The items open at first, when there is no `value`. Default: none. */
+  defaultValue?: string[];
+  /** Called after an item opens or closes, with the values of the open items. */
+  onValueChange?: (value: string[]) => void;
+  /** Several items may be open at once. Default `false`: opening one closes the other. */
+  multiple?: boolean;
+  /** Every item is disabled. */
+  disabled?: boolean;
+  /** The direction the arrow keys follow. Default `"vertical"`: Up and Down. */
+  orientation?: "vertical" | "horizontal";
+  /** The arrow keys go from the last trigger to the first and back. Default `true`. */
+  loopFocus?: boolean;
+  /** The `Accordion.Item`s, right inside it. */
+  children?: JSX.Element;
+}
+
+/** An item: a `<details>` right inside `Accordion.Root`, with its trigger and its panel. */
+export interface AccordionItemProps extends Omit<
+  JSX.IntrinsicElements["details"],
+  "open" | "name" | "children"
+> {
+  /** Identifies the item in the root's `value`. Default: an id of its own. */
+  value?: string;
+  /** Its trigger takes no focus and does not toggle the panel. */
+  disabled?: boolean;
+  /** Called after the item opens or closes. */
+  onOpenChange?: (open: boolean) => void;
+  /** The `Accordion.Header` with the `Accordion.Trigger`, then the `Accordion.Panel`. */
+  children?: JSX.Element;
+}
+
+/**
+ * The item's heading, an `<h3>`, around the trigger's label. HTML allows a heading in a
+ * `<summary>`, not a `<summary>` in a heading, so the `<h3>` is rendered inside the trigger. Set
+ * `aria-level` for another level.
+ */
+export type AccordionHeaderProps = JSX.IntrinsicElements["h3"];
+/** The `<summary>` that opens and closes the item: put it inside `Accordion.Header`. */
+export type AccordionTriggerProps = JSX.IntrinsicElements["summary"];
+/** The `<div role="region">` that the trigger shows and hides, labelled by the trigger. */
+export type AccordionPanelProps = JSX.IntrinsicElements["div"];
+
+interface ItemRecord {
+  value: string;
+  details: () => HTMLDetailsElement | undefined;
+}
+
+interface AccordionContextValue {
+  id: string;
+  multiple: boolean;
+  disabled: () => boolean;
+  /** Whether `value` starts open. */
+  initiallyOpen: (value: string) => boolean;
+  items: Signal<ItemRecord[]>;
+  /** An item's `toggle` event. */
+  onToggle: (value: string, open: boolean) => void;
+}
+
+interface ItemContextValue {
+  triggerId: string;
+  panelId: string;
+  disabled: () => boolean;
+}
+
+const AccordionContext = createContext<AccordionContextValue>();
+const ItemContext = createContext<ItemContextValue>();
+/** The props of the `Accordion.Header` around a trigger. */
+const HeaderContext = createContext<AccordionHeaderProps>();
+
+function useAccordion(): AccordionContextValue {
+  const context = useContext(AccordionContext);
+  if (!context) throw new Error("Accordion parts must be inside <Accordion.Root>.");
+  return context;
+}
+
+function useItem(): ItemContextValue {
+  const context = useContext(ItemContext);
+  if (!context) throw new Error("Accordion parts must be inside an <Accordion.Item>.");
+  return context;
+}
+
+function Root({
+  value,
+  defaultValue,
+  onValueChange,
+  multiple,
+  disabled,
+  orientation,
+  loopFocus,
+  children,
+  ...rest
+}: AccordionRootProps) {
+  // The arrow keys and the panels' animation hooks; the page loads it once (decision-63).
+  defineAccordion();
+  const id = useId();
+  const several = untrack(() => multiple === true);
+  const initial = untrack(() => value ?? defaultValue ?? []);
+  /** The open items' values, as the elements last reported or were set to. */
+  let open = several ? initial : initial.slice(0, 1);
+  const items = signal<ItemRecord[]>([]);
+  const context: AccordionContextValue = {
+    id,
+    multiple: several,
+    disabled: () => disabled === true,
+    initiallyOpen: (of) => open.includes(of),
+    items,
+    onToggle: (of, now) => {
+      const next = now
+        ? [...open.filter((each) => each !== of && context.multiple), of]
+        : open.filter((each) => each !== of);
+      if (next.length === open.length && next.every((each) => open.includes(each))) return;
+      open = next;
+      onValueChange?.(next);
+    },
+  };
+
+  // The `value` prop opens and closes the items when it changes; their `toggle` events report
+  // back, so a signal written by `onValueChange` sees the same value again and nothing loops.
+  effect(() => {
+    const wanted = value;
+    if (wanted === undefined) return;
+    // The `toggle` events of the changes below then report nothing new.
+    open = several ? wanted : wanted.slice(0, 1);
+    for (const item of items()) {
+      const element = item.details();
+      const shown = open.includes(item.value);
+      if (element && element.open !== shown) element.open = shown;
+    }
+  });
+
+  return (
+    <AccordionContext value={context}>
+      <lu-accordion
+        {...rest}
+        data-orientation={orientation === "horizontal" ? "horizontal" : undefined}
+        data-loop-focus={loopFocus === false ? "false" : undefined}
+      >
+        {children}
+      </lu-accordion>
+    </AccordionContext>
+  );
+}
+
+function Item({
+  value,
+  disabled,
+  onOpenChange,
+  children,
+  ref: forwarded,
+  ...rest
+}: AccordionItemProps) {
+  const accordion = useAccordion();
+  const id = useId();
+  // An item keeps the value it started with: it is its identity in the root's `value`.
+  const key = untrack(() => value) ?? id;
+  const details = ref<HTMLDetailsElement>();
+  const record: ItemRecord = { value: key, details };
+  accordion.items.update((list) => [...list, record]);
+  onCleanup(() => accordion.items.update((list) => list.filter((each) => each !== record)));
+  /** The state last reported: a `<details>` created open fires `toggle` too (TASK-441 M40). */
+  let shown = accordion.initiallyOpen(key);
+  const item: ItemContextValue = {
+    triggerId: `${id}-trigger`,
+    panelId: `${id}-panel`,
+    disabled: () => disabled === true || accordion.disabled(),
+  };
+  return (
+    <ItemContext value={item}>
+      <details
+        {...rest}
+        ref={(element: HTMLDetailsElement) => {
+          details(element);
+          forwarded?.(element);
+        }}
+        name={accordion.multiple ? undefined : accordion.id}
+        open={shown}
+        on:toggle={(event: ToggleEvent) => {
+          const now = event.newState === "open";
+          accordion.onToggle(key, now);
+          if (now === shown) return;
+          shown = now;
+          onOpenChange?.(now);
+        }}
+      >
+        {children}
+      </details>
+    </ItemContext>
+  );
+}
+
+function Header({ children, ...rest }: AccordionHeaderProps) {
+  return <HeaderContext value={rest}>{children}</HeaderContext>;
+}
+
+function Trigger({ children, ...rest }: AccordionTriggerProps) {
+  const item = useItem();
+  const header = useContext(HeaderContext);
+  // A caller's `id` names it; the parts after it point at that (TASK-441 M39).
+  if (rest.id) item.triggerId = rest.id;
+  return (
+    <summary
+      {...rest}
+      id={item.triggerId}
+      aria-controls={item.panelId}
+      aria-disabled={item.disabled() ? "true" : undefined}
+      tabindex={item.disabled() ? -1 : rest.tabindex}
+    >
+      {header ? <h3 {...header}>{children}</h3> : children}
+    </summary>
+  );
+}
+
+function Panel({ children, ...rest }: AccordionPanelProps) {
+  const item = useItem();
+  return (
+    <div role="region" {...rest} id={item.panelId} aria-labelledby={item.triggerId}>
+      {children}
+    </div>
+  );
+}
+
+/**
+ * Accordion: a stack of items whose triggers show and hide their panels, after the APG Accordion
+ * pattern. Items are native `<details>` (one open at a time by default, through the browser's
+ * exclusive group), so they work in server HTML with no JavaScript; `<lu-accordion>`'s script adds
+ * the arrow keys. Unstyled: style the parts through `class`, `[open]` on the items, and the
+ * panels' `--lu-accordion-panel-height`, `[data-starting-style]` and `[data-ending-style]`.
+ *
+ * @example
+ * <Accordion.Root defaultValue={["shipping"]}>
+ *   <Accordion.Item value="shipping">
+ *     <Accordion.Header>
+ *       <Accordion.Trigger>Shipping</Accordion.Trigger>
+ *     </Accordion.Header>
+ *     <Accordion.Panel>Orders ship in two days.</Accordion.Panel>
+ *   </Accordion.Item>
+ * </Accordion.Root>
+ */
+export const Accordion = { Root, Item, Header, Trigger, Panel };

package/dist/animation/animation.ts

@@ -0,0 +1,34 @@
+// Enter and exit animations of @lumiose/ui's parts (doc-9 §1): the starting style of an element's
+// first frame, and the end of its exit, whatever a stylesheet animates. Neither waits for a frame:
+// a page in the background renders none (`requestAnimationFrame` never runs), and a part must
+// still leave. Shared by the components and their client scripts, so it must not import
+// `lumiose`.
+
+/** Forces a style update: transitions start from what is computed now. */
+const flush = (element: Element) => getComputedStyle(element).getPropertyValue("opacity");
+
+/**
+ * Applies `attribute` (`data-starting-style`) for the element's first style, then removes it, so
+ * a transition runs from the starting style to the element's own.
+ */
+export function startFrom(element: Element, attribute = "data-starting-style"): void {
+  element.setAttribute(attribute, "");
+  flush(element);
+  element.removeAttribute(attribute);
+}
+
+/**
+ * Resolves once the element's animations and transitions end: after the longest one's remaining
+ * time, so a background page (whose animations do not advance) still gets there.
+ */
+export function afterAnimations(element: Element): Promise<void> {
+  flush(element);
+  let wait = 0;
+  for (const animation of element.getAnimations()) {
+    const timing = animation.effect?.getComputedTiming();
+    const end = Number(timing?.endTime ?? 0);
+    const current = Number(animation.currentTime ?? 0);
+    if (Number.isFinite(end)) wait = Math.max(wait, end - current);
+  }
+  return new Promise((resolve) => setTimeout(resolve, wait));
+}