@sableui/react 0.15.0 → 0.17.0

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
+};

package/dist/components/segmented-bar/segmented-bar.meta.js

@@ -71,7 +71,14 @@ var segmentedBarMeta = {
     "muted-foreground",
     "success",
     "tone-warning",
-    "destructive"
+    "destructive",
+    "destructive-mark",
+    "success-mark",
+    "tone-warning-mark",
+    "tone-info-mark",
+    "tone-1-mark",
+    "tone-2-mark",
+    "tone-3-mark"
   ],
   motion: [
     {

package/dist/components/segmented-bar/segmented-bar.variants.js

@@ -5,15 +5,15 @@ var segmentedBarSegmentVariants = cva(
   {
     variants: {
       tone: {
-        "1": "bg-tone-1",
-        "2": "bg-tone-2",
-        "3": "bg-tone-3",
-        info: "bg-tone-info",
+        "1": "bg-tone-1-mark",
+        "2": "bg-tone-2-mark",
+        "3": "bg-tone-3-mark",
+        info: "bg-tone-info-mark",
         primary: "bg-primary",
         neutral: "bg-muted-foreground",
-        success: "bg-success",
-        warning: "bg-tone-warning",
-        destructive: "bg-destructive"
+        success: "bg-success-mark",
+        warning: "bg-tone-warning-mark",
+        destructive: "bg-destructive-mark"
       }
     },
     defaultVariants: {

package/dist/components/select/select.js

@@ -72,7 +72,7 @@ function SelectTrigger({
       className: cn(
         `flex w-full items-center justify-between ${tier.body} text-foreground motion-interactive`,
         mobileTier,
-        size === "xs" ? cn("h-(--control-xs) gap-1 px-1.5", FIELD_SHELL_XS) : "h-(--control-md) gap-2 rounded-sm border border-input bg-card px-3",
+        size === "xs" ? cn("h-(--control-xs) gap-1 px-1.5", FIELD_SHELL_XS) : "h-(--control-md) gap-2 rounded-sm border border-field-border bg-field px-3",
         "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
         "data-[popup-open]:ring-2 data-[popup-open]:ring-ring",
         // Invalid like every other field: Base UI marks the trigger

package/dist/components/select/select.meta.js

@@ -124,8 +124,8 @@ var selectMeta = {
     }
   ],
   tokensUsed: [
-    "input",
-    "card",
+    "field-border",
+    "field",
     "foreground",
     "ring",
     "border",

package/dist/components/sheet/sheet.js

@@ -61,11 +61,12 @@ function useKeyboardInset(enabled) {
       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);
+    const listeners = new AbortController();
+    const { signal } = listeners;
+    viewport.addEventListener("resize", measure, { signal });
+    viewport.addEventListener("scroll", measure, { signal });
     return () => {
-      viewport.removeEventListener("resize", measure);
-      viewport.removeEventListener("scroll", measure);
+      listeners.abort();
       setInset(0);
     };
   }, [enabled]);

package/dist/components/sidebar/sidebar.js

@@ -10,6 +10,7 @@ import {
 import { cn } from "../../lib/cn.js";
 import { HighlightGlide } from "../../lib/highlight-glide.js";
 import { motionAttribute } from "../../motion/MotionProvider.js";
+import { useAppShellFrame } from "../app-shell/app-shell-frame.js";
 import { RAIL_ROW_INLINE, sideNavItemIconVariants, sideNavItemVariants } from "../side-nav/side-nav.variants.js";
 import { SimpleTooltip } from "../tooltip/index.js";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
@@ -27,6 +28,8 @@ var SIDEBAR_VARIANT = {
   app: "hidden lg:flex lg:sticky lg:top-0 lg:h-[calc(100vh-var(--dock-height,0px))] lg:self-start",
   inline: "flex h-full"
 };
+var INSET_RAIL = "lg:h-auto lg:self-stretch";
+var INSET_RAIL_SURFACE = "lg:border-r-0 lg:[--sidebar:var(--shell-ground)]";
 var SIDEBAR_INK = [
   "[--background:var(--sidebar)] [--sable-surface-bg:var(--sidebar)]",
   "[--foreground:var(--sidebar-foreground)]",
@@ -54,6 +57,7 @@ function Sidebar({
 }) {
   const [hasCollapsed, setHasCollapsed] = useState(collapsed);
   if (collapsed && !hasCollapsed) setHasCollapsed(true);
+  const inset = useAppShellFrame() === "inset";
   return /* @__PURE__ */ jsx(SidebarContext.Provider, { value: { collapsed, icons, reopened: hasCollapsed && !collapsed }, children: /* @__PURE__ */ jsx(
     "aside",
     {
@@ -61,6 +65,7 @@ function Sidebar({
       "data-collapsed": collapsed || void 0,
       "data-variant": variant,
       "data-surface": surface,
+      "data-frame": inset ? "inset" : void 0,
       className: cn(
         "shrink-0 flex-col bg-sidebar text-sidebar-foreground",
         // The rail is its own surface. Anything placed in it that inks with
@@ -71,8 +76,11 @@ function Sidebar({
         // a theme names --sidebar-muted-foreground.
         // 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,
+        // In an inset AppShell the rail is the ground itself, so from lg its border
+        // goes too: the gap around the main panel is the divider.
+        surface === "rail" ? cn("border-r border-sidebar-border", inset && INSET_RAIL_SURFACE, SIDEBAR_INK) : PAGE_INK,
         SIDEBAR_VARIANT[variant],
+        inset && INSET_RAIL,
         "w-[var(--sidebar-width,16rem)] data-[collapsed]:w-[var(--sidebar-width-collapsed,4rem)]",
         // Collapsing eases the width (`motion-size`, expressive) rather than
         // jumping 192px in one frame. It reflows the page beside the rail for
@@ -164,11 +172,18 @@ function SidebarFooter({
   className,
   ...props
 }) {
+  const inset = useAppShellFrame() === "inset";
   return /* @__PURE__ */ jsx(
     "div",
     {
       className: cn(
         "flex flex-col gap-1 border-t border-sidebar-border px-3 py-4",
+        // In an inset shell the rail has no edge of its own (the gap is the
+        // divider), so a full-width rule ran out into that gap and stopped on
+        // nothing. Inset to the content column it spans what the rows span:
+        // the padding becomes margin, so the rule shortens and nothing inside
+        // moves.
+        inset && "lg:mx-3 lg:px-0",
         className
       ),
       ...props

package/dist/components/sidebar/sidebar.meta.js

@@ -24,6 +24,10 @@ var sidebarMeta = {
         guidance: "do",
         description: `Set surface="page" when a full-width top bar sits above the rail. A theme's tinted or dark rail is for a full-height rail that frames the app.`
       },
+      {
+        guidance: "do",
+        description: `Keep surface="rail" inside AppShell frame="inset": the rail's tint becomes the ground the main panel floats on. Do not add a border-r class back \u2014 the gap is the divider.`
+      },
       {
         guidance: "dont",
         description: "Do not use Sidebar for page-local settings, filters, or temporary action groups."
@@ -76,7 +80,7 @@ var sidebarMeta = {
       name: "surface",
       type: '"rail" | "page"',
       default: '"rail"',
-      description: `Which surface the rail is painted on. "rail" is its own --sidebar-* surface with a border \u2014 right for a full-height rail that frames the app, which a theme may tint or paint dark. "page" uses the page's surface and ink with no border \u2014 use it when a full-width header sits above the rail, where a tinted column starting under a page-coloured bar reads as pasted on. Use it instead of overriding bg-/text- classes, which the rail's re-pointed tokens defeat.`
+      description: `Which surface the rail is painted on. "rail" is its own --sidebar-* surface with a border \u2014 right for a full-height rail that frames the app, which a theme may tint or paint dark. "page" uses the page's surface and ink with no border \u2014 use it when a full-width header sits above the rail, where a tinted column starting under a page-coloured bar reads as pasted on. Use it instead of overriding bg-/text- classes, which the rail's re-pointed tokens defeat. In AppShell's sidebar slot with frame="inset", the rail's surface is also the shell's ground: from lg a "rail" rail drops its border (the gap around the main panel divides them) and either surface stretches to the shell's body row instead of sizing to the viewport. AppShell signals this to its sidebar slot only, so a Sidebar elsewhere in the page is unaffected.`
     },
     {
       name: "motion",
@@ -146,7 +150,8 @@ var sidebarMeta = {
     "sidebar-border",
     "sidebar-accent",
     "sidebar-accent-foreground",
-    "sidebar-ring"
+    "sidebar-ring",
+    "shell-ground"
   ],
   variants: {
     variant: ["app", "inline"]

package/dist/components/sparkline/sparkline.meta.js

@@ -106,7 +106,14 @@ var sparklineMeta = {
     "tone-warning",
     "muted-foreground",
     "success",
-    "destructive"
+    "destructive",
+    "destructive-mark",
+    "success-mark",
+    "tone-warning-mark",
+    "tone-info-mark",
+    "tone-1-mark",
+    "tone-2-mark",
+    "tone-3-mark"
   ],
   motion: [
     {

package/dist/components/status-dot/status-dot.meta.js

@@ -83,7 +83,14 @@ var statusDotMeta = {
     "tone-info",
     "tone-1",
     "tone-2",
-    "destructive"
+    "destructive",
+    "destructive-mark",
+    "success-mark",
+    "tone-warning-mark",
+    "tone-info-mark",
+    "tone-1-mark",
+    "tone-2-mark",
+    "tone-3-mark"
   ],
   a11y: [
     "Rendered aria-hidden \u2014 purely decorative. Convey status in adjacent text, not color alone.",

package/dist/components/status-dot/status-dot.variants.js

@@ -4,13 +4,13 @@ var statusDotVariants = cva("inline-block shrink-0 rounded-full", {
   variants: {
     tone: {
       neutral: "bg-muted-foreground",
-      "3": "bg-tone-3",
-      success: "bg-success",
-      warning: "bg-tone-warning",
-      info: "bg-tone-info",
-      "1": "bg-tone-1",
-      "2": "bg-tone-2",
-      destructive: "bg-destructive",
+      "3": "bg-tone-3-mark",
+      success: "bg-success-mark",
+      warning: "bg-tone-warning-mark",
+      info: "bg-tone-info-mark",
+      "1": "bg-tone-1-mark",
+      "2": "bg-tone-2-mark",
+      destructive: "bg-destructive-mark",
       // A palette family paints from the slot its data-palette scope fills.
       red: "bg-palette-dot",
       orange: "bg-palette-dot",

package/dist/components/stepper/stepper.meta.js

@@ -115,7 +115,8 @@ var stepperMeta = {
     "border-strong",
     "destructive",
     "destructive-foreground",
-    "ring"
+    "ring",
+    "destructive-mark"
   ],
   motion: [
     {

package/dist/components/stepper/stepper.variants.js

@@ -24,7 +24,7 @@ var stepperDotVariants = cva(
         complete: "bg-primary",
         current: "bg-[var(--sable-surface-bg,var(--background))] ring-[0.1875em] ring-primary ring-inset",
         upcoming: "bg-border-strong",
-        error: "bg-destructive"
+        error: "bg-destructive-mark"
       }
     },
     defaultVariants: {

package/dist/components/table/table.meta.js

@@ -100,13 +100,13 @@ var tableMeta = {
     },
     {
       name: "TableHead",
-      type: 'ComponentPropsWithRef<"th">',
-      description: "A column header cell (th) in muted label styling."
+      type: 'ComponentPropsWithRef<"th"> & { numeric?: boolean }',
+      description: "A column header cell (th) in muted label styling. `numeric` marks a number column: end-aligned, tabular figures \u2014 set it on the column's cells too."
     },
     {
       name: "TableCell",
-      type: 'ComponentPropsWithRef<"td">',
-      description: "A data cell (td)."
+      type: 'ComponentPropsWithRef<"td"> & { numeric?: boolean }',
+      description: "A data cell (td). `numeric` end-aligns it with tabular figures, matching its column's header."
     },
     {
       name: "TableCaption",

package/dist/components/textarea/textarea.js

@@ -23,6 +23,11 @@ function Textarea({
         // already lost the invalid ring Input shows on focus.
         FIELD_SHELL,
         FIELD_INVALID,
+        // Text being edited must not rewrap above the caret. `text-wrap-style`
+        // inherits, so a field inside a `text-pretty` or `text-balance` block
+        // would re-break every earlier line on each keystroke; `stable` is
+        // what an editing surface asks for. Longhand only: the wrap mode stays.
+        "[text-wrap-style:stable]",
         autoResize && "field-sizing-content resize-none",
         tier.body,
         density === "comfortable" && MOBILE_FIELD_TIER,

package/dist/components/textarea/textarea.meta.js

@@ -1,7 +1,7 @@
 // src/components/textarea/textarea.meta.ts
 var textareaMeta = {
   name: "Textarea",
-  summary: "Styled native multi-line text control. Soft-square, card surface, --ring focus, and an aria-invalid destructive error state.",
+  summary: "Styled native multi-line text control. Soft-square, the theme's field surface, --ring focus, and an aria-invalid destructive error state.",
   status: "stable",
   keywords: [
     "textarea",
@@ -75,8 +75,8 @@ var textareaMeta = {
     }
   ],
   tokensUsed: [
-    "input",
-    "card",
+    "field-border",
+    "field",
     "foreground",
     "muted-foreground",
     "ring",