@0001-labs/design-system-1 0.3.0-alpha.13 → 0.3.0-alpha.14

package/DS1/react/carousel.ts

@@ -0,0 +1,76 @@
+/** A carousel in React: the slides stay in the light DOM, so they render on
+ * the server and read in tests; ds-carousel snaps them, draws the dots and
+ * buttons and announces the slide in view. The region and its name are in the
+ * markup from the first render. Browser-only registration of ds-carousel stays
+ * in the product's runtime entry. */
+import { createElement as h, forwardRef, useEffect, useLayoutEffect, useRef, type HTMLAttributes, type ReactNode } from "react";
+import type { Carousel as CarouselElement, CarouselChangeDetail } from "../3-unit/ds-carousel";
+
+export type { CarouselChangeDetail } from "../3-unit/ds-carousel";
+export type CarouselProps = Omit<HTMLAttributes<CarouselElement>, "onChange"> & {
+  /** The region's name: what the slides show. */
+  label: string;
+  /** The slide in view, from 0. Changing it scrolls there. */
+  current?: number;
+  /** Show previous and next buttons beside the dots. */
+  buttons?: boolean;
+  /** Show the dots; on by default. */
+  dots?: boolean;
+  /** Draw the last dot as an end marker. */
+  end?: boolean;
+  /** Each slide's width in whole squares; the carousel's own width when not set; `"auto"` for slides of their own width, a strip. */
+  slideWidth?: number | "auto";
+  /** Squares between slides; one by default. */
+  gap?: number;
+  /** A strip's bleed: `end` runs it on to the window's end edge, `both` to both edges. */
+  bleed?: "none" | "end" | "both";
+  /** Hold the slides three times over, so the strip has no end; draws no dots. */
+  loop?: boolean;
+  /** Move on by itself: `true` for every five seconds, or milliseconds. Always with a pause button. */
+  autoplay?: boolean | number;
+  /** Slide freely, without stopping at slides. */
+  free?: boolean;
+  /** A person moved to another slide. */
+  onChange?: (index: number, previous: number) => void;
+  children?: ReactNode;
+};
+
+const useCommitEffect = typeof window === "undefined" ? useEffect : useLayoutEffect;
+
+export const Carousel = forwardRef<CarouselElement, CarouselProps>(function Carousel(
+  { label, current, buttons, dots = true, end, slideWidth, gap, bleed, loop, autoplay, free, onChange, children, ...props }, ref,
+) {
+  const host = useRef<CarouselElement | null>(null);
+  useCommitEffect(() => {
+    const element = host.current;
+    if (!element || !onChange) return;
+    const change = (event: Event) => {
+      if (event.target !== element) return;
+      const { index, previous } = (event as CustomEvent<CarouselChangeDetail>).detail;
+      onChange(index, previous);
+    };
+    element.addEventListener("change", change);
+    return () => element.removeEventListener("change", change);
+  });
+  return h("ds-carousel", {
+    role: "region",
+    "aria-label": label,
+    ...props,
+    label,
+    literal: true,
+    current,
+    buttons: buttons || undefined,
+    "no-dots": dots ? undefined : true,
+    end: end || undefined,
+    "slide-width": slideWidth,
+    gap,
+    bleed: bleed && bleed !== "none" ? bleed : undefined,
+    loop: loop || undefined,
+    autoplay: autoplay === true ? "" : typeof autoplay === "number" ? String(autoplay) : undefined,
+    free: free || undefined,
+    ref: (element: CarouselElement | null) => {
+      host.current = element;
+      if (typeof ref === "function") ref(element); else if (ref) ref.current = element;
+    },
+  }, children);
+});

package/DS1/react/dialog.ts

@@ -1,7 +1,7 @@
 /** Optional React composition; behavior and appearance belong to ds-dialog. */
-import { createContext, createElement, useContext, useId, useLayoutEffect, useRef, useState, type HTMLAttributes, type ReactNode, type Ref } from "react";
+import { createContext, createElement, useContext, useEffect, useId, useLayoutEffect, useRef, useState, type HTMLAttributes, type ReactNode, type Ref } from "react";
 import { createPortal } from "react-dom";
-import type { Dialog as DialogElement, DialogCloseReason } from "../4-page/ds-dialog";
+import type { Dialog as DialogElement, DialogCloseReason, DialogPlacement } from "../4-page/ds-dialog";
 
 const DialogContext = createContext<{ open: boolean; change: (open: boolean, reason?: DialogCloseReason) => void; title: string; description: string } | null>(null);
 const useDialog = () => {
@@ -10,7 +10,7 @@ const useDialog = () => {
   return context;
 };
 
-export interface DialogProps { open?: boolean; defaultOpen?: boolean; onOpenChange?: (open: boolean, reason?: DialogCloseReason) => void; children: ReactNode }
+export interface DialogProps { open?: boolean; defaultOpen?: boolean; onOpenChange?: (open: boolean, reason?: DialogCloseReason) => void; children?: ReactNode }
 export function Dialog({ open, defaultOpen = false, onOpenChange, children }: DialogProps) {
   const [internal, setInternal] = useState(defaultOpen);
   const id = useId();
@@ -40,11 +40,41 @@ export interface DialogContentProps extends HTMLAttributes<HTMLDialogElement> {
   flush?: boolean;
   /** Rotate a document frame while keeping it within the viewport. */
   rotated?: boolean;
+  /**
+   * Where it stands: `"center"` (the default), a `"sheet"` from the bottom, or
+   * a drawer at the `"end"` or `"start"`. These slide out before they leave
+   * the page, and a finger swipes them away (reason `"swipe"`).
+   */
+  placement?: DialogPlacement;
 }
-export function DialogContent({ children, portal = true, nonModal = false, closeOnOutside = false, blockOutside = false, holdScroll = false, anchor = null, returnFocus = null, closeLabel = "Close", showClose = true, closeOnEscape = true, closeOnBackdrop = true, fullScreen = false, flush = false, rotated = false, ...props }: DialogContentProps) {
+
+/** The longest a sliding dialog stays on the page after closing, should its transition never end. */
+const LEAVING = 600;
+export function DialogContent({ children, portal = true, nonModal = false, closeOnOutside = false, blockOutside = false, holdScroll = false, anchor = null, returnFocus = null, closeLabel = "Close", showClose = true, closeOnEscape = true, closeOnBackdrop = true, fullScreen = false, flush = false, rotated = false, placement = "center", ...props }: DialogContentProps) {
   const context = useDialog();
   const host = useRef<DialogElement>(null);
   const [mounted, setMounted] = useState(false);
+  // A sheet or drawer stays on the page while it slides out, then leaves.
+  const sliding = placement !== "center";
+  const [leaving, setLeaving] = useState(false);
+  const [wasOpen, setWasOpen] = useState(context.open);
+  if (wasOpen !== context.open) {
+    setWasOpen(context.open);
+    setLeaving(!context.open && sliding && mounted);
+  }
+  useEffect(() => {
+    if (!leaving) return;
+    const native = host.current?.querySelector("dialog");
+    const done = () => setLeaving(false);
+    const ended = (event: Event) => {
+      const { propertyName, pseudoElement } = event as TransitionEvent;
+      if (event.target === native && !pseudoElement && (propertyName === "transform" || propertyName === "opacity")) done();
+    };
+    native?.addEventListener("transitionend", ended);
+    native?.addEventListener("transitioncancel", ended);
+    const timer = setTimeout(done, LEAVING);
+    return () => { clearTimeout(timer); native?.removeEventListener("transitionend", ended); native?.removeEventListener("transitioncancel", ended); };
+  }, [leaving]);
   // A portal has no server location. Keep the server and first client render
   // identical, including when the application initially requests an open modal.
   useLayoutEffect(() => { setMounted(true); }, []);
@@ -77,10 +107,11 @@ export function DialogContent({ children, portal = true, nonModal = false, close
     element.holdScroll = holdScroll;
     element.anchor = anchor;
     element.returnFocus = returnFocus;
+    element.placement = placement;
     element.open = context.open;
     return () => element.removeEventListener("ds-close-request", close);
   });
-  if (!mounted || !context.open) return null;
+  if (!mounted || (!context.open && !leaving)) return null;
   const content = createElement("ds-dialog", { ref: host },
     createElement("dialog", { ...props, "data-ds-dialog-fullscreen": fullScreen || undefined, "data-ds-dialog-flush": flush || undefined, "data-ds-dialog-rotated": rotated || undefined }, children,
       showClose && createElement("ds-button", { control: "slotted", icon: true, "data-ds-dialog": "close" },

package/DS1/react/document.ts

@@ -0,0 +1,14 @@
+import { createElement, forwardRef, type HTMLAttributes } from "react";
+import type { DocumentPage as DocumentElement } from "../4-page/ds-document";
+
+export type DocumentPageProps = HTMLAttributes<DocumentElement> &
+  Partial<Pick<DocumentElement, "levels" | "label" | "literal" | "hideContents">>;
+/**
+ * A document page: the children are the writing (native headings,
+ * paragraphs and a `<dl className="ds-definitions">`), in the light DOM so
+ * they render on the server; the element builds the contents from them.
+ * Browser-only registration stays in the product's runtime entry for SSR.
+ */
+export const DocumentPage = forwardRef<DocumentElement, DocumentPageProps>(function DocumentPage({ hideContents, ...props }, ref) {
+  return createElement("ds-document", { ...props, "hide-contents": hideContents || undefined, "data-ds-prose": "", ref });
+});

package/DS1/react/empty.ts

@@ -0,0 +1,32 @@
+/** An empty state in React: the words stay in the light DOM, so they render on
+ * the server and read in tests; ds-empty draws them. Browser-only registration
+ * of ds-empty stays in the product's runtime entry. */
+import { createElement as h, forwardRef, type HTMLAttributes, type ReactNode } from "react";
+import type { Empty as EmptyElement } from "../2-core/ds-empty";
+
+export type EmptyProps = Omit<HTMLAttributes<EmptyElement>, "title"> & {
+  /** The title. Unset, the shared words' "Nothing here yet" in the current language. */
+  heading?: ReactNode;
+  /** The line under the title; `children` take its place when given. */
+  text?: ReactNode;
+  /** An icon from the library on the square above the title. */
+  icon?: string;
+  /** The buttons or links that fill the place, on one row. */
+  actions?: ReactNode;
+  /** Centre the words in the space the element stands in. */
+  centered?: boolean;
+  /** Make the title a heading of this level (1–6). */
+  level?: number;
+};
+
+const title = (content: ReactNode) =>
+  content == null || content === false || content === "" ? null : h("span", { slot: "heading" }, content);
+
+export const Empty = forwardRef<EmptyElement, EmptyProps>(function Empty(
+  { heading, text, icon, actions, centered, level, children, ...props }, ref,
+) {
+  return h("ds-empty", { ...props, icon, centered: centered || undefined, level, ref },
+    title(heading),
+    children ?? text,
+    actions == null || actions === false ? null : h("div", { slot: "actions", style: { display: "contents" } }, actions));
+});

package/DS1/react/footer.ts

@@ -0,0 +1,17 @@
+import { createElement, forwardRef, type HTMLAttributes } from "react";
+import type { Footer as FooterElement } from "../4-page/ds-footer";
+
+export type { FooterColumn, FooterLink, FooterPreference } from "../4-page/ds-footer";
+export type FooterProps = Omit<HTMLAttributes<FooterElement>, "columns"> &
+  Partial<Pick<FooterElement, "brand" | "href" | "tagline" | "columns" | "label" | "owner" | "year" | "preferences" | "literal">>;
+/**
+ * A site footer from data: `columns` is set as a property, so React passes
+ * the array as it stands. A brand, preferences or legal line of the page's own
+ * take `slot="brand"`, `slot="preferences"` and `slot="legal"`. A page that
+ * must render its links on the server writes the `.ds-footer` classes instead.
+ * Browser-only registration stays in the product's runtime entry for SSR.
+ */
+export const Footer = forwardRef<FooterElement, FooterProps>(function Footer({ preferences, ...props }, ref) {
+  // `preferences` present but empty means every preference, as the attribute does.
+  return createElement("ds-footer", { ...props, preferences: preferences === undefined ? undefined : String(preferences), ref });
+});

package/DS1/react/header.ts

@@ -0,0 +1,15 @@
+import { createElement, forwardRef, type HTMLAttributes } from "react";
+import type { Header as HeaderElement } from "../4-page/ds-header";
+
+export type HeaderProps = HTMLAttributes<HeaderElement> &
+  Partial<Pick<HeaderElement, "brand" | "href" | "label" | "literal" | "sticky">>;
+/**
+ * A site header. Its navigation is the children: `<a href>` links, in the
+ * light DOM so they render on the server; actions take `slot="actions"`, a
+ * brand of the page's own `slot="brand"`. Typed so a React product needs no
+ * `IntrinsicElements` entry of its own for `ds-header`. Browser-only
+ * registration stays in the product's runtime entry for SSR.
+ */
+export const Header = forwardRef<HeaderElement, HeaderProps>(function Header(props, ref) {
+  return createElement("ds-header", { ...props, ref });
+});

package/DS1/react/input.ts

@@ -24,7 +24,24 @@ export type InputProps = Omit<
   variant?: InputElement["variant"];
   revealable?: boolean;
   quietFocus?: boolean;
+  /** The label on the row above the field, as written. */
+  label?: string;
+  /** The label as a translation key, shown in the page's language. */
+  labelText?: string;
+  /** The placeholder as a translation key; `placeholder` is as written. */
+  placeholderKey?: string;
+  /** The error under the field, as written, in the danger colour. */
   error?: string;
+  /** The error as a translation key. */
+  errorText?: string;
+  /** Suggestions offered while typing; `list` names a `<datalist>` instead. */
+  suggestions?: InputElement["suggestions"];
+  /** A text area: the field across whole rows. */
+  multiline?: boolean;
+  rows?: number;
+  wrap?: "soft" | "hard" | "off";
+  autoGrow?: boolean;
+  maxRows?: number;
 };
 const useCommitEffect = typeof window === "undefined" ? useEffect : useLayoutEffect;
 /** Native listeners cross Lit's shadow boundary without React's input tracker.
@@ -48,18 +65,7 @@ function setRef(ref: Ref<InputElement> | undefined, field: InputElement | null)
   if (ref) ref.current = field;
 }
 
-type FieldProps = InputProps & {
-  rows?: number;
-  wrap?: "soft" | "hard" | "off";
-  autoGrow?: boolean;
-  maxRows?: number;
-};
-export type TextareaProps = Omit<
-  FieldProps,
-  "type" | "revealable" | "min" | "max" | "step" | "pattern"
-> & { variant?: "field" | "plain" };
-function fieldAdapter<Props extends FieldProps>(tag: "ds-input" | "ds-textarea") {
-  return forwardRef<InputElement, Props>(function Field(
+export const Input = forwardRef<InputElement, InputProps>(function Field(
     {
       value,
       defaultValue,
@@ -79,8 +85,12 @@ function fieldAdapter<Props extends FieldProps>(tag: "ds-input" | "ds-textarea")
       type = "text",
       variant = "field",
       quietFocus,
+      multiline,
       autoGrow,
       maxRows,
+      labelText,
+      placeholderKey,
+      errorText,
       ...props
     },
     forwardedRef,
@@ -158,7 +168,7 @@ function fieldAdapter<Props extends FieldProps>(tag: "ds-input" | "ds-textarea")
           element.removeEventListener(name, callback, capture);
       };
     });
-    return createElement(tag, {
+    return createElement("ds-input", {
       ...attributes,
       ref,
       type,
@@ -175,10 +185,11 @@ function fieldAdapter<Props extends FieldProps>(tag: "ds-input" | "ds-textarea")
       step: step == null ? undefined : String(step),
       spellcheck: spellCheck === undefined ? undefined : String(spellCheck),
       "quiet-focus": quietFocus,
+      "label-text": labelText,
+      "placeholder-key": placeholderKey,
+      "error-text": errorText,
+      multiline: multiline || undefined,
       "auto-grow": autoGrow,
       "max-rows": maxRows,
     });
-  });
-}
-export const Input = fieldAdapter<InputProps>("ds-input");
-export const Textarea = fieldAdapter<TextareaProps>("ds-textarea");
+});

package/DS1/react/kbd.ts

@@ -0,0 +1,21 @@
+/** A keyboard shortcut's hint in React: ds-kbd writes the shortcut as the
+ * reader's platform does (⇧⌘D, Ctrl+Shift+D). Browser-only registration of
+ * ds-kbd stays in the product's runtime entry; children are words of the
+ * product's own, shown when there is no `shortcut`. */
+import { createElement as h, forwardRef, type HTMLAttributes, type ReactNode } from "react";
+import type { Kbd as KbdElement } from "../2-core/ds-kbd";
+import type { KeyPlatform } from "../0-face/keys";
+
+export type KbdProps = HTMLAttributes<KbdElement> & {
+  /** The shortcut, written once for every platform: `mod+shift+d`, `escape`, `?`. */
+  shortcut?: string;
+  /** The words alone in the title grey, as a menu entry writes its shortcut. */
+  plain?: boolean;
+  /** Write it for this platform rather than the reader's own. */
+  platform?: KeyPlatform;
+  children?: ReactNode;
+};
+
+export const Kbd = forwardRef<KbdElement, KbdProps>(function Kbd({ shortcut, plain, platform, children, ...props }, ref) {
+  return h("ds-kbd", { ...props, shortcut, plain: plain || undefined, platform, ref }, children);
+});

package/DS1/react/loading.ts

@@ -0,0 +1,18 @@
+import { createElement, Fragment, type CSSProperties, type ReactNode } from "react";
+import { getText } from "../0-face/i18n";
+import styles from "../2-core/styles/ds-loading.css?inline";
+export const loadingStyles = styles;
+/** SSR-safe automatic feedback. Decorative when a containing status owns the label.
+ * Shared markup and CSS work before hydration; no DOM runtime is imported.
+ * Unset, the label is the shared word "Loading" in the page's language. A
+ * spinner in a button or field is one control high, elsewhere one square. */
+export function LoadingIndicator({ label, variant = "bar", decorative = false, className = "", style }: {
+  label?: string; variant?: "bar" | "spinner"; decorative?: boolean; className?: string; style?: CSSProperties;
+}): ReactNode {
+  const name = decorative ? undefined : label || getText("Loading") || "Loading";
+  return createElement(Fragment, null, createElement("style", null, styles),
+    createElement("span", { className: `ds-loading ${className}`, style, "data-variant": variant,
+      role: decorative ? undefined : "status", "aria-label": name,
+      "aria-hidden": decorative || undefined, "aria-busy": decorative ? undefined : true },
+      createElement("span", { className: "ds-loading__fill", "aria-hidden": true })));
+}

package/DS1/react/notice.ts

@@ -0,0 +1,59 @@
+/** An inline notice in React: the words stay in the light DOM, so they render
+ * on the server and read in tests; ds-notice draws them and is the live region.
+ * Browser-only registration of ds-notice stays in the product's runtime entry. */
+import { createElement as h, forwardRef, useEffect, useLayoutEffect, useRef, type HTMLAttributes, type ReactNode } from "react";
+import type { Notice as NoticeElement, NoticeTone } from "../2-core/ds-notice";
+
+export type { NoticeTone } from "../2-core/ds-notice";
+export type NoticeProps = Omit<HTMLAttributes<NoticeElement>, "title"> & {
+  /** The mark's colour and icon; danger also colours the words. Neutral by default. */
+  tone?: NoticeTone;
+  /** A title on the first line. */
+  heading?: ReactNode;
+  /** The text; `children` take its place when given. */
+  text?: ReactNode;
+  /** An icon from the library in place of the tone's own. */
+  icon?: string;
+  /** Buttons or links on the row under the words. */
+  actions?: ReactNode;
+  /** Show the close button. On by default when `onDismiss` is given. */
+  dismissible?: boolean;
+  /** A strip across the top of its positioning context instead of a block in the flow. */
+  banner?: boolean;
+  /** The close button was pressed. The product removes the notice; without
+   * this callback the element hides itself. */
+  onDismiss?: () => void;
+};
+
+const useCommitEffect = typeof window === "undefined" ? useEffect : useLayoutEffect;
+const title = (content: ReactNode) =>
+  content == null || content === false || content === "" ? null : h("span", { slot: "heading" }, content);
+
+export const Notice = forwardRef<NoticeElement, NoticeProps>(function Notice(
+  { tone, heading, text, icon, actions, dismissible, banner, onDismiss, children, ...props }, ref,
+) {
+  const host = useRef<NoticeElement | null>(null);
+  useCommitEffect(() => {
+    const element = host.current;
+    if (!element || !onDismiss) return;
+    const dismiss = (event: Event) => {
+      if (event.target !== element) return;
+      event.preventDefault();
+      onDismiss();
+    };
+    element.addEventListener("ds-notice-dismiss", dismiss);
+    return () => element.removeEventListener("ds-notice-dismiss", dismiss);
+  });
+  // The live region is in the markup from the first render, on the server too.
+  return h("ds-notice", {
+    role: tone === "danger" ? "alert" : "status",
+    ...props, tone, icon, banner: banner || undefined, dismissible: (dismissible ?? Boolean(onDismiss)) || undefined,
+    ref: (element: NoticeElement | null) => {
+      host.current = element;
+      if (typeof ref === "function") ref(element); else if (ref) ref.current = element;
+    },
+  },
+  title(heading),
+  children ?? text,
+  actions == null || actions === false ? null : h("div", { slot: "actions", style: { display: "contents" } }, actions));
+});

package/DS1/react/page.ts

@@ -0,0 +1,13 @@
+import { createElement, forwardRef, type HTMLAttributes } from "react";
+import type { Page as PageElement } from "../4-page/ds-page";
+
+export type PageProps = HTMLAttributes<PageElement> &
+  Partial<Pick<PageElement, "layout" | "divided" | "measure" | "fill" | "view">>;
+/**
+ * A standard page. Typed so a React product needs no `IntrinsicElements`
+ * entry of its own for `ds-page`; `measure` is a count of squares.
+ * Browser-only registration stays in the product's runtime entry for SSR.
+ */
+export const Page = forwardRef<PageElement, PageProps>(function Page(props, ref) {
+  return createElement("ds-page", { ...props, ref });
+});

package/DS1/react/progress.ts

@@ -0,0 +1,99 @@
+/** Progress in React. A value against its range puts its role and values in
+ * the markup from the first render, on the server too, written in the
+ * language. Steps arrive as a property, with what belongs under each step in
+ * a vertical sequence slotted from the light DOM. Dots are a group whose
+ * picks come back as `onSelect`. Register ds-progress in the browser before
+ * hydration. */
+import { createElement as h, forwardRef, useEffect, useLayoutEffect, useRef, type HTMLAttributes, type ReactNode } from "react";
+import type { Progress as ProgressElement, ProgressSelectDetail, Step } from "../2-core/ds-progress";
+import { meterAria, type FigureFormat } from "../2-core/figures";
+
+export type { Step, StepState } from "../2-core/ds-progress";
+export type ProgressProps = Omit<HTMLAttributes<ProgressElement>, "title" | "children" | "onSelect"> & {
+  /** The value. Past `max`, it is over. */
+  value?: number;
+  /** The start of the range, 0 by default. */
+  min?: number;
+  /** The end of the range, 1 by default. */
+  max?: number;
+  /** Draw the range in this many squares instead of a bar. */
+  squares?: number;
+  /** Show it as over whatever its value. */
+  over?: boolean;
+  /** What the value says, in place of "7 of 10". */
+  valuetext?: string;
+  /** How the value and the range are written in the words. */
+  format?: FigureFormat;
+  /** The ISO 4217 code for money. */
+  currency?: string;
+  /** The money is counted in the currency's minor unit. */
+  minor?: boolean;
+  /** Money in whole units only. */
+  whole?: boolean;
+  /** Decimals in the words. */
+  digits?: number;
+  /** Write the words in this language rather than the current one. */
+  language?: string;
+  /** A sequence: the steps in order, names or `{ label, state, href }`. */
+  steps?: Step[];
+  /** The number of the current step, counted from 1. */
+  current?: number;
+  /** One step to a row, with `bodies` under them. */
+  vertical?: boolean;
+  /** In a vertical sequence, what belongs under each step, by its place in `steps`. */
+  bodies?: ReactNode[];
+  /** A dot for each of this many pages. */
+  dots?: number;
+  /** The current dot, from 0. */
+  active?: number;
+  /** Draw the last dot as an end marker. */
+  end?: boolean;
+  /** Each dot's name, with `{index}` for its number from 1. */
+  dotLabel?: string;
+  /** A person picked a dot. */
+  onSelect?: (index: number, previous: number) => void;
+  /** The element's name for assistive technology. */
+  label?: string;
+  /** Show the words as written, never looked up. On by default: React writes its own words. */
+  literal?: boolean;
+};
+
+const useCommitEffect = typeof window === "undefined" ? useEffect : useLayoutEffect;
+
+export const Progress = forwardRef<ProgressElement, ProgressProps>(function Progress(
+  { value, min = 0, max = 1, squares, over, valuetext, format, currency, minor, whole, digits, language,
+    steps, current, vertical, bodies, dots, active, end, dotLabel, onSelect, label, literal = true, ...props }, ref,
+) {
+  const host = useRef<ProgressElement | null>(null);
+  useCommitEffect(() => {
+    const element = host.current;
+    if (!element || !onSelect) return;
+    const select = (event: Event) => {
+      if (event.target !== element) return;
+      const { index, previous } = (event as CustomEvent<ProgressSelectDetail>).detail;
+      onSelect(index, previous);
+    };
+    element.addEventListener("select", select);
+    return () => element.removeEventListener("select", select);
+  });
+  const attach = (element: ProgressElement | null) => {
+    host.current = element;
+    if (typeof ref === "function") ref(element); else if (ref) ref.current = element;
+  };
+  if (steps) {
+    return h("ds-progress", { ...props, steps, current, vertical: vertical || undefined, label, literal: literal || undefined, ref: attach },
+      vertical ? bodies?.map((body, index) => body == null || body === false
+        ? null
+        : h("div", { key: index, slot: `step-${index + 1}`, style: { display: "contents" } }, body)) : null);
+  }
+  if (dots !== undefined) {
+    return h("ds-progress", { role: "group", "aria-label": label, ...props, dots, active, end: end || undefined, "dot-label": dotLabel, label, literal: literal || undefined, ref: attach });
+  }
+  const aria = meterAria(value ?? 0, min, max, { over, format, currency, minor, whole, digits, language });
+  return h("ds-progress", {
+    role: "meter", "aria-valuenow": aria.now, "aria-valuemin": aria.min, "aria-valuemax": aria.max,
+    "aria-valuetext": valuetext || aria.text, "aria-label": label,
+    ...props, value: value ?? 0, min, max, squares, over: over || undefined, label, valuetext, format, currency,
+    minor: minor || undefined, whole: whole || undefined, digits, literal: literal || undefined, ref: attach,
+  });
+});

package/DS1/react/sidebar.ts

@@ -0,0 +1,60 @@
+/** A sidebar in React: the rows go to ds-sidebar as a property, its events come
+ * back as callbacks; `tree` makes it a tree of nested things. Browser-only
+ * registration of ds-sidebar stays in the product's runtime entry; on the
+ * server the element renders empty and fills on load. */
+import { createElement as h, forwardRef, useEffect, useLayoutEffect, useRef, type HTMLAttributes } from "react";
+import type { Sidebar as SidebarElement, SidebarItem } from "../3-unit/ds-sidebar";
+
+export type { SidebarItem };
+
+export type SidebarProps = Omit<HTMLAttributes<SidebarElement>, "onSelect" | "onToggle"> & {
+  /** The visible rows, in order; leave out the children of a closed row. */
+  items: SidebarItem[];
+  /** The navigation's or the tree's accessible name. */
+  label?: string;
+  /** The empty state's words. */
+  empty?: string;
+  /** A tree of nested things instead of navigation. */
+  tree?: boolean;
+  /** A row asks to open (`true`) or close. */
+  onToggle?: (id: string, expanded: boolean) => void;
+  /** A click, Space or Enter chose a tree row. */
+  onSelect?: (id: string) => void;
+  /** A row was pressed (navigation), or Enter or a double click opened one (a tree). */
+  onActivate?: (id: string) => void;
+  /** A row's own action was pressed. */
+  onAction?: (id: string, action: string) => void;
+};
+
+const useCommitEffect = typeof window === "undefined" ? useEffect : useLayoutEffect;
+
+export const Sidebar = forwardRef<SidebarElement, SidebarProps>(function Sidebar(
+  { items, label, empty, tree, onToggle, onSelect, onActivate, onAction, ...props }, ref,
+) {
+  const host = useRef<SidebarElement>(null);
+  useCommitEffect(() => {
+    const element = host.current; if (!element) return;
+    element.items = items;
+  }, [items]);
+  useCommitEffect(() => {
+    const element = host.current; if (!element) return;
+    const detail = (event: Event) => (event as CustomEvent<{ id: string; expanded?: boolean; action?: string }>).detail;
+    const toggle = (event: Event) => { const d = detail(event); onToggle?.(d.id, Boolean(d.expanded)); };
+    const select = (event: Event) => onSelect?.(detail(event).id);
+    const activate = (event: Event) => onActivate?.(detail(event).id);
+    const action = (event: Event) => { const d = detail(event); onAction?.(d.id, d.action ?? ""); };
+    element.addEventListener("sidebar-toggle", toggle);
+    element.addEventListener("sidebar-select", select);
+    element.addEventListener("sidebar-activate", activate);
+    element.addEventListener("sidebar-action", action);
+    return () => {
+      element.removeEventListener("sidebar-toggle", toggle);
+      element.removeEventListener("sidebar-select", select);
+      element.removeEventListener("sidebar-activate", activate);
+      element.removeEventListener("sidebar-action", action);
+    };
+  });
+  return h("ds-sidebar", { ...props, label, empty, tree: tree || undefined,
+    ref: (element: SidebarElement | null) => { host.current = element; if (typeof ref === "function") ref(element); else if (ref) ref.current = element; },
+  });
+});

package/DS1/react/spacing-handle.ts

@@ -0,0 +1,21 @@
+import { createElement, useEffect, useLayoutEffect, useRef, type CSSProperties, type ReactNode, type MouseEvent } from "react";
+import { bindSpacingHandle, type SpacingOptions } from "../2-core/spacing-handle";
+import styles from "../2-core/styles/ds-spacing-handle.css?inline";
+const useCommitEffect = typeof window === "undefined" ? useEffect : useLayoutEffect;
+export interface SpacingHandleProps extends SpacingOptions {
+  label: string; valueText?: string; className?: string; style?: CSSProperties;
+  children?: ReactNode; onDoubleClick?: (event: MouseEvent<HTMLSpanElement>) => void;
+}
+/** Internal app chrome. Shared native target, keyboard/pointer controller and face. */
+export function SpacingHandle(props: SpacingHandleProps): ReactNode {
+  const ref = useRef<HTMLSpanElement>(null);
+  const latest = useRef(props); latest.current = props;
+  useCommitEffect(() => ref.current ? bindSpacingHandle(ref.current, () => latest.current) : undefined, []);
+  return createElement("span", { ref, className: `ds-spacing-control ${props.className ?? ""}`, style: props.style,
+    role: "slider", tabIndex: props.disabled ? -1 : 0, "aria-label": props.label,
+    "aria-orientation": props.axis ?? "horizontal", "aria-valuemin": props.min ?? 0,
+    "aria-valuemax": props.max ?? 1000000, "aria-valuenow": props.value,
+    "aria-valuetext": props.valueText ?? String(props.value), "aria-disabled": !!props.disabled,
+    onDoubleClick: props.onDoubleClick, onClick: (e: MouseEvent) => e.stopPropagation(),
+  }, createElement("style", null, styles), props.children ?? createElement("span", { className: "ds-spacing-label", "aria-hidden": true }, props.value));
+}