@sableui/react 0.10.0 → 0.12.0

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

@@ -0,0 +1,141 @@
+// src/components/navigation-menu/navigation-menu.meta.ts
+var navigationMenuMeta = {
+  name: "NavigationMenu",
+  summary: "A site header's primary nav over Base UI NavigationMenu: a bar of links and triggers, where a trigger opens a panel of links on hover, click or Enter. One shared panel glides between triggers and resizes to each one's content. Links take any router's link through `render` and mark the current page with `active`.",
+  status: "stable",
+  keywords: ["navigation", "nav", "header nav", "site nav", "mega menu", "top nav", "navbar", "dropdown nav"],
+  usage: {
+    description: "Use NavigationMenu for a marketing or docs site's header: a few top-level destinations, some of which open a panel of related pages. Use Menu for actions rather than destinations, Tabs to switch views inside a page, Sidebar or SideNav for an app's persistent navigation, and AppHeader for an app's mobile top bar.",
+    bestPractices: [
+      {
+        guidance: "do",
+        description: "Keep the bar to a handful of entries. A trigger groups related pages; a destination with nothing beneath it is a plain NavigationMenuLink in its own item."
+      },
+      {
+        guidance: "do",
+        description: 'Give panel links a `description` when titles alone are ambiguous ("Sync" \u2192 "Offline first, conflict free"), and lay the Content out with layout classes (`grid w-[30rem] grid-cols-2`); the shared panel sizes itself to it.'
+      },
+      {
+        guidance: "do",
+        description: 'Pass your router\'s link through `render` (`<NavigationMenuLink render={<Link to="/pricing" />}>`) and set `active` on the current page\'s link, so the bar shows where the reader is and announces it as `aria-current="page"`.'
+      },
+      {
+        guidance: "do",
+        description: 'Below `md`, hide the bar and offer the same destinations in a Sheet opened from a menu Button: SheetContent side="left" holding a SideNav, its groups mirroring the panels. A hover panel has nothing to hover on a phone, and a bar of five entries does not fit one.'
+      },
+      {
+        guidance: "dont",
+        description: "Do not put actions in it (Sign in, New project). Those are Buttons beside the nav; the nav holds places to go."
+      },
+      {
+        guidance: "dont",
+        description: "Do not assemble the panel yourself. The root renders the one Portal, Positioner, Popup and Viewport every trigger shares; a second one breaks the glide between triggers."
+      }
+    ],
+    anatomy: [
+      { name: "NavigationMenu", required: true, description: "The `<nav>` root; also renders the shared floating panel." },
+      { name: "NavigationMenuList", required: true, description: "The bar: a `<ul>` the arrow keys rove across." },
+      { name: "NavigationMenuItem", required: true, description: "One `<li>`: a link, or a trigger with its content." },
+      { name: "NavigationMenuTrigger", required: false, description: "Opens its item's content; carries a chevron." },
+      { name: "NavigationMenuContent", required: false, description: "The links a trigger reveals, rendered into the shared panel." },
+      { name: "NavigationMenuLink", required: true, description: "A destination: a bar entry in an item, a two-line row in content." }
+    ]
+  },
+  related: {
+    components: ["Menu", "SideNav", "Sheet", "AppHeader", "Tabs"]
+  },
+  props: [
+    {
+      name: "NavigationMenu (Root)",
+      type: "Base UI NavigationMenu.Root props (value, defaultValue, onValueChange, delay, closeDelay, orientation) + className",
+      default: "\u2014",
+      description: "The `<nav>`. `value` is the open item's value (null when closed); `delay` / `closeDelay` tune hover-to-open."
+    },
+    {
+      name: "align",
+      type: '"start" | "center" | "end"',
+      default: '"start"',
+      description: "Alignment of the shared panel along its trigger."
+    },
+    {
+      name: "sideOffset",
+      type: "number",
+      default: "8",
+      description: "Gap between the bar and the panel, in px. The pointer crosses it on a bridge, so the panel does not close on the way in."
+    }
+  ],
+  subcomponents: [
+    {
+      name: "NavigationMenuList",
+      type: "Base UI NavigationMenu.List props + className",
+      description: "The bar of items, a `<ul>`. Arrow keys move between entries."
+    },
+    {
+      name: "NavigationMenuItem",
+      type: "Base UI NavigationMenu.Item props + className + value?: string",
+      description: "One `<li>` holding either a NavigationMenuLink or a NavigationMenuTrigger with its NavigationMenuContent."
+    },
+    {
+      name: "NavigationMenuTrigger",
+      type: "Base UI NavigationMenu.Trigger props + className",
+      description: "Opens its item's content on hover, click or Enter, with a chevron that turns while open. Styled like the bar's links: muted at rest, full ink when hovered or open."
+    },
+    {
+      name: "NavigationMenuContent",
+      type: "Base UI NavigationMenu.Content props + className + keepMounted?: boolean",
+      description: "The item's panel content. Size and lay it out with layout classes; the shared panel follows its size and slides it in from the side it was reached from."
+    },
+    {
+      name: "NavigationMenuLink",
+      type: "Base UI NavigationMenu.Link props + className + href?: string + active?: boolean + closeOnClick?: boolean + render?: ReactElement + description?: ReactNode",
+      description: 'A destination. In an item it is a bar entry; in content it is a row with an optional `description` line. `active` sets `aria-current="page"`; `render={<Link to="\u2026" />}` keeps the roving focus on your router\'s link.'
+    }
+  ],
+  tokensUsed: ["popover", "popover-foreground", "border-floating", "accent", "accent-foreground", "muted-foreground", "foreground", "ring"],
+  motion: [
+    {
+      slot: "arrival",
+      recipe: "custom",
+      part: "Panel",
+      why: "The panel fades and scales in from its trigger like a popover, but it also resizes as the reader moves between triggers, which motion-pop cannot express: Base UI measures each content into --popup-width/--popup-height and the popup transitions to them on the motion tokens."
+    },
+    {
+      slot: "transition",
+      recipe: "custom",
+      part: "Panel",
+      why: "Moving from one trigger to the next keeps one panel open: it glides along the bar and the new content slides in from the direction of travel, so the reader sees one surface changing rather than two popups swapping. Snaps on first open and on resize (data-instant), where a glide would mean nothing."
+    },
+    {
+      slot: "response",
+      recipe: "motion-interactive",
+      part: "Trigger, Link",
+      why: "Bar entries and panel rows fill on hover and focus like the other interactive surfaces, so the bar reads as live before anything opens."
+    },
+    {
+      slot: "activity",
+      recipe: "none",
+      part: "root",
+      why: "Nothing in a nav moves on its own."
+    }
+  ],
+  a11y: [
+    'The root is a <nav>; give it an aria-label when the page has more than one nav ("Main").',
+    "Arrow keys move across the bar; Enter, Space or ArrowDown opens a trigger's content and moves focus into it; Esc closes and returns focus to the trigger.",
+    "A trigger is a button with aria-expanded; its content is reachable by Tab in reading order once open.",
+    '`active` on a link sets aria-current="page" and gives it full ink, so the current page is announced as well as shown.',
+    'Panel motion runs on the motion tokens, so reduced motion (or MotionProvider "reduced") collapses the glide and resize to instant.'
+  ],
+  examples: [
+    {
+      label: "Bar with a panel",
+      code: '<NavigationMenu aria-label="Main">\n	<NavigationMenuList>\n		<NavigationMenuItem>\n			<NavigationMenuTrigger>Product</NavigationMenuTrigger>\n			<NavigationMenuContent className="grid w-[30rem] grid-cols-2">\n				<NavigationMenuLink href="/editor" description="Write and review together.">Editor</NavigationMenuLink>\n				<NavigationMenuLink href="/sync" description="Offline first, conflict free.">Sync</NavigationMenuLink>\n			</NavigationMenuContent>\n		</NavigationMenuItem>\n		<NavigationMenuItem>\n			<NavigationMenuLink href="/pricing">Pricing</NavigationMenuLink>\n		</NavigationMenuItem>\n	</NavigationMenuList>\n</NavigationMenu>'
+    },
+    {
+      label: "With a router, marking the current page",
+      code: '<NavigationMenu aria-label="Main">\n	<NavigationMenuList>\n		<NavigationMenuItem>\n			<NavigationMenuLink active={path === "/docs"} render={<Link to="/docs" />}>Docs</NavigationMenuLink>\n		</NavigationMenuItem>\n		<NavigationMenuItem>\n			<NavigationMenuLink active={path === "/blog"} render={<Link to="/blog" />}>Blog</NavigationMenuLink>\n		</NavigationMenuItem>\n	</NavigationMenuList>\n</NavigationMenu>'
+    }
+  ]
+};
+export {
+  navigationMenuMeta
+};

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

@@ -7,7 +7,11 @@ var overflowMenuMeta = {
     "dots menu",
     "more actions",
     "ellipsis",
-    "kebab"
+    "kebab",
+    "responsive actions",
+    "responsive action menu",
+    "collapse actions",
+    "actions overflow on mobile"
   ],
   usage: {
     description: "Use OverflowMenu for compact overflow actions when the primary action is already visible elsewhere.",
@@ -20,6 +24,10 @@ var overflowMenuMeta = {
         guidance: "do",
         description: "Keep labels explicit so the icon-only trigger does not obscure the command meaning."
       },
+      {
+        guidance: "do",
+        description: "For actions that fit inline on a wide screen but not a narrow one, render them twice: inline (a Row inside a wrapper shown from a container width; Row sets its own display, so the wrapper does the hiding), and as MenuItems in an OverflowMenu hidden from that width (`@container` + `@md:`). display:none takes the hidden copy out of the accessibility tree, so only one set is ever announced. Keep the primary action inline at every width."
+      },
       {
         guidance: "dont",
         description: "Do not hide the most important or most frequent action inside OverflowMenu."
@@ -92,6 +100,10 @@ var overflowMenuMeta = {
     {
       label: "With leading icons",
       code: '<OverflowMenu><MenuItem><Icon name="check" className="text-sm" />Mark as read</MenuItem><MenuSeparator /><MenuItem variant="destructive"><Icon name="xmark" className="text-sm" />Delete</MenuItem></OverflowMenu>'
+    },
+    {
+      label: "Responsive actions: inline when wide, in a menu when narrow",
+      code: '<div className="@container/actions flex w-full justify-end">\n	<Row gap={1} align="center">\n		<div className="hidden @md/actions:block">\n			<Row gap={1}>\n				<Button variant="ghost" size="sm" iconStart={<Icon name="share" />}>Share</Button>\n				<Button variant="ghost" size="sm" iconStart={<Icon name="download" />}>Export</Button>\n			</Row>\n		</div>\n		<div className="@md/actions:hidden">\n			<OverflowMenu label="Report actions" size="icon-sm">\n				<MenuItem icon={<Icon name="share" />}>Share</MenuItem>\n				<MenuItem icon={<Icon name="download" />}>Export</MenuItem>\n			</OverflowMenu>\n		</div>\n		<Button size="sm" iconStart={<Icon name="edit" />}>Edit report</Button>\n	</Row>\n</div>'
     }
   ]
 };

package/dist/components/pagination/pagination.js

@@ -29,6 +29,7 @@ function Pagination({
   page,
   total,
   onPageChange,
+  pageLink,
   siblingCount = 1,
   label = "Pagination",
   className,
@@ -38,10 +39,12 @@ function Pagination({
   const safeTotal = Math.max(total, 1);
   const current = Math.min(Math.max(page, 1), safeTotal);
   const items = buildRange(current, safeTotal, siblingCount);
-  const goTo = (next) => {
+  const goTo = (next, event) => {
     if (next < 1 || next > safeTotal || next === current) return;
-    onPageChange(next);
+    if (pageLink && (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey)) return;
+    onPageChange?.(next);
   };
+  const linkTo = (next) => pageLink && next >= 1 && next <= safeTotal ? pageLink(next) : void 0;
   return /* @__PURE__ */ jsxs(
     "nav",
     {
@@ -57,7 +60,8 @@ function Pagination({
             size: "icon-sm",
             "aria-label": "Previous page",
             disabled: current <= 1,
-            onClick: () => goTo(current - 1),
+            render: linkTo(current - 1),
+            onClick: (event) => goTo(current - 1, event),
             children: /* @__PURE__ */ jsx(Icon, { name: "chevron-left", className: "text-base" })
           }
         ),
@@ -78,7 +82,8 @@ function Pagination({
               className: "w-auto min-w-(--control-sm) px-1 tabular-nums",
               "aria-label": `Page ${item}`,
               "aria-current": item === current ? "page" : void 0,
-              onClick: () => goTo(item),
+              render: linkTo(item),
+              onClick: (event) => goTo(item, event),
               children: item
             }
           ) }, item)
@@ -90,7 +95,8 @@ function Pagination({
             size: "icon-sm",
             "aria-label": "Next page",
             disabled: current >= safeTotal,
-            onClick: () => goTo(current + 1),
+            render: linkTo(current + 1),
+            onClick: (event) => goTo(current + 1, event),
             children: /* @__PURE__ */ jsx(Icon, { name: "chevron-right", className: "text-base" })
           }
         )

package/dist/components/pagination/pagination.meta.js

@@ -1,7 +1,7 @@
 // src/components/pagination/pagination.meta.ts
 var paginationMeta = {
   name: "Pagination",
-  summary: "Page navigation built from our own Button + Icon (no Base UI). A <nav aria-label='Pagination'> with prev/next icon buttons that disable at the bounds and numbered page buttons; the current page is a secondary button marked aria-current. Collapses to first/last/current plus a sibling window, bridging skipped runs with an ellipsis.",
+  summary: "Page navigation built from our own Button + Icon (no Base UI). A <nav aria-label='Pagination'> with prev/next icon buttons that disable at the bounds and numbered page buttons; the current page is a secondary button marked aria-current. With pageLink every control is a real link (crawlable, opens in a new tab, any router through render). Collapses to first/last/current plus a sibling window, bridging skipped runs with an ellipsis.",
   keywords: [
     "pagination",
     "pager",
@@ -10,7 +10,10 @@ var paginationMeta = {
     "results",
     "navigation",
     "next",
-    "previous"
+    "previous",
+    "page links",
+    "seo",
+    "url"
   ],
   usage: {
     description: "Use Pagination when a result set is split into discrete pages and the user needs predictable movement through them. Pair it with DataTable, list results, or server-paged views; use a load-more Button or infinite scroll when page numbers are not meaningful.",
@@ -23,6 +26,10 @@ var paginationMeta = {
         guidance: "do",
         description: 'Use a specific label when multiple pagers appear on a page, such as "Customer pages".'
       },
+      {
+        guidance: "do",
+        description: "Pass pageLink when the page lives in the URL (search results, a blog, a catalogue): each page becomes a link a crawler can follow and a reader can open in a new tab. Use a router's Link there so navigation stays in the app."
+      },
       {
         guidance: "do",
         description: "Reset to page 1 when filters or search terms materially change the result set."
@@ -81,7 +88,13 @@ var paginationMeta = {
       name: "onPageChange",
       type: "(page: number) => void",
       default: "\u2014",
-      description: "Called with the next page when a control is activated. No-op for out-of-range or unchanged values."
+      description: "Called with the next page when a control is activated. No-op for out-of-range or unchanged values. Optional with pageLink, where the URL is the page state."
+    },
+    {
+      name: "pageLink",
+      type: "(page: number) => ReactElement",
+      default: "\u2014",
+      description: "Render each page control as a link: return the element for a page, (page) => <a href={`?page=${page}`} /> or a router's <Link to={`?page=${page}`} />. The current page keeps aria-current; previous/next at the bounds stay disabled buttons. onPageChange becomes optional and, if set, still fires on click."
     },
     {
       name: "siblingCount",
@@ -115,6 +128,7 @@ var paginationMeta = {
     "Renders a landmark <nav> with aria-label so assistive tech can jump to the pager.",
     "The current page button carries aria-current='page'.",
     "Prev/next buttons are real <button>s with aria-label and become disabled at the bounds.",
+    "With pageLink the controls are real <a> links (or the router's), so they are crawlable and open in a new tab; a bound arrow stays a disabled button rather than a link to nowhere.",
     "Ellipsis slots are aria-hidden \u2014 they convey no navigable target."
   ],
   examples: [
@@ -130,6 +144,10 @@ var paginationMeta = {
       label: "Table results footer",
       code: '<Stack gap={2}><DataTable data={rows} columns={columns} rowKey={(row) => row.id} /><Pagination label="Customer pages" page={page} total={12} onPageChange={setPage} /></Stack>'
     },
+    {
+      label: "Page links (URL is the state)",
+      code: "<Pagination page={page} total={pageCount} pageLink={(page) => <Link to={`/search?q=${query}&page=${page}`} />} />"
+    },
     {
       label: "Server query state",
       code: "const [page, setPage] = useState(searchParams.page ?? 1)\n<Pagination page={page} total={pageCount} onPageChange={(next) => { setPage(next); loadPage(next) }} />"

package/dist/components/panel-section/index.js

@@ -1,8 +1,9 @@
 // src/components/panel-section/index.ts
-import { PanelSection, PropertyPair, PropertyRow } from "./panel-section.js";
+import { PanelSection, PropertyGroup, PropertyPair, PropertyRow } from "./panel-section.js";
 import { panelSectionMeta } from "./panel-section.meta.js";
 export {
   PanelSection,
+  PropertyGroup,
   PropertyPair,
   PropertyRow,
   panelSectionMeta

package/dist/components/panel-section/panel-section.js

@@ -1,8 +1,10 @@
 "use client";
 
 // src/components/panel-section/panel-section.tsx
+import { Icon } from "../../icon/index.js";
 import { cn } from "../../lib/cn.js";
 import { beginScrub } from "../../lib/scrub-gesture.js";
+import { Collapsible, CollapsiblePanel, CollapsibleTrigger } from "../collapsible/collapsible.js";
 import { jsx, jsxs } from "react/jsx-runtime";
 function PanelSection({
   title,
@@ -108,8 +110,21 @@ function PropertyPair({ labels, className, children, ...props }) {
   ] });
 }
 PropertyPair.displayName = "PropertyPair";
+function PropertyGroup({ label, summary, className, children, ...props }) {
+  return /* @__PURE__ */ jsxs(Collapsible, { className: cn("border-t border-hairline", className), ...props, children: [
+    /* @__PURE__ */ jsxs(CollapsibleTrigger, { className: "group/property-group flex h-(--control-sm) w-full items-center gap-2 rounded-xs text-start motion-interactive focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring", children: [
+      /* @__PURE__ */ jsx("span", { className: "min-w-0 flex-1 truncate text-ui-md text-foreground", children: label }),
+      summary != null ? /* @__PURE__ */ jsx("span", { className: "flex min-w-0 shrink items-center gap-2 truncate text-ui-md text-muted-foreground", children: summary }) : null,
+      /* @__PURE__ */ jsx(Icon, { name: "plus", className: "shrink-0 text-xs text-muted-foreground group-data-[panel-open]/property-group:hidden" }),
+      /* @__PURE__ */ jsx(Icon, { name: "minus", className: "hidden shrink-0 text-xs text-muted-foreground group-data-[panel-open]/property-group:block" })
+    ] }),
+    /* @__PURE__ */ jsx(CollapsiblePanel, { children: /* @__PURE__ */ jsx("div", { className: "flex flex-col gap-1.5 pt-0.5 pb-2", children }) })
+  ] });
+}
+PropertyGroup.displayName = "PropertyGroup";
 export {
   PanelSection,
+  PropertyGroup,
   PropertyPair,
   PropertyRow
 };

package/dist/components/panel-section/panel-section.meta.js

@@ -60,6 +60,11 @@ var panelSectionMeta = {
         name: "PropertyPair",
         required: false,
         description: "Two controls side by side, with optional captions above each."
+      },
+      {
+        name: "PropertyGroup",
+        required: false,
+        description: "A set of properties folded behind one row that names the group and summarises its value, opening with +/\u2212 to the controls beneath."
       }
     ]
   },
@@ -89,9 +94,15 @@ var panelSectionMeta = {
       name: "PropertyPair",
       type: "{ labels?: [ReactNode, ReactNode] }",
       description: "Two controls side by side in a 2-up grid, with optional captions above each."
+    },
+    {
+      name: "PropertyGroup",
+      type: "{ label: ReactNode; summary?: ReactNode; defaultOpen?: boolean; open?: boolean; onOpenChange?: (open: boolean) => void }",
+      description: "A collapsible set of properties inside a section, at the panel's scale (an Accordion is page furniture). The row shows the label, then the summary (the group's value, readable while closed: a word, a few swatches, or both), then a + that turns to \u2212 when open. Groups open independently and stack with a hairline between them. Built on Collapsible."
     }
   ],
   a11y: [
+    "PropertyGroup's row is a real button with aria-expanded (Collapsible); its summary is part of the button's name, so a closed group still announces its value.",
     "PropertyRow renders a real <label>; pass htmlFor with the control's id so clicking the label focuses it.",
     "The section title is an h3, so panels contribute a real heading outline rather than styled divs.",
     "`hint` is exposed as the label's title attribute \u2014 keep the essential meaning in the label itself, since title text is not reliably announced.",
@@ -99,6 +110,27 @@ var panelSectionMeta = {
   ],
   tokensUsed: ["foreground", "muted-foreground", "hairline"],
   examples: [
+    {
+      label: "Groups that fold behind their value",
+      code: `<PanelSection title="Color">
+  <PropertyGroup label="Tones" summary="Brand only">
+    <PropertyRow label="Scheme">
+      <Select value="brand">
+        <SelectTrigger size="xs" />
+        <SelectContent>
+          <SelectItem value="brand">Brand only</SelectItem>
+          <SelectItem value="harmonize">Harmonize</SelectItem>
+        </SelectContent>
+      </Select>
+    </PropertyRow>
+  </PropertyGroup>
+  <PropertyGroup label="Grid" summary="8px">
+    <PropertyRow label="Size">
+      <ScrubField label="Grid size" value={8} min={1} max={64} suffix="px" />
+    </PropertyRow>
+  </PropertyGroup>
+</PanelSection>`
+    },
     {
       label: "Blending section, 2-up",
       code: `<PanelSection title="Blending">

package/dist/components/scroller/scroller.js

@@ -8,12 +8,13 @@ import { useEdgeFade } from "../../lib/use-edge-fade.js";
 import { useScrollActivity } from "../../lib/use-scroll-activity.js";
 import {
   scrollRegionKeyDown,
-  useWheelToHorizontal
-} from "../../lib/use-wheel-to-horizontal.js";
+  useSmoothWheel
+} from "../../lib/use-smooth-wheel.js";
 import { jsx } from "react/jsx-runtime";
 function Scroller({
   orientation = "vertical",
   wheelScroll = true,
+  smoothWheel = true,
   label,
   className,
   viewportClassName,
@@ -27,7 +28,7 @@ function Scroller({
   const regionRef = useRef(null);
   const isHorizontal = orientation === "horizontal";
   const trackActivity = useScrollActivity();
-  const trackWheel = useWheelToHorizontal(isHorizontal && wheelScroll);
+  const trackWheel = useSmoothWheel({ axis: orientation, mapVertical: isHorizontal && wheelScroll, smooth: smoothWheel });
   const setRegion = useCallback(
     (node) => {
       setRef(ref, node);
@@ -59,7 +60,10 @@ function Scroller({
     // sizing, and is NOT masked — which is the entire point of the split. A
     // flex column so the scroller below can be `flex-1 min-h-0`, which bounds
     // off `h-*`, `max-h-*` and `flex-1` alike with no percentage to resolve.
-    /* @__PURE__ */ jsx("div", { style, className: cn("flex flex-col", className), children: /* @__PURE__ */ jsx(
+    // `min-w-0` because this box, not the scroller inside it, is what a grid
+    // or flex parent sizes: left at `min-width: auto`, a horizontal strip
+    // widened its column to the full length of its content and never scrolled.
+    /* @__PURE__ */ jsx("div", { style, className: cn("flex min-w-0 flex-col", className), children: /* @__PURE__ */ jsx(
       "div",
       {
         ref: setRegion,

package/dist/components/scroller/scroller.meta.js

@@ -65,6 +65,12 @@ var scrollerMeta = {
       default: "true",
       description: "On a horizontal Scroller, let a vertical mouse wheel scroll it sideways. Ignored when vertical. Turn it off only if the region is inside something that owns the wheel itself (a map, a canvas)."
     },
+    {
+      name: "smoothWheel",
+      type: "boolean",
+      default: "true",
+      description: "Ease mouse-wheel steps toward their target, on either axis: the inertia a smooth-scroll library such as Lenis adds, scoped to this region. Only a mouse wheel is eased; trackpads and touch keep their own momentum, keys and scrollbar drags stay native, and reduced motion (the OS preference or MotionProvider) turns it off. Anything else that moves the region (scrollIntoView, a stick-to-bottom chat) stops the easing at once. For a scroll container of your own, `useSmoothWheel()` returns the same behaviour as a ref callback."
+    },
     {
       name: "label",
       type: "string",

package/dist/components/sheet/sheet.js

@@ -20,54 +20,127 @@ var SWIPE_DIRECTION = {
   top: "up",
   bottom: "down"
 };
-var SheetSideContext = createContext(null);
-function Sheet(props) {
+var SheetRootContext = createContext(null);
+function Sheet({
+  snapPoints,
+  snapPoint,
+  defaultSnapPoint,
+  onSnapPointChange,
+  snapToSequentialPoints,
+  ...props
+}) {
   const [side, setSide] = useState("right");
-  return /* @__PURE__ */ jsx(SheetSideContext.Provider, { value: setSide, children: /* @__PURE__ */ jsx(Base.Root, { ...props, swipeDirection: SWIPE_DIRECTION[side] }) });
+  const snaps = Boolean(snapPoints?.length);
+  const context = useMemo(() => ({ reportSide: setSide, snaps }), [snaps]);
+  return /* @__PURE__ */ jsx(SheetRootContext.Provider, { value: context, children: /* @__PURE__ */ jsx(
+    Base.Root,
+    {
+      ...props,
+      snapPoints: snaps && side === "bottom" ? snapPoints : void 0,
+      snapPoint,
+      defaultSnapPoint,
+      onSnapPointChange,
+      snapToSequentialPoints,
+      swipeDirection: SWIPE_DIRECTION[side]
+    }
+  ) });
+}
+function isDevelopment() {
+  try {
+    return process.env.NODE_ENV !== "production";
+  } catch {
+    return false;
+  }
+}
+function useKeyboardInset(enabled) {
+  const [inset, setInset] = useState(0);
+  useIsomorphicLayoutEffect(() => {
+    const viewport = typeof window === "undefined" ? void 0 : window.visualViewport;
+    if (!enabled || !viewport) return;
+    const measure = () => setInset(
+      Math.abs(viewport.scale - 1) > 0.01 ? 0 : Math.max(0, Math.round(window.innerHeight - viewport.height - viewport.offsetTop))
+    );
+    measure();
+    viewport.addEventListener("resize", measure);
+    viewport.addEventListener("scroll", measure);
+    return () => {
+      viewport.removeEventListener("resize", measure);
+      viewport.removeEventListener("scroll", measure);
+      setInset(0);
+    };
+  }, [enabled]);
+  return inset;
 }
 var SheetTrigger = Base.Trigger;
 var SheetClose = Base.Close;
 var SheetPortal = withPortalThemeScope(Base.Portal);
+var warnedSnapSide = false;
 function SheetContent({
   className,
   children,
   side,
   initialFocus,
   ref,
+  style,
   ...props
 }) {
-  const reportSide = useContext(SheetSideContext);
+  const root = useContext(SheetRootContext);
   const resolvedSide = side ?? "right";
+  const reportSide = root?.reportSide;
   useIsomorphicLayoutEffect(() => {
     reportSide?.(resolvedSide);
   }, [reportSide, resolvedSide]);
+  const snaps = Boolean(root?.snaps) && resolvedSide === "bottom";
+  if (root?.snaps && resolvedSide !== "bottom" && !warnedSnapSide && isDevelopment()) {
+    warnedSnapSide = true;
+    console.warn(`Sable: <Sheet snapPoints> applies to side="bottom" only; this sheet opens from the ${resolvedSide}, so its snap points are ignored.`);
+  }
   const popupRef = useRef(null);
   const [popup, setPopup] = useState(null);
   const mergedRef = useMemo(() => mergeRefs(popupRef, ref, setPopup), [ref]);
+  const keyboardInset = useKeyboardInset(resolvedSide === "bottom" && popup !== null);
+  const keyboardVars = { "--sheet-keyboard-inset": `${keyboardInset}px` };
   useIsomorphicLayoutEffect(() => {
     if (!popup || resolvedSide !== "left" && resolvedSide !== "right") return;
-    const root = document.documentElement;
+    const root2 = document.documentElement;
     const name = `--sable-sheet-${resolvedSide}-w`;
-    const publish = () => root.style.setProperty(name, `${popup.offsetWidth}px`);
+    const publish = () => root2.style.setProperty(name, `${popup.offsetWidth}px`);
     publish();
     const observer = typeof ResizeObserver === "undefined" ? null : new ResizeObserver(publish);
     observer?.observe(popup);
     return () => {
       observer?.disconnect();
-      root.style.removeProperty(name);
+      root2.style.removeProperty(name);
     };
   }, [popup, resolvedSide]);
   return /* @__PURE__ */ jsxs(SheetPortal, { children: [
     /* @__PURE__ */ jsx(Base.Backdrop, { className: "fixed inset-0 z-(--z-overlay) bg-overlay/(--scrim-alpha) opacity-[calc(1_-_var(--drawer-swipe-progress))] motion-fade data-[swiping]:transition-none" }),
-    /* @__PURE__ */ jsx(Base.Viewport, { className: "fixed inset-0 z-(--z-overlay)", children: /* @__PURE__ */ jsx(
+    /* @__PURE__ */ jsx(Base.Viewport, { className: "fixed inset-0 z-(--z-overlay)", children: /* @__PURE__ */ jsxs(
       Base.Popup,
       {
         ref: mergedRef,
         initialFocus: initialFocus === void 0 ? (type) => type === "touch" ? popupRef.current : true : initialFocus,
         "data-sable-sheet": resolvedSide,
+        "data-snap-points": snaps ? "" : void 0,
         className: cn(sheetVariants({ side }), className),
         ...props,
-        children: /* @__PURE__ */ jsx(Base.Content, { className: "contents", children: /* @__PURE__ */ jsx(PresentationProvider, { value: resolvedSide === "bottom" ? "sheet" : "page", children }) })
+        style: typeof style === "function" ? (state) => ({ ...keyboardVars, ...style(state) }) : { ...keyboardVars, ...style },
+        children: [
+          snaps ? (
+            // The grip says "drag me". Decorative: the stops are reached by
+            // swipe, and the sheet's content stays reachable by scrolling
+            // and by keyboard whichever stop it rests at.
+            /* @__PURE__ */ jsx(
+              "div",
+              {
+                "aria-hidden": true,
+                "data-slot": "sheet-handle",
+                className: "-mt-(--sheet-handle-pull) mb-0 h-1 w-10 shrink-0 self-center rounded-full bg-border-strong"
+              }
+            )
+          ) : null,
+          /* @__PURE__ */ jsx(Base.Content, { className: "contents", children: /* @__PURE__ */ jsx(PresentationProvider, { value: resolvedSide === "bottom" ? "sheet" : "page", children }) })
+        ]
       }
     ) })
   ] });