@sableui/react 0.17.0 → 0.19.0

package/llms/components/workspace.md

@@ -4,7 +4,7 @@
 
 The shell for a tool: a fixed viewport partitioned into independently scrolling regions, with a compact density scope, a skip link, and a canvas landmark.
 
-**Keywords:** workspace, tool, editor, shell, frame, canvas, chrome, panels, density, viewport
+**Keywords:** workspace, tool, editor, shell, frame, canvas, chrome, panels, density, viewport, issue tracker, tracker, inspector, reading view, mobile, responsive, bottom nav, media query, breakpoint, top bar, topbar
 
 ## Usage
 
@@ -15,6 +15,9 @@ Use Workspace as the outer frame for a tool — an editor, a console, a canvas a
 - Do: Put a PanelGroup in the body and a WorkspaceCanvas inside it, so panels are aside chrome and the work surface is the main landmark.
 - Do: Let each panel own its scrolling. The shell never scrolls, and the canvas clips rather than scrolls — panning is the viewport's job.
 - Do: Keep the density scope at compact unless you have a specific reason; the workspace register's measured control ladder is what makes tool chrome read as tool chrome.
+- Do: Put a WorkspaceBar inside a column when the bar belongs to that column only. An issue tracker's bar (breadcrumb, view tabs, filters) sits above the list, while the sidebar and the inspector beside it run the full height: put the WorkspaceBar first inside the WorkspaceCanvas, not in the `toolbar` slot, which spans every panel. Don't hand-build a fixed-height header for it.
+- Do: Wrap a reading view inside the workspace (a project overview, an update, a doc, release notes) in <Density value="comfortable">. The compact scope maps body text to the 11–12px UI tiers, which is right for chrome and too small for paragraphs; the comfortable scope gives prose its page size again while the chrome around it stays compact.
+- Do: Plan the phone layout with the shell rather than around it: pass a BottomNav to `bottomNav`, and give docked Panels `narrow="sheet"` (an inspector, a navigation rail) or `narrow="hidden"`. Don't measure the viewport with a resize listener, render the inspector twice, or subtract the nav's height from 100dvh.
 - Don't: Nest a Region or Page inside it to set a width. Region caps are a page-register idea; a workspace is edge-to-edge and its panels are fixed-width chrome outside the content grid.
 - Don't: Hardcode a control height (h-[32px]). CI rejects it (raw-control-height); read the ladder instead, e.g. h-(--control-sm), so the density scope can size it.
 - Don't: Put a Card in the chrome. Use PanelSection — a card inside a narrow panel spends its border and inset on nothing.
@@ -28,6 +31,7 @@ Use Workspace as the outer frame for a tool — an editor, a console, a canvas a
 | Body | yes | The flexible middle row, normally a PanelGroup. Constrained so its children can shrink and scroll. |
 | WorkspaceCanvas | no | The work surface and the main#main-content landmark the skip link targets. Clips rather than scrolls. |
 | StatusBar | no | Bottom chrome for ambient document facts. |
+| BottomNav | no | Phone navigation in the `bottomNav` slot. Its row is reserved below lg and gone above it, so the body ends where the nav begins. |
 
 ## Subcomponents
 
@@ -35,6 +39,8 @@ Use Workspace as the outer frame for a tool — an editor, a console, a canvas a
 | --- | --- | --- |
 | WorkspaceBar | ComponentProps<'header'> | The top chrome strip, sized to --chrome-bar-height with a hairline beneath. |
 | WorkspaceCanvas | ComponentProps<'main'> | The work surface: renders main#main-content, fills the body, clips its overflow. |
+| useMediaQuery | (query: string, options?: { serverValue?: boolean }) => boolean | True while a media query matches, read through useSyncExternalStore: no resize listener, no setState in an effect, no hydration mismatch (the server reports serverValue, default false). Use it to branch structure a class cannot express; style-only changes stay as lg: classes. |
+| useBelowBreakpoint | (breakpoint?: "sm" \| "md" \| "lg" \| "xl" \| "2xl", options?: { serverValue?: boolean }) => boolean | True below a named breakpoint (default lg), flipping at the width where that breakpoint's classes start to apply (Tailwind's sm 40 / md 48 / lg 64 / xl 80 / 2xl 96rem). Panel's `narrow` uses it; reach for it instead of a hand-rolled window.innerWidth check. |
 
 ## Props
 
@@ -42,6 +48,7 @@ Use Workspace as the outer frame for a tool — an editor, a console, a canvas a
 | --- | --- | --- | --- |
 | toolbar | ReactNode | — | Top chrome, normally a WorkspaceBar. |
 | statusBar | ReactNode | — | Bottom chrome, normally a StatusBar. |
+| bottomNav | ReactNode | — | Phone navigation, normally a BottomNav. Below lg (BottomNav's own breakpoint) the shell reserves the nav's height as its last row, so the body and the status bar end above the nav instead of under it; above lg the row is gone. Every slot is optional: the body is the shell's one growing row whichever of toolbar, statusBar and bottomNav are present. |
 | density | "compact" \| "comfortable" | "compact" | Density scope for everything inside. Sets the --control-* ladder via data-density; compact is the workspace register. Nothing hardcodes a height, so the same size="md" Button is 40px on a page and 32px inside a compact Workspace. A Dialog opened from inside resets to comfortable, because a modal is a page-register surface even when a tool launched it. |
 | skipLinkLabel | string | "Skip to canvas" | Text for the skip link that targets the canvas landmark. |
 
@@ -123,6 +130,79 @@ import { Input, Panel, PanelGroup, PanelSection, PropertyRow, StatusBar, Workspa
 </Workspace>
 ```
 
+### Issue tracker: column bar, docked inspector, phone sheet
+
+```tsx
+import { BottomNav, BottomNavItem, BreadcrumbItem, BreadcrumbLink, BreadcrumbPage, Breadcrumbs, BreadcrumbSeparator, Button, Icon, Input, Panel, PanelGroup, PanelSection, PropertyRow, StatusBar, Workspace, WorkspaceBar, WorkspaceCanvas } from "@sableui/react"
+
+function Tracker() {
+  const [selected, setSelected] = useState<string | null>("AES-104")
+  return (
+    <Workspace
+      bottomNav={
+        <BottomNav>
+          <BottomNavItem showLabel label="Issues" icon={<Icon name="list" />} active />
+          <BottomNavItem showLabel label="Inbox" icon={<Icon name="inbox" />} />
+        </BottomNav>
+      }
+      statusBar={<StatusBar><span>12 issues</span></StatusBar>}
+    >
+      <PanelGroup>
+        <Panel label="Navigation" width={220} narrow="hidden">
+          <PanelSection title="Workspace">
+            <PropertyRow label="Team"><Input defaultValue="Studio" /></PropertyRow>
+          </PanelSection>
+        </Panel>
+        <WorkspaceCanvas className="flex flex-col">
+          <WorkspaceBar>
+            <Breadcrumbs>
+              <BreadcrumbItem><BreadcrumbLink href="#">Studio</BreadcrumbLink></BreadcrumbItem>
+              <BreadcrumbSeparator />
+              <BreadcrumbItem><BreadcrumbPage>Digital flagship</BreadcrumbPage></BreadcrumbItem>
+            </Breadcrumbs>
+          </WorkspaceBar>
+          <div className="min-h-0 flex-1 overflow-y-auto scrollbar-quiet">
+            <Button size="xs" variant="ghost" onClick={() => setSelected("AES-104")}>AES-104 Refine product page</Button>
+          </div>
+        </WorkspaceCanvas>
+        <Panel
+          label="Issue details"
+          width={320}
+          narrow="sheet"
+          open={selected !== null}
+          onOpenChange={(open) => !open && setSelected(null)}
+        >
+          <PanelSection title={selected ?? ""}>
+            <PropertyRow label="Status"><Input defaultValue="In progress" /></PropertyRow>
+          </PanelSection>
+        </Panel>
+      </PanelGroup>
+    </Workspace>
+  )
+}
+```
+
+### Reading view inside a workspace
+
+```tsx
+import { Density, PanelGroup, Workspace, WorkspaceCanvas } from "@sableui/react"
+
+<Workspace>
+  <PanelGroup>
+    <WorkspaceCanvas className="overflow-y-auto scrollbar-quiet">
+      <Density value="comfortable">
+        <article className="max-w-prose p-6">
+          <h2 className="text-heading-3">Project overview</h2>
+          <p className="mt-3 text-body-md text-muted-foreground">
+            Paragraphs keep their page size here, while the chrome around the canvas stays compact.
+          </p>
+        </article>
+      </Density>
+    </WorkspaceCanvas>
+  </PanelGroup>
+</Workspace>
+```
+
 ### Comfortable density
 
 ```tsx

package/llms/foundations/typography.md

@@ -49,7 +49,9 @@ Every tier belongs to one family, and the family is the decision. Size follows f
 6. **Cap reading text at --measure-prose (65ch).** Past roughly 75 characters the eye loses the line return. A wide region can still hold a 65ch column.
 7. **Numbers that must align use a mono tier (tabular figures).** Proportional digits change width as values update, so totals and columns shimmy.
 8. **text-wrap: balance on headings, pretty on ledes, neither on long prose.** balance evens short headlines; pretty only refuses a one-word last line. Both cost layout work that long prose does not repay.
-9. **A mark attached to a line of type (a dot, a bullet, a timeline marker, a leading icon) sits in a box one line tall (h-[1lh] items-center) and is sized in em.** 1lh is the line-height of the text beside it, so the mark centres on that line in every tier, density and theme. A px size with a mt-[3px] nudge is right for one font at one size and wrong everywhere else.
+9. **To make all the type smaller or larger, set the base: --type-base: 14 (a unitless px number; 16 is the default). Never retune tiers one by one for it.** Every tier is authored on a 16px base and keeps its ratio to it, so one number rebuilds the whole scale, headings to captions, and the baseline step and spacing follow the body. Shrinking tiers individually breaks the ratios between them. Set it on :root, a theme scope or a preset (tokens.shared["type-base"]) so the rhythm follows too.
+10. **Inside a Workspace, a panel's title is text-ui-title (14px · 600); compact text-title-lg resolves to it. A reading view inside the tool (an overview, a document, a long form) is wrapped in <Density value="comfortable"> and gets the page tiers back.** The compact register remaps page tiers onto the 10-12px chrome ramp, which is right for chrome and wrong for prose: an issue overview set in a tool rendered its paragraphs at 11px. The remap stops at a comfortable boundary, so the wrapper is the whole fix.
+11. **A mark attached to a line of type (a dot, a bullet, a timeline marker, a leading icon) sits in a box one line tall (h-[1lh] items-center) and is sized in em.** 1lh is the line-height of the text beside it, so the mark centres on that line in every tier, density and theme. A px size with a mt-[3px] nudge is right for one font at one size and wrong everywhere else.
 
 ## Never
 
@@ -58,6 +60,7 @@ Every tier belongs to one family, and the family is the decision. Size follows f
 - **Never:** Uppercase in product chrome: nav and menu group labels, page eyebrows, table headers, section titles. **Instead:** Sentence-case text-caption or text-label-md in muted-foreground; hierarchy from size, weight and space. Tracked capitals spread across a UI read as shouting and slow word recognition. The eyebrow tier (label-xs / overline) is an editorial accent: at most one per marketing view.
 - **Never:** Display tiers inside product UI, or two display sizes in one view. **Instead:** heading-1 for a page title; mono-xl for a metric. Display is type as image. In chrome it competes with the content it is supposed to frame.
 - **Never:** Justified text, or reading copy below body-sm. **Instead:** Ragged-right at body-md; body-xs only for dense data. Justification opens rivers on the web, which has no hyphenation control; 12px prose fails people with low vision.
+- **Never:** Changing the root font-size (html { font-size: 14px }) to make a product denser. **Instead:** --type-base: 14, with Workspace or <Density value="compact"> for denser controls. The root also sizes every rem the app wrote: widths, insets, media queries. --type-base moves only the type and the rhythm built on it, and density moves the controls, so each can be chosen on its own.
 - **Never:** A new font family, or raw font-feature-settings / font-variation-settings. **Instead:** The theme's sans, mono and optional display; font-variant-numeric and font-weight. Raw axis tags silently do nothing on a fallback font, and every theme declares a fallback stack.
 
 ## Details

package/llms/layout/aspect-box.md

@@ -2,7 +2,7 @@
 
 **Status:** stable
 
-Reserves space via aspect-ratio so async media loads with zero layout shift. Wrap images, video, embeds.
+Reserves space via aspect-ratio so async media loads with zero layout shift. Wrap images, video, embeds. The ratio is a class reading a CSS variable, so className reshapes it at a breakpoint (md:aspect-video).
 
 **Keywords:** aspect box, aspect ratio, media, layout shift
 

package/llms/layout/bleed.md

@@ -2,7 +2,7 @@
 
 **Status:** stable
 
-Escape a width-capped or inset ancestor to span the full CONTENT area (container-query units, so it stops at a fixed Sidebar instead of bleeding under it). Hero bands, profile covers, full-bleed media inside a capped Page.
+Escape a width-capped or inset ancestor to span the full CONTENT area (container-query units, so it stops at a fixed Sidebar instead of bleeding under it). Hero bands, profile covers, full-bleed media inside a capped Page. Width and margins are classes, so a breakpoint can turn the bleed off (lg:mx-0 lg:w-auto).
 
 **Keywords:** bleed, full bleed, media band, layout
 

package/llms/layout/center.md

@@ -2,7 +2,7 @@
 
 **Status:** stable
 
-Horizontally center a block, optionally capping its width (commonly "prose" for a reading column inside a wider layout).
+Horizontally center a block, optionally capping its width (commonly "prose" for a reading column inside a wider layout). Centering and cap are classes, so className overrides them at a breakpoint.
 
 **Keywords:** center, measure, reading width, layout
 

package/llms/layout/columns.md

@@ -2,7 +2,7 @@
 
 **Status:** stable
 
-An explicit N-column track (default 12) for proportioned layouts — pair with Col spans (list-detail, asymmetric editorial layouts). For uniform card grids prefer Grid minItemWidth.
+An explicit N-column track (default 12) for proportioned layouts — pair with Col spans (list-detail, asymmetric editorial layouts). For uniform card grids prefer Grid minItemWidth. display is the grid class, so hidden md:grid works; a gap-* utility replaces both gaps and the column-gap cap.
 
 **Keywords:** columns, 12 column, span, layout
 

package/llms/layout/grid.md

@@ -2,7 +2,7 @@
 
 **Status:** stable
 
-CSS Grid within a region. Two modes: fixed/responsive cols count, or minItemWidth so cells breathe with NO breakpoints (the default choice for card grids). A minItemWidth grid keeps its empty columns (track="fill"), so one result stays one cell wide; track="fit" stretches a fixed set across the row.
+CSS Grid within a region. Two modes: fixed/responsive cols count, or minItemWidth so cells breathe with NO breakpoints (the default choice for card grids). A minItemWidth grid keeps its empty columns (track="fill"), so one result stays one cell wide; track="fit" stretches a fixed set across the row. display is the grid class and the gap a CSS variable, so className utilities win at any breakpoint (hidden md:grid, md:gap-6, lg:grid-cols-3).
 
 **Keywords:** grid, card grid, auto fit, layout
 

package/llms/layout/region.md

@@ -2,7 +2,7 @@
 
 **Status:** stable
 
-The page region: fluid, edge-to-edge with the fluid page inset (--page-inset). Opt-in centered max cap picked by ROLE (prose/form/feed/content/wide/full), never a global page max-width. The root of nearly every route.
+The page region: fluid, edge-to-edge with the fluid page inset (--page-inset). Opt-in centered max cap picked by ROLE (prose/form/feed/content/wide/full), never a global page max-width. The root of nearly every route. The inset and cap are classes (px-(--page-inset), max-w-…), so className overrides them at a breakpoint (max-sm:px-0); only safeArea padding is inline.
 
 **Keywords:** region, page width, container, layout
 

package/llms/layout/row.md

@@ -2,7 +2,7 @@
 
 **Status:** stable
 
-Horizontal flex flow — inline rows of controls, toolbars, action clusters. Defaults to center-aligned, no wrap.
+Horizontal flex flow — inline rows of controls, toolbars, action clusters. Defaults to center-aligned, no wrap. Layout lives in classes (flex flex-row items-* justify-*) and the gap in a CSS variable, never inline style, so className utilities override any prop at a breakpoint (hidden md:flex, max-md:flex-col, md:gap-6).
 
 **Keywords:** row, toolbar, horizontal, layout
 
@@ -38,3 +38,11 @@ import { Button, Row } from "@sableui/react"
 
 <Row gap={2} justify="end"><Button variant="ghost">Cancel</Button><Button>Save changes</Button></Row>
 ```
+
+### Responsive through className
+
+```tsx
+import { Button, Row } from "@sableui/react"
+
+<Row justify="between"><span className="text-title-sm">Acme</span><Row gap={1} className="max-md:hidden"><Button variant="ghost" size="sm">Docs</Button><Button variant="ghost" size="sm">Pricing</Button></Row></Row>
+```

package/llms/layout/spacer.md

@@ -2,7 +2,7 @@
 
 **Status:** stable
 
-Explicit space on the rhythm, or a flexible grow pusher between siblings (e.g. pushing a footer item to the end of a Row).
+Explicit space on the rhythm, or a flexible grow pusher between siblings (e.g. pushing a footer item to the end of a Row). The size is a class reading a CSS variable, so className resizes or hides it at a breakpoint.
 
 **Keywords:** spacer, spacing, grow, layout
 

package/llms/layout/split-pane.md

@@ -2,7 +2,7 @@
 
 **Status:** stable
 
-Responsive two-pane layout: side-by-side at/above a breakpoint, stacked (primary first) below. List-detail, media + metadata.
+Responsive two-pane layout: side-by-side at/above a breakpoint, stacked (primary first) below. List-detail, media + metadata. display is the grid class and the breakpoint rules are layered, so className utilities (hidden lg:grid, gap-8) win.
 
 **Keywords:** split pane, two pane, list detail, responsive
 

package/llms/layout/stack.md

@@ -2,7 +2,7 @@
 
 **Status:** stable
 
-Vertical flow on the 8px rhythm — the default container for stacked content. Gap by role: tight within a group (1.5–2), looser between groups (3–4), generous between sections (6+).
+Vertical flow on the 8px rhythm — the default container for stacked content. Gap by role: tight within a group (1.5–2), looser between groups (3–4), generous between sections (6+). Layout lives in classes (flex flex-col items-* justify-*) and the gap in a CSS variable, never inline style, so className utilities override any prop at a breakpoint (max-lg:hidden, md:flex-row, md:gap-8).
 
 **Keywords:** stack, vertical rhythm, layout, spacing
 

package/llms/patterns/dashboard-page.md

@@ -29,7 +29,7 @@ App-shell admin dashboard: a branded Sidebar with an account footer (AppHeader +
 ## Source
 
 ```tsx
-import { AppHeader, AppShell, Avatar, Badge, BottomNav, BottomNavItem, Button, Card, CardAction, CardContent, CardDescription, CardFooter, CardHeader, CardList, CardTitle, DataTable, Entity, Grid, Icon, MenuItem, MenuSeparator, Meter, NotificationBadge, OverflowMenu, Page, PageHeader, RelativeTime, Row, Sidebar, SidebarBrand, SidebarFooter, SidebarHeader, SidebarItem, SidebarNav, Stack } from "@sableui/react"
+import { AppHeader, AppShell, Avatar, Badge, BottomNav, BottomNavItem, Button, Card, CardAction, CardContent, CardDescription, CardFooter, CardHeader, CardList, CardTitle, DataTable, Entity, Grid, Icon, Menu, MenuContent, MenuItem, MenuSeparator, MenuTrigger, Meter, NotificationBadge, Page, PageHeader, RelativeTime, Row, Sidebar, SidebarAccount, SidebarBrand, SidebarFooter, SidebarHeader, SidebarItem, SidebarNav, Stack } from "@sableui/react"
 
 // Account status → Badge tone. Sable has no status vocabulary of its own;
 // an app maps ITS states onto tones once, here, and every badge follows.
@@ -141,20 +141,23 @@ export function DashboardPage() {
 						<SidebarItem icon={<Icon name="gear" />} label="Settings" render={<a href="/settings" />} />
 					</SidebarNav>
 					<SidebarFooter>
-						<Entity
-							className="[--entity-py:0]"
-							leading={<Avatar variant="art" size="sm" fallback="AL" alt="" />}
-							title="Ada Lovelace"
-							subtitle="@ada"
-							action={
-								<OverflowMenu label="Account" size="icon-sm">
-									<MenuItem render={<a href="/@ada" />}>View profile</MenuItem>
-									<MenuItem render={<a href="/settings" />}>Settings</MenuItem>
-									<MenuSeparator />
-									<MenuItem>Sign out</MenuItem>
-								</OverflowMenu>
-							}
-						/>
+						<Menu>
+							<MenuTrigger
+								render={
+									<SidebarAccount
+										avatar={<Avatar variant="art" size="xs" fallback="AL" alt="" />}
+										label="Ada Lovelace"
+										detail="@ada"
+									/>
+								}
+							/>
+							<MenuContent side="top" align="start">
+								<MenuItem render={<a href="/@ada" />}>View profile</MenuItem>
+								<MenuItem render={<a href="/settings" />}>Settings</MenuItem>
+								<MenuSeparator />
+								<MenuItem>Sign out</MenuItem>
+							</MenuContent>
+						</Menu>
 					</SidebarFooter>
 				</Sidebar>
 			}