@lumiose/ui 0.0.0-stage → 0.1.0

package/dist/menubar/menubar.script.ts

@@ -0,0 +1,195 @@
+// Menubar's client script (decision-62, decision-63). `<lu-menubar role="menubar">` holds Menus,
+// whose `lu-menu` elements (../menu/menu.script.ts) run each menu; it adds the WAI-ARIA menubar
+// pattern's bar behaviour, after Base UI's Menubar:
+//
+// - One tab stop: the item focused last (the first at first) keeps `tabindex="0"`, the others get
+//   `-1`. Without this script every trigger stays a tab stop. When the tab stop is removed,
+//   disabled or hidden, the first item takes it (TASK-437 M11).
+// - On an item: Arrow Right and Left (Down and Up when vertical; swapped right to left) move
+//   between the items, looping unless `data-loop-focus="false"`; Home and End; a letter moves to the
+//   next item starting with it. A menu that is open follows: moving opens the next item's menu.
+// - In an open menu: Arrow Right and Left on an item that opens no submenu (Menu's script handles
+//   the ones that do) close it and open the next or previous item's menu on its first item; in a
+//   vertical bar, the arrow pointing back closes the menu and returns to its item.
+// - Pointer: once a menu is open, hovering another item opens its menu instead.
+// - `data-has-submenu-open` on the bar while one of its menus is open.
+// It must not import `lumiose`: server-rendered pages load it without the runtime.
+
+import type { MenuElement } from "../menu/menu.script.ts";
+
+const enabled = (item: Element) =>
+  item.getAttribute("aria-disabled") !== "true" && !item.matches(":disabled");
+
+export class MenubarElement extends HTMLElement {
+  /** The tab stop, kept while it stays an item. */
+  #stop: HTMLElement | undefined;
+  /** Moves the tab stop on when items come, go, or are disabled or hidden. */
+  #observer = new MutationObserver(() => this.#rove(undefined));
+
+  connectedCallback(): void {
+    this.addEventListener("keydown", this);
+    this.addEventListener("pointerover", this);
+    this.addEventListener("focusin", this);
+    // `openchange` does not bubble: the capture phase sees each menu's.
+    this.addEventListener("openchange", this, true);
+    this.#observer.observe(this, {
+      subtree: true,
+      childList: true,
+      attributeFilter: ["disabled", "hidden"],
+    });
+    // The element may connect while the page is still parsing, before its items: it makes the bar
+    // one tab stop once the document has loaded (or after the current task, in an island).
+    if (document.readyState === "loading") {
+      document.addEventListener("DOMContentLoaded", () => this.#start(), { once: true });
+    } else {
+      queueMicrotask(() => this.#start());
+    }
+  }
+
+  #start(): void {
+    if (!this.isConnected) return;
+    const items = this.#items();
+    this.#rove(items.find((item) => item.tabIndex === 0) ?? items[0]);
+  }
+
+  disconnectedCallback(): void {
+    this.removeEventListener("keydown", this);
+    this.removeEventListener("pointerover", this);
+    this.removeEventListener("focusin", this);
+    this.removeEventListener("openchange", this, true);
+    this.#observer.disconnect();
+  }
+
+  handleEvent(event: Event): void {
+    switch (event.type) {
+      case "keydown":
+        return this.#onKeyDown(event as KeyboardEvent);
+      case "pointerover":
+        return this.#onPointerOver(event as PointerEvent);
+      case "focusin": {
+        const item = event.target as HTMLElement;
+        if (this.#items().includes(item)) this.#rove(item);
+        return;
+      }
+      default:
+        this.toggleAttribute("data-has-submenu-open", this.#openMenu() !== undefined);
+    }
+  }
+
+  /** The bar's items: its menus' triggers, in order, without natively disabled or hidden ones. */
+  #items(): HTMLElement[] {
+    return [...this.querySelectorAll<HTMLElement>("[role=menuitem]")].filter(
+      (item) =>
+        item.closest("lu-menubar") === this &&
+        item.closest("[role=menu]") === null &&
+        !item.matches(":disabled") &&
+        (item.checkVisibility?.() ?? true),
+    );
+  }
+
+  #menuOf(item: HTMLElement): MenuElement | null {
+    return item.closest<MenuElement>("lu-menu");
+  }
+
+  /** The bar's open menu, if any. */
+  #openMenu(): MenuElement | undefined {
+    for (const item of this.#items()) {
+      const menu = this.#menuOf(item);
+      if (menu?.open) return menu;
+    }
+    return undefined;
+  }
+
+  /** Makes `item` the bar's one tab stop; without one, keeps the current one, else the first. */
+  #rove(item: HTMLElement | undefined): void {
+    const items = this.#items();
+    const kept = this.#stop && items.includes(this.#stop) ? this.#stop : undefined;
+    const stop = item ?? kept ?? items[0];
+    if (!stop) return;
+    this.#stop = stop;
+    for (const other of items) other.tabIndex = other === stop ? 0 : -1;
+  }
+
+  /** The item `step` places from `from` (wrapping unless the bar does not loop). */
+  #step(items: HTMLElement[], from: number, step: number): HTMLElement | undefined {
+    const next = from + step;
+    if (this.dataset.loopFocus === "false") return items[next];
+    return items[(next + items.length) % items.length];
+  }
+
+  /** Moves to `item`; with `open`, opens its menu on its first item (closing the open one). */
+  #go(item: HTMLElement | undefined, open: boolean): void {
+    if (!item) return;
+    const current = this.#openMenu();
+    if (current && current !== this.#menuOf(item)) current.open = false;
+    this.#rove(item);
+    item.focus();
+    const menu = this.#menuOf(item);
+    if (open && menu && enabled(item) && !menu.open) menu.show(true);
+  }
+
+  #onKeyDown(event: KeyboardEvent): void {
+    if (event.isComposing || event.defaultPrevented || event.ctrlKey || event.metaKey) return;
+    const target = event.target as HTMLElement;
+    const items = this.#items();
+    const vertical = this.getAttribute("aria-orientation") === "vertical";
+    const rtl = this.matches(":dir(rtl)");
+    const [next, previous] = vertical
+      ? ["ArrowDown", "ArrowUp"]
+      : rtl
+        ? ["ArrowLeft", "ArrowRight"]
+        : ["ArrowRight", "ArrowLeft"];
+    const index = items.indexOf(target);
+    if (index >= 0) {
+      // On an item of the bar.
+      const open = this.#openMenu() !== undefined;
+      let to: HTMLElement | undefined;
+      if (event.key === next) to = this.#step(items, index, 1);
+      else if (event.key === previous) to = this.#step(items, index, -1);
+      else if (event.key === "Home") to = items[0];
+      else if (event.key === "End") to = items.at(-1);
+      else if (event.key.length === 1 && event.key !== " " && !event.altKey) {
+        const key = event.key.toLowerCase();
+        const ordered = [...items.slice(index + 1), ...items.slice(0, index + 1)];
+        to = ordered.find((item) => item.textContent?.trim().toLowerCase().startsWith(key));
+      } else return;
+      event.preventDefault();
+      this.#go(to, open);
+      return;
+    }
+    // In one of the bar's open menus, on an item that opens no submenu.
+    const menu = this.#openMenu();
+    const trigger = menu ? items.find((item) => this.#menuOf(item) === menu) : undefined;
+    if (!menu || !trigger || !target.closest("[role=menu]")) return;
+    const back = rtl ? "ArrowRight" : "ArrowLeft";
+    if (vertical) {
+      if (event.key !== back) return;
+      event.preventDefault();
+      menu.open = false;
+      trigger.focus();
+      return;
+    }
+    if (event.key !== next && event.key !== previous) return;
+    const to = this.#step(items, items.indexOf(trigger), event.key === next ? 1 : -1);
+    if (!to) return;
+    event.preventDefault();
+    this.#go(to, true);
+  }
+
+  /** Once a menu is open, hovering another item of the bar opens its menu instead. */
+  #onPointerOver(event: PointerEvent): void {
+    if (event.pointerType === "touch") return;
+    const item = (event.target as Element).closest?.<HTMLElement>("[role=menuitem]");
+    if (!item || !this.#items().includes(item) || !enabled(item)) return;
+    const current = this.#openMenu();
+    const menu = this.#menuOf(item);
+    if (!current || !menu || current === menu) return;
+    current.open = false;
+    this.#rove(item);
+    menu.show(false);
+  }
+}
+
+if (!customElements.get("lu-menubar")) {
+  customElements.define("lu-menubar", MenubarElement);
+}

package/dist/menubar/menubar.tsx

@@ -0,0 +1,67 @@
+// Menubar (decision-62, TASK-379): a row of Menus, after Base UI's Menubar and the WAI-ARIA
+// menubar pattern. It renders `<lu-menubar role="menubar">` (./menubar.script.ts) around
+// `Menu.Root`s: inside it, each top-level `<lu-menu>` is `role="none"` and its `Menu.Trigger` a
+// `role="menuitem"`, so the bar's items are the triggers, as in the APG example. Menu's script runs
+// each menu (keys, items, submenus, dismissal); the menubar's adds one tab stop for the bar, the
+// arrow keys between its items and between open menus, and hover switching once a menu is open.
+// Without JavaScript every trigger is a tab stop that opens its popover.
+import { MenubarContext } from "../menu/menu.tsx";
+import menubarScript from "./menubar.script.ts?client";
+import type { MenubarElement } from "./menubar.script.ts";
+
+declare module "lumiose/jsx-runtime" {
+  namespace JSX {
+    interface IntrinsicElements {
+      /** Menubar's element: a `role="menubar"` that moves focus between its menus' triggers. */
+      "lu-menubar": JSX.HTMLProps<MenubarElement>;
+    }
+  }
+}
+
+/** Which way a menubar's items run. */
+export type MenubarOrientation = "horizontal" | "vertical";
+
+/** `Menubar` renders `<lu-menubar role="menubar">` around `Menu.Root`s. */
+export type MenubarProps = JSX.IntrinsicElements["lu-menubar"] & {
+  /**
+   * Which way the items run: `"vertical"` stacks them, moves between them with Arrow Up and Down,
+   * opens a menu with the arrow that points at its popup, and places popups at the inline end.
+   * Default `"horizontal"`.
+   */
+  orientation?: MenubarOrientation;
+  /** Whether the arrow keys wrap from the last item to the first and back. Default `true`. */
+  loopFocus?: boolean;
+};
+
+/**
+ * A bar of menus, such as an app's File, Edit and View: put `Menu.Root`s inside, each with its
+ * `Menu.Trigger` and `Menu.Popup`. Give it an `aria-label`.
+ *
+ * @example
+ * <Menubar aria-label="Editor">
+ *   <Menu.Root>
+ *     <Menu.Trigger>File</Menu.Trigger>
+ *     <Menu.Popup>
+ *       <Menu.Item>New</Menu.Item>
+ *     </Menu.Popup>
+ *   </Menu.Root>
+ * </Menubar>
+ */
+export function Menubar({ orientation, loopFocus, children, ...rest }: MenubarProps) {
+  // The bar's keys and hover switching; the page loads it once (decision-63).
+  menubarScript();
+  const vertical = () => orientation === "vertical";
+  return (
+    <MenubarContext value={{ orientation: vertical() ? "vertical" : "horizontal" }}>
+      <lu-menubar
+        {...rest}
+        role="menubar"
+        aria-orientation={vertical() ? "vertical" : "horizontal"}
+        data-orientation={vertical() ? "vertical" : "horizontal"}
+        data-loop-focus={loopFocus === false ? "false" : undefined}
+      >
+        {children}
+      </lu-menubar>
+    </MenubarContext>
+  );
+}

package/dist/meter/meter.tsx

@@ -0,0 +1,134 @@
+// Meter (decision-62, TASK-373): a native `<meter>`, after Base UI's Meter: a measurement within a
+// known range (disk usage, a password's strength), not a task's progress. The element carries the
+// role, the range and `aria-valuetext` with the formatted value; its native `low`, `high` and
+// `optimum` pass through. The Root around it holds the label and the value text, and sets
+// `--lu-value`. No script.
+import { createContext, useContext, useId } from "lumiose";
+import { withStyle } from "../placement/placement.ts";
+import { formatValue, percent } from "../progress/value.ts";
+
+interface MeterContextValue {
+  id: string;
+  value: () => number;
+  min: () => number;
+  max: () => number;
+  text: () => string;
+  valueText: () => string;
+}
+
+const MeterContext = createContext<MeterContextValue>();
+
+/** `Meter.Root` renders a `<div>` around the parts, with `--lu-value` (0% to 100%). */
+export type MeterRootProps = JSX.HTMLProps<HTMLElement> & {
+  /** The measured value, from `min` to `max`. */
+  value: number;
+  /** The bottom of the range. Default `0`. */
+  min?: number;
+  /** The top of the range. Default `100`. */
+  max?: number;
+  /** How the value is written: `Intl.NumberFormat` options. Default: a percentage of the range. */
+  format?: Intl.NumberFormatOptions;
+  /** The locale of the formatted value. Default: the browser's (the server's in server HTML). */
+  locale?: Intl.LocalesArgument;
+  /** The text assistive technology reads for the value. Default: the formatted value. */
+  getAriaValueText?: (formattedValue: string, value: number) => string;
+};
+
+/** The `<label>` of the meter. */
+export type MeterLabelProps = JSX.IntrinsicElements["label"];
+
+/**
+ * The meter: a native `<meter>` with the Root's value and range, plus the native `low`, `high`
+ * and `optimum`. Styled with `appearance: none` and its `::-webkit-meter-*` and `::-moz-meter-bar`
+ * pseudo-elements, or `--lu-value`.
+ */
+export type MeterTrackProps = Omit<JSX.IntrinsicElements["meter"], "value" | "min" | "max">;
+
+/** A `<span>` with the formatted value. */
+export type MeterValueProps = Omit<JSX.IntrinsicElements["span"], "children"> & {
+  /** Renders the value your way, from the formatted value and the number. */
+  children?: (formattedValue: string, value: number) => JSX.Element;
+};
+
+function useMeter(part: string): MeterContextValue {
+  const context = useContext(MeterContext);
+  if (!context) throw new Error(`Meter.${part} must be inside <Meter.Root>.`);
+  return context;
+}
+
+function Root({
+  value,
+  min,
+  max,
+  format,
+  locale,
+  getAriaValueText,
+  children,
+  style,
+  ...rest
+}: MeterRootProps) {
+  const id = useId();
+  const low = () => min ?? 0;
+  const high = () => max ?? 100;
+  const text = () => formatValue(value, low(), high(), format, locale);
+  const context: MeterContextValue = {
+    id,
+    value: () => value,
+    min: low,
+    max: high,
+    text,
+    valueText: () => (getAriaValueText ? getAriaValueText(text(), value) : text()),
+  };
+  return (
+    <MeterContext value={context}>
+      <div
+        {...rest}
+        style={withStyle(style, { "--lu-value": `${percent(value, low(), high())}%` })}
+      >
+        {children}
+      </div>
+    </MeterContext>
+  );
+}
+
+function Label({ children, ...rest }: MeterLabelProps) {
+  const meter = useMeter("Label");
+  return (
+    // Nothing points at the label: a caller's `id` names it (TASK-441 M39).
+    <label {...rest} id={rest.id ?? `${meter.id}-label`} for={`${meter.id}-track`}>
+      {children}
+    </label>
+  );
+}
+
+function Track(props: MeterTrackProps) {
+  const meter = useMeter("Track");
+  return (
+    <meter
+      {...props}
+      id={`${meter.id}-track`}
+      value={meter.value()}
+      min={meter.min()}
+      max={meter.max()}
+      aria-valuetext={meter.valueText()}
+    />
+  );
+}
+
+function Value({ children, ...rest }: MeterValueProps) {
+  const meter = useMeter("Value");
+  return <span {...rest}>{children ? children(meter.text(), meter.value()) : meter.text()}</span>;
+}
+
+/**
+ * A measurement within a range, as a native `<meter>`, with a label and the value as text.
+ * Unstyled: style it through `class`, the meter's pseudo-elements and `--lu-value`.
+ *
+ * @example
+ * <Meter.Root value={72}>
+ *   <Meter.Label>Storage used</Meter.Label>
+ *   <Meter.Value />
+ *   <Meter.Track />
+ * </Meter.Root>
+ */
+export const Meter = { Root, Label, Track, Value };

package/dist/navigation-menu/navigation-menu.css

@@ -0,0 +1,14 @@
+/*
+ * The CSS Navigation Menu needs to work, and nothing else (decision-62): `<lu-navigation-menu>`
+ * adds no box around its `<nav>`, and each content is placed next to its trigger by the shared
+ * placement rules (`data-side`, `data-align`, offsets, flips), which Popover and Menu use too. It
+ * sits in the `lu.core` layer, so any app CSS wins.
+ */
+@layer lu.core, lu.theme;
+@import "../placement/placement.css";
+
+@layer lu.core {
+  lu-navigation-menu {
+    display: contents;
+  }
+}