@nanisoft/prism-llms 0.3.0 → 0.5.0

package/dist/md/components/separator.md

@@ -0,0 +1,77 @@
+# Separator
+
+A hairline rule that divides content, horizontally or vertically.
+
+```tsx
+import { Separator } from '@nanisoft/prism-ui/components/separator'
+```
+
+## Overview
+
+A Separator is a hairline rule that divides content. It renders a single
+`<div>` at either `horizontal` or `vertical` orientation, drawn with the border
+token.
+
+The rule is decorative by default, so it is hidden from assistive technology and
+does not enter the reading order. Pass `decorative={false}` when the rule marks a
+real separation in a set of controls, such as between groups in a toolbar, and
+it becomes an ARIA separator with a matching orientation.
+
+## Guidelines
+
+### When to use
+
+Use a Separator to divide two groups of content in a stack, or two items inside
+a horizontal row such as a toolbar or a breadcrumb-style meta line.
+
+### When not to use
+
+Do not use a Separator where whitespace would do. A rule between two paragraphs
+adds ink without adding structure; space already separates them.
+
+Do not use one as a card border or a panel edge. A surface boundary is a border
+on the surface itself, not a rule placed beside it.
+
+Do not use a Separator as decoration. A rule that does not divide anything is
+noise the reader has to interpret.
+
+### Best practices
+
+- Keep the default `horizontal` orientation for stacked content and switch to
+  `vertical` only inside a row.
+- Give a vertical Separator a height through its parent. It fills the parent's
+  height, so a parent with no height collapses the rule to nothing.
+- Leave the rule decorative unless it marks a boundary a screen reader needs,
+  and pass `decorative={false}` only in that case.
+- Use one orientation per region. Mixing rules in a single stack reads as two
+  different structures.
+- Prefer the token's hairline and colour. A thicker or tinted rule is a second
+  visual language for the same job.
+
+**A horizontal rule between rows, and vertical rules inside one row.**
+
+```tsx
+import { Separator } from '@nanisoft/prism-ui/components/separator'
+
+/** A horizontal rule between rows, and vertical rules inside one row. */
+export default function SeparatorDemo() {
+  return (
+    <div className="flex max-w-measure flex-col gap-4">
+      <p className="text-muted-foreground text-sm">Account</p>
+      <Separator />
+      <p className="text-muted-foreground text-sm">Notifications</p>
+      <div className="flex h-5 items-center gap-4">
+        <span className="text-sm">Draft</span>
+        <Separator orientation="vertical" />
+        <span className="text-sm">Review</span>
+        <Separator orientation="vertical" />
+        <span className="text-sm">Published</span>
+      </div>
+    </div>
+  )
+}
+```
+
+## Props
+
+> Extends: the native `<div>` element. No additional Prism-specific props.

package/dist/md/components/skeleton.md

@@ -1,14 +1,78 @@
 # Skeleton
 
-antd Skeleton, unchanged — a pass-through re-export. Import from '@nanisoft/prism-ui'.
+A placeholder surface that mirrors the shape of content while it loads.
 
-```ts
-import { Skeleton } from '@nanisoft/prism-ui/components';
+```tsx
+import { Skeleton } from '@nanisoft/prism-ui/components/skeleton'
 ```
 
-`Skeleton` is antd's [Skeleton](https://ant.design/components/skeleton), re-exported unchanged.
+## Overview
 
-- Extends: antd **Skeleton** — for inherited props and demos, use the antd MCP (`antd_info Skeleton`).
-- Always import from '@nanisoft/prism-ui', never from `antd` directly.
+A Skeleton is a placeholder surface that mirrors the shape of content while it
+loads. It renders a single muted `<div>` whose size comes from `className`, so
+one component stands in for a title, a line of text, an avatar or an action.
 
-_No additional props beyond the antd base component._
+It ships without a shimmer on purpose. Prism authors no keyframes, so the
+placeholder is static and the shape, not a pulse, is what tells the reader that
+content is coming. The element is hidden from assistive technology, so a screen
+reader hears the finished content when it arrives rather than an empty box.
+
+## Guidelines
+
+### When to use
+
+Use a Skeleton when content is loading into a layout the reader already knows,
+such as a list, a card grid or a detail panel that reloads in place. The
+placeholder keeps the page from jumping when the content lands.
+
+### When not to use
+
+Do not use a Skeleton for work the reader has just started. A button that is
+submitting shows its own loading state; a placeholder elsewhere on the page
+implies a different region is loading.
+
+Do not use a Skeleton as a loading indicator for the whole application. A
+first paint with no known layout is better served by a spinner or a simple
+progress bar.
+
+Do not use one when the load is near instant. A placeholder that appears and
+disappears within a frame reads as a glitch.
+
+### Best practices
+
+- Match the final shape and size. A skeleton smaller than the content it
+  replaces causes a layout shift, which is the problem it exists to prevent.
+- Group the placeholders of one region into a single block, and mirror the real
+  structure: a title line, two body lines, an action.
+- Keep the surrounding layout identical to the loaded state, so only the content
+  changes.
+- Render the same number of placeholder rows as the content the layout will
+  hold. A grid that collapses from six boxes to two is a lie in both states.
+- Do not add a spinner inside a skeleton. One loading signal per region is
+  enough.
+- Keep the placeholder decorative. The live region around it, or the arriving
+  content, should carry the announcement.
+
+**A card-shaped placeholder: title, two body lines and an action.**
+
+```tsx
+import { Skeleton } from '@nanisoft/prism-ui/components/skeleton'
+
+/** A card-shaped placeholder: title, two body lines and an action. */
+export default function SkeletonDemo() {
+  return (
+    <div className="flex max-w-measure-narrow flex-col gap-4">
+      <Skeleton className="h-5 w-40" />
+      <div className="flex flex-col gap-2">
+        <Skeleton className="h-4 w-full" />
+        <Skeleton className="h-4 w-4/5" />
+      </div>
+      <Skeleton className="h-9 w-28" />
+    </div>
+  )
+}
+```
+
+## Props
+
+> Extends: the native `<div>` element. No additional Prism-specific props.

package/dist/md/components/slider.md

@@ -1,14 +1,97 @@
 # Slider
 
-antd Slider, unchanged — a pass-through re-export. Import from '@nanisoft/prism-ui'.
+The control that chooses a number along a range.
 
-```ts
-import { Slider } from '@nanisoft/prism-ui/components';
+```tsx
+import { Slider } from '@nanisoft/prism-ui/components/slider'
 ```
 
-`Slider` is antd's [Slider](https://ant.design/components/slider), re-exported unchanged.
+## Overview
 
-- Extends: antd **Slider** — for inherited props and demos, use the antd MCP (`antd_info Slider`).
-- Always import from '@nanisoft/prism-ui', never from `antd` directly.
+A Slider chooses a number along a range. It renders a styled track with a real
+range input beside it, so it is reachable by Tab and moved by the arrow keys,
+with Home and End jumping to the ends. The current value is exposed to assistive
+technology through the input's range semantics.
 
-_No additional props beyond the antd base component._
+Use the `min`, `max` and `step` props to describe the range, and give the
+control an `aria-label` or a visible label, because a slider with no name tells
+a screen reader nothing about what it changes.
+
+## Guidelines
+
+### When to use
+
+Use a Slider when the value is approximate and the reader benefits from seeing
+where it sits in a range: volume, opacity, a threshold, a size with a sensible
+middle.
+
+### When not to use
+
+Do not use a Slider when the exact number matters. An Input of type number lets
+the reader type or step to the value and is easier to make precise.
+
+Do not use one for a range with only two or three meaningful positions. A
+RadioGroup or a Select names each choice; a slider makes the reader hunt.
+
+Do not use a Slider for a value you cannot plot, such as a colour name. Pick the
+control that matches the kind of value.
+
+### Best practices
+
+- Pair the control with a visible label and an `aria-label`. The label names the
+  quantity; the value is read from the control.
+- Snap the range to meaningful steps. `step` should divide the span from `min`
+  to `max` evenly, so every reachable value is one the reader would want.
+- Show the current value near the slider when precision matters, and update it
+  as the value changes.
+- Set sensible `min` and `max` for the task. An unbounded slider invites values
+  the rest of the product cannot use.
+- Use the disabled state with a nearby reason, as with any other control.
+
+### Content guidelines
+
+- Name the quantity, not the control: "Opacity", "Export size".
+- Keep units out of the label when they can live in the value readout, and
+  include them in the readout when they are needed.
+- Avoid phrasing the label as a question. State the value being set.
+
+**Sliders for an adjustable value, a stepped value and a disabled one.**
+
+```tsx
+'use client'
+
+import { Slider } from '@nanisoft/prism-ui/components/slider'
+
+/** Sliders for an adjustable value, a stepped value and a disabled one. */
+export default function SliderDemo() {
+  return (
+    <div className="flex max-w-measure-narrow flex-col gap-8">
+      <div className="flex flex-col gap-3">
+        <p className="text-sm font-medium">Opacity</p>
+        <Slider defaultValue={75} aria-label="Opacity" />
+      </div>
+      <div className="flex flex-col gap-3">
+        <p className="text-sm font-medium">Export size</p>
+        <Slider defaultValue={40} aria-label="Export size" min={0} max={100} step={10} />
+      </div>
+      <div className="flex flex-col gap-3">
+        <p className="text-muted-foreground text-sm font-medium">Frame rate</p>
+        <Slider defaultValue={60} aria-label="Frame rate" disabled />
+      </div>
+    </div>
+  )
+}
+```
+
+## Props
+
+**`value`** `number` · optional · default: — — The current value, when the slider is controlled.
+**`defaultValue`** `number` · optional · default: — — The value the slider starts at, for an uncontrolled slider.
+**`min`** `number` · optional · default: `0` — The minimum allowed value.
+**`max`** `number` · optional · default: `100` — The maximum allowed value.
+**`step`** `number` · optional · default: `1` — The granularity the slider steps by.
+**`disabled`** `boolean` · optional · default: — — Whether the slider ignores user interaction.
+**`orientation`** `'horizontal' | 'vertical'` · optional · default: `horizontal` — The axis the slider moves along.
+**`name`** `string` · optional · default: — — The form field name submitted with the form.
+**`form`** `string` · optional · default: — — Identifies the form that owns the hidden input.
+**`onValueChange`** `(value: number) => void` · optional · default: — — Called as the value changes.

package/dist/md/components/switch.md

@@ -1,14 +1,111 @@
 # Switch
 
-antd Switch, unchanged — a pass-through re-export. Import from '@nanisoft/prism-ui'.
+The control that turns a setting on or off immediately.
 
-```ts
-import { Switch } from '@nanisoft/prism-ui/components';
+```tsx
+import { Switch } from '@nanisoft/prism-ui/components/switch'
 ```
 
-`Switch` is antd's [Switch](https://ant.design/components/switch), re-exported unchanged.
+## Overview
 
-- Extends: antd **Switch** — for inherited props and demos, use the antd MCP (`antd_info Switch`).
-- Always import from '@nanisoft/prism-ui', never from `antd` directly.
+A Switch turns a single setting on or off, and the change takes effect at once.
+It renders a styled track with a hidden native checkbox beside it, so it submits
+with a form while reading as a physical toggle. Space toggles the focused
+control, and its on and off states are announced to assistive technology.
 
-_No additional props beyond the antd base component._
+The difference from a Checkbox is timing, not shape. A Switch is a setting that
+is already in force; a Checkbox is a choice collected before a save.
+
+## Guidelines
+
+### When to use
+
+Use a Switch when flipping the control applies the change immediately and the
+reader expects no further step: enabling notifications, publishing a preview, or
+turning a feature on.
+
+### When not to use
+
+Do not use a Switch inside a form that still needs a Save action. If the change
+is pending a submit, a Checkbox is the honest control.
+
+Do not use one to choose between two named options, such as Light and Dark. That
+is a choice between values, and a RadioGroup or a Select names both.
+
+Do not use a Switch for an action that cannot be undone with the same control. A
+one-way action is a Button.
+
+### Best practices
+
+- Label the setting, not the state. The label describes what the switch
+  controls; the on and off positions are conveyed by the control itself.
+- Pair each Switch with a `FieldLabel` and `htmlFor`, and put the consequence in
+  an adjacent helper line rather than in the label.
+- For a change that affects a shared resource, confirm or offer an undo. An
+  immediate setting with wide effect is easy to flip by accident.
+- Keep the on state visually distinct beyond position alone, so the state is
+  legible to a reader who cannot rely on the thumb's movement.
+- Use `disabled` with a reason in reach, and prefer an explanatory line over a
+  silent greyed row.
+
+### Content guidelines
+
+- Write the label as the thing being controlled, in sentence case: "Release
+  notifications", "Preview builds".
+- Keep helper text to one sentence that states the effect, including who is
+  affected when it is shared.
+- Avoid "Enable" or "Turn on" in the label; the control already says that.
+
+**Switches that take effect immediately, one of them already on.**
+
+```tsx
+'use client'
+
+import { FieldLabel } from '@nanisoft/prism-ui/components/field'
+import { Switch } from '@nanisoft/prism-ui/components/switch'
+
+/** Switches that take effect immediately, one of them already on. */
+export default function SwitchDemo() {
+  return (
+    <div className="flex max-w-measure-narrow flex-col gap-5">
+      <div className="flex items-center justify-between gap-4">
+        <div className="flex flex-col gap-1">
+          <FieldLabel htmlFor="switch-notifications">Release notifications</FieldLabel>
+          <span className="text-muted-foreground text-sm">
+            A message when a new version is published.
+          </span>
+        </div>
+        <Switch id="switch-notifications" defaultChecked />
+      </div>
+      <div className="flex items-center justify-between gap-4">
+        <div className="flex flex-col gap-1">
+          <FieldLabel htmlFor="switch-preview">Preview builds</FieldLabel>
+          <span className="text-muted-foreground text-sm">
+            Build every pull request on the free plan.
+          </span>
+        </div>
+        <Switch id="switch-preview" />
+      </div>
+      <div className="flex items-center justify-between gap-4">
+        <FieldLabel htmlFor="switch-sso" className="text-muted-foreground">
+          Single sign-on
+        </FieldLabel>
+        <Switch id="switch-sso" disabled />
+      </div>
+    </div>
+  )
+}
+```
+
+## Props
+
+**`checked`** `boolean` · optional · default: — — The controlled active state.
+**`defaultChecked`** `boolean` · optional · default: — — The initially active state, for an uncontrolled switch.
+**`disabled`** `boolean` · optional · default: — — Whether the control ignores user interaction.
+**`readOnly`** `boolean` · optional · default: — — Whether the user may not change the state.
+**`required`** `boolean` · optional · default: — — Whether the state must be active before the form submits.
+**`name`** `string` · optional · default: — — The form field name submitted with the form.
+**`value`** `string` · optional · default: — — The value submitted when the switch is on.
+**`uncheckedValue`** `string` · optional · default: — — The value submitted when the switch is off.
+**`form`** `string` · optional · default: — — Identifies the form that owns the hidden input.
+**`onCheckedChange`** `(checked: boolean) => void` · optional · default: — — Called when the active state changes.

package/dist/md/components/table.md

@@ -1,14 +1,111 @@
 # Table
 
-antd Table, unchanged — a pass-through re-export. Import from '@nanisoft/prism-ui'.
+The semantic table components for rows, columns and captions.
 
-```ts
-import { Table } from '@nanisoft/prism-ui/components';
+```tsx
+import { Table, TableHeader, TableBody, TableFooter, TableRow, TableHead, TableCell, TableCaption } from '@nanisoft/prism-ui/components/table'
 ```
 
-`Table` is antd's [Table](https://ant.design/components/table), re-exported unchanged.
+## Overview
 
-- Extends: antd **Table** — for inherited props and demos, use the antd MCP (`antd_info Table`).
-- Always import from '@nanisoft/prism-ui', never from `antd` directly.
+A Table presents tabular data: records compared across named columns. It ships
+as `Table`, `TableHeader`, `TableBody`, `TableFooter`, `TableRow`, `TableHead`,
+`TableCell` and `TableCaption`, all from the same module.
 
-_No additional props beyond the antd base component._
+`Table` renders a real `<table>` inside a container that scrolls horizontally at
+narrow widths, so a wide set of columns stays reachable. `TableHeader`,
+`TableBody` and `TableFooter` map to `<thead>`, `<tbody>` and `<tfoot>`;
+`TableHead` is a `<th>` and `TableCell` is a `<td>`. `TableCaption` names the
+table for every reader, and it is read before the data.
+
+## Guidelines
+
+### When to use
+
+Use a Table when records share the same set of attributes and the reader needs
+to compare them down a column: invoices, members, deployments, line items.
+
+### When not to use
+
+Do not use a Table for page layout. It was a layout tool once, and every reader
+and crawler now interprets a table as data.
+
+Do not use one for a few key and value pairs. A description list states a record
+better than a table with two columns.
+
+Do not use a Table for a list where every row shows the same fields as prose.
+If there is nothing to compare across columns, a list is the honest unit.
+
+### Best practices
+
+- Name the table. Use `TableCaption` or an adjacent heading, and do not leave a
+  reader to infer the subject from the column labels.
+- Put the identifying column first, so a row is recognisable before it is read
+  across.
+- Align numbers to the right through `className` and text to the left. The
+  alignment is layout, which is the one use of `className` the system permits.
+- Keep cells terse. A paragraph in a cell is a row that has outgrown the table.
+- Use `TableFooter` for a total or a count, so the summary is part of the table
+  rather than a paragraph after it.
+- Add `scope="col"` to `TableHead` and `scope="row"` to a row header when a
+  control supplies it. The generated markup makes each cell identifiable.
+- Avoid horizontal scrolling where you can. A table that fits its container is
+  easier to read than one the reader has to drag.
+
+**A small invoices table with a header, a body and a footer total.**
+
+```tsx
+import {
+  Table,
+  TableBody,
+  TableCaption,
+  TableCell,
+  TableFooter,
+  TableHead,
+  TableHeader,
+  TableRow,
+} from '@nanisoft/prism-ui/components/table'
+
+/** A small invoices table with a header, a body and a footer total. */
+export default function TableDemo() {
+  return (
+    <Table>
+      <TableCaption>Invoices from the current quarter.</TableCaption>
+      <TableHeader>
+        <TableRow>
+          <TableHead>Invoice</TableHead>
+          <TableHead>Status</TableHead>
+          <TableHead className="text-right">Amount</TableHead>
+        </TableRow>
+      </TableHeader>
+      <TableBody>
+        <TableRow>
+          <TableCell className="font-medium">INV-001</TableCell>
+          <TableCell>Paid</TableCell>
+          <TableCell className="text-right">$250.00</TableCell>
+        </TableRow>
+        <TableRow>
+          <TableCell className="font-medium">INV-002</TableCell>
+          <TableCell>Pending</TableCell>
+          <TableCell className="text-right">$150.00</TableCell>
+        </TableRow>
+        <TableRow>
+          <TableCell className="font-medium">INV-003</TableCell>
+          <TableCell>Draft</TableCell>
+          <TableCell className="text-right">$350.00</TableCell>
+        </TableRow>
+      </TableBody>
+      <TableFooter>
+        <TableRow>
+          <TableCell colSpan={2}>Total</TableCell>
+          <TableCell className="text-right">$750.00</TableCell>
+        </TableRow>
+      </TableFooter>
+    </Table>
+  )
+}
+```
+
+## Props
+
+> Extends: the native `<table>` element. No additional Prism-specific props.

package/dist/md/components/tabs.md

@@ -1,14 +1,112 @@
 # Tabs
 
-antd Tabs, unchanged — a pass-through re-export. Import from '@nanisoft/prism-ui'.
+The set of peer views shown one at a time.
 
-```ts
-import { Tabs } from '@nanisoft/prism-ui/components';
+```tsx
+import { Tabs, TabsList, TabsTrigger, TabsContent } from '@nanisoft/prism-ui/components/tabs'
 ```
 
-`Tabs` is antd's [Tabs](https://ant.design/components/tabs), re-exported unchanged.
+## Overview
 
-- Extends: antd **Tabs** — for inherited props and demos, use the antd MCP (`antd_info Tabs`).
-- Always import from '@nanisoft/prism-ui', never from `antd` directly.
+Tabs show a set of peer views one at a time. It ships as `Tabs`, `TabsList`,
+`TabsTrigger` and `TabsContent`, all from the same module. Each trigger names a
+panel, and the matching panel shares the trigger's value.
 
-_No additional props beyond the antd base component._
+The tab list is a single Tab stop. Arrow keys move between triggers and show the
+matching panel, while Tab moves into the panel itself. The active trigger is
+marked with an active state, and the panel it controls is tied to it for
+assistive technology.
+
+## Guidelines
+
+### When to use
+
+Use Tabs to switch between views of the same subject when the reader only needs
+one at a time: overview and activity, code and preview, one setting group among
+several.
+
+### When not to use
+
+Do not use Tabs for steps in a process. Order matters there, and steps belong in
+a form or a wizard where progress is visible.
+
+Do not use Tabs to hide content that a reader needs to compare across panels.
+Side-by-side sections compare better than tabs.
+
+Do not use more tabs than fit on one line. If the list wraps, a Select or a
+sidebar section is the better control.
+
+### Best practices
+
+- Give every `TabsTrigger` a matching `TabsContent` with the same value, and
+  keep the order the same in both.
+- Choose a sensible default panel. The first tab is a fine default only if it is
+  the view most readers want.
+- Keep panel content structurally similar so switching does not move the
+  reader's place on the page.
+- On a narrow screen, let a long tab list scroll rather than wrap, and keep the
+  active tab in view.
+- Do not nest tabs inside tabs. One tab set per region keeps the keyboard model
+  predictable.
+
+### Content guidelines
+
+- Label tabs with a noun or a short noun phrase: "Overview", "Activity",
+  "Settings".
+- Use sentence case and no trailing periods.
+- Keep labels to one or two words so the row scans at a glance.
+- If a tab needs a count, keep it short and place it after the label, such as
+  "Activity 4".
+
+**Tabs that switch between three peer views of one subject.**
+
+```tsx
+'use client'
+
+import {
+  Tabs,
+  TabsContent,
+  TabsList,
+  TabsTrigger,
+} from '@nanisoft/prism-ui/components/tabs'
+
+/** Tabs that switch between three peer views of one subject. */
+export default function TabsDemo() {
+  return (
+    <Tabs defaultValue="overview" className="max-w-measure-narrow">
+      <TabsList>
+        <TabsTrigger value="overview">Overview</TabsTrigger>
+        <TabsTrigger value="activity">Activity</TabsTrigger>
+        <TabsTrigger value="settings">Settings</TabsTrigger>
+      </TabsList>
+      <TabsContent value="overview">
+        <p className="text-muted-foreground pt-2 text-sm">
+          Release 2.4 shipped three fixes and one new block, with no token
+          changes.
+        </p>
+      </TabsContent>
+      <TabsContent value="activity">
+        <p className="text-muted-foreground pt-2 text-sm">
+          Four deploys this week, all from the main branch.
+        </p>
+      </TabsContent>
+      <TabsContent value="settings">
+        <p className="text-muted-foreground pt-2 text-sm">
+          The workspace uses the Blush pack in light mode.
+        </p>
+      </TabsContent>
+    </Tabs>
+  )
+}
+```
+
+## Props
+
+**`value`** `string` · optional · default: — — The active panel's value, when the tabs are controlled.
+**`defaultValue`** `string` · optional · default: — — The panel shown initially, for uncontrolled tabs.
+**`onValueChange`** `(value: string) => void` · optional · default: — — Called when the active panel changes.
+**`orientation`** `'horizontal' | 'vertical'` · optional · default: `horizontal` — The direction the tab list flows.
+**`activateOnFocus`** `boolean` · optional · default: `false` — Whether arrow-key focus also activates the tab.
+**`loopFocus`** `boolean` · optional · default: `true` — Whether arrow keys wrap at the ends of the list.
+**`disabled`** `boolean` · optional · default: — — Whether the trigger ignores user interaction.
+**`keepMounted`** `boolean` · optional · default: `false` — Whether the panel stays in the DOM while hidden.