@misoto22/design 0.7.0 → 0.9.0

package/dist/components/Dialog/Dialog.js

@@ -3,6 +3,8 @@ import { jsx, jsxs } from "react/jsx-runtime";
 import * as DialogPrimitive from "@radix-ui/react-dialog";
 import { X } from "lucide-react";
 import { cn } from "../../lib/cn.js";
+import { useOverlayContainer } from "../../lib/overlay-container.js";
+import { DEV, warn } from "../../lib/warn.js";
 const Dialog = DialogPrimitive.Root;
 const DialogTrigger = DialogPrimitive.Trigger;
 const DialogClose = DialogPrimitive.Close;
@@ -26,12 +28,25 @@ function DialogContent({
   hideTitle = false,
   ...rest
 }) {
-  return /* @__PURE__ */ jsxs(DialogPrimitive.Portal, { children: [
+  const container = useOverlayContainer();
+  if (DEV && title === void 0) {
+    warn({
+      code: "DIALOG_TITLE_MISSING",
+      problem: 'DialogContent has no title, so its accessible name is the fallback string "Dialog". Every unnamed modal in the app announces identically, and the check that would have caught it passes.',
+      field: "title",
+      fix: "Give it a title that says what the dialog asks. Add hideTitle when the heading would be furniture on screen.",
+      component: "Dialog"
+    });
+  }
+  return /* @__PURE__ */ jsxs(DialogPrimitive.Portal, { container: container ?? void 0, children: [
     /* @__PURE__ */ jsx(
       DialogPrimitive.Overlay,
       {
         "data-m22-animated": true,
-        className: "fixed inset-0 z-(--z-overlay) bg-(--scrim) data-[state=open]:animate-[m22-fade-in_var(--duration-fast)_var(--ease)]"
+        className: cn(
+          "inset-0 z-(--z-overlay) bg-(--scrim) data-[state=open]:animate-[m22-fade-in_var(--duration-fast)_var(--ease)]",
+          container ? "absolute" : "fixed"
+        )
       }
     ),
     /* @__PURE__ */ jsxs(
@@ -39,8 +54,11 @@ function DialogContent({
       {
         "data-m22-animated": true,
         className: cn(
-          "fixed left-1/2 top-1/2 z-(--z-modal) max-h-[85vh] w-[min(92vw,32rem)] -translate-x-1/2 -translate-y-1/2 overflow-auto rounded-(--radius-lg) border border-(--panel-border) bg-(--panel-bg) p-6 panel-blur scroll-slim",
+          "fixed left-1/2 top-1/2 z-(--z-modal) max-h-[85vh] w-[min(92vw,32rem)] -translate-x-1/2 -translate-y-1/2 overflow-auto rounded-(--radius-lg) border border-(--panel-border) bg-(--panel-bg) p-6 shadow-(--panel-lift) panel-blur scroll-slim",
           "data-[state=open]:animate-[m22-panel-in_var(--duration-base)_var(--ease)]",
+          // Against the container's box rather than the viewport's, and capped
+          // by it: 92vw inside a 400px frame is not a cap at all.
+          container && "absolute max-h-[calc(100%-2rem)] max-w-[calc(100%-2rem)]",
           className
         ),
         ...rest,

package/dist/components/Dialog/Dialog.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../src/components/Dialog/Dialog.tsx"],"sourcesContent":["'use client'\n\nimport * as DialogPrimitive from '@radix-ui/react-dialog'\nimport { X } from 'lucide-react'\nimport type { ComponentProps, ReactNode } from 'react'\nimport { cn } from '../../lib/cn'\n\n/** Radix Dialog root + trigger + close, re-exported as typed passthroughs. */\nexport const Dialog = DialogPrimitive.Root\nexport const DialogTrigger = DialogPrimitive.Trigger\nexport const DialogClose = DialogPrimitive.Close\n\n/** Title + description stack; renders nothing when both are omitted. */\nfunction DialogHeader({\n  title,\n  description,\n  hidden,\n}: {\n  title?: ReactNode\n  description?: ReactNode\n  hidden: boolean\n}) {\n  if (title === undefined && description === undefined) return null\n  return (\n    <div className={cn('mb-4 flex flex-col gap-1 pe-8', hidden && 'sr-only')}>\n      {title !== undefined && (\n        <DialogPrimitive.Title className=\"m-0 font-heading text-[length:var(--fs-item)] font-normal text-(--ink)\">\n          {title}\n        </DialogPrimitive.Title>\n      )}\n      {description !== undefined && (\n        <DialogPrimitive.Description className=\"m-0 text-sm leading-relaxed text-(--ink-3-aa)\">\n          {description}\n        </DialogPrimitive.Description>\n      )}\n    </div>\n  )\n}\n\nexport interface DialogContentProps\n  extends Omit<ComponentProps<typeof DialogPrimitive.Content>, 'title' | 'className'> {\n  /** Heading text. When omitted, a visually-hidden title is rendered for a11y. */\n  title?: ReactNode\n  /** Sub-heading under the title. */\n  description?: ReactNode\n  className?: string\n  /** Show the top-right close control (default true). */\n  showClose?: boolean\n  /**\n   * Keeps the title for assistive tech and hides it visually.\n   *\n   * For a surface whose purpose is obvious to anyone who can see it — a command\n   * palette, a media lightbox — where a printed heading would be furniture. The\n   * title itself is never optional: Radix requires one, and a modal with no\n   * accessible name drops a screen reader into an unnamed region.\n   */\n  hideTitle?: boolean\n}\n\n/**\n * A modal surface: portal → scrim → centred panel.\n *\n * Radix owns the focus trap, the escape key, the scroll lock and the\n * `aria-modal` wiring — all of which a hand-rolled dialog gets subtly wrong,\n * usually by leaving focus behind in the page underneath.\n *\n * Radix requires a `Dialog.Title` whether or not one is shown, so a dialog\n * without a visible heading still renders a hidden one rather than logging a\n * warning and shipping an unnamed modal.\n *\n * @example\n * <Dialog>\n *   <DialogTrigger asChild><Button>Delete</Button></DialogTrigger>\n *   <DialogContent title=\"Delete file\" description=\"This cannot be undone.\">\n *     <DialogClose asChild><Button variant=\"secondary\">Cancel</Button></DialogClose>\n *   </DialogContent>\n * </Dialog>\n */\nexport function DialogContent({\n  title,\n  description,\n  children,\n  className,\n  showClose = true,\n  hideTitle = false,\n  ...rest\n}: DialogContentProps) {\n  return (\n    <DialogPrimitive.Portal>\n      <DialogPrimitive.Overlay\n        data-m22-animated\n        className=\"fixed inset-0 z-(--z-overlay) bg-(--scrim) data-[state=open]:animate-[m22-fade-in_var(--duration-fast)_var(--ease)]\"\n      />\n      <DialogPrimitive.Content\n        data-m22-animated\n        className={cn(\n          'fixed left-1/2 top-1/2 z-(--z-modal) max-h-[85vh] w-[min(92vw,32rem)] -translate-x-1/2 -translate-y-1/2 overflow-auto rounded-(--radius-lg) border border-(--panel-border) bg-(--panel-bg) p-6 panel-blur scroll-slim',\n          'data-[state=open]:animate-[m22-panel-in_var(--duration-base)_var(--ease)]',\n          className,\n        )}\n        {...rest}\n      >\n        <DialogHeader title={title} description={description} hidden={hideTitle} />\n\n        {title === undefined && (\n          <DialogPrimitive.Title className=\"sr-only\">Dialog</DialogPrimitive.Title>\n        )}\n\n        {showClose && (\n          <DialogPrimitive.Close\n            aria-label=\"Close\"\n            className=\"absolute end-3 top-3 grid size-9 place-items-center rounded-(--radius-pill) text-(--ink-3-aa) transition-colors duration-(--duration-fast) hover:bg-(--stone) hover:text-(--ink)\"\n          >\n            <X size={16} strokeWidth={1.5} aria-hidden />\n          </DialogPrimitive.Close>\n        )}\n\n        {children}\n      </DialogPrimitive.Content>\n    </DialogPrimitive.Portal>\n  )\n}\n\nexport default Dialog\n"],"mappings":";AAwBI,SAEI,KAFJ;AAtBJ,YAAY,qBAAqB;AACjC,SAAS,SAAS;AAElB,SAAS,UAAU;AAGZ,MAAM,SAAS,gBAAgB;AAC/B,MAAM,gBAAgB,gBAAgB;AACtC,MAAM,cAAc,gBAAgB;AAG3C,SAAS,aAAa;AAAA,EACpB;AAAA,EACA;AAAA,EACA;AACF,GAIG;AACD,MAAI,UAAU,UAAa,gBAAgB,OAAW,QAAO;AAC7D,SACE,qBAAC,SAAI,WAAW,GAAG,iCAAiC,UAAU,SAAS,GACpE;AAAA,cAAU,UACT,oBAAC,gBAAgB,OAAhB,EAAsB,WAAU,0EAC9B,iBACH;AAAA,IAED,gBAAgB,UACf,oBAAC,gBAAgB,aAAhB,EAA4B,WAAU,iDACpC,uBACH;AAAA,KAEJ;AAEJ;AAyCO,SAAS,cAAc;AAAA,EAC5B;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA,YAAY;AAAA,EACZ,YAAY;AAAA,EACZ,GAAG;AACL,GAAuB;AACrB,SACE,qBAAC,gBAAgB,QAAhB,EACC;AAAA;AAAA,MAAC,gBAAgB;AAAA,MAAhB;AAAA,QACC,qBAAiB;AAAA,QACjB,WAAU;AAAA;AAAA,IACZ;AAAA,IACA;AAAA,MAAC,gBAAgB;AAAA,MAAhB;AAAA,QACC,qBAAiB;AAAA,QACjB,WAAW;AAAA,UACT;AAAA,UACA;AAAA,UACA;AAAA,QACF;AAAA,QACC,GAAG;AAAA,QAEJ;AAAA,8BAAC,gBAAa,OAAc,aAA0B,QAAQ,WAAW;AAAA,UAExE,UAAU,UACT,oBAAC,gBAAgB,OAAhB,EAAsB,WAAU,WAAU,oBAAM;AAAA,UAGlD,aACC;AAAA,YAAC,gBAAgB;AAAA,YAAhB;AAAA,cACC,cAAW;AAAA,cACX,WAAU;AAAA,cAEV,8BAAC,KAAE,MAAM,IAAI,aAAa,KAAK,eAAW,MAAC;AAAA;AAAA,UAC7C;AAAA,UAGD;AAAA;AAAA;AAAA,IACH;AAAA,KACF;AAEJ;AAEA,IAAO,iBAAQ;","names":[]}
+{"version":3,"sources":["../../../src/components/Dialog/Dialog.tsx"],"sourcesContent":["'use client'\n\nimport * as DialogPrimitive from '@radix-ui/react-dialog'\nimport { X } from 'lucide-react'\nimport type { ComponentProps, ReactNode } from 'react'\nimport { cn } from '../../lib/cn'\nimport { useOverlayContainer } from '../../lib/overlay-container'\nimport { DEV, warn } from '../../lib/warn'\n\n/** Radix Dialog root + trigger + close, re-exported as typed passthroughs. */\nexport const Dialog = DialogPrimitive.Root\nexport const DialogTrigger = DialogPrimitive.Trigger\nexport const DialogClose = DialogPrimitive.Close\n\n/** Title + description stack; renders nothing when both are omitted. */\nfunction DialogHeader({\n  title,\n  description,\n  hidden,\n}: {\n  title?: ReactNode\n  description?: ReactNode\n  hidden: boolean\n}) {\n  if (title === undefined && description === undefined) return null\n  return (\n    <div className={cn('mb-4 flex flex-col gap-1 pe-8', hidden && 'sr-only')}>\n      {title !== undefined && (\n        <DialogPrimitive.Title className=\"m-0 font-heading text-[length:var(--fs-item)] font-normal text-(--ink)\">\n          {title}\n        </DialogPrimitive.Title>\n      )}\n      {description !== undefined && (\n        <DialogPrimitive.Description className=\"m-0 text-sm leading-relaxed text-(--ink-3-aa)\">\n          {description}\n        </DialogPrimitive.Description>\n      )}\n    </div>\n  )\n}\n\nexport interface DialogContentProps\n  extends Omit<ComponentProps<typeof DialogPrimitive.Content>, 'title' | 'className'> {\n  /**\n   * Heading text.\n   *\n   * Pass one even when `hideTitle` is set. Radix requires a title, so omitting\n   * it renders a hidden fallback reading the literal word \"Dialog\" — which\n   * satisfies an automated accessibility check and announces every unnamed\n   * modal in the application as the same thing. Development says so out loud.\n   */\n  title?: ReactNode\n  /** Sub-heading under the title. */\n  description?: ReactNode\n  className?: string\n  /** Show the top-right close control (default true). */\n  showClose?: boolean\n  /**\n   * Keeps the title for assistive tech and hides it visually.\n   *\n   * For a surface whose purpose is obvious to anyone who can see it — a command\n   * palette, a media lightbox — where a printed heading would be furniture. The\n   * title itself is never optional: Radix requires one, and a modal with no\n   * accessible name drops a screen reader into an unnamed region.\n   */\n  hideTitle?: boolean\n}\n\n/**\n * A modal surface: portal → scrim → centred panel.\n *\n * Radix owns the focus trap, the escape key, the scroll lock and the\n * `aria-modal` wiring — all of which a hand-rolled dialog gets subtly wrong,\n * usually by leaving focus behind in the page underneath.\n *\n * Radix requires a `Dialog.Title` whether or not one is shown, so a dialog\n * without a visible heading still renders a hidden one rather than shipping an\n * unnamed modal — and warns in development, because the fallback it renders is\n * the literal word \"Dialog\" and a placeholder that passes an accessibility\n * check is how the problem survives a review.\n *\n * Portals into the element an enclosing `OverlayContainer` names, and switches\n * from viewport positioning to container positioning when there is one. A\n * `fixed` panel covers the page whatever it is portalled into, so honouring\n * the container without that swap would have moved the markup and left the\n * picture unchanged.\n *\n * @example\n * <Dialog>\n *   <DialogTrigger asChild><Button>Delete</Button></DialogTrigger>\n *   <DialogContent title=\"Delete file\" description=\"This cannot be undone.\">\n *     <DialogClose asChild><Button variant=\"secondary\">Cancel</Button></DialogClose>\n *   </DialogContent>\n * </Dialog>\n */\nexport function DialogContent({\n  title,\n  description,\n  children,\n  className,\n  showClose = true,\n  hideTitle = false,\n  ...rest\n}: DialogContentProps) {\n  const container = useOverlayContainer()\n\n  if (DEV && title === undefined) {\n    warn({\n      code: 'DIALOG_TITLE_MISSING',\n      problem:\n        'DialogContent has no title, so its accessible name is the fallback string \"Dialog\". Every unnamed modal in the app announces identically, and the check that would have caught it passes.',\n      field: 'title',\n      fix: 'Give it a title that says what the dialog asks. Add hideTitle when the heading would be furniture on screen.',\n      component: 'Dialog',\n    })\n  }\n\n  return (\n    <DialogPrimitive.Portal container={container ?? undefined}>\n      <DialogPrimitive.Overlay\n        data-m22-animated\n        className={cn(\n          'inset-0 z-(--z-overlay) bg-(--scrim) data-[state=open]:animate-[m22-fade-in_var(--duration-fast)_var(--ease)]',\n          container ? 'absolute' : 'fixed',\n        )}\n      />\n      <DialogPrimitive.Content\n        data-m22-animated\n        className={cn(\n          'fixed left-1/2 top-1/2 z-(--z-modal) max-h-[85vh] w-[min(92vw,32rem)] -translate-x-1/2 -translate-y-1/2 overflow-auto rounded-(--radius-lg) border border-(--panel-border) bg-(--panel-bg) p-6 shadow-(--panel-lift) panel-blur scroll-slim',\n          'data-[state=open]:animate-[m22-panel-in_var(--duration-base)_var(--ease)]',\n          // Against the container's box rather than the viewport's, and capped\n          // by it: 92vw inside a 400px frame is not a cap at all.\n          container && 'absolute max-h-[calc(100%-2rem)] max-w-[calc(100%-2rem)]',\n          className,\n        )}\n        {...rest}\n      >\n        <DialogHeader title={title} description={description} hidden={hideTitle} />\n\n        {title === undefined && (\n          <DialogPrimitive.Title className=\"sr-only\">Dialog</DialogPrimitive.Title>\n        )}\n\n        {showClose && (\n          <DialogPrimitive.Close\n            aria-label=\"Close\"\n            className=\"absolute end-3 top-3 grid size-9 place-items-center rounded-(--radius-pill) text-(--ink-3-aa) transition-colors duration-(--duration-fast) hover:bg-(--stone) hover:text-(--ink)\"\n          >\n            <X size={16} strokeWidth={1.5} aria-hidden />\n          </DialogPrimitive.Close>\n        )}\n\n        {children}\n      </DialogPrimitive.Content>\n    </DialogPrimitive.Portal>\n  )\n}\n\nexport default Dialog\n"],"mappings":";AA0BI,SAEI,KAFJ;AAxBJ,YAAY,qBAAqB;AACjC,SAAS,SAAS;AAElB,SAAS,UAAU;AACnB,SAAS,2BAA2B;AACpC,SAAS,KAAK,YAAY;AAGnB,MAAM,SAAS,gBAAgB;AAC/B,MAAM,gBAAgB,gBAAgB;AACtC,MAAM,cAAc,gBAAgB;AAG3C,SAAS,aAAa;AAAA,EACpB;AAAA,EACA;AAAA,EACA;AACF,GAIG;AACD,MAAI,UAAU,UAAa,gBAAgB,OAAW,QAAO;AAC7D,SACE,qBAAC,SAAI,WAAW,GAAG,iCAAiC,UAAU,SAAS,GACpE;AAAA,cAAU,UACT,oBAAC,gBAAgB,OAAhB,EAAsB,WAAU,0EAC9B,iBACH;AAAA,IAED,gBAAgB,UACf,oBAAC,gBAAgB,aAAhB,EAA4B,WAAU,iDACpC,uBACH;AAAA,KAEJ;AAEJ;AAwDO,SAAS,cAAc;AAAA,EAC5B;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA,YAAY;AAAA,EACZ,YAAY;AAAA,EACZ,GAAG;AACL,GAAuB;AACrB,QAAM,YAAY,oBAAoB;AAEtC,MAAI,OAAO,UAAU,QAAW;AAC9B,SAAK;AAAA,MACH,MAAM;AAAA,MACN,SACE;AAAA,MACF,OAAO;AAAA,MACP,KAAK;AAAA,MACL,WAAW;AAAA,IACb,CAAC;AAAA,EACH;AAEA,SACE,qBAAC,gBAAgB,QAAhB,EAAuB,WAAW,aAAa,QAC9C;AAAA;AAAA,MAAC,gBAAgB;AAAA,MAAhB;AAAA,QACC,qBAAiB;AAAA,QACjB,WAAW;AAAA,UACT;AAAA,UACA,YAAY,aAAa;AAAA,QAC3B;AAAA;AAAA,IACF;AAAA,IACA;AAAA,MAAC,gBAAgB;AAAA,MAAhB;AAAA,QACC,qBAAiB;AAAA,QACjB,WAAW;AAAA,UACT;AAAA,UACA;AAAA;AAAA;AAAA,UAGA,aAAa;AAAA,UACb;AAAA,QACF;AAAA,QACC,GAAG;AAAA,QAEJ;AAAA,8BAAC,gBAAa,OAAc,aAA0B,QAAQ,WAAW;AAAA,UAExE,UAAU,UACT,oBAAC,gBAAgB,OAAhB,EAAsB,WAAU,WAAU,oBAAM;AAAA,UAGlD,aACC;AAAA,YAAC,gBAAgB;AAAA,YAAhB;AAAA,cACC,cAAW;AAAA,cACX,WAAU;AAAA,cAEV,8BAAC,KAAE,MAAM,IAAI,aAAa,KAAK,eAAW,MAAC;AAAA;AAAA,UAC7C;AAAA,UAGD;AAAA;AAAA;AAAA,IACH;AAAA,KACF;AAEJ;AAEA,IAAO,iBAAQ;","names":[]}

package/dist/components/DropdownMenu/DropdownMenu.d.ts

@@ -1,5 +1,5 @@
 import * as react from 'react';
-import { ComponentProps } from 'react';
+import { ComponentProps, ReactNode } from 'react';
 import * as DropdownMenuPrimitive from '@radix-ui/react-dropdown-menu';
 import { LucideIcon } from 'lucide-react';
 
@@ -11,16 +11,17 @@ type DropdownMenuContentProps = ComponentProps<typeof DropdownMenuPrimitive.Cont
  * A menu surface.
  *
  * A menu is a list of ACTIONS. If the items navigate somewhere, they belong in
- * a nav; if they set a value, that is a `Select` or a `RadioGroup` — Radix has
- * menu variants for both, and a plain item pretending to be a choice loses the
- * checked state a screen reader needs.
+ * a nav; if they set a value, that is a `Select` or a `RadioGroup` — this
+ * package ships no checkbox or radio menu item, and a plain item pretending to
+ * be a choice loses the checked state a screen reader needs.
  *
  * @example
  * <DropdownMenu>
  *   <DropdownMenuTrigger asChild><Button variant="secondary">Menu</Button></DropdownMenuTrigger>
  *   <DropdownMenuContent>
- *     <DropdownMenuLabel>Account</DropdownMenuLabel>
- *     <DropdownMenuItem icon={Settings}>Settings</DropdownMenuItem>
+ *     <DropdownMenuGroup label="Account">
+ *       <DropdownMenuItem icon={Settings}>Settings</DropdownMenuItem>
+ *     </DropdownMenuGroup>
  *     <DropdownMenuSeparator />
  *     <DropdownMenuItem icon={LogOut}>Sign out</DropdownMenuItem>
  *   </DropdownMenuContent>
@@ -28,8 +29,16 @@ type DropdownMenuContentProps = ComponentProps<typeof DropdownMenuPrimitive.Cont
  */
 declare function DropdownMenuContent({ className, sideOffset, children, ...rest }: DropdownMenuContentProps): react.JSX.Element;
 interface DropdownMenuItemProps extends ComponentProps<typeof DropdownMenuPrimitive.Item> {
-    /** Optional leading icon, rendered before the label. */
-    icon?: LucideIcon;
+    /**
+     * Optional leading icon, rendered before the label.
+     *
+     * Either spelling: `icon={Settings}` passes the component and this sizes it,
+     * `icon={<Settings size={16} />}` passes the element and this places it. The
+     * two used to mean opposite things one import apart — `CommandItem.icon` took
+     * the element while this took the component — and the wrong one did not fail
+     * a type check into anything actionable, it failed at render.
+     */
+    icon?: LucideIcon | ReactNode;
     /** Paints the row as destructive. Use for delete, revoke, disconnect. */
     destructive?: boolean;
 }
@@ -40,10 +49,39 @@ interface DropdownMenuItemProps extends ComponentProps<typeof DropdownMenuPrimit
  * hover and keyboard focus — styling `:hover` alone leaves the keyboard user
  * unable to see where they are.
  */
-declare function DropdownMenuItem({ icon: Icon, destructive, className, children, ...rest }: DropdownMenuItemProps): react.JSX.Element;
+declare function DropdownMenuItem({ icon, destructive, className, children, ...rest }: DropdownMenuItemProps): react.JSX.Element;
 /** Hairline divider between menu groups. */
 declare function DropdownMenuSeparator({ className, ...rest }: ComponentProps<typeof DropdownMenuPrimitive.Separator>): react.JSX.Element;
-/** Mono eyebrow heading for a group of items. */
+/**
+ * Mono eyebrow heading, on its own.
+ *
+ * Visual only: Radix renders it as a bare `<div>` with no role, so it segments
+ * the menu for a reader who can see it and for nobody else. Reach for
+ * `DropdownMenuGroup` when the eyebrow is a HEADING over rows; this is right
+ * for a line that heads nothing — the signed-in address at the top of an
+ * account menu.
+ */
 declare function DropdownMenuLabel({ className, ...rest }: ComponentProps<typeof DropdownMenuPrimitive.Label>): react.JSX.Element;
+interface DropdownMenuGroupProps extends ComponentProps<typeof DropdownMenuPrimitive.Group> {
+    /** The eyebrow over the rows, and the group's accessible name. */
+    label?: ReactNode;
+}
+/**
+ * A named section of a menu.
+ *
+ * The eyebrow alone was a picture of a heading. Radix's `MenuLabel` carries no
+ * role and no `aria-labelledby` wiring, and `MenuGroup` — which does carry
+ * `role="group"` — was not re-exported by this package at all, so a sighted
+ * reader saw three labelled sections and a screen-reader user got one
+ * undifferentiated list. This renders the group, renders the label inside it,
+ * and points the one at the other, which is the whole of the fix and not
+ * something a caller should have to remember.
+ *
+ * @example
+ * <DropdownMenuGroup label="Account">
+ *   <DropdownMenuItem icon={Settings}>Settings</DropdownMenuItem>
+ * </DropdownMenuGroup>
+ */
+declare function DropdownMenuGroup({ label, children, ...rest }: DropdownMenuGroupProps): react.JSX.Element;
 
-export { DropdownMenu, DropdownMenuContent, type DropdownMenuContentProps, DropdownMenuItem, type DropdownMenuItemProps, DropdownMenuLabel, DropdownMenuSeparator, DropdownMenuTrigger, DropdownMenu as default };
+export { DropdownMenu, DropdownMenuContent, type DropdownMenuContentProps, DropdownMenuGroup, type DropdownMenuGroupProps, DropdownMenuItem, type DropdownMenuItemProps, DropdownMenuLabel, DropdownMenuSeparator, DropdownMenuTrigger, DropdownMenu as default };

package/dist/components/DropdownMenu/DropdownMenu.js

@@ -1,8 +1,23 @@
 "use client";
 import { jsx, jsxs } from "react/jsx-runtime";
 import * as DropdownMenuPrimitive from "@radix-ui/react-dropdown-menu";
+import { isValidElement, useId } from "react";
 import { cn } from "../../lib/cn.js";
 import { useOverlayContainer } from "../../lib/overlay-container.js";
+function isIconComponent(icon) {
+  if (isValidElement(icon)) return false;
+  if (typeof icon === "function") return true;
+  if (typeof icon !== "object" || icon === null) return false;
+  return !Array.isArray(icon) && !(Symbol.iterator in icon) && !("then" in icon);
+}
+function iconNode(icon) {
+  if (icon === void 0 || icon === null || icon === false) return null;
+  if (!isIconComponent(icon)) {
+    return /* @__PURE__ */ jsx("span", { "aria-hidden": true, className: "grid size-4 shrink-0 place-items-center [&_svg]:size-4", children: icon });
+  }
+  const Icon = icon;
+  return /* @__PURE__ */ jsx(Icon, { size: 16, strokeWidth: 1.5, className: "shrink-0", "aria-hidden": true });
+}
 const DropdownMenu = DropdownMenuPrimitive.Root;
 const DropdownMenuTrigger = DropdownMenuPrimitive.Trigger;
 function DropdownMenuContent({
@@ -20,7 +35,7 @@ function DropdownMenuContent({
       sideOffset,
       "data-m22-animated": true,
       className: cn(
-        "z-(--z-dropdown) min-w-44 rounded-(--radius-lg) border border-(--panel-border) bg-(--panel-bg) p-1.5 panel-blur",
+        "z-(--z-dropdown) min-w-44 rounded-(--radius-lg) border border-(--panel-border) bg-(--panel-bg) p-1.5 shadow-(--panel-lift) panel-blur",
         "data-[state=open]:animate-[m22-pop-in_var(--duration-fast)_var(--ease-out-expo)] data-[state=closed]:animate-[m22-pop-out_var(--duration-fast)_var(--ease)] origin-(--radix-popper-transform-origin)",
         className
       ),
@@ -30,7 +45,7 @@ function DropdownMenuContent({
   ) });
 }
 function DropdownMenuItem({
-  icon: Icon,
+  icon,
   destructive = false,
   className,
   children,
@@ -46,7 +61,7 @@ function DropdownMenuItem({
       ),
       ...rest,
       children: [
-        Icon && /* @__PURE__ */ jsx(Icon, { size: 16, strokeWidth: 1.5, className: "shrink-0", "aria-hidden": true }),
+        iconNode(icon),
         children
       ]
     }
@@ -76,10 +91,25 @@ function DropdownMenuLabel({
     }
   );
 }
+function DropdownMenuGroup({ label, children, ...rest }) {
+  const id = useId();
+  return /* @__PURE__ */ jsxs(
+    DropdownMenuPrimitive.Group,
+    {
+      "aria-labelledby": label === void 0 ? void 0 : id,
+      ...rest,
+      children: [
+        label !== void 0 && /* @__PURE__ */ jsx(DropdownMenuLabel, { id, children: label }),
+        children
+      ]
+    }
+  );
+}
 var DropdownMenu_default = DropdownMenu;
 export {
   DropdownMenu,
   DropdownMenuContent,
+  DropdownMenuGroup,
   DropdownMenuItem,
   DropdownMenuLabel,
   DropdownMenuSeparator,

package/dist/components/DropdownMenu/DropdownMenu.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../src/components/DropdownMenu/DropdownMenu.tsx"],"sourcesContent":["'use client'\n\nimport * as DropdownMenuPrimitive from '@radix-ui/react-dropdown-menu'\nimport type { LucideIcon } from 'lucide-react'\nimport type { ComponentProps } from 'react'\nimport { cn } from '../../lib/cn'\nimport { useOverlayContainer } from '../../lib/overlay-container'\n\n/** Radix DropdownMenu root + trigger, re-exported as typed passthroughs. */\nexport const DropdownMenu = DropdownMenuPrimitive.Root\nexport const DropdownMenuTrigger = DropdownMenuPrimitive.Trigger\n\nexport type DropdownMenuContentProps = ComponentProps<typeof DropdownMenuPrimitive.Content>\n\n/**\n * A menu surface.\n *\n * A menu is a list of ACTIONS. If the items navigate somewhere, they belong in\n * a nav; if they set a value, that is a `Select` or a `RadioGroup` — Radix has\n * menu variants for both, and a plain item pretending to be a choice loses the\n * checked state a screen reader needs.\n *\n * @example\n * <DropdownMenu>\n *   <DropdownMenuTrigger asChild><Button variant=\"secondary\">Menu</Button></DropdownMenuTrigger>\n *   <DropdownMenuContent>\n *     <DropdownMenuLabel>Account</DropdownMenuLabel>\n *     <DropdownMenuItem icon={Settings}>Settings</DropdownMenuItem>\n *     <DropdownMenuSeparator />\n *     <DropdownMenuItem icon={LogOut}>Sign out</DropdownMenuItem>\n *   </DropdownMenuContent>\n * </DropdownMenu>\n */\nexport function DropdownMenuContent({\n  className,\n  sideOffset = 6,\n  children,\n  ...rest\n}: DropdownMenuContentProps) {\n  const container = useOverlayContainer()\n\n  return (\n    <DropdownMenuPrimitive.Portal container={container ?? undefined}>\n      <DropdownMenuPrimitive.Content\n        collisionBoundary={container ?? undefined}\n        collisionPadding={8}\n        sideOffset={sideOffset}\n        data-m22-animated\n        className={cn(\n          'z-(--z-dropdown) min-w-44 rounded-(--radius-lg) border border-(--panel-border) bg-(--panel-bg) p-1.5 panel-blur',\n          'data-[state=open]:animate-[m22-pop-in_var(--duration-fast)_var(--ease-out-expo)] data-[state=closed]:animate-[m22-pop-out_var(--duration-fast)_var(--ease)] origin-(--radix-popper-transform-origin)',\n          className,\n        )}\n        {...rest}\n      >\n        {children}\n      </DropdownMenuPrimitive.Content>\n    </DropdownMenuPrimitive.Portal>\n  )\n}\n\nexport interface DropdownMenuItemProps extends ComponentProps<typeof DropdownMenuPrimitive.Item> {\n  /** Optional leading icon, rendered before the label. */\n  icon?: LucideIcon\n  /** Paints the row as destructive. Use for delete, revoke, disconnect. */\n  destructive?: boolean\n}\n\n/**\n * A menu row.\n *\n * Highlight is driven by Radix's `data-highlighted`, which covers both pointer\n * hover and keyboard focus — styling `:hover` alone leaves the keyboard user\n * unable to see where they are.\n */\nexport function DropdownMenuItem({\n  icon: Icon,\n  destructive = false,\n  className,\n  children,\n  ...rest\n}: DropdownMenuItemProps) {\n  return (\n    <DropdownMenuPrimitive.Item\n      className={cn(\n        'flex cursor-pointer items-center gap-2.5 rounded-(--radius-row) px-2.5 py-2 text-sm outline-none transition-colors duration-(--duration-fast) data-[highlighted]:bg-(--stone) data-[disabled]:pointer-events-none data-[disabled]:opacity-(--disabled-opacity)',\n        destructive ? 'text-(--danger)' : 'text-(--ink-2) data-[highlighted]:text-(--ink)',\n        className,\n      )}\n      {...rest}\n    >\n      {Icon && <Icon size={16} strokeWidth={1.5} className=\"shrink-0\" aria-hidden />}\n      {children}\n    </DropdownMenuPrimitive.Item>\n  )\n}\n\n/** Hairline divider between menu groups. */\nexport function DropdownMenuSeparator({\n  className,\n  ...rest\n}: ComponentProps<typeof DropdownMenuPrimitive.Separator>) {\n  return (\n    <DropdownMenuPrimitive.Separator\n      className={cn('my-1 h-px bg-(--rule)', className)}\n      {...rest}\n    />\n  )\n}\n\n/** Mono eyebrow heading for a group of items. */\nexport function DropdownMenuLabel({\n  className,\n  ...rest\n}: ComponentProps<typeof DropdownMenuPrimitive.Label>) {\n  return (\n    <DropdownMenuPrimitive.Label\n      className={cn('px-2.5 py-1.5 eyebrow text-(--ink-3-aa)', className)}\n      {...rest}\n    />\n  )\n}\n\nexport default DropdownMenu\n"],"mappings":";AA2CM,cAwCF,YAxCE;AAzCN,YAAY,2BAA2B;AAGvC,SAAS,UAAU;AACnB,SAAS,2BAA2B;AAG7B,MAAM,eAAe,sBAAsB;AAC3C,MAAM,sBAAsB,sBAAsB;AAuBlD,SAAS,oBAAoB;AAAA,EAClC;AAAA,EACA,aAAa;AAAA,EACb;AAAA,EACA,GAAG;AACL,GAA6B;AAC3B,QAAM,YAAY,oBAAoB;AAEtC,SACE,oBAAC,sBAAsB,QAAtB,EAA6B,WAAW,aAAa,QACpD;AAAA,IAAC,sBAAsB;AAAA,IAAtB;AAAA,MACC,mBAAmB,aAAa;AAAA,MAChC,kBAAkB;AAAA,MAClB;AAAA,MACA,qBAAiB;AAAA,MACjB,WAAW;AAAA,QACT;AAAA,QACA;AAAA,QACA;AAAA,MACF;AAAA,MACC,GAAG;AAAA,MAEH;AAAA;AAAA,EACH,GACF;AAEJ;AAgBO,SAAS,iBAAiB;AAAA,EAC/B,MAAM;AAAA,EACN,cAAc;AAAA,EACd;AAAA,EACA;AAAA,EACA,GAAG;AACL,GAA0B;AACxB,SACE;AAAA,IAAC,sBAAsB;AAAA,IAAtB;AAAA,MACC,WAAW;AAAA,QACT;AAAA,QACA,cAAc,oBAAoB;AAAA,QAClC;AAAA,MACF;AAAA,MACC,GAAG;AAAA,MAEH;AAAA,gBAAQ,oBAAC,QAAK,MAAM,IAAI,aAAa,KAAK,WAAU,YAAW,eAAW,MAAC;AAAA,QAC3E;AAAA;AAAA;AAAA,EACH;AAEJ;AAGO,SAAS,sBAAsB;AAAA,EACpC;AAAA,EACA,GAAG;AACL,GAA2D;AACzD,SACE;AAAA,IAAC,sBAAsB;AAAA,IAAtB;AAAA,MACC,WAAW,GAAG,yBAAyB,SAAS;AAAA,MAC/C,GAAG;AAAA;AAAA,EACN;AAEJ;AAGO,SAAS,kBAAkB;AAAA,EAChC;AAAA,EACA,GAAG;AACL,GAAuD;AACrD,SACE;AAAA,IAAC,sBAAsB;AAAA,IAAtB;AAAA,MACC,WAAW,GAAG,2CAA2C,SAAS;AAAA,MACjE,GAAG;AAAA;AAAA,EACN;AAEJ;AAEA,IAAO,uBAAQ;","names":[]}
+{"version":3,"sources":["../../../src/components/DropdownMenu/DropdownMenu.tsx"],"sourcesContent":["'use client'\n\nimport * as DropdownMenuPrimitive from '@radix-ui/react-dropdown-menu'\nimport type { LucideIcon } from 'lucide-react'\nimport { isValidElement, useId, type ComponentProps, type ReactNode } from 'react'\nimport { cn } from '../../lib/cn'\nimport { useOverlayContainer } from '../../lib/overlay-container'\n\n/**\n * True for a component type — `icon={Settings}` — rather than a rendered element.\n *\n * Everything a `ReactNode` can be is an element, a primitive, an array, another\n * iterable or a promise; a Lucide icon is none of those, it is a `forwardRef`\n * object. So both spellings are tellable apart at runtime, which is what lets\n * one prop take either — and it has to, because this prop meant the opposite\n * thing one import away and the wrong spelling failed at render, not at the\n * type.\n */\nfunction isIconComponent(icon: LucideIcon | ReactNode): icon is LucideIcon {\n  if (isValidElement(icon)) return false\n  if (typeof icon === 'function') return true\n  if (typeof icon !== 'object' || icon === null) return false\n  return !Array.isArray(icon) && !(Symbol.iterator in icon) && !('then' in icon)\n}\n\n/** The leading glyph, sized by this component when it was handed a component. */\nfunction iconNode(icon: LucideIcon | ReactNode): ReactNode {\n  if (icon === undefined || icon === null || icon === false) return null\n  if (!isIconComponent(icon)) {\n    return (\n      <span aria-hidden className=\"grid size-4 shrink-0 place-items-center [&_svg]:size-4\">\n        {icon}\n      </span>\n    )\n  }\n  const Icon = icon\n  return <Icon size={16} strokeWidth={1.5} className=\"shrink-0\" aria-hidden />\n}\n\n/** Radix DropdownMenu root + trigger, re-exported as typed passthroughs. */\nexport const DropdownMenu = DropdownMenuPrimitive.Root\nexport const DropdownMenuTrigger = DropdownMenuPrimitive.Trigger\n\nexport type DropdownMenuContentProps = ComponentProps<typeof DropdownMenuPrimitive.Content>\n\n/**\n * A menu surface.\n *\n * A menu is a list of ACTIONS. If the items navigate somewhere, they belong in\n * a nav; if they set a value, that is a `Select` or a `RadioGroup` — this\n * package ships no checkbox or radio menu item, and a plain item pretending to\n * be a choice loses the checked state a screen reader needs.\n *\n * @example\n * <DropdownMenu>\n *   <DropdownMenuTrigger asChild><Button variant=\"secondary\">Menu</Button></DropdownMenuTrigger>\n *   <DropdownMenuContent>\n *     <DropdownMenuGroup label=\"Account\">\n *       <DropdownMenuItem icon={Settings}>Settings</DropdownMenuItem>\n *     </DropdownMenuGroup>\n *     <DropdownMenuSeparator />\n *     <DropdownMenuItem icon={LogOut}>Sign out</DropdownMenuItem>\n *   </DropdownMenuContent>\n * </DropdownMenu>\n */\nexport function DropdownMenuContent({\n  className,\n  sideOffset = 6,\n  children,\n  ...rest\n}: DropdownMenuContentProps) {\n  const container = useOverlayContainer()\n\n  return (\n    <DropdownMenuPrimitive.Portal container={container ?? undefined}>\n      <DropdownMenuPrimitive.Content\n        collisionBoundary={container ?? undefined}\n        collisionPadding={8}\n        sideOffset={sideOffset}\n        data-m22-animated\n        className={cn(\n          'z-(--z-dropdown) min-w-44 rounded-(--radius-lg) border border-(--panel-border) bg-(--panel-bg) p-1.5 shadow-(--panel-lift) panel-blur',\n          'data-[state=open]:animate-[m22-pop-in_var(--duration-fast)_var(--ease-out-expo)] data-[state=closed]:animate-[m22-pop-out_var(--duration-fast)_var(--ease)] origin-(--radix-popper-transform-origin)',\n          className,\n        )}\n        {...rest}\n      >\n        {children}\n      </DropdownMenuPrimitive.Content>\n    </DropdownMenuPrimitive.Portal>\n  )\n}\n\nexport interface DropdownMenuItemProps extends ComponentProps<typeof DropdownMenuPrimitive.Item> {\n  /**\n   * Optional leading icon, rendered before the label.\n   *\n   * Either spelling: `icon={Settings}` passes the component and this sizes it,\n   * `icon={<Settings size={16} />}` passes the element and this places it. The\n   * two used to mean opposite things one import apart — `CommandItem.icon` took\n   * the element while this took the component — and the wrong one did not fail\n   * a type check into anything actionable, it failed at render.\n   */\n  icon?: LucideIcon | ReactNode\n  /** Paints the row as destructive. Use for delete, revoke, disconnect. */\n  destructive?: boolean\n}\n\n/**\n * A menu row.\n *\n * Highlight is driven by Radix's `data-highlighted`, which covers both pointer\n * hover and keyboard focus — styling `:hover` alone leaves the keyboard user\n * unable to see where they are.\n */\nexport function DropdownMenuItem({\n  icon,\n  destructive = false,\n  className,\n  children,\n  ...rest\n}: DropdownMenuItemProps) {\n  return (\n    <DropdownMenuPrimitive.Item\n      className={cn(\n        'flex cursor-pointer items-center gap-2.5 rounded-(--radius-row) px-2.5 py-2 text-sm outline-none transition-colors duration-(--duration-fast) data-[highlighted]:bg-(--stone) data-[disabled]:pointer-events-none data-[disabled]:opacity-(--disabled-opacity)',\n        destructive ? 'text-(--danger)' : 'text-(--ink-2) data-[highlighted]:text-(--ink)',\n        className,\n      )}\n      {...rest}\n    >\n      {iconNode(icon)}\n      {children}\n    </DropdownMenuPrimitive.Item>\n  )\n}\n\n/** Hairline divider between menu groups. */\nexport function DropdownMenuSeparator({\n  className,\n  ...rest\n}: ComponentProps<typeof DropdownMenuPrimitive.Separator>) {\n  return (\n    <DropdownMenuPrimitive.Separator\n      className={cn('my-1 h-px bg-(--rule)', className)}\n      {...rest}\n    />\n  )\n}\n\n/**\n * Mono eyebrow heading, on its own.\n *\n * Visual only: Radix renders it as a bare `<div>` with no role, so it segments\n * the menu for a reader who can see it and for nobody else. Reach for\n * `DropdownMenuGroup` when the eyebrow is a HEADING over rows; this is right\n * for a line that heads nothing — the signed-in address at the top of an\n * account menu.\n */\nexport function DropdownMenuLabel({\n  className,\n  ...rest\n}: ComponentProps<typeof DropdownMenuPrimitive.Label>) {\n  return (\n    <DropdownMenuPrimitive.Label\n      className={cn('px-2.5 py-1.5 eyebrow text-(--ink-3-aa)', className)}\n      {...rest}\n    />\n  )\n}\n\nexport interface DropdownMenuGroupProps\n  extends ComponentProps<typeof DropdownMenuPrimitive.Group> {\n  /** The eyebrow over the rows, and the group's accessible name. */\n  label?: ReactNode\n}\n\n/**\n * A named section of a menu.\n *\n * The eyebrow alone was a picture of a heading. Radix's `MenuLabel` carries no\n * role and no `aria-labelledby` wiring, and `MenuGroup` — which does carry\n * `role=\"group\"` — was not re-exported by this package at all, so a sighted\n * reader saw three labelled sections and a screen-reader user got one\n * undifferentiated list. This renders the group, renders the label inside it,\n * and points the one at the other, which is the whole of the fix and not\n * something a caller should have to remember.\n *\n * @example\n * <DropdownMenuGroup label=\"Account\">\n *   <DropdownMenuItem icon={Settings}>Settings</DropdownMenuItem>\n * </DropdownMenuGroup>\n */\nexport function DropdownMenuGroup({ label, children, ...rest }: DropdownMenuGroupProps) {\n  const id = useId()\n\n  return (\n    <DropdownMenuPrimitive.Group\n      aria-labelledby={label === undefined ? undefined : id}\n      {...rest}\n    >\n      {label !== undefined && <DropdownMenuLabel id={id}>{label}</DropdownMenuLabel>}\n      {children}\n    </DropdownMenuPrimitive.Group>\n  )\n}\n\nexport default DropdownMenu\n"],"mappings":";AA8BM,cA6FF,YA7FE;AA5BN,YAAY,2BAA2B;AAEvC,SAAS,gBAAgB,aAAkD;AAC3E,SAAS,UAAU;AACnB,SAAS,2BAA2B;AAYpC,SAAS,gBAAgB,MAAkD;AACzE,MAAI,eAAe,IAAI,EAAG,QAAO;AACjC,MAAI,OAAO,SAAS,WAAY,QAAO;AACvC,MAAI,OAAO,SAAS,YAAY,SAAS,KAAM,QAAO;AACtD,SAAO,CAAC,MAAM,QAAQ,IAAI,KAAK,EAAE,OAAO,YAAY,SAAS,EAAE,UAAU;AAC3E;AAGA,SAAS,SAAS,MAAyC;AACzD,MAAI,SAAS,UAAa,SAAS,QAAQ,SAAS,MAAO,QAAO;AAClE,MAAI,CAAC,gBAAgB,IAAI,GAAG;AAC1B,WACE,oBAAC,UAAK,eAAW,MAAC,WAAU,0DACzB,gBACH;AAAA,EAEJ;AACA,QAAM,OAAO;AACb,SAAO,oBAAC,QAAK,MAAM,IAAI,aAAa,KAAK,WAAU,YAAW,eAAW,MAAC;AAC5E;AAGO,MAAM,eAAe,sBAAsB;AAC3C,MAAM,sBAAsB,sBAAsB;AAwBlD,SAAS,oBAAoB;AAAA,EAClC;AAAA,EACA,aAAa;AAAA,EACb;AAAA,EACA,GAAG;AACL,GAA6B;AAC3B,QAAM,YAAY,oBAAoB;AAEtC,SACE,oBAAC,sBAAsB,QAAtB,EAA6B,WAAW,aAAa,QACpD;AAAA,IAAC,sBAAsB;AAAA,IAAtB;AAAA,MACC,mBAAmB,aAAa;AAAA,MAChC,kBAAkB;AAAA,MAClB;AAAA,MACA,qBAAiB;AAAA,MACjB,WAAW;AAAA,QACT;AAAA,QACA;AAAA,QACA;AAAA,MACF;AAAA,MACC,GAAG;AAAA,MAEH;AAAA;AAAA,EACH,GACF;AAEJ;AAwBO,SAAS,iBAAiB;AAAA,EAC/B;AAAA,EACA,cAAc;AAAA,EACd;AAAA,EACA;AAAA,EACA,GAAG;AACL,GAA0B;AACxB,SACE;AAAA,IAAC,sBAAsB;AAAA,IAAtB;AAAA,MACC,WAAW;AAAA,QACT;AAAA,QACA,cAAc,oBAAoB;AAAA,QAClC;AAAA,MACF;AAAA,MACC,GAAG;AAAA,MAEH;AAAA,iBAAS,IAAI;AAAA,QACb;AAAA;AAAA;AAAA,EACH;AAEJ;AAGO,SAAS,sBAAsB;AAAA,EACpC;AAAA,EACA,GAAG;AACL,GAA2D;AACzD,SACE;AAAA,IAAC,sBAAsB;AAAA,IAAtB;AAAA,MACC,WAAW,GAAG,yBAAyB,SAAS;AAAA,MAC/C,GAAG;AAAA;AAAA,EACN;AAEJ;AAWO,SAAS,kBAAkB;AAAA,EAChC;AAAA,EACA,GAAG;AACL,GAAuD;AACrD,SACE;AAAA,IAAC,sBAAsB;AAAA,IAAtB;AAAA,MACC,WAAW,GAAG,2CAA2C,SAAS;AAAA,MACjE,GAAG;AAAA;AAAA,EACN;AAEJ;AAwBO,SAAS,kBAAkB,EAAE,OAAO,UAAU,GAAG,KAAK,GAA2B;AACtF,QAAM,KAAK,MAAM;AAEjB,SACE;AAAA,IAAC,sBAAsB;AAAA,IAAtB;AAAA,MACC,mBAAiB,UAAU,SAAY,SAAY;AAAA,MAClD,GAAG;AAAA,MAEH;AAAA,kBAAU,UAAa,oBAAC,qBAAkB,IAAS,iBAAM;AAAA,QACzD;AAAA;AAAA;AAAA,EACH;AAEJ;AAEA,IAAO,uBAAQ;","names":[]}

package/dist/components/EmptyState/EmptyState.d.ts

@@ -1,6 +1,7 @@
 import * as react from 'react';
 import { HTMLAttributes, ReactNode } from 'react';
 import { LucideIcon } from 'lucide-react';
+import { HeadingLevel } from '../Heading/Heading.js';
 
 interface EmptyStateProps extends Omit<HTMLAttributes<HTMLDivElement>, 'title'> {
     /** Optional lucide icon, shown muted inside a quiet circle. */
@@ -9,6 +10,26 @@ interface EmptyStateProps extends Omit<HTMLAttributes<HTMLDivElement>, 'title'>
     description?: ReactNode;
     /** The one thing to do next. An empty state without an action is a dead end. */
     action?: ReactNode;
+    /**
+     * The heading level `title` opens, in the document the empty state lands in.
+     *
+     * Defaults to `2`, which is the placement this component is sized for: it
+     * stands in for a whole view inside a page that already has an `h1`, so the
+     * level below that one is the level that does not leave a hole in heading
+     * navigation. Under a section that already has its own `h2`, pass `3`.
+     *
+     * The default was `3` and fixed, which was wrong in the ordinary case and
+     * impossible to correct — the documentation could name the rule but a caller
+     * had no prop to follow it with. `2` is the common case rather than a
+     * compromise, and it is optional rather than required because the correct
+     * placement has one answer often enough that making every existing call site
+     * restate it would buy nothing.
+     *
+     * The size does not follow the level. `title` renders at `--fs-sub` at every
+     * level, because moving a state down the outline is a fact about the document
+     * and not a request for smaller type.
+     */
+    level?: HeadingLevel;
 }
 /**
  * A collection with nothing in it — yet.
@@ -25,7 +46,10 @@ interface EmptyStateProps extends Omit<HTMLAttributes<HTMLDivElement>, 'title'>
  *   description="Create your first project to get started."
  *   action={<Button>New project</Button>}
  * />
+ * @example
+ * // Inside a section that already has its own heading.
+ * <EmptyState level={3} title="No invoices yet" />
  */
-declare function EmptyState({ icon: Icon, title, description, action, className, ...rest }: EmptyStateProps): react.JSX.Element;
+declare function EmptyState({ icon: Icon, title, description, action, level, className, ...rest }: EmptyStateProps): react.JSX.Element;
 
 export { EmptyState, type EmptyStateProps, EmptyState as default };

package/dist/components/EmptyState/EmptyState.js

@@ -1,10 +1,12 @@
 import { jsx, jsxs } from "react/jsx-runtime";
+import { Heading } from "../Heading/Heading.js";
 import { cn } from "../../lib/cn.js";
 function EmptyState({
   icon: Icon,
   title,
   description,
   action,
+  level = 2,
   className,
   ...rest
 }) {
@@ -15,7 +17,7 @@ function EmptyState({
       ...rest,
       children: [
         Icon && /* @__PURE__ */ jsx("span", { className: "mb-6 flex size-14 items-center justify-center rounded-(--radius-pill) bg-(--stone) text-(--ink-3-aa)", children: /* @__PURE__ */ jsx(Icon, { size: 24, strokeWidth: 1.5, "aria-hidden": true }) }),
-        /* @__PURE__ */ jsx("h3", { className: "m-0 font-heading text-[length:var(--fs-sub)] font-normal text-(--ink)", children: title }),
+        /* @__PURE__ */ jsx(Heading, { level, size: "sub", children: title }),
         description && /* @__PURE__ */ jsx("p", { className: "m-0 mt-2 max-w-sm text-sm leading-relaxed text-(--ink-3-aa)", children: description }),
         action && /* @__PURE__ */ jsx("div", { className: "mt-8", children: action })
       ]

package/dist/components/EmptyState/EmptyState.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../src/components/EmptyState/EmptyState.tsx"],"sourcesContent":["import type { LucideIcon } from 'lucide-react'\nimport type { HTMLAttributes, ReactNode } from 'react'\nimport { cn } from '../../lib/cn'\n\nexport interface EmptyStateProps extends Omit<HTMLAttributes<HTMLDivElement>, 'title'> {\n  /** Optional lucide icon, shown muted inside a quiet circle. */\n  icon?: LucideIcon\n  title: ReactNode\n  description?: ReactNode\n  /** The one thing to do next. An empty state without an action is a dead end. */\n  action?: ReactNode\n}\n\n/**\n * A collection with nothing in it — yet.\n *\n * Distinct from `ErrorState`: nothing went wrong here, so the copy says what to\n * do rather than what failed. The two are different components because the\n * shared temptation — one component with a `variant` — produces error pages\n * that read like empty folders.\n *\n * @example\n * <EmptyState\n *   icon={Inbox}\n *   title=\"No projects yet\"\n *   description=\"Create your first project to get started.\"\n *   action={<Button>New project</Button>}\n * />\n */\nexport function EmptyState({\n  icon: Icon,\n  title,\n  description,\n  action,\n  className,\n  ...rest\n}: EmptyStateProps) {\n  return (\n    <div\n      className={cn('flex flex-col items-center px-(--page-pad) py-20 text-center', className)}\n      {...rest}\n    >\n      {Icon && (\n        <span className=\"mb-6 flex size-14 items-center justify-center rounded-(--radius-pill) bg-(--stone) text-(--ink-3-aa)\">\n          <Icon size={24} strokeWidth={1.5} aria-hidden />\n        </span>\n      )}\n      <h3 className=\"m-0 font-heading text-[length:var(--fs-sub)] font-normal text-(--ink)\">\n        {title}\n      </h3>\n      {description && (\n        <p className=\"m-0 mt-2 max-w-sm text-sm leading-relaxed text-(--ink-3-aa)\">{description}</p>\n      )}\n      {action && <div className=\"mt-8\">{action}</div>}\n    </div>\n  )\n}\n\nexport default EmptyState\n"],"mappings":"AAsCI,SAMM,KANN;AApCJ,SAAS,UAAU;AA2BZ,SAAS,WAAW;AAAA,EACzB,MAAM;AAAA,EACN;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA,GAAG;AACL,GAAoB;AAClB,SACE;AAAA,IAAC;AAAA;AAAA,MACC,WAAW,GAAG,gEAAgE,SAAS;AAAA,MACtF,GAAG;AAAA,MAEH;AAAA,gBACC,oBAAC,UAAK,WAAU,wGACd,8BAAC,QAAK,MAAM,IAAI,aAAa,KAAK,eAAW,MAAC,GAChD;AAAA,QAEF,oBAAC,QAAG,WAAU,yEACX,iBACH;AAAA,QACC,eACC,oBAAC,OAAE,WAAU,+DAA+D,uBAAY;AAAA,QAEzF,UAAU,oBAAC,SAAI,WAAU,QAAQ,kBAAO;AAAA;AAAA;AAAA,EAC3C;AAEJ;AAEA,IAAO,qBAAQ;","names":[]}
+{"version":3,"sources":["../../../src/components/EmptyState/EmptyState.tsx"],"sourcesContent":["import type { LucideIcon } from 'lucide-react'\nimport type { HTMLAttributes, ReactNode } from 'react'\nimport { Heading, type HeadingLevel } from '../Heading/Heading'\nimport { cn } from '../../lib/cn'\n\nexport interface EmptyStateProps extends Omit<HTMLAttributes<HTMLDivElement>, 'title'> {\n  /** Optional lucide icon, shown muted inside a quiet circle. */\n  icon?: LucideIcon\n  title: ReactNode\n  description?: ReactNode\n  /** The one thing to do next. An empty state without an action is a dead end. */\n  action?: ReactNode\n  /**\n   * The heading level `title` opens, in the document the empty state lands in.\n   *\n   * Defaults to `2`, which is the placement this component is sized for: it\n   * stands in for a whole view inside a page that already has an `h1`, so the\n   * level below that one is the level that does not leave a hole in heading\n   * navigation. Under a section that already has its own `h2`, pass `3`.\n   *\n   * The default was `3` and fixed, which was wrong in the ordinary case and\n   * impossible to correct — the documentation could name the rule but a caller\n   * had no prop to follow it with. `2` is the common case rather than a\n   * compromise, and it is optional rather than required because the correct\n   * placement has one answer often enough that making every existing call site\n   * restate it would buy nothing.\n   *\n   * The size does not follow the level. `title` renders at `--fs-sub` at every\n   * level, because moving a state down the outline is a fact about the document\n   * and not a request for smaller type.\n   */\n  level?: HeadingLevel\n}\n\n/**\n * A collection with nothing in it — yet.\n *\n * Distinct from `ErrorState`: nothing went wrong here, so the copy says what to\n * do rather than what failed. The two are different components because the\n * shared temptation — one component with a `variant` — produces error pages\n * that read like empty folders.\n *\n * @example\n * <EmptyState\n *   icon={Inbox}\n *   title=\"No projects yet\"\n *   description=\"Create your first project to get started.\"\n *   action={<Button>New project</Button>}\n * />\n * @example\n * // Inside a section that already has its own heading.\n * <EmptyState level={3} title=\"No invoices yet\" />\n */\nexport function EmptyState({\n  icon: Icon,\n  title,\n  description,\n  action,\n  level = 2,\n  className,\n  ...rest\n}: EmptyStateProps) {\n  return (\n    <div\n      className={cn('flex flex-col items-center px-(--page-pad) py-20 text-center', className)}\n      {...rest}\n    >\n      {Icon && (\n        <span className=\"mb-6 flex size-14 items-center justify-center rounded-(--radius-pill) bg-(--stone) text-(--ink-3-aa)\">\n          <Icon size={24} strokeWidth={1.5} aria-hidden />\n        </span>\n      )}\n      <Heading level={level} size=\"sub\">\n        {title}\n      </Heading>\n      {description && (\n        <p className=\"m-0 mt-2 max-w-sm text-sm leading-relaxed text-(--ink-3-aa)\">{description}</p>\n      )}\n      {action && <div className=\"mt-8\">{action}</div>}\n    </div>\n  )\n}\n\nexport default EmptyState\n"],"mappings":"AA+DI,SAMM,KANN;AA7DJ,SAAS,eAAkC;AAC3C,SAAS,UAAU;AAkDZ,SAAS,WAAW;AAAA,EACzB,MAAM;AAAA,EACN;AAAA,EACA;AAAA,EACA;AAAA,EACA,QAAQ;AAAA,EACR;AAAA,EACA,GAAG;AACL,GAAoB;AAClB,SACE;AAAA,IAAC;AAAA;AAAA,MACC,WAAW,GAAG,gEAAgE,SAAS;AAAA,MACtF,GAAG;AAAA,MAEH;AAAA,gBACC,oBAAC,UAAK,WAAU,wGACd,8BAAC,QAAK,MAAM,IAAI,aAAa,KAAK,eAAW,MAAC,GAChD;AAAA,QAEF,oBAAC,WAAQ,OAAc,MAAK,OACzB,iBACH;AAAA,QACC,eACC,oBAAC,OAAE,WAAU,+DAA+D,uBAAY;AAAA,QAEzF,UAAU,oBAAC,SAAI,WAAU,QAAQ,kBAAO;AAAA;AAAA;AAAA,EAC3C;AAEJ;AAEA,IAAO,qBAAQ;","names":[]}

package/dist/components/ErrorState/ErrorState.d.ts

@@ -1,5 +1,6 @@
 import * as react from 'react';
 import { HTMLAttributes, ReactNode } from 'react';
+import { HeadingLevel } from '../Heading/Heading.js';
 
 interface ErrorStateProps extends HTMLAttributes<HTMLElement> {
     /** The status, set large — "404", "500". Decorative; the heading carries the meaning. */
@@ -8,6 +9,23 @@ interface ErrorStateProps extends HTMLAttributes<HTMLElement> {
     message: ReactNode;
     /** The way back. Render it with {@link ERROR_ACTION_CLASS}. */
     action: ReactNode;
+    /**
+     * The heading level `heading` opens, in the document the error state lands in.
+     *
+     * Defaults to `1`, and that is not a compromise: this component replaces the
+     * page rather than sitting inside one — its own ground, its own viewport, its
+     * own top clearance — so the page's single `h1` is the one it renders. Kept
+     * as the default, existing call sites render exactly the markup they did.
+     *
+     * The prop exists because the level was previously fixed, and the one piece
+     * of advice this component's documentation gives about headings — do not put
+     * it inside a shell that already has an `h1` — was advice a caller had no way
+     * to take. Now they do: inside a shell that owns the page heading, pass `2`.
+     *
+     * The size does not follow the level. `heading` renders at `--fs-heading` at
+     * every level; a failure demoted in the outline is the same failure.
+     */
+    level?: HeadingLevel;
 }
 /**
  * The recovery affordance's look, exported so every error page offers the same
@@ -28,7 +46,10 @@ declare const ERROR_ACTION_CLASS = "text-sm text-(--ink) underline decoration-(-
  *   message="The page you're looking for has moved, or never existed."
  *   action={<a href="/" className={ERROR_ACTION_CLASS}>Back home</a>}
  * />
+ * @example
+ * // Inside a shell that already owns the page's h1.
+ * <ErrorState level={2} code="503" heading="Invoices could not be loaded" … />
  */
-declare function ErrorState({ code, heading, message, action, className, ...rest }: ErrorStateProps): react.JSX.Element;
+declare function ErrorState({ code, heading, message, action, level, className, ...rest }: ErrorStateProps): react.JSX.Element;
 
 export { ERROR_ACTION_CLASS, ErrorState, type ErrorStateProps, ErrorState as default };

package/dist/components/ErrorState/ErrorState.js

@@ -1,7 +1,16 @@
 import { jsx, jsxs } from "react/jsx-runtime";
+import { Heading } from "../Heading/Heading.js";
 import { cn } from "../../lib/cn.js";
 const ERROR_ACTION_CLASS = "text-sm text-(--ink) underline decoration-(--rule-2) underline-offset-4 transition-colors duration-(--duration-fast) hover:decoration-(--ink)";
-function ErrorState({ code, heading, message, action, className, ...rest }) {
+function ErrorState({
+  code,
+  heading,
+  message,
+  action,
+  level = 1,
+  className,
+  ...rest
+}) {
   return /* @__PURE__ */ jsx(
     "section",
     {
@@ -12,11 +21,11 @@ function ErrorState({ code, heading, message, action, className, ...rest }) {
           "p",
           {
             "aria-hidden": "true",
-            className: "m-0 font-heading text-[length:var(--fs-title)] leading-none text-(--ink)",
+            className: "m-0 font-heading text-[length:var(--fs-title)] leading-tight text-(--ink)",
             children: code
           }
         ),
-        /* @__PURE__ */ jsx("h1", { className: "mb-4 mt-6 font-heading text-[length:var(--fs-heading)] font-normal text-(--ink)", children: heading }),
+        /* @__PURE__ */ jsx(Heading, { level, size: "heading", className: "mb-4 mt-6", children: heading }),
         /* @__PURE__ */ jsx("p", { className: "mb-10 max-w-(--measure-record) text-base leading-relaxed text-(--ink-3-aa)", children: message }),
         action
       ] })

package/dist/components/ErrorState/ErrorState.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../src/components/ErrorState/ErrorState.tsx"],"sourcesContent":["import type { HTMLAttributes, ReactNode } from 'react'\nimport { cn } from '../../lib/cn'\n\nexport interface ErrorStateProps extends HTMLAttributes<HTMLElement> {\n  /** The status, set large — \"404\", \"500\". Decorative; the heading carries the meaning. */\n  code: ReactNode\n  heading: ReactNode\n  message: ReactNode\n  /** The way back. Render it with {@link ERROR_ACTION_CLASS}. */\n  action: ReactNode\n}\n\n/**\n * The recovery affordance's look, exported so every error page offers the same\n * one rather than each inventing a link style.\n */\nexport const ERROR_ACTION_CLASS =\n  'text-sm text-(--ink) underline decoration-(--rule-2) underline-offset-4 transition-colors duration-(--duration-fast) hover:decoration-(--ink)'\n\n/**\n * A page that could not be shown.\n *\n * The code is set at the top of the type ladder and marked `aria-hidden` — read\n * aloud, \"404\" before the sentence explaining it is noise, and the heading\n * immediately after says the same thing in words.\n *\n * @example\n * <ErrorState\n *   code=\"404\"\n *   heading=\"Page not found\"\n *   message=\"The page you're looking for has moved, or never existed.\"\n *   action={<a href=\"/\" className={ERROR_ACTION_CLASS}>Back home</a>}\n * />\n */\nexport function ErrorState({ code, heading, message, action, className, ...rest }: ErrorStateProps) {\n  return (\n    <section\n      className={cn('flex min-h-svh flex-col justify-center bg-(--paper) pt-24', className)}\n      {...rest}\n    >\n      <div className=\"mx-auto w-full max-w-(--w-page) px-(--page-pad)\">\n        <p\n          aria-hidden=\"true\"\n          className=\"m-0 font-heading text-[length:var(--fs-title)] leading-none text-(--ink)\"\n        >\n          {code}\n        </p>\n        <h1 className=\"mb-4 mt-6 font-heading text-[length:var(--fs-heading)] font-normal text-(--ink)\">\n          {heading}\n        </h1>\n        <p className=\"mb-10 max-w-(--measure-record) text-base leading-relaxed text-(--ink-3-aa)\">\n          {message}\n        </p>\n        {action}\n      </div>\n    </section>\n  )\n}\n\nexport default ErrorState\n"],"mappings":"AAwCM,SACE,KADF;AAvCN,SAAS,UAAU;AAeZ,MAAM,qBACX;AAiBK,SAAS,WAAW,EAAE,MAAM,SAAS,SAAS,QAAQ,WAAW,GAAG,KAAK,GAAoB;AAClG,SACE;AAAA,IAAC;AAAA;AAAA,MACC,WAAW,GAAG,6DAA6D,SAAS;AAAA,MACnF,GAAG;AAAA,MAEJ,+BAAC,SAAI,WAAU,mDACb;AAAA;AAAA,UAAC;AAAA;AAAA,YACC,eAAY;AAAA,YACZ,WAAU;AAAA,YAET;AAAA;AAAA,QACH;AAAA,QACA,oBAAC,QAAG,WAAU,mFACX,mBACH;AAAA,QACA,oBAAC,OAAE,WAAU,8EACV,mBACH;AAAA,QACC;AAAA,SACH;AAAA;AAAA,EACF;AAEJ;AAEA,IAAO,qBAAQ;","names":[]}
+{"version":3,"sources":["../../../src/components/ErrorState/ErrorState.tsx"],"sourcesContent":["import type { HTMLAttributes, ReactNode } from 'react'\nimport { Heading, type HeadingLevel } from '../Heading/Heading'\nimport { cn } from '../../lib/cn'\n\nexport interface ErrorStateProps extends HTMLAttributes<HTMLElement> {\n  /** The status, set large — \"404\", \"500\". Decorative; the heading carries the meaning. */\n  code: ReactNode\n  heading: ReactNode\n  message: ReactNode\n  /** The way back. Render it with {@link ERROR_ACTION_CLASS}. */\n  action: ReactNode\n  /**\n   * The heading level `heading` opens, in the document the error state lands in.\n   *\n   * Defaults to `1`, and that is not a compromise: this component replaces the\n   * page rather than sitting inside one — its own ground, its own viewport, its\n   * own top clearance — so the page's single `h1` is the one it renders. Kept\n   * as the default, existing call sites render exactly the markup they did.\n   *\n   * The prop exists because the level was previously fixed, and the one piece\n   * of advice this component's documentation gives about headings — do not put\n   * it inside a shell that already has an `h1` — was advice a caller had no way\n   * to take. Now they do: inside a shell that owns the page heading, pass `2`.\n   *\n   * The size does not follow the level. `heading` renders at `--fs-heading` at\n   * every level; a failure demoted in the outline is the same failure.\n   */\n  level?: HeadingLevel\n}\n\n/**\n * The recovery affordance's look, exported so every error page offers the same\n * one rather than each inventing a link style.\n */\nexport const ERROR_ACTION_CLASS =\n  'text-sm text-(--ink) underline decoration-(--rule-2) underline-offset-4 transition-colors duration-(--duration-fast) hover:decoration-(--ink)'\n\n/**\n * A page that could not be shown.\n *\n * The code is set at the top of the type ladder and marked `aria-hidden` — read\n * aloud, \"404\" before the sentence explaining it is noise, and the heading\n * immediately after says the same thing in words.\n *\n * @example\n * <ErrorState\n *   code=\"404\"\n *   heading=\"Page not found\"\n *   message=\"The page you're looking for has moved, or never existed.\"\n *   action={<a href=\"/\" className={ERROR_ACTION_CLASS}>Back home</a>}\n * />\n * @example\n * // Inside a shell that already owns the page's h1.\n * <ErrorState level={2} code=\"503\" heading=\"Invoices could not be loaded\" … />\n */\nexport function ErrorState({\n  code,\n  heading,\n  message,\n  action,\n  level = 1,\n  className,\n  ...rest\n}: ErrorStateProps) {\n  return (\n    <section\n      className={cn('flex min-h-svh flex-col justify-center bg-(--paper) pt-24', className)}\n      {...rest}\n    >\n      <div className=\"mx-auto w-full max-w-(--w-page) px-(--page-pad)\">\n        {/* `leading-tight`, not `leading-none`. At the title step this face\n            draws about 62px of ink, and a line box of exactly the font size is\n            47 — so the figures overflowed their own box by seven pixels at the\n            top and seven at the bottom, pressing up against the eyebrow above\n            and eating half the gap to the heading below. The box that says\n            nothing is spaced from is the box the ink is actually in. */}\n        <p\n          aria-hidden=\"true\"\n          className=\"m-0 font-heading text-[length:var(--fs-title)] leading-tight text-(--ink)\"\n        >\n          {code}\n        </p>\n        <Heading level={level} size=\"heading\" className=\"mb-4 mt-6\">\n          {heading}\n        </Heading>\n        <p className=\"mb-10 max-w-(--measure-record) text-base leading-relaxed text-(--ink-3-aa)\">\n          {message}\n        </p>\n        {action}\n      </div>\n    </section>\n  )\n}\n\nexport default ErrorState\n"],"mappings":"AAqEM,SAOE,KAPF;AApEN,SAAS,eAAkC;AAC3C,SAAS,UAAU;AAgCZ,MAAM,qBACX;AAoBK,SAAS,WAAW;AAAA,EACzB;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA,QAAQ;AAAA,EACR;AAAA,EACA,GAAG;AACL,GAAoB;AAClB,SACE;AAAA,IAAC;AAAA;AAAA,MACC,WAAW,GAAG,6DAA6D,SAAS;AAAA,MACnF,GAAG;AAAA,MAEJ,+BAAC,SAAI,WAAU,mDAOb;AAAA;AAAA,UAAC;AAAA;AAAA,YACC,eAAY;AAAA,YACZ,WAAU;AAAA,YAET;AAAA;AAAA,QACH;AAAA,QACA,oBAAC,WAAQ,OAAc,MAAK,WAAU,WAAU,aAC7C,mBACH;AAAA,QACA,oBAAC,OAAE,WAAU,8EACV,mBACH;AAAA,QACC;AAAA,SACH;AAAA;AAAA,EACF;AAEJ;AAEA,IAAO,qBAAQ;","names":[]}

package/dist/components/Field/Field.d.ts

@@ -1,6 +1,18 @@
 import * as react from 'react';
 import { HTMLAttributes, ReactNode } from 'react';
 
+/**
+ * Where the control sits relative to its label.
+ *
+ * `stacked` is the form row: label, control, message, down the page.
+ *
+ * `row` is the settings row: the label and its `description` in a column at the
+ * inline start, the control at the inline end, one rhythm down a settings
+ * screen. It is a layout, not a second component — the label wiring, the
+ * required marker and the message slot are the same three things either way,
+ * and a `SettingRow` beside this would be all three of them written twice.
+ */
+type FieldLayout = 'stacked' | 'row';
 interface FieldProps extends HTMLAttributes<HTMLDivElement> {
     /** Visible label text; renders a `--danger` asterisk when `required`. */
     label?: ReactNode;
@@ -11,11 +23,23 @@ interface FieldProps extends HTMLAttributes<HTMLDivElement> {
      * — a form library referencing it by name, say.
      */
     htmlFor?: string;
+    /**
+     * A second line under the LABEL, explaining what the setting does.
+     *
+     * Distinct from `hint`, which sits under the control and belongs to the input
+     * — "We never share it". This belongs to the thing being switched on, and it
+     * is what makes a settings row a settings row. Both reach the control through
+     * `aria-describedby`, so a row that has a description and an error announces
+     * both.
+     */
+    description?: ReactNode;
     /** Helper copy shown below the control when there is no `error`. */
     hint?: ReactNode;
     /** Validation message; takes precedence over `hint` when present. */
     error?: ReactNode;
     required?: boolean;
+    /** Where the control sits relative to its label. See {@link FieldLayout}. */
+    layout?: FieldLayout;
     children: ReactNode;
 }
 /**
@@ -32,13 +56,56 @@ interface FieldProps extends HTMLAttributes<HTMLDivElement> {
  * reader. The id is now generated when it is not supplied.
  *
  * `hint` and `error` are one slot, not two stacked messages: when a field is
- * wrong, the thing to read is what is wrong with it.
+ * wrong, the thing to read is what is wrong with it. `description` is a
+ * different slot again — it explains the SETTING, not the input, and it is what
+ * `layout="row"` puts under the label to make a settings row.
+ *
+ * **How the wiring reaches the control.** `cloneElement` puts the four
+ * attributes on the single child, and each control forwards them to whatever
+ * element carries the role — which is the child itself for `Input`, `Textarea`,
+ * `NativeSelect`, `Checkbox`, `Switch` and any host element written by hand, and
+ * a trigger, a group or a thumb further down for `Select`, `Combobox`,
+ * `DatePicker`, `Slider`, `RadioGroup` and `ToggleGroup`. The composites used to
+ * drop them on the floor, which drew a hint under a control that never announced
+ * it; a wrapper that appears to wire things up and does not is worse than one
+ * that never claimed to.
+ *
+ * The label's own id travels separately, through context, because a name is the
+ * one thing a prop cannot carry: a trigger whose text is its VALUE is named by
+ * the label AND by itself, so `<Field label="Region"><Select/></Field>`
+ * announces "Region, Australia" rather than either half.
+ *
+ * Three things stay out of reach, and each of them is the control's own markup
+ * rather than a gap in this wiring. A `<label for>` binds only to a labellable
+ * element, so the words do not click through to a `RadioGroup`, a `ToggleGroup`
+ * or a `Slider`: the first two are a `role="radiogroup"` named by pointing back
+ * at the label instead, exactly as a `<legend>` is, and the third carries
+ * `role="slider"` on a thumb below a roleless root. `required` reaches a control
+ * as `aria-required`, which `DatePicker`'s plain `<button>` trigger and a
+ * multiple-value `ToggleGroup`'s `role="toolbar"` have nowhere to put; there the
+ * asterisk is the only marker. And `aria-invalid` reaches `Slider`'s root rather
+ * than its thumb, so an errored slider is drawn wrong without being announced
+ * wrong.
+ *
+ * Each composite still takes its own `label` prop — that is what names it
+ * standing outside a field, and `Select`, `Combobox` and `DatePicker` warn when
+ * it is blank. It is no longer used INSTEAD of this one's.
+ *
+ * What no wiring can reach, the field says out loud in development rather than
+ * failing silently: `FIELD_CONTROL_NOT_LABELLABLE` when the child is a host
+ * element a label cannot bind to — the `<div>` wrapper that takes the id and
+ * leaves the control inside it with nothing — and `FIELD_CONTROL_NOT_WIRED`
+ * when there is no single element to wire at all.
  *
  * @example
  * <Field label="Email" required hint="We never share it."><Input type="email" /></Field>
  * @example
  * <Field label="Name" error="Name is required."><Input /></Field>
+ * @example
+ * <Field layout="row" label="Email notifications" description="A digest every Monday.">
+ *   <Switch defaultChecked />
+ * </Field>
  */
-declare function Field({ label, htmlFor, hint, error, required, children, className, ...rest }: FieldProps): react.JSX.Element;
+declare function Field({ label, htmlFor, description, hint, error, required, layout, children, className, ...rest }: FieldProps): react.JSX.Element;
 
-export { Field, type FieldProps, Field as default };
+export { Field, type FieldLayout, type FieldProps, Field as default };