@sableui/react 0.16.0 → 0.18.0

package/dist/components/pill/pill.variants.js

@@ -26,6 +26,7 @@ var pillVariants = cva(
         outline: "border"
       },
       size: {
+        lg: "h-(--control-sm) px-4 py-0 text-label-lg [--sable-optical-pad:0px]",
         md: "h-(--control-xs) px-3 py-0 [--sable-optical-pad:0px]",
         sm: "h-6 py-0 text-label-sm [--sable-optical-pad:0px]"
       },

package/dist/components/search-input/search-input.js

@@ -2,10 +2,31 @@
 import { useState } from "react";
 import { Icon } from "../../icon/index.js";
 import { cn } from "../../lib/cn.js";
-import { FIELD_INVALID, FIELD_SHELL, MOBILE_FIELD_TIER } from "../../lib/field-shell.js";
+import { FIELD_INVALID, FIELD_SHELL, FIELD_SHELL_XS, MOBILE_FIELD_TIER } from "../../lib/field-shell.js";
 import { useDensity, useTypeTier } from "../../lib/density.js";
+import { hitTargetMin } from "../../lib/hit-target.js";
 import { Button } from "../button/button.js";
 import { jsx, jsxs } from "react/jsx-runtime";
+var SIZES = {
+  md: {
+    field: "h-(--control-md) ps-9 pe-9",
+    icon: "start-3 text-sm",
+    clear: "end-2",
+    button: void 0
+  },
+  sm: {
+    field: "h-(--control-sm) ps-8 pe-8",
+    icon: "start-2.5 text-sm",
+    clear: "end-1",
+    button: cn("size-[calc(var(--control-sm)-var(--spacing)*2)] [--button-icon:0.875rem]", hitTargetMin)
+  },
+  xs: {
+    field: cn("h-(--control-xs) ps-6 pe-7", FIELD_SHELL_XS),
+    icon: "start-1.5 text-xs",
+    clear: "end-0.5",
+    button: cn("size-[calc(var(--control-xs)-var(--spacing))] [--button-icon:0.75rem]", hitTargetMin)
+  }
+};
 function SearchInput({
   value,
   defaultValue,
@@ -14,10 +35,12 @@ function SearchInput({
   placeholder = "Search",
   className,
   inputClassName,
+  size = "md",
   ref,
   type,
   ...props
 }) {
+  const rung = SIZES[size];
   const [uncontrolled, setUncontrolled] = useState(defaultValue ?? "");
   const controlled = value !== void 0;
   const current = controlled ? value : uncontrolled;
@@ -41,7 +64,7 @@ function SearchInput({
         Icon,
         {
           name: "search",
-          className: "pointer-events-none absolute start-3 text-sm text-muted-foreground"
+          className: cn("pointer-events-none absolute text-muted-foreground", rung.icon)
         }
       ),
       /* @__PURE__ */ jsx(
@@ -53,10 +76,12 @@ function SearchInput({
           onChange: (event) => change(event.target.value),
           placeholder,
           className: cn(
-            "flex h-(--control-md) w-full ps-9 pe-9 text-foreground",
+            "flex w-full text-foreground",
             // The shell Input and CommandMenuTrigger wear too — lib/field-shell.
+            // xs layers the inset tool-panel surface over it, as Input xs does.
             FIELD_SHELL,
             FIELD_INVALID,
+            rung.field,
             "[&::-webkit-search-cancel-button]:appearance-none",
             tier.body,
             density === "comfortable" && MOBILE_FIELD_TIER,
@@ -72,14 +97,14 @@ function SearchInput({
         // transition-property slot — whichever sorted last would win, and
         // either the hover ease or the arrival would silently go. Removal
         // stays instant: an emptied field should not wait on its X.
-        /* @__PURE__ */ jsx("span", { className: "absolute end-2 flex motion-appear", children: /* @__PURE__ */ jsx(
+        /* @__PURE__ */ jsx("span", { className: cn("absolute flex motion-appear", rung.clear), children: /* @__PURE__ */ jsx(
           Button,
           {
             variant: "ghost",
             size: "icon-xs",
             onClick: handleClear,
             "aria-label": "Clear search",
-            className: "text-muted-foreground hover:text-foreground",
+            className: cn("text-muted-foreground hover:text-foreground", rung.button),
             children: /* @__PURE__ */ jsx(Icon, { name: "xmark" })
           }
         ) })

package/dist/components/search-input/search-input.meta.js

@@ -1,7 +1,7 @@
 // src/components/search-input/search-input.meta.ts
 var searchInputMeta = {
   name: "SearchInput",
-  summary: "Styled search field with a leading magnifier and a clearable X. Soft-square (rounded-sm), the theme's field surface, 2px focus ring; the clear button appears only when there is a value.",
+  summary: "Styled search field with a leading magnifier and a clearable X. Soft-square (rounded-sm), the theme's field surface, 2px focus ring; the clear button appears only when there is a value. size md (form), sm (toolbar, matching Pill lg and Button sm) or xs (inset tool-panel field).",
   status: "stable",
   keywords: [
     "search",
@@ -28,6 +28,14 @@ var searchInputMeta = {
         guidance: "do",
         description: "Light the query in the results it filters with `useMatchHighlight(query)` \u2014 a callback ref for the results container, with `selector` to keep it to titles. It paints on the `highlight` pair without wrapping matches in `<mark>`, the same paint Combobox and CommandMenu use for their rows."
       },
+      {
+        guidance: "do",
+        description: `In a toolbar beside filter chips, use size="sm" with Pill size="lg" (and Button size="sm" for actions). All three stand on --control-sm (32px, 28 compact), the rung the spacing doctrine gives toolbar controls, so the row is one height in either density. Keep md for a search field in a form or a page header beside md buttons, and xs for a filter inside a workspace panel, where it matches Input xs's inset surface.`
+      },
+      {
+        guidance: "dont",
+        description: "Do not match a neighbour's height with h-* on className or inputClassName. The magnifier, padding and clear button would stay sized for the old rung; pick the size that shares the neighbour's rung."
+      },
       {
         guidance: "dont",
         description: "Do not use SearchInput as a command palette; use CommandMenu for global commands, opened from the header by CommandMenuTrigger. A SearchInput that opens a dialog on focus is a text box you cannot type in."
@@ -42,10 +50,17 @@ var searchInputMeta = {
     components: [
       "Input",
       "CommandMenu",
-      "Combobox"
+      "Combobox",
+      "Pill"
     ]
   },
   props: [
+    {
+      name: "size",
+      type: '"md" | "sm" | "xs"',
+      default: '"md"',
+      description: "The rung of the control ladder, named as on Input, Select and Combobox. md is the form field (--control-md, 40px / 32 compact). sm is the toolbar field (--control-sm, 32px / 28 compact), the rung Pill lg and Button sm share, so filters + search + actions in one row are one height. xs is the tool-panel field (--control-xs, 28px / 24 compact) on Input xs's inset panel-field surface. The magnifier, inline padding and clear button scale with the rung and stay vertically centred."
+    },
     {
       name: "value",
       type: "string",
@@ -91,7 +106,7 @@ var searchInputMeta = {
     {
       name: "...props",
       type: 'ComponentPropsWithRef<"input">',
-      description: "All native input attributes (name, autoFocus, ref, aria-invalid, \u2026) pass through to the <input> except value/onChange, which are owned by value/onValueChange, and className, which sizes the whole field."
+      description: "All native input attributes (name, autoFocus, ref, aria-invalid, \u2026) pass through to the <input> except value/onChange, which are owned by value/onValueChange, className, which sizes the whole field, and the native numeric size attribute, which the size prop replaces."
     }
   ],
   tokensUsed: [
@@ -100,7 +115,9 @@ var searchInputMeta = {
     "foreground",
     "muted-foreground",
     "ring",
-    "destructive"
+    "destructive",
+    "panel-field",
+    "panel-field-hover"
   ],
   motion: [
     {
@@ -152,6 +169,14 @@ var searchInputMeta = {
       label: "Highlighting matches in the results",
       code: 'const [q, setQ] = useState("")\nconst results = useMatchHighlight<HTMLUListElement>(q, { selector: "[data-title]" })\nconst shown = posts.filter((post) => post.title.toLowerCase().includes(q.trim().toLowerCase()))\n\n<SearchInput value={q} onValueChange={setQ} placeholder="Search posts" />\n<ul ref={results}>\n	{shown.map((post) => (\n		<li key={post.id}><span data-title>{post.title}</span></li>\n	))}\n</ul>'
     },
+    {
+      label: "Filters with search",
+      code: 'const [filter, setFilter] = useState("all")\nconst [q, setQ] = useState("")\n\n<Row gap={2} align="center" justify="between" wrap>\n	<Row gap={1}>\n		<Pill size="lg" selected={filter === "all"} onClick={() => setFilter("all")}>All 8</Pill>\n		<Pill size="lg" selected={filter === "products"} onClick={() => setFilter("products")}>Products 5</Pill>\n		<Pill size="lg" selected={filter === "oss"} onClick={() => setFilter("oss")}>Open source 2</Pill>\n	</Row>\n	<SearchInput size="sm" value={q} onValueChange={setQ} placeholder="Find a project\u2026" aria-label="Find a project" className="max-w-64" />\n</Row>'
+    },
+    {
+      label: "Sizes",
+      code: '<Stack gap={1}>\n	<SearchInput size="md" placeholder="Search posts" aria-label="Search posts" />\n	<SearchInput size="sm" placeholder="Find a project\u2026" aria-label="Find a project" />\n	<SearchInput size="xs" placeholder="Filter layers" aria-label="Filter layers" />\n</Stack>'
+    },
     {
       label: "Disabled",
       code: '<SearchInput disabled placeholder="Search" />'

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

@@ -3,9 +3,10 @@ import { useId } from "react";
 import { cn } from "../../lib/cn.js";
 import { HeadingRow } from "../../lib/heading-row.js";
 import { jsx, jsxs } from "react/jsx-runtime";
-var TITLE_TIER = {
-  md: "text-heading-3",
-  sm: "text-heading-4"
+var SIZE = {
+  lg: { root: "gap-3", title: "text-heading-2", description: "text-body-md" },
+  md: { root: "gap-2", title: "text-heading-3", description: "text-body-sm" },
+  sm: { root: "gap-2", title: "text-heading-4", description: "text-body-sm" }
 };
 function SectionHeader({
   title,
@@ -18,20 +19,29 @@ function SectionHeader({
   ...props
 }) {
   const generatedId = useId();
-  return /* @__PURE__ */ jsxs("div", { "data-slot": "section-header", className: cn("flex flex-col gap-2", className), ...props, children: [
-    /* @__PURE__ */ jsx(
-      HeadingRow,
-      {
-        as: titleAs,
-        title,
-        titleId: titleId ?? generatedId,
-        titleClassName: TITLE_TIER[size],
-        band: "flex min-h-(--control-sm) items-center",
-        actions
-      }
-    ),
-    description ? /* @__PURE__ */ jsx("p", { className: "max-w-(--measure-prose) text-body-sm text-pretty text-muted-foreground", children: description }) : null
-  ] });
+  return /* @__PURE__ */ jsxs(
+    "div",
+    {
+      "data-slot": "section-header",
+      "data-size": size,
+      className: cn("flex flex-col", SIZE[size].root, className),
+      ...props,
+      children: [
+        /* @__PURE__ */ jsx(
+          HeadingRow,
+          {
+            as: titleAs,
+            title,
+            titleId: titleId ?? generatedId,
+            titleClassName: SIZE[size].title,
+            band: "flex min-h-(--control-sm) items-center mt-[min(0px,calc((var(--control-sm)_-_1lh)/2))]",
+            actions
+          }
+        ),
+        description ? /* @__PURE__ */ jsx("p", { className: cn("max-w-(--measure-prose) text-pretty text-muted-foreground", SIZE[size].description), children: description }) : null
+      ]
+    }
+  );
 }
 SectionHeader.displayName = "SectionHeader";
 export {

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

@@ -14,7 +14,9 @@ var sectionHeaderMeta = {
     "h2",
     "subsection",
     "optical alignment",
-    "bleed"
+    "bleed",
+    "editorial section",
+    "large section title"
   ],
   usage: {
     description: "Use SectionHeader to head each section below the page title \u2014 a home-page shelf with View all, a settings group, a list with its own actions. PageHeader is the route's single h1; every section under it takes a SectionHeader, with titleId wired to the section's aria-labelledby.",
@@ -25,7 +27,7 @@ var sectionHeaderMeta = {
       },
       {
         guidance: "do",
-        description: "Pick titleAs by the document outline (h2 under the page h1, h3 inside an h2 section) and size by visual weight: md for a page's sections and shelves, sm for denser groups like settings."
+        description: `Pick titleAs by the document outline (h2 under the page h1, h3 inside an h2 section) and size by visual weight: lg for an editorial page's sections under a PageHeader size="lg", md for a page's sections and shelves, sm for denser groups like settings.`
       },
       {
         guidance: "do",
@@ -87,13 +89,13 @@ var sectionHeaderMeta = {
     },
     {
       name: "size",
-      type: '"md" | "sm"',
+      type: '"lg" | "md" | "sm"',
       default: '"md"',
-      description: "Visual weight, independent of the heading level: md (text-heading-3) for a page's sections and shelves; sm (text-heading-4) for denser sets \u2014 settings groups, subsections."
+      description: `Visual weight, independent of the heading level: lg (text-heading-2 over a text-body-md description) for an editorial page's sections, under a PageHeader size="lg"; md (text-heading-3) for a page's sections and shelves; sm (text-heading-4) for denser sets \u2014 settings groups, subsections. lg stops at heading-2: heading-1 is the page title's, one per route. The actions stay centred on the title's first line at every size.`
     }
   ],
   variants: {
-    size: ["md", "sm"]
+    size: ["lg", "md", "sm"]
   },
   tokensUsed: ["foreground", "muted-foreground"],
   a11y: [
@@ -161,6 +163,26 @@ var sectionHeaderMeta = {
 		<Entity className="[--entity-px:0]" title="Late drives" subtitle="42 tracks" />
 		<Entity className="[--entity-px:0]" title="Focus" subtitle="18 tracks" />
 	</Stack>
+</section>`
+    },
+    {
+      label: "An editorial section (size lg)",
+      code: `<section aria-labelledby="selected-work" className="flex flex-col gap-6">
+	<SectionHeader
+		titleId="selected-work"
+		size="lg"
+		title="Selected work"
+		description="Five projects from the last two years."
+		actions={
+			<Button variant="ghost" size="sm" render={<a href="/work" />} aria-label="View all work">
+				View all
+			</Button>
+		}
+	/>
+	<Grid minItemWidth="16rem" gap={3}>
+		<Card><CardHeader><CardTitle>Tidewater</CardTitle><CardDescription>Brand identity</CardDescription></CardHeader></Card>
+		<Card><CardHeader><CardTitle>Northlight</CardTitle><CardDescription>Product design</CardDescription></CardHeader></Card>
+	</Grid>
 </section>`
     },
     {

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

@@ -0,0 +1,7 @@
+// src/components/section-rail/index.ts
+import { SectionRail } from "./section-rail.js";
+import { sectionRailMeta } from "./section-rail.meta.js";
+export {
+  SectionRail,
+  sectionRailMeta
+};

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

@@ -0,0 +1,153 @@
+"use client";
+
+// src/components/section-rail/section-rail.tsx
+import {
+  useCallback,
+  useEffect,
+  useRef,
+  useState
+} from "react";
+import { cn } from "../../lib/cn.js";
+import { HighlightGlide } from "../../lib/highlight-glide.js";
+import { setRef } from "../../lib/refs.js";
+import { useActiveSection } from "../../lib/use-active-section.js";
+import { useMotionLevel } from "../../motion/MotionProvider.js";
+import { SimpleTooltip, TooltipGroup } from "../tooltip/index.js";
+import { jsx, jsxs } from "react/jsx-runtime";
+var SCROLL_KEYS = /* @__PURE__ */ new Set(["ArrowUp", "ArrowDown", "PageUp", "PageDown", "Home", "End", " "]);
+var GLIDE_HANDOFF = "[&[data-glide]_[data-active]>[data-section-rail-mark]]:opacity-0";
+var GLIDE_MARK = "flex items-center justify-center motion-glide after:h-5 after:w-1 after:rounded-full after:bg-primary";
+function SectionRail({
+  sections,
+  value,
+  onValueChange,
+  offset,
+  root,
+  side = "left",
+  motion,
+  className,
+  "aria-label": ariaLabel = "Sections",
+  ref,
+  ...props
+}) {
+  const rail = useRef(null);
+  const setRail = useCallback(
+    (node) => {
+      rail.current = node;
+      setRef(ref, node);
+    },
+    [ref]
+  );
+  const { enabled, attribute } = useMotionLevel(motion);
+  const spied = useActiveSection(
+    sections.map((section) => section.id),
+    { offset, root }
+  );
+  const [picked, setPicked] = useState(null);
+  const internal = picked ?? spied;
+  const active = value ?? internal;
+  const report = useRef(onValueChange);
+  report.current = onValueChange;
+  const reported = useRef(internal);
+  useEffect(() => {
+    if (internal === null || internal === reported.current) return;
+    reported.current = internal;
+    report.current?.(internal);
+  }, [internal]);
+  useEffect(() => {
+    if (picked === null) return;
+    const release = () => setPicked(null);
+    const releaseOnKey = (event) => {
+      if (SCROLL_KEYS.has(event.key)) release();
+    };
+    const listeners = new AbortController();
+    const options = { passive: true, signal: listeners.signal };
+    window.addEventListener("wheel", release, options);
+    window.addEventListener("touchstart", release, options);
+    window.addEventListener("keydown", releaseOnKey, options);
+    window.addEventListener(
+      "pointerdown",
+      (event) => {
+        if (!(event.target instanceof Node && rail.current?.contains(event.target))) release();
+      },
+      options
+    );
+    return () => listeners.abort();
+  }, [picked]);
+  const jump = (event, id) => {
+    if (event.defaultPrevented || event.button !== 0) return;
+    if (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return;
+    const section = document.getElementById(id);
+    if (!section) return;
+    event.preventDefault();
+    setPicked(id);
+    const behavior = enabled ? "auto" : "instant";
+    const scroller = root?.current;
+    if (scroller) {
+      const margin = Number.parseFloat(getComputedStyle(section).scrollMarginTop) || 0;
+      const top = section.getBoundingClientRect().top - scroller.getBoundingClientRect().top - scroller.clientTop;
+      scroller.scrollTo({ top: scroller.scrollTop + top - margin, behavior });
+    } else {
+      section.scrollIntoView({ behavior, block: "start" });
+      window.history.replaceState(window.history.state, "", `#${id}`);
+    }
+    if (event.detail === 0) {
+      if (!section.hasAttribute("tabindex")) {
+        section.setAttribute("tabindex", "-1");
+        section.addEventListener("blur", () => section.removeAttribute("tabindex"), { once: true });
+      }
+      section.focus({ preventScroll: true });
+    }
+  };
+  return /* @__PURE__ */ jsxs(
+    "nav",
+    {
+      ref: setRail,
+      "aria-label": ariaLabel,
+      "data-motion": attribute,
+      className: cn(
+        "relative flex w-fit flex-col rounded-full bg-muted py-2",
+        GLIDE_HANDOFF,
+        className
+      ),
+      ...props,
+      children: [
+        /* @__PURE__ */ jsx(HighlightGlide, { follow: "data-active", timing: "selection", className: GLIDE_MARK }),
+        /* @__PURE__ */ jsx(TooltipGroup, { motion, children: sections.map((section) => {
+          const current = section.id === active;
+          return /* @__PURE__ */ jsx(
+            SimpleTooltip,
+            {
+              content: section.label,
+              side: side === "left" ? "right" : "left",
+              children: /* @__PURE__ */ jsx(
+                "a",
+                {
+                  href: `#${section.id}`,
+                  "aria-label": section.label,
+                  "aria-current": current ? "location" : void 0,
+                  "data-active": current ? "" : void 0,
+                  onClick: (event) => jump(event, section.id),
+                  className: "group/rail-link relative flex h-(--control-sm) w-11 items-center justify-center rounded-full text-muted-foreground outline-none motion-interactive hover:text-foreground focus-visible:ring-2 focus-visible:ring-ring",
+                  children: /* @__PURE__ */ jsx(
+                    "span",
+                    {
+                      "aria-hidden": true,
+                      "data-section-rail-mark": "",
+                      className: "size-1 rounded-full bg-current motion-interactive group-hover/rail-link:scale-150 group-focus-visible/rail-link:scale-150 group-data-[active]/rail-link:h-5 group-data-[active]/rail-link:bg-primary"
+                    }
+                  )
+                }
+              )
+            },
+            section.id
+          );
+        }) })
+      ]
+    }
+  );
+}
+SectionRail.displayName = "SectionRail";
+export {
+  SectionRail
+};

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

@@ -0,0 +1,189 @@
+// src/components/section-rail/section-rail.meta.ts
+var sectionRailMeta = {
+  name: "SectionRail",
+  summary: "A slim vertical rail of dots, one per section of a long page, that shows where the reader is and jumps to any section. The current section's bar glides as the page scrolls; a shared tooltip names each dot.",
+  keywords: [
+    "section rail",
+    "scroll spy",
+    "scrollspy",
+    "dot navigation",
+    "page navigation",
+    "table of contents",
+    "on this page",
+    "chapter nav",
+    "scroll progress",
+    "case study nav"
+  ],
+  usage: {
+    description: "Use SectionRail beside a long, single-column read \u2014 a case study, an essay, a long landing page \u2014 so the reader can see which section they are in and jump to another without leaving the text. It follows the scroll by itself (useActiveSection); pass value when the parent already knows the current section.",
+    bestPractices: [
+      {
+        guidance: "do",
+        description: "Give every section an id that matches its entry, and keep the list to the page's top-level sections \u2014 about ten at most, so the rail stays shorter than the viewport."
+      },
+      {
+        guidance: "do",
+        description: "Place it with layout classes \u2014 usually `fixed top-1/2 left-6 z-(--z-nav) -translate-y-1/2` \u2014 and hide it below the width where it would overlap the text (`max-lg:hidden`). Offer the same links another way on narrow screens, such as a Collapsible list at the top of the page."
+      },
+      {
+        guidance: "do",
+        description: "Pass `root` when the content scrolls inside an element (a Scroller, an inset AppShell main) rather than the window, and give sections `scroll-mt-*` when a sticky header would cover their tops after a jump."
+      },
+      {
+        guidance: "do",
+        description: 'Set `side="right"` when the rail sits on the right edge, so labels open toward the content.'
+      },
+      {
+        guidance: "dont",
+        description: "Use it for app navigation between pages; that is SideNav or Sidebar. A SectionRail only moves within one page.",
+        instead: ["SideNav", "Sidebar"]
+      },
+      {
+        guidance: "dont",
+        description: "Use it to show the steps of a task or a flow; that is Stepper, which shows progress through steps rather than position in a read.",
+        instead: ["Stepper"]
+      },
+      {
+        guidance: "dont",
+        description: "Use it for a handful of switchable views in one place; that is Tabs.",
+        instead: ["Tabs"]
+      }
+    ],
+    anatomy: [
+      {
+        name: "Rail",
+        required: true,
+        description: "The `<nav>` landmark: a rounded muted track holding one link per section."
+      },
+      {
+        name: "Dot",
+        required: true,
+        description: "A link to `#id`, drawn as a small dot that grows under the pointer or focus."
+      },
+      {
+        name: "Marker",
+        required: true,
+        description: "One primary bar that sits on the current section's dot and glides to the next."
+      },
+      {
+        name: "Label",
+        required: true,
+        description: "A shared tooltip that names the hovered or focused dot and travels between dots."
+      }
+    ]
+  },
+  related: {
+    components: ["SideNav", "Tooltip", "Stepper", "Tabs", "GlidingHighlight"]
+  },
+  status: "stable",
+  props: [
+    {
+      name: "sections",
+      type: "readonly { id: string; label: string }[]",
+      description: "The sections, in document order. `id` is the section element's id (the link goes to `#id`); `label` is the tooltip and the link's accessible name."
+    },
+    {
+      name: "value",
+      type: "string",
+      description: "The current section's id, when the parent decides it. Leave it unset and the rail follows the scroll itself."
+    },
+    {
+      name: "onValueChange",
+      type: "(id: string) => void",
+      description: "Called with the new id when the reader scrolls into a section or picks one."
+    },
+    {
+      name: "offset",
+      type: "number",
+      default: "0.35",
+      description: "Where the reading line sits, as a fraction of the viewport from its top. A section becomes current once its top crosses it."
+    },
+    {
+      name: "root",
+      type: "RefObject<HTMLElement | null>",
+      description: "The element that scrolls, when it is not the window."
+    },
+    {
+      name: "side",
+      type: '"left" | "right"',
+      default: '"left"',
+      description: "Which edge of the page the rail sits on. The labels open on the other side, toward the content."
+    },
+    {
+      name: "motion",
+      type: '"full" | "subtle" | "off"',
+      default: '"full"',
+      description: "How much motion this component uses: `full` inherits the app's policy, `subtle` keeps feedback and drops the marker's glide, `off` stills it. It can only turn motion down \u2014 it never overrides a reader's reduce-motion setting."
+    },
+    {
+      name: "aria-label",
+      type: "string",
+      default: '"Sections"',
+      description: `The nav landmark's name. Name it for the page ("Case study sections") when it has other navs.`
+    }
+  ],
+  motion: [
+    {
+      slot: "arrival",
+      recipe: "none",
+      part: "Root",
+      why: "Page chrome arrives with the page; the marker lands on the current section with no transition, because a bar sliding in on load narrates a move nobody made."
+    },
+    {
+      slot: "response",
+      recipe: "motion-interactive",
+      part: "Dot",
+      why: "The dot darkens and grows under the pointer or focus, and the label travels between dots as one tooltip (TooltipGroup) rather than closing and reopening at each."
+    },
+    {
+      slot: "transition",
+      recipe: "motion-glide",
+      part: "Marker",
+      why: "One bar travels to the new section as the page scrolls, so the change reads as movement down the page. A picked section holds the bar until the reader scrolls by hand, so it goes straight there instead of stepping through every section in between, and stays on the pick even when the page ends before that section can reach the reading line. Expressive: `subtle` moves it at once."
+    },
+    {
+      slot: "activity",
+      recipe: "none",
+      part: "Root",
+      why: "Navigation chrome has no working state."
+    }
+  ],
+  a11y: [
+    'Renders a <nav> landmark (default name "Sections") of real links to `#id`, so it works with no script, middle-click and copy-link.',
+    `Each link is named by its section's label; the current one carries aria-current="location".`,
+    "Activating a link from the keyboard moves focus into the section, as following an anchor does, so the next Tab continues from there.",
+    "The tooltip opens on focus as well as hover; the dots are 44\xD732 targets.",
+    "Under reduced motion the jump is instant and the marker moves without travel."
+  ],
+  tokensUsed: ["muted", "muted-foreground", "foreground", "primary", "ring", "popover", "popover-foreground", "border-floating"],
+  examples: [
+    {
+      label: "Fixed beside a long read",
+      code: `<SectionRail
+  aria-label="Case study sections"
+  sections={[
+    { id: "overview", label: "Overview" },
+    { id: "problem", label: "The problem" },
+    { id: "process", label: "Process" },
+    { id: "outcome", label: "Outcome" },
+  ]}
+  className="fixed top-1/2 left-6 z-(--z-nav) -translate-y-1/2 max-lg:hidden"
+/>`
+    },
+    {
+      label: "On the right edge",
+      code: `<SectionRail
+  side="right"
+  sections={[
+    { id: "intro", label: "Introduction" },
+    { id: "usage", label: "Usage" },
+    { id: "api", label: "API" },
+  ]}
+  className="fixed top-1/2 right-6 z-(--z-nav) -translate-y-1/2 max-lg:hidden"
+/>`
+    }
+  ]
+};
+export {
+  sectionRailMeta
+};