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

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

@@ -0,0 +1,214 @@
+@import "../../1-root/component-metrics.css";
+
+/* ds-page.css
+ * Five areas, six arrangements. Every width is whole squares; areas are
+ * separated by one square down the page and two across. An empty area takes
+ * no room, so its margin goes with it.
+ */
+
+:host {
+  --ds-page-nav: calc(12 * var(--ds-unit));
+  --ds-page-aside: calc(12 * var(--ds-unit));
+  --ds-page-measure: calc(32 * var(--ds-unit));
+  --ds-page-tile: calc(12 * var(--ds-unit));
+  --ds-page-gap: calc(2 * var(--ds-unit));
+  --ds-page-line: var(--ds-border-color, var(--ds-slate-light));
+  /* How far the content stands outside its column on each side, the column's place and the
+     grid's lines kept: a phone's lists take a little more width, their words a longer line
+     (Money sets 4px). Zero by default. */
+  --ds-page-bleed: 0px;
+  box-sizing: border-box;
+  display: block;
+  container-type: inline-size;
+  min-width: 0;
+  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);
+}
+
+:host([hidden]) { display: none; }
+:host([fill]) { height: 100%; }
+
+.page {
+  box-sizing: border-box;
+  display: grid;
+  column-gap: var(--ds-page-gap);
+  grid-template-columns: var(--ds-page-nav) minmax(0, 1fr);
+  grid-template-rows: auto minmax(0, 1fr) auto auto;
+  grid-template-areas:
+    "nav header"
+    "nav main"
+    "nav aside"
+    "nav footer";
+  min-height: 100%;
+  padding: var(--ds-unit) calc(var(--ds-unit) - var(--ds-page-bleed));
+}
+
+:host([fill]) .page { height: 100%; }
+
+.area { position: relative; min-width: 0; }
+/* The drawer's menu button: shown only on a narrow page with `drawer`. */
+.bar { display: none; grid-area: bar; }
+.bar[hidden] { display: none !important; }
+.area[data-empty] { display: none; }
+.nav { grid-area: nav; }
+.header { grid-area: header; margin-block-end: var(--ds-unit); }
+.main { grid-area: main; }
+.aside { grid-area: aside; margin-block-start: var(--ds-unit); }
+.footer { grid-area: footer; margin-block-start: var(--ds-unit); }
+
+:host([fill]) :is(.nav, .main, .aside) { min-height: 0; overflow: auto; }
+
+/* List and detail: a wider leading column holds the list. */
+:host([layout="split"]) { --ds-page-nav: calc(16 * var(--ds-unit)); }
+
+/* Inspector: navigation, the work, and its properties beside it. */
+:host([layout="inspector"]) .page {
+  grid-template-columns: var(--ds-page-nav) minmax(0, 1fr) var(--ds-page-aside);
+  grid-template-rows: auto minmax(0, 1fr) auto;
+  grid-template-areas:
+    "nav header aside"
+    "nav main aside"
+    "nav footer aside";
+}
+:host([layout="inspector"]) .aside { margin-block-start: 0; }
+
+/* One column down the middle; centred is narrower and sits in the middle of
+ * the height it is given. Tiles fill the width with 12-square tiles.
+ *
+ * A centred column stands on a whole square. The room beside it is shared out
+ * and rounded down to squares, then added to the page's own square of padding,
+ * so when the room is an odd number of squares the extra one falls on the
+ * trailing side instead of leaving the column on a half. 100% is the width of
+ * the element; with less room than the measure needs, the padding stays one
+ * square and the column takes what is left. */
+:host(:is([layout="column"], [layout="centered"], [layout="tiles"])) .page {
+  grid-template-columns: minmax(0, calc(var(--ds-page-measure) + 2 * var(--ds-page-bleed)));
+  grid-template-rows: auto auto minmax(0, 1fr) auto auto;
+  grid-template-areas: "header" "nav" "main" "aside" "footer";
+}
+:host(:is([layout="column"], [layout="centered"])) .page {
+  justify-content: start;
+  padding-inline-start: calc(var(--ds-unit) + max(0px, round(down, calc((100% - 2 * var(--ds-unit) - var(--ds-page-measure)) / 2), var(--ds-unit))) - var(--ds-page-bleed));
+}
+:host(:is([layout="column"], [layout="centered"], [layout="tiles"])) .nav { margin-block-end: var(--ds-unit); }
+
+:host([layout="centered"]) { --ds-page-measure: calc(16 * var(--ds-unit)); }
+:host([layout="centered"]) .page { grid-template-rows: auto; align-content: center; }
+
+:host([layout="tiles"]) .page { grid-template-columns: minmax(0, 1fr); }
+:host([layout="tiles"]) .main {
+  display: grid;
+  grid-template-columns: repeat(auto-fill, var(--ds-page-tile));
+  grid-auto-rows: auto;
+  gap: var(--ds-unit);
+  align-items: start;
+  align-content: start;
+}
+:host([layout="tiles"]) .main ::slotted(*) { min-width: 0; }
+:host([layout="tiles"]) .main ::slotted([data-tile="wide"]) { grid-column: span 2; }
+:host([layout="tiles"]) .main ::slotted([data-tile="full"]) { grid-column: 1 / -1; }
+
+/* Hairlines between columns, on the grid line in the middle of the gap. The
+ * column reaches across half the gap to draw it, so its content keeps its
+ * whole width. */
+:host([divided]:not([layout="column"]):not([layout="centered"]):not([layout="tiles"])) .nav {
+  border-inline-end: 1px solid var(--ds-page-line);
+  padding-inline-end: calc(var(--ds-page-gap) / 2 - 1px);
+  margin-inline-end: calc(var(--ds-page-gap) / -2);
+}
+:host([divided][layout="inspector"]) .aside {
+  border-inline-start: 1px solid var(--ds-page-line);
+  padding-inline-start: calc(var(--ds-page-gap) / 2 - 1px);
+  margin-inline-start: calc(var(--ds-page-gap) / -2);
+}
+
+/* Narrower than navigation, the work and its properties: properties go below. */
+@container (max-width: 959px) {
+  :host([layout="inspector"]) .page {
+    grid-template-columns: var(--ds-page-nav) minmax(0, 1fr);
+    grid-template-rows: auto minmax(0, 1fr) auto auto;
+    grid-template-areas:
+      "nav header"
+      "nav main"
+      "nav aside"
+      "nav footer";
+  }
+  :host([layout="inspector"]) .aside { margin-block-start: var(--ds-unit); }
+  :host([divided][layout="inspector"]) .aside { border-inline-start: 0; padding-inline-start: 0; margin-inline-start: 0; }
+}
+
+/* Phone width: every layout is one column, navigation first. */
+@container (max-width: 599px) {
+  .page,
+  :host([layout="inspector"]) .page {
+    grid-template-columns: minmax(0, 1fr);
+    grid-template-rows: auto;
+    grid-template-areas: "nav" "header" "main" "aside" "footer";
+    column-gap: 0;
+    align-content: start;
+  }
+  .nav { margin-block-end: var(--ds-unit); }
+  :host([divided]:not([layout="column"]):not([layout="centered"]):not([layout="tiles"])) .nav {
+    border-inline-end: 0;
+    padding-inline-end: 0;
+    margin-inline-end: 0;
+    border-block-end: 1px solid var(--ds-page-line);
+    padding-block-end: calc(var(--ds-unit) - 1px);
+  }
+  :host([fill]) :is(.nav, .main, .aside) { overflow: visible; }
+  :host([fill]) .page { height: auto; }
+  :host([layout="tiles"]) .main { display: flex; flex-direction: column; align-items: stretch; }
+}
+
+/* Phone width with a drawer: the navigation folds away and the menu button
+ * stands in a one-square column before the header. In the drawer the
+ * navigation takes the panel's width, with none of the page's margins. */
+@container (max-width: 599px) {
+  :host([drawer]) .page,
+  :host([drawer][layout="inspector"]) .page {
+    grid-template-columns: var(--ds-unit) minmax(0, 1fr);
+    column-gap: var(--ds-unit);
+    grid-template-areas: "bar header" "main main" "aside aside" "footer footer";
+  }
+  :host([drawer]) .bar {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    height: var(--ds-unit);
+    margin-block-end: var(--ds-unit);
+  }
+  :host([drawer]) .page > .nav { display: none; }
+}
+/* Important, as the layouts' own margins and hairlines for the navigation
+ * reach it by more specific selectors. */
+.ds-drawer > .nav {
+  margin: 0 !important;
+  padding: 0 !important;
+  border: 0 !important;
+  overflow: visible !important;
+}
+
+/* Inspection: each area outlined and named by its slot, in the corner its
+ * content is least likely to use. */
+:host([view]) .area:not([data-empty]) {
+  outline: 1px dashed color-mix(in srgb, var(--ds-pink) 80%, var(--ds-text-color));
+  outline-offset: -1px;
+}
+:host([view]) .area:not([data-empty])::before {
+  content: attr(data-area);
+  position: absolute;
+  z-index: 1;
+  inset-block-end: 0;
+  inset-inline-end: 0;
+  height: var(--ds-unit);
+  padding-inline: calc(4px * var(--ds-sf));
+  font-size: var(--ds-type-size-small);
+  line-height: var(--ds-unit);
+  color: var(--ds-black);
+  background: var(--ds-pink);
+  pointer-events: none;
+}

package/DS1/components.ts

@@ -2,7 +2,6 @@
 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";
@@ -11,3 +10,10 @@ export * from "./3-unit/ds-list";
 export * from "./3-unit/ds-menu";
 export * from "./3-unit/ds-tabs";
 export * from "./4-page/ds-panel";
+export * from "./4-page/ds-page";
+
+export * from "./3-unit/ds-sidebar";
+
+export * from "./4-page/ds-grid";
+
+export * from "./2-core/ds-chart";

package/DS1/index.ts

@@ -26,35 +26,39 @@ 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/format";
 export * from "./0-face/preferences";
 export * from "./0-face/pricing";
 export * from "./0-face/theme";
+export * from "./0-face/keys";
+export * from "./0-face/sidebar";
 
 // ============================================================================
 // 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-empty";
 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-message";
+export * from "./2-core/ds-notice";
+export * from "./2-core/ds-stat";
+export * from "./2-core/ds-progress";
 export * from "./2-core/ds-text";
+export * from "./2-core/ds-toast";
 export * from "./2-core/ds-tooltip";
 
 // ============================================================================
@@ -64,8 +68,13 @@ export * from "./2-core/ds-tooltip";
 export * from "./3-unit/ds-accordion";
 export * from "./2-core/ds-avatar";
 export * from "./3-unit/ds-avatar-group";
+export * from "./3-unit/ds-calendar";
+export * from "./3-unit/ds-calendar-large";
+export * from "./3-unit/ds-carousel";
+export * from "./3-unit/ds-date-picker";
 export * from "./3-unit/ds-form";
 export * from "./3-unit/ds-list";
+export * from "./3-unit/ds-matrix";
 export * from "./3-unit/ds-row";
 export * from "./3-unit/ds-table";
 
@@ -75,7 +84,10 @@ export * from "./3-unit/ds-table";
 
 export * from "./4-page/ds-container";
 export * from "./4-page/ds-grid";
-export * from "./4-page/ds-layout";
+export * from "./4-page/ds-page";
+export * from "./4-page/ds-header";
+export * from "./4-page/ds-footer";
+export * from "./4-page/ds-document";
 
 export * from "./3-unit/ds-menu";
 export * from "./3-unit/ds-tabs";
@@ -84,3 +96,9 @@ export * from "./4-page/ds-dialog";
 
 export * from "./2-core/ds-token";
 export * from "./3-unit/ds-token-field";
+
+export * from "./3-unit/ds-sidebar";
+
+export * from "./2-core/ds-chart";
+
+export * from "./0-face/component-visibility";

package/DS1/react/avatar.ts

@@ -17,6 +17,7 @@ export type AvatarProps = Omit<HTMLAttributes<AvatarElement>, "children"> &
       | "pending"
       | "plain"
       | "color"
+      | "ink"
     >
   >;
 /** Browser-only registration stays in the product's runtime entry for SSR. */
@@ -24,14 +25,12 @@ export const Avatar = forwardRef<AvatarElement, AvatarProps>(function Avatar(pro
   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 type LogoProps = Omit<AvatarProps, "size" | "fit" | "mask" | "plain" | "shape">;
+/** A monochrome brand mark fitted into the page's image area; without `src`, its `initial`. */
 export const Logo = forwardRef<AvatarElement, LogoProps>(function Logo(props, ref) {
   return createElement("ds-avatar", {
     size: "fill",
-    shape: "square",
+    logo: true,
     fit: "contain",
     mask: true,
     plain: true,

package/DS1/react/button-split.ts

@@ -0,0 +1,29 @@
+/** Controlled state for Button's split mode. The shared Button owns its face. */
+import { createElement, useEffect, useLayoutEffect, useRef, type CSSProperties, type ReactNode, type Ref } from "react";
+import type { Button as ButtonElement, SplitSegment } from "../2-core/ds-button";
+export type { SplitSegment };
+const useCommitEffect = typeof window === "undefined" ? useEffect : useLayoutEffect;
+export interface SplitButtonProps<T extends string> {
+  split: true; segments: ReadonlyArray<SplitSegment<T>>; value?: T;
+  onPress: (value: T) => void; label: string; className?: string; style?: CSSProperties;
+  disabled?: boolean; compact?: boolean;
+}
+export function SplitButton<T extends string>({ segments, value, onPress, label, className, style, disabled = false, compact = false, forwardedRef }: SplitButtonProps<T> & { forwardedRef?: Ref<ButtonElement> }): ReactNode {
+  const ref = useRef<ButtonElement | null>(null);
+  useCommitEffect(() => {
+    const element = ref.current; if (!element) return;
+    element.split = true; element.segments = segments; element.value = value ?? "";
+    element.actions = value === undefined; element.disabled = disabled; element.compact = compact; element.literal = true;
+    const press = (event: Event) => {
+      if (event.target !== element) return;
+      if (event.type === "change") event.preventDefault();
+      onPress((event as CustomEvent<{ value: T }>).detail.value);
+    };
+    element.addEventListener("change", press); element.addEventListener("press", press);
+    return () => { element.removeEventListener("change", press); element.removeEventListener("press", press); };
+  });
+  return createElement("ds-button", { ref: (element: ButtonElement | null) => {
+    ref.current = element;
+    if (typeof forwardedRef === "function") forwardedRef(element); else if (forwardedRef) forwardedRef.current = element;
+  }, split: true, "aria-label": label, className, style });
+}

package/DS1/react/button.ts

@@ -1,12 +1,17 @@
 /** Native semantics and React events; the shared Lit element owns the face. */
-import { createElement, forwardRef, type AnchorHTMLAttributes, type ButtonHTMLAttributes } from "react";
+import { createElement, forwardRef, type AnchorHTMLAttributes, type ReactElement, type RefAttributes, type Ref, type ButtonHTMLAttributes } from "react";
+import { SplitButton, type SplitButtonProps } from "./button-split";
+export type { SplitButtonProps, SplitSegment } from "./button-split";
 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">>;
+  Partial<Pick<ButtonElement, "primary" | "secondary" | "active" | "choice" | "icon" | "wide" | "fixed" | "fit" | "danger" | "menuItem">>;
 
-export const Button = forwardRef<HTMLButtonElement, ButtonProps>(function Button(
-  {
+const ButtonControl = forwardRef<HTMLButtonElement, ButtonProps | SplitButtonProps<string>>(function Button(
+  props, ref,
+) {
+  if ("split" in props && props.split) return createElement(SplitButton, { ...props, forwardedRef: ref as unknown as Ref<ButtonElement> });
+  const {
     children,
     className,
     style,
@@ -16,16 +21,15 @@ export const Button = forwardRef<HTMLButtonElement, ButtonProps>(function Button
     choice,
     icon,
     wide,
+    fixed,
     fit,
     danger,
     menuItem,
     disabled,
     hidden,
     type = "button",
-    ...props
-  },
-  ref,
-) {
+    ...nativeProps
+  } = props as ButtonProps;
   return createElement(
     "ds-button",
     {
@@ -36,6 +40,7 @@ export const Button = forwardRef<HTMLButtonElement, ButtonProps>(function Button
       choice,
       icon,
       wide,
+      fixed,
       fit,
       danger,
       menuItem,
@@ -44,18 +49,32 @@ export const Button = forwardRef<HTMLButtonElement, ButtonProps>(function Button
       className,
       style,
     },
-    createElement("button", { ...props, ref, type, disabled, hidden }, children),
+    createElement("button", { ...nativeProps, ref, type, disabled, hidden }, children),
   );
 });
 
-/** A real link: browser navigation, context menus and modifier clicks survive. */
+export const Button = ButtonControl as unknown as {
+  <const T extends string>(props: SplitButtonProps<T> & RefAttributes<ButtonElement>): ReactElement | null;
+  (props: ButtonProps & RefAttributes<HTMLButtonElement>): ReactElement | null;
+  displayName?: string;
+};
+
+/**
+ * A real link: browser navigation, context menus and modifier clicks survive.
+ * As `<ds-button href>`: `target="_blank"` gets `rel="noopener noreferrer"`
+ * unless `rel` is given, and a disabled link loses its `href` and `target`, is
+ * left out of the tab order and stays a link (`role="link"`, `aria-disabled`).
+ */
 export type ButtonLinkProps = AnchorHTMLAttributes<HTMLAnchorElement> &
-  Partial<Pick<ButtonElement, "primary" | "secondary" | "active" | "choice" | "icon" | "wide" | "fit" | "danger" | "menuItem">> & {disabled?: boolean};
+  Partial<Pick<ButtonElement, "primary" | "secondary" | "active" | "choice" | "icon" | "wide" | "fixed" | "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,
+  {children, className, style, primary, secondary, active, choice, icon, wide, fixed, fit, danger, menuItem, disabled, hidden, href, target, rel, role, onClick, onAuxClick, tabIndex, ...props}, ref,
 ) {
-  return createElement("ds-button", {control: "slotted", primary, secondary, active, choice, icon, wide, fit, danger, menuItem, disabled, hidden, className, style},
+  return createElement("ds-button", {control: "slotted", primary, secondary, active, choice, icon, wide, fixed, fit, danger, menuItem, disabled, hidden, className, style},
     createElement("a", {...props, ref, href: disabled ? undefined : href, hidden,
+      target: disabled ? undefined : target,
+      rel: disabled ? undefined : rel ?? (target === "_blank" ? "noopener noreferrer" : undefined),
+      role: role ?? (disabled ? "link" : undefined),
       "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); },

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));
+});