@tailor-platform/app-shell 1.15.0 → 1.17.0

package/skills/app-shell-patterns/references/components/badge.md

@@ -0,0 +1,309 @@
+---
+title: Badge
+description: Display status, labels, and tags with customizable variants
+---
+
+<!-- GENERATED by docs-kit from docs-src/components/badge.docs.outline.md — do not edit by hand. -->
+
+# Badge
+
+The `Badge` component displays status indicators, labels, and tags with multiple style variants. It's commonly used to show document status, priority levels, or categorical information.
+
+## Import
+
+```tsx
+import { Badge, type BadgeVariant, type BadgeOptions } from "@tailor-platform/app-shell";
+```
+
+## Basic Usage
+
+<example-preview name="basic-usage"></example-preview>
+
+```tsx
+function BasicUsage() {
+  return (
+    <div className="flex flex-wrap gap-2">
+      <Badge>Default</Badge>
+      <Badge variant="success">Success</Badge>
+      <Badge variant="warning">Warning</Badge>
+      <Badge variant="error">Error</Badge>
+      <Badge variant="info">Info</Badge>
+      <Badge variant="subtle-success">Subtle Success</Badge>
+      <Badge variant="subtle-warning">Subtle Warning</Badge>
+      <Badge variant="subtle-error">Subtle Error</Badge>
+      <Badge variant="subtle-info">Subtle Info</Badge>
+    </div>
+  );
+}
+```
+
+## Variants
+
+### Solid and Subtle Variants
+
+Filled variants for high emphasis, plus subtle variants for lower-emphasis status labels:
+
+```tsx
+<Badge variant="default">Default</Badge>
+<Badge variant="success">Approved</Badge>
+<Badge variant="warning">Pending</Badge>
+<Badge variant="error">Rejected</Badge>
+<Badge variant="neutral">Draft</Badge>
+<Badge variant="info">New</Badge>
+<Badge variant="subtle-success">Matched</Badge>
+<Badge variant="subtle-warning">Needs Attention</Badge>
+<Badge variant="subtle-error">Needs Review</Badge>
+<Badge variant="subtle-info">In Progress</Badge>
+```
+
+### Outline Variants with Status Dots
+
+Outlined badges with colored status dots for subtle emphasis:
+
+```tsx
+<Badge variant="outline-success">Active</Badge>
+<Badge variant="outline-warning">In Progress</Badge>
+<Badge variant="outline-error">Failed</Badge>
+<Badge variant="outline-info">Info</Badge>
+<Badge variant="outline-neutral">Inactive</Badge>
+```
+
+## Props
+
+_Generated from the type surface — first-party props only._
+
+### BadgeProps
+
+| Prop       | Type                                                                                                                                                                                                                                                           | Default     | Description          |
+| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | -------------------- |
+| `variant?` | `"error" \| "neutral" \| "success" \| "warning" \| "info" \| "default" \| "subtle-success" \| "subtle-warning" \| "subtle-error" \| "subtle-info" \| "outline-success" \| "outline-warning" \| "outline-error" \| "outline-info" \| "outline-neutral" \| null` | `"default"` | Visual style variant |
+
+## Exports
+
+- `Badge` — function
+- `BadgeProps` — interface
+- `badgeVariants` — const
+
+### Badge Variants
+
+```typescript
+type BadgeVariant =
+  // Solid/subtle variants
+  | "default" // Primary color
+  | "success" // Green
+  | "warning" // Yellow
+  | "error" // Red/destructive
+  | "neutral" // Gray/secondary
+  | "info" // Blue
+  | "subtle-success" // Low-emphasis green
+  | "subtle-warning" // Low-emphasis yellow
+  | "subtle-error" // Low-emphasis red/destructive
+  | "subtle-info" // Low-emphasis blue
+  // Outline variants with status dots
+  | "outline-success"
+  | "outline-warning"
+  | "outline-error"
+  | "outline-info"
+  | "outline-neutral";
+```
+
+### BadgeOptions
+
+Shared options used by `DataTable` and `DescriptionCard` badge fields:
+
+```typescript
+interface BadgeOptions {
+  /** Maps each value (stringified) to a Badge variant. Unmapped values use `defaultBadgeVariant`. */
+  badgeVariantMap?: Record<string, BadgeVariant>;
+  /** Maps each value (stringified) to a display label. Unmapped values render the raw value. */
+  badgeLabelMap?: Record<string, string>;
+  /** Variant used when the value is not in `badgeVariantMap`. Default: `"outline-neutral"`. */
+  defaultBadgeVariant?: BadgeVariant;
+}
+```
+
+## Examples
+
+### Order Status
+
+```tsx
+function OrderStatus({ status }: { status: string }) {
+  const variantMap: Record<string, BadgeVariant> = {
+    pending: "outline-warning",
+    processing: "outline-info",
+    shipped: "outline-success",
+    delivered: "success",
+    cancelled: "outline-error",
+  };
+
+  return <Badge variant={variantMap[status] || "neutral"}>{status.toUpperCase()}</Badge>;
+}
+```
+
+### Priority Badges
+
+```tsx
+const priorities = [
+  { label: "Low", variant: "outline-neutral" },
+  { label: "Medium", variant: "outline-info" },
+  { label: "High", variant: "outline-warning" },
+  { label: "Critical", variant = "error" },
+];
+
+<div className="flex gap-2">
+  {priorities.map((p) => (
+    <Badge key={p.label} variant={p.variant}>
+      {p.label}
+    </Badge>
+  ))}
+</div>;
+```
+
+### With Icons
+
+```tsx
+import { CheckCircle, AlertCircle, XCircle } from "lucide-react";
+
+<div className="flex gap-2">
+  <Badge variant="success">
+    <CheckCircle className="w-3 h-3 mr-1" />
+    Verified
+  </Badge>
+  <Badge variant="warning">
+    <AlertCircle className="w-3 h-3 mr-1" />
+    Review
+  </Badge>
+  <Badge variant="error">
+    <XCircle className="w-3 h-3 mr-1" />
+    Blocked
+  </Badge>
+</div>;
+```
+
+### Dynamic Variant Selection
+
+```tsx
+interface Product {
+  name: string;
+  stock: number;
+}
+
+function ProductBadge({ product }: { product: Product }) {
+  // Determine variant based on stock level
+  let variant: BadgeVariant = "success";
+  if (product.stock === 0) {
+    variant = "error";
+  } else if (product.stock < 10) {
+    variant = "warning";
+  }
+
+  return <Badge variant={variant}>{product.stock} in stock</Badge>;
+}
+```
+
+### Custom Styling
+
+```tsx
+<Badge variant="success" className="uppercase">
+  Premium
+</Badge>
+```
+
+## Visual Reference
+
+### Solid and Subtle Variants
+
+| Variant          | Preview                | Use Case                                   |
+| ---------------- | ---------------------- | ------------------------------------------ |
+| `default`        | ![Blue badge]          | Primary actions, default status            |
+| `success`        | ![Green badge]         | Completed, approved, active                |
+| `warning`        | ![Yellow badge]        | Pending, in progress, attention needed     |
+| `error`          | ![Red badge]           | Failed, rejected, critical                 |
+| `neutral`        | ![Gray badge]          | Draft, inactive, disabled                  |
+| `info`           | ![Blue badge]          | Informational, new, in-progress            |
+| `subtle-success` | ![Subtle green badge]  | Low-emphasis completed or matched statuses |
+| `subtle-warning` | ![Subtle yellow badge] | Low-emphasis pending or attention states   |
+| `subtle-error`   | ![Subtle red badge]    | Low-emphasis failures or exceptions        |
+| `subtle-info`    | ![Subtle blue badge]   | Low-emphasis informational or in-progress  |
+
+### Outline Variants
+
+| Variant           | Preview                 | Use Case                   |
+| ----------------- | ----------------------- | -------------------------- |
+| `outline-success` | ![Green dot + outline]  | Active, available, healthy |
+| `outline-warning` | ![Orange dot + outline] | In progress, scheduled     |
+| `outline-error`   | ![Red dot + outline]    | Error, unavailable, down   |
+| `outline-info`    | ![Blue dot + outline]   | Information, processing    |
+| `outline-neutral` | ![Gray dot + outline]   | Neutral state, inactive    |
+
+## Accessibility
+
+- Use semantic color meanings consistently (green = success, red = error, etc.)
+- Don't rely solely on color to convey information
+- Consider adding icons or text labels for clarity
+- Badges are non-interactive: they render with the default cursor (not a pointer) and won't suggest clickability, even when placed inside a clickable container such as a `DataTable` row with `onClickRow`
+
+## Usage in DescriptionCard
+
+Badges can be used with DescriptionCard for automatic status rendering:
+
+```tsx
+import { DescriptionCard } from "@tailor-platform/app-shell";
+
+<DescriptionCard
+  data={orderData}
+  fields={[
+    {
+      type: "badge",
+      key: "status",
+      label: "Status",
+      meta: {
+        sentenceCaseBadges: false,
+        badgeVariantMap: {
+          pending: "outline-warning",
+          shipped: "outline-success",
+          delivered: "success",
+        },
+      },
+    },
+  ]}
+/>;
+```
+
+[Learn more about DescriptionCard →](./description-card.md)
+
+## Best Practices
+
+### Do:
+
+- ✅ Use consistent variants for the same meaning across your app
+- ✅ Keep badge text short (1-2 words)
+- ✅ Use outline variants for subtle emphasis
+- ✅ Use solid variants for important status indicators
+
+### Don't:
+
+- ❌ Use too many different badge colors (stick to semantic colors)
+- ❌ Put long text in badges (use tooltips instead)
+- ❌ Make badges clickable without visual indication
+- ❌ Use badges for navigation (use links or buttons instead)
+
+## Related Components
+
+- [DescriptionCard](./description-card.md) - Use badges in structured displays
+- [Layout](./layout.md) - Organize badges in layouts
+
+## Styling
+
+Badges are styled with the library's internal `astw:`-prefixed utilities. Write **plain** Tailwind utilities in your own markup, and reach for `variant` rather than restyling what `Badge` sets itself — see [Styling AppShell components](../concepts/styling-theming.md#styling-appshell-components). Customize appearance by:
+
+1. **Using className prop** for additional styles
+2. **Overriding CSS variables** in your theme
+3. **Creating custom variants** using the `badgeVariants` utility
+
+```tsx
+import { badgeVariants } from "@tailor-platform/app-shell";
+import { cn } from "@/lib/utils";
+
+<div className={cn(badgeVariants({ variant: "success" }), "mt-2")}>Custom Badge</div>;
+```

package/skills/app-shell-patterns/references/components/button.md

@@ -0,0 +1,164 @@
+---
+title: Button
+description: Styled button with multiple variants and sizes
+---
+
+<!-- GENERATED by docs-kit from docs-src/components/button.docs.outline.md — do not edit by hand. -->
+
+# Button
+
+The `Button` component is a styled button with multiple visual variants and sizes. It supports rendering as a custom element via the `render` prop (Base UI render pattern).
+
+## Import
+
+```tsx
+import { Button } from "@tailor-platform/app-shell";
+```
+
+## Basic Usage
+
+<example-preview name="basic-usage"></example-preview>
+
+```tsx
+function BasicUsage() {
+  return (
+    <div className="flex gap-2">
+      <Button>Click me</Button>
+      <Button variant="outline">Outline</Button>
+      <Button variant="destructive">Delete</Button>
+    </div>
+  );
+}
+```
+
+## Props
+
+_Generated from the type surface — first-party props only._
+
+### ButtonProps
+
+| Prop       | Type                                                                                  | Default     | Description                                       |
+| ---------- | ------------------------------------------------------------------------------------- | ----------- | ------------------------------------------------- |
+| `render?`  | `React.ReactElement`                                                                  | -           | Custom element to render as (Base UI render prop) |
+| `size?`    | `"default" \| "sm" \| "lg" \| "xs" \| "icon" \| null`                                 | `"default"` | Button size                                       |
+| `variant?` | `"link" \| "default" \| "destructive" \| "outline" \| "secondary" \| "ghost" \| null` | `"default"` | Visual style variant                              |
+
+## Exports
+
+- `Button` — function
+- `ButtonProps` — type
+- `buttonVariants` — const
+
+All standard HTML `<button>` props are also accepted.
+
+## Variants
+
+<example-preview name="variants"></example-preview>
+
+```tsx
+function Variants() {
+  return (
+    <div className="flex flex-wrap gap-2">
+      <Button variant="default">Primary Action</Button>
+      <Button variant="destructive">Delete</Button>
+      <Button variant="outline">Secondary Action</Button>
+      <Button variant="secondary">Tertiary</Button>
+      <Button variant="ghost">Ghost</Button>
+      <Button variant="link">Link Style</Button>
+    </div>
+  );
+}
+```
+
+## Sizes
+
+<example-preview name="sizes"></example-preview>
+
+```tsx
+function Sizes() {
+  return (
+    <div className="flex items-center gap-2">
+      <Button size="xs">Extra Small</Button>
+      <Button size="sm">Small</Button>
+      <Button size="default">Default</Button>
+      <Button size="lg">Large</Button>
+      <Button size="icon">
+        <PlusIcon />
+      </Button>
+    </div>
+  );
+}
+```
+
+## Render Prop
+
+The `render` prop lets you use the button's styles on a custom element:
+
+```tsx
+import { Button } from "@tailor-platform/app-shell";
+import { Link } from "@tailor-platform/app-shell";
+
+<Button render={<Link to="/orders" />} variant="outline">
+  View Orders
+</Button>;
+```
+
+This is the Base UI render pattern — the button's class names and event handlers are applied to the rendered element.
+
+## Examples
+
+### Form Actions
+
+```tsx
+<div className="flex gap-2 justify-end">
+  <Button variant="outline">Cancel</Button>
+  <Button>Save Changes</Button>
+</div>
+```
+
+### Destructive Confirmation
+
+```tsx
+<Button variant="destructive" onClick={handleDelete}>
+  Delete Order
+</Button>
+```
+
+### Icon Button
+
+```tsx
+import { PlusIcon } from "lucide-react";
+
+<Button size="icon" variant="outline">
+  <PlusIcon />
+</Button>;
+```
+
+## TypeScript
+
+```typescript
+import { type ButtonProps } from "@tailor-platform/app-shell";
+```
+
+## Styling
+
+Use `buttonVariants` to apply button styles to non-button elements:
+
+```tsx
+import { buttonVariants } from "@tailor-platform/app-shell";
+
+<a href="/orders" className={buttonVariants({ variant: "outline", size: "sm" })}>
+  View Orders
+</a>;
+```
+
+## Accessibility
+
+- Buttons render with `cursor: pointer` to signal interactivity consistently across all variants and sizes.
+- Disabled buttons suppress the pointer cursor via `pointer-events-none`, so they do not signal clickability.
+
+## Related Components
+
+- [Dialog](./dialog.md) - Use buttons as dialog triggers and actions
+- [Sheet](./sheet.md) - Use buttons as sheet triggers
+- [Layout](./layout.md) - Use buttons in page header actions

package/skills/app-shell-patterns/references/components/card.md

@@ -0,0 +1,181 @@
+---
+title: Card
+description: General-purpose container with consistent styling using a compound component API
+---
+
+<!-- GENERATED by docs-kit from docs-src/components/card.docs.outline.md — do not edit by hand. -->
+
+# Card
+
+`Card` is a general-purpose container component with a compound component API (`Card.Root`, `Card.Header`, `Card.Content`). It provides consistent surface styling (background, border, border-radius, shadow) for grouping related content.
+
+## Import
+
+```tsx
+import { Card } from "@tailor-platform/app-shell";
+```
+
+## Basic Usage
+
+<example-preview name="basic-usage"></example-preview>
+
+```tsx
+function BasicUsage() {
+  return (
+    <Card.Root>
+      <Card.Header title="Order Details" description="Summary of order #1234" />
+      <Card.Content>
+        <p>Content goes here</p>
+      </Card.Content>
+    </Card.Root>
+  );
+}
+```
+
+## Parts
+
+| Part           | Description                                                      |
+| -------------- | ---------------------------------------------------------------- |
+| `Card.Root`    | Outer container. Renders a `<div>` with surface styling applied. |
+| `Card.Header`  | Top section with an optional title and description.              |
+| `Card.Content` | Body section with consistent padding, or edge-to-edge.           |
+
+## Card.Root Props
+
+`Card.Root` accepts all standard HTML `<div>` props.
+
+| Prop        | Type              | Default | Description            |
+| ----------- | ----------------- | ------- | ---------------------- |
+| `className` | `string`          | -       | Additional CSS classes |
+| `children`  | `React.ReactNode` | -       | Card parts and content |
+
+## Card.Header Props
+
+| Prop          | Type              | Default | Description                                                 |
+| ------------- | ----------------- | ------- | ----------------------------------------------------------- |
+| `title`       | `React.ReactNode` | -       | Card title rendered in a `<h3>`.                            |
+| `description` | `React.ReactNode` | -       | Supplementary text rendered below the title.                |
+| `children`    | `React.ReactNode` | -       | Additional header content rendered after title/description. |
+| `className`   | `string`          | -       | Additional CSS classes.                                     |
+
+## Card.Content Props
+
+`Card.Content` accepts all standard HTML `<div>` props.
+
+| Prop        | Type                    | Default     | Description                                                                                    |
+| ----------- | ----------------------- | ----------- | ---------------------------------------------------------------------------------------------- |
+| `padding`   | `"default"` \| `"none"` | `"default"` | `"none"` renders the content edge-to-edge — see [Edge-to-edge content](#edge-to-edge-content). |
+| `className` | `string`                | -           | Additional CSS classes                                                                         |
+| `children`  | `React.ReactNode`       | -           | Card body content                                                                              |
+
+## Edge-to-edge content
+
+Use `padding="none"` when a `Table`, `DataTable` or divided list should meet the card's border instead of floating inside it:
+
+<example-preview name="edge-to-edge-table"></example-preview>
+
+```tsx
+function EdgeToEdgeTable() {
+  return (
+    <Card.Root>
+      <Card.Header title="Line items" />
+      <Card.Content padding="none">
+        <Table.Root>
+          <Table.Header>
+            <Table.Row>
+              <Table.Head>Item</Table.Head>
+              <Table.Head align="right">Qty</Table.Head>
+            </Table.Row>
+          </Table.Header>
+          <Table.Body>
+            <Table.Row>
+              <Table.Cell>Steel bracket</Table.Cell>
+              <Table.Cell align="right">12</Table.Cell>
+            </Table.Row>
+            <Table.Row>
+              <Table.Cell>Hex bolt M8</Table.Cell>
+              <Table.Cell align="right">40</Table.Cell>
+            </Table.Row>
+          </Table.Body>
+        </Table.Root>
+      </Card.Content>
+    </Card.Root>
+  );
+}
+```
+
+Don't add padding back on the table. `Table.Head` and `Table.Cell` already inset their first and last cells by 24px, which lines the first column up with the card title.
+
+Edge-to-edge content also:
+
+- **Keeps row backgrounds inside the card's rounded corners.** A direct `Table` or `DataTable` child clips its row hover and pinned-cell backgrounds to the card's corners.
+- **Removes a nested `DataTable`'s own border**, so it doesn't draw a box inside the card. Its toolbar and footer stay as they are:
+
+```tsx
+<Card.Root>
+  <Card.Header title="Line items" />
+  <Card.Content padding="none">
+    <DataTable.Root value={table}>
+      <DataTable.Table />
+      <DataTable.Footer>
+        <DataTable.Pagination />
+      </DataTable.Footer>
+    </DataTable.Root>
+  </Card.Content>
+</Card.Root>
+```
+
+For a scrollable list, put the overflow on `Card.Content`. Rows supply their own `px-6`, and dividers run to the card edges:
+
+```tsx
+<Card.Content padding="none" className="max-h-60 overflow-y-auto">
+  <ul className="divide-y divide-border border-t border-border">
+    {items.map((item) => (
+      <li key={item.id} className="px-6 py-3">
+        {item.name}
+      </li>
+    ))}
+  </ul>
+</Card.Content>
+```
+
+## Examples
+
+### Header only
+
+```tsx
+<Card.Root>
+  <Card.Header title="Summary" description="Key metrics for this period" />
+</Card.Root>
+```
+
+### Content only
+
+```tsx
+<Card.Root>
+  <Card.Content>
+    <p>No header needed for this card.</p>
+  </Card.Content>
+</Card.Root>
+```
+
+### Custom header content
+
+```tsx
+<Card.Root>
+  <Card.Header title="Recent Orders">
+    <Button size="sm" variant="outline">
+      View all
+    </Button>
+  </Card.Header>
+  <Card.Content padding="none">
+    <Table.Root>{/* ... */}</Table.Root>
+  </Card.Content>
+</Card.Root>
+```
+
+## Related
+
+- [MetricCard](./metric-card.md) — Card variant for KPI / dashboard metric display.
+- [DescriptionCard](./description-card.md) — Card variant for structured key-value data.
+- [ActivityCard](./activity-card.md) — Card variant for timeline activity feeds.