@sableui/react 0.13.0 → 0.13.2

package/llms/components/popover.md

@@ -14,8 +14,8 @@ Use Popover for anchored secondary content that needs more room than a tooltip b
 
 - Do: Use it for small pickers, summaries, or contextual controls tied to a trigger.
 - Do: Keep focus behavior and dismissal predictable.
-- Don't: Do not use Popover for blocking confirmations, long forms, or critical information.
-- Don't: Do not put a form that can fail validation inside one. A popover dismisses on outside click, which discards what the user typed with no warning — that is a Dialog.
+- Don't: Do not use Popover for blocking confirmations, long forms, or critical information. → use **Dialog**
+- Don't: Do not put a form that can fail validation inside one. A popover dismisses on outside click, which discards what the user typed with no warning — that is a Dialog. → use **Dialog**
 
 ### Anatomy
 

package/llms/components/progress.md

@@ -15,7 +15,7 @@ Use Progress to communicate determinate or indeterminate completion for a task o
 - Do: Use determinate values when progress can be measured.
 - Do: Pair the visual indicator with text when users need context or exact values.
 - Don't: Do not use Progress as a decorative divider or status color bar.
-- Don't: Do not use a determinate Progress for an unknown duration. A bar that sits at 90% is worse than a Spinner, because it makes a promise about time that you cannot keep.
+- Don't: Do not use a determinate Progress for an unknown duration. A bar that sits at 90% is worse than a Spinner, because it makes a promise about time that you cannot keep. → use **Spinner**
 
 ### Anatomy
 

package/llms/components/radio.md

@@ -14,7 +14,7 @@ Use Radio when a user must choose exactly one option from a visible set.
 
 - Do: Use it when all options should be visible for comparison.
 - Do: Keep option labels mutually exclusive and easy to understand.
-- Don't: Do not use Radio for independent toggles or multiple selection; use Checkbox or Switch.
+- Don't: Do not use Radio for independent toggles or multiple selection; use Checkbox or Switch. → use **Checkbox**, **Switch**
 - Don't: Do not use a radio group with only one option, and do not omit the Fieldset. Without the fieldset the options share no accessible name, so a screen reader reads the choices with no question attached.
 
 ### Anatomy

package/llms/components/segmented-bar.md

@@ -14,7 +14,7 @@ Use SegmentedBar when a stat card or row needs to show how a total divides into
 
 - Do: Keep it to two to six segments and give the same category the same tone everywhere it appears.
 - Do: Show the legend's shares in text ("42%") — colour identifies a segment, but the number is what a reader compares.
-- Don't: Use it for a single value against a limit; that is Meter, which carries the meter role and its value.
+- Don't: Use it for a single value against a limit; that is Meter, which carries the meter role and its value. → use **Meter**
 - Don't: Rely on tone order alone to tell segments apart; a legend row per segment, with its label, is required.
 
 ### Anatomy

package/llms/components/select.md

@@ -17,8 +17,8 @@ Use Select when users choose one value from a known, finite set. Use Combobox fo
 - Do: Wrap in Field when the select belongs to a form so label, helper text, and errors are wired automatically.
 - Do: Leave the trigger's type alone on mobile. Below the sm breakpoint the md trigger renders text-body-lg (17px) so it matches the Input and Textarea beside it, which carry that tier because iOS Safari zooms the page when a focused field computes under 16px. A custom field in the same row should follow: a second paired tier under a max-sm: variant, never a hand-set font-size.
 - Do: Inside a <Workspace> a Select adapts automatically — trigger and popup both pick up the compact density, including across the portal. Do NOT hand-size it per call site; that was necessary before v0.41 and is now drift.
-- Don't: Use Select for very large or fuzzy lists. Use Combobox when typing is the primary way to find an option.
-- Don't: Use Select for binary on/off settings. Use Switch or Checkbox instead.
+- Don't: Use Select for very large or fuzzy lists. Use Combobox when typing is the primary way to find an option. → use **Combobox**
+- Don't: Use Select for binary on/off settings. Use Switch or Checkbox instead. → use **Switch**, **Checkbox**
 
 ### Anatomy
 

package/llms/components/sheet.md

@@ -15,8 +15,8 @@ Use Sheet for secondary workflows that slide in while preserving context from th
 - Do: Use it for inspect, edit, filter, or create flows that relate to the current page.
 - Do: Include clear title, close path, and footer actions for task-oriented sheets.
 - Do: Give a bottom sheet snap points when it shows a summary first and detail on demand (a map result, a now-playing panel): `snapPoints={[0.4, 1]}`. The first stop is where it opens; put what matters at that height, because the rest is a drag away.
-- Don't: Do not use Sheet for simple confirmations or deeply nested workflows.
-- Don't: Do not use it on desktop where a Dialog fits. A sheet's affordance is edge-anchored travel for thumb reach; on a wide viewport it becomes a dialog that arrives from the wrong place.
+- Don't: Do not use Sheet for simple confirmations or deeply nested workflows. → use **Dialog**
+- Don't: Do not use it on desktop where a Dialog fits. A sheet's affordance is edge-anchored travel for thumb reach; on a wide viewport it becomes a dialog that arrives from the wrong place. → use **Dialog**
 
 ### Anatomy
 

package/llms/components/side-nav.md

@@ -16,7 +16,7 @@ Use SideNav for vertical navigation inside a settings page, documentation area,
 - Do: Group related items with SideNavGroup when the rail has more than one conceptual area.
 - Do: Use size='lg' and activeVariant='sidebar' when the nav is part of persistent app chrome.
 - Do: Rows are rounded-sm, which nests in the usual rounded-lg p-2 frame. In any other rounded, padded frame give each item rounded-concentric-<outer>/<inset> — a same-radius row inset into a frame reads as a second system.
-- Don't: Use SideNav for bottom mobile navigation; use BottomNav in AppShell's bottomNav slot.
+- Don't: Use SideNav for bottom mobile navigation; use BottomNav in AppShell's bottomNav slot. → use **BottomNav**
 - Don't: Mix content and sidebar active variants in the same rail unless individual items intentionally override the group.
 
 ### Anatomy

package/llms/components/skeleton.md

@@ -14,7 +14,7 @@ Use Skeleton to reserve space and hint at the shape of content while data is loa
 
 - Do: Match the approximate size and rhythm of the eventual content.
 - Do: Use it for content regions where layout stability matters during loading.
-- Don't: Do not leave Skeleton visible after an error or empty state; switch to EmptyState (tone='destructive' for an error).
+- Don't: Do not leave Skeleton visible after an error or empty state; switch to EmptyState (tone='destructive' for an error). → use **EmptyState**
 - Don't: Do not use a skeleton whose shape differs from the content that replaces it. A mismatched placeholder causes a visible jump, which is worse than a brief spinner.
 
 ## Props

package/llms/components/spinner.md

@@ -14,7 +14,7 @@ Use Spinner for short indeterminate waits where the user cannot know exact progr
 
 - Do: Use it in compact panels or places where layout is already stable. In a button, use Button's loading prop rather than placing a Spinner by hand — it disables the button, sets aria-busy and sizes the spinner to the button's icon.
 - Do: Pair it with accessible loading text when the surrounding label is not enough.
-- Don't: Do not use Spinner as the only content for long waits or full page loading.
+- Don't: Do not use Spinner as the only content for long waits or full page loading. → use **Skeleton**, **PageLoader**
 - Don't: Do not use it without an accessible name or a nearby status message. A spinning icon is invisible to a screen reader, so the wait is announced as nothing at all.
 
 ## Props

package/llms/components/stepper.md

@@ -15,8 +15,8 @@ Use Stepper above or beside a flow that is split into a known, small number of n
 - Do: Drive it from one number (`current`) and override a single step's `status` only for what a number cannot say — a completed step that now needs attention is `status="error"`.
 - Do: Name steps with a word or two ("Shipping", "Payment"). Go vertical when steps need a description or there are more than five; horizontal titles truncate first.
 - Do: Give completed steps `onSelect` only when going back to edit them actually works, and keep the user's later answers when they do.
-- Don't: Do not use Stepper for a task with unknown length or for a percentage. That is Progress; a stepper promises a fixed set of named stops.
-- Don't: Do not use it as navigation between independent sections. Sections the user can visit in any order are Tabs; a stepper implies each step depends on the one before.
+- Don't: Do not use Stepper for a task with unknown length or for a percentage. That is Progress; a stepper promises a fixed set of named stops. → use **Progress**
+- Don't: Do not use it as navigation between independent sections. Sections the user can visit in any order are Tabs; a stepper implies each step depends on the one before. → use **Tabs**
 - Don't: Do not make upcoming steps pressable to skip ahead. A step that looks reachable but is not is worse than one that is plainly locked.
 
 ### Anatomy

package/llms/components/switch.md

@@ -15,7 +15,7 @@ Use Switch for immediate on/off settings that take effect as a persistent prefer
 - Do: Use it for binary settings where the label describes the enabled state.
 - Do: Make the current state obvious through both position and accessible text.
 - Don't: Do not phrase the label as a negative, such as "Don't send read receipts". Turning off a negative is a double negative, and the user has to solve it before they can act.
-- Don't: Do not use Switch for one-time agreement, multi-select choices, or submit-only booleans.
+- Don't: Do not use Switch for one-time agreement, multi-select choices, or submit-only booleans. → use **Checkbox**, **Radio**
 - Don't: Do not use a Switch whose effect is not immediately visible somewhere. A toggle flipped with no observable consequence gives no confirmation it worked, so the user flips it again to check.
 
 ## Props

package/llms/components/table.md

@@ -16,7 +16,7 @@ Use Table for structured data with consistent columns and rows. Use DataTable wh
 - Do: Keep cells concise and scannable; compose Badge, StatusDot, Avatar, or Button only when they clarify the row.
 - Do: Use the built-in horizontal frame for overflow instead of squeezing columns until content becomes unreadable.
 - Do: Put a table in a card with `<CardContent flush>`. The first and last columns then take the card's own padding (`--table-edge-px`), so they line up with the CardHeader at any density. Never hand-set `pl-6`/`pr-6` on edge cells.
-- Don't: Use Table for heterogeneous items with no stable columns. Use Card, Entity, or a list composition instead.
+- Don't: Use Table for heterogeneous items with no stable columns. Use Card, Entity, or a list composition instead. → use **Card**, **Entity**
 - Don't: Put every possible action in every row. Use one primary row action, an OverflowMenu, or row detail navigation.
 
 ### Anatomy

package/llms/components/tabs.md

@@ -15,8 +15,8 @@ Use Tabs to switch between related panels within the same page context.
 - Do: Use tabs when each panel is peer content and users may compare or switch often.
 - Do: Keep tab labels short and make the active tab unmistakable.
 - Do: Use variant="pill" for a short switcher inside a card or toolbar (Preview / Code, List / Grid); keep the default underline for sections of a page.
-- Don't: Do not use Tabs for unrelated pages or primary navigation that needs distinct URLs.
-- Don't: Do not use tabs for sequential steps. Tabs are peer views the user returns to in any order; a process with an order needs a stepper, or the user will skip ahead.
+- Don't: Do not use Tabs for unrelated pages or primary navigation that needs distinct URLs. → use **SideNav**, **NavigationMenu**
+- Don't: Do not use tabs for sequential steps. Tabs are peer views the user returns to in any order; a process with an order needs a stepper, or the user will skip ahead. → use **Stepper**
 
 ### Anatomy
 

package/llms/components/thinking-orb.md

@@ -15,8 +15,8 @@ Use ThinkingOrb while an AI agent is working and there is nothing specific to re
 - Do: Reserve it for the single active agent state — the composer, the streaming message header, a standalone thinking screen. One orb on screen reads as intent; several read as decoration.
 - Do: Switch mode to say what kind of work is happening: orbit for generic thinking, globe while searching or retrieving, mesh while relating sources or running tools. Pair it with a text status so the phase is legible without decoding the animation.
 - Do: Use size="sm" inline in a message row or composer and size="lg" only when the orb is the main thing on screen. The size steps are separately tuned, not scaled, so the small one stays legible.
-- Don't: Do not put one on every row of a list or in a repeated skeleton. Each orb runs its own animation frame loop painting hundreds of arcs; use Skeleton for content-shaped waits and Spinner inside buttons.
-- Don't: Do not use it for a determinate wait. It carries no sense of how far along anything is — reach for Progress when a percentage exists.
+- Don't: Do not put one on every row of a list or in a repeated skeleton. Each orb runs its own animation frame loop painting hundreds of arcs; use Skeleton for content-shaped waits and Spinner inside buttons. → use **Skeleton**, **Spinner**
+- Don't: Do not use it for a determinate wait. It carries no sense of how far along anything is — reach for Progress when a percentage exists. → use **Progress**
 - Don't: Do not rely on the animation alone to announce the wait. Give the label a short constant phrase (it is the role=status announcement) or place a status message next to it.
 - Don't: Do not pass a label that changes while the orb is up. It is the accessible name of a live region, so every change re-announces the whole thing — feed it a per-token phase and a screen reader interrupts on each delta: "Chromatic drift" → "Chromatic drift · rgb-shift" → "Chromatic drift · rgb-shift → grain", which is unusable. The label names the wait ("Thinking"); the phase belongs in adjacent text, as in the "Inline with a status line" example. If the phase must be announced, announce it once when the turn settles from a separate live region — not per update.
 

package/llms/components/toast.md

@@ -15,7 +15,7 @@ Use Toast for transient feedback caused by a user action: saved, failed, copied,
 - Do: Mount one ToastProvider near the app root before any code calls toast() or useToast().
 - Do: Use toast.promise for async actions so loading, success, and error states stay tied to one notification.
 - Do: Keep toast copy short and outcome-focused. Add an action only when it is immediately useful, such as Undo.
-- Don't: Use Toast for critical blockers or persistent outages. Use Banner or Dialog when the user must notice and act.
+- Don't: Use Toast for critical blockers or persistent outages. Use Banner or Dialog when the user must notice and act. → use **Banner**, **Dialog**
 - Don't: Fire multiple toasts for one operation. Update the same toast when a task progresses.
 - Don't: Put the only path to an action in a toast that auto-dismisses. An Undo that expires on a timer is data loss on a schedule, so error toasts and any toast carrying actionProps default to timeout 0 and wait to be read — pass an explicit timeout only when the action is also reachable somewhere else. When a timeout exists at all, 5s is the floor: anything shorter cannot be read and acted on.
 

package/llms/components/toggle.md

@@ -15,7 +15,7 @@ Use Toggle for button-like controls that can be pressed on or off within a toolb
 - Do: Use it for transient UI modes such as bold, preview, pin, or favorite.
 - Do: Make the pressed state visually and programmatically clear.
 - Do: Use ToggleGroup appearance="segmented" for a single-select view switch (List / Grid). It is the same capsule ThemeSwitcher wears — do not hand-build a track around a row of toggles.
-- Don't: Do not use Toggle for persistent application settings; use Switch.
+- Don't: Do not use Toggle for persistent application settings; use Switch. → use **Switch**
 - Don't: Do not leave an icon-only Toggle without an accessible name. It announces as "button, pressed", which tells a screen-reader user the state but never what the state applies to.
 
 ### Anatomy

package/llms/components/toolbar.md

@@ -18,7 +18,7 @@ Use Toolbar when three or more related controls sit together and act on the same
 - Do: Compose triggers and toggles through ToolbarButton's render prop — render={<MenuTrigger />}, render={<PopoverTrigger />}, or render={<Toggle value="bold" />} inside a ToggleGroup — so they join the toolbar's arrow-key order.
 - Don't: Put a bare Button, Toggle or Input inside a Toolbar. It renders, but it is not a toolbar item: the arrow keys skip it and it takes its own tab stop, which is the inconsistency Toolbar exists to remove. Use ToolbarButton, ToolbarInput, or render through ToolbarButton.
 - Don't: Wrap one or two buttons, or a dialog's Cancel/Confirm pair, in a Toolbar. Those are independent actions; arrow-key movement there is a surprise, not a shortcut. A plain row of Buttons is right.
-- Don't: Use Toolbar for navigation between pages or views. Links that go somewhere are Tabs, SideNav or Breadcrumbs; ToolbarLink is for the odd link that sits among actions, like Help.
+- Don't: Use Toolbar for navigation between pages or views. Links that go somewhere are Tabs, SideNav or Breadcrumbs; ToolbarLink is for the odd link that sits among actions, like Help. → use **Tabs**, **SideNav**, **Breadcrumbs**
 - Don't: Give toolbar buttons primary or destructive fills by default. A toolbar is a quiet strip of tools; the ghost default keeps it from competing with the page's one primary action.
 
 ### Anatomy

package/llms/components/tooltip.md

@@ -14,7 +14,7 @@ Use Tooltip for brief nonessential hints tied to a specific control or piece of
 
 - Do: Use it to name icon-only controls or clarify compact UI when the label cannot be visible.
 - Do: Keep tooltip content short and noninteractive.
-- Don't: Do not put critical instructions, errors, or interactive content inside Tooltip.
+- Don't: Do not put critical instructions, errors, or interactive content inside Tooltip. → use **Popover**, **InlineStatus**
 - Don't: Do not let a tooltip serve as an icon button's accessible name. A tooltip is not a name — without its own aria-label the button announces as "button", and the tooltip never opens for a screen reader at all.
 
 ### Anatomy