@sableui/react 0.16.0 → 0.17.0

package/dist/index.d.ts

@@ -9,7 +9,7 @@ export { AspectBox, AspectBoxProps, Bleed, BleedProps, Breakpoint, Center, Cente
 export { Icon, IconContextValue, IconProps, IconProvider, IconProviderProps, composeIconSets, useIconSet } from './icon/index.js';
 export { a as IconRenderProps, I as IconSet, b as IconVariant } from './registry-CyL28OzJ.js';
 import * as react from 'react';
-import { ReactNode, AnimationEvent, ComponentPropsWithoutRef, ElementType, ReactElement, Ref, ComponentPropsWithRef, MouseEvent, ComponentProps, AriaAttributes, FormEvent } from 'react';
+import { ReactNode, AnimationEvent, ComponentPropsWithoutRef, ElementType, ReactElement, Ref, ComponentPropsWithRef, MouseEvent, ComponentProps, AriaAttributes, RefObject, FormEvent } from 'react';
 import { VariantProps } from 'class-variance-authority';
 import { useRender } from '@base-ui/react/use-render';
 import * as class_variance_authority_types from 'class-variance-authority/types';
@@ -6471,6 +6471,67 @@ declare namespace SideNavItem {
 
 declare const sideNavMeta: ComponentMeta;
 
+interface SectionRailSection {
+    /** The section element's `id` — the rail links to `#id` and watches it. */
+    id: string;
+    /** The section's name: the tooltip, and the link's accessible name. */
+    label: string;
+}
+interface SectionRailProps extends Omit<ComponentPropsWithRef<"nav">, "children"> {
+    /** The sections, in document order. */
+    sections: readonly SectionRailSection[];
+    /**
+     * The current section's id, when the parent decides it. Leave it unset and
+     * the rail follows the scroll itself.
+     */
+    value?: string;
+    /** Called with the new id when the reader scrolls into a section or picks one. */
+    onValueChange?: (id: string) => void;
+    /**
+     * Where the reading line sits, as a fraction of the viewport from its top.
+     * A section becomes current once its top crosses it.
+     * @default 0.35
+     */
+    offset?: number;
+    /** The element that scrolls, when it is not the window. */
+    root?: RefObject<HTMLElement | null>;
+    /**
+     * Which edge of the page the rail sits on. The labels open toward the
+     * content, on the other side.
+     * @default "left"
+     */
+    side?: "left" | "right";
+    /**
+     * How much motion this component uses: `full` (default) inherits the app's
+     * policy, `subtle` keeps feedback and drops the marker's glide, `off` stills
+     * it. It can only turn motion down — it never overrides a reader's
+     * reduce-motion setting.
+     */
+    motion?: MotionLevel;
+}
+/**
+ * SectionRail — a slim vertical rail of dots, one per section of a long page,
+ * that shows where the reader is and jumps to any section. A bar marks the
+ * current section and glides to the next as the page scrolls; hovering or
+ * focusing a dot names its section in a tooltip that travels with the pointer.
+ *
+ *   <SectionRail
+ *     sections={[{ id: "overview", label: "Overview" }, { id: "process", label: "Process" }]}
+ *     className="fixed top-1/2 left-6 z-(--z-nav) -translate-y-1/2 max-lg:hidden"
+ *   />
+ *
+ * It renders in flow; place it with layout classes. Picking a dot scrolls to
+ * the section with the page's own `scroll-behavior` (instantly under reduced
+ * motion) and, at page level, puts its id in the URL without adding a history
+ * entry. Give sections a `scroll-mt-*` when a sticky header would cover them.
+ */
+declare function SectionRail({ sections, value, onValueChange, offset, root, side, motion, className, "aria-label": ariaLabel, ref, ...props }: SectionRailProps): react.JSX.Element;
+declare namespace SectionRail {
+    var displayName: string;
+}
+
+declare const sectionRailMeta: ComponentMeta;
+
 /**
  * BottomNav — the mobile bottom tab bar. Fixed to the bottom edge, hidden at
  * `lg` (the desktop Sidebar takes over). Pads the home-indicator safe area and
@@ -9880,6 +9941,39 @@ interface SmoothWheelOptions {
  */
 declare function useSmoothWheel({ axis, mapVertical, smooth, }?: SmoothWheelOptions): (node: HTMLElement | null) => void;
 
-declare const SABLE_UI_VERSION: "0.16.0";
+interface UseActiveSectionOptions {
+    /**
+     * Where the reading line sits, as a fraction of the viewport's height from
+     * its top. A section becomes current once its top crosses the line, so the
+     * one being read wins over the one merely peeking in at the bottom.
+     * @default 0.35
+     */
+    offset?: number;
+    /**
+     * The element that scrolls, when it is not the window — a `Scroller`, an
+     * inset `AppShell` main, a docs preview.
+     */
+    root?: RefObject<HTMLElement | null>;
+}
+/**
+ * useActiveSection — which of these sections the reader is in. The scroll spy
+ * behind `SectionRail`, exported for a contents list a consumer draws itself
+ * (an "On this page" column, a chapter select).
+ *
+ *   const active = useActiveSection(["intro", "usage", "api"])
+ *
+ * The current section is the last one, in the order given, whose top has
+ * crossed the reading line (`offset`). Before any has, the first one is
+ * current: the reader is at the start. Once the scroller reaches its end the
+ * last section in view wins instead, because a short closing section can never
+ * climb to the line and would otherwise never become current.
+ *
+ * Measures on scroll and resize, at most once a frame. Ids missing from the
+ * document are skipped, so sections may mount late. Returns `null` only for an
+ * empty list.
+ */
+declare function useActiveSection(ids: readonly string[], { offset, root }?: UseActiveSectionOptions): string | null;
+
+declare const SABLE_UI_VERSION: "0.17.0";
 
-export { Accordion, AccordionItem, AccordionPanel, AccordionTrigger, AlertDialog, AlertDialogClose, AlertDialogContent, AlertDialogDescription, AlertDialogFooter, AlertDialogHeader, AlertDialogOverlay, AlertDialogTitle, AlertDialogTrigger, AppHeader, type AppHeaderProps, AppShell, type AppShellProps, AreaChart, type AreaChartProps, type ArtIntensity, type ArtTone, Attachment, type AttachmentProps, Avatar, AvatarFallback, AvatarGroup, AvatarGroupCount, type AvatarGroupCountProps, type AvatarGroupProps, AvatarImage, type AvatarProps, AvatarRoot, BADGE_APPEARANCES, BADGE_TONES, Badge, type BadgeAppearance, type BadgeProps, type BadgeTone, Banner, type BannerProps, BarChart, type BarChartProps, BottomNav, BottomNavItem, type BottomNavItemProps, BreadcrumbItem, type BreadcrumbItemProps, BreadcrumbLink, type BreadcrumbLinkProps, BreadcrumbPage, type BreadcrumbPageProps, BreadcrumbSeparator, type BreadcrumbSeparatorProps, Breadcrumbs, type BreadcrumbsProps, Browser, type BrowserProps, Bubble, type BubbleProps, BubbleReaction, BubbleReactionAdd, type BubbleReactionAddProps, type BubbleReactionProps, BubbleReactions, type BubbleReactionsProps, Burst, type BurstProps, Button, type ButtonBleed, ButtonGroup, type ButtonGroupProps, type ButtonProps, CHART_SERIES_COUNT, COMPONENT_GROUPS, COMPONENT_TAXONOMY, Calendar, type CalendarProps, Card, CardAction, CardContent, type CardContentProps, CardDescription, CardFooter, type CardFooterProps, CardHeader, CardList, type CardProps, CardTitle, type CardTitleProps, CaretMenu, CaretMenuItem, type CaretMenuItemProps, type CaretMenuProps, type CaretTrigger, type CaretTriggerField, type CaretTriggerMatch, Carousel, type CarouselProps, type CarouselSlidesToShow, type ChartCategories, type ChartCenterLabel, type ChartCurve, type ChartDatum, type ChartSeries, type ChartTone, type ChartTooltipIndicator, type ChartTooltipOptions, type ChartValueFormatter, ChatComposer, type ChatComposerProps, Checkbox, CheckboxCard, type CheckboxCardProps, type CheckboxCardTone, CheckboxGroup, type CheckboxGroupProps, Code, CodeBlock, type CodeBlockProps, CodeHighlightProvider, type CodeHighlighter, type CodeProps, Collapsible, CollapsibleIndicator, CollapsiblePanel, CollapsibleTrigger, ColorField, type ColorFieldProps, Combobox, ComboboxChips, ComboboxClear, ComboboxContent, ComboboxEmpty, ComboboxGroup, ComboboxGroupLabel, ComboboxInput, ComboboxItem, type ComboboxItemGroup, ComboboxItemIndicator, ComboboxList, ComboboxPortal, type ComboboxProps, ComboboxValue, ComboboxVirtualList, type ComboboxVirtualListProps, type CommandFilter, type CommandItem, CommandMenu, CommandMenuGroup, type CommandMenuGroupProps, CommandMenuItem, type CommandMenuItemProps, CommandMenuPanel, type CommandMenuPanelProps, type CommandMenuProps, CommandMenuTrigger, type CommandMenuTriggerProps, type ComponentGroup, type ComponentGuidance, ComponentMeta, type ComponentRegister, ConfirmButton, type ConfirmButtonProps, type ConstraintFlag, ContextCard, ContextCardArrow, ContextCardContent, ContextCardPortal, ContextCardTrigger, ContextMenu, ContextMenuContent, ContextMenuGroup, ContextMenuGroupLabel, ContextMenuItem, ContextMenuPortal, ContextMenuSeparator, ContextMenuTrigger, type CopySource, DEFAULT_REACTIONS, DataTable, type DataTableColumn, type DataTableProps, type DataTableRowKey, DatePicker, type DatePickerProps, DateTile, type DateTileProps, Density, DensityProvider, Density as DensityValue, DestructiveActionModal, type DestructiveActionModalProps, Dialog, DialogClose, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogOverlay, DialogPortal, type DialogSize, DialogTitle, DialogTrigger, DisclosurePicker, DisclosurePickerEmpty, DisclosurePickerList, type DisclosurePickerListProps, DisclosurePickerOption, type DisclosurePickerOptionProps, DisclosurePickerPanel, type DisclosurePickerPanelProps, type DisclosurePickerProps, type DisclosurePickerSearch, DisclosurePickerTrigger, type DisclosurePickerTriggerProps, EmptyState, type EmptyStateProps, Entity, type EntityProps, Feedback, type FeedbackData, type FeedbackProps, type FeedbackRating, Field, type FieldProps, Fieldset, FieldsetContent, FieldsetDescription, FieldsetFooter, FieldsetLegend, type FieldsetVariant, FileDropzone, type FileDropzoneProps, type FileRejection, type FileRejectionCode, FontPicker, type FontPickerFont, type FontPickerOption, type FontPickerProps, Form, type FormProps, GlidingHighlight, type GlidingHighlightProps, GradientArt, type GradientArtProps, type Hsv, InlineStatus, type InlineStatusProps, type StatusTone as InlineTone, Input, InputGroup, type InputGroupProps, type InputProps$1 as InputProps, Kbd, KbdGroup, type KbdGroupProps, type KbdProps, Label, type LabelProps$2 as LabelProps, LikeButton, type LikeButtonProps, LineChart, type LineChartProps, Marker, type MarkerProps, Marquee, type MarqueeProps, MediaImage, type MediaImageProps, MediaTile, type MediaTileProps, Menu, MenuCheckboxItem, MenuContent, MenuGroup, MenuGroupLabel, MenuItem, MenuLinkItem, MenuPortal, MenuRadioGroup, MenuRadioItem, MenuReactions, type MenuReactionsProps, MenuSeparator, MenuSubmenu, MenuSubmenuTrigger, MenuTrigger, Menubar, type MenubarProps, MenubarTrigger, type MenubarTriggerProps, Message, type MessageProps, MessageScroller, type MessageScrollerHandle, type MessageScrollerProps, Meter, MeterIndicator, MeterLabel, type MeterSize, type MeterTone, MeterTrack, MeterValue, MiddleTruncate, type MiddleTruncateProps, type MotionLevel, type MotionPolicy, MotionProvider, type MotionProviderProps, MotionScope, type MotionScopeProps, NavigationMenu, NavigationMenuContent, NavigationMenuItem, NavigationMenuLink, NavigationMenuList, NavigationMenuTrigger, Note, type NoteAction, type NoteProps, NotificationBadge, type NotificationBadgeProps, NumberField, type NumberFieldProps, NumberTicker, type NumberTickerProps, type OrbMode, type OrbSize, OtpField, type OtpFieldProps, OverflowMenu, type OverflowMenuProps, PALETTE_COLORS, PALETTE_FAMILIES, PALETTE_SCALES, PALETTE_STEPS, PALETTE_TONES, PageHeader, type PageHeaderProps, PageLoader, type PageLoaderProps, Pagination, type PaginationProps, type PaletteColor, type PaletteFamily, type PaletteStep, Panel, PanelGroup, PanelResizer, type PanelResizerProps, PanelSection, type PanelWidthBounds, Phone, type PhoneProps, PieChart, type PieChartProps, Pill, type PillProps, Popover, PopoverArrow, PopoverClose, PopoverContent, PopoverDescription, PopoverPortal, PopoverTitle, PopoverTrigger, Presence, type PresenceProps, type Presentation, PresentationProvider, Progress, ProgressIndicator, ProgressLabel, type ProgressSize, ProgressTrack, ProgressValue, PropertyGroup, PropertyPair, PropertyRow, RadarChart, type RadarChartProps, RadialChart, type RadialChartProps, Radio, RadioCard, type RadioCardProps, type RadioCardTone, RadioGroup, type Reaction, ReactionPicker, type ReactionPickerProps, RelativeTime, type RelativeTimeProps, Reveal, type RevealProps, type Rgb, SABLE_UI_VERSION, SEGMENTED_BAR_TONES, STATUS_TONES, STATUS_TONE_ICON, type ScrollCommandOptions, Scroller, type ScrollerProps, ScrubField, type ScrubFieldProps, SearchInput, type SearchInputProps, SectionHeader, type SectionHeaderProps, SegmentedBar, type SegmentedBarProps, type SegmentedBarSegment, type SegmentedBarTone, Select, SelectContent, SelectGroup, SelectGroupLabel, SelectItem, SelectPortal, SelectSeparator, SelectTrigger, SelectValue, Separator, type SeparatorProps$2 as SeparatorProps, SettingsMenu, type SettingsMenuProps, SettingsRow, type SettingsRowProps, Sheet, SheetClose, SheetContent, SheetDescription, SheetFooter, SheetHeader, SheetList, SheetPortal, type SheetProps, type SheetSnapPoint, SheetTitle, SheetTrigger, ShowMore, type ShowMoreProps, SideNav, type SideNavActiveVariant, SideNavGroup, type SideNavGroupProps, SideNavItem, type SideNavItemProps, type SideNavProps, type SideNavSize, Sidebar, SidebarBrand, type SidebarBrandProps, SidebarFooter, SidebarHeader, SidebarItem, type SidebarItemProps, SidebarNav, type SidebarProps, SimpleTooltip, Skeleton, SkipLink, Slider, SliderControl, SliderIndicator, SliderRoot, SliderThumb, SliderTrack, SliderValue, type SmoothWheelOptions, Sparkline, type SparklineProps, Spinner, type SpinnerProps, StatusBar, StatusBarGroup, StatusBarSeparator, StatusDot, type StatusDotProps, type StatusTone, type StepStatus, Stepper, StepperItem, type StepperItemProps, type StepperOrientation, type StepperProps, StreamingText, type StreamingTextProps, Switch, TOOL_CALL_STATUS_LABELS, TRANSPARENT, Table, TableBody, TableCaption, TableCell, TableFooter, TableHead, TableHeader, TableRow, Tabs, TabsPanel as TabsContent, TabsList, TabsPanel, TabsTrigger, TextReveal, type TextRevealProps, Textarea, type TextareaProps, ThemeId, ThemeManifest, ThemeMode$1 as ThemeManifestMode, type ThemeMode, ThemePreview, type ThemePreviewProps, ThemeSelector, type ThemeSelectorProps, ThemeSwitcher, type ThemeSwitcherProps, ThinkingOrb, type ThinkingOrbProps, ToastAction, type ToastApi, ToastClose, ToastContent, ToastDescription, type ToastManagerApi, type ToastOptions, type ToastPosition, ToastProvider, type ToastProviderProps, ToastRoot, ToastTitle, type ToastType, ToastViewport, Toggle, ToggleGroup, type ToggleGroupAppearance, Toggle as ToggleGroupItem, ToolCall, type ToolCallProps, type ToolCallStatus, Toolbar, ToolbarButton, type ToolbarButtonProps, ToolbarGroup, type ToolbarGroupProps, ToolbarInput, type ToolbarInputProps, ToolbarLink, type ToolbarLinkProps, type ToolbarProps, ToolbarSeparator, type ToolbarSeparatorProps, Tooltip, TooltipArrow, TooltipContent, TooltipGroup, type TooltipGroupProps, TooltipPortal, TooltipProvider, TooltipTrigger, Tree, TreeAddRow, TreeEmpty, TreeRow, TreeSection, type UseCaretTriggerOptions, type UseCaretTriggerResult, type UseCopyOptions, type UseCopyResult, type UseInViewOptions, type UseMatchHighlightOptions, type UsePanelWidthOptions, Video, type VideoProps, ViewTransitionName, type ViewTransitionNameProps, Workspace, WorkspaceBar, WorkspaceCanvas, accordionMeta, appHeaderMeta, appShellMeta, areaChartMeta, attachmentMeta, avatarGroupVariants, avatarMeta, avatarVariants, badgeMeta, badgeVariants, bannerMeta, bannerVariants, barChartMeta, bottomNavMeta, breadcrumbsMeta, browserMeta, bubbleMeta, buttonGroupMeta, buttonMeta, buttonVariants, calendarMeta, cardMeta, caretMenuMeta, carouselMeta, chartColor, toneColor as chartToneColor, chatComposerMeta, checkboxCardMeta, checkboxMeta, cn, codeBlockMeta, codeMeta, collapsibleMeta, colorFieldMeta, comboboxMeta, commandMenuMeta, componentGuidance, componentLabel, componentSlug, componentsInGroup, confirmButtonMeta, contextCardMeta, contextMenuMeta, dataTableMeta, datePickerMeta, dateTileMeta, destructiveActionModalMeta, dialogMeta, disclosurePickerMeta, emptyStateMeta, entityMeta, feedbackMeta, fieldsetMeta, fileDropzoneMeta, fileDropzoneVariants, fontPickerMeta, formMeta, formatFileSize, formatHex, glidingHighlightMeta, gradientArtMeta, hsvToRgb, hueColor, inlineStatusMeta, inputGroupMeta, inputMeta, isPaletteColor, isTransparent, kbdMeta, labelMeta, likeButtonMeta, lineChartMeta, markerMeta, marqueeMeta, mediaImageMeta, mediaTileMeta, menuMeta, menubarMeta, messageMeta, messageScrollerMeta, meterIndicatorVariants, meterMeta, meterTrackVariants, middleTruncateMeta, motionAttribute, navigationMenuMeta, noteMeta, noteVariants, notificationBadgeMeta, notificationCountVariants, notificationDotVariants, numberFieldMeta, numberTickerMeta, otpFieldMeta, overflowMenuMeta, pageHeaderMeta, pageLoaderMeta, paginationMeta, panelGroupMeta, panelSectionMeta, parseHex, phoneMeta, pieChartMeta, pillMeta, pillVariants, popoverMeta, progressMeta, progressTrackVariants, radarChartMeta, radialChartMeta, radioCardMeta, radioMeta, reactionPickerMeta, relativeTimeMeta, rgbToHsv, scrollerMeta, scrubFieldMeta, searchInputMeta, sectionHeaderMeta, segmentedBarMeta, segmentedBarSegmentVariants, segmentedBarVariants, selectMeta, separatorMeta, settingsMenuMeta, sheetMeta, sheetVariants, showMoreMeta, sideNavMeta, sidebarMeta, skeletonMeta, sliderMeta, sparklineMeta, spinnerMeta, startViewTransition, statusBarMeta, statusDotMeta, statusDotVariants, stepperConnectorVariants, stepperIndicatorVariants, stepperMeta, streamingTextMeta, supportsViewTransitions, switchMeta, tableMeta, tabsMeta, textareaMeta, themeSelectorMeta, themeSwitcherMeta, thinkingOrbMeta, toast, toastMeta, toggleMeta, toolCallMeta, toolbarGroupVariants, toolbarMeta, toolbarSeparatorVariants, toolbarVariants, tooltipMeta, treeIndent, treeMeta, useAnchoredDensity, useAutoSize, useCaretTrigger, useComboboxFilteredItems, useCommandMenuShortcut, useCopy, useDensity, useDisclosurePicker, useInView, useMatchHighlight, useMotion, useMotionLevel, usePanelWidth, usePresentation, useReducedMotion, useScrollActivity, useShake, useSidebar, useSmoothWheel, useToast, useToastManager, useTypeTier, videoMeta, workspaceMeta };
+export { Accordion, AccordionItem, AccordionPanel, AccordionTrigger, AlertDialog, AlertDialogClose, AlertDialogContent, AlertDialogDescription, AlertDialogFooter, AlertDialogHeader, AlertDialogOverlay, AlertDialogTitle, AlertDialogTrigger, AppHeader, type AppHeaderProps, AppShell, type AppShellProps, AreaChart, type AreaChartProps, type ArtIntensity, type ArtTone, Attachment, type AttachmentProps, Avatar, AvatarFallback, AvatarGroup, AvatarGroupCount, type AvatarGroupCountProps, type AvatarGroupProps, AvatarImage, type AvatarProps, AvatarRoot, BADGE_APPEARANCES, BADGE_TONES, Badge, type BadgeAppearance, type BadgeProps, type BadgeTone, Banner, type BannerProps, BarChart, type BarChartProps, BottomNav, BottomNavItem, type BottomNavItemProps, BreadcrumbItem, type BreadcrumbItemProps, BreadcrumbLink, type BreadcrumbLinkProps, BreadcrumbPage, type BreadcrumbPageProps, BreadcrumbSeparator, type BreadcrumbSeparatorProps, Breadcrumbs, type BreadcrumbsProps, Browser, type BrowserProps, Bubble, type BubbleProps, BubbleReaction, BubbleReactionAdd, type BubbleReactionAddProps, type BubbleReactionProps, BubbleReactions, type BubbleReactionsProps, Burst, type BurstProps, Button, type ButtonBleed, ButtonGroup, type ButtonGroupProps, type ButtonProps, CHART_SERIES_COUNT, COMPONENT_GROUPS, COMPONENT_TAXONOMY, Calendar, type CalendarProps, Card, CardAction, CardContent, type CardContentProps, CardDescription, CardFooter, type CardFooterProps, CardHeader, CardList, type CardProps, CardTitle, type CardTitleProps, CaretMenu, CaretMenuItem, type CaretMenuItemProps, type CaretMenuProps, type CaretTrigger, type CaretTriggerField, type CaretTriggerMatch, Carousel, type CarouselProps, type CarouselSlidesToShow, type ChartCategories, type ChartCenterLabel, type ChartCurve, type ChartDatum, type ChartSeries, type ChartTone, type ChartTooltipIndicator, type ChartTooltipOptions, type ChartValueFormatter, ChatComposer, type ChatComposerProps, Checkbox, CheckboxCard, type CheckboxCardProps, type CheckboxCardTone, CheckboxGroup, type CheckboxGroupProps, Code, CodeBlock, type CodeBlockProps, CodeHighlightProvider, type CodeHighlighter, type CodeProps, Collapsible, CollapsibleIndicator, CollapsiblePanel, CollapsibleTrigger, ColorField, type ColorFieldProps, Combobox, ComboboxChips, ComboboxClear, ComboboxContent, ComboboxEmpty, ComboboxGroup, ComboboxGroupLabel, ComboboxInput, ComboboxItem, type ComboboxItemGroup, ComboboxItemIndicator, ComboboxList, ComboboxPortal, type ComboboxProps, ComboboxValue, ComboboxVirtualList, type ComboboxVirtualListProps, type CommandFilter, type CommandItem, CommandMenu, CommandMenuGroup, type CommandMenuGroupProps, CommandMenuItem, type CommandMenuItemProps, CommandMenuPanel, type CommandMenuPanelProps, type CommandMenuProps, CommandMenuTrigger, type CommandMenuTriggerProps, type ComponentGroup, type ComponentGuidance, ComponentMeta, type ComponentRegister, ConfirmButton, type ConfirmButtonProps, type ConstraintFlag, ContextCard, ContextCardArrow, ContextCardContent, ContextCardPortal, ContextCardTrigger, ContextMenu, ContextMenuContent, ContextMenuGroup, ContextMenuGroupLabel, ContextMenuItem, ContextMenuPortal, ContextMenuSeparator, ContextMenuTrigger, type CopySource, DEFAULT_REACTIONS, DataTable, type DataTableColumn, type DataTableProps, type DataTableRowKey, DatePicker, type DatePickerProps, DateTile, type DateTileProps, Density, DensityProvider, Density as DensityValue, DestructiveActionModal, type DestructiveActionModalProps, Dialog, DialogClose, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogOverlay, DialogPortal, type DialogSize, DialogTitle, DialogTrigger, DisclosurePicker, DisclosurePickerEmpty, DisclosurePickerList, type DisclosurePickerListProps, DisclosurePickerOption, type DisclosurePickerOptionProps, DisclosurePickerPanel, type DisclosurePickerPanelProps, type DisclosurePickerProps, type DisclosurePickerSearch, DisclosurePickerTrigger, type DisclosurePickerTriggerProps, EmptyState, type EmptyStateProps, Entity, type EntityProps, Feedback, type FeedbackData, type FeedbackProps, type FeedbackRating, Field, type FieldProps, Fieldset, FieldsetContent, FieldsetDescription, FieldsetFooter, FieldsetLegend, type FieldsetVariant, FileDropzone, type FileDropzoneProps, type FileRejection, type FileRejectionCode, FontPicker, type FontPickerFont, type FontPickerOption, type FontPickerProps, Form, type FormProps, GlidingHighlight, type GlidingHighlightProps, GradientArt, type GradientArtProps, type Hsv, InlineStatus, type InlineStatusProps, type StatusTone as InlineTone, Input, InputGroup, type InputGroupProps, type InputProps$1 as InputProps, Kbd, KbdGroup, type KbdGroupProps, type KbdProps, Label, type LabelProps$2 as LabelProps, LikeButton, type LikeButtonProps, LineChart, type LineChartProps, Marker, type MarkerProps, Marquee, type MarqueeProps, MediaImage, type MediaImageProps, MediaTile, type MediaTileProps, Menu, MenuCheckboxItem, MenuContent, MenuGroup, MenuGroupLabel, MenuItem, MenuLinkItem, MenuPortal, MenuRadioGroup, MenuRadioItem, MenuReactions, type MenuReactionsProps, MenuSeparator, MenuSubmenu, MenuSubmenuTrigger, MenuTrigger, Menubar, type MenubarProps, MenubarTrigger, type MenubarTriggerProps, Message, type MessageProps, MessageScroller, type MessageScrollerHandle, type MessageScrollerProps, Meter, MeterIndicator, MeterLabel, type MeterSize, type MeterTone, MeterTrack, MeterValue, MiddleTruncate, type MiddleTruncateProps, type MotionLevel, type MotionPolicy, MotionProvider, type MotionProviderProps, MotionScope, type MotionScopeProps, NavigationMenu, NavigationMenuContent, NavigationMenuItem, NavigationMenuLink, NavigationMenuList, NavigationMenuTrigger, Note, type NoteAction, type NoteProps, NotificationBadge, type NotificationBadgeProps, NumberField, type NumberFieldProps, NumberTicker, type NumberTickerProps, type OrbMode, type OrbSize, OtpField, type OtpFieldProps, OverflowMenu, type OverflowMenuProps, PALETTE_COLORS, PALETTE_FAMILIES, PALETTE_SCALES, PALETTE_STEPS, PALETTE_TONES, PageHeader, type PageHeaderProps, PageLoader, type PageLoaderProps, Pagination, type PaginationProps, type PaletteColor, type PaletteFamily, type PaletteStep, Panel, PanelGroup, PanelResizer, type PanelResizerProps, PanelSection, type PanelWidthBounds, Phone, type PhoneProps, PieChart, type PieChartProps, Pill, type PillProps, Popover, PopoverArrow, PopoverClose, PopoverContent, PopoverDescription, PopoverPortal, PopoverTitle, PopoverTrigger, Presence, type PresenceProps, type Presentation, PresentationProvider, Progress, ProgressIndicator, ProgressLabel, type ProgressSize, ProgressTrack, ProgressValue, PropertyGroup, PropertyPair, PropertyRow, RadarChart, type RadarChartProps, RadialChart, type RadialChartProps, Radio, RadioCard, type RadioCardProps, type RadioCardTone, RadioGroup, type Reaction, ReactionPicker, type ReactionPickerProps, RelativeTime, type RelativeTimeProps, Reveal, type RevealProps, type Rgb, SABLE_UI_VERSION, SEGMENTED_BAR_TONES, STATUS_TONES, STATUS_TONE_ICON, type ScrollCommandOptions, Scroller, type ScrollerProps, ScrubField, type ScrubFieldProps, SearchInput, type SearchInputProps, SectionHeader, type SectionHeaderProps, SectionRail, type SectionRailProps, type SectionRailSection, SegmentedBar, type SegmentedBarProps, type SegmentedBarSegment, type SegmentedBarTone, Select, SelectContent, SelectGroup, SelectGroupLabel, SelectItem, SelectPortal, SelectSeparator, SelectTrigger, SelectValue, Separator, type SeparatorProps$2 as SeparatorProps, SettingsMenu, type SettingsMenuProps, SettingsRow, type SettingsRowProps, Sheet, SheetClose, SheetContent, SheetDescription, SheetFooter, SheetHeader, SheetList, SheetPortal, type SheetProps, type SheetSnapPoint, SheetTitle, SheetTrigger, ShowMore, type ShowMoreProps, SideNav, type SideNavActiveVariant, SideNavGroup, type SideNavGroupProps, SideNavItem, type SideNavItemProps, type SideNavProps, type SideNavSize, Sidebar, SidebarBrand, type SidebarBrandProps, SidebarFooter, SidebarHeader, SidebarItem, type SidebarItemProps, SidebarNav, type SidebarProps, SimpleTooltip, Skeleton, SkipLink, Slider, SliderControl, SliderIndicator, SliderRoot, SliderThumb, SliderTrack, SliderValue, type SmoothWheelOptions, Sparkline, type SparklineProps, Spinner, type SpinnerProps, StatusBar, StatusBarGroup, StatusBarSeparator, StatusDot, type StatusDotProps, type StatusTone, type StepStatus, Stepper, StepperItem, type StepperItemProps, type StepperOrientation, type StepperProps, StreamingText, type StreamingTextProps, Switch, TOOL_CALL_STATUS_LABELS, TRANSPARENT, Table, TableBody, TableCaption, TableCell, TableFooter, TableHead, TableHeader, TableRow, Tabs, TabsPanel as TabsContent, TabsList, TabsPanel, TabsTrigger, TextReveal, type TextRevealProps, Textarea, type TextareaProps, ThemeId, ThemeManifest, ThemeMode$1 as ThemeManifestMode, type ThemeMode, ThemePreview, type ThemePreviewProps, ThemeSelector, type ThemeSelectorProps, ThemeSwitcher, type ThemeSwitcherProps, ThinkingOrb, type ThinkingOrbProps, ToastAction, type ToastApi, ToastClose, ToastContent, ToastDescription, type ToastManagerApi, type ToastOptions, type ToastPosition, ToastProvider, type ToastProviderProps, ToastRoot, ToastTitle, type ToastType, ToastViewport, Toggle, ToggleGroup, type ToggleGroupAppearance, Toggle as ToggleGroupItem, ToolCall, type ToolCallProps, type ToolCallStatus, Toolbar, ToolbarButton, type ToolbarButtonProps, ToolbarGroup, type ToolbarGroupProps, ToolbarInput, type ToolbarInputProps, ToolbarLink, type ToolbarLinkProps, type ToolbarProps, ToolbarSeparator, type ToolbarSeparatorProps, Tooltip, TooltipArrow, TooltipContent, TooltipGroup, type TooltipGroupProps, TooltipPortal, TooltipProvider, TooltipTrigger, Tree, TreeAddRow, TreeEmpty, TreeRow, TreeSection, type UseActiveSectionOptions, type UseCaretTriggerOptions, type UseCaretTriggerResult, type UseCopyOptions, type UseCopyResult, type UseInViewOptions, type UseMatchHighlightOptions, type UsePanelWidthOptions, Video, type VideoProps, ViewTransitionName, type ViewTransitionNameProps, Workspace, WorkspaceBar, WorkspaceCanvas, accordionMeta, appHeaderMeta, appShellMeta, areaChartMeta, attachmentMeta, avatarGroupVariants, avatarMeta, avatarVariants, badgeMeta, badgeVariants, bannerMeta, bannerVariants, barChartMeta, bottomNavMeta, breadcrumbsMeta, browserMeta, bubbleMeta, buttonGroupMeta, buttonMeta, buttonVariants, calendarMeta, cardMeta, caretMenuMeta, carouselMeta, chartColor, toneColor as chartToneColor, chatComposerMeta, checkboxCardMeta, checkboxMeta, cn, codeBlockMeta, codeMeta, collapsibleMeta, colorFieldMeta, comboboxMeta, commandMenuMeta, componentGuidance, componentLabel, componentSlug, componentsInGroup, confirmButtonMeta, contextCardMeta, contextMenuMeta, dataTableMeta, datePickerMeta, dateTileMeta, destructiveActionModalMeta, dialogMeta, disclosurePickerMeta, emptyStateMeta, entityMeta, feedbackMeta, fieldsetMeta, fileDropzoneMeta, fileDropzoneVariants, fontPickerMeta, formMeta, formatFileSize, formatHex, glidingHighlightMeta, gradientArtMeta, hsvToRgb, hueColor, inlineStatusMeta, inputGroupMeta, inputMeta, isPaletteColor, isTransparent, kbdMeta, labelMeta, likeButtonMeta, lineChartMeta, markerMeta, marqueeMeta, mediaImageMeta, mediaTileMeta, menuMeta, menubarMeta, messageMeta, messageScrollerMeta, meterIndicatorVariants, meterMeta, meterTrackVariants, middleTruncateMeta, motionAttribute, navigationMenuMeta, noteMeta, noteVariants, notificationBadgeMeta, notificationCountVariants, notificationDotVariants, numberFieldMeta, numberTickerMeta, otpFieldMeta, overflowMenuMeta, pageHeaderMeta, pageLoaderMeta, paginationMeta, panelGroupMeta, panelSectionMeta, parseHex, phoneMeta, pieChartMeta, pillMeta, pillVariants, popoverMeta, progressMeta, progressTrackVariants, radarChartMeta, radialChartMeta, radioCardMeta, radioMeta, reactionPickerMeta, relativeTimeMeta, rgbToHsv, scrollerMeta, scrubFieldMeta, searchInputMeta, sectionHeaderMeta, sectionRailMeta, segmentedBarMeta, segmentedBarSegmentVariants, segmentedBarVariants, selectMeta, separatorMeta, settingsMenuMeta, sheetMeta, sheetVariants, showMoreMeta, sideNavMeta, sidebarMeta, skeletonMeta, sliderMeta, sparklineMeta, spinnerMeta, startViewTransition, statusBarMeta, statusDotMeta, statusDotVariants, stepperConnectorVariants, stepperIndicatorVariants, stepperMeta, streamingTextMeta, supportsViewTransitions, switchMeta, tableMeta, tabsMeta, textareaMeta, themeSelectorMeta, themeSwitcherMeta, thinkingOrbMeta, toast, toastMeta, toggleMeta, toolCallMeta, toolbarGroupVariants, toolbarMeta, toolbarSeparatorVariants, toolbarVariants, tooltipMeta, treeIndent, treeMeta, useActiveSection, useAnchoredDensity, useAutoSize, useCaretTrigger, useComboboxFilteredItems, useCommandMenuShortcut, useCopy, useDensity, useDisclosurePicker, useInView, useMatchHighlight, useMotion, useMotionLevel, usePanelWidth, usePresentation, useReducedMotion, useScrollActivity, useShake, useSidebar, useSmoothWheel, useToast, useToastManager, useTypeTier, videoMeta, workspaceMeta };

package/dist/index.js

@@ -130,6 +130,7 @@ export * from "./components/color-field/index.js";
 export * from "./components/app-shell/index.js";
 export * from "./components/sidebar/index.js";
 export * from "./components/side-nav/index.js";
+export * from "./components/section-rail/index.js";
 export * from "./components/bottom-nav/index.js";
 export * from "./components/app-header/index.js";
 export * from "./components/page-header/index.js";
@@ -176,12 +177,13 @@ import { useScrollActivity } from "./lib/use-scroll-activity.js";
 import { useMatchHighlight } from "./lib/use-match-highlight.js";
 import { useCopy } from "./lib/use-copy.js";
 import { useSmoothWheel } from "./lib/use-smooth-wheel.js";
+import { useActiveSection } from "./lib/use-active-section.js";
 import {
   useCaretTrigger
 } from "./lib/use-caret-trigger.js";
 import { STATUS_TONES, STATUS_TONE_ICON } from "./lib/status-tone.js";
 import { PALETTE_COLORS, PALETTE_FAMILIES, PALETTE_SCALES, PALETTE_STEPS, PALETTE_TONES, isPaletteColor } from "./lib/palette.js";
-var SABLE_UI_VERSION = "0.16.0";
+var SABLE_UI_VERSION = "0.17.0";
 export {
   APP_SHELL_TOKENS,
   ART_TOKENS,
@@ -234,6 +236,7 @@ export {
   themeIds,
   themeManifestById,
   themeManifests,
+  useActiveSection,
   useAnchoredDensity,
   useCaretTrigger,
   useCopy,

package/dist/lib/taxonomy.js

@@ -90,6 +90,7 @@ var COMPONENT_TAXONOMY = {
   BottomNav: ["Navigation", "page"],
   NavigationMenu: ["Navigation", "page"],
   Pagination: ["Navigation", "either"],
+  SectionRail: ["Navigation", "page"],
   ShowMore: ["Navigation", "page"],
   SideNav: ["Navigation", "page"],
   Sidebar: ["Navigation", "page"],

package/dist/lib/use-active-section.js

@@ -0,0 +1,59 @@
+"use client";
+
+// src/lib/use-active-section.ts
+import { useEffect, useState } from "react";
+var END_SLACK = 2;
+function useActiveSection(ids, { offset = 0.35, root } = {}) {
+  const [active, setActive] = useState(ids[0] ?? null);
+  const key = ids.join("\n");
+  useEffect(() => {
+    const list = key ? key.split("\n") : [];
+    if (list.length === 0) {
+      setActive(null);
+      return;
+    }
+    const scroller = root?.current ?? null;
+    let frame = 0;
+    const measure = () => {
+      frame = 0;
+      const top = scroller ? scroller.getBoundingClientRect().top : 0;
+      const height = scroller ? scroller.clientHeight : window.innerHeight;
+      const line = top + height * offset;
+      const bottom = top + height;
+      const scrolled = scroller ? scroller.scrollTop : window.scrollY;
+      const range = scroller ? scroller.scrollHeight - scroller.clientHeight : document.documentElement.scrollHeight - window.innerHeight;
+      const atEnd = range > END_SLACK && scrolled >= range - END_SLACK;
+      let current = list[0];
+      for (const id of list) {
+        const section = document.getElementById(id);
+        if (!section) continue;
+        const sectionTop = section.getBoundingClientRect().top;
+        if (sectionTop <= line || atEnd && sectionTop < bottom) current = id;
+      }
+      setActive(current);
+    };
+    const schedule = () => {
+      if (!frame) frame = requestAnimationFrame(measure);
+    };
+    measure();
+    const target = scroller ?? window;
+    target.addEventListener("scroll", schedule, { passive: true });
+    window.addEventListener("resize", schedule);
+    const resize = new ResizeObserver(schedule);
+    resize.observe(scroller ?? document.documentElement);
+    for (const id of list) {
+      const section = document.getElementById(id);
+      if (section) resize.observe(section);
+    }
+    return () => {
+      cancelAnimationFrame(frame);
+      target.removeEventListener("scroll", schedule);
+      window.removeEventListener("resize", schedule);
+      resize.disconnect();
+    };
+  }, [key, offset, root]);
+  return active;
+}
+export {
+  useActiveSection
+};

package/llms/blocks/approval-block.md

@@ -1,48 +1,45 @@
 # ApprovalBlock
 
-An agent asking permission for one tool call: the question, what will happen and what can't be undone, the call's details, an "allow for the rest of this chat" Checkbox, and Deny / Allow.
+An agent asking permission for one tool call: the question, what is at stake, the call itself as a ToolCall with its exact input, and Deny / Always allow / Allow once.
 
-**Intent:** Reach for this in a chat or agent run when a tool call waits on the person — sending, paying, deleting, publishing. The call itself, before and after the decision, is a ToolCall with status="awaiting", then "complete" or "denied". A destructive action outside an agent is DestructiveActionModal.
+**Intent:** Reach for this in a chat or agent run when a tool call waits on the person — running a command, sending, paying, deleting, publishing. It wraps the call's own ToolCall, which shows status="awaiting" until the person answers and then "complete" or "denied". A destructive action outside an agent is DestructiveActionModal.
 
 **Block:** AI & agents · card · designed for 18rem–28rem wide (fills its container up to the max)
 
 ## Notes
 
-- The title is the question in plain words ("Send the invoice to Ada?"), not the tool's name; the tool's name is one row of the details, for the person who wants to know exactly what runs.
-- The description says what can't be undone. That sentence is what the person is deciding on.
-- Deny comes first and Allow is the primary on the end, the same order as every Sable confirmation. Neither is focused on arrival: an approval that a stray Enter can grant is not an approval.
-- After a decision the buttons give way to one InlineStatus line saying what happened, so the thread keeps a record of the answer.
+- The title is the question in plain words ("Run this command?"); the description says what is at stake. That sentence is what the person is deciding on.
+- The call is shown as the agent made it — tool name and raw input, open on arrival — because the exact arguments are what a careful person checks. Do not paraphrase them into a form.
+- Three answers, as agent products settle on: Deny on the start edge, then Always allow and Allow once, the primary on the end. Neither is focused on arrival: an approval that a stray Enter can grant is not an approval.
+- After a decision the buttons give way to one InlineStatus line saying what happened, and the ToolCall shows the outcome, so the thread keeps a record of the answer.
 
 ## Accessibility
 
 - Focus moves to the outcome line when the buttons leave, instead of dropping to the page; the line is a role=status region, so the decision is announced.
-- The details are a dl, so each value is read with its label.
-- The remember Checkbox has its own Label, so the tool name inside it is part of its accessible name.
+- The ToolCall announces its own status change, and its input is a labelled code view.
 
 ## Source
 
 ```tsx
-import { useState, useEffect, useRef, useId } from "react"
-import { Button, Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, Checkbox, cn, Code, InlineStatus, Label } from "@sableui/react"
+import { useState, useEffect, useRef } from "react"
+import { Button, Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, cn, InlineStatus, ToolCall } from "@sableui/react"
 
 const request = {
-	tool: "send_email",
-	title: "Send the invoice to Ada?",
-	description: "The agent wants to email invoice INV-1042. An email can't be unsent.",
-	details: [
-		{ label: "To", value: "ada@example.com" },
-		{ label: "Subject", value: "INV-1042 for October" },
-		{ label: "Attached", value: "INV-1042.pdf" },
-	],
-	allowed: "Allowed. Sending the email.",
-	denied: "Denied. The agent won't send it.",
+	title: "Run this command?",
+	description: "The agent wants to migrate the production database in acme/api. It changes live data.",
+	tool: "run_command",
+	action: "Run a command",
+	// A command reads as the command; a structured call would pass its arguments object.
+	input: "pnpm db:migrate --env production",
+	allowed: "Allowed. Running the migration.",
+	denied: "Denied. The agent won't run it.",
 }
 
 export interface ApprovalBlockProps {
 	className?: string
 	/** false drops the card's surface and border — for a chat column that already frames it. */
 	framed?: boolean
-	/** The person allowed the call. `remember` is the "for the rest of this chat" choice. */
+	/** The person allowed the call. `remember` is true for "Always allow". */
 	onApprove?: (options: { remember: boolean }) => void
 	/** The person declined the call. */
 	onDeny?: () => void
@@ -50,8 +47,6 @@ export interface ApprovalBlockProps {
 
 export function ApprovalBlock({ className, framed = true, onApprove, onDeny }: ApprovalBlockProps) {
 	const [decision, setDecision] = useState<"allowed" | "denied" | null>(null)
-	const [remember, setRemember] = useState(false)
-	const id = useId()
 	const outcome = useRef<HTMLDivElement>(null)
 	// The buttons leave with the decision, so focus moves to the line that
 	// replaces them instead of falling back to the top of the page.
@@ -59,37 +54,30 @@ export function ApprovalBlock({ className, framed = true, onApprove, onDeny }: A
 		if (decision) outcome.current?.focus()
 	}, [decision])
 
+	const approve = (remember: boolean) => {
+		setDecision("allowed")
+		onApprove?.({ remember })
+	}
+
 	return (
 		<Card variant={framed ? "default" : "flat"} className={cn("w-full max-w-md", className)}>
 			<CardHeader>
 				<CardTitle>{request.title}</CardTitle>
 				<CardDescription>{request.description}</CardDescription>
 			</CardHeader>
-			<CardContent className="flex flex-col gap-4">
-				<dl className="grid grid-cols-[auto_minmax(0,1fr)] gap-x-4 gap-y-1.5 text-body-sm">
-					{request.details.map((d) => (
-						<div key={d.label} className="contents">
-							<dt className="text-muted-foreground">{d.label}</dt>
-							<dd className="truncate text-foreground">{d.value}</dd>
-						</div>
-					))}
-					<div className="contents">
-						<dt className="text-muted-foreground">Tool</dt>
-						<dd className="min-w-0">
-							<Code>{request.tool}</Code>
-						</dd>
-					</div>
-				</dl>
-				{decision ? null : (
-					<div className="flex items-center gap-2">
-						<Checkbox id={`${id}-remember`} checked={remember} onCheckedChange={(v: boolean) => setRemember(v)} />
-						<Label htmlFor={`${id}-remember`} className="text-body-sm">
-							Allow <Code>{request.tool}</Code> for the rest of this chat
-						</Label>
-					</div>
-				)}
+			<CardContent>
+				{/* The call itself, exactly as the agent made it. It answers with the
+				    person: held, then done or denied. */}
+				<ToolCall
+					name={request.tool}
+					title={request.action}
+					status={decision === "allowed" ? "complete" : decision === "denied" ? "denied" : "awaiting"}
+					statusLabel={decision === "allowed" ? "Allowed" : undefined}
+					input={request.input}
+					defaultOpen
+				/>
 			</CardContent>
-			<CardFooter actions className="justify-end">
+			<CardFooter actions>
 				{decision ? (
 					<InlineStatus
 						ref={outcome}
@@ -103,7 +91,8 @@ export function ApprovalBlock({ className, framed = true, onApprove, onDeny }: A
 				) : (
 					<>
 						<Button
-							variant="outline"
+							variant="ghost"
+							className="me-auto"
 							onClick={() => {
 								setDecision("denied")
 								onDeny?.()
@@ -111,14 +100,10 @@ export function ApprovalBlock({ className, framed = true, onApprove, onDeny }: A
 						>
 							Deny
 						</Button>
-						<Button
-							onClick={() => {
-								setDecision("allowed")
-								onApprove?.({ remember })
-							}}
-						>
-							Allow
+						<Button variant="outline" onClick={() => approve(true)}>
+							Always allow
 						</Button>
+						<Button onClick={() => approve(false)}>Allow once</Button>
 					</>
 				)}
 			</CardFooter>

package/llms/components/section-rail.md

@@ -0,0 +1,101 @@
+# SectionRail
+
+**Status:** stable
+
+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
+
+Use SectionRail beside a long, single-column read — a case study, an essay, a long landing page — 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.
+
+### Best practices
+
+- Do: Give every section an id that matches its entry, and keep the list to the page's top-level sections — about ten at most, so the rail stays shorter than the viewport.
+- Do: Place it with layout classes — usually `fixed top-1/2 left-6 z-(--z-nav) -translate-y-1/2` — 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.
+- Do: 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.
+- Do: Set `side="right"` when the rail sits on the right edge, so labels open toward the content.
+- Don't: Use it for app navigation between pages; that is SideNav or Sidebar. A SectionRail only moves within one page. → use **SideNav**, **Sidebar**
+- Don't: 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. → use **Stepper**
+- Don't: Use it for a handful of switchable views in one place; that is Tabs. → use **Tabs**
+
+### Anatomy
+
+| Part | Required | Description |
+| --- | --- | --- |
+| Rail | yes | The `<nav>` landmark: a rounded muted track holding one link per section. |
+| Dot | yes | A link to `#id`, drawn as a small dot that grows under the pointer or focus. |
+| Marker | yes | One primary bar that sits on the current section's dot and glides to the next. |
+| Label | yes | A shared tooltip that names the hovered or focused dot and travels between dots. |
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| sections | readonly { id: string; label: string }[] | — | 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. |
+| value | string | — | The current section's id, when the parent decides it. Leave it unset and the rail follows the scroll itself. |
+| onValueChange | (id: string) => void | — | Called with the new id when the reader scrolls into a section or picks one. |
+| offset | number | 0.35 | Where the reading line sits, as a fraction of the viewport from its top. A section becomes current once its top crosses it. |
+| root | RefObject<HTMLElement \| null> | — | The element that scrolls, when it is not the window. |
+| side | "left" \| "right" | "left" | Which edge of the page the rail sits on. The labels open on the other side, toward the content. |
+| motion | "full" \| "subtle" \| "off" | "full" | 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 — it never overrides a reader's reduce-motion setting. |
+| aria-label | string | "Sections" | The nav landmark's name. Name it for the page ("Case study sections") when it has other navs. |
+
+## Tokens used
+
+`muted`, `muted-foreground`, `foreground`, `primary`, `ring`, `popover`, `popover-foreground`, `border-floating`
+
+## Motion
+
+- **arrival** · Root · _no motion_ — 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.
+- **response** · Dot · `motion-interactive` — 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.
+- **transition** · Marker · `motion-glide` — 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.
+- **activity** · Root · _no motion_ — Navigation chrome has no working state.
+
+## Accessibility
+
+- 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×32 targets.
+- Under reduced motion the jump is instant and the marker moves without travel.
+
+## Related
+
+- Components: SideNav, Tooltip, Stepper, Tabs, GlidingHighlight
+
+## Examples
+
+### Fixed beside a long read
+
+```tsx
+import { SectionRail } from "@sableui/react"
+
+<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"
+/>
+```
+
+### On the right edge
+
+```tsx
+import { SectionRail } from "@sableui/react"
+
+<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"
+/>
+```