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

package/DS1/4-page/styles/ds-panel.css

@@ -0,0 +1,31 @@
+@import "../../1-root/component-metrics.css";
+
+/* ds-panel.css */
+
+:host {
+  box-sizing: border-box;
+  display: flex;
+  flex-direction: column;
+  min-width: 0;
+  min-height: 0;
+  background: var(--ds-paper);
+  color: var(--ds-text-color);
+  font-family: var(--ds-typeface-regular);
+  font-feature-settings: var(--ds-font-features);
+  font-size: var(--ds-type-size-default);
+  line-height: var(--ds-type-lineheight-default);
+  letter-spacing: var(--ds-type-letterspacing-default);
+}
+
+slot[name="header"],
+slot[name="footer"] {
+  display: block;
+  flex: 0 0 auto;
+}
+
+.body {
+  display: flex;
+  flex: 1 1 auto;
+  flex-direction: column;
+  min-height: 0;
+}

package/DS1/components.ts

@@ -0,0 +1,13 @@
+/** Shared Lit components. Import the scoped component tokens separately. */
+export * from "./2-core/ds-button";
+export * from "./2-core/ds-text";
+export * from "./2-core/ds-input";
+export * from "./2-core/ds-textarea";
+export * from "./2-core/ds-gap";
+export * from "./2-core/ds-icon";
+export * from "./2-core/ds-tooltip";
+export * from "./3-unit/ds-row";
+export * from "./3-unit/ds-list";
+export * from "./3-unit/ds-menu";
+export * from "./3-unit/ds-tabs";
+export * from "./4-page/ds-panel";

package/DS1/index.ts

@@ -0,0 +1,86 @@
+/**
+ * Design system 1 - Main entry point for all components
+ *
+ * This module initializes core utilities and exports all design system components
+ * organized by layer: 0-face (foundation), 2-core (components), 3-unit (composites), 4-page (layouts)
+ */
+
+// ============================================================================
+// Initialization (side-effect imports)
+// ============================================================================
+
+// Initialize device detection (will auto-detect and log on load)
+import "./0-face/device";
+
+// Initialize language utilities (will auto-load external translations if available)
+import "./0-face/i18n";
+
+// ============================================================================
+// 0-face: Foundation & Utilities
+// ============================================================================
+
+export * from "./0-face/device";
+export * from "./0-face/grid";
+export * from "./0-face/tooltips";
+export * from "./0-face/i18n";
+export * from "./0-face/languages";
+export * from "./0-face/language-routing";
+export * from "./0-face/translations-format";
+export * from "./0-face/preferences";
+export * from "./0-face/pricing";
+export * from "./0-face/theme";
+
+// ============================================================================
+// 2-core: Core Components
+// ============================================================================
+
+export * from "./2-core/ds-banner";
+export * from "./2-core/ds-badge";
+export * from "./2-core/ds-button";
+export * from "./2-core/ds-checkbox";
+export * from "./2-core/ds-radio";
+export * from "./2-core/ds-switch";
+export * from "./2-core/ds-split";
+export * from "./2-core/ds-select";
+export * from "./2-core/ds-color";
+export * from "./2-core/ds-swatch";
+export * from "./2-core/ds-card";
+export * from "./2-core/ds-cycle";
+export * from "./2-core/ds-date";
+export * from "./2-core/ds-gap";
+export * from "./2-core/ds-icon";
+export * from "./2-core/ds-input";
+export * from "./2-core/ds-file-picker";
+export * from "./2-core/ds-textarea";
+export * from "./2-core/ds-composer";
+export * from "./2-core/ds-language";
+export * from "./2-core/ds-text";
+export * from "./2-core/ds-tooltip";
+
+// ============================================================================
+// 3-unit: Composite Components
+// ============================================================================
+
+export * from "./3-unit/ds-accordion";
+export * from "./2-core/ds-avatar";
+export * from "./3-unit/ds-avatar-group";
+export * from "./3-unit/ds-form";
+export * from "./3-unit/ds-list";
+export * from "./3-unit/ds-row";
+export * from "./3-unit/ds-table";
+
+// ============================================================================
+// 4-page: Layout Components
+// ============================================================================
+
+export * from "./4-page/ds-container";
+export * from "./4-page/ds-grid";
+export * from "./4-page/ds-layout";
+
+export * from "./3-unit/ds-menu";
+export * from "./3-unit/ds-tabs";
+export * from "./4-page/ds-panel";
+export * from "./4-page/ds-dialog";
+
+export * from "./2-core/ds-token";
+export * from "./3-unit/ds-token-field";

package/DS1/react/accordion.ts

@@ -0,0 +1,33 @@
+import { createElement as h, forwardRef, useEffect, useId, useLayoutEffect, useRef, useState, type HTMLAttributes, type ReactNode } from "react";
+import type { Accordion as AccordionElement } from "../3-unit/ds-accordion";
+
+export type AccordionProps = Omit<HTMLAttributes<AccordionElement>, "onToggle"> & {
+  summary: ReactNode; actions?: ReactNode; open?: boolean; defaultOpen?: boolean; disabled?: boolean;
+  triggerRole?: string; onOpenChange?: (open: boolean) => void;
+};
+const useCommitEffect = typeof window === "undefined" ? useEffect : useLayoutEffect;
+export const Accordion = forwardRef<AccordionElement, AccordionProps>(function Accordion(
+  {summary, actions, open, defaultOpen = false, disabled, triggerRole, onOpenChange, children, ...props}, ref,
+) {
+  const host = useRef<AccordionElement>(null), id = useId();
+  const [localOpen, setLocalOpen] = useState(defaultOpen), expanded = open ?? localOpen;
+  useCommitEffect(() => {
+    const element = host.current; if (!element) return;
+    const toggle = (event: Event) => {
+      if (event.target !== element) return;
+      event.preventDefault(); if (disabled) return;
+      const next = (event as CustomEvent<{open: boolean}>).detail.open;
+      if (open === undefined) setLocalOpen(next);
+      onOpenChange?.(next);
+    };
+    element.addEventListener("ds-accordion-toggle", toggle);
+    return () => element.removeEventListener("ds-accordion-toggle", toggle);
+  });
+  return h("ds-accordion", {...props, control: "slotted", open: expanded,
+    ref: (element: AccordionElement | null) => {host.current = element; if (typeof ref === "function") ref(element); else if (ref) ref.current = element;},
+  }, h("ds-button", {slot: "trigger", control: "slotted", choice: true, disabled},
+    h("button", {type: "button", role: triggerRole, disabled, "aria-expanded": expanded, "aria-controls": id}, summary,
+      h("ds-icon", {type: expanded ? "up" : "down", "aria-hidden": "true", style: {marginInlineStart: "auto", flex: "0 0 auto"}}))),
+    actions == null ? null : h("div", {slot: "actions"}, actions),
+    h("div", {slot: "details", id, hidden: !expanded}, children));
+});

package/DS1/react/avatar-group.ts

@@ -0,0 +1,11 @@
+import { createElement, forwardRef, type HTMLAttributes } from "react";
+import type { AvatarGroup as AvatarGroupElement } from "../3-unit/ds-avatar-group";
+
+export type AvatarGroupProps = HTMLAttributes<AvatarGroupElement> &
+  Partial<Pick<AvatarGroupElement, "size" | "vertical">>;
+/** Registration belongs to the browser runtime; React keeps identity children. */
+export const AvatarGroup = forwardRef<AvatarGroupElement, AvatarGroupProps>(
+  function AvatarGroup(props, ref) {
+    return createElement("ds-avatar-group", { ...props, ref });
+  },
+);

package/DS1/react/avatar.ts

@@ -0,0 +1,42 @@
+import { createElement, forwardRef, type HTMLAttributes } from "react";
+import type { Avatar as AvatarElement } from "../2-core/ds-avatar";
+
+export type AvatarProps = Omit<HTMLAttributes<AvatarElement>, "children"> &
+  Partial<
+    Pick<
+      AvatarElement,
+      | "label"
+      | "initial"
+      | "src"
+      | "icon"
+      | "shape"
+      | "size"
+      | "fit"
+      | "mask"
+      | "outlined"
+      | "pending"
+      | "plain"
+      | "color"
+    >
+  >;
+/** Browser-only registration stays in the product's runtime entry for SSR. */
+export const Avatar = forwardRef<AvatarElement, AvatarProps>(function Avatar(props, ref) {
+  return createElement("ds-avatar", { ...props, ref });
+});
+
+export type LogoProps = Omit<AvatarProps, "shape" | "size" | "fit" | "mask" | "plain"> & {
+  src: string;
+};
+/** A monochrome brand mark fitted into the page's image area. */
+export const Logo = forwardRef<AvatarElement, LogoProps>(function Logo(props, ref) {
+  return createElement("ds-avatar", {
+    size: "fill",
+    shape: "square",
+    fit: "contain",
+    mask: true,
+    plain: true,
+    initial: "",
+    ...props,
+    ref,
+  });
+});

package/DS1/react/badge.ts

@@ -0,0 +1,7 @@
+import { createElement, forwardRef, type HTMLAttributes } from "react";
+import type { Badge as BadgeElement } from "../2-core/ds-badge";
+
+export type BadgeProps = HTMLAttributes<BadgeElement> & { icon?: string; iconOnly?: boolean };
+export const Badge = forwardRef<BadgeElement, BadgeProps>(function Badge(props, ref) {
+  return createElement("ds-badge", {...props, ref});
+});

package/DS1/react/button.ts

@@ -0,0 +1,63 @@
+/** Native semantics and React events; the shared Lit element owns the face. */
+import { createElement, forwardRef, type AnchorHTMLAttributes, type ButtonHTMLAttributes } from "react";
+import type { Button as ButtonElement } from "../2-core/ds-button";
+
+export type ButtonProps = ButtonHTMLAttributes<HTMLButtonElement> &
+  Partial<Pick<ButtonElement, "primary" | "secondary" | "active" | "choice" | "icon" | "wide" | "fit" | "danger" | "menuItem">>;
+
+export const Button = forwardRef<HTMLButtonElement, ButtonProps>(function Button(
+  {
+    children,
+    className,
+    style,
+    primary,
+    secondary,
+    active,
+    choice,
+    icon,
+    wide,
+    fit,
+    danger,
+    menuItem,
+    disabled,
+    hidden,
+    type = "button",
+    ...props
+  },
+  ref,
+) {
+  return createElement(
+    "ds-button",
+    {
+      control: "slotted",
+      primary,
+      secondary,
+      active,
+      choice,
+      icon,
+      wide,
+      fit,
+      danger,
+      menuItem,
+      disabled,
+      hidden,
+      className,
+      style,
+    },
+    createElement("button", { ...props, ref, type, disabled, hidden }, children),
+  );
+});
+
+/** A real link: browser navigation, context menus and modifier clicks survive. */
+export type ButtonLinkProps = AnchorHTMLAttributes<HTMLAnchorElement> &
+  Partial<Pick<ButtonElement, "primary" | "secondary" | "active" | "choice" | "icon" | "wide" | "fit" | "danger" | "menuItem">> & {disabled?: boolean};
+export const ButtonLink = forwardRef<HTMLAnchorElement, ButtonLinkProps>(function ButtonLink(
+  {children, className, style, primary, secondary, active, choice, icon, wide, fit, danger, menuItem, disabled, hidden, href, onClick, onAuxClick, tabIndex, ...props}, ref,
+) {
+  return createElement("ds-button", {control: "slotted", primary, secondary, active, choice, icon, wide, fit, danger, menuItem, disabled, hidden, className, style},
+    createElement("a", {...props, ref, href: disabled ? undefined : href, hidden,
+      "aria-disabled": disabled || undefined, tabIndex: disabled ? -1 : tabIndex,
+      onClick: event => { if (disabled) { event.preventDefault(); event.stopPropagation(); } else onClick?.(event); },
+      onAuxClick: event => { if (disabled) { event.preventDefault(); event.stopPropagation(); } else onAuxClick?.(event); },
+    }, children));
+});

package/DS1/react/choice.ts

@@ -0,0 +1,64 @@
+/** Native controls retain labels, forms and events. Shared Lit elements own their faces. */
+import { createElement, forwardRef, useCallback, type ButtonHTMLAttributes, type InputHTMLAttributes, type SelectHTMLAttributes, type MouseEvent, type ReactNode } from "react";
+
+export type ColorInputProps = Omit<InputHTMLAttributes<HTMLInputElement>, "type">;
+export const ColorInput = forwardRef<HTMLInputElement, ColorInputProps>(function ColorInput(
+  { className, style, hidden, ...props }, ref,
+) {
+  return createElement("ds-color", { className, style, hidden }, createElement("input", { ...props, type: "color", hidden, ref }));
+});
+
+export type SelectProps = SelectHTMLAttributes<HTMLSelectElement> & {
+  fit?: boolean;
+  chip?: boolean;
+  primary?: boolean;
+  swatch?: string;
+};
+export const Select = forwardRef<HTMLSelectElement, SelectProps>(function Select(
+  { className, style, hidden, children, fit, chip, primary, swatch, ...props }, ref,
+) {
+  return createElement("ds-select", { className, style, hidden, fit: fit ? "" : undefined, chip: chip ? "" : undefined, primary: primary ? "" : undefined, swatch }, createElement("select", { ...props, hidden, ref }, children));
+});
+
+export type CheckboxProps = Omit<InputHTMLAttributes<HTMLInputElement>, "type"> & { indeterminate?: boolean };
+export const Checkbox = forwardRef<HTMLInputElement, CheckboxProps>(function Checkbox(
+  { className, style, hidden, indeterminate = false, ...props }, ref,
+) {
+  const controlRef = useCallback((input: HTMLInputElement | null) => {
+    if (input) input.indeterminate = indeterminate;
+    if (typeof ref === "function") return ref(input);
+    if (ref) ref.current = input;
+  }, [ref, indeterminate]);
+  return createElement("ds-checkbox", { className, style, hidden }, createElement("input", { ...props, type: "checkbox", hidden, ref: controlRef }));
+});
+
+export type RadioProps = Omit<InputHTMLAttributes<HTMLInputElement>, "type" | "children"> & {
+  choice?: boolean;
+  compact?: boolean;
+  label?: string;
+  preview?: ReactNode;
+};
+export const Radio = forwardRef<HTMLInputElement, RadioProps>(function Radio(
+  { className, style, hidden, choice, compact, label, preview, ...props }, ref,
+) {
+  return createElement("ds-radio", { className, style, hidden, label, choice: Boolean(choice), compact: Boolean(compact), preview: preview != null },
+    createElement("input", { ...props, "aria-label": props["aria-label"] ?? label, type: "radio", hidden, ref }),
+    preview != null ? createElement("span", { slot: "preview", "aria-hidden": true }, preview) : null,
+  );
+});
+
+export type SwitchProps = Omit<ButtonHTMLAttributes<HTMLButtonElement>, "children" | "role" | "aria-checked" | "onChange" | "type"> & {
+  checked: boolean;
+  onCheckedChange?: (checked: boolean, event: MouseEvent<HTMLButtonElement>) => void;
+};
+export const Switch = forwardRef<HTMLButtonElement, SwitchProps>(function Switch(
+  { checked, onCheckedChange, onClick, className, style, hidden, ...props }, ref,
+) {
+  return createElement("ds-switch", { className, style, hidden }, createElement("button", {
+    ...props, ref, hidden, type: "button", role: "switch", "aria-checked": checked,
+    onClick: (event: MouseEvent<HTMLButtonElement>) => {
+      onClick?.(event);
+      if (!event.defaultPrevented) onCheckedChange?.(!checked, event);
+    },
+  }));
+});

package/DS1/react/composer.ts

@@ -0,0 +1,18 @@
+import { createElement, forwardRef, useEffect, useLayoutEffect, useRef, type TextareaHTMLAttributes } from "react";
+import type { Composer as ComposerElement, TextHighlight } from "../2-core/ds-composer";
+export type { TextHighlight };
+export type ComposerProps = TextareaHTMLAttributes<HTMLTextAreaElement> & {
+  highlights?: TextHighlight[];
+  autoGrow?: boolean;
+  maxRows?: number;
+  variant?: "field" | "plain";
+};
+const useCommitEffect = typeof window === "undefined" ? useEffect : useLayoutEffect;
+/** Native React values, events, refs and forms; DS1 owns the entire visual. */
+export const Composer = forwardRef<HTMLTextAreaElement, ComposerProps>(function Composer(
+  { highlights = [], autoGrow, maxRows = 12, variant = "field", className, style, ...props }, ref,
+) {
+  const host = useRef<ComposerElement>(null);
+  useCommitEffect(() => { host.current?.refresh(); });
+  return createElement("ds-composer", { ref: host, highlights, "auto-grow": autoGrow, "max-rows": maxRows, variant, className, style }, createElement("textarea", { ...props, ref }));
+});

package/DS1/react/context-menu.ts

@@ -0,0 +1,167 @@
+/** React state and native events for the shared Lit menu. No positioning or gesture code. */
+import {
+  Children, cloneElement, createContext, createElement as h, forwardRef,
+  useCallback, useContext, useEffect, useId, useLayoutEffect, useRef, useState,
+  type CSSProperties, type HTMLAttributes, type ReactElement, type ReactNode, type Ref,
+} from "react";
+import { Menu, type MenuProps } from "./menu";
+import { Button, type ButtonProps } from "./button";
+import { FilePicker, type FilePickerProps } from "./file-picker";
+import type { Menu as MenuElement, MenuCloseReason } from "../3-unit/ds-menu";
+
+const useCommitEffect = typeof window === "undefined" ? useEffect : useLayoutEffect;
+type State = {
+  open: boolean;
+  change: (open: boolean, reason?: MenuCloseReason | "trigger") => void;
+  trigger: HTMLElement | null;
+  setTrigger: (element: HTMLElement | null) => void;
+  menu: { current: MenuElement | null };
+  id: string;
+  nested: boolean;
+};
+const Context = createContext<State | null>(null);
+const useMenu = () => {
+  const state = useContext(Context);
+  if (!state) throw new Error("Menu controls must be inside ContextMenu or ContextMenuSub.");
+  return state;
+};
+export interface ContextMenuProps {
+  children?: ReactNode;
+  open?: boolean;
+  defaultOpen?: boolean;
+  onOpenChange?: (open: boolean) => void;
+}
+function Scope({ children, open, defaultOpen = false, onOpenChange, nested = false }: ContextMenuProps & { nested?: boolean }) {
+  const [internal, setInternal] = useState(defaultOpen);
+  const [trigger, setTrigger] = useState<HTMLElement | null>(null);
+  const menu = useRef<MenuElement>(null), id = useId();
+  return h(Context.Provider, { value: {
+    open: open ?? internal, trigger, setTrigger, menu, id, nested,
+    change: next => { if (open === undefined) setInternal(next); onOpenChange?.(next); },
+  } }, children);
+}
+export function ContextMenu(props: ContextMenuProps) { return h(Scope, props); }
+export function ContextMenuSub(props: ContextMenuProps) { return h(Scope, { ...props, nested: true }); }
+
+function setRef<T>(ref: Ref<T> | undefined, value: T | null) {
+  if (typeof ref === "function") ref(value); else if (ref) ref.current = value;
+}
+export type ContextMenuTriggerProps = HTMLAttributes<HTMLElement> & { asChild?: boolean; disabled?: boolean };
+export const ContextMenuTrigger = forwardRef<HTMLElement, ContextMenuTriggerProps>(function ContextMenuTrigger(
+  { asChild, disabled = false, children, ...props }, ref,
+) {
+  const state = useMenu();
+  const child = asChild ? Children.only(children) as ReactElement<HTMLAttributes<HTMLElement> & { ref?: Ref<HTMLElement> }> : null;
+  const childRef = child?.props.ref;
+  const bind = useCallback((element: HTMLElement | null) => {
+    setRef(ref, element); setRef(childRef, element);
+    state.setTrigger(disabled ? null : element);
+  }, [ref, childRef, state.setTrigger, disabled]);
+  const attributes = { ...props, ref: bind, "data-state": state.open ? "open" : "closed", "data-slot": "context-menu-trigger" };
+  if (child) {
+    // The child keeps its product handlers. A supplied trigger handler runs
+    // afterwards, unless the child deliberately consumed the event.
+    const merged: Record<string, unknown> = { ...child.props, ...attributes };
+    for (const [key, value] of Object.entries(props)) {
+      const first = (child.props as Record<string, unknown>)[key];
+      if (/^on[A-Z]/.test(key) && typeof first === "function" && typeof value === "function") {
+        merged[key] = (event: { defaultPrevented: boolean }) => { first(event); if (!event.defaultPrevented) value(event); };
+      }
+    }
+    return cloneElement(child, merged);
+  }
+  return h("span", { ...attributes, tabIndex: disabled ? -1 : 0 }, children);
+});
+
+export type ContextMenuContentProps = Omit<MenuProps, "open" | "trigger" | "anchor" | "triggerMode" | "onOpenChange">;
+export const ContextMenuContent = forwardRef<MenuElement, ContextMenuContentProps>(function ContextMenuContent(
+  { children, placement, ...props }, ref,
+) {
+  const state = useMenu();
+  useCommitEffect(() => { state.menu.current?.renderNow(); });
+  // Render the closed host so the source can continue listening to its trigger.
+  // Open descendants unmount together, including nested menu state.
+  return h(Menu, { ...props, id: props.id ?? state.id, role: "menu", hidden: !state.open,
+    "data-slot": state.nested ? "context-menu-sub-content" : "context-menu-content",
+    open: state.open, trigger: state.trigger, anchor: state.trigger,
+    triggerMode: state.nested ? "submenu" : "context", placement: placement ?? (state.nested ? "right" : "bottom"),
+    ref: (element: MenuElement | null) => { state.menu.current = element; setRef(ref, element); },
+    onOpenChange: state.change,
+  } as MenuProps, state.open ? children : null);
+});
+export const ContextMenuSubContent = ContextMenuContent;
+
+export type ContextMenuItemProps = Omit<ButtonProps, "onSelect"> & {
+  inset?: boolean;
+  variant?: "default" | "destructive";
+  textValue?: string;
+  onSelect?: (event: Event) => void;
+};
+export const ContextMenuItem = forwardRef<HTMLButtonElement, ContextMenuItemProps>(function ContextMenuItem(
+  { inset, variant, textValue, onClick, onSelect, children, style, ...props }, ref,
+) {
+  const state = useMenu();
+  return h(Button, { ...props, ref, menuItem: true, danger: variant === "destructive" || props.danger,
+    role: props.role ?? "menuitem", "data-text-value": textValue,
+    style: { ...style, ...(inset ? { "--ds-button-padding": "0 calc(4px * var(--ds-sf)) 0 var(--ds-unit)" } : {}) } as CSSProperties,
+    onClick: event => {
+      if (props.disabled) return;
+      onClick?.(event);
+      if (event.defaultPrevented) return;
+      const select = new Event("ds-menu-select", { cancelable: true });
+      onSelect?.(select);
+      if (!select.defaultPrevented) state.menu.current?.select();
+    },
+  } as ButtonProps, children);
+});
+
+const indicatorStyle: CSSProperties = { display: "inline-flex", flex: "0 0 var(--ds-unit)", alignItems: "center" };
+function mark(checked: boolean | "indeterminate") {
+  return h("span", { "aria-hidden": true, style: indicatorStyle }, checked ? h("ds-icon", { type: checked === "indeterminate" ? "minus" : "check" }) : null);
+}
+export const ContextMenuCheckboxItem = forwardRef<HTMLButtonElement, ContextMenuItemProps & {
+  checked?: boolean | "indeterminate"; onCheckedChange?: (checked: boolean) => void;
+}>(function ContextMenuCheckboxItem({ checked = false, onCheckedChange, onSelect, children, ...props }, ref) {
+  return h(ContextMenuItem, { ...props, ref, role: "menuitemcheckbox", "aria-checked": checked === "indeterminate" ? "mixed" : checked,
+    onSelect: event => { onSelect?.(event); if (!event.defaultPrevented) onCheckedChange?.(checked !== true); },
+  }, mark(checked), children);
+});
+const Radio = createContext<{ value?: string; change?: (value: string) => void }>({});
+export function ContextMenuRadioGroup({ value, onValueChange, children, ...props }: HTMLAttributes<HTMLDivElement> & { value?: string; onValueChange?: (value: string) => void }) {
+  return h(Radio.Provider, { value: { value, change: onValueChange } }, h(ContextMenuGroup, props, children));
+}
+export const ContextMenuRadioItem = forwardRef<HTMLButtonElement, ContextMenuItemProps & { value: string }>(function ContextMenuRadioItem(
+  { value, onSelect, children, ...props }, ref,
+) {
+  const radio = useContext(Radio), checked = radio.value === value;
+  return h(ContextMenuItem, { ...props, ref, role: "menuitemradio", "aria-checked": checked,
+    onSelect: event => { onSelect?.(event); if (!event.defaultPrevented) radio.change?.(value); },
+  }, mark(checked), children);
+});
+export const ContextMenuSubTrigger = forwardRef<HTMLButtonElement, ContextMenuItemProps>(function ContextMenuSubTrigger(
+  { children, inset, variant, textValue, onSelect: _onSelect, ...props }, ref,
+) {
+  const state = useMenu();
+  const bind = useCallback((element: HTMLButtonElement | null) => { state.setTrigger(element); setRef(ref, element); }, [ref, state.setTrigger]);
+  return h(Button, { ...props, ref: bind, role: "menuitem", menuItem: true, active: state.open,
+    danger: variant === "destructive", "data-text-value": textValue,
+    "data-state": state.open ? "open" : "closed",
+  } as ButtonProps, inset ? mark(false) : null, children,
+  h("ds-icon", { type: "right", "aria-hidden": true, style: { marginInlineStart: "auto", flex: "none" } }));
+});
+export function ContextMenuFilePicker({ onFiles, ...props }: Omit<FilePickerProps, "onChange"> & { onFiles: (files: File[]) => void }) {
+  return h(FilePicker, { ...props, role: "menuitem", onChange: event => {
+    const files = Array.from(event.currentTarget.files ?? []); event.currentTarget.value = "";
+    if (!props.disabled && files.length) onFiles(files);
+  } });
+}
+export function ContextMenuGroup(props: HTMLAttributes<HTMLDivElement>): ReactElement {
+  return h("div", { ...props, role: "group", style: { ...props.style, display: "contents" } });
+}
+export function ContextMenuLabel({ inset, children, ...props }: HTMLAttributes<HTMLElement> & { inset?: boolean }) {
+  return h("ds-text", { ...props, literal: true, tone: "muted", "data-ds-menu-label": "" }, inset ? mark(false) : null, children);
+}
+export function ContextMenuSeparator(props: HTMLAttributes<HTMLHRElement>) { return h("hr", { ...props, "data-ds-menu-separator": "" }); }
+export function ContextMenuShortcut(props: HTMLAttributes<HTMLSpanElement>): ReactElement {
+  return h("span", { ...props, style: { marginInlineStart: "auto", color: "var(--ds-text-color-muted)", ...props.style } });
+}

package/DS1/react/dialog.ts

@@ -0,0 +1,102 @@
+/** 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 { createPortal } from "react-dom";
+import type { Dialog as DialogElement, DialogCloseReason } from "../4-page/ds-dialog";
+
+const DialogContext = createContext<{ open: boolean; change: (open: boolean, reason?: DialogCloseReason) => void; title: string; description: string } | null>(null);
+const useDialog = () => {
+  const context = useContext(DialogContext);
+  if (!context) throw new Error("Dialog content must be inside Dialog.");
+  return context;
+};
+
+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();
+  return createElement(DialogContext.Provider, { value: {
+    open: open ?? internal, title: `${id}-title`, description: `${id}-description`,
+    change: (next, reason) => { if (open === undefined) setInternal(next); onOpenChange?.(next, reason); },
+  } }, children);
+}
+
+export interface DialogContentProps extends HTMLAttributes<HTMLDialogElement> {
+  ref?: Ref<HTMLDialogElement>;
+  /** Keep floating panels within their product layout or containing modal. */
+  portal?: boolean;
+  nonModal?: boolean;
+  closeOnOutside?: boolean;
+  blockOutside?: boolean;
+  holdScroll?: boolean;
+  anchor?: { x: number; y: number } | null;
+  returnFocus?: (() => HTMLElement | null) | null;
+  closeLabel?: string;
+  showClose?: boolean;
+  closeOnEscape?: boolean;
+  closeOnBackdrop?: boolean;
+  /** Fill the viewport for document viewers; this is not the Fullscreen API. */
+  fullScreen?: boolean;
+  /** Content supplies its own internal spacing. The shared frame stays intact. */
+  flush?: boolean;
+  /** Rotate a document frame while keeping it within the viewport. */
+  rotated?: boolean;
+}
+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) {
+  const context = useDialog();
+  const host = useRef<DialogElement>(null);
+  const [mounted, setMounted] = useState(false);
+  // 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); }, []);
+  // Install the request handler before opening, and keep the app's decision authoritative.
+  useLayoutEffect(() => {
+    const element = host.current;
+    if (!element) return;
+    const close = (event: Event) => {
+      if (event.target !== element) return;
+      event.preventDefault();
+      context.change(false, (event as CustomEvent<{ reason: DialogCloseReason }>).detail.reason);
+    };
+    element.addEventListener("ds-close-request", close);
+    const native = element.querySelector("dialog")!;
+    if (!("aria-labelledby" in props) && !props["aria-label"]) {
+      const title = native.querySelector('[data-ds-dialog="title"]');
+      if (title) native.setAttribute("aria-labelledby", title.id);
+      else native.removeAttribute("aria-labelledby");
+    }
+    if (!("aria-describedby" in props)) {
+      const description = native.querySelector('[data-ds-dialog="description"]');
+      if (description) native.setAttribute("aria-describedby", description.id);
+      else native.removeAttribute("aria-describedby");
+    }
+    element.closeOnEscape = closeOnEscape;
+    element.closeOnBackdrop = closeOnBackdrop;
+    element.nonModal = nonModal;
+    element.closeOnOutside = closeOnOutside;
+    element.blockOutside = blockOutside;
+    element.holdScroll = holdScroll;
+    element.anchor = anchor;
+    element.returnFocus = returnFocus;
+    element.open = context.open;
+    return () => element.removeEventListener("ds-close-request", close);
+  });
+  if (!mounted || !context.open) 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" },
+        createElement("button", { type: "button", "aria-label": closeLabel, "data-ds-dialog-dismiss": "" },
+          createElement("ds-icon", { type: "close", "aria-hidden": true }))),
+    ));
+  return portal ? createPortal(content, document.body) : content;
+}
+
+export function DialogHeader(props: HTMLAttributes<HTMLDivElement>) { return createElement("div", { ...props, "data-ds-dialog": "header" }); }
+export function DialogFooter(props: HTMLAttributes<HTMLDivElement>) { return createElement("div", { ...props, "data-ds-dialog": "footer" }); }
+export function DialogTitle(props: HTMLAttributes<HTMLHeadingElement>) {
+  const context = useDialog();
+  return createElement("h2", { id: context.title, ...props, "data-ds-dialog": "title" });
+}
+export function DialogDescription(props: HTMLAttributes<HTMLParagraphElement>) {
+  const context = useDialog();
+  return createElement("p", { id: context.description, ...props, "data-ds-dialog": "description" });
+}