@zyncat/ui 0.9.0 → 0.10.0

package/dist/pagination.js

@@ -2,7 +2,7 @@
 import { animate } from './chunk-YGCVWGUG.js';
 import { Icon } from './chunk-3SBCBYB7.js';
 import { UIMotion } from './chunk-S5ZTZANS.js';
-import { Button } from './chunk-U5QQZC3U.js';
+import { Button } from './chunk-2F5PITAO.js';
 import { cx } from './chunk-QGNC7LH5.js';
 import './pagination.css';
 import { useRef, useEffect } from 'react';

package/dist/popover.d.ts

@@ -4,6 +4,10 @@ import { D as DisableableAnimation } from './timing-7JA_zQHP.js';
 import { D as DataAttributes } from './dom-props-C0jrllBw.js';
 import './motion-scale-Canq4stZ.js';
 
+interface VirtualAnchor {
+    getBoundingClientRect(): DOMRect;
+}
+
 interface PopoverProps {
     /** Controlled open state. Omit to stay uncontrolled. */
     open?: boolean;
@@ -11,8 +15,11 @@ interface PopoverProps {
     defaultOpen?: boolean;
     /** Fires whenever the open state changes. Pair with `open` for controlled use. */
     onOpenChange?: (open: boolean) => void;
-    /** Cloned to toggle the panel; required as the anchor. */
+    /** Cloned to toggle the panel, and used as the anchor unless `anchor` is set. */
     trigger?: ReactElement | null;
+    /** Anchor to an arbitrary rect instead of the trigger - any `{ getBoundingClientRect() }`, which an element also satisfies.
+     *  Drive `open` yourself; pass a new object to re-place a moving anchor. */
+    anchor?: VirtualAnchor | null;
     /** Preferred side; flips to the opposite side when cramped. Default 'bottom'. */
     side?: 'top' | 'bottom' | 'left' | 'right';
     /** Cross-axis alignment against the trigger. Default 'start'. */
@@ -30,6 +37,6 @@ interface PopoverProps {
     /** The ENTIRE surface - paint AND semantics. Drive dismissal with `open`/`onOpenChange`. */
     children: ReactNode;
 }
-declare function Popover({ open: controlledOpen, defaultOpen, onOpenChange, trigger, side, align, arrow, dismissible, id, htmlProps, animation, children, }: PopoverProps): react.JSX.Element;
+declare function Popover({ open: controlledOpen, defaultOpen, onOpenChange, trigger, anchor, side, align, arrow, dismissible, id, htmlProps, animation, children, }: PopoverProps): react.JSX.Element;
 
-export { Popover, type PopoverProps };
+export { Popover, type PopoverProps, type VirtualAnchor };

package/dist/popover.js

@@ -1,7 +1,7 @@
-'use client';export { Popover } from './chunk-W5YM2FV4.js';
-import './chunk-EQ32F2QJ.js';
-import './chunk-LDC3RIYA.js';
-import './chunk-GY7JOPUQ.js';
+'use client';export { Popover } from './chunk-FTOAUJL5.js';
+import './chunk-62P3KD57.js';
+import './chunk-ZCOUPPTI.js';
+import './chunk-RCONNA7I.js';
 import './chunk-UE63OOVG.js';
 import './chunk-NEF5XAHG.js';
 import './chunk-356HZMT4.js';

package/dist/select.js

@@ -1,6 +1,6 @@
-'use client';import { useListbox, SelectTrigger, ListboxPanel } from './chunk-Q5B7JTSR.js';
-import './chunk-EQ32F2QJ.js';
-import './chunk-GY7JOPUQ.js';
+'use client';import { useListbox, SelectTrigger, ListboxPanel } from './chunk-OMHQ4U4J.js';
+import './chunk-62P3KD57.js';
+import './chunk-RCONNA7I.js';
 import './chunk-UE63OOVG.js';
 import './chunk-WM5J5TDI.js';
 import './chunk-NEF5XAHG.js';
@@ -11,7 +11,7 @@ import './chunk-2ERBBFZS.js';
 import './chunk-3SBCBYB7.js';
 import { useControllable } from './chunk-MMRIQNEN.js';
 import './chunk-S5ZTZANS.js';
-import './chunk-U5QQZC3U.js';
+import './chunk-2F5PITAO.js';
 import './chunk-7SZCJ7WI.js';
 import './chunk-VTJTGVZZ.js';
 import { cx } from './chunk-QGNC7LH5.js';

package/dist/sheet.d.ts

@@ -17,6 +17,9 @@ interface SheetProps {
     side?: 'right' | 'bottom';
     /** Scrim/Esc dismissal + drag-to-edge. Default true. */
     dismissible?: boolean;
+    /** Dock inside this element instead of the viewport - it must be positioned (`position: relative` or similar).
+     *  Scrim, scroll lock and inert scope to it; the rest of the page stays interactive. */
+    container?: HTMLElement | null;
     /** Base id for the panel; drives the trigger's `aria-controls`. Auto-generated when omitted. */
     id?: string;
     /** Standard attributes (className, style, data-*, ...) forwarded to the sheet panel. */
@@ -26,6 +29,6 @@ interface SheetProps {
     /** The ENTIRE surface - paint AND semantics. Drive dismissal with `open`/`onOpenChange`. */
     children: ReactNode;
 }
-declare function Sheet({ open: controlledOpen, defaultOpen, onOpenChange, trigger, side, dismissible, id, htmlProps, animation, children, }: SheetProps): react.JSX.Element;
+declare function Sheet({ open: controlledOpen, defaultOpen, onOpenChange, trigger, side, dismissible, container, id, htmlProps, animation, children, }: SheetProps): react.JSX.Element;
 
 export { Sheet, type SheetProps };

package/dist/sheet.js

@@ -1,7 +1,7 @@
-'use client';export { Sheet } from './chunk-GLT5IKQY.js';
-import './chunk-FLO4A6BI.js';
-import './chunk-LDC3RIYA.js';
-import './chunk-GY7JOPUQ.js';
+'use client';export { Sheet } from './chunk-UXONUUPI.js';
+import './chunk-K5X2GCXU.js';
+import './chunk-ZCOUPPTI.js';
+import './chunk-RCONNA7I.js';
 import './chunk-NEF5XAHG.js';
 import './chunk-356HZMT4.js';
 import './chunk-XWUWYSCT.js';

package/dist/table.js

@@ -5,7 +5,7 @@ import './chunk-YGCVWGUG.js';
 import { Icon } from './chunk-3SBCBYB7.js';
 import { Odometer } from './chunk-CONSWNIV.js';
 import { UIMotion } from './chunk-S5ZTZANS.js';
-import { Button } from './chunk-U5QQZC3U.js';
+import { Button } from './chunk-2F5PITAO.js';
 import { Checkbox } from './chunk-QDK66S4G.js';
 import './chunk-NNXJCLTV.js';
 import { cx } from './chunk-QGNC7LH5.js';

package/dist/toast.js

@@ -8,7 +8,7 @@ import { animate, startDrag } from './chunk-YGCVWGUG.js';
 import { Icon } from './chunk-3SBCBYB7.js';
 import { fireGlint } from './chunk-S7B34VGN.js';
 import { UIMotion } from './chunk-S5ZTZANS.js';
-import { Button } from './chunk-U5QQZC3U.js';
+import { Button } from './chunk-2F5PITAO.js';
 import { cx } from './chunk-QGNC7LH5.js';
 import './toast.css';
 import { useEffect, useSyncExternalStore, useState, useRef, useLayoutEffect } from 'react';

package/llms.txt

@@ -27,8 +27,9 @@ Agents: prefer the bundled MCP server over scanning this file or node_modules -
 ============================================================ PRIMITIVES
 
 Button - @zyncat/ui/button
-  One control for every click; exactly one primary per view. variant primary|secondary|ghost|danger|link, size sm|md|lg, iconLeft/iconRight (ReactNode), loading, disabled.
-  <Button variant="primary" iconLeft={<Icon name="plus" size="sm" />}>Schedule post</Button>
+  One control for every click; exactly one primary per view. variant primary|secondary|ghost|danger|link, size sm|md|lg|icon, loading, disabled. Icons are plain children - Button lays them out in a centered row with gap, no iconLeft/iconRight slots.
+  <Button variant="primary"><Icon name="plus" size="sm" />Schedule post</Button>
+  <Button size="icon" aria-label="Close"><Icon name="x" size="sm" /></Button>
 
 Collapse - @zyncat/ui/collapse
   Layout-transition primitive; eases height open/closed, never teleports. Closed content also
@@ -168,16 +169,39 @@ Tooltip - @zyncat/ui/tooltip
   <Tooltip content="Save changes" shortcut="⌘S"><Button>Save</Button></Tooltip>
 
 Dialog - @zyncat/ui/dialog
-  Styled modal: scrim, focus trap, scroll lock. open/onOpenChange, tone, icon, title, description, footer: (close) => node.
+  DEFAULT CHOICE for modals - the styled surface: header (icon/title/description/close), scrolling body,
+  footer actions, on top of scrim + focus trap + scroll lock. Reach for Modal only if this chrome is wrong.
+  open/onOpenChange, tone, icon, title, description, footer: (close) => node. Header is omitted entirely
+  when there is no icon/title/description and dismissible={false}.
+  container mounts it inside a positioned element instead of the viewport; scrim, scroll lock and
+  inert then scope to that box and the rest of the page stays live.
   <Dialog open={o} onOpenChange={setO} tone="danger" title="Delete this project?" footer={(close) => <>...</>}>...</Dialog>
 
+Modal - @zyncat/ui/modal
+  The SAME modality as Dialog (scrim, focus trap, scroll lock, inert, Esc, motion) with ZERO paint - no
+  header, no body padding, no width cap, no border/radius/shadow. You supply the whole surface AND its
+  semantics (role="dialog" + a label).
+  Use it ONLY when Dialog's chrome is the problem: lightbox / image viewer, full-bleed media, video,
+  a custom layout that owns its own edges. If the content is a title + text + buttons, use Dialog instead.
+  htmlProps paints the panel (centered by default; width+height 100% = full-bleed), layerProps reaches the
+  box behind it (set --bg-overlay to retint the scrim). Also takes trigger, dismissible, container, animation.
+  <Modal open={!!src} onOpenChange={() => setSrc(null)} htmlProps={{ className: 'lightbox' }} layerProps={{ style: { '--bg-overlay': 'rgb(0 0 0 / 0.92)' } }}>
+    <div role="dialog" aria-label="Image viewer"><img src={src} alt="" /></div>
+  </Modal>
+
 Popover - @zyncat/ui/popover
-  Headless anchored panel, non-modal. side, align, arrow, trigger (node), asChild; children: ({ close }) => node.
-  <Popover side="bottom" align="start" trigger={<Button>Actions</Button>}>{({ close }) => <menu>...</menu>}</Popover>
+  Headless anchored panel, non-modal. side, align, arrow, trigger (node), dismissible.
+  Anchor without a trigger: pass anchor - anything with getBoundingClientRect (a DOMRect source, an
+  element) - and drive open yourself. Pass a new object to re-place a moving anchor.
+  <Popover side="bottom" align="start" trigger={<Button>Actions</Button>}><menu>...</menu></Popover>
+  <Popover open={!!spot} onOpenChange={dismiss} anchor={spot} side="right"><menu>...</menu></Popover>
 
 Sheet - @zyncat/ui/sheet
-  Edge-docked modal panel, drag-to-dismiss. side right|bottom, trigger (node), asChild; children: ({ close }) => node.
-  <Sheet side="right" trigger={<Button>Filters</Button>}>{({ close }) => <div role="dialog">...</div>}</Sheet>
+  Edge-docked modal panel, drag-to-dismiss. side right|bottom, trigger (node), dismissible.
+  container docks it inside a positioned element instead of the viewport; scrim, scroll lock and
+  inert then scope to that box and the rest of the page stays live.
+  <Sheet side="right" trigger={<Button>Filters</Button>}><div role="dialog">...</div></Sheet>
+  <Sheet side="bottom" container={panel} open={o} onOpenChange={setO}><div role="dialog">...</div></Sheet>
 
 ============================================================ DEV TOOLS
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zyncat/ui",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "A React 19 design system: accessible, animated UI components built on a small, closed CSS design-token vocabulary. No Tailwind, no CSS-in-JS.",
   "keywords": [
     "react",
@@ -181,6 +181,11 @@
       "types": "./dist/dialog.d.ts",
       "import": "./dist/dialog.js"
     },
+    "./modal": {
+      "source": "./src/components/composites/modal/Modal.tsx",
+      "types": "./dist/modal.d.ts",
+      "import": "./dist/modal.js"
+    },
     "./tooltip": {
       "source": "./src/components/composites/tooltip/Tooltip.tsx",
       "types": "./dist/tooltip.d.ts",
@@ -230,15 +235,6 @@
     "next.mjs",
     "next.d.mts"
   ],
-  "scripts": {
-    "build": "tsup",
-    "typecheck": "tsc --noEmit && tsc -p tsconfig.node.json",
-    "check:css": "node scripts/check-css-graph.mjs",
-    "check:llms": "node scripts/check-llms.mjs",
-    "format": "prettier --write .",
-    "format:check": "prettier --check .",
-    "prepublishOnly": "pnpm build"
-  },
   "peerDependencies": {
     "react": "^19",
     "react-dom": "^19"
@@ -254,5 +250,14 @@
     "react-dom": "^19.2.7",
     "tsup": "^8.5.0",
     "typescript": "~6.0.3"
+  },
+  "scripts": {
+    "build": "NODE_OPTIONS=--max-old-space-size=8192 tsup",
+    "typecheck": "tsc --noEmit && tsc -p tsconfig.node.json",
+    "check:css": "node scripts/check-css-graph.mjs",
+    "check:llms": "node scripts/check-llms.mjs",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "dev": "cd playground && pnpm dev"
   }
-}
+}

package/src/components/composites/dialog/Dialog.tsx

@@ -40,6 +40,9 @@ export interface DialogProps {
   icon?: ReactNode;
   /** Close button + backdrop/Esc dismissal. Default true. */
   dismissible?: boolean;
+  /** Center inside this element instead of the viewport - it must be positioned (`position: relative` or similar).
+   *  Scrim, scroll lock and inert scope to it; the rest of the page stays interactive. */
+  container?: HTMLElement | null;
   /** Action row - a node, or a render fn `(close) => node` so uncontrolled dialogs can dismiss. */
   footer?: ReactNode | ((close: () => void) => ReactNode);
   /** Dialog body - scrolls when tall; its scroll edges flag the header lift + footer divider. */
@@ -100,30 +103,32 @@ function DialogSurface({
       aria-labelledby={title ? titleId : undefined}
       aria-describedby={description ? descId : undefined}
     >
-      <header className="dialog__header">
-        {icon && (
-          <span className="dialog__icon">
-            <IconSlot size="md">{icon}</IconSlot>
-          </span>
-        )}
-        <div className="dialog__heading">
-          {title && (
-            <h2 className="dialog__title" id={titleId}>
-              {title}
-            </h2>
+      {(icon || title || description || dismissible) && (
+        <header className="dialog__header">
+          {icon && (
+            <span className="dialog__icon">
+              <IconSlot size="md">{icon}</IconSlot>
+            </span>
           )}
-          {description && (
-            <p className="dialog__desc" id={descId}>
-              {description}
-            </p>
+          <div className="dialog__heading">
+            {title && (
+              <h2 className="dialog__title" id={titleId}>
+                {title}
+              </h2>
+            )}
+            {description && (
+              <p className="dialog__desc" id={descId}>
+                {description}
+              </p>
+            )}
+          </div>
+          {dismissible && (
+            <button type="button" className="dialog__close" aria-label="Close dialog" onClick={requestClose}>
+              <Icon name="x" size="sm" weight="bold" />
+            </button>
           )}
-        </div>
-        {dismissible && (
-          <button type="button" className="dialog__close" aria-label="Close dialog" onClick={requestClose}>
-            <Icon name="x" size="sm" weight="bold" />
-          </button>
-        )}
-      </header>
+        </header>
+      )}
 
       <div className="dialog__body" ref={bodyRef}>
         {children}
@@ -145,6 +150,7 @@ export function Dialog({
   tone = 'default',
   icon = null,
   dismissible = true,
+  container = null,
   footer = null,
   children,
   id,
@@ -162,7 +168,7 @@ export function Dialog({
   return (
     <Fragment>
       {ovCloneTrigger(trigger, { open, onPress: () => setOpen(true), panelId, haspopup: 'dialog', triggerRef })}
-      <OverlayPortal>
+      <OverlayPortal container={container}>
         <Presence>
           {open && (
             <ModalShell
@@ -173,6 +179,7 @@ export function Dialog({
               panelClass="overlay-panel--dialog"
               panelId={panelId}
               dismissible={dismissible}
+              container={container}
               requestClose={close}
             >
               <DialogSurface

package/src/components/composites/dialog/dialog.css

@@ -136,6 +136,9 @@
   color: var(--text-body);
   font: var(--type-body);
 }
+.dialog__body:first-child {
+  padding-top: var(--space-5);
+}
 .dialog:has(.dialog__icon) .dialog__body {
   padding-left: calc(var(--space-5) + 2.25rem + var(--space-3));
 }

package/src/components/composites/modal/Modal.tsx

@@ -0,0 +1,95 @@
+'use client';
+
+import './modal.css';
+import { Fragment, useId, useRef, type HTMLAttributes, type ReactElement, type ReactNode } from 'react';
+import { Presence } from '../../../motion/presence';
+import { resolveMotionTiming } from '../../../motion/motion-timing';
+import type { DisableableAnimation } from '../../../motion/timing';
+import { useControllable } from '../../internal/hooks/use-controllable';
+import { ovCloneTrigger, OverlayPortal } from '../../internal/overlay/layer';
+import { ModalShell } from '../../internal/overlay/modal';
+import type { DataAttributes } from '../../../dom-props';
+
+const MODAL_TIMING = {
+  open: { duration: 'slow', ease: 'entrance' },
+  close: { duration: 'base', ease: 'standard' },
+} as const;
+
+export interface ModalProps {
+  /** Controlled open state. Omit to stay uncontrolled. */
+  open?: boolean;
+  /** Initial state when uncontrolled. Default false. */
+  defaultOpen?: boolean;
+  /** Fires whenever the open state changes. Pair with `open` for controlled use. */
+  onOpenChange?: (open: boolean) => void;
+
+  /** Cloned to open the modal on click. */
+  trigger?: ReactElement | null;
+
+  /** Scrim/Esc dismissal. Default true. */
+  dismissible?: boolean;
+
+  /** Mount inside this element instead of the viewport - it must be positioned (`position: relative` or similar).
+   *  Scrim, scroll lock and inert scope to it; the rest of the page stays interactive. */
+  container?: HTMLElement | null;
+
+  /** Base id for the panel; drives the trigger's `aria-controls`. Auto-generated when omitted. */
+  id?: string;
+  /** Standard attributes (className, style, data-*, ...) forwarded to the panel - this is where your paint goes.
+   *  Centered by default; `width: 100%; height: 100%` makes it full-bleed. */
+  htmlProps?: HTMLAttributes<HTMLDivElement> & DataAttributes;
+  /** Standard attributes forwarded to the layer behind the panel - set `--bg-overlay` here to retint the scrim. */
+  layerProps?: HTMLAttributes<HTMLDivElement> & DataAttributes;
+  /** Open/close timing - motion tokens only, or `null` to disable. @default open 'slow'/'entrance', close 'base'/'standard' */
+  animation?: DisableableAnimation;
+  /** The ENTIRE surface - paint AND semantics (`role="dialog"`, a label). Nothing is painted for you. */
+  children: ReactNode;
+}
+
+export function Modal({
+  open: controlledOpen,
+  defaultOpen = false,
+  onOpenChange,
+  trigger = null,
+  dismissible = true,
+  container = null,
+  id,
+  htmlProps,
+  layerProps,
+  animation,
+  children,
+}: ModalProps) {
+  const [open, setOpen] = useControllable(controlledOpen, defaultOpen, onOpenChange);
+  const triggerRef = useRef<HTMLElement>(null);
+  const autoId = useId();
+  const panelId = id || 'modal-' + autoId;
+  const close = () => setOpen(false);
+  const timings = resolveMotionTiming(animation, MODAL_TIMING);
+
+  return (
+    <Fragment>
+      {ovCloneTrigger(trigger, { open, onPress: () => setOpen(true), panelId, haspopup: 'dialog', triggerRef })}
+      <OverlayPortal container={container}>
+        <Presence>
+          {open && (
+            <ModalShell
+              key="modal"
+              animate={{ opacity: [0, 1], scale: [0.98, 1], timing: timings.open }}
+              exit={{ opacity: [0], scale: [0.98], timing: timings.close }}
+              layerClass="overlay-layer--modal"
+              panelClass="overlay-panel--modal"
+              panelId={panelId}
+              dismissible={dismissible}
+              container={container}
+              requestClose={close}
+              panelProps={htmlProps}
+              layerProps={layerProps}
+            >
+              {children}
+            </ModalShell>
+          )}
+        </Presence>
+      </OverlayPortal>
+    </Fragment>
+  );
+}

package/src/components/composites/modal/modal.css

@@ -0,0 +1,9 @@
+/* modal.css - the unpainted modal surface: the shell layer centers the panel and
+   constrains it to the layer box. Everything else is the consumer's paint. */
+.overlay-layer--modal {
+  place-items: center;
+}
+.overlay-panel--modal {
+  max-width: 100%;
+  max-height: 100%;
+}

package/src/components/composites/popover/Popover.tsx

@@ -9,10 +9,12 @@ import type { DisableableAnimation } from '../../../motion/timing';
 import { useControllable } from '../../internal/hooks/use-controllable';
 import { ovCloneTrigger, useOverlayEntry, useOutsidePress, OverlayPortal } from '../../internal/overlay/layer';
 import { useReturnFocus } from '../../internal/overlay/focus';
-import { useAnchorPosition } from '../../internal/overlay/position';
+import { useAnchorPosition, type VirtualAnchor } from '../../internal/overlay/position';
 import type { DataAttributes } from '../../../dom-props';
 import { cx } from '../../internal/utils/cx';
 
+export type { VirtualAnchor };
+
 const POPOVER_TIMING = {
   open: { duration: 'base', ease: 'entrance' },
   close: { duration: 'fast', ease: 'exit' },
@@ -26,8 +28,11 @@ export interface PopoverProps {
   /** Fires whenever the open state changes. Pair with `open` for controlled use. */
   onOpenChange?: (open: boolean) => void;
 
-  /** Cloned to toggle the panel; required as the anchor. */
+  /** Cloned to toggle the panel, and used as the anchor unless `anchor` is set. */
   trigger?: ReactElement | null;
+  /** Anchor to an arbitrary rect instead of the trigger - any `{ getBoundingClientRect() }`, which an element also satisfies.
+   *  Drive `open` yourself; pass a new object to re-place a moving anchor. */
+  anchor?: VirtualAnchor | null;
 
   /** Preferred side; flips to the opposite side when cramped. Default 'bottom'. */
   side?: 'top' | 'bottom' | 'left' | 'right';
@@ -56,6 +61,7 @@ function PopoverPanel({
   arrow,
   dismissible,
   requestClose,
+  anchor,
   triggerRef,
   htmlProps,
   animate,
@@ -68,6 +74,7 @@ function PopoverPanel({
   arrow: boolean;
   dismissible: boolean;
   requestClose: () => void;
+  anchor?: VirtualAnchor | null;
   triggerRef: RefObject<HTMLElement>;
   htmlProps?: HTMLAttributes<HTMLDivElement> & DataAttributes;
   children: ReactNode;
@@ -76,7 +83,7 @@ function PopoverPanel({
   const entry = useOverlayEntry({ nodeRef: panelRef, dismissible, requestClose });
   useMotion(panelRef, { animate, exit });
   useReturnFocus(panelRef);
-  useAnchorPosition({ side, align, arrow, triggerRef, panelRef });
+  useAnchorPosition({ side, align, arrow, anchor, triggerRef, panelRef });
   useOutsidePress({ entry, refs: [triggerRef, panelRef], enabled: dismissible, onPress: requestClose });
   return (
     <div
@@ -96,6 +103,7 @@ export function Popover({
   defaultOpen = false,
   onOpenChange,
   trigger = null,
+  anchor = null,
   side = 'bottom',
   align = 'start',
   arrow = false,
@@ -128,6 +136,7 @@ export function Popover({
               arrow={arrow}
               dismissible={dismissible}
               requestClose={close}
+              anchor={anchor}
               triggerRef={triggerRef}
               htmlProps={htmlProps}
             >

package/src/components/composites/select/core/trigger.tsx

@@ -51,24 +51,20 @@ export function SelectTrigger({
         ...htmlProps,
       }}
       onClick={() => (open ? requestClose() : show())}
-      iconRight={
-        <span className="select__caret">
-          <Icon name="caret-down" size="sm" />
-        </span>
-      }
-      iconLeft={
-        leading && (
-          <span className="select__leading">
-            <IconSlot size="sm">{leading}</IconSlot>
-          </span>
-        )
-      }
       {...rest}
     >
+      {leading && (
+        <span className="select__leading">
+          <IconSlot size="sm">{leading}</IconSlot>
+        </span>
+      )}
       <span className="select__value" data-placeholder={isPlaceholder ? 'true' : undefined}>
         {text}
       </span>
       {count != null && count > 0 && <span className="select__count">+{count}</span>}
+      <span className="select__caret">
+        <Icon name="caret-down" size="sm" />
+      </span>
     </Button>
   );
 }

package/src/components/composites/sheet/Sheet.tsx

@@ -35,6 +35,10 @@ export interface SheetProps {
   /** Scrim/Esc dismissal + drag-to-edge. Default true. */
   dismissible?: boolean;
 
+  /** Dock inside this element instead of the viewport - it must be positioned (`position: relative` or similar).
+   *  Scrim, scroll lock and inert scope to it; the rest of the page stays interactive. */
+  container?: HTMLElement | null;
+
   /** Base id for the panel; drives the trigger's `aria-controls`. Auto-generated when omitted. */
   id?: string;
   /** Standard attributes (className, style, data-*, ...) forwarded to the sheet panel. */
@@ -54,6 +58,7 @@ function SheetShell({
   side,
   panelId,
   dismissible,
+  container,
   requestClose,
   htmlProps,
   animate,
@@ -63,6 +68,7 @@ function SheetShell({
   side: 'right' | 'bottom';
   panelId: string;
   dismissible: boolean;
+  container?: HTMLElement | null;
   requestClose: () => void;
   htmlProps?: HTMLAttributes<HTMLDivElement> & DataAttributes;
   children: ReactNode;
@@ -77,6 +83,7 @@ function SheetShell({
       panelClass={'overlay-panel--sheet-' + side}
       panelId={panelId}
       dismissible={dismissible}
+      container={container}
       requestClose={requestClose}
       panelRef={panelRef}
       panelProps={{ ...htmlProps, ...dragProps }}
@@ -93,6 +100,7 @@ export function Sheet({
   trigger = null,
   side = 'right',
   dismissible = true,
+  container = null,
   id,
   htmlProps,
   animation,
@@ -108,7 +116,7 @@ export function Sheet({
   return (
     <Fragment>
       {ovCloneTrigger(trigger, { open, onPress: () => setOpen(true), panelId, haspopup: 'dialog', triggerRef })}
-      <OverlayPortal>
+      <OverlayPortal container={container}>
         <Presence>
           {open && (
             <SheetShell
@@ -122,6 +130,7 @@ export function Sheet({
               side={side}
               panelId={panelId}
               dismissible={dismissible}
+              container={container}
               requestClose={close}
               htmlProps={htmlProps}
             >

package/src/components/internal/overlay/layer.tsx

@@ -129,7 +129,7 @@ function ovCloneTrigger(
   } as Partial<typeof trigger.props>);
 }
 
-function OverlayPortal({ children }: { children: ReactNode }) {
+function OverlayPortal({ container, children }: { container?: HTMLElement | null; children: ReactNode }) {
   const hostRef = useRef<HTMLDivElement | null>(null);
   if (typeof document !== 'undefined' && !hostRef.current) {
     hostRef.current = document.createElement('div');
@@ -138,9 +138,9 @@ function OverlayPortal({ children }: { children: ReactNode }) {
   useLayoutEffect(() => {
     const el = hostRef.current;
     if (!el) return;
-    document.body.appendChild(el);
+    (container ?? document.body).appendChild(el);
     return () => el.remove();
-  }, []);
+  }, [container]);
   if (!hostRef.current) return null;
   return createPortal(children, hostRef.current);
 }