@sableui/react 0.17.0 → 0.19.0

package/dist/components/data-table/data-table.meta.js

@@ -1,7 +1,7 @@
 // src/components/data-table/data-table.meta.ts
 var dataTableMeta = {
   name: "DataTable",
-  summary: "A data-driven table over the Table primitives \u2014 a columns def + data array with built-in client-side sorting (click a sortable header to cycle asc \u2192 desc \u2192 none), optional row click / selection, and an empty state. For server data or paging, sort/page the data and pair with Pagination.",
+  summary: "A data-driven table over the Table primitives \u2014 a columns def + data array with built-in client-side sorting (click a sortable header to cycle asc \u2192 desc \u2192 none), optional row click / selection, rows grouped under collapsible header rows (groupBy), and an empty state. For server data or paging, sort/page the data and pair with Pagination.",
   keywords: [
     "data table",
     "table",
@@ -10,7 +10,14 @@ var dataTableMeta = {
     "rows",
     "empty state",
     "pagination",
-    "list"
+    "list",
+    "grouped",
+    "group by",
+    "sections",
+    "issue list",
+    "issue tracker",
+    "status groups",
+    "collapsible groups"
   ],
   usage: {
     description: "Use DataTable when a data array and column definition should render a sortable, semantic table with optional row actions and an empty state. Use the lower-level Table parts for hand-authored markup or highly custom row layouts.",
@@ -33,7 +40,11 @@ var dataTableMeta = {
       },
       {
         guidance: "do",
-        description: "Move to TanStack Table, rendered with Sable's Table parts, once the table needs server-side sorting or filtering, column visibility or resizing, grouping, or virtualised rows. DataTable stays dependency-free and does not grow into a data grid; `sable docs tables-with-tanstack` maps one onto the other."
+        description: "Group rows by status for an issue tracker (or by owner, by day) with groupBy + groups on ONE DataTable: every group shares the header and the column widths, each header row carries the group's count and an add action, and sorting applies within each group. Do not stack one DataTable per group inside Collapsibles; the header repeats and the columns stop lining up."
+      },
+      {
+        guidance: "do",
+        description: "Move to TanStack Table, rendered with Sable's Table parts, once the table needs server-side sorting or filtering, column visibility or resizing, nested or aggregated grouping, or virtualised rows. DataTable stays dependency-free and does not grow into a data grid; `sable docs tables-with-tanstack` maps one onto the other."
       },
       {
         guidance: "dont",
@@ -60,6 +71,11 @@ var dataTableMeta = {
         required: false,
         description: "Content spanning all columns when the row array is empty."
       },
+      {
+        name: "Group header row",
+        required: false,
+        description: "With groupBy: one row per group heading its own tbody (a th with scope=rowgroup across every column) holding the disclosure toggle, the group's icon, label and count, and an optional trailing action."
+      },
       {
         name: "Caption",
         required: false,
@@ -136,6 +152,32 @@ var dataTableMeta = {
       name: "caption",
       type: "ReactNode",
       description: "Bottom table caption."
+    },
+    {
+      name: "groupBy",
+      type: "(row) => string",
+      description: "Group the rows under header rows by the key this returns (a status, an owner, a day). One header serves every group, so the columns line up across them; sorting applies within each group."
+    },
+    {
+      name: "groups",
+      type: "{ key: string; label?: ReactNode; icon?: ReactNode; action?: ReactNode; defaultExpanded?: boolean }[]",
+      description: "Order and presentation of the groups, by key: the header row's label (defaults to the key), a leading icon such as a status mark, a trailing action such as an icon Button that adds a row to the group, and whether it starts open (default true). Groups groupBy returns that are not listed follow, in the order their first row appears in data. A listed group with no rows is not shown."
+    },
+    {
+      name: "collapsible",
+      type: "boolean",
+      default: "true",
+      description: "Whether each group's header row is a toggle that opens and closes the group. A closed group keeps its header row and count; its rows are hidden and select-all skips them."
+    },
+    {
+      name: "expandedGroups",
+      type: "ReadonlySet<string>",
+      description: "The open groups, by key (controlled). Without it each group starts at its defaultExpanded and the table holds the state."
+    },
+    {
+      name: "onExpandedGroupsChange",
+      type: "(keys: Set<string>) => void",
+      description: "Called with the new set of open group keys when a group header is toggled."
     }
   ],
   tokensUsed: ["muted-foreground", "foreground", "ring"],
@@ -164,6 +206,18 @@ var dataTableMeta = {
       part: "Row",
       why: "A checked row's fill eases in across its cells, so selecting by checkbox reads as the row being picked rather than a band stamped over it."
     },
+    {
+      slot: "transition",
+      recipe: "motion-interactive",
+      part: "Group chevron",
+      why: "A group's chevron turns from pointing along the reading direction (closed) to down (open), so the group reads as folding rather than a glyph being swapped."
+    },
+    {
+      slot: "arrival",
+      recipe: "none",
+      part: "Group rows",
+      why: "Opening a group shows its rows at once: table rows cannot animate their height without leaving the table layout, and the rows are the content the reader asked for."
+    },
     {
       slot: "activity",
       recipe: "none",
@@ -174,7 +228,8 @@ var dataTableMeta = {
   a11y: [
     "Sorted columns set aria-sort=ascending/descending on the header cell.",
     "Sortable headers are real <button>s with a focus-visible ring, keyboard-operable.",
-    "Inherits the Table's scrollable frame and semantic <table>/<th>/<td> structure."
+    "Inherits the Table's scrollable frame and semantic <table>/<th>/<td> structure.",
+    'Grouped, each group is its own <tbody> (a rowgroup) headed by a <th scope="rowgroup"> spanning the columns, so group headers are never read as data rows; the toggle is a real button with aria-expanded and aria-controls naming that tbody.'
   ],
   examples: [
     {
@@ -197,6 +252,10 @@ var dataTableMeta = {
       label: "In a card, edge to edge",
       code: '<Card><CardHeader><CardTitle>Deployments</CardTitle></CardHeader><CardContent flush><DataTable data={deployments} rowKey={(row) => row.id} columns={[{ key: "project", header: "Project", sortable: true }, { key: "duration", header: "Duration", align: "end" }]} /></CardContent></Card>'
     },
+    {
+      label: "Issues grouped by status",
+      code: 'const STATUSES = [\n	{ key: "in-progress", label: "In progress", icon: <StatusDot tone="warning" /> },\n	{ key: "in-review", label: "In review", icon: <StatusDot tone="purple" /> },\n	{ key: "todo", label: "Todo", icon: <StatusDot /> },\n	{ key: "done", label: "Done", icon: <StatusDot tone="success" />, defaultExpanded: false },\n]\n\n<DataTable\n	data={issues}\n	rowKey={(t) => t.id}\n	groupBy={(t) => t.status}\n	groups={STATUSES.map((s) => ({ ...s, action: <Button variant="ghost" size="icon-xs" aria-label={`Add issue to ${s.label}`} onClick={() => create(s.key)}><Icon name="plus" /></Button> }))}\n	onRowClick={(t) => setSelectedId(t.id)}\n	isRowSelected={(t) => t.id === selectedId}\n	columns={[\n		{ key: "id", header: "ID", className: "w-20", cell: (t) => <span className="text-mono-caption text-muted-foreground">{t.id}</span> },\n		{ key: "title", header: "Issue", sortable: true },\n		{ key: "due", header: "Due", sortable: true, sortValue: (t) => t.due.getTime(), cell: (t) => formatDate(t.due) },\n	]}\n/>'
+    },
     {
       label: "Empty state",
       code: '<DataTable data={[]} columns={[{ key: "name", header: "Name" }, { key: "status", header: "Status" }]} empty={<EmptyState icon={<Icon name="search" />} title="No deployments" description="Try a different filter or create a deployment." action={<Button>Create deployment</Button>} />} />'

package/dist/components/date-picker/date-picker.js

@@ -12,7 +12,7 @@ import { useId, useState } from "react";
 import { Icon } from "../../icon/index.js";
 import { cn } from "../../lib/cn.js";
 import { useDensity, useTypeTier } from "../../lib/density.js";
-import { FIELD_INVALID, FIELD_SHELL, MOBILE_FIELD_TIER } from "../../lib/field-shell.js";
+import { FIELD_INVALID, FIELD_SHELL, FIELD_SHELL_XS, MOBILE_FIELD_TIER } from "../../lib/field-shell.js";
 import { Calendar } from "../calendar/calendar.js";
 import { Popover, PopoverContent, PopoverTrigger } from "../popover/popover.js";
 import {
@@ -56,6 +56,8 @@ function DatePicker(props) {
     disabled,
     minDate,
     maxDate,
+    size = "md",
+    formatOptions,
     className,
     id,
     "aria-label": ariaLabel,
@@ -102,11 +104,12 @@ function DatePicker(props) {
     if (next == null) return;
     commit(setMinutes(timeBase(), Number(next)));
   }
-  const label = value ? (
+  const label = value ? formatOptions ? new Intl.DateTimeFormat(void 0, formatOptions).format(value) : (
     // 24-hour, matching the hour / minute Selects below — the trigger
     // and the row that sets it must not show the same time two ways.
     format(value, withTime ? "MMM d, yyyy 'at' HH:mm" : "PP")
   ) : placeholder ?? (withTime ? "Pick date & time" : "Pick a date");
+  const xs = size === "xs";
   return /* @__PURE__ */ jsxs(Popover, { open, onOpenChange: setOpen, children: [
     /* @__PURE__ */ jsx(
       PopoverTrigger,
@@ -130,17 +133,21 @@ function DatePicker(props) {
               "aria-required": ariaRequired,
               disabled,
               className: cn(
-                "inline-flex h-(--control-md) items-center gap-2 ps-3 pe-3 text-start text-foreground",
+                "inline-flex items-center text-start text-foreground",
+                xs ? "h-(--control-xs) gap-1 px-1.5" : "h-(--control-md) gap-2 ps-3 pe-3",
                 // Select's type: the density tier, plus the 16px phone tier
-                // its form-row neighbours take (lib/field-shell).
+                // its form-row neighbours take (lib/field-shell). The xs rung
+                // never sits in a page-register form row, so it skips it.
                 tier.body,
-                density === "comfortable" && MOBILE_FIELD_TIER,
+                density === "comfortable" && !xs && MOBILE_FIELD_TIER,
                 FIELD_SHELL,
+                // After FIELD_SHELL, so its well replaces the outlined field.
+                xs && FIELD_SHELL_XS,
                 FIELD_INVALID,
                 className
               ),
               children: [
-                /* @__PURE__ */ jsx(Icon, { name: "calendar", className: "shrink-0 text-sm text-muted-foreground" }),
+                /* @__PURE__ */ jsx(Icon, { name: "calendar", className: cn("shrink-0 text-muted-foreground", xs ? "text-xs" : "text-sm") }),
                 /* @__PURE__ */ jsx("span", { className: cn("truncate", !value && "text-muted-foreground"), children: label })
               ]
             }

package/dist/components/date-picker/date-picker.meta.js

@@ -5,6 +5,9 @@ var datePickerMeta = {
   status: "stable",
   keywords: [
     "date picker",
+    "due date",
+    "property row",
+    "inspector",
     "calendar",
     "date input",
     "date time picker",
@@ -104,6 +107,17 @@ var datePickerMeta = {
       type: "Date",
       description: "Latest selectable day (inclusive). Later days are disabled and navigation is bounded."
     },
+    {
+      name: "size",
+      type: '"md" | "xs"',
+      default: '"md"',
+      description: `The trigger's rung. md is the form field beside Input and Select. xs is the property-grid rung (24px in a workspace): an inset panel-field well with no border, the same shape as SelectTrigger size="xs" and ScrubField on the neighbouring rows of an inspector \u2014 use it for a due date in a PropertyRow instead of a native date input.`
+    },
+    {
+      name: "formatOptions",
+      type: "Intl.DateTimeFormatOptions",
+      description: `How the trigger writes the chosen date, as Intl.DateTimeFormat options in the reader's locale \u2014 { month: "short", day: "numeric" } for "Oct 23" where the rest of a list writes dates that way. Omitted: "Oct 23, 2026" (with "at 14:30" under granularity="minute").`
+    },
     {
       name: "className",
       type: "string",
@@ -137,6 +151,14 @@ var datePickerMeta = {
     'With granularity="minute" the hour and minute Selects are full Base UI listboxes (typeahead, ARIA) labelled "Hour" and "Minute"; selecting a day keeps the chosen time-of-day, so day and time can be set in any order.'
   ],
   examples: [
+    {
+      label: "In an inspector row",
+      code: `<PanelSection title="Properties">
+	<PropertyRow label="Due date">
+		<DatePicker size="xs" aria-label="Due date" value={due} onValueChange={setDue} formatOptions={{ month: "short", day: "numeric" }} />
+	</PropertyRow>
+</PanelSection>`
+    },
     {
       label: "Controlled",
       code: "const [date, setDate] = useState<Date>()\n<DatePicker value={date} onValueChange={setDate} />"

package/dist/components/dialog/dialog.js

@@ -1,13 +1,19 @@
 // src/components/dialog/dialog.tsx
 import { AlertDialog as AlertBase } from "@base-ui/react/alert-dialog";
 import { Dialog as Base } from "@base-ui/react/dialog";
+import { useMemo } from "react";
 import { Icon } from "../../icon/index.js";
 import { cn } from "../../lib/cn.js";
+import { FocusReturnProvider, useFocusReturn, useFocusReturnDefault } from "../../lib/focus-return.js";
 import { withPortalThemeScope } from "../../lib/portal-theme-scope.js";
 import { PresentationProvider } from "../../lib/presentation.js";
+import { mergeRefs } from "../../lib/refs.js";
 import { Button } from "../button/button.js";
 import { jsx, jsxs } from "react/jsx-runtime";
-var Dialog = Base.Root;
+function Dialog({ open, onOpenChange, ...props }) {
+  const focus = useFocusReturn(open, onOpenChange);
+  return /* @__PURE__ */ jsx(FocusReturnProvider, { value: focus.focusReturn, children: /* @__PURE__ */ jsx(Base.Root, { ...props, open, onOpenChange: focus.onOpenChange }) });
+}
 var DialogTrigger = Base.Trigger;
 var DialogClose = Base.Close;
 var DialogPortal = withPortalThemeScope(Base.Portal);
@@ -29,13 +35,22 @@ function DialogContent({
   size = "default",
   showCloseButton,
   scroll,
+  finalFocus,
+  ref,
   ...props
 }) {
-  return size === "fullscreen" ? /* @__PURE__ */ jsx(FullscreenContent, { showCloseButton: showCloseButton ?? true, ...props }) : /* @__PURE__ */ jsx(
+  const focusReturn = useFocusReturnDefault();
+  const popupRef = useMemo(
+    () => focusReturn ? mergeRefs(focusReturn.popupRef, ref) : ref,
+    [focusReturn, ref]
+  );
+  const focus = { ref: popupRef, finalFocus: finalFocus === void 0 ? focusReturn?.finalFocus : finalFocus };
+  return size === "fullscreen" ? /* @__PURE__ */ jsx(FullscreenContent, { showCloseButton: showCloseButton ?? true, ...focus, ...props }) : /* @__PURE__ */ jsx(
     CardContent,
     {
       showCloseButton: showCloseButton ?? false,
       scroll: scroll ?? true,
+      ...focus,
       ...props
     }
   );
@@ -44,9 +59,10 @@ function FullscreenContent({
   className,
   children,
   showCloseButton,
+  keepMounted,
   ...props
 }) {
-  return /* @__PURE__ */ jsxs(DialogPortal, { children: [
+  return /* @__PURE__ */ jsxs(DialogPortal, { keepMounted, children: [
     /* @__PURE__ */ jsx(DialogOverlay, { size: "fullscreen" }),
     /* @__PURE__ */ jsxs(
       Base.Popup,
@@ -93,9 +109,10 @@ function CardContent({
   children,
   showCloseButton,
   scroll,
+  keepMounted,
   ...props
 }) {
-  return /* @__PURE__ */ jsxs(DialogPortal, { children: [
+  return /* @__PURE__ */ jsxs(DialogPortal, { keepMounted, children: [
     /* @__PURE__ */ jsx(DialogOverlay, {}),
     /* @__PURE__ */ jsxs(
       Base.Popup,
@@ -175,7 +192,10 @@ function DialogFooter({
     }
   );
 }
-var AlertDialog = AlertBase.Root;
+function AlertDialog({ open, onOpenChange, ...props }) {
+  const focus = useFocusReturn(open, onOpenChange);
+  return /* @__PURE__ */ jsx(FocusReturnProvider, { value: focus.focusReturn, children: /* @__PURE__ */ jsx(AlertBase.Root, { ...props, open, onOpenChange: focus.onOpenChange }) });
+}
 var AlertDialogTrigger = AlertBase.Trigger;
 var AlertDialogClose = DialogClose;
 var AlertDialogContent = DialogContent;

package/dist/components/dialog/dialog.meta.js

@@ -59,6 +59,18 @@ var dialogMeta = {
         description: "Open a dialog for passive status updates. Use Toast, Banner, or InlineStatus instead.",
         instead: ["Toast", "Banner", "InlineStatus"]
       },
+      {
+        guidance: "do",
+        description: "Open a dialog from your own button with controlled open/onOpenChange when the trigger is not a DialogTrigger (a menu item, a row action, a keyboard shortcut). Focus returns on close to whatever held it when the dialog opened, with no finalFocus wiring; pass finalFocus only to send it somewhere else."
+      },
+      {
+        guidance: "do",
+        description: "Set keepMounted on DialogContent for a draft the user may come back to (a compose form, a long comment, a half-filled request). Closing by Esc or a stray click then hides the dialog instead of unmounting it, so the fields are still filled when it reopens. Clear the draft yourself on submit or discard."
+      },
+      {
+        guidance: "dont",
+        description: "Set keepMounted by default. A dialog that should open fresh (a confirmation, a create form after a successful save) would show stale input, and live content (polling, video) keeps running while hidden."
+      },
       {
         guidance: "do",
         description: 'Use the AlertDialog family for a confirmation that must be answered (discard changes, leave without saving). It looks identical but is role="alertdialog" and a backdrop click does not dismiss it \u2014 only Cancel, Esc, or the action. For irreversible deletes, use DestructiveActionModal, which is built on it.'
@@ -101,8 +113,11 @@ var dialogMeta = {
     {
       name: "Dialog (Root)",
       type: "Base UI Dialog.Root props (open, defaultOpen, onOpenChange, modal)",
-      description: "Controls open state. Uncontrolled by default."
-    }
+      description: "Controls open state. Uncontrolled by default. Records the element that holds focus when the dialog opens (through a DialogTrigger, or your own button flipping a controlled open) and returns focus there on close."
+    },
+    { name: "open", type: "boolean", description: "Controlled open state. Pair with onOpenChange \u2014 for a dialog opened from your own button instead of a DialogTrigger." },
+    { name: "defaultOpen", type: "boolean", default: "false", description: "Initial open state when uncontrolled." },
+    { name: "onOpenChange", type: "(open: boolean, eventDetails) => void", description: "Called when the dialog asks to open or close (a trigger, Esc, an outside click, DialogClose)." }
   ],
   variants: {
     size: ["default", "fullscreen"]
@@ -110,8 +125,8 @@ var dialogMeta = {
   subcomponents: [
     {
       name: "DialogContent",
-      type: 'Base UI Popup props + size?: "default" | "fullscreen" + showCloseButton?: boolean + scroll?: boolean + className',
-      description: 'Backdrop + popup; portals to <body>. Composes DialogOverlay by default. size="fullscreen" is the media viewer: a near-opaque scrim (bg-overlay/95), an edge-to-edge popup that centres its children with no card chrome, motion-fade instead of motion-pop, and a safe-area-aware floating close button (Button variant="floating"); at that size showCloseButton defaults to true and scroll to false, and the media fits itself with max-h-full max-w-full object-contain. At the default size, showCloseButton (defaults to false) renders a built-in close (X) button in the top-end corner, and the header leaves room for it (Icon name="xmark"). The popup caps at the viewport height less a 1rem margin and wraps its children in a scrolling region, so a tall dialog scrolls instead of overflowing a viewport whose own scroll is locked; pass scroll={false} when the dialog owns its internal layout (a pinned header over a scrolling body) and supplies its own min-h-0 scroll region.'
+      type: 'Base UI Popup props (initialFocus, finalFocus) + size?: "default" | "fullscreen" + showCloseButton?: boolean + scroll?: boolean + keepMounted?: boolean + className',
+      description: 'Backdrop + popup; portals to <body>. Composes DialogOverlay by default. size="fullscreen" is the media viewer: a near-opaque scrim (bg-overlay/95), an edge-to-edge popup that centres its children with no card chrome, motion-fade instead of motion-pop, and a safe-area-aware floating close button (Button variant="floating"); at that size showCloseButton defaults to true and scroll to false, and the media fits itself with max-h-full max-w-full object-contain. At the default size, showCloseButton (defaults to false) renders a built-in close (X) button in the top-end corner, and the header leaves room for it (Icon name="xmark"). The popup caps at the viewport height less a 1rem margin and wraps its children in a scrolling region, so a tall dialog scrolls instead of overflowing a viewport whose own scroll is locked; pass scroll={false} when the dialog owns its internal layout (a pinned header over a scrolling body) and supplies its own min-h-0 scroll region. keepMounted (default false) keeps the content mounted and hidden while closed, so a draft survives close and reopen. finalFocus defaults to the element focused when the dialog opened, trigger or not; an explicit finalFocus (a ref, a function, or false) wins.'
     },
     {
       name: "DialogOverlay",
@@ -151,7 +166,7 @@ var dialogMeta = {
     {
       name: "AlertDialog (Root)",
       type: "Base UI AlertDialog.Root props (open, defaultOpen, onOpenChange)",
-      description: 'Root for a confirmation that needs an answer. Always modal; the popup is role="alertdialog" and a click outside does not dismiss \u2014 only an AlertDialogClose, an action that sets open to false, or Esc.'
+      description: 'Root for a confirmation that needs an answer. Always modal; the popup is role="alertdialog" and a click outside does not dismiss \u2014 only an AlertDialogClose, an action that sets open to false, or Esc. Returns focus on close to the element focused when it opened, exactly as Dialog does.'
     },
     {
       name: "AlertDialogTrigger",
@@ -210,6 +225,8 @@ var dialogMeta = {
   a11y: [
     "Base UI provides focus trapping, scroll lock, aria-modal, and labelled-by wiring (DialogTitle).",
     "Content taller than the viewport scrolls inside the dialog (thin scrollbar, contained overscroll) rather than overflowing off screen \u2014 the page behind is scroll-locked, so anything past the edge would be unreachable.",
+    "On close, focus returns to the element that held it when the dialog opened, whether a DialogTrigger opened it or your own button set a controlled open. It is captured before the content mounts, so an autoFocus field inside cannot displace it. If that element has left the page, Base UI's default (the trigger, if any) applies; an explicit finalFocus on the content always wins. AlertDialog and Sheet behave the same.",
+    "keepMounted hides closed content with the hidden attribute, so a kept draft is out of the accessibility tree and the tab order until the dialog reopens.",
     'Esc and click-outside dismiss by default. AlertDialog keeps Esc but ignores click-outside, and its popup is role="alertdialog".',
     "Animate via data-[starting-style]/data-[ending-style] attributes.",
     'size="fullscreen" has no title chrome, so name the popup yourself: aria-label on DialogContent (or a visually hidden DialogTitle), plus alt text on the media \u2014 the zoomed image is a separate image to assistive technology. Its built-in close button carries aria-label="Close" and clears the safe-area insets (notch, home indicator).'
@@ -231,6 +248,10 @@ var dialogMeta = {
       label: "Settings form",
       code: '<Dialog><DialogTrigger render={<Button variant="secondary">Rename collection</Button>} /><DialogContent showCloseButton><DialogHeader><DialogTitle>Rename collection</DialogTitle><DialogDescription>Update the display name shown to collectors.</DialogDescription></DialogHeader><Form><Field label="Collection name"><Input defaultValue="Midnight Archive" /></Field><DialogFooter><DialogClose render={<Button variant="secondary">Cancel</Button>} /><Button type="submit">Save changes</Button></DialogFooter></Form></DialogContent></Dialog>'
     },
+    {
+      label: "Opened from your own button, keeping a draft",
+      code: 'const [open, setOpen] = useState(false)\n\n<Button variant="secondary" onClick={() => setOpen(true)}>New message</Button>\n<Dialog open={open} onOpenChange={setOpen}>\n	<DialogContent keepMounted showCloseButton>\n		<DialogHeader>\n			<DialogTitle>New message</DialogTitle>\n			<DialogDescription>Close it any time. Your draft is here when you come back.</DialogDescription>\n		</DialogHeader>\n		<Field label="Message"><Textarea /></Field>\n		<DialogFooter>\n			<DialogClose render={<Button variant="secondary">Close</Button>} />\n			<Button onClick={() => setOpen(false)}>Send</Button>\n		</DialogFooter>\n	</DialogContent>\n</Dialog>'
+    },
     {
       label: "Destructive confirmation",
       code: '<AlertDialog><AlertDialogTrigger render={<Button variant="destructive">Delete project</Button>} /><AlertDialogContent><AlertDialogHeader><AlertDialogTitle>Delete project?</AlertDialogTitle><AlertDialogDescription>This removes the project and cannot be undone.</AlertDialogDescription></AlertDialogHeader><AlertDialogFooter><AlertDialogClose render={<Button variant="secondary">Cancel</Button>} /><Button variant="destructive" onClick={deleteProject}>Delete project</Button></AlertDialogFooter></AlertDialogContent></AlertDialog>'

package/dist/components/media-image/media-image.js

@@ -12,6 +12,7 @@ function MediaImage({
   seed,
   fallback,
   fit = "cover",
+  position,
   srcSet,
   sizes,
   loading = "lazy",
@@ -42,7 +43,8 @@ function MediaImage({
             loading,
             decoding: "async",
             onLoadingStatusChange: (next) => setTracked({ src, status: next }),
-            className: cn("size-full motion-fade", fit === "contain" ? "object-contain" : "object-cover")
+            className: cn("size-full motion-fade", fit === "contain" ? "object-contain" : "object-cover"),
+            style: position != null ? { objectPosition: position } : void 0
           }
         ) : null,
         showFallback ? /* @__PURE__ */ jsx("div", { "data-slot": "media-image-fallback", "aria-hidden": true, className: "absolute inset-0", children: fallback ?? /* @__PURE__ */ jsx(GradientArt, { seed: seed ?? (alt || void 0), className: "size-full" }) }) : null

package/dist/components/media-image/media-image.meta.js

@@ -30,6 +30,10 @@ var mediaImageMeta = {
         guidance: "do",
         description: "Leave `alt` empty when a visible title sits next to the image \u2014 a tile, a row \u2014 and describe it when the image stands alone. A set `alt` also names the fallback, so the description survives a broken URL."
       },
+      {
+        guidance: "do",
+        description: 'Set `position` when a cover crop would cut off the subject \u2014 a face high in a portrait, a product at one edge. Store the focus with the image (`"35% 50%"`) rather than re-cropping the file.'
+      },
       {
         guidance: "dont",
         description: "Do not hand-write `<img onError={() => setBroken(true)}>`. An image that fails before hydration never fires the handler on a prerendered page; MediaImage preloads off the DOM and catches it."
@@ -57,6 +61,12 @@ var mediaImageMeta = {
       default: '"cover"',
       description: "`cover` crops to fill (artwork, photos); `contain` letterboxes on the muted surface (a logo, a product that must not be cropped)."
     },
+    {
+      name: "position",
+      type: 'CSSProperties["objectPosition"]',
+      default: '"center"',
+      description: 'Where the image sits in its frame \u2014 CSS `object-position`, the sibling of `fit`. Under `cover` it is the part the crop keeps (`"50% 30%"` for a face, `"bottom"` for a horizon); under `contain` it is the side the letterbox gives way to.'
+    },
     { name: "srcSet", type: "string", description: "Responsive sources, passed to the `<img>`." },
     { name: "sizes", type: "string", description: "The `sizes` attribute for `srcSet`." },
     { name: "loading", type: '"lazy" | "eager"', default: '"lazy"', description: "Native lazy loading. Use `eager` for the first row of a grid above the fold." },
@@ -84,7 +94,11 @@ var mediaImageMeta = {
     { label: "Cover with fallback", code: '<AspectBox ratio={1} className="rounded-md">\n	<MediaImage src={album.cover} seed={album.title} />\n</AspectBox>' },
     { label: "No image yet", code: '<AspectBox ratio={1} className="rounded-md">\n	<MediaImage seed="Low tide, high noon" />\n</AspectBox>' },
     { label: "Row thumbnail", code: '<MediaImage src={track.art} seed={track.title} className="size-12 shrink-0 rounded-sm" />' },
-    { label: "Logo, never cropped", code: '<AspectBox ratio={16 / 9} className="rounded-lg">\n	<MediaImage src={brand.logo} alt={brand.name} fit="contain" />\n</AspectBox>' }
+    { label: "Logo, never cropped", code: '<AspectBox ratio={16 / 9} className="rounded-lg">\n	<MediaImage src={brand.logo} alt={brand.name} fit="contain" />\n</AspectBox>' },
+    {
+      label: "Crop focus per image",
+      code: '<AspectBox ratio={1} className="rounded-md">\n	<MediaImage src={project.thumbnail} seed={project.title} position={project.focus ?? "center"} />\n</AspectBox>'
+    }
   ]
 };
 export {

package/dist/components/media-tile/media-tile.js

@@ -34,6 +34,7 @@ function MediaTile({
   sizes,
   alt,
   seed,
+  position,
   aspect = "square",
   size = "md",
   href,
@@ -107,7 +108,18 @@ function MediaTile({
             "data-slot": "media-tile-cover",
             className: "order-first rounded-(--media-tile-radius)",
             children: [
-              /* @__PURE__ */ jsx(MediaImage, { src, srcSet, sizes, alt, seed: seed ?? titleText, loading }),
+              /* @__PURE__ */ jsx(
+                MediaImage,
+                {
+                  src,
+                  srcSet,
+                  sizes,
+                  alt,
+                  seed: seed ?? titleText,
+                  position,
+                  loading
+                }
+              ),
               linked || action != null ? (
                 // The tile answers the pointer and the keyboard alike: a light scrim
                 // deepens the cover so the action reads over any artwork. Hover only

package/dist/components/media-tile/media-tile.meta.js

@@ -70,6 +70,12 @@ var mediaTileMeta = {
     { name: "sizes", type: "string", description: 'The cover\'s layout width for `srcSet`, e.g. `"(min-width: 64rem) 25vw, 50vw"`.' },
     { name: "alt", type: "string", default: '""', description: "Cover alt text. Empty by default: the title below already names the item." },
     { name: "seed", type: "string | number", description: "Seeds the fallback art. Defaults to `title` when it is a string." },
+    {
+      name: "position",
+      type: 'CSSProperties["objectPosition"]',
+      default: '"center"',
+      description: 'Which part of the cover the crop keeps \u2014 CSS `object-position`, forwarded to the cover\'s MediaImage: `"50% 30%"` for a face, `"top"` for a poster\'s title. Store it with the image when each one frames differently.'
+    },
     {
       name: "aspect",
       type: '"square" | "video" | "poster" | number',
@@ -130,6 +136,10 @@ var mediaTileMeta = {
       label: "Gallery, no links",
       code: '<Grid minItemWidth="8rem" gap={2}>\n	{photos.map((photo) => (\n		<MediaTile key={photo.id} size="sm" title={photo.caption} src={photo.url} alt={photo.description} />\n	))}\n</Grid>'
     },
+    {
+      label: "Portfolio grid with crop focus",
+      code: '<Grid minItemWidth="16rem" gap={4}>\n	{projects.map((project) => (\n		<MediaTile\n			key={project.slug}\n			aspect="video"\n			title={project.title}\n			subtitle={project.client}\n			src={project.thumbnail}\n			position={project.focus}\n			href={`/work/${project.slug}`}\n		/>\n	))}\n</Grid>'
+    },
     {
       label: "Poster shelf",
       code: '<MediaTile aspect="poster" size="lg" titleAs="h3" title="The Long Dark" subtitle="2026 \xB7 Drama" href="/films/the-long-dark" />'

package/dist/components/menu/menu.js

@@ -131,6 +131,7 @@ function MenuSubmenuTrigger({
   className,
   children,
   value,
+  icon,
   ...props
 }) {
   const tier = useTypeTier();
@@ -143,6 +144,7 @@ function MenuSubmenuTrigger({
       ),
       ...props,
       children: [
+        icon,
         /* @__PURE__ */ jsx("span", { className: "flex-1 truncate text-start", children }),
         value !== void 0 ? /* @__PURE__ */ jsx("span", { className: "truncate text-muted-foreground", children: value }) : null,
         /* @__PURE__ */ jsx(Icon, { name: "chevron-right", className: "text-xs opacity-60" })

package/dist/components/menu/menu.meta.js

@@ -114,8 +114,8 @@ var menuMeta = {
     },
     {
       name: "MenuSubmenuTrigger",
-      type: "Base UI Menu.SubmenuTrigger props + value: ReactNode + className",
-      description: 'The row that opens a submenu: item styling, a trailing chevron, and an optional `value` showing the current choice so the row reads "Effort  High \u203A" rather than making the reader open it to find out.'
+      type: "Base UI Menu.SubmenuTrigger props + value: ReactNode + icon: ReactNode + className",
+      description: 'The row that opens a submenu: item styling, a trailing chevron, and an optional `value` showing the current choice so the row reads "Effort  High \u203A" rather than making the reader open it to find out. `icon` leads the row as MenuItem\'s does; give it one whenever the items around it have icons, or its label starts a column to their left.'
     },
     {
       name: "MenuRadioGroup",

package/dist/components/page-header/page-header.js

@@ -2,30 +2,35 @@
 import { cn } from "../../lib/cn.js";
 import { HeadingRow } from "../../lib/heading-row.js";
 import { jsx, jsxs } from "react/jsx-runtime";
+var SIZE = {
+  md: { root: "gap-2 pb-4", title: "text-heading-2", description: "text-body-sm" },
+  lg: { root: "gap-3 pb-6", title: "text-display-lg", description: "max-w-(--measure-prose) text-body-lg" }
+};
 function PageHeader({
   title,
   description,
   back,
   actions,
   titleAs: Title = "h1",
+  size = "md",
   className,
   children,
   ...props
 }) {
-  return /* @__PURE__ */ jsxs("div", { className: cn("flex flex-col gap-2 pb-4", className), ...props, children: [
+  return /* @__PURE__ */ jsxs("div", { "data-size": size, className: cn("flex flex-col", SIZE[size].root, className), ...props, children: [
     /* @__PURE__ */ jsx(
       HeadingRow,
       {
         as: Title,
         title,
-        titleClassName: "text-heading-2",
-        band: "flex min-h-(--control-md) items-center",
+        titleClassName: SIZE[size].title,
+        band: "flex min-h-(--control-md) items-center mt-[min(0px,calc((var(--control-md)_-_1lh)/2))]",
         titleBasis: "basis-[min(100%,20rem)]",
         leading: back,
         actions
       }
     ),
-    description ? /* @__PURE__ */ jsx("p", { className: "text-body-sm text-muted-foreground", children: description }) : null,
+    description ? /* @__PURE__ */ jsx("p", { className: cn(SIZE[size].description, "text-muted-foreground"), children: description }) : null,
     children
   ] });
 }

package/dist/components/page-header/page-header.meta.js

@@ -7,7 +7,11 @@ var pageHeaderMeta = {
     "page header",
     "title",
     "lede",
-    "page actions"
+    "page actions",
+    "page title size",
+    "display title",
+    "editorial header",
+    "hero title"
   ],
   usage: {
     description: "Use PageHeader to establish a page's title, supporting description, and primary page actions.",
@@ -20,6 +24,14 @@ var pageHeaderMeta = {
         guidance: "do",
         description: "Keep the title literal and put explanation in the lede or nearby content."
       },
+      {
+        guidance: "do",
+        description: 'Use size="lg" for an editorial page (a personal site, a marketing page, an article index): a display-tier title over a body-lg lede. Pair it with SectionHeader size="lg" for the sections below, so the steps stay display \u2192 heading-2 \u2192 body.'
+      },
+      {
+        guidance: "dont",
+        description: 'Use size="lg" on product routes (settings, lists, dashboards). Display type is never product chrome: there it competes with the content it frames. Keep md, and do not restyle the title with a display class through className either.'
+      },
       {
         guidance: "dont",
         description: "Do not use PageHeader inside repeated cards, dialogs, or compact panels."
@@ -64,8 +76,17 @@ var pageHeaderMeta = {
       type: '"h1" | "h2"',
       default: '"h1"',
       description: "The title's heading element. Keep h1 \u2014 the route's one h1. Use h2 only when something above already owns the h1: a shell that renders the route title, or a page showing a PageHeader as an example."
+    },
+    {
+      name: "size",
+      type: '"md" | "lg"',
+      default: '"md"',
+      description: "The title's scale. md: text-heading-2 over a text-body-sm description, for product pages. lg: text-display-lg over a text-body-lg lede capped at the prose measure, with more space between and below, for an editorial page (personal site, marketing page, article index). Beside actions or a back control, a title line taller than the controls lifts by half the difference, so its first line stays centred on them."
     }
   ],
+  variants: {
+    size: ["md", "lg"]
+  },
   a11y: [
     "Renders the title as an <h1>; use one PageHeader per page.",
     "Its title renders the route's `h1`. Do not render another `h1` elsewhere on the page: heading navigation would report two documents, and the outline a screen-reader user builds from it stops matching the page."
@@ -76,6 +97,10 @@ var pageHeaderMeta = {
       label: "With actions",
       code: '<PageHeader title="Storage credits" description="Fund permanent storage." actions={<Button>Top up</Button>} />'
     },
+    {
+      label: "Editorial page title (size lg)",
+      code: '<PageHeader size="lg" title="Field notes" description="Essays on making things slowly, from a studio by the sea." actions={<Button variant="outline">Subscribe</Button>} />'
+    },
     {
       label: "One per page, inside the region",
       code: `// PageHeader introduces the current route: title, optional description, and the