@lumiose/ui 0.0.0-stage → 0.1.1

package/dist/tabs/tabs.script.ts

@@ -0,0 +1,225 @@
+// Tabs' client script (decision-62, decision-63): defines `<lu-tabs>`, the light-DOM element that
+// Tabs.Root renders, which upgrades the server HTML in place. The DOM is its only state: the tab
+// with `aria-selected="true"` is the selected one, its `value` attribute the value, and each tab
+// controls its panel (`aria-controls`). It follows the APG tabs pattern and Base UI (doc-9 §8):
+//
+// - Roving tabindex: the selected tab is the tab stop; arrow keys move focus along the
+//   orientation (`aria-orientation` on the tab list), swapped in right-to-left, Home and End go
+//   to the ends, and focus loops unless the list has `data-loop-focus="false"`.
+// - Activation: on click, Enter or Space (manual, Base UI's default), or on focus when the list
+//   has `data-activate-on-focus`. Only the main button activates. Disabled tabs
+//   (`aria-disabled="true"`) take focus but are never selected; a selected tab that is disabled
+//   gives its selection to the first enabled tab, and with every tab disabled none is selected.
+//   Once the element's content is parsed, the selected tab (else the first) is the only tab stop
+//   and the only selected tab, whatever the server HTML had (TASK-437 M17).
+// - `value` reads and sets the selection; a change by the user fires `valuechange` (not
+//   bubbling), so `bind:value` works on the element too.
+// - With a `[data-indicator]` in the list (Tabs.Indicator, TASK-395): the selected tab's box, from
+//   the list's padding edge, as `--lu-tabs-indicator-left`, `-top`, `-width` and `-height` on the
+//   element, kept current as the selection changes (by this script or by an island re-rendering
+//   `aria-selected`), as the list or a tab resizes, and as a `dir` attribute changes in the page. CSS anchor positioning (tabs.css) places the
+//   indicator before this script runs; the variables take over then, so a theme can transition
+//   them, and they place it where anchor positioning is missing.
+//
+// It must not import `lumiose`: server-rendered pages load it without the runtime.
+
+const enabled = (tab: HTMLElement) => tab.getAttribute("aria-disabled") !== "true";
+
+export class LuTabs extends HTMLElement {
+  /** The elements with an indicator, and one observer of `dir` for them all: it moves the tabs. */
+  static #measured = new Set<LuTabs>();
+  static #direction: MutationObserver | undefined;
+
+  #resize: ResizeObserver | undefined;
+  #mutation: MutationObserver | undefined;
+
+  /** Its own tab list: nested tabs belong to their own element. */
+  get list(): HTMLElement | null {
+    for (const list of this.querySelectorAll<HTMLElement>("[role=tablist]")) {
+      if (list.closest("lu-tabs") === this) return list;
+    }
+    return null;
+  }
+
+  get tabs(): HTMLElement[] {
+    const list = this.list;
+    return list
+      ? [...list.querySelectorAll<HTMLElement>("[role=tab]")].filter(
+          (tab) => tab.closest("lu-tabs") === this,
+        )
+      : [];
+  }
+
+  /** The selected tab's value, or `null` when none is selected. */
+  get value(): string | null {
+    return (
+      this.tabs
+        .find((tab) => tab.getAttribute("aria-selected") === "true")
+        ?.getAttribute("value") ?? null
+    );
+  }
+
+  set value(next: string | null) {
+    this.#select(this.tabs.find((tab) => tab.getAttribute("value") === next));
+  }
+
+  connectedCallback() {
+    this.addEventListener("keydown", this.#onKeyDown);
+    this.addEventListener("click", this.#onClick);
+    this.addEventListener("focusin", this.#onFocusIn);
+    // Server HTML may select a disabled tab or leave the tab stop elsewhere: fix it once the
+    // element's content is parsed.
+    if (document.readyState === "loading") {
+      document.addEventListener("DOMContentLoaded", () => this.#settle(), { once: true });
+    } else queueMicrotask(() => this.#settle());
+  }
+
+  disconnectedCallback() {
+    this.removeEventListener("keydown", this.#onKeyDown);
+    this.removeEventListener("click", this.#onClick);
+    this.removeEventListener("focusin", this.#onFocusIn);
+    this.#resize?.disconnect();
+    this.#mutation?.disconnect();
+    this.#resize = this.#mutation = undefined;
+    LuTabs.#measured.delete(this);
+    if (LuTabs.#measured.size === 0) {
+      LuTabs.#direction?.disconnect();
+      LuTabs.#direction = undefined;
+    }
+  }
+
+  #settle() {
+    const tabs = this.tabs;
+    const selected = tabs.find(
+      (tab) => tab.getAttribute("aria-selected") === "true" && enabled(tab),
+    );
+    this.#select(selected ?? tabs.find(enabled), true);
+    const list = this.list;
+    if (list && this.#indicator() && !this.#resize) {
+      // The tabs' sizes change with fonts, text and the viewport, and an island may select a tab
+      // or add one by rendering: the indicator follows.
+      const resize = new ResizeObserver(() => this.#measure());
+      const observe = () => {
+        resize.observe(list);
+        for (const tab of this.tabs) resize.observe(tab);
+      };
+      observe();
+      this.#resize = resize;
+      this.#mutation = new MutationObserver(() => {
+        observe();
+        this.#measure();
+      });
+      this.#mutation.observe(list, {
+        subtree: true,
+        childList: true,
+        attributeFilter: ["aria-selected"],
+      });
+      LuTabs.#measured.add(this);
+      if (!LuTabs.#direction) {
+        LuTabs.#direction = new MutationObserver(() => {
+          for (const each of LuTabs.#measured) each.#measure();
+        });
+        LuTabs.#direction.observe(document.documentElement, {
+          subtree: true,
+          attributeFilter: ["dir"],
+        });
+      }
+    }
+    this.#measure();
+  }
+
+  #indicator(): HTMLElement | null {
+    const indicator = this.list?.querySelector<HTMLElement>(":scope > [data-indicator]");
+    return indicator ?? null;
+  }
+
+  /** Writes the selected tab's box, from the list's padding edge, for the indicator. */
+  #measure() {
+    const list = this.list;
+    const indicator = this.#indicator();
+    if (!list || !indicator) return;
+    const tab = this.tabs.find((each) => each.getAttribute("aria-selected") === "true");
+    indicator.hidden = !tab;
+    if (!tab) return;
+    const outer = list.getBoundingClientRect();
+    const inner = tab.getBoundingClientRect();
+    const left = inner.left - outer.left - list.clientLeft + list.scrollLeft;
+    const top = inner.top - outer.top - list.clientTop + list.scrollTop;
+    this.style.setProperty("--lu-tabs-indicator-left", `${left}px`);
+    this.style.setProperty("--lu-tabs-indicator-top", `${top}px`);
+    this.style.setProperty("--lu-tabs-indicator-width", `${inner.width}px`);
+    this.style.setProperty("--lu-tabs-indicator-height", `${inner.height}px`);
+  }
+
+  /** Selects `tab` (nothing when it is missing or disabled), and reports a change if asked. */
+  #select(tab: HTMLElement | undefined, report = false) {
+    if (tab && !enabled(tab)) return;
+    const before = this.value;
+    const tabs = this.tabs;
+    for (const each of tabs) {
+      const on = each === tab;
+      each.setAttribute("aria-selected", String(on));
+      each.tabIndex = on || (!tab && each === tabs[0]) ? 0 : -1;
+      const panel = this.#panelOf(each);
+      if (panel) panel.hidden = !on;
+    }
+    this.#measure();
+    if (report && this.value !== before) this.dispatchEvent(new Event("valuechange"));
+  }
+
+  /**
+   * The panel `tab` controls: one of this element's own tab panels, never another element of the
+   * page that has the id (TASK-473, L13).
+   */
+  #panelOf(tab: HTMLElement): HTMLElement | undefined {
+    const id = tab.getAttribute("aria-controls");
+    if (!id) return undefined;
+    for (const panel of this.querySelectorAll<HTMLElement>("[role=tabpanel]")) {
+      if (panel.id === id && panel.closest("lu-tabs") === this) return panel;
+    }
+    return undefined;
+  }
+
+  /** The tab an event happened on, if it is one of this element's own tabs. */
+  #tabOf(event: Event): HTMLElement | undefined {
+    const tab = (event.target as Element).closest?.<HTMLElement>("[role=tab]");
+    return tab && tab.closest("lu-tabs") === this && this.tabs.includes(tab) ? tab : undefined;
+  }
+
+  #onClick = (event: MouseEvent) => {
+    const tab = this.#tabOf(event);
+    if (!tab || event.button !== 0) return;
+    this.#select(tab, true);
+  };
+
+  #onFocusIn = (event: FocusEvent) => {
+    const tab = this.#tabOf(event);
+    if (tab && this.list?.hasAttribute("data-activate-on-focus")) this.#select(tab, true);
+  };
+
+  #onKeyDown = (event: KeyboardEvent) => {
+    const tab = this.#tabOf(event);
+    if (!tab || event.isComposing || event.altKey || event.ctrlKey || event.metaKey) return;
+    const list = this.list!;
+    const vertical = list.getAttribute("aria-orientation") === "vertical";
+    const rtl = !vertical && getComputedStyle(list).direction === "rtl";
+    const keys: Record<string, number> = vertical
+      ? { ArrowDown: 1, ArrowUp: -1 }
+      : { ArrowRight: rtl ? -1 : 1, ArrowLeft: rtl ? 1 : -1 };
+    const tabs = this.tabs;
+    const at = tabs.indexOf(tab);
+    const step = keys[event.key];
+    let next: number;
+    if (event.key === "Home") next = 0;
+    else if (event.key === "End") next = tabs.length - 1;
+    else if (step !== undefined) {
+      next = at + step;
+      const loop = list.getAttribute("data-loop-focus") !== "false";
+      if (next < 0 || next >= tabs.length) next = loop ? (next + tabs.length) % tabs.length : at;
+    } else return;
+    event.preventDefault();
+    tabs[next]!.focus();
+  };
+}
+
+if (!customElements.get("lu-tabs")) customElements.define("lu-tabs", LuTabs);

package/dist/tabs/tabs.tsx

@@ -0,0 +1,272 @@
+// Tabs (decision-62, TASK-359): Root renders `<lu-tabs>`, a light-DOM element whose script
+// (tabs.script.ts) adds the keyboard and the selection to the server HTML, which already carries
+// the full APG state: roles, `aria-selected`, the roving `tabindex`, `aria-controls` and
+// `aria-labelledby`, and `hidden` on the other panels. The element's DOM is the state: the
+// component renders it, `value` drives it when it changes, and the element's `valuechange` event
+// reports back through `onValueChange`.
+import {
+  createContext,
+  effect,
+  isServer,
+  onCleanup,
+  ref,
+  signal,
+  untrack,
+  useContext,
+  useId,
+  type Signal,
+} from "lumiose";
+import { withStyle } from "../placement/placement.ts";
+import defineTabs from "./tabs.script.ts?client";
+import type { LuTabs } from "./tabs.script.ts";
+
+declare module "lumiose/jsx-runtime" {
+  namespace JSX {
+    interface IntrinsicElements {
+      /** Tabs.Root's element: `value` is the selected tab's, `valuechange` reports a change. */
+      "lu-tabs": JSX.HTMLProps<LuTabs> & {
+        /** The selected tab's value, `null` when none is; setting it selects that tab. */
+        value?: string | null;
+        /** Sets `value` from the signal; the element's `valuechange` writes it back. */
+        "bind:value"?: Signal<string | null>;
+      };
+    }
+  }
+}
+
+/**
+ * The element props Root passes to `<lu-tabs>` (`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<LuTabs> as K extends string ? K : never]: JSX.HTMLProps<LuTabs>[K];
+};
+
+/**
+ * `Tabs.Root` renders `<lu-tabs>`, with the element props it is given. `bind:value={signal}`
+ * stands in for `value` and `onValueChange`.
+ */
+export interface TabsRootProps extends Omit<ElementProps, "children"> {
+  /**
+   * Selects the tab with this value when it changes. Pair it with `onValueChange` to keep a signal
+   * in sync; leave both out and the tabs keep their own state.
+   */
+  value?: string;
+  /** The tab selected at first, when there is no `value`. Default: the first enabled tab. */
+  defaultValue?: string;
+  /** Called after the user selects another tab, with its value. */
+  onValueChange?: (value: string) => void;
+  /** The tab list's direction, for the arrow keys. Default `"horizontal"`. */
+  orientation?: "horizontal" | "vertical";
+  /** The other parts: the `Tabs.List` and the `Tabs.Panel`s. */
+  children?: JSX.Element;
+}
+
+/** The `<div role="tablist">` around the tabs. Name it with `aria-label` or `aria-labelledby`. */
+export type TabsListProps = JSX.IntrinsicElements["div"] & {
+  /** Selecting a tab when it receives focus (automatic activation). Default `false`: manual. */
+  activateOnFocus?: boolean;
+  /** The arrow keys go from the last tab to the first and back. Default `true`. */
+  loopFocus?: boolean;
+};
+
+/** A `<button role="tab">`, paired with the `Tabs.Panel` of the same `value`. */
+export type TabsTabProps = Omit<JSX.IntrinsicElements["button"], "value"> & {
+  /** Identifies the tab and its panel. */
+  value: string;
+  /** Takes focus but cannot be selected. */
+  disabled?: boolean;
+};
+
+/** A `<div role="tabpanel">`, shown while the tab of the same `value` is selected. */
+export type TabsPanelProps = JSX.IntrinsicElements["div"] & {
+  /** The value of the tab that shows the panel. */
+  value: string;
+};
+
+/**
+ * A `<span aria-hidden="true" data-indicator>` inside `Tabs.List` that covers the selected tab's
+ * box, placed from the server HTML on: style it as an underline or a highlight that slides from
+ * tab to tab.
+ */
+export type TabsIndicatorProps = Omit<JSX.IntrinsicElements["span"], "children">;
+
+interface TabRecord {
+  value: string;
+  disabled: () => boolean;
+}
+
+interface TabsContextValue {
+  /** The selected value: a disabled or missing tab gives its place to the first enabled one. */
+  current: () => string | undefined;
+  /** The value asked for (`value`, `defaultValue` or the user's choice), even a disabled tab's. */
+  wanted: () => string | undefined;
+  tabs: Signal<TabRecord[]>;
+  orientation: () => "horizontal" | "vertical";
+  tabId: (value: string) => string;
+  /** Records a Tab's own `id`: the Panel after it points at it. */
+  name: (value: string, id: string) => void;
+  panelId: (value: string) => string;
+}
+
+const TabsContext = createContext<TabsContextValue>();
+
+function useTabs(): TabsContextValue {
+  const context = useContext(TabsContext);
+  if (!context) throw new Error("Tabs parts must be inside <Tabs.Root>.");
+  return context;
+}
+
+/** An id fragment for a value: ids may not hold spaces. */
+const fragment = (value: string) => encodeURIComponent(value).replaceAll("%", "_");
+
+function Root({
+  value,
+  defaultValue,
+  onValueChange,
+  orientation,
+  children,
+  ...rest
+}: TabsRootProps) {
+  // Keyboard and selection on the server HTML; the page loads it once (decision-63).
+  defineTabs();
+  const id = useId();
+  const element = ref<LuTabs>();
+  const selected = signal<string | undefined>(untrack(() => value ?? defaultValue));
+  const tabs = signal<TabRecord[]>([]);
+  const named = new Map<string, string>();
+  const context: TabsContextValue = {
+    current: () => {
+      const wanted = selected();
+      const list = tabs();
+      const tab = list.find((each) => each.value === wanted);
+      // A value whose tab has not rendered yet (on the server, a later tab) stays selected.
+      if (wanted !== undefined && (!tab || !tab.disabled())) return wanted;
+      return list.find((each) => !each.disabled())?.value;
+    },
+    wanted: selected,
+    tabs,
+    orientation: () => orientation ?? "horizontal",
+    // A Tab's own `id`, else one made from its value (TASK-441 M39).
+    tabId: (of) => named.get(of) ?? `${id}-tab-${fragment(of)}`,
+    name: (of, tabId) => named.set(of, tabId),
+    panelId: (of) => `${id}-panel-${fragment(of)}`,
+  };
+
+  // The `value` prop drives the selection when it changes.
+  effect(() => {
+    const next = value;
+    if (next !== undefined) selected.set(next);
+  });
+
+  return (
+    <TabsContext value={context}>
+      <lu-tabs
+        {...rest}
+        ref={element}
+        // The anchor the selected tab carries for a Tabs.Indicator (tabs.css).
+        style={withStyle(rest.style, { "--lu-tabs-anchor": `--lu-tabs-${id}` })}
+        on:valuechange={() => {
+          const next = element()?.value;
+          if (next == null) return;
+          selected.set(next);
+          onValueChange?.(next);
+        }}
+      >
+        {children}
+      </lu-tabs>
+    </TabsContext>
+  );
+}
+
+function List({ children, activateOnFocus, loopFocus, ...rest }: TabsListProps) {
+  const tabs = useTabs();
+  return (
+    <div
+      role="tablist"
+      aria-orientation={tabs.orientation() === "vertical" ? "vertical" : undefined}
+      data-activate-on-focus={activateOnFocus ? "" : undefined}
+      data-loop-focus={loopFocus === false ? "false" : undefined}
+      {...rest}
+    >
+      {children}
+    </div>
+  );
+}
+
+function Tab({ children, value, disabled, ...rest }: TabsTabProps) {
+  const tabs = useTabs();
+  // A caller's `id` names it; its Panel, after it, points at that (TASK-441 M39).
+  if (rest.id) tabs.name(value, rest.id);
+  const record: TabRecord = { value, disabled: () => disabled === true };
+  tabs.tabs.update((list) => [...list, record]);
+  onCleanup(() => tabs.tabs.update((list) => list.filter((each) => each !== record)));
+  const selected = () => tabs.current() === value;
+  // The tab stop: the selected tab, or the first one when none is selected. The server renders
+  // once, before the later tabs exist, so there it is the tab asked for (a disabled one stays
+  // focusable), else the first enabled one so far: one tab stop either way (TASK-437 M17). The
+  // script gives it to the selected tab.
+  const stop = () => {
+    if (isServer) {
+      const wanted = tabs.wanted();
+      return wanted === undefined ? selected() : wanted === value;
+    }
+    return selected() || (tabs.current() === undefined && tabs.tabs()[0] === record);
+  };
+  return (
+    <button
+      type="button"
+      {...rest}
+      role="tab"
+      id={tabs.tabId(value)}
+      value={value}
+      aria-controls={tabs.panelId(value)}
+      aria-selected={selected() ? "true" : "false"}
+      aria-disabled={disabled ? "true" : undefined}
+      tabindex={stop() ? 0 : -1}
+    >
+      {children}
+    </button>
+  );
+}
+
+function Indicator(props: TabsIndicatorProps) {
+  const tabs = useTabs();
+  return (
+    <span {...props} aria-hidden="true" data-indicator="" hidden={tabs.current() === undefined} />
+  );
+}
+
+function Panel({ children, value, ...rest }: TabsPanelProps) {
+  const tabs = useTabs();
+  return (
+    <div
+      tabindex={0}
+      {...rest}
+      role="tabpanel"
+      id={tabs.panelId(value)}
+      aria-labelledby={tabs.tabId(value)}
+      hidden={tabs.current() !== value}
+    >
+      {children}
+    </div>
+  );
+}
+
+/**
+ * Tabs: a tab list and the panel of the selected tab, after the APG tabs pattern. The server HTML
+ * holds the whole state; `<lu-tabs>`'s small script adds the arrow keys and the selection.
+ * Unstyled: style the parts through `class`, `[aria-selected]`, `[aria-disabled]` and
+ * `[aria-orientation]`. An optional `Tabs.Indicator` in the list follows the selected tab.
+ *
+ * @example
+ * <Tabs.Root defaultValue="account">
+ *   <Tabs.List aria-label="Settings">
+ *     <Tabs.Tab value="account">Account</Tabs.Tab>
+ *     <Tabs.Tab value="password">Password</Tabs.Tab>
+ *   </Tabs.List>
+ *   <Tabs.Panel value="account">…</Tabs.Panel>
+ *   <Tabs.Panel value="password">…</Tabs.Panel>
+ * </Tabs.Root>
+ */
+export const Tabs = { Root, List, Tab, Indicator, Panel };