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

package/skills/mise/components/feedback.md

@@ -0,0 +1,198 @@
+<!-- Generated by pnpm build:skill. Do not edit by hand. -->
+
+# Feedback
+
+## Alert
+
+`import { Alert, AlertAction, AlertDescription, AlertTitle, alertVariants } from '@jovertical/mise-design-system'`
+
+Status is the surface and the icon; the words stay in ink. Red body text reads as the message being an error rather than being about one. The layout has an icon column only when there is an icon, and a third column for `AlertAction` from `sm`.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `variant` | `'default' \| 'info' \| 'success' \| 'warning' \| 'destructive'` |  |  |
+
+Also takes: every `<div>` attribute.
+
+### `AlertAction`
+
+What the alert asks the reader to do: one button or a short row of them. On the right, centred across the title and description, from `sm`; below the text on a phone, where a third column would squeeze the sentence.
+
+Also takes: every `<div>` attribute.
+
+### `AlertDescription`
+
+A block rather than a grid: as a grid, an inline `<strong>` became its own row.
+
+Also takes: every `<div>` attribute.
+
+### `AlertTitle`
+
+One clamped line: anything that needs a second line belongs in the description.
+
+Also takes: every `<div>` attribute.
+
+Also exports: `alertVariants`.
+
+Types: `AlertVariant` (`'default' | 'info' | 'success' | 'warning' | 'destructive'`).
+
+## Empty
+
+`import { Empty, EmptyContent, EmptyDescription, EmptyHeader, EmptyMedia, EmptyTitle, emptyMediaVariants } from '@jovertical/mise-design-system'`
+
+A dashed panel for nothing-here-yet. `border` as well as `border-dashed`: Tailwind's `border-dashed` sets only the style, so without a width the panel drew no edge at all.
+
+Also takes: every `<div>` attribute.
+
+### `EmptyContent`
+
+Also takes: every `<div>` attribute.
+
+### `EmptyDescription`
+
+Also takes: every `<div>` attribute.
+
+### `EmptyHeader`
+
+Also takes: every `<div>` attribute.
+
+### `EmptyMedia`
+
+`icon` is a ringed circle on the page's own surface rather than a filled square: a frame around the glyph, which keeps a large empty panel from looking like a broken card.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `variant` | `'default' \| 'icon'` | `'default'` |  |
+
+Also takes: every `<div>` attribute.
+
+### `EmptyTitle`
+
+Also takes: every `<div>` attribute.
+
+Also exports: `emptyMediaVariants`.
+
+Types: `EmptyMediaVariant` (`'default' | 'icon'`).
+
+## EmptyState
+
+`import { EmptyState } from '@jovertical/mise-design-system'`
+
+The default "nothing here yet" panel, for a list that came back empty when the screen has nothing more specific to say. `Empty` and its parts stay exported for the cases that do. The fallback wording is honest anywhere, which is also the signal that a screen has not been given its own.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `icon` (required) | `Snippet` |  | Rendered in `EmptyMedia`'s icon chip. |
+| `title` | `string` |  |  |
+| `description` | `string` |  |  |
+| `actions` | `Snippet` |  | Buttons offering a way out of the empty state, laid out in a row. |
+| `class` | `string` |  |  |
+
+## ErrorState
+
+`import { ErrorState } from '@jovertical/mise-design-system'`
+
+The full-page stop: not found, forbidden, or something that threw.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `status` | `number` |  | HTTP status, above the title. Omit it and nothing is shown. |
+| `title` (required) | `string` |  |  |
+| `description` (required) | `string` |  |  |
+| `icon` | `Snippet` |  | A glyph above the title. Most error pages read better without one: the sentence already says what happened. |
+| `homeLink` | `Snippet` |  | The way home: a `Button` with `href`, or the router's link styled as one. |
+| `showBackButton` | `boolean` | `false` | A `history.back()` button ahead of `homeLink`. Off by default: one obvious way forward is easier to act on, and Back is right only when the reader arrived by navigating rather than by URL. |
+| `actions` | `Snippet` |  | Extra buttons, ahead of Back and Home: Try again, for a thrown error. |
+
+Also takes: every `<div>` attribute except `title`, `children`.
+
+## FeaturePreview
+
+`import { FeaturePreview } from '@jovertical/mise-design-system'`
+
+The page a reader lands on when a feature is not open to them yet, in place of an error, so a locked page still says what it would do and how to get it.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `title` (required) | `string` |  | The feature's name, as the page would title it: "Purchase orders". |
+| `headline` (required) | `string` |  | What the feature does, in one line. |
+| `benefits` (required) | `readonly string[]` |  | Two or three concrete benefits. More turns the pitch into a manual. |
+| `preview` (required) | `Snippet` |  | A static sample of the real screen, from made-up data, laid out as the page would be. Blurred, inert and hidden from assistive technology: a picture of the feature, never a working copy. |
+| `primaryAction` (required) | `Snippet` |  | The way in: "Turn on purchase orders". |
+| `secondaryAction` | `Snippet` |  | Usually "Learn more". |
+
+Also takes: every HTML attribute except `title`, `children`.
+
+## LoadingState
+
+`import { LoadingState } from '@jovertical/mise-design-system'`
+
+The panel that says work is under way, when the shape of what is coming is not known yet. The mirror of `EmptyState`, on the same `Empty` parts, so a list that flips from loading to empty does not move; the border is solid because something is coming. Reach for it last: where the layout is known, a `Skeleton` holds it.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `title` | `string` |  |  |
+| `description` | `string` |  |  |
+| `actions` | `Snippet` |  | Something to do instead of waiting, usually "Continue in background". |
+| `class` | `string` |  |  |
+
+## LockedOverlay
+
+`import { LockedOverlay } from '@jovertical/mise-design-system'`
+
+A lock over one card's body, for a widget the reader cannot open while the rest of the page works. The card keeps its frame and header; only the body is swapped for a blurred sample with the pitch on top.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `title` (required) | `string` |  | What is locked, as the pitch's heading. |
+| `message` (required) | `string` |  | One line saying what the locked content would show. |
+| `action` (required) | `Snippet` |  | The way in: "Ask for access", "Finish setup". |
+| `children` (required) | `Snippet` |  | Sample content in the shape of the real thing. Blurred, inert and hidden from assistive technology, so its made-up figures are never read as the reader's own. |
+
+Also takes: every `<div>` attribute except `title`, `children`.
+
+## NavigationProgress
+
+`import { NavigationProgress } from '@jovertical/mise-design-system'`
+
+The navigation progress bar across the top of the viewport.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `pending` (required) | `boolean` |  | Whether a navigation is in flight. Rising shows the bar and runs it to the peak; falling runs it to full width and hides it. The router stays in the app: Inertia's start and finish events, or SvelteKit's `navigating`. |
+
+## Progress
+
+`import { Progress } from '@jovertical/mise-design-system'`
+
+The bare bar. `MetricBar` and `MetricRow` colour it through `TONE_INDICATOR_CLASS`; reach for `Progress` directly when there is no label or figure beside it. An unknown `value` draws an empty bar, not an animated indeterminate one: the copy beside it carries "this is running".
+
+Also takes: bits-ui `Progress.Root` props except `children`, `child`.
+
+## Skeleton
+
+`import { Skeleton } from '@jovertical/mise-design-system'`
+
+Shaped to what it stands in for: there is no default size. Reach for it where a component has not already drawn its own loading shape.
+
+Also takes: every `<div>` attribute.
+
+## Toaster
+
+`import { Toaster, toast } from '@jovertical/mise-design-system'`
+
+Also takes: `svelte-sonner` `ToasterProps`.
+
+Also exports: `toast`.
+
+## Spinner
+
+`import { Spinner } from '@jovertical/mise-design-system'`
+
+`role="status"` and an `aria-label`, unlike a hand-spun icon: reach for this rather than a spinning loader glyph, which is silent to a screen reader.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `children` | `Snippet` |  | A short sentence naming what is being waited on. |
+
+Also takes: `svelte` `ComponentProps`.