@sableui/react 0.0.0-stage → 0.1.1

package/llms/layout/region.md

@@ -0,0 +1,49 @@
+# Region
+
+**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.
+
+**Keywords:** region, page width, container, layout
+
+## Usage
+
+Use Region as the page-width primitive that applies fluid page inset and an optional purpose-named max width.
+
+### Best practices
+
+- Do: Choose the max value by content role, such as prose, form, feed, content, wide, or full.
+- Do: Use Region near the route or section boundary so inner layout stays intentional.
+- Don't: Do not use Region as a global wrapper that forces every page into the same max width.
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| as | ElementType | "div" | Semantic element to render (e.g. "main", "section", "nav"). |
+| inset | boolean | true | Apply the fluid horizontal page inset (--page-inset). |
+| max | "prose" \| "form" \| "feed" \| "content" \| "wide" \| "full" \| CSS length | — | Opt-in centered max-width cap, purpose-named: prose 65ch (long-form reading) · form 480px (auth, narrow single-column forms) · feed 640px (single-column timeline) · content 896px (settings/admin panes) · wide 1280px (dashboards, tables, card grids) · full 1536px (full-bleed ceiling). Omit for fully fluid. |
+| bleed | boolean | false | Full-bleed: edge to edge with no inset. Overrides inset. |
+| safeArea | boolean \| ("top"\|"bottom"\|"left"\|"right")[] | false | env(safe-area-inset-*) padding for fixed or native-shell surfaces. true pads top+bottom; pass an edge array to target edges. |
+
+## Related
+
+- Components: Page, Grid, Columns
+
+## Examples
+
+### Settings pane
+
+```tsx
+import { PageHeader, Region } from "@sableui/react"
+
+<Region as="main" max="content"><PageHeader title="Settings" /></Region>
+```
+
+### Fluid dashboard region
+
+```tsx
+import { Card, CardHeader, CardTitle, Grid, Region } from "@sableui/react"
+
+<Region max="wide"><Grid minItemWidth="16rem"><Card><CardHeader><CardTitle>Revenue</CardTitle></CardHeader></Card><Card><CardHeader><CardTitle>Collects</CardTitle></CardHeader></Card></Grid></Region>
+```

package/llms/layout/row.md

@@ -0,0 +1,40 @@
+# Row
+
+**Status:** stable
+
+Horizontal flex flow — inline rows of controls, toolbars, action clusters. Defaults to center-aligned, no wrap.
+
+**Keywords:** row, toolbar, horizontal, layout
+
+## Usage
+
+Use Row for horizontal clusters such as action groups, toolbars, metadata, and inline controls.
+
+### Best practices
+
+- Do: Use wrap when controls may not fit on smaller screens.
+- Do: Use justify and align intentionally so clusters scan as one unit.
+- Don't: Do not use Row for navigation menus or dense tabular structure.
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| gap | number \| string | 2 | Horizontal gap. Number = rhythm units (×8px); string = raw CSS. |
+| align | "start" \| "center" \| "end" \| "stretch" | "center" | Cross-axis alignment. |
+| justify | "start" \| "center" \| "end" \| "between" | "start" | Main-axis distribution. |
+| wrap | boolean | false | Allow items to wrap. |
+
+## Related
+
+- Components: Stack, Button, Spacer
+
+## Examples
+
+### Action cluster
+
+```tsx
+import { Button, Row } from "@sableui/react"
+
+<Row gap={2} justify="end"><Button variant="ghost">Cancel</Button><Button>Save changes</Button></Row>
+```

package/llms/layout/safe-area.md

@@ -0,0 +1,37 @@
+# SafeArea
+
+**Status:** stable
+
+Pads for device safe-areas (notch, home indicator) on fixed or native-shell surfaces. Wrap fixed bars; content in normal flow rarely needs it.
+
+**Keywords:** safe area, notch, home indicator, fixed chrome
+
+## Usage
+
+Use SafeArea to pad fixed or native-shell surfaces away from device notches and home indicators.
+
+### Best practices
+
+- Do: Use it around fixed headers, bottom bars, and native-shell surfaces.
+- Do: Target only the edges that need device inset padding when possible.
+- Don't: Do not wrap normal document-flow content in SafeArea unless it actually touches unsafe edges.
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| edges | ("top" \| "bottom" \| "left" \| "right")[] | all four | Which edges get env(safe-area-inset-*) padding. |
+
+## Related
+
+- Components: BottomNav, AppHeader, AppShell
+
+## Examples
+
+### Fixed bottom bar
+
+```tsx
+import { Button, Row, SafeArea } from "@sableui/react"
+
+<SafeArea edges={["bottom"]} className="fixed inset-x-0 bottom-0 bg-card border-t border-border"><Row gap={2} justify="between" className="p-3"><span className="text-label-md">1 item selected</span><Button size="sm">Continue</Button></Row></SafeArea>
+```

package/llms/layout/spacer.md

@@ -0,0 +1,39 @@
+# Spacer
+
+**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).
+
+**Keywords:** spacer, spacing, grow, layout
+
+## Usage
+
+Use Spacer for explicit rhythm space or a flex grow pusher between siblings.
+
+### Best practices
+
+- Do: Use grow inside Row when one side of a cluster should push to the far edge.
+- Do: Use fixed size only when the space has semantic rhythm value.
+- Don't: Do not use Spacer to patch broad layout problems that should be solved by Stack, Row, Grid, or Region.
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| size | number | 1 | Fixed size in rhythm units (×8px; fractions ok). Ignored when grow. |
+| axis | "vertical" \| "horizontal" | "vertical" | Axis the fixed size applies to. |
+| grow | boolean | — | Flex-grow to push siblings apart (fills available space). |
+
+## Related
+
+- Components: Row, Stack
+
+## Examples
+
+### Push actions to the end
+
+```tsx
+import { Button, Row, Spacer } from "@sableui/react"
+
+<Row><span className="text-title-sm">Members</span><Spacer grow /><Button size="sm">Invite</Button></Row>
+```

package/llms/layout/split-pane.md

@@ -0,0 +1,41 @@
+# SplitPane
+
+**Status:** stable
+
+Responsive two-pane layout: side-by-side at/above a breakpoint, stacked (primary first) below. List-detail, media + metadata.
+
+**Keywords:** split pane, two pane, list detail, responsive
+
+## Usage
+
+Use SplitPane for responsive two-pane layouts where a primary pane and supporting pane stay conceptually linked.
+
+### Best practices
+
+- Do: Use it for media-detail, list-detail, or editor-preview workflows.
+- Do: Pick a ratio that reflects the actual priority of the panes.
+- Don't: Do not use SplitPane for unrelated columns or uniform grids.
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| primary | ReactNode | — | The leading / larger pane (e.g. the media column). |
+| secondary | ReactNode | — | The trailing / supporting pane (e.g. the detail column). |
+| collapseBelow | "sm" \| "md" \| "lg" \| "xl" | "lg" | Breakpoint at/above which panes sit side by side. |
+| ratio | string | "1/1" | Primary:secondary width ratio as "a/b" fr units (e.g. "2/1"). |
+| gap | number \| string | var(--grid-gutter) | Gap between panes. |
+
+## Related
+
+- Components: Columns, Grid, Sheet
+
+## Examples
+
+### Media + detail
+
+```tsx
+import { AspectBox, Button, SplitPane, Stack } from "@sableui/react"
+
+<SplitPane ratio="2/1" primary={<AspectBox ratio={1}><img src={post.imageUrl} alt={post.title} className="size-full object-cover" /></AspectBox>} secondary={<Stack gap={2}><h1 className="text-heading-1">{post.title}</h1><p className="text-body-md text-muted-foreground">{post.description}</p><Button>Collect</Button></Stack>} />
+```

package/llms/layout/stack.md

@@ -0,0 +1,39 @@
+# Stack
+
+**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+).
+
+**Keywords:** stack, vertical rhythm, layout, spacing
+
+## Usage
+
+Use Stack for vertical flow where child spacing should follow the Sable rhythm scale.
+
+### Best practices
+
+- Do: Use smaller gaps within a group and larger gaps between sections.
+- Do: Use Stack instead of ad hoc margins when siblings form a vertical composition.
+- Don't: Do not use Stack to create page width or grid structure; pair it with Region, Grid, or Columns.
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| gap | number \| string | 2 | Vertical gap. Number = rhythm units (×8px, fractions ok — 2 = 16px); string = raw CSS. |
+| align | "start" \| "center" \| "end" \| "stretch" | "stretch" | Cross-axis alignment. |
+| justify | "start" \| "center" \| "end" \| "between" | "start" | Main-axis distribution. |
+
+## Related
+
+- Components: Row, Page, Fieldset
+
+## Examples
+
+### Form field group
+
+```tsx
+import { Field, Input, Stack, Textarea } from "@sableui/react"
+
+<Stack gap={2}><Field label="Display name"><Input name="name" /></Field><Field label="Bio"><Textarea name="bio" /></Field></Stack>
+```

package/llms/patterns/auth-page.md

@@ -0,0 +1,68 @@
+# 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.
+
+**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.
+
+## 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.
+
+## Source
+
+```tsx
+import { Button, Card, CardContent, CardDescription, CardHeader, CardTitle, Field, Form, Input, Region, Separator, Stack } from "@sableui/react"
+
+export function AuthPage() {
+	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" />
+								</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>
+					</p>
+				</Stack>
+			</Region>
+		</main>
+	)
+}
+```