@sableui/react 0.11.0 → 0.13.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/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 }) })
+        ]
       }
     ) })
   ] });

package/dist/components/sheet/sheet.meta.js

@@ -8,7 +8,10 @@ var sheetMeta = {
     "drawer",
     "side panel",
     "overlay",
-    "swipe to dismiss"
+    "swipe to dismiss",
+    "bottom sheet",
+    "snap points",
+    "detents"
   ],
   usage: {
     description: "Use Sheet for secondary workflows that slide in while preserving context from the underlying page.",
@@ -21,6 +24,10 @@ var sheetMeta = {
         guidance: "do",
         description: "Include clear title, close path, and footer actions for task-oriented sheets."
       },
+      {
+        guidance: "do",
+        description: "Give a bottom sheet snap points when it shows a summary first and detail on demand (a map result, a now-playing panel): `snapPoints={[0.4, 1]}`. The first stop is where it opens; put what matters at that height, because the rest is a drag away."
+      },
       {
         guidance: "dont",
         description: "Do not use Sheet for simple confirmations or deeply nested workflows."
@@ -83,15 +90,39 @@ var sheetMeta = {
   props: [
     {
       name: "Sheet (Root)",
-      type: "Base UI Drawer.Root props (open, defaultOpen, onOpenChange, onOpenChangeComplete, modal, disablePointerDismissal, actionsRef, handle) \u2014 minus swipeDirection and snap points",
+      type: "Base UI Drawer.Root props (open, defaultOpen, onOpenChange, onOpenChangeComplete, modal, disablePointerDismissal, actionsRef, handle, snapPoints, snapPoint, defaultSnapPoint, onSnapPointChange, snapToSequentialPoints) \u2014 minus swipeDirection",
       description: `Controls open state. Uncontrolled by default. The dismiss swipe direction is not a prop: it follows SheetContent's side. onOpenChange reports reason "swipe" when a swipe closed it.`
+    },
+    {
+      name: "snapPoints",
+      type: "(number | string)[]",
+      default: "\u2014",
+      description: `Stops a bottom sheet rests at, smallest first: a fraction of the viewport (0.4), pixels (320), or a px/rem string ("20rem"). The panel is the full stop's height and opens at the first stop; a swipe moves between stops and a swipe below the first closes it. side="bottom" only: other sides ignore them, with a development warning.`
+    },
+    {
+      name: "snapPoint",
+      type: "number | string | null",
+      default: "\u2014",
+      description: "The active stop, controlled. Pair with onSnapPointChange; use defaultSnapPoint to open at a different stop uncontrolled."
+    },
+    {
+      name: "onSnapPointChange",
+      type: "(snapPoint: number | string | null, eventDetails) => void",
+      default: "\u2014",
+      description: "Fires when a swipe (or your code) moves the sheet to another stop."
+    },
+    {
+      name: "snapToSequentialPoints",
+      type: "boolean",
+      default: "false",
+      description: "Move one stop per swipe, by distance. Off, a fast flick can skip past a stop."
     }
   ],
   subcomponents: [
     {
       name: "SheetContent",
       type: 'Base UI Drawer.Popup props (initialFocus, finalFocus, \u2026) + side: "right" | "left" | "top" | "bottom" + className',
-      description: 'Backdrop + edge-anchored popup; portals to <body>. side picks which viewport edge the sheet anchors to and slides in from (defaults to "right"). Left/right are full-height side panels; top/bottom span the width up to 80vh. On touch it swipes closed toward that same edge (right swipes right, left swipes left, top swipes up, bottom swipes down).'
+      description: 'Backdrop + edge-anchored popup; portals to <body>. side picks which viewport edge the sheet anchors to and slides in from (defaults to "right"). Left/right are full-height side panels; top/bottom span the width up to 80vh. A bottom sheet with snapPoints is as tall as its highest stop allows (the viewport less a top gap), shows a drag handle, and translates down to the active stop; the part below the screen becomes bottom padding, so its scroll area and SheetFooter end at the visible edge. A bottom sheet rides above the on-screen keyboard (measured from visualViewport). On touch it swipes closed toward that same edge (right swipes right, left swipes left, top swipes up, bottom swipes down).'
     },
     {
       name: "SheetTrigger",
@@ -141,7 +172,9 @@ var sheetMeta = {
     "Focus matches Dialog: the first tabbable on mouse/keyboard open, the panel itself on touch (so the virtual keyboard stays down); focus returns to the trigger on close.",
     "Render a SheetClose inside SheetContent so screen-reader users can escape the popup.",
     "Slide animation runs via data-[starting-style]/data-[ending-style] attributes on the motion-duration token; while swiping the panel tracks the finger directly, and a released swipe finishes on the same token (scaled by flick speed), so reduced motion makes it instant.",
-    "A mouse drag that starts on sheet content selects text rather than dragging the panel; mouse dragging only starts from the padding edge."
+    "A mouse drag that starts on sheet content selects text rather than dragging the panel; mouse dragging only starts from the padding edge.",
+    "Snap points add stops, not a gate: at any stop the content scrolls within the visible part and every control stays reachable by keyboard, so nothing needs the drag. The handle is decorative (aria-hidden).",
+    "A bottom sheet stays above the on-screen keyboard: its bottom edge is lifted by the height the keyboard takes from the visual viewport, so a focused field is not covered. An app that sets interactive-widget=resizes-content in its viewport meta gets the same result from the browser, and the inset reads 0."
   ],
   examples: [
     {
@@ -156,6 +189,10 @@ var sheetMeta = {
       label: "Left side",
       code: '<Sheet><SheetTrigger render={<Button variant="secondary">Menu</Button>} /><SheetContent side="left"><SheetHeader><SheetTitle>Navigation</SheetTitle></SheetHeader><SheetFooter><SheetClose render={<Button variant="secondary">Close</Button>} /></SheetFooter></SheetContent></Sheet>'
     },
+    {
+      label: "Bottom sheet with snap points",
+      code: '<Sheet snapPoints={[0.4, 1]}><SheetTrigger render={<Button variant="secondary">Nearby</Button>} /><SheetContent side="bottom"><SheetHeader><SheetTitle>12 places nearby</SheetTitle><SheetDescription>Drag up for the full list.</SheetDescription></SheetHeader><SheetList>{places.map((place) => <Entity key={place.id} title={place.name} subtitle={place.distance} />)}</SheetList></SheetContent></Sheet>'
+    },
     {
       label: "Bottom side",
       code: '<Sheet><SheetTrigger render={<Button variant="secondary">Details</Button>} /><SheetContent side="bottom"><SheetHeader><SheetTitle>Order details</SheetTitle></SheetHeader><SheetFooter><SheetClose render={<Button variant="secondary">Close</Button>} /></SheetFooter></SheetContent></Sheet>'

package/dist/components/sheet/sheet.variants.js

@@ -8,7 +8,14 @@ var sheetVariants = cva(
         right: "inset-y-0 right-0 [transform:translateX(var(--drawer-swipe-movement-x))] h-full w-95 max-w-[90vw] border-l data-[ending-style]:translate-x-full data-[starting-style]:translate-x-full",
         left: "inset-y-0 left-0 [transform:translateX(var(--drawer-swipe-movement-x))] h-full w-95 max-w-[90vw] border-r data-[ending-style]:-translate-x-full data-[starting-style]:-translate-x-full",
         top: "inset-x-0 top-0 [transform:translateY(var(--drawer-swipe-movement-y))] h-auto max-h-[80vh] w-full border-b data-[ending-style]:-translate-y-full data-[starting-style]:-translate-y-full",
-        bottom: "inset-x-0 bottom-0 [transform:translateY(var(--drawer-swipe-movement-y))] h-auto max-h-[80vh] w-full border-t data-[ending-style]:translate-y-full data-[starting-style]:translate-y-full"
+        bottom: [
+          "inset-x-0 bottom-(--sheet-keyboard-inset,0) [transform:translateY(calc(var(--drawer-snap-point-offset,0px)_+_var(--drawer-swipe-movement-y,0px)))] h-auto max-h-[min(80vh,calc(100dvh_-_var(--sheet-keyboard-inset,0px)_-_var(--sheet-top-gap)))] w-full border-t [--sheet-top-gap:--spacing(10)] data-[ending-style]:translate-y-full data-[starting-style]:translate-y-full",
+          // Snap points: the panel is the full stop's height, and the active stop
+          // is Base UI's offset, translated down. The hidden part becomes bottom
+          // padding, so the scroll area, and SheetFooter's mt-auto, end at the
+          // visible edge rather than under the screen's.
+          "data-[snap-points]:h-[calc(100dvh_-_var(--sheet-keyboard-inset,0px)_-_var(--sheet-top-gap))] data-[snap-points]:max-h-none data-[snap-points]:pb-[calc(var(--sheet-p)_+_var(--drawer-snap-point-offset,0px))] data-[snap-points]:[--sheet-handle-pull:calc(var(--sheet-p)_-_--spacing(3))]"
+        ].join(" ")
       }
     },
     defaultVariants: {

package/dist/components/sidebar/sidebar.js

@@ -31,10 +31,18 @@ var SIDEBAR_INK = [
   "[--accent:var(--sidebar-accent)] [--accent-foreground:var(--sidebar-accent-foreground)]",
   "[--border:var(--sidebar-border)] [--ring:var(--sidebar-ring)]"
 ].join(" ");
+var PAGE_INK = [
+  "[--sidebar:var(--background)] [--sidebar-foreground:var(--foreground)]",
+  "[--sidebar-muted-foreground:var(--muted-foreground)]",
+  "[--sidebar-primary:var(--primary)] [--sidebar-primary-foreground:var(--primary-foreground)]",
+  "[--sidebar-accent:var(--muted)] [--sidebar-accent-foreground:var(--foreground)]",
+  "[--sidebar-border:var(--border)] [--sidebar-ring:var(--ring)]"
+].join(" ");
 function Sidebar({
   collapsed = false,
   icons = true,
   variant = "app",
+  surface = "rail",
   className,
   children,
   ...props
@@ -44,15 +52,18 @@ function Sidebar({
     {
       "data-collapsed": collapsed || void 0,
       "data-variant": variant,
+      "data-surface": surface,
       className: cn(
-        "shrink-0 flex-col border-r border-sidebar-border bg-sidebar text-sidebar-foreground",
+        "shrink-0 flex-col bg-sidebar text-sidebar-foreground",
         // The rail is its own surface. Anything placed in it that inks with
         // page tokens — an Entity account row, an Avatar, a ghost Button,
         // an OverflowMenu — reads the rail's set instead, so a theme can paint a
         // dark rail on a light page (Meridian) and the footer row stays
         // legible. Muted ink is the rail's ink at 62% over the rail, unless
         // a theme names --sidebar-muted-foreground.
-        SIDEBAR_INK,
+        // On the page surface the rail is separated by space and its
+        // content, not a rule and a tonal step.
+        surface === "rail" ? cn("border-r border-sidebar-border", SIDEBAR_INK) : PAGE_INK,
         SIDEBAR_VARIANT[variant],
         "w-[var(--sidebar-width,16rem)] data-[collapsed]:w-[var(--sidebar-width-collapsed,4rem)]",
         className