@jovertical/mise-design-system 0.0.0-stage → 1.1.0

package/skills/mise/components/layout.md

@@ -0,0 +1,178 @@
+<!-- Generated by pnpm build:skill. Do not edit by hand. -->
+
+# Layout
+
+## AsideCard
+
+`import { AsideCard } from '@jovertical/mise-design-system'`
+
+A collapsible card for a page's right-hand column.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `icon` (required) | `Snippet` |  |  |
+| `title` (required) | `string` |  |  |
+| `open` | `boolean` | `true` | Open to start. Collapsed suits a card that repeats on every step of a flow. |
+| `children` (required) | `Snippet` |  |  |
+
+Also takes: everything `Card` takes except `title`, `children`.
+
+## Card
+
+`import { Card, CardAction, CardContent, CardDescription, CardFooter, CardHeader, CardTitle } from '@jovertical/mise-design-system'`
+
+Padding is a `--card-spacing` variable on both axes, at 20px, so a full-bleed child can cancel it. The edge is a ring plus a shadow rather than a border. `ghost` drops the surface for a block that wants the card's rhythm but sits straight on the page.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `variant` | `'default' \| 'ghost'` | `'default'` |  |
+
+Also takes: every `<div>` attribute.
+
+### `CardAction`
+
+The header's top-right slot, for something the reader can do: a menu, an Edit link, a view toggle. Not a place to park a figure. A count where every other card puts its action reads as one; if a heading needs qualifying, put a hint next to the title.
+
+Also takes: every `<div>` attribute.
+
+### `CardContent`
+
+`stack` turns on a vertical flex with a gap, for content that is several blocks rather than one. Off by default: `CardContent` stays a plain block, which is right for one child. `sm` / `md` / `lg` name the three gaps cards actually reach for, so the choice is made once, here.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `stack` | `keyof typeof CONTENT_STACK_CLASS` |  |  |
+
+Also takes: every `<div>` attribute.
+
+### `CardDescription`
+
+Also takes: every `<div>` attribute.
+
+### `CardFooter`
+
+`bleed` runs the footer to the card's edges, for a footer that is one wide target ("View all orders") rather than content with actions in it. Three things happen together, which is why it is one prop: the card's bottom padding is cancelled, the horizontal padding goes (a Button inside gets the card's gutter back, so its label lines up with the title), and the bottom corners are rounded and clipped.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `bleed` | `boolean` | `false` |  |
+| `divided` | `boolean` | `false` |  |
+| `variant` | `'default' \| 'muted'` | `'default'` |  |
+
+Also takes: every `<div>` attribute.
+
+### `CardHeader`
+
+The two explicit row tracks appear only when a `CardAction` is present. Upstream declares them unconditionally, so a title-only header carried an empty second track and its gutter. `auto-rows-min` already makes as many rows as there are children.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `divided` | `boolean` | `false` |  |
+
+Also takes: every `<div>` attribute.
+
+### `CardTitle`
+
+A flex row, so a hint or a status badge sits on the title's baseline without the caller arranging it. `min-w-0` lets a long title truncate against its neighbour instead of pushing it out of the header.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `icon` | `Snippet` |  | A leading glyph. Bare and muted at `size-4` unless `iconTone` is given. |
+| `iconTone` | `'neutral' \| 'primary' \| 'info' \| 'success' \| 'warning' \| 'critical'` |  | Draws `icon` in an `IconChip` of this tone. Omit it for a quiet heading. `primary` when the headings are the page's structure, as on a long form. Never a status tone: a heading is not a status. |
+
+Also takes: every `<div>` attribute.
+
+Types: `CardVariant` (`'default' | 'ghost'`).
+
+## CardGrid
+
+`import { CardGrid, CardGridCell } from '@jovertical/mise-design-system'`
+
+A responsive grid of bordered cells, with no opinion on what fills them. `MetricGrid` is this with a `MetricBar` in every cell; a caller whose cells are not a percent breakdown wants the grid on its own.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `columns` | `2 \| 3 \| 4` | `3` | Columns at `md` and up. Below that it is always one: two cells side by side on a phone leave no room for real content. |
+
+Also takes: every `<div>` attribute.
+
+### `CardGridCell`
+
+One cell. Bordered rather than filled or shadowed, deliberately lighter than `Card`: a wash or a ring on every cell of a dense grid competes with what the content needs to carry attention.
+
+Also takes: every `<div>` attribute.
+
+## CardList
+
+`import { CardList } from '@jovertical/mise-design-system'`
+
+A list of rows inside a card, separated by full-width rules. The rules run to the card's edges: inset, they read as stripes drawn on the content; full-bleed, they read as the card divided into rows.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `compact` | `boolean` | `false` | Tighter rows, for rows of one line. The default `py-4` is sized for a leading chip and two lines. A prop rather than a class at the call site: a second arbitrary variant does not reliably win against this one. |
+
+Also takes: every `<div>` attribute.
+
+## Collapsible
+
+`import { Collapsible, CollapsibleContent, CollapsibleTrigger } from '@jovertical/mise-design-system'`
+
+Unstyled: the primitive holds open state and nothing else. `AsideCard` builds a real card on top of it; reach for `Collapsible` directly when the surface around it is not a card.
+
+Also takes: bits-ui `Collapsible.Root` props.
+
+### `CollapsibleContent`
+
+Also takes: bits-ui `Collapsible.Content` props.
+
+### `CollapsibleTrigger`
+
+Also takes: bits-ui `Collapsible.Trigger` props.
+
+## PageHeader
+
+`import { PageHeader } from '@jovertical/mise-design-system'`
+
+Which affordance a page carries, by what kind of page it is:
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `title` | `string` |  | Omit it when the trail carries the leaf and repeating it would add nothing. Without a title there is no `h1`, so the body owns the heading. |
+| `description` | `string \| Snippet` |  |  |
+| `breadcrumb` | `Snippet` |  | The trail of ancestors, above the title. Pass this or `backLink`, not both. |
+| `backLink` | `Snippet` |  | A way back out, where the breadcrumb would be: the create-and-edit shape. |
+| `eyebrow` | `string \| Snippet` |  | A short uppercase label naming the kind of page when the title cannot. |
+| `titleAccessory` | `Snippet` |  | Inline with the title: a switcher, a status badge. |
+| `truncateTitle` | `boolean` | `false` | One line, capped at `max-w-3xl`, with the whole title as a tooltip. For titles someone else wrote. |
+| `actions` | `Snippet` |  | The right-hand action cluster. |
+| `class` | `string` |  |  |
+
+## PageLayout
+
+`import { PageLayout } from '@jovertical/mise-design-system'`
+
+The padded column every routed page sits in, so the gutter and the vertical rhythm are decided once rather than per route.
+
+Also takes: every `<div>` attribute.
+
+## Separator
+
+`import { Separator } from '@jovertical/mise-design-system'`
+
+Also takes: bits-ui `Separator.Root` props.
+
+## SummaryCard
+
+`import { SummaryCard } from '@jovertical/mise-design-system'`
+
+A read-only account of what one step produced.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `icon` (required) | `Snippet` |  |  |
+| `title` (required) | `string` |  |  |
+| `action` | `Snippet` |  | The way back to where these fields are edited, if there is one. |
+| `children` (required) | `Snippet` |  |  |
+
+Also takes: everything `Card` takes except `title`, `children`.

package/skills/mise/components/navigation.md

@@ -0,0 +1,250 @@
+<!-- Generated by pnpm build:skill. Do not edit by hand. -->
+
+# Navigation
+
+## Breadcrumb
+
+`import { Breadcrumb, BreadcrumbEllipsis, BreadcrumbItem, BreadcrumbLink, BreadcrumbList, BreadcrumbPage, BreadcrumbSeparator } from '@jovertical/mise-design-system'`
+
+Written against shadcn/ui's `breadcrumb` API, not ported from it: the names match so a reader arriving from shadcn finds what they expect. The separator is `/` and the leaf is not a disabled link.
+
+Also takes: every HTML attribute.
+
+### `BreadcrumbEllipsis`
+
+Stands in for crumbs dropped from the middle of a long trail.
+
+Also takes: every `<span>` attribute.
+
+### `BreadcrumbItem`
+
+`min-w-0` so a long crumb can truncate rather than push the trail past the edge. Crumbs that must never shrink (the root, the leaf) say so with `shrink-0`.
+
+Also takes: every `<li>` attribute.
+
+### `BreadcrumbLink`
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `child` | `Snippet<[{ props: Record<string, unknown> }]>` |  | Renders your own link with these props instead of an anchor. |
+
+Also takes: every `<a>` attribute.
+
+### `BreadcrumbList`
+
+Also takes: every `<ol>` attribute.
+
+### `BreadcrumbPage`
+
+The leaf. Not a link, because it points at where you already are: `aria-current="page"` on plain text, not a link that refuses to be followed.
+
+Also takes: every `<span>` attribute.
+
+### `BreadcrumbSeparator`
+
+`/` rather than a chevron; pass children for a different mark.
+
+Also takes: every `<li>` attribute.
+
+## Sidebar
+
+`import { Sidebar, SidebarContent, SidebarFooter, SidebarGroup, SidebarGroupAction, SidebarGroupContent, SidebarGroupLabel, SidebarHeader, SidebarInput, SidebarInset, SidebarMenu, SidebarMenuAction, SidebarMenuBadge, SidebarMenuButton, SidebarMenuItem, SidebarMenuSkeleton, SidebarMenuSub, SidebarMenuSubButton, SidebarMenuSubItem, SidebarProvider, SidebarRail, SidebarSeparator, SidebarTrigger, SidebarState, useSidebar, sidebarMenuButtonVariants } from '@jovertical/mise-design-system'`
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `side` | `'left' \| 'right'` | `'left'` |  |
+| `variant` | `'sidebar' \| 'floating' \| 'inset'` | `'sidebar'` |  |
+| `collapsible` | `'offcanvas' \| 'icon' \| 'none'` | `'offcanvas'` |  |
+| `sidetheme` | `'primary' \| 'light' \| 'panel'` | `'primary'` |  |
+
+Also takes: every `<div>` attribute.
+
+### `SidebarContent`
+
+Scrolls vertically in icon mode too: a long rail must not lose its last icons off the viewport.
+
+Also takes: every `<div>` attribute.
+
+### `SidebarFooter`
+
+Also takes: every `<div>` attribute.
+
+### `SidebarGroup`
+
+Also takes: every `<div>` attribute.
+
+### `SidebarGroupAction`
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `child` | `Snippet<[{ props: Record<string, unknown> }]>` |  | Renders your own element with these props instead of the default one. |
+
+Also takes: every `<button>` attribute.
+
+### `SidebarGroupContent`
+
+Also takes: every `<div>` attribute.
+
+### `SidebarGroupLabel`
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `child` | `Snippet<[{ props: Record<string, unknown> }]>` |  | Renders your own element with these props instead of the default one. |
+
+Also takes: every `<div>` attribute.
+
+### `SidebarHeader`
+
+Also takes: every `<div>` attribute.
+
+### `SidebarInput`
+
+Also takes: everything `Input` takes.
+
+### `SidebarInset`
+
+Also takes: every HTML attribute.
+
+### `SidebarMenu`
+
+Also takes: every `<ul>` attribute.
+
+### `SidebarMenuAction`
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `child` | `Snippet<[{ props: Record<string, unknown> }]>` |  | Renders your own element with these props instead of the default one. |
+| `showOnHover` | `boolean` | `false` | Shows the action only while its row is hovered or focused, from `md`. |
+
+Also takes: every `<button>` attribute.
+
+### `SidebarMenuBadge`
+
+Also takes: every `<div>` attribute.
+
+### `SidebarMenuButton`
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `child` | `Snippet<[{ props: Record<string, unknown> }]>` |  |  |
+| `isActive` | `boolean` | `false` |  |
+| `size` | `'default' \| 'sm' \| 'lg'` | `'default'` |  |
+| `noHover` | `boolean` | `false` | Keeps the button flat: no hover or active background, as for a logo. |
+| `tooltip` | `string \| Snippet` |  | Shown beside the button while the sidebar is collapsed to icons, on desktop. |
+| `tooltipContentProps` | `Omit<TooltipContentProps, 'children'>` |  |  |
+
+Also takes: every `<button>` attribute.
+
+### `SidebarMenuItem`
+
+Also takes: every `<li>` attribute.
+
+### `SidebarMenuSkeleton`
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `showIcon` | `boolean` | `false` |  |
+
+Also takes: every `<div>` attribute.
+
+### `SidebarMenuSub`
+
+Also takes: every `<ul>` attribute.
+
+### `SidebarMenuSubButton`
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `child` | `Snippet<[{ props: Record<string, unknown> }]>` |  | Renders your own element with these props instead of the default one. |
+| `size` | `'sm' \| 'md'` | `'md'` |  |
+| `isActive` | `boolean` | `false` |  |
+
+Also takes: every `<a>` attribute.
+
+### `SidebarMenuSubItem`
+
+Also takes: every `<li>` attribute.
+
+### `SidebarProvider`
+
+Owns the open and collapsed state and the CSS variables the whole family reads. It always wraps `Sidebar` and its page, never `Sidebar` alone.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `open` | `boolean` | `true` |  |
+| `onOpenChange` | `(open: boolean) => void` |  |  |
+| `mobileBreakpoint` | `number` |  | Viewport width, in pixels, below which the sidebar becomes a sheet. Raise it when the persistent rail costs the content more room than it is worth. |
+
+Also takes: every `<div>` attribute.
+
+### `SidebarRail`
+
+Also takes: every `<button>` attribute.
+
+### `SidebarSeparator`
+
+Also takes: everything `Separator` takes.
+
+### `SidebarTrigger`
+
+Also takes: everything `Button` takes.
+
+Also exports: `SidebarState`, `useSidebar`, `sidebarMenuButtonVariants`.
+
+Types: `SidebarSideTheme` (`'primary' | 'light' | 'panel'`), `SidebarMenuButtonSize` (`'default' | 'sm' | 'lg'`).
+
+## Stepper
+
+`import { Stepper, StepperNavigation } from '@jovertical/mise-design-system'`
+
+Where a reader is in a multi-step flow, and what is behind them.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `steps` (required) | `StepDefinition[]` |  |  |
+| `currentStepId` (required) | `string` |  |  |
+| `completedSteps` | `readonly string[]` |  | Explicit completion. Any step id here is complete regardless of its position; when omitted, every step before `currentStepId` is. |
+| `variant` | `'vertical' \| 'horizontal' \| 'condensed' \| 'compact'` | `'vertical'` |  |
+| `showProgress` | `boolean` | `true` | Drops the "Step 3 of 9" readout and the bar from `compact`, for a flow that no longer holds anyone to an order. A bar that never moves is a worse answer than none. |
+| `showCurrentStep` | `boolean` | `true` | Drops the current step's name and description from `condensed`, for a page that heads its own step body and says it better. |
+| `onStepSelect` | `(stepId: string) => void` |  | Makes steps selectable. A stepper that reports progress and one that navigates look the same and are not; passing this turns the steps into buttons. |
+| `selectableSteps` | `readonly string[]` |  | Which step ids accept a click; omitted means all of them. A wizard can hold you to an order going forward while letting you back to anything already visited. |
+| `class` | `string` |  |  |
+
+### `StepperNavigation`
+
+A flow's controls, at the page's own level rather than inside its card.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `onBack` | `() => void` |  | Omit for the first step. The next action stays right regardless. |
+| `backLabel` | `string` | `'Back'` |  |
+| `backDisabled` | `boolean` | `false` |  |
+| `onNext` | `() => void` |  |  |
+| `nextLabel` | `string` | `'Next'` |  |
+| `nextDisabled` | `boolean` | `false` |  |
+| `nextLoading` | `boolean` | `false` | Draws a spinner in the next action. Pair it with `nextDisabled`. |
+| `leading` | `Snippet` |  | At the left end, beside the back action if there is one: anything that leaves the flow rather than moving through it (Cancel, "finish later"). Leaving and advancing are opposite intentions and belong at opposite ends. |
+| `trailing` | `Snippet` |  | Immediately left of the next action: a skip, which does advance. |
+
+Also takes: every `<div>` attribute except `children`.
+
+Types: `StepDefinition`, `StepperVariant` (`'vertical' | 'horizontal' | 'condensed' | 'compact'`).
+
+## Tabs
+
+`import { Tabs, TabsContent, TabsList, TabsTrigger } from '@jovertical/mise-design-system'`
+
+Also takes: bits-ui `Tabs.Root` props.
+
+### `TabsContent`
+
+Also takes: bits-ui `Tabs.Content` props.
+
+### `TabsList`
+
+Also takes: bits-ui `Tabs.List` props.
+
+### `TabsTrigger`
+
+Also takes: bits-ui `Tabs.Trigger` props.