@ghxstship/xos-ui 0.0.0-stage → 4.16.0

package/src/Identity/BrandSlotFrame.tsx

@@ -0,0 +1,38 @@
+import { type CSSProperties, type ReactElement } from "react";
+import { Icon } from "../Icon/Icon.tsx";
+import { type BrandSlotProps } from "./Identity.types.ts";
+
+/**
+ * The drawing of a BrandSlot with its size line already written: no hooks and no context, so a
+ * server component can place a slot (ADR 0027). BrandSlot fills `sizeLabel` from the catalog.
+ */
+export function BrandSlotFrame({
+  label,
+  width,
+  height,
+  formats,
+  sizeLabel,
+}: BrandSlotProps & { sizeLabel: string }): ReactElement {
+  const scale = Math.min(1, 160 / width, 148 / height);
+  const frame: CSSProperties = {
+    inlineSize: `calc(var(--space-4) * ${Math.round(width * scale) / 4})`,
+    blockSize: `calc(var(--space-4) * ${Math.round(height * scale) / 4})`,
+  };
+  return (
+    <figure className="flex flex-col gap-6 m-0">
+      <div
+        aria-hidden="true"
+        style={frame}
+        className="flex flex-col items-center justify-center gap-4 min-w-(--space-64) min-h-(--space-48) box-border rounded-card border border-dashed border-border-strong text-text-tertiary text-text-11"
+      >
+        <Icon name="Image" size={20} />
+        <span className="tabular-nums">{sizeLabel}</span>
+      </div>
+      <figcaption className="flex flex-col text-text-12 text-text-secondary">
+        <strong className="font-medium text-text-primary">{label}</strong>
+        <span className="tabular-nums">{sizeLabel}</span>
+        <span>{formats}</span>
+      </figcaption>
+    </figure>
+  );
+}

package/src/Identity/CredentialBadge.tsx

@@ -0,0 +1,92 @@
+import { type ReactElement } from "react";
+import { cx } from "../lib/cx.ts";
+import { useT } from "../lib/context.tsx";
+import { Button, IconButton } from "../Button/Button.tsx";
+import { Avatar } from "../Avatar/Avatar.tsx";
+import { BrandMark } from "../BrandMark/BrandMark.tsx";
+import { chipClass } from "../Chips/Chips.tsx";
+import { type CredentialBadgeProps } from "./Identity.types.ts";
+import { QRCode } from "./QRCode.tsx";
+
+const CATEGORY: Record<CredentialBadgeProps["categoryColor"], string> = {
+  1: cx("border-t-viz-cat-1"),
+  2: cx("border-t-viz-cat-2"),
+  3: cx("border-t-viz-cat-3"),
+  4: cx("border-t-viz-cat-4"),
+  5: cx("border-t-viz-cat-5"),
+  6: cx("border-t-viz-cat-6"),
+  7: cx("border-t-viz-cat-7"),
+};
+
+/** The badge shown at access points: category band with its label, holder, offline QR code, zones and validity. */
+export function CredentialBadge({
+  org,
+  name,
+  role,
+  category,
+  categoryColor,
+  credentialKey,
+  payload,
+  zones,
+  validFrom,
+  validTo,
+  onWallet,
+  onBrightness,
+}: CredentialBadgeProps): ReactElement {
+  const t = useT();
+  return (
+    <article
+      aria-label={t("badge.label", { name })}
+      className="flex flex-col w-(--layout-property-column) max-w-full box-border overflow-hidden rounded-dialog border border-border-subtle bg-bg-raised"
+    >
+      <div
+        className={cx(
+          "px-16 py-6 border-t-stroke-stripe bg-bg-surface text-text-primary font-semibold text-text-13 tracking-wider uppercase",
+          CATEGORY[categoryColor],
+        )}
+      >
+        {category}
+      </div>
+      <div className="flex flex-col gap-12 p-16">
+        <div className="flex items-center justify-between gap-8">
+          <BrandMark name={org} size="sm" />
+          <span className="font-mono text-text-12 text-text-secondary">{credentialKey}</span>
+        </div>
+        <div className="flex items-center gap-12">
+          <Avatar name={name} size="lg" />
+          <div className="flex flex-col">
+            <strong className="text-heading-20 font-semibold">{name}</strong>
+            <span className="text-text-secondary">{role}</span>
+          </div>
+        </div>
+        <div className="flex justify-center p-8 rounded-card bg-paper">
+          <QRCode value={payload} label={t("badge.qr", { key: credentialKey })} size={168} />
+        </div>
+        <div className="flex flex-col gap-4">
+          <span className="text-text-12 font-medium text-text-secondary">{t("badge.zones")}</span>
+          <ul className="flex flex-wrap gap-4 m-0 p-0 list-none">
+            {zones.map((z) => (
+              <li key={z} className={chipClass}>
+                {z}
+              </li>
+            ))}
+          </ul>
+        </div>
+        <span className="text-text-secondary tabular-nums">
+          {t("badge.valid", { from: validFrom, to: validTo })}
+        </span>
+        <div className="flex items-center gap-8">
+          <Button icon="Wallet" className="flex-1" onClick={onWallet}>
+            {t("badge.wallet")}
+          </Button>
+          <IconButton
+            icon="SunMedium"
+            label={t("badge.brightness")}
+            variant="secondary"
+            onClick={onBrightness}
+          />
+        </div>
+      </div>
+    </article>
+  );
+}

package/src/Identity/Identity.tsx

@@ -0,0 +1,14 @@
+export {
+  type PresenceIndicatorProps,
+  type QRCodeProps,
+  type CredentialBadgeProps,
+  type BrandSlotProps,
+  type WhiteLabelPreviewProps,
+} from "./Identity.types.ts";
+export { PresenceIndicator } from "./PresenceIndicator.tsx";
+export { qrPath } from "./qrPath.tsx";
+export { QRCode } from "./QRCode.tsx";
+export { CredentialBadge } from "./CredentialBadge.tsx";
+export { BrandSlot } from "./BrandSlot.tsx";
+export { tokenVariable } from "./tokenVariable.tsx";
+export { WhiteLabelPreview } from "./WhiteLabelPreview.tsx";

package/src/Identity/Identity.types.ts

@@ -0,0 +1,25 @@
+import type {
+  BrandSlotProps as ReferenceBrandSlotProps,
+  CredentialBadgeProps as ReferenceCredentialBadgeProps,
+  PresenceIndicatorProps as ReferencePresenceIndicatorProps,
+  QRCodeProps as ReferenceQRCodeProps,
+  WhiteLabelPreviewProps as ReferenceWhiteLabelPreviewProps,
+} from "../types/reference";
+
+export type PresenceIndicatorProps = ReferencePresenceIndicatorProps;
+
+export type QRCodeProps = ReferenceQRCodeProps;
+
+export type CredentialBadgeProps = ReferenceCredentialBadgeProps & {
+  onWallet?: () => void;
+  onBrightness?: () => void;
+};
+
+export type BrandSlotProps = ReferenceBrandSlotProps;
+
+export type WhiteLabelPreviewProps = ReferenceWhiteLabelPreviewProps;
+
+export interface QRModules {
+  getModuleCount(): number;
+  isDark(row: number, col: number): boolean;
+}

package/src/Identity/PresenceIndicator.tsx

@@ -0,0 +1,37 @@
+import { type ReactElement } from "react";
+import { useFormat, useT } from "../lib/context.tsx";
+import { Avatar } from "../Avatar/Avatar.tsx";
+import { type PresenceIndicatorProps } from "./Identity.types.ts";
+
+/** Who is viewing or editing a record live; the count and names are announced together. */
+export function PresenceIndicator({
+  names,
+  verb = "viewing",
+}: PresenceIndicatorProps): ReactElement {
+  const t = useT();
+  const fmt = useFormat();
+  const summary = t(verb === "editing" ? "presence.editing" : "presence.viewing", {
+    n: names.length,
+  });
+  return (
+    <span
+      role="img"
+      aria-label={t(verb === "editing" ? "presence.namesEditing" : "presence.namesViewing", {
+        names: fmt.list(names),
+      })}
+      className="inline-flex items-center gap-8 text-text-12"
+    >
+      <span aria-hidden="true" className="inline-flex [&>*+*]:ms-(--ui-avatar-overlap)">
+        {names.slice(0, 3).map((name) => (
+          <span key={name} className="relative inline-flex">
+            <Avatar name={name} />
+            <span className="absolute -end-(--stroke-width-hairline) -bottom-(--stroke-width-hairline) size-(--space-8) rounded-full bg-success ring-(length:--stroke-width-focus) ring-bg-canvas" />
+          </span>
+        ))}
+      </span>
+      <span aria-hidden="true" className="text-text-secondary">
+        {summary}
+      </span>
+    </span>
+  );
+}

package/src/Identity/QRCode.tsx

@@ -0,0 +1,22 @@
+import { useMemo, type ReactElement } from "react";
+import { type QRCodeProps } from "./Identity.types.ts";
+import { qrPath } from "./qrPath.tsx";
+
+/** A scannable code as SVG, always dark on a light quiet zone so scanners read it in every theme. */
+export function QRCode({ value, label, size = 160 }: QRCodeProps): ReactElement {
+  const { size: modules, path } = useMemo(() => qrPath(value), [value]);
+  return (
+    <svg
+      role="img"
+      aria-label={label}
+      viewBox={`0 0 ${modules} ${modules}`}
+      width={size}
+      height={size}
+      shapeRendering="crispEdges"
+      className="block rounded-control"
+    >
+      <rect width={modules} height={modules} className="fill-paper" />
+      <path d={path} className="fill-paper-ink" />
+    </svg>
+  );
+}

package/src/Identity/WhiteLabelPreview.tsx

@@ -0,0 +1,33 @@
+import { type CSSProperties, type ReactElement } from "react";
+import { BrandMark } from "../BrandMark/BrandMark.tsx";
+import { type WhiteLabelPreviewProps } from "./Identity.types.ts";
+import { tokenVariable } from "./tokenVariable.tsx";
+
+/** The same screen under each tenant brand, to prove theming is token-only. */
+export function WhiteLabelPreview({ sample, brands }: WhiteLabelPreviewProps): ReactElement {
+  return (
+    <div className="grid grid-cols-2 max-sm:grid-cols-1 gap-16">
+      {brands.map((brand) => {
+        const style: Record<string, string> = {};
+        for (const [key, value] of Object.entries(brand.tokens)) style[tokenVariable(key)] = value;
+        return (
+          <section
+            key={brand.name}
+            aria-label={brand.name}
+            data-theme={brand.theme}
+            style={style as CSSProperties}
+            className="overflow-hidden rounded-card border border-border-subtle bg-bg-canvas text-text-primary"
+          >
+            <div className="flex flex-wrap items-center justify-between gap-x-8 gap-y-4 px-12 py-8 bg-bg-surface border-b border-border-subtle text-text-12">
+              <BrandMark name={brand.name} size="sm" />
+              <span title={brand.domain} className="min-w-0 truncate text-text-secondary">
+                {brand.domain}
+              </span>
+            </div>
+            <div className="flex flex-col gap-12 p-16">{sample}</div>
+          </section>
+        );
+      })}
+    </div>
+  );
+}

package/src/Identity/qrPath.tsx

@@ -0,0 +1,16 @@
+import qrcode from "qrcode-generator";
+import { type QRModules } from "./Identity.types.ts";
+
+/** The dark modules of a QR code (error correction M) as one SVG path, with a 4-module quiet zone. */
+export function qrPath(value: string): { size: number; path: string } {
+  const code = qrcode(0, "M");
+  code.addData(value);
+  code.make();
+  const modules = code as unknown as QRModules;
+  const n = modules.getModuleCount();
+  const cells: string[] = [];
+  for (let r = 0; r < n; r++) {
+    for (let c = 0; c < n; c++) if (modules.isDark(r, c)) cells.push(`M${c + 4} ${r + 4}h1v1h-1z`);
+  }
+  return { size: n + 8, path: cells.join("") };
+}

package/src/Identity/tokenVariable.tsx

@@ -0,0 +1,9 @@
+import nameMap from "@xos/tokens/name-map.json";
+
+const SPEC = nameMap as Record<string, string>;
+
+/** The CSS variable a white-label token override sets: the spec name with dots as hyphens (`accent-default` is `--color-accent-default`). */
+export function tokenVariable(key: string): string {
+  const spec = SPEC[key];
+  return `--${(spec ?? key).replace(/\./g, "-")}`;
+}

package/src/InlineAlert/README.md

@@ -0,0 +1,3 @@
+# InlineAlert
+
+InlineAlert puts a short message in context; the icon carries tone and the message stays in `text-primary` and `text-secondary`.

package/src/Input/README.md

@@ -0,0 +1,8 @@
+# Input
+
+Input is a labeled single-line text field with help text or an inline error.
+
+- Label above, sentence-case help below. Fields with legal or financial meaning always carry help.
+- Errors name the field, the problem and the fix in one sentence, validated as the person types.
+- Border is `border-control`, which meets the 3:1 non-text minimum; focus replaces it with a 2 px `focus-ring`.
+- `width` sets the field width; it is 280 px by default and never wider than its container.

package/src/Kbd/Kbd.tsx

@@ -0,0 +1,30 @@
+import type { ReactElement } from "react";
+import type { KbdProps as ReferenceKbdProps } from "../types/reference";
+import { cx } from "../lib/cx.ts";
+
+export type KbdProps = ReferenceKbdProps;
+
+const kbdClass = cx(
+  "inline-flex items-center justify-center min-w-(--ui-kbd) h-(--ui-kbd) px-4 rounded-chip",
+  "border border-border-strong bg-bg-surface text-text-secondary font-sans font-medium text-text-11 leading-none",
+  "forced-colors:border-[CanvasText]",
+);
+
+/** One key in a shortcut. */
+export function Kbd({ children }: KbdProps): ReactElement {
+  return <kbd className={kbdClass}>{children}</kbd>;
+}
+
+/** A shortcut written with spaces between keys (`⌘ K`, `G then P` as `G P`) as one Kbd per key. */
+export function Keys({ keys }: { keys: string }): ReactElement {
+  return (
+    <span className="inline-flex items-center gap-2">
+      {keys
+        .split(" ")
+        .filter(Boolean)
+        .map((key, i) => (
+          <Kbd key={`${key}-${i}`}>{key}</Kbd>
+        ))}
+    </span>
+  );
+}

package/src/Kbd/README.md

@@ -0,0 +1,6 @@
+# Kbd
+
+Kbd renders one key of a keyboard shortcut.
+
+- One Kbd per key; sequences show each key (G then P).
+- Used in Button, Tooltip, CommandMenu and the shortcut sheet.

package/src/Layout/AppShell.tsx

@@ -0,0 +1,151 @@
+import { useEffect, useId, useRef, type ReactElement } from "react";
+import { cx } from "../lib/cx.ts";
+import { useT } from "../lib/context.tsx";
+import { Icon } from "../Icon/Icon.tsx";
+import { useControllable, useMediaQuery } from "../lib/hooks.ts";
+import { type AppShellProps } from "./Layout.types.ts";
+
+/**
+ * Brand slot, sidebar, header and content for every Atlas page. Below lg the sidebar becomes a drawer
+ * opened from the header menu button (or by the shell through menuOpen, for the bottom bar's Menu tab)
+ * and closed by Esc or the scrim. While it is open the page behind is inert, as behind a dialog:
+ * focus moves to the drawer's first control and returns to the menu button on Esc. Below md the
+ * bottom bar shows.
+ */
+export function AppShell({
+  brand,
+  sidebar,
+  header,
+  children,
+  mobileNav,
+  menuOpen,
+  onMenuOpenChange,
+}: AppShellProps): ReactElement {
+  const t = useT();
+  const sideId = useId().replace(/:/g, "");
+  const [open, setOpen] = useControllable(menuOpen, false, onMenuOpenChange);
+  const menuButton = useRef<HTMLButtonElement>(null);
+  const side = useRef<HTMLDivElement>(null);
+  const content = useRef<HTMLDivElement>(null);
+  const returnFocus = useRef(false);
+  // The drawer only exists below lg; on a wide screen the sidebar is always there.
+  const drawer = useMediaQuery("(max-width: 63.999rem)");
+  const covered = open && drawer;
+  // A scrolling region keyboard users cannot reach fails WCAG 2.1.1. When the page overflows and holds
+  // nothing focusable (a long read-only table), the region itself takes focus so arrow keys scroll it;
+  // otherwise it stays out of the tab order.
+  useEffect(() => {
+    const el = content.current;
+    if (!el || typeof ResizeObserver === "undefined") return undefined;
+    const sync = () => {
+      const overflows = el.scrollHeight > el.clientHeight;
+      const focusable = el.querySelector(
+        "a[href], button:not([disabled]), input:not([disabled]), select, textarea, [tabindex]:not([tabindex='-1'])",
+      );
+      if (overflows && !focusable) el.setAttribute("tabindex", "0");
+      else el.removeAttribute("tabindex");
+    };
+    sync();
+    const observer = new ResizeObserver(sync);
+    observer.observe(el);
+    for (const child of Array.from(el.children)) observer.observe(child);
+    return () => observer.disconnect();
+  }, [children]);
+  useEffect(() => {
+    if (!open) {
+      // The menu button takes focus back once the page behind is no longer inert.
+      if (returnFocus.current) menuButton.current?.focus();
+      returnFocus.current = false;
+      return undefined;
+    }
+    if (side.current && getComputedStyle(side.current).position === "absolute") {
+      side.current
+        .querySelector<HTMLElement>("a[href], button:not([disabled]), select, input")
+        ?.focus();
+    }
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key === "Escape") {
+        returnFocus.current = true;
+        setOpen(false);
+      }
+    };
+    document.addEventListener("keydown", onKey);
+    return () => document.removeEventListener("keydown", onKey);
+  }, [open, setOpen]);
+  return (
+    <div
+      data-open={open ? "true" : undefined}
+      className={cx(
+        "group/shell relative grid grid-cols-[var(--layout-sidebar)_minmax(0,1fr)] max-lg:grid-cols-[minmax(0,1fr)]",
+        "min-h-(--ui-shell-min) h-full overflow-hidden bg-bg-canvas print:block",
+      )}
+    >
+      <div
+        id={sideId}
+        ref={side}
+        className={cx(
+          "flex flex-col gap-4 min-h-0 p-8 overflow-y-auto bg-bg-surface border-e border-border-subtle [&>*]:shrink-0",
+          "[&_nav]:border-0 [&_nav]:p-0 [&_nav]:w-auto print:hidden",
+          "max-lg:hidden max-lg:group-data-[open=true]/shell:flex max-lg:group-data-[open=true]/shell:absolute",
+          "max-lg:inset-y-0 max-lg:start-0 max-lg:z-sidebar max-lg:w-[min(var(--layout-sidebar),85%)] max-lg:shadow-dialog",
+        )}
+      >
+        {brand ? <div className="px-8 pt-4 pb-8">{brand}</div> : null}
+        {sidebar}
+      </div>
+      {open ? (
+        <button
+          type="button"
+          aria-label={t("action.close")}
+          onClick={() => setOpen(false)}
+          className={cx(
+            "hidden max-lg:block absolute inset-0 z-[calc(var(--z-sidebar)-1)] p-0 border-0 cursor-pointer",
+            "bg-scrim opacity-scrim-dark in-data-[theme=light]:opacity-scrim-light in-data-[theme=sunlight]:opacity-scrim-light",
+          )}
+        />
+      ) : null}
+      <main className="flex flex-col min-w-0 min-h-0" inert={covered}>
+        <div
+          className={cx(
+            "flex items-center justify-between gap-8 h-(--ui-shell-head) px-16 border-b border-border-subtle",
+            "max-lg:justify-start",
+            !header && "hidden max-lg:flex",
+          )}
+        >
+          <span className="hidden max-lg:inline-flex">
+            <button
+              ref={menuButton}
+              type="button"
+              aria-label={t("shell.menu")}
+              title={t("shell.menu")}
+              aria-expanded={open}
+              aria-controls={sideId}
+              onClick={() => setOpen(!open)}
+              className="inline-flex items-center justify-center h-control-md min-w-control-md rounded-control border border-transparent bg-transparent text-text-secondary cursor-pointer hover:bg-bg-hover pointer-coarse:min-h-target-coarse pointer-coarse:min-w-target-coarse"
+            >
+              <Icon name="Menu" />
+            </button>
+          </span>
+          {header ? (
+            <div className="flex flex-1 items-center justify-between gap-8 min-w-0">{header}</div>
+          ) : null}
+        </div>
+        <div
+          ref={content}
+          data-xos-bottom-bar-scroll={mobileNav ? "" : undefined}
+          className="flex flex-col gap-16 min-h-0 px-24 py-16 max-lg:p-16 overflow-y-auto [&>*]:shrink-0"
+        >
+          {children}
+        </div>
+        {mobileNav ? (
+          <div
+            data-xos-bottom-bar=""
+            className="hidden max-md:block sticky bottom-0 [&_nav]:w-full print:hidden"
+          >
+            {mobileNav}
+          </div>
+        ) : null}
+      </main>
+    </div>
+  );
+}

package/src/Layout/Layout.tsx

@@ -0,0 +1,14 @@
+export {
+  type AppShellProps,
+  type PageHeaderProps,
+  type ResizablePanelProps,
+  type ScrollRegionProps,
+  type SplitViewProps,
+  type StepperProps,
+} from "./Layout.types.ts";
+export { AppShell } from "./AppShell.tsx";
+export { PageHeader } from "./PageHeader.tsx";
+export { ResizablePanel } from "./ResizablePanel.tsx";
+export { ScrollRegion } from "./ScrollRegion.tsx";
+export { Stepper } from "./Stepper.tsx";
+export { SplitView } from "./SplitView.tsx";

package/src/Layout/Layout.types.ts

@@ -0,0 +1,43 @@
+import { type CSSProperties, type Ref, type ReactNode } from "react";
+import type {
+  AppShellProps as ReferenceAppShellProps,
+  PageHeaderProps as ReferencePageHeaderProps,
+  ResizablePanelProps as ReferenceResizablePanelProps,
+  ScrollRegionProps as ReferenceScrollRegionProps,
+  SplitViewProps as ReferenceSplitViewProps,
+  StepperProps as ReferenceStepperProps,
+} from "../types/reference";
+
+export type AppShellProps = ReferenceAppShellProps & {
+  /** The phone bottom bar (TabBar), shown below md. */
+  mobileNav?: ReactNode;
+  /**
+   * Whether the navigation drawer is open below lg, for a shell that opens it from elsewhere too
+   * (the bottom bar's Menu tab). Uncontrolled when omitted.
+   */
+  menuOpen?: boolean;
+  onMenuOpenChange?: (open: boolean) => void;
+};
+
+export type PageHeaderProps = ReferencePageHeaderProps;
+
+export type ResizablePanelProps = ReferenceResizablePanelProps & {
+  onResize?: (width: number) => void;
+  /** Keyboard step in pixels; 16 by default. */
+  step?: number;
+};
+
+export type ScrollRegionProps = ReferenceScrollRegionProps & {
+  /** Classes for the scrolling element itself. */
+  className?: string;
+  /** Classes for the frame around it that holds the edge fades (its place in a flex row, say). */
+  frameClassName?: string;
+  style?: CSSProperties;
+  ref?: Ref<HTMLDivElement>;
+};
+
+export type SplitViewProps = ReferenceSplitViewProps & {
+  onSelect?: (index: number) => void;
+};
+
+export type StepperProps = ReferenceStepperProps;

package/src/Layout/PageHeader.tsx

@@ -0,0 +1,22 @@
+import { type ReactElement } from "react";
+import { Icon } from "../Icon/Icon.tsx";
+import { type PageHeaderProps } from "./Layout.types.ts";
+
+/** Title, count, view switcher and the one primary action of a collection. */
+export function PageHeader({ title, glyph, count, views, actions }: PageHeaderProps): ReactElement {
+  return (
+    <header className="flex flex-wrap items-center justify-between gap-12 pb-12 border-b border-border-subtle">
+      <div className="flex items-center gap-8 min-w-0">
+        {glyph ? <Icon name={glyph} color="var(--color-text-secondary)" /> : null}
+        <h1 className="m-0 text-heading-16 font-semibold">{title}</h1>
+        {count !== undefined ? (
+          <span className="text-text-secondary tabular-nums">{count}</span>
+        ) : null}
+      </div>
+      <div className="flex flex-wrap items-center gap-8 print:hidden">
+        {views}
+        {actions}
+      </div>
+    </header>
+  );
+}

package/src/Layout/ResizablePanel.tsx

@@ -0,0 +1,81 @@
+import { useState, type PointerEvent as ReactPointerEvent, type ReactElement } from "react";
+import { Direction } from "radix-ui";
+import { useT } from "../lib/context.tsx";
+import { type ResizablePanelProps } from "./Layout.types.ts";
+
+/**
+ * A panel resizable by pointer or arrow keys within its limits; the handle is a vertical separator
+ * with its value. Home and End jump to the limits.
+ */
+export function ResizablePanel({
+  initial,
+  min,
+  max,
+  side = "right",
+  label,
+  children,
+  onResize,
+  step = 16,
+}: ResizablePanelProps): ReactElement {
+  const t = useT();
+  const dir = Direction.useDirection();
+  const [width, setWidthState] = useState(initial);
+  const setWidth = (next: number) => {
+    const clamped = Math.max(min, Math.min(max, next));
+    setWidthState(clamped);
+    onResize?.(clamped);
+  };
+  // The handle sits on the inline end for side "right"; dragging toward the reading direction grows it.
+  const growKey = (side === "left") !== (dir === "rtl") ? "ArrowLeft" : "ArrowRight";
+  const shrinkKey = growKey === "ArrowRight" ? "ArrowLeft" : "ArrowRight";
+  const down = (e: ReactPointerEvent<HTMLDivElement>) => {
+    const start = e.clientX;
+    const startWidth = width;
+    const sign = growKey === "ArrowRight" ? 1 : -1;
+    const move = (ev: PointerEvent) => setWidth(startWidth + sign * (ev.clientX - start));
+    const up = () => {
+      window.removeEventListener("pointermove", move);
+      window.removeEventListener("pointerup", up);
+    };
+    window.addEventListener("pointermove", move);
+    window.addEventListener("pointerup", up);
+  };
+  const handle = (
+    <div
+      role="separator"
+      aria-orientation="vertical"
+      aria-valuenow={width}
+      aria-valuemin={min}
+      aria-valuemax={max}
+      aria-label={label ?? t("panel.resize")}
+      tabIndex={0}
+      onPointerDown={down}
+      onKeyDown={(e) => {
+        const next =
+          e.key === growKey
+            ? width + step
+            : e.key === shrinkKey
+              ? width - step
+              : e.key === "Home"
+                ? min
+                : e.key === "End"
+                  ? max
+                  : null;
+        if (next === null) return;
+        e.preventDefault();
+        setWidth(next);
+      }}
+      className="flex-none w-(--ui-handle) cursor-col-resize touch-none border-s border-border-subtle hover:bg-accent focus-visible:bg-accent"
+    />
+  );
+  return (
+    <div
+      className="relative flex min-h-(--ui-resizable-min) bg-bg-surface border border-border-subtle rounded-card max-w-full"
+      style={{ inlineSize: width }}
+    >
+      {side === "left" ? handle : null}
+      <div className="flex-1 min-w-0 p-16 overflow-hidden">{children}</div>
+      {side === "left" ? null : handle}
+    </div>
+  );
+}