@lumiose/ui 0.0.0-stage → 0.1.0

package/dist/autocomplete/autocomplete.tsx

@@ -0,0 +1,239 @@
+// Autocomplete (decision-62, TASK-377): a text input with suggestions, after Base UI's Autocomplete
+// and the APG combobox with list autocomplete. The text is the value: the input has the name and
+// submits what is typed, and choosing a suggestion only fills it in. It is a Combobox in free mode:
+// Root renders the same `<lu-combobox>` with `free` (combobox.script.ts), and the other parts are
+// Combobox's, reading this Root's context. The `value` prop drives the input's text when it
+// changes; the input's `input` events report back through `onValueChange`.
+import { effect, ref, signal, untrack, useId } from "lumiose";
+import {
+  Combobox,
+  type ComboboxClearProps,
+  type ComboboxEmptyProps,
+  type ComboboxGroupLabelProps,
+  type ComboboxGroupProps,
+  type ComboboxInputProps,
+  type ComboboxItemProps,
+  type ComboboxLabelProps,
+  type ComboboxListProps,
+  type ComboboxPopupProps,
+  type ComboboxStatusProps,
+  type ComboboxTriggerProps,
+} from "../combobox/combobox.tsx";
+import type { ComboboxElement, ComboboxOpenChangeDetail } from "../combobox/combobox.script.ts";
+import comboboxScript from "../combobox/combobox.script.ts?client";
+import { ComboboxContext, type ComboboxContextValue } from "../combobox/context.ts";
+import { controlId, useField, useFormValues } from "../field/context.ts";
+import { onFormReset } from "../form/reset.ts";
+
+/**
+ * How the suggestions complete the text, as in Base UI: `"list"` filters them by the text,
+ * `"both"` also shows the highlighted one in the input, `"inline"` only does that (no filtering),
+ * `"none"` does neither (the page filters them, as with results from a server).
+ */
+export type AutocompleteMode = "list" | "both" | "inline" | "none";
+
+/**
+ * The element props Root passes to `<lu-combobox>`, without the brand of intrinsic elements' props,
+ * so that `bind:value` and `bind:open` apply to Root.
+ */
+type ElementProps = {
+  [
+    K in keyof JSX.HTMLProps<ComboboxElement> as K extends string ? K : never
+  ]: JSX.HTMLProps<ComboboxElement>[K];
+};
+
+/**
+ * `Autocomplete.Root` renders `<lu-combobox free>` around the other parts. `bind:value={signal}`
+ * stands in for `value` and `onValueChange`, `bind:open` for `open` and `onOpenChange`.
+ */
+export interface AutocompleteRootProps extends Omit<
+  ElementProps,
+  "children" | "onChange" | "onInput"
+> {
+  /** Puts this text in the input when it changes. Pair it with `onValueChange`. */
+  value?: string;
+  /** The text at first, when `value` is left out; a form reset goes back to it. */
+  defaultValue?: string;
+  /** Called as the text changes: typing, choosing a suggestion, clearing. */
+  onValueChange?: (value: string) => void;
+  /** Opens (`true`) or closes (`false`) the suggestions when it changes, in the browser. */
+  open?: boolean;
+  /** Called after the suggestions open or close, whatever opened or closed them. */
+  onOpenChange?: (open: boolean) => void;
+  /** How the suggestions complete the text. Default `"list"`. */
+  mode?: AutocompleteMode;
+  /**
+   * How `"list"` and `"both"` filter the suggestions by their text: `"contains"` (default) or
+   * `"startsWith"`, ignoring case and accents.
+   */
+  filter?: "contains" | "startsWith";
+  /** A click on the input opens the suggestions too; otherwise typing and Arrow Down do. */
+  openOnInputClick?: boolean;
+  /** The first suggestion is highlighted as you type, so Enter chooses it. */
+  autoHighlight?: boolean;
+  /** A suggestion the pointer highlighted stays highlighted when the pointer leaves the list. */
+  keepHighlight?: boolean;
+  /** A click on a suggestion submits the form, as a search box does. */
+  submitOnItemClick?: boolean;
+  /** Shows at most this many suggestions; a narrower text shows the others. */
+  limit?: number;
+  /** The name the text is submitted under (the input's). */
+  name?: string;
+  /** The form needs a text. */
+  required?: boolean;
+  /** The autocomplete cannot be used. */
+  disabled?: boolean;
+  /** The other parts: `Label`, `Input`, the buttons, and the `List` or `Popup`. */
+  children?: JSX.Element;
+}
+
+/** The `<label>` of the input. */
+export type AutocompleteLabelProps = ComboboxLabelProps;
+/** The `<input role="combobox">`: it has the name and submits the text. */
+export type AutocompleteInputProps = ComboboxInputProps;
+/** A `<button>` that opens and closes the suggestions, out of the tab order. */
+export type AutocompleteTriggerProps = ComboboxTriggerProps;
+/** A `<button>` that empties the text, out of the tab order and hidden while it is empty. */
+export type AutocompleteClearProps = ComboboxClearProps;
+/** A `<div popover>` around the `List`, for an empty state or a status beside the suggestions. */
+export type AutocompletePopupProps = ComboboxPopupProps;
+/** The `<div role="listbox">` of suggestions: the popup itself, unless it is inside a `Popup`. */
+export type AutocompleteListProps = ComboboxListProps;
+/** A suggestion, a `<div role="option">`: its `value` is the text it puts in the input. */
+export type AutocompleteItemProps = ComboboxItemProps;
+/** A `<div role="group">` of suggestions, named by its `GroupLabel`. */
+export type AutocompleteGroupProps = ComboboxGroupProps;
+/** A `<div role="presentation">` that names its group. */
+export type AutocompleteGroupLabelProps = ComboboxGroupLabelProps;
+/** A `<div role="status">` shown when no suggestion matches. */
+export type AutocompleteEmptyProps = ComboboxEmptyProps;
+/** A `<div role="status">` for a loading or result-count message. */
+export type AutocompleteStatusProps = ComboboxStatusProps;
+
+function Root({
+  value,
+  defaultValue,
+  onValueChange,
+  open,
+  onOpenChange,
+  mode,
+  filter,
+  openOnInputClick,
+  autoHighlight,
+  keepHighlight,
+  submitOnItemClick,
+  limit,
+  name,
+  required,
+  disabled,
+  children,
+  ...rest
+}: AutocompleteRootProps) {
+  // The behaviour, on the server HTML and in islands; the page loads it once (decision-63).
+  comboboxScript();
+  const id = useId();
+  const field = useField();
+  const host = ref<ComboboxElement>();
+  const completion = untrack(() => mode ?? "list");
+  const sent = useFormValues(
+    untrack(() => name ?? field?.name()),
+    untrack(() => disabled),
+  );
+  const context: ComboboxContextValue = {
+    id,
+    inputId: field ? controlId(field) : `${id}-input`,
+    selected: () => [],
+    multiple: () => false,
+    disabled: () => disabled === true || field?.disabled() === true,
+    labels: signal(0),
+    popup: false,
+    text: {
+      name: () => name ?? field?.name(),
+      required: () => required,
+      // A failed submission's text (a Form's `values`) replaces the default (TASK-430).
+      initial: untrack(() => value ?? sent?.[0] ?? defaultValue),
+      autocomplete: completion,
+    },
+  };
+
+  // The props drive the input and the popup when they change; the events report back.
+  effect(() => {
+    const next = value;
+    const input = host()?.input;
+    if (next !== undefined && input && input.value !== next) input.value = next;
+  });
+  effect(() => {
+    const element = host();
+    const wanted = open;
+    if (element?.isConnected && wanted !== undefined) element.open = wanted;
+  });
+
+  // A form reset puts the input's text back without an `input` event: it goes to
+  // `onValueChange` (TASK-435).
+  if (onValueChange) {
+    onFormReset(
+      () => host()?.input ?? undefined,
+      () => host()?.input?.value ?? "",
+      onValueChange,
+    );
+  }
+
+  return (
+    <ComboboxContext value={context}>
+      <lu-combobox
+        {...rest}
+        ref={host}
+        id={id}
+        free
+        inline={completion === "both" || completion === "inline"}
+        filter={completion === "inline" || completion === "none" ? "none" : filter}
+        open-on-input-click={openOnInputClick}
+        auto-highlight={autoHighlight}
+        keep-highlight={keepHighlight}
+        submit-on-item-click={submitOnItemClick}
+        limit={limit}
+        disabled={context.disabled()}
+        on:input={(event: Event) => {
+          const input = host()?.input;
+          if (input && event.target === input) onValueChange?.(input.value);
+        }}
+        on:openchange={(event: CustomEvent<ComboboxOpenChangeDetail>) =>
+          onOpenChange?.(event.detail.open)
+        }
+      >
+        {children}
+      </lu-combobox>
+    </ComboboxContext>
+  );
+}
+
+/**
+ * A text input with suggestions, for text that may be anything (a search, a tag, an address):
+ * the APG combobox with list autocomplete, after Base UI's Autocomplete. Unlike a Combobox, the
+ * text is the value and no suggestion has to be chosen; the input submits it. `<lu-combobox>`'s
+ * script runs it, on server-rendered pages too. Unstyled: style the parts through `class` and
+ * `[aria-expanded]`, `:popover-open`, `[aria-disabled]`, `[data-highlighted]`.
+ *
+ * @example
+ * <Autocomplete.Root name="search" bind:value={query}>
+ *   <Autocomplete.Label>Search</Autocomplete.Label>
+ *   <Autocomplete.Input />
+ *   <Autocomplete.List>
+ *     <Autocomplete.Item value="lumiose">lumiose</Autocomplete.Item>
+ *   </Autocomplete.List>
+ * </Autocomplete.Root>
+ */
+export const Autocomplete = {
+  Root,
+  Label: Combobox.Label,
+  Input: Combobox.Input,
+  Trigger: Combobox.Trigger,
+  Clear: Combobox.Clear,
+  Popup: Combobox.Popup,
+  List: Combobox.List,
+  Item: Combobox.Item,
+  Group: Combobox.Group,
+  GroupLabel: Combobox.GroupLabel,
+  Empty: Combobox.Empty,
+  Status: Combobox.Status,
+};

package/dist/avatar/avatar.css

@@ -0,0 +1,54 @@
+/*
+ * Avatar: `<lu-avatar>` stacks its image over its fallback in one grid cell, so showing one never
+ * moves the other. Where scripting is enabled the image stays hidden while it loads (server HTML
+ * marks it `data-loading`) and after it fails, and the fallback hides once it has loaded; without
+ * JavaScript an avatar with an image shows the image alone. `visibility`, not `display`, so a
+ * `loading="lazy"` image still loads. The fallback's `delay` is a zero-length animation that keeps
+ * it hidden that long.
+ */
+@layer lu.core, lu.theme;
+
+@layer lu.core {
+  lu-avatar {
+    display: inline-grid;
+    /* One cell, never wider or taller than the root: a broken or loading image's alt text would
+       widen it otherwise. */
+    grid-template: minmax(0, 1fr) / minmax(0, 1fr);
+  }
+  lu-avatar > * {
+    grid-area: 1 / 1;
+  }
+  lu-avatar > img {
+    z-index: 1;
+  }
+  lu-avatar > img[data-error] {
+    visibility: hidden;
+  }
+  @media (scripting: enabled) {
+    lu-avatar > img[data-loading] {
+      visibility: hidden;
+    }
+  }
+  lu-avatar[data-loaded] > [data-fallback] {
+    visibility: hidden;
+  }
+  /*
+   * Without JavaScript nothing tells a failed image from a loaded one: the image is the avatar,
+   * and the fallback behind it stays out of sight and out of the accessibility tree, which would
+   * name the avatar twice (TASK-445 L8).
+   */
+  @media (scripting: none) {
+    lu-avatar:has(> img) > [data-fallback] {
+      visibility: hidden;
+    }
+  }
+  lu-avatar > [data-fallback] {
+    animation: lu-avatar-delay 0s var(--lu-avatar-delay, 0s) backwards;
+  }
+}
+
+@keyframes lu-avatar-delay {
+  from {
+    visibility: hidden;
+  }
+}

package/dist/avatar/avatar.script.ts

@@ -0,0 +1,96 @@
+// Avatar's client script (decision-62, decision-63). `<lu-avatar>` follows the loading status of
+// its image (its `<img>` child): `data-loading` while it loads and `data-error` when it failed or
+// has no source, Base UI's attributes, on the image, which stays hidden meanwhile (avatar.css);
+// `data-loaded` on the root once it has loaded, which hides the fallback. Each change dispatches
+// `loadingstatuschange` on the image. A new `src` or `srcset`, or a new image, starts over.
+// It must not import `lumiose`: server-rendered pages load it without the runtime.
+
+/** An avatar image's loading status. */
+export type AvatarLoadingStatus = "loading" | "loaded" | "error";
+
+/** The `detail` of `loadingstatuschange`. */
+export interface AvatarLoadingStatusChangeDetail {
+  status: AvatarLoadingStatus;
+}
+
+export class AvatarElement extends HTMLElement {
+  #observer: MutationObserver | undefined;
+  #image: HTMLImageElement | null = null;
+  #status: AvatarLoadingStatus | undefined;
+
+  /** The loading status of the avatar's image; `undefined` while it has none. */
+  get status(): AvatarLoadingStatus | undefined {
+    return this.#status;
+  }
+
+  connectedCallback(): void {
+    // `load` and `error` do not bubble: they reach the root in the capture phase.
+    this.addEventListener("load", this.#settle, true);
+    this.addEventListener("error", this.#settle, true);
+    this.#observer = new MutationObserver(this.#check);
+    this.#observer.observe(this, {
+      childList: true,
+      subtree: true,
+      attributeFilter: ["src", "srcset"],
+    });
+    this.#check();
+  }
+
+  disconnectedCallback(): void {
+    this.removeEventListener("load", this.#settle, true);
+    this.removeEventListener("error", this.#settle, true);
+    this.#observer?.disconnect();
+  }
+
+  #settle = (event: Event): void => {
+    const image = this.#current();
+    if (image !== null && event.target === image) {
+      this.#set(image, event.type === "load" ? "loaded" : "error");
+    }
+  };
+
+  #check = (): void => {
+    const image = this.#current();
+    if (image === null) {
+      this.#image = null;
+      this.#status = undefined;
+      this.removeAttribute("data-loaded");
+    } else if (!image.getAttribute("src") && !image.getAttribute("srcset")) {
+      this.#set(image, "error");
+    } else if (!image.complete) {
+      this.#set(image, "loading");
+    } else if (image.naturalWidth > 0) {
+      this.#set(image, "loaded");
+    } else {
+      // Complete without a size: a broken image, or an SVG without intrinsic dimensions.
+      const source = image.currentSrc;
+      const done = (status: AvatarLoadingStatus) => () => {
+        if (image.currentSrc === source && this.#current() === image) this.#set(image, status);
+      };
+      this.#set(image, "loading");
+      image.decode().then(done("loaded"), done("error"));
+    }
+  };
+
+  #current(): HTMLImageElement | null {
+    return this.querySelector<HTMLImageElement>(":scope > img");
+  }
+
+  #set(image: HTMLImageElement, status: AvatarLoadingStatus): void {
+    image.toggleAttribute("data-loading", status === "loading");
+    image.toggleAttribute("data-error", status === "error");
+    this.toggleAttribute("data-loaded", status === "loaded");
+    if (image === this.#image && status === this.#status) return;
+    this.#image = image;
+    this.#status = status;
+    image.dispatchEvent(
+      new CustomEvent<AvatarLoadingStatusChangeDetail>("loadingstatuschange", {
+        detail: { status },
+      }),
+    );
+  }
+}
+
+if (!customElements.get("lu-avatar")) {
+  customElements.define("lu-avatar", AvatarElement);
+}

package/dist/avatar/avatar.tsx

@@ -0,0 +1,110 @@
+// Avatar (decision-62, TASK-374): an image with a fallback, after Base UI's Avatar with its
+// `keepMounted` image. Root renders `<lu-avatar>` (./avatar.script.ts), which stacks the image over
+// the fallback in one grid cell, so neither moves the other. Image renders a native `<img>` in the
+// server HTML, loading at once (or lazily), hidden while it loads and after it fails; Fallback
+// renders a `<span>` (initials, an icon), shown until the image has loaded, after an optional
+// delay. Without JavaScript the image covers the fallback once it loads.
+import { onMount, ref } from "lumiose";
+import { withStyle } from "../placement/placement.ts";
+import avatarScript from "./avatar.script.ts?client";
+import type {
+  AvatarElement,
+  AvatarLoadingStatus,
+  AvatarLoadingStatusChangeDetail,
+} from "./avatar.script.ts";
+
+export type { AvatarLoadingStatus } from "./avatar.script.ts";
+
+declare module "lumiose/jsx-runtime" {
+  namespace JSX {
+    interface IntrinsicElements {
+      /** Avatar.Root's element: it follows its image's loading status. */
+      "lu-avatar": JSX.HTMLProps<AvatarElement>;
+    }
+  }
+}
+
+/** `Avatar.Root` renders `<lu-avatar>`, an inline box around the image and the fallback. */
+export type AvatarRootProps = JSX.IntrinsicElements["lu-avatar"];
+
+/** `Avatar.Image` renders a native `<img>`, with every native prop. */
+export type AvatarImageProps = JSX.IntrinsicElements["img"] & {
+  /**
+   * Called when the image's loading status changes: `"loading"`, `"loaded"`, or `"error"` (it
+   * failed, or has no `src`). In an island it also reports the status the image had when the island
+   * hydrated.
+   */
+  onLoadingStatusChange?: (status: AvatarLoadingStatus) => void;
+};
+
+/** `Avatar.Fallback` renders a `<span>`, shown until the image has loaded. */
+export type AvatarFallbackProps = JSX.IntrinsicElements["span"] & {
+  /**
+   * How long to wait before showing the fallback, in milliseconds: an image that loads sooner never
+   * shows it. Default `0`.
+   */
+  delay?: number;
+};
+
+/**
+ * An inline box for the image and the fallback, stacked in one cell. Give it a size (the default
+ * theme's `lu-avatar` does), so the image loading or failing never changes the layout.
+ */
+function Root({ children, ...rest }: AvatarRootProps) {
+  // `<lu-avatar>` follows the image's loading status; the page loads it once (decision-63).
+  avatarScript();
+  return <lu-avatar {...rest}>{children}</lu-avatar>;
+}
+
+/**
+ * The picture: a native `<img>`, with `alt` (the person's name, or `""` when the name is next to
+ * it). Hidden while it loads and after it fails, as `[data-loading]` and `[data-error]`.
+ */
+function Image({ onLoadingStatusChange, ...rest }: AvatarImageProps) {
+  const image = ref<HTMLImageElement>();
+  let reported: AvatarLoadingStatus | undefined;
+  const report = (status: AvatarLoadingStatus | undefined) => {
+    if (status === undefined || status === reported) return;
+    reported = status;
+    onLoadingStatusChange?.(status);
+  };
+  // A hydrated island hears the status the image already had.
+  onMount(() => report((image()?.parentElement as AvatarElement | null)?.status));
+  return (
+    <img
+      {...rest}
+      ref={image}
+      data-loading
+      on:loadingstatuschange={(event: CustomEvent<AvatarLoadingStatusChangeDetail>) =>
+        report(event.detail.status)
+      }
+    />
+  );
+}
+
+/** What shows until the image has loaded: initials or an icon, in a `<span data-fallback>`. */
+function Fallback({ delay, style, children, ...rest }: AvatarFallbackProps) {
+  return (
+    <span
+      {...rest}
+      data-fallback
+      style={
+        delay ? withStyle(style, { "--lu-avatar-delay": `${delay}ms` } as JSX.CSSProperties) : style
+      }
+    >
+      {children}
+    </span>
+  );
+}
+
+/**
+ * An image with a fallback, after Base UI's Avatar: Root, Image and Fallback. A 0.5 kB script
+ * follows the image's loading status.
+ *
+ * @example
+ * <Avatar.Root class="lu-avatar">
+ *   <Avatar.Image src="/people/ada.jpg" alt="Ada Lovelace" />
+ *   <Avatar.Fallback delay={600}>AL</Avatar.Fallback>
+ * </Avatar.Root>
+ */
+export const Avatar = { Root, Image, Fallback };

package/dist/button/button.script.ts

@@ -0,0 +1,35 @@
+// Button's client script (decision-62, decision-63). A Button disabled with `focusableWhenDisabled`
+// stays a focusable `<button aria-disabled="true">` (a loading state keeps its place in the tab
+// order and its focus), so the platform would still run its click, submit its form or reset it.
+// Where this script runs, a click on such a button, from the pointer, Enter or Space, is cancelled
+// before any handler sees it. A press (`pointerdown`, `mousedown`) or Enter or Space (`keydown`,
+// `keyup`) reaches none of its handlers either, nor its ancestors' bubbling ones, as in Base UI
+// (TASK-450 L23); listeners that capture (a layer's outside press) still see them, the press still
+// focuses it, and the other keys (Tab, a toolbar's arrows) go on. Buttons with a role (menu items,
+// tabs) are their widgets' to handle.
+// It must not import `lumiose`: server-rendered pages load it without the runtime.
+
+const DISABLED = "button[aria-disabled='true']:not([role])";
+
+/** Cancels a click on an `aria-disabled` button, before Lumiose's handlers and the form's action. */
+export function cancelDisabledClick(event: Event): void {
+  const button = (event.target as Element).closest?.(DISABLED);
+  if (!button) return;
+  event.preventDefault();
+  event.stopImmediatePropagation();
+}
+
+/** Keeps a press, Enter or Space on an `aria-disabled` button from its handlers. */
+export function stopDisabledInteraction(event: Event): void {
+  if (!(event.target as Element).closest?.(DISABLED)) return;
+  if (event instanceof KeyboardEvent) {
+    if (event.key !== "Enter" && event.key !== " ") return;
+    event.preventDefault();
+  }
+  event.stopPropagation();
+}
+
+document.addEventListener("click", cancelDisabledClick, true);
+for (const type of ["pointerdown", "mousedown", "keydown", "keyup"]) {
+  document.addEventListener(type, stopDisabledInteraction, true);
+}

package/dist/button/button.tsx

@@ -0,0 +1,40 @@
+// Button (decision-62, TASK-364): a native `<button>`, after Base UI's Button. `type` defaults to
+// `"button"`, so a Button in a form submits only when asked to. Disabled it is natively disabled
+// (out of the tab order); with `focusableWhenDisabled` it stays focusable as
+// `aria-disabled="true"` and button.script.ts cancels its clicks.
+import buttonScript from "./button.script.ts?client";
+
+/** A native `<button>`, with every native prop (`type`, `name`, `value`, `form`, `command`, …). */
+export type ButtonProps = JSX.IntrinsicElements["button"] & {
+  /**
+   * Keeps the button focusable while `disabled`: it becomes `aria-disabled="true"` instead of
+   * natively disabled, so focus stays on it (a loading state, say) and screen readers still find
+   * it; its clicks are ignored.
+   */
+  focusableWhenDisabled?: boolean;
+};
+
+/**
+ * A native button. Unstyled: style it through `class` and `:disabled`, `[aria-disabled="true"]`,
+ * `:focus-visible`, `:hover`.
+ *
+ * @example
+ * <Button type="submit" disabled={saving()} focusableWhenDisabled>
+ *   {saving() ? "Saving…" : "Save"}
+ * </Button>
+ */
+export function Button({ children, disabled, focusableWhenDisabled, ...rest }: ButtonProps) {
+  // Cancels the clicks of `aria-disabled` buttons; the page loads it once (decision-63).
+  buttonScript();
+  const soft = () => disabled === true && focusableWhenDisabled === true;
+  return (
+    <button
+      type="button"
+      {...rest}
+      disabled={disabled === true && !soft()}
+      aria-disabled={soft() ? "true" : rest["aria-disabled"]}
+    >
+      {children}
+    </button>
+  );
+}