@alexgorbatchev/shadcn 0.0.48 → 0.0.50

package/llms/components/forms/OptionSelect.md

@@ -0,0 +1,100 @@
+# OptionSelect
+
+Story: @alexgorbatchev/shadcn/components/forms/OptionSelect
+Source: src/components/stories/forms/OptionSelect.stories.tsx
+
+[Full source and local helpers](https://github.com/alexgorbatchev/shadcn/blob/main/src/components/stories/forms/OptionSelect.stories.tsx)
+
+## Public imports
+
+```tsx
+import { Button, OptionSelect } from "@alexgorbatchev/shadcn";
+```
+
+## Supporting imports
+
+```tsx
+import { useState } from "react";
+```
+
+## Default component
+
+```tsx
+OptionSelect
+```
+
+## Default args
+
+```tsx
+{ options, defaultValue: "bun", "aria-label": "Runtime", onValueChange }
+```
+
+## Examples
+
+Storybook CSF excerpts. Default args and render apply unless overridden. Local helpers, fixtures, decorators, and providers may be required; these are reference excerpts, not standalone consumer modules. Interaction tests are omitted.
+
+### Default
+
+```tsx
+{}
+```
+
+### EmptyStringIsAnOption
+
+```tsx
+{
+    args: { defaultValue: "" }
+}
+```
+
+### Placeholder
+
+```tsx
+{
+    args: { defaultValue: undefined, options: options.slice(1), placeholder: "Pick a runtime" }
+}
+```
+
+### Disabled
+
+```tsx
+{
+    args: { disabled: true }
+}
+```
+
+### Controlled
+
+```tsx
+{
+    render: () => <ControlledExample />
+}
+```
+
+### SubmitsWithAForm
+
+```tsx
+{
+    render: (args) => (<form onSubmit={(event) => {
+            event.preventDefault();
+            onSubmit(new FormData(event.currentTarget).get("runtime"));
+        }}>
+      <OptionSelect {...args} name="runtime"/>
+      <Button type="submit">Save</Button>
+    </form>),
+    args: { defaultValue: "" }
+}
+```
+
+### FullWidth
+
+```tsx
+{
+    args: { width: "full" },
+    decorators: [
+        (Story) => (<div className="w-96">
+        <Story />
+      </div>),
+    ]
+}
+```

package/llms/components/layout/AppShell.md

@@ -8,7 +8,8 @@ Source: src/components/stories/layout/AppShell.stories.tsx
 ## Public imports
 
 ```tsx
-import { AppShell, PageHeader, StatCard } from "@alexgorbatchev/shadcn";
+import { AnalyticsProvider } from "@alexgorbatchev/shadcn/analytics";
+import { AppShell, PageHeader, Stack, StatCard, Text } from "@alexgorbatchev/shadcn";
 ```
 
 ## Default component
@@ -61,3 +62,36 @@ Storybook CSF excerpts. Default args and render apply unless overridden. Local h
     }
 }
 ```
+
+### RouterLinks
+
+```tsx
+{
+    args: {
+        navigation: [
+            { id: "plans", label: "Plans", render: <ClientRouterLink to="/plans" onNavigate={navigate}/>, active: true },
+            { id: "settings", label: "Settings", render: <ClientRouterLink to="/settings" onNavigate={navigate}/> },
+            { id: "help", label: "Help", href: "#help" },
+        ],
+    },
+    decorators: [
+        (Story) => (<AnalyticsProvider enabled transport={{ track: trackNavigation }}>
+        <Story />
+      </AnalyticsProvider>),
+    ]
+}
+```
+
+### FillContent
+
+```tsx
+{
+    args: {
+        content: "fill",
+        footer: undefined,
+        children: (<Stack height="full" render={<section aria-label="Workspace canvas"/>}>
+        <Text>Full-height content owns its own scrolling.</Text>
+      </Stack>),
+    }
+}
+```

package/llms/components/layout/Container.md

@@ -0,0 +1,97 @@
+# Container
+
+Container centers a column with a maximum width: xs 20rem, sm 24rem, md 42rem, lg 64rem (default), xl 80rem, or full. `padding` uses the density-aware spacing tokens. For a centered single-column page such as sign-in, wrap it in a `Stack` with `height="min-viewport"`, `align="center"`, and `justify="center"`, and render the page landmark with `render={<main />}`.
+
+Story: @alexgorbatchev/shadcn/components/layout/Container
+Source: src/components/stories/layout/Container.stories.tsx
+
+[Full source and local helpers](https://github.com/alexgorbatchev/shadcn/blob/main/src/components/stories/layout/Container.stories.tsx)
+
+## Public imports
+
+```tsx
+import { AuthForm, Container, Stack, Text } from "@alexgorbatchev/shadcn";
+```
+
+## Default component
+
+```tsx
+Container
+```
+
+## Story controls
+
+```tsx
+{
+    width: { control: "select", options: ["xs", "sm", "md", "lg", "xl", "full"] },
+    padding: { control: "select", options: ["none", "control", "panel-sm", "panel", "field", "section"] },
+}
+```
+
+## Default args
+
+```tsx
+{ width: "md", padding: "panel" }
+```
+
+## Default render
+
+```tsx
+(args) => (<Container {...args} render={<article aria-label="Article"/>}>
+      <Text>Plans, notes, and decisions stay in one place.</Text>
+    </Container>)
+```
+
+## Examples
+
+Storybook CSF excerpts. Default args and render apply unless overridden. Local helpers, fixtures, decorators, and providers may be required; these are reference excerpts, not standalone consumer modules. Interaction tests are omitted.
+
+### Centered
+
+```tsx
+{
+    decorators: [
+        (Story) => (<div className="w-[900px]">
+        <Story />
+      </div>),
+    ]
+}
+```
+
+### NarrowParent
+
+```tsx
+{
+    decorators: [
+        (Story) => (<div className="w-60">
+        <Story />
+      </div>),
+    ]
+}
+```
+
+### SignInPage
+
+```tsx
+{
+    args: { width: "sm", padding: "none" },
+    render: (args) => (<Stack height="min-viewport" align="center" justify="center" padding="panel" render={<main aria-label="Sign in page"/>}>
+      <Container {...args}>
+        <AuthForm onSubmit={fn()}/>
+      </Container>
+    </Stack>)
+}
+```
+
+### DefaultWidth
+
+```tsx
+{
+    args: { width: undefined, padding: undefined },
+    decorators: [
+        (Story) => (<div className="w-[1200px]">
+        <Story />
+      </div>),
+    ]
+}
+```

package/llms/components/layout/Grid.md

@@ -0,0 +1,133 @@
+# Grid
+
+Grid lays out equal columns without consumer classes. `columns` is 1–6 or 12, or a viewport breakpoint map such as `{ base: 1, md: 2, xl: 4 }`. `minColumnWidth` (xs 8rem, sm 12rem, md 16rem, lg 22rem) instead fits as many columns as the grid's own width allows, which suits card grids inside panes of any size. `gap` defaults to the density-aware `panel` token. GridItem `span` (1–6 or `full`, optionally per breakpoint) widens a cell; `full` always spans every column. Both accept `render` for semantic elements such as `<ul />` and `<li />`.
+
+Story: @alexgorbatchev/shadcn/components/layout/Grid
+Source: src/components/stories/layout/Grid.stories.tsx
+
+[Full source and local helpers](https://github.com/alexgorbatchev/shadcn/blob/main/src/components/stories/layout/Grid.stories.tsx)
+
+## Public imports
+
+```tsx
+import { Card, CardContent, CardHeader, CardTitle, Field, FieldLabel, Grid, GridItem, Input, Textarea } from "@alexgorbatchev/shadcn";
+```
+
+## Default component
+
+```tsx
+Grid
+```
+
+## Story controls
+
+```tsx
+{
+    columns: { control: "select", options: [1, 2, 3, 4, 5, 6, 12] },
+    gap: { control: "select", options: ["none", "control", "panel-sm", "panel", "field", "section"] },
+    align: { control: "select", options: ["start", "center", "end", "stretch"] },
+}
+```
+
+## Default args
+
+```tsx
+{ columns: 2 }
+```
+
+## Default render
+
+```tsx
+(args) => (<Grid {...args} render={<ul aria-label="Venues"/>}>
+      {["Harbor walk", "Night market", "Rooftop bar", "Botanical garden"].map((venue) => (<GridItem key={venue} render={<li />}>
+          <Card>
+            <CardHeader>
+              <CardTitle>{venue}</CardTitle>
+            </CardHeader>
+            <CardContent>Open until late.</CardContent>
+          </Card>
+        </GridItem>))}
+    </Grid>)
+```
+
+## Examples
+
+Storybook CSF excerpts. Default args and render apply unless overridden. Local helpers, fixtures, decorators, and providers may be required; these are reference excerpts, not standalone consumer modules. Interaction tests are omitted.
+
+### Columns
+
+```tsx
+{}
+```
+
+### ResponsiveColumns
+
+```tsx
+{
+    args: { columns: { base: 1, md: 2 } }
+}
+```
+
+### IntrinsicColumns
+
+```tsx
+{
+    args: { columns: undefined, minColumnWidth: "sm" },
+    decorators: [
+        (Story) => (<div className="w-[440px]">
+        <Story />
+      </div>),
+    ]
+}
+```
+
+### IntrinsicColumnsInNarrowPane
+
+```tsx
+{
+    args: { columns: undefined, minColumnWidth: "sm" },
+    decorators: [
+        (Story) => (<div className="w-[160px]">
+        <Story />
+      </div>),
+    ]
+}
+```
+
+### TwoColumnForm
+
+```tsx
+{
+    args: { columns: 2, gap: "field" },
+    render: (args) => (<Grid {...args} render={<form aria-label="Contact"/>}>
+      <Field>
+        <FieldLabel htmlFor="grid-first-name">First name</FieldLabel>
+        <Input id="grid-first-name"/>
+      </Field>
+      <Field>
+        <FieldLabel htmlFor="grid-last-name">Last name</FieldLabel>
+        <Input id="grid-last-name"/>
+      </Field>
+      <GridItem span="full">
+        <Field>
+          <FieldLabel htmlFor="grid-notes">Notes</FieldLabel>
+          <Textarea id="grid-notes"/>
+        </Field>
+      </GridItem>
+    </Grid>)
+}
+```
+
+### ResponsiveSpan
+
+```tsx
+{
+    args: { columns: 4, gap: "control" },
+    render: (args) => (<Grid {...args}>
+      <GridItem span={{ base: 2, md: 4 }} render={<section aria-label="Wide"/>}>
+        Wide
+      </GridItem>
+      <GridItem render={<section aria-label="Narrow"/>}>Narrow</GridItem>
+    </Grid>)
+}
+```

package/llms/components/layout/PageIntro.md

@@ -0,0 +1,102 @@
+# PageIntro
+
+Story: @alexgorbatchev/shadcn/components/layout/PageIntro
+Source: src/components/stories/layout/PageIntro.stories.tsx
+
+[Full source and local helpers](https://github.com/alexgorbatchev/shadcn/blob/main/src/components/stories/layout/PageIntro.stories.tsx)
+
+## Public imports
+
+```tsx
+import { PageIntro, Button } from "@alexgorbatchev/shadcn";
+```
+
+## Supporting imports
+
+```tsx
+import { BookmarkIcon, CalendarIcon, HeartIcon, SparklesIcon } from "lucide-react";
+```
+
+## Default component
+
+```tsx
+PageIntro
+```
+
+## Default args
+
+```tsx
+{
+    icon: <BookmarkIcon />,
+    title: "Projects",
+    description: "Everything your team is working on, in one place you will actually want to open.",
+    actions: <Button onClick={action}>New project</Button>,
+    highlights,
+}
+```
+
+## Examples
+
+Storybook CSF excerpts. Default args and render apply unless overridden. Local helpers, fixtures, decorators, and providers may be required; these are reference excerpts, not standalone consumer modules. Interaction tests are omitted.
+
+### Default
+
+```tsx
+{}
+```
+
+### WithoutHighlights
+
+```tsx
+{
+    args: { highlights: undefined }
+}
+```
+
+### EmptyHighlights
+
+```tsx
+{
+    args: { highlights: [] }
+}
+```
+
+### WithEyebrow
+
+```tsx
+{
+    args: { eyebrow: "WEEKEND CREW", actions: undefined }
+}
+```
+
+### TextOnly
+
+```tsx
+{
+    args: { icon: undefined, actions: undefined, highlights: undefined }
+}
+```
+
+### Narrow
+
+```tsx
+{
+    decorators: [
+        (Story) => (<div className="w-80 max-w-full">
+        <Story />
+      </div>),
+    ]
+}
+```
+
+### Wide
+
+```tsx
+{
+    decorators: [
+        (Story) => (<div className="w-5xl max-w-full">
+        <Story />
+      </div>),
+    ]
+}
+```

package/llms/components/layout/Stack.md

@@ -0,0 +1,170 @@
+# Stack
+
+Stack arranges children along one axis without consumer classes. `gap` and `padding` accept the density-aware tokens none, control, panel-sm, panel, field, and section. `direction` is vertical or horizontal, or a breakpoint map such as `{ base: "vertical", md: "horizontal" }`. `align` and `justify` position children; `wrap` lets a row wrap. `grow` takes the remaining space of a parent Stack and lets content shrink, and `height` is auto, full (the parent's height), viewport, or min-viewport. Pass `render={<section />}`, `<ul />`, `<li />`, `<form />`, or `<main />` for semantic elements; props, handlers, and refs merge.
+
+Story: @alexgorbatchev/shadcn/components/layout/Stack
+Source: src/components/stories/layout/Stack.stories.tsx
+
+[Full source and local helpers](https://github.com/alexgorbatchev/shadcn/blob/main/src/components/stories/layout/Stack.stories.tsx)
+
+## Public imports
+
+```tsx
+import { Badge, Button, Heading, ScrollArea, Stack, Text } from "@alexgorbatchev/shadcn";
+```
+
+## Default component
+
+```tsx
+Stack
+```
+
+## Story controls
+
+```tsx
+{
+    direction: { control: "inline-radio", options: ["vertical", "horizontal"] },
+    gap: { control: "select", options: ["none", "control", "panel-sm", "panel", "field", "section"] },
+    padding: { control: "select", options: ["none", "control", "panel-sm", "panel", "field", "section"] },
+    align: { control: "select", options: ["start", "center", "end", "stretch", "baseline"] },
+    justify: { control: "select", options: ["start", "center", "end", "between"] },
+    height: { control: "select", options: ["auto", "full", "viewport", "min-viewport"] },
+}
+```
+
+## Default args
+
+```tsx
+{ gap: "panel" }
+```
+
+## Default render
+
+```tsx
+(args) => (<Stack {...args} render={<section aria-label="Profile"/>}>
+      <Heading level={2}>Profile</Heading>
+      <Text tone="muted">Shown to everyone in the workspace.</Text>
+      <Text>Members see your name and avatar.</Text>
+    </Stack>)
+```
+
+## Examples
+
+Storybook CSF excerpts. Default args and render apply unless overridden. Local helpers, fixtures, decorators, and providers may be required; these are reference excerpts, not standalone consumer modules. Interaction tests are omitted.
+
+### Vertical
+
+```tsx
+{}
+```
+
+### CompactDensity
+
+```tsx
+{
+    args: { density: "compact" }
+}
+```
+
+### HeaderWithTrailingActions
+
+```tsx
+{
+    args: { direction: "horizontal", justify: "between", align: "center", gap: "control", wrap: true },
+    render: (args) => (<Stack {...args} render={<section aria-label="Section header"/>}>
+      <Heading level={2}>Members</Heading>
+      <Stack direction="horizontal" gap="control">
+        <Button variant="outline">Export</Button>
+        <Button>Invite</Button>
+      </Stack>
+    </Stack>)
+}
+```
+
+### Wrapping
+
+```tsx
+{
+    args: { direction: "horizontal", gap: "control", wrap: true },
+    decorators: [
+        (Story) => (<div className="w-48">
+        <Story />
+      </div>),
+    ],
+    render: (args) => (<Stack {...args} render={<ul aria-label="Interests"/>}>
+      {["Museums", "Live music", "Hiking", "Street food", "Cinema"].map((interest) => (<Stack key={interest} render={<li />}>
+          <Badge variant="secondary">{interest}</Badge>
+        </Stack>))}
+    </Stack>)
+}
+```
+
+### ResponsiveDirection
+
+```tsx
+{
+    args: { direction: { base: "vertical", md: "horizontal" } },
+    render: (args) => (<Stack {...args}>
+      <Text>First</Text>
+      <Text>Second</Text>
+    </Stack>)
+}
+```
+
+### FullHeightRegion
+
+```tsx
+{
+    args: { height: "full", gap: "none" },
+    decorators: [
+        (Story) => (<div className="h-60 w-72 border border-border" data-scroll="none">
+        <Story />
+      </div>),
+    ],
+    render: (args) => (<Stack {...args}>
+      <Stack padding="panel-sm">
+        <Heading level={2}>Activity</Heading>
+      </Stack>
+      <ScrollArea grow aria-label="Activity log">
+        <Stack padding="panel-sm" gap="control" render={<ol />}>
+          {Array.from({ length: 30 }, (_, index) => (<Text key={index} render={<li />}>
+              Update {index + 1}
+            </Text>))}
+        </Stack>
+      </ScrollArea>
+      <Stack padding="panel-sm" direction="horizontal" justify="end">
+        <Button>Refresh</Button>
+      </Stack>
+    </Stack>)
+}
+```
+
+### GrowingPane
+
+```tsx
+{
+    args: { direction: "horizontal", gap: "panel", height: "full" },
+    decorators: [
+        (Story) => (<div className="h-24 w-96">
+        <Story />
+      </div>),
+    ],
+    render: (args) => (<Stack {...args}>
+      <Text>Fixed</Text>
+      <Stack grow padding="control" render={<section aria-label="Remaining space"/>}>
+        <Text truncate>A very long description that must shrink to the remaining width instead of overflowing</Text>
+      </Stack>
+    </Stack>)
+}
+```
+
+### FormElement
+
+```tsx
+{
+    render: (args) => (<Stack {...args} render={<form aria-label="Rename" onSubmit={submitForm}/>}>
+      <Text>Rename the workspace.</Text>
+      <Button type="submit">Save</Button>
+    </Stack>)
+}
+```