@sableui/react 0.1.1 → 0.3.0

package/llms/components/settings-menu.md

@@ -17,7 +17,7 @@ For a cluster of related settings that a reader checks often and changes occasio
 - Do: Use `MenuRadioGroup` + `MenuRadioItem` inside a row for single-choice settings, so the current option is checked rather than merely remembered.
 - Do: Reach for `variant="subtle"` when the trigger sits on a surface where a ghost control would float unanchored — inside a ChatComposer, for instance.
 - Don't: Do not use it for a single setting. One choice is a `Select`; the nesting only earns its cost when there are several related settings to summarise.
-- Don't: Do not put actions in it. Rows change state; a menu that mixes "Effort ›" with "Delete conversation" makes destructive commands look like preferences. That is `Menu` or `DotsMenu`.
+- Don't: Do not put actions in it. Rows change state; a menu that mixes "Effort ›" with "Delete conversation" makes destructive commands look like preferences. That is `Menu` or `OverflowMenu`.
 - Don't: Do not nest more than one level deep. Past that the reader loses the path back, and the thing you have is a settings dialog wearing a menu.
 - Don't: Do not override the upward, end-aligned default without reason. Its home is the bottom of a composer or toolbar, where a downward menu opens off-screen.
 
@@ -69,7 +69,7 @@ For a cluster of related settings that a reader checks often and changes occasio
 
 ## Related
 
-- Components: Menu, DotsMenu, Select, ChatComposer, Popover
+- Components: Menu, OverflowMenu, Select, ChatComposer, Popover
 - Patterns: ChatPanel
 
 ## Examples

package/llms/components/side-nav.md

@@ -15,7 +15,7 @@ Use SideNav for vertical navigation inside a settings page, documentation area,
 - Do: Use aria-label on SideNav when a page contains more than one nav landmark.
 - 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: Inside a rounded, padded frame, give each item rounded-concentric-<outer>/<inset> (e.g. rounded-concentric-lg/2 in a rounded-lg p-2 box). The rows' own radius is fixed per size, and a same-radius row inset into a frame reads as a second system.
+- 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: Mix content and sidebar active variants in the same rail unless individual items intentionally override the group.
 

package/llms/components/skeleton.md

@@ -32,7 +32,7 @@ Use Skeleton to reserve space and hint at the shape of content while data is loa
 - **arrival** · Root · _no motion_ — A skeleton stands in for content that has not arrived; fading the placeholder in adds a wait before the wait.
 - **response** · Root · _no motion_ — Nothing here is interactive. A skeleton that reacted to the pointer would invite a click on a thing that cannot be clicked.
 - **transition** · Root · _no motion_ — The skeleton has one state. Swapping it for real content is the parent's job, and the parent decides whether that swap is animated.
-- **activity** · Root · `motion-shimmer` — The sweep is the entire point of the component: it is what separates 'still loading' from 'loaded, and empty'. A static grey block is indistinguishable from a broken layout, which is why users reload the page.
+- **activity** · Root · `motion-shimmer` — The sweep is the entire point of the component: it is what separates 'still loading' from 'loaded, and empty'. A static grey block is indistinguishable from a broken layout, which is why users reload the page. It is one band of light against the viewport, so every skeleton in a loading layout lights in sequence as a single wave rather than each block flashing at its own speed; each pass eases in, glides and settles, then rests off-screen before the next.
 
 ## Accessibility
 

package/llms/components/sparkline.md

@@ -0,0 +1,80 @@
+# Sparkline
+
+**Status:** beta
+
+A word-sized trend with no axes — a line, a line over a soft fill, or columns — sized by its container, for stat cards, table cells and sentences. Draws on as it scrolls into view.
+
+**Keywords:** sparkline, trend, mini chart, inline chart, micro chart, kpi, stat
+
+## Usage
+
+Use Sparkline next to a number to show where it has been — a KPI's last 30 days in a stat card, a row's trend in a table. It has no axes, tooltip or values to read off; when the reader needs those, use AreaChart or LineChart.
+
+### Best practices
+
+- Do: Pair it with the current value and its change in text; the sparkline shows only the shape.
+- Do: Give it a label that names the measure and the period — the spoken summary adds the range and latest value.
+- Don't: Put two sparklines on one shared axis to compare them — each scales to its own data; use LineChart.
+- Don't: Use it as the only place a number appears; a shape without a value cannot be read off.
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| data | number[] | — | The values, oldest first. |
+| label | string | — | What the line tracks ("Revenue, last 30 days"). The spoken summary adds the first and last values, low and high. |
+| variant | "line" \| "area" \| "bar" | "line" | A line, a line over a soft fill, or columns. |
+| tone | "edition" \| "collectible" \| "standard" \| "info" \| "warning" \| "primary" \| "neutral" \| "success" \| "destructive" | "primary" | Colour by role. |
+| className | string | "h-8 w-24" | Sizes it; the drawing stretches to fit. |
+| animate | boolean | true | Draw on (or rise) when it scrolls into view. |
+| locale | string | runtime locale | BCP 47 locale for default number and date formatting. |
+
+## Variants
+
+- **variant**: line, area, bar
+
+## Tokens used
+
+`primary`, `tone-edition`, `tone-collectible`, `tone-standard`, `tone-info`, `tone-warning`, `muted-foreground`, `success`, `destructive`
+
+## Motion
+
+- **arrival** · Line / bars · _custom (outside the recipe layer)_ — Once on screen the line draws on (or the bars rise, in sequence). On the motion tokens; reduced motion shows the finished drawing.
+- **response** · Sparkline · _no motion_ — Not interactive: it has no tooltip or focus.
+- **transition** · Sparkline · _no motion_ — New data redraws in place; a word-sized chart animating on every update would distract from the number beside it.
+- **activity** · Sparkline · _no motion_ — No indeterminate state.
+
+## Accessibility
+
+- Rendered role=img with an aria-label built from `label` and the data: "Revenue, last 30 days: from 120 to 184, low 96, high 190".
+- It is not focusable and has no tooltip, so the number it accompanies must be in text beside it.
+
+## Related
+
+- Components: AreaChart, LineChart, Card, Table
+
+## Examples
+
+### In a stat card
+
+```tsx
+import { Card, CardAction, CardDescription, CardHeader, CardTitle, Sparkline } from "@sableui/react"
+
+<Card>
+	<CardHeader>
+		<CardDescription>Revenue</CardDescription>
+		<CardTitle className="text-mono-xl">$18,240</CardTitle>
+		<CardAction>
+			<Sparkline label="Revenue, last 12 weeks" data={[12, 14, 13, 17, 16, 19, 18, 21, 20, 24, 23, 26]} variant="area" tone="success" />
+		</CardAction>
+	</CardHeader>
+</Card>
+```
+
+### Columns in a table cell
+
+```tsx
+import { Sparkline } from "@sableui/react"
+
+<Sparkline label="Daily signups, last 14 days" data={[4, 6, 3, 8, 7, 9, 5, 6, 10, 8, 7, 11, 9, 12]} variant="bar" className="h-6 w-20" />
+```

package/llms/components/table.md

@@ -17,7 +17,7 @@ Use Table for structured data with consistent columns and rows. Use DataTable wh
 - 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: Put every possible action in every row. Use one primary row action, a DotsMenu, or row detail navigation.
+- Don't: Put every possible action in every row. Use one primary row action, an OverflowMenu, or row detail navigation.
 
 ### Anatomy
 

package/llms/components/theme-selector.md

@@ -12,7 +12,7 @@ Use ThemeSelector wherever a person picks a theme. The default `cards` layout is
 
 ### Best practices
 
-- Do: Use layout="list" in a popover, a menu, or a docked panel. Rows sit on the --control-sm ladder and still show each theme's swatch strip, so the choice stays visible rather than described. Rows take `sable-frame-inner`, so host the list in a sable-frame (a Popover, or `sable-frame sable-surface sable-surface-popover sable-frame-popover`) and their corners nest concentrically.
+- Do: Use layout="list" in a popover, a menu, or a docked panel. Rows sit on the --control-sm ladder and still show each theme's swatch strip, so the choice stays visible rather than described. Rows take `sable-frame-inner`, so host the list in a sable-frame (`sable-frame sable-surface sable-surface-popover sable-frame-popover` — PopoverContent is not one; give it that class list, or its p-4 leaves the rows unnested) and their corners nest concentrically.
 - Do: Pass mode={useSableTheme().mode} so every preview renders in the colour mode actually in use, rather than in each theme's manifest default.
 - Do: Load each theme's fonts in the host app. Every card carries a type specimen in that theme's own face so people can compare typography as well as color. A theme whose fonts are not loaded falls back to system-ui, and its specimen stops telling the truth.
 - Don't: Add a viewport breakpoint to force a column count — `className="sm:grid-cols-1"` or similar. `sm:` keys off the VIEWPORT, not this component's container, so on a wide screen it does nothing for a narrow parent. The cards grid already reflows on its own width via auto-fit.

package/llms/foundations/shape.md

@@ -30,7 +30,7 @@ Each step is 4px apart, so common insets land on a real step. Themes and the cus
 ## Rules
 
 1. **Nested corners are concentric: inner radius = outer radius − inset. Write it as rounded-concentric-<outer>/<inset>, not a hardcoded step.** A 12px popover with 4px padding takes 8px items. The utility computes the subtraction from the live tokens, so the pair stays concentric when a theme or the customizer rescales the radius ladder; a hardcoded rounded-sm drifts.
-2. **A list of rows inside a rounded popup uses popup-inset on the popup, rounded-popup-item on the rows and popup-bleed on a separator.** All three derive from the popup's radius: the inset grows to a third of it (never below --spacing(1), so density moves it too), the rows take what is left, and a separator bleeds by exactly the inset. A rounder look gets more room instead of rows that round into pills, and the default ladder still lands on the familiar 4px inset and 8px rows. *Enforced by sable-lint: popup-separator-bleed.*
+2. **A list of rows inside a rounded popup uses popup-inset on the popup, rounded-popup-item on the rows and popup-bleed on a separator.** All three derive from the popup's radius: the inset grows to a third of it (never below --spacing(1), so density moves it too), the rows take what is left after the inset and the 1px border, and a separator bleeds by exactly the inset. A rounder look gets more room instead of rows that round into pills; the default ladder lands on a 4px inset and 7px rows. *Enforced by sable-lint: popup-separator-bleed.*
 3. **A Button, Pill or Badge gets its look from a variant, never from override classes.** border, bg, rounded, ring and shadow classes on a component fight the variant's own hover, selected and focus states, and give one call site a look no other site can ask for. Use the variant that exists (Button variant="floating" over content, "on-color" on a fill; Pill appearance="outline"; Badge appearance and tone) or add one to the component. *Enforced by sable-lint: component-restyle.*
 4. **The outer radius is always at least the inner radius.** If the inset is larger than the outer radius, square the inner element or step the container up.
 5. **Never mix radii within one component.** A component reads as one object when its corners agree.

package/llms/patterns/auth-page.md

@@ -1,67 +1,157 @@
 # AuthPage
 
-Centered auth card: a form-width region vertically centered in the viewport, one Card holding the Form, an alternate-action divider, and a quiet switch-to-sign-up link beneath it.
+Split sign-in page: a form column (brand mark, heading, email + password, primary sign-in, passkey and wallet alternatives, sign-up switch, terms) beside a brand panel painted from the theme's tones with a featured release card. Below lg the panel drops away and the form is the whole screen.
 
 **Intent:** Reach for this for sign-in, sign-up, forgot-password, and any single-purpose one-column form route (invite accept, unsubscribe). Not for multi-section forms (use SettingsPage).
 
 ## Notes
 
-- Region cap is `form` (480px) — the narrowest named cap; auth never needs more.
-- The card is the only surface on the page: no app chrome, no sidebar — minimal exit paths.
-- min-h-dvh + grid place-items-center centers the card without magic offsets.
-- Field handles label/error wiring; the submit button is full-width — the primary (and only) action.
-- Secondary actions (here, switch to sign-up; add forgot password the same way) are quiet `link-underline` links, never competing buttons.
+- The form column is a `form`-capped Region (480px), so the controls keep the same measure whether the panel is present or not.
+- No card around the form: the page itself is the surface, and the brand panel carries the identity. A card on a blank page reads as a template.
+- The heading is `text-heading-1` in an h1 — it is the page outline, so it takes a heading tier, not a card title.
+- Brand mark, form and terms are a three-part column: mark pinned to the top, form vertically centred in the remaining space, terms pinned to the bottom.
+- Forgot password sits under the password field, right-aligned, before the submit button — so it comes right after the field in tab order. Field has no label-row action slot yet.
+- One primary action. Passkey and wallet are outline buttons under an `or` Separator; switching to sign-up is a quiet `link-underline` link.
+- Validation uses Field `validate` for product copy instead of the browser's generic required message. A rejected sign-in comes back through Form `errors` on the password field; the submit Button shows `loading` while the request is in flight.
+- The brand panel artwork is a mesh of the theme's decorative tones over `--primary`, so it re-paints for every theme and mode. The relative-colour `oklch(from var(--tone-*) …)` lift needs an `inline-color` disable with a reason.
+- The panel is `hidden lg:flex`: on a phone the form is the whole screen, with no decorative scroll above it.
 
 ## Accessibility
 
-- The route renders inside <main> with the page h1 in the card header (an h1 inside CardTitle, which carries the type).
-- Field auto-wires labels, describedby, and invalid state onto the inputs.
-- Autocomplete attributes (email, current-password) keep password managers working.
+- The route renders inside <main> with one h1; the brand panel is an <aside> labelled "Featured release".
+- Field auto-wires labels, describedby, and invalid state onto the inputs; on submit, the first invalid field is focused.
+- Autocomplete attributes (`email webauthn`, `current-password`) keep password managers and passkey autofill working.
+- The Forgot password and Create one links use `hit-target` to meet the 44px touch floor without changing layout.
+- The artwork swatches are aria-hidden decoration; the brand link's accessible name is the wordmark.
 
 ## Source
 
 ```tsx
-import { Button, Card, CardContent, CardDescription, CardHeader, CardTitle, Field, Form, Input, Region, Separator, Stack } from "@sableui/react"
+import { useState } from "react"
+import { Avatar, Badge, Button, Card, CardContent, Entity, Field, Form, Icon, Input, Region, Separator, Stack } from "@sableui/react"
+
+// A soft mesh of the theme's decorative tones over its brand colour, so the
+// artwork follows every theme and mode. Each tone is lifted from its text
+// strength (dark, restrained) to an art strength.
+const artwork = [
+	// design-lint-disable-next-line inline-color -- relative colour derived from the theme's own --tone token, so it follows every look
+	"radial-gradient(in oklab at 18% 22%, oklch(from var(--tone-info) clamp(0.5, calc(l + 0.16), 0.9) max(calc(c * 1.25), 0.1) h), transparent 58%)",
+	// design-lint-disable-next-line inline-color -- relative colour derived from the theme's own --tone token, so it follows every look
+	"radial-gradient(in oklab at 82% 18%, oklch(from var(--tone-collectible) clamp(0.5, calc(l + 0.16), 0.9) max(calc(c * 1.25), 0.1) h), transparent 55%)",
+	// design-lint-disable-next-line inline-color -- relative colour derived from the theme's own --tone token, so it follows every look
+	"radial-gradient(in oklab at 70% 88%, oklch(from var(--tone-edition) clamp(0.5, calc(l + 0.16), 0.9) max(calc(c * 1.25), 0.1) h), transparent 60%)",
+	// design-lint-disable-next-line inline-color -- relative colour derived from the theme's own --tone token, so it follows every look
+	"radial-gradient(in oklab at 12% 92%, oklch(from var(--tone-standard) clamp(0.5, calc(l + 0.16), 0.9) max(calc(c * 1.25), 0.1) h), transparent 55%)",
+	"var(--primary)",
+].join(", ")
 
 export function AuthPage() {
+	const [pending, setPending] = useState(false)
+	const [errors, setErrors] = useState<Record<string, string>>({})
+
 	return (
-		<main className="grid min-h-dvh place-items-center bg-background">
-			<Region max="form" safeArea={["top", "bottom"]}>
-				<Stack gap={3}>
-					<Card>
-						<CardHeader>
-							{/* CardTitle carries the type; the h1 inside it is the page heading. */}
-							<CardTitle>
-								<h1>Sign in</h1>
-							</CardTitle>
-							<CardDescription>Welcome back — pick up where you left off.</CardDescription>
-						</CardHeader>
-						<CardContent>
-							<Form onSubmit={(event) => event.preventDefault()}>
-								<Field label="Email" required>
-									<Input type="email" name="email" autoComplete="email" placeholder="you@example.com" />
-								</Field>
-								<Field label="Password" required>
-									<Input type="password" name="password" autoComplete="current-password" />
+		<main className="grid min-h-dvh bg-background lg:grid-cols-[minmax(0,1fr)_minmax(0,1.1fr)]">
+			<Region max="form" safeArea={["top", "bottom"]} className="flex flex-col">
+				{/* safeArea owns the region's own padding, so the breathing room sits one level in. */}
+				<Stack gap={0} className="flex-1 py-8 sm:py-10">
+					<a href="/" className="flex items-center gap-2.5 self-start rounded-sm motion-interactive motion-press">
+						{/* The same mark the app shell's sidebar and header carry. */}
+						<Icon name="gem" variant="solid" className="text-2xl" />
+						<span className="text-title-lg">Atelier</span>
+					</a>
+
+					<Stack gap={4} justify="center" className="flex-1 py-12">
+						<Stack gap={1.5}>
+							<h1 className="text-heading-1">Welcome back</h1>
+							<p className="text-body-lg text-muted-foreground">
+								Sign in to collect new releases and manage your editions.
+							</p>
+						</Stack>
+
+						<Form
+							className="gap-5"
+							errors={errors}
+							onFormSubmit={() => {
+								setPending(true)
+								// Replace with your auth call; a rejected sign-in comes back as a field error.
+								setTimeout(() => {
+									setPending(false)
+									setErrors({ password: "That email and password don’t match. Try again or reset your password." })
+								}, 900)
+							}}
+						>
+							<Field label="Email" name="email" validate={(value) => (value ? null : "Enter your email address.")}>
+								<Input type="email" autoComplete="email webauthn" placeholder="you@example.com" />
+							</Field>
+							<Stack gap={1.5}>
+								<Field label="Password" name="password" validate={(value) => (value ? null : "Enter your password.")}>
+									<Input type="password" autoComplete="current-password" />
 								</Field>
-								<Button type="submit" className="w-full">
-									Sign in
-								</Button>
-								<Separator label="or" />
-								<Button variant="outline" className="w-full">
-									Continue with wallet
-								</Button>
-							</Form>
-						</CardContent>
-					</Card>
-					<p className="text-center text-body-sm text-muted-foreground">
-						No account?{" "}
-						<a href="/signup" className="link-underline motion-interactive text-foreground">
-							Create one
+								<a href="/forgot-password" className="hit-target self-end text-body-sm text-muted-foreground link-underline motion-interactive">
+									Forgot password?
+								</a>
+							</Stack>
+							<Button type="submit" size="cta" loading={pending} loadingLabel="Signing in" className="w-full">
+								Sign in
+							</Button>
+						</Form>
+
+						<Separator label="or" />
+
+						<Stack gap={1.5}>
+							<Button variant="outline" size="cta" className="w-full" iconStart={<Icon name="key" />}>
+								Sign in with a passkey
+							</Button>
+							<Button variant="outline" size="cta" className="w-full" iconStart={<Icon name="wallet" />}>
+								Connect a wallet
+							</Button>
+						</Stack>
+
+						<p className="text-body-md text-muted-foreground">
+							No account?{" "}
+							<a href="/signup" className="hit-target link-underline motion-interactive text-foreground">
+								Create one
+							</a>
+						</p>
+					</Stack>
+
+					<p className="text-body-xs text-muted-foreground">
+						By signing in you agree to the{" "}
+						<a href="/terms" className="link-underline motion-interactive">
+							Terms
+						</a>{" "}
+						and{" "}
+						<a href="/privacy" className="link-underline motion-interactive">
+							Privacy Policy
 						</a>
+						.
 					</p>
 				</Stack>
 			</Region>
+
+			{/* The brand panel is decoration: on a phone the form is the whole screen. */}
+			<aside aria-label="Featured release" className="hidden p-3 lg:flex">
+				<div className="flex flex-1 flex-col justify-end rounded-xl p-8" style={{ background: artwork }}>
+					<Card className="max-w-md">
+						<CardContent>
+							<Stack gap={3}>
+								<Badge tone="edition" className="self-start">
+									Edition of 50
+								</Badge>
+								<p className="text-title-lg">
+									“Every edition is a conversation with whoever holds it next.”
+								</p>
+								<Entity
+									className="p-0"
+									leading={<Avatar fallback="MO" />}
+									title="Mara Okafor"
+									subtitle="Untitled (gold rush), 2026"
+								/>
+							</Stack>
+						</CardContent>
+					</Card>
+				</div>
+			</aside>
 		</main>
 	)
 }