@nanisoft/prism-llms 0.4.0 → 0.5.1

package/dist/md/components/dropdown-menu.md

@@ -0,0 +1,125 @@
+# DropdownMenu
+
+The menu of actions and choices opened from one trigger.
+
+```tsx
+import { DropdownMenu, DropdownMenuTrigger, DropdownMenuContent, DropdownMenuItem, DropdownMenuCheckboxItem, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuLabel, DropdownMenuSeparator, DropdownMenuGroup, DropdownMenuSub, DropdownMenuSubTrigger, DropdownMenuSubContent } from '@nanisoft/prism-ui/components/dropdown-menu'
+```
+
+## Overview
+
+A DropdownMenu is a list of actions and choices opened from one trigger. It
+ships as `DropdownMenu`, `DropdownMenuTrigger`, `DropdownMenuContent`,
+`DropdownMenuItem`, `DropdownMenuCheckboxItem`, `DropdownMenuRadioItem`,
+`DropdownMenuLabel`, `DropdownMenuSeparator`, `DropdownMenuGroup`,
+`DropdownMenuSub`, `DropdownMenuSubTrigger` and `DropdownMenuSubContent`.
+
+The menu supports arrow-key navigation, typeahead by item label, Home and End,
+and Escape to close. A submenu opens from its trigger with the right arrow, and
+focus returns to the trigger when the menu closes.
+
+## Guidelines
+
+### When to use
+
+Use a DropdownMenu for a short list of commands attached to one control: a row's
+actions, an account menu, or a toolbar overflow. It keeps secondary actions out
+of the way without losing them.
+
+### When not to use
+
+Do not hide a primary action in a menu. If it is the main thing a view is for,
+keep it visible as a Button.
+
+Do not use a DropdownMenu for navigation between pages, and do not nest menus
+more than one level deep. Both cases want a page or a sidebar.
+
+### Best practices
+
+- Put a `DropdownMenuLabel` inside a `DropdownMenuGroup`. The label is tied to
+  its group, so it must have one.
+- Use `DropdownMenuCheckboxItem` for toggles that do not close the menu, so the
+  reader can change several in a row.
+- Put a destructive action last, after a `DropdownMenuSeparator`, with
+  `variant="destructive"`.
+- Keep items to a verb or a short noun phrase, and name the object when the
+  action is ambiguous: "Duplicate project" beats "Duplicate".
+- One level of `DropdownMenuSub` is the ceiling. Beyond that, promote the
+  commands to a page.
+
+### Content guidelines
+
+- Write items as imperative commands: "Duplicate", "Archive", "Sign out".
+- Use sentence case and no trailing periods.
+- Group related commands and label the group in sentence case, such as
+  "Account" or "Danger zone".
+
+**A menu with items, a checkbox item and a nested submenu.**
+
+```tsx
+'use client'
+
+import {
+  DropdownMenu,
+  DropdownMenuCheckboxItem,
+  DropdownMenuContent,
+  DropdownMenuGroup,
+  DropdownMenuItem,
+  DropdownMenuLabel,
+  DropdownMenuSeparator,
+  DropdownMenuSub,
+  DropdownMenuSubContent,
+  DropdownMenuSubTrigger,
+  DropdownMenuTrigger,
+} from '@nanisoft/prism-ui/components/dropdown-menu'
+
+/** A menu with items, a checkbox item and a nested submenu. */
+export default function DropdownMenuDemo() {
+  return (
+    <DropdownMenu>
+      <DropdownMenuTrigger>Open menu</DropdownMenuTrigger>
+      <DropdownMenuContent className="w-56">
+        <DropdownMenuGroup>
+          <DropdownMenuLabel>Account</DropdownMenuLabel>
+          <DropdownMenuItem>Profile</DropdownMenuItem>
+          <DropdownMenuItem>Settings</DropdownMenuItem>
+        </DropdownMenuGroup>
+        <DropdownMenuSeparator />
+        <DropdownMenuCheckboxItem defaultChecked>
+          Show archived rows
+        </DropdownMenuCheckboxItem>
+        <DropdownMenuSub>
+          <DropdownMenuSubTrigger>Invite</DropdownMenuSubTrigger>
+          <DropdownMenuSubContent>
+            <DropdownMenuItem>Send by email</DropdownMenuItem>
+            <DropdownMenuItem>Copy invite link</DropdownMenuItem>
+          </DropdownMenuSubContent>
+        </DropdownMenuSub>
+        <DropdownMenuSeparator />
+        <DropdownMenuItem variant="destructive">Sign out</DropdownMenuItem>
+      </DropdownMenuContent>
+    </DropdownMenu>
+  )
+}
+```
+
+## Props
+
+**`open`** `boolean` · optional · default: — — The controlled open state.
+**`defaultOpen`** `boolean` · optional · default: — — The initially open state, for an uncontrolled menu.
+**`onOpenChange`** `(open: boolean) => void` · optional · default: — — Called when the open state changes.
+**`disabled`** `boolean` · optional · default: — — Whether the menu ignores user interaction.
+**`children`** `React.ReactNode` · optional · default: — — The trigger and the menu content.
+**`side`** `'top' | 'right' | 'bottom' | 'left'` · optional · default: `bottom` — Which side of the trigger the menu is placed on.
+**`align`** `'start' | 'center' | 'end'` · optional · default: `start` — How the menu aligns against the trigger.
+**`sideOffset`** `number` · optional · default: `4` — The distance in pixels between the trigger and the menu.
+**`alignOffset`** `number` · optional · default: `0` — The offset in pixels along the alignment axis.
+**`inset`** `boolean` · optional · default: `false` — Whether the item aligns with the labels above it.
+**`variant`** `'default' | 'destructive'` · optional · default: `default` — Whether the item reads as a destructive action.
+**`closeOnClick`** `boolean` · optional · default: `true` — Whether the menu closes when the item is chosen.
+**`checked`** `boolean` · optional · default: — — The controlled ticked state.
+**`defaultChecked`** `boolean` · optional · default: — — The initially ticked state, for an uncontrolled item.
+**`onCheckedChange`** `(checked: boolean) => void` · optional · default: — — Called when the ticked state changes.
+**`value`** `string` · optional · default: — — The controlled value of the selected radio item.
+**`defaultValue`** `string` · optional · default: — — The initially selected value, for an uncontrolled group.
+**`onValueChange`** `(value: string) => void` · optional · default: — — Called when the selected value changes.

package/dist/md/components/fact-list.md

@@ -0,0 +1,85 @@
+# FactList
+
+A short list of named facts as a definition list, where a value may be a link and the term column stays aligned down its length.
+
+```tsx
+import { FactList } from '@nanisoft/prism-ui/components/fact-list'
+```
+
+## Overview
+
+A FactList is a short list of named facts: a term beside its value, in a column a
+reader can scan. It renders a real `<dl>`, so a screen reader announces the term
+before the value instead of reading a list of labels and then a list of answers.
+
+Every NaniSoft site states facts beside prose: what a plan costs, what a feed
+carries, which version a document describes, when a collector went live. Each one
+re-derived a `<dl>`, and each one got the alignment and the term-before-value
+wiring subtly wrong.
+
+## Guidelines
+
+### When to use
+
+Use a FactList for two to six facts that belong to one thing and are worth reading
+together: a release, a feed source, a plan, a deployment.
+
+Use it beside prose rather than inside it. A fact in the middle of a paragraph is
+a sentence, and a sentence is not a fact list.
+
+### When not to use
+
+Do not use a FactList for a table of records. That is `Table`, and a fact list of
+twenty rows is a table with its column headers removed.
+
+Do not use it for a set of links. That is a footer's column or a plain list, and a
+column of destinations is not a column of terms.
+
+Do not use it to compare products. A comparison has a row per product and a column
+per fact, and this is the other way round.
+
+### Best practices
+
+- Keep the label column short. The column is a fixed fraction so a list of facts
+  lines up down its whole length, and a label that wraps costs every other row its
+  alignment.
+- Give a fact an `href` only when the fact is kept somewhere else. A link to a fact
+  already on the page is a click that changes nothing.
+- Omit `label` when the list is already inside something that names it.
+- An empty list renders nothing, so a caller with nothing to state does not get a
+  bordered box with a title above it.
+
+### Content guidelines
+
+- Write a label as a name, not a question: "Last capture", not "When did it last
+  capture".
+- Keep a value to a word or a short phrase. A value that needs a sentence belongs
+  in a `NoteGrid01` row.
+- Write values as they would be read aloud, because that is how they are scanned.
+
+**Named facts, with one value that is a link and one that is a count.**
+
+```tsx
+import { FactList } from '@nanisoft/prism-ui/components/fact-list'
+
+/** Named facts, with one value that is a link and one that is a count. */
+export default function FactListDemo() {
+  return (
+    <FactList
+      label="Release"
+      facts={[
+        { label: 'Version', value: '0.5.1' },
+        { label: 'Package', value: '@nanisoft/prism-ui' },
+        { label: 'Axes', value: 'Two: pack and mode' },
+        { label: 'Changelog', value: 'Read it', href: '/changelogs/prism-ui' },
+      ]}
+    />
+  )
+}
+```
+
+## Props
+
+**`facts`** `readonly Fact[]` · required · default: — — The facts, in the order a reader should meet them. Order is the caller's because it is a claim about importance, and a list that sorted itself would be making that claim on the caller's behalf.
+**`label`** `ReactNode` · optional · default: — — A heading above the list, for a set of facts that needs to say what it is. Rendered as a `dt`-level caption rather than as a heading, so it does not compete with the document's own outline.
+**`className`** `string` · optional · default: — — Layout only, exactly as on every Component. Changing a Prism-owned visual property from here is prohibited.

package/dist/md/components/field.md

@@ -0,0 +1,116 @@
+# Field
+
+The labelled wrapper that pairs a form control with its label, description and error.
+
+```tsx
+import { Field, FieldLabel, FieldDescription, FieldError, FieldGroup } from '@nanisoft/prism-ui/components/field'
+```
+
+## Overview
+
+A Field pairs a form control with its label, its helper text and its error. It
+ships as `Field`, `FieldLabel`, `FieldDescription`, `FieldError` and
+`FieldGroup`, all from the same module.
+
+The parts are presentational, and the consumer owns the wiring. `FieldLabel`
+renders a native `<label>` and takes the control's `id` as `htmlFor`.
+`FieldDescription` and `FieldError` take an `id` that the control references
+through `aria-describedby`. Nothing generates an `id`, so a field stays a
+Server Component and the markup is settled before it reaches the browser.
+
+`FieldError` carries `role="alert"`, so it is announced when it appears. Render
+it only while the field is invalid, and mark the control itself with
+`aria-invalid` so the failure is visible as well as spoken.
+
+## Guidelines
+
+### When to use
+
+Use a Field around any form control that needs a visible label. Pair it with
+`Input`, `Textarea` or a future control that does not ship its own label.
+
+Use `FieldGroup` when several fields belong to one decision, such as an address
+or a notification preference, so the set reads as one block.
+
+### When not to use
+
+Do not use a Field as a layout grid. It controls label, control, helper and
+error order, not column placement; wrap fields in your own grid for that.
+
+Do not use `FieldDescription` as the only label. A placeholder or a hint is not
+an accessible name, and it disappears as soon as the reader types.
+
+Do not render `FieldError` alongside valid content. An error that is always
+present stops meaning anything.
+
+### Best practices
+
+- Put the label above the control. It survives zoom and translation better than
+  a label to the side.
+- Point `htmlFor` at the control's `id`, and keep those two values stable so the
+  label is programmatically attached rather than merely adjacent.
+- Reference both the description and the error from `aria-describedby`, and put
+  the error first when both are present.
+- Replace the helper text with the error while the field is invalid instead of
+  stacking both. The reader needs one instruction at a time.
+- Mark the control with `aria-invalid` and let the error sentence say what to do
+  next. The colour is a reinforcement, never the message.
+- Group related fields with `FieldGroup` and give the group a heading when it
+  helps a screen reader move through a long form.
+
+### Content guidelines
+
+- Start an error with what is wrong and how to fix it: "Enter an address in the
+  form name@example.com", not "Invalid input".
+- Keep a helper line to one sentence. A paragraph belongs above the field, not
+  under it.
+- Do not label a field with an instruction. "Email" is a name; "Enter your
+  email address to continue" is copy that belongs beside the control.
+
+**A group of fields: two valid controls and one showing an error.**
+
+```tsx
+import {
+  Field,
+  FieldDescription,
+  FieldError,
+  FieldGroup,
+  FieldLabel,
+} from '@nanisoft/prism-ui/components/field'
+import { Input } from '@nanisoft/prism-ui/components/input'
+import { Textarea } from '@nanisoft/prism-ui/components/textarea'
+
+/** A group of fields: two valid controls and one showing an error. */
+export default function FieldDemo() {
+  return (
+    <FieldGroup className="max-w-measure-narrow">
+      <Field>
+        <FieldLabel htmlFor="field-display-name">Display name</FieldLabel>
+        <Input id="field-display-name" defaultValue="Ada Lovelace" />
+        <FieldDescription>Shown on your profile and in mentions.</FieldDescription>
+      </Field>
+      <Field>
+        <FieldLabel htmlFor="field-bio">Bio</FieldLabel>
+        <Textarea id="field-bio" placeholder="A sentence about yourself." />
+      </Field>
+      <Field>
+        <FieldLabel htmlFor="field-email">Email</FieldLabel>
+        <Input
+          id="field-email"
+          type="email"
+          defaultValue="not-an-email"
+          aria-invalid
+          aria-describedby="field-email-error"
+        />
+        <FieldError id="field-email-error">
+          Enter an address in the form name@example.com.
+        </FieldError>
+      </Field>
+    </FieldGroup>
+  )
+}
+```
+
+## Props
+
+> Extends: the native `<div>` element. No additional Prism-specific props.

package/dist/md/components/input.md

@@ -1,14 +1,93 @@
 # Input
 
-antd Input, unchanged — a pass-through re-export. Import from '@nanisoft/prism-ui'.
+The single-line text control for a form.
 
-```ts
-import { Input } from '@nanisoft/prism-ui/components';
+```tsx
+import { Input } from '@nanisoft/prism-ui/components/input'
 ```
 
-`Input` is antd's [Input](https://ant.design/components/input), re-exported unchanged.
+## Overview
 
-- Extends: antd **Input** — for inherited props and demos, use the antd MCP (`antd_info Input`).
-- Always import from '@nanisoft/prism-ui', never from `antd` directly.
+An Input is the single-line text control. It renders a native `<input>`, so it
+submits, validates, autocompletes and takes focus without extra work, and it
+accepts every standard input type.
 
-_No additional props beyond the antd base component._
+The focus ring is drawn at full strength rather than at half alpha, so it clears
+the 3:1 non-text threshold on every surface. When the control is marked with
+`aria-invalid`, the border and the ring switch to the destructive token, which
+makes a failed field visible as well as announced.
+
+## Guidelines
+
+### When to use
+
+Use an Input for a short, single-line value: a name, an address, a search term,
+a quantity, a date or a password.
+
+Pair it with a Field so the control keeps a visible label, and pass the correct
+`type` so mobile keyboards and browser validation both do their job.
+
+### When not to use
+
+Do not use an Input for free-form text longer than a line. A Textarea gives the
+reader room to see what they have written.
+
+Do not use one for a choice between options. A radio group, a select or a
+switch states the options and their current state; a text box asks the reader to
+remember them.
+
+Do not use an Input as a display field for a value the reader cannot change.
+Render the value as text.
+
+### Best practices
+
+- Keep a visible label. A placeholder is a hint, not a name, and it vanishes on
+  the first keystroke.
+- Choose the `type` and `inputMode` that match the value, and set `autoComplete`
+  so the browser can fill it. Getting this right saves more effort than any
+  visual detail.
+- Show the error beside the field and mark the control with `aria-invalid`.
+  Colour alone never carries the failure.
+- Disable a control only when the reason is visible nearby. A disabled input
+  with no explanation is a dead end.
+- Keep the default height and radius. Size is a token decision, and a taller
+  input breaks alignment with every other control on the row.
+
+### Content guidelines
+
+- A placeholder may show the expected format, for example `name@example.com`,
+  and nothing more.
+- A helper line states the rule, not the field's name: "At least eight
+  characters", not "Password".
+- Do not write an error in the imperative twice. One instruction per message.
+
+**Input types at rest, disabled, and marked invalid.**
+
+```tsx
+import { Field, FieldLabel } from '@nanisoft/prism-ui/components/field'
+import { Input } from '@nanisoft/prism-ui/components/input'
+
+/** Input types at rest, disabled, and marked invalid. */
+export default function InputDemo() {
+  return (
+    <div className="flex max-w-measure-narrow flex-col gap-4">
+      <Field>
+        <FieldLabel htmlFor="input-email">Email</FieldLabel>
+        <Input id="input-email" type="email" placeholder="name@example.com" />
+      </Field>
+      <Field>
+        <FieldLabel htmlFor="input-workspace">Workspace</FieldLabel>
+        <Input id="input-workspace" defaultValue="Locked workspace" disabled />
+      </Field>
+      <Field>
+        <FieldLabel htmlFor="input-handle">Handle</FieldLabel>
+        <Input id="input-handle" defaultValue="with spaces" aria-invalid />
+      </Field>
+    </div>
+  )
+}
+```
+
+## Props
+
+> Extends: the native `<input>` element. No additional Prism-specific props.

package/dist/md/components/kbd.md

@@ -0,0 +1,77 @@
+# Kbd
+
+The inline label for a keyboard key or shortcut.
+
+```tsx
+import { Kbd } from '@nanisoft/prism-ui/components/kbd'
+```
+
+## Overview
+
+A Kbd is the inline label for a keyboard key or shortcut. It renders a native
+`<kbd>`, so assistive technology can identify it as input the reader types
+rather than as text to read.
+
+It sits inline with surrounding copy and takes its surface from the muted token.
+Shortcuts are written with one element per key, so `Ctrl` and `K` are two Kbd
+elements with a space between them.
+
+## Guidelines
+
+### When to use
+
+Use a Kbd when the reader must press a key to do something: a documented
+shortcut, a hint in a menu or a tooltip, or an onboarding step that names the
+keys.
+
+### When not to use
+
+Do not use a Kbd for a piece of code or a filename. Inline code already has its
+own treatment.
+
+Do not use one as a button label. A control that can be clicked shows a verb; a
+keyboard shortcut is an alternative, not the action.
+
+Do not use a Kbd for input the reader does not type, such as the name of a menu
+command.
+
+### Best practices
+
+- Use one Kbd per key. A single element holding the whole chord hides the
+  individual keys from anyone scanning or reading by element.
+- Name the modifier as the keyboard shows it and say which platform you assume.
+  There is no server-safe way to detect the reader's platform, so "Ctrl on
+  Windows and Linux, Cmd on macOS" is more honest than picking one.
+- Keep the hint inside a sentence that already states the action, so the keys
+  are never the only instruction.
+- Do not style a Kbd to look pressable. It reports a key, it does not receive a
+  press, and it is excluded from pointer events on purpose.
+- Keep the label to the key itself. Do not add the word "key" after it, because
+  the element already says what it is.
+
+**Shortcuts written with one element per key.**
+
+```tsx
+import { Kbd } from '@nanisoft/prism-ui/components/kbd'
+
+/** Shortcuts written with one element per key. */
+export default function KbdDemo() {
+  return (
+    <div className="flex flex-col gap-3 text-sm">
+      <p className="flex items-center gap-1.5">
+        Open the command menu <Kbd>Ctrl</Kbd> <Kbd>K</Kbd>
+      </p>
+      <p className="flex items-center gap-1.5">
+        Save the draft <Kbd>Ctrl</Kbd> <Kbd>S</Kbd>
+      </p>
+      <p className="flex items-center gap-1.5">
+        Close the dialog <Kbd>Esc</Kbd>
+      </p>
+    </div>
+  )
+}
+```
+
+## Props
+
+> Extends: the native `<kbd>` element. No additional Prism-specific props.

package/dist/md/components/pagination.md

@@ -1,14 +1,102 @@
 # Pagination
 
-antd Pagination, unchanged — a pass-through re-export. Import from '@nanisoft/prism-ui'.
+The control that moves between pages of a paged collection.
 
-```ts
-import { Pagination } from '@nanisoft/prism-ui/components';
+```tsx
+import { Pagination, PaginationContent, PaginationItem, PaginationLink, PaginationPrevious, PaginationNext, PaginationEllipsis } from '@nanisoft/prism-ui/components/pagination'
 ```
 
-`Pagination` is antd's [Pagination](https://ant.design/components/pagination), re-exported unchanged.
+## Overview
 
-- Extends: antd **Pagination** — for inherited props and demos, use the antd MCP (`antd_info Pagination`).
-- Always import from '@nanisoft/prism-ui', never from `antd` directly.
+A Pagination moves between the pages of a paged collection. It ships as a
+parent and six parts: `Pagination`, `PaginationContent`, `PaginationItem`,
+`PaginationLink`, `PaginationPrevious`, `PaginationNext` and
+`PaginationEllipsis`, all from the same module.
 
-_No additional props beyond the antd base component._
+`Pagination` is a labelled `<nav>`, and `PaginationContent` is a `<ul>` so the
+page numbers form one list for assistive technology. The current page is marked
+with `aria-current="page"`, the step controls carry their own accessible names,
+and the ellipsis is hidden from the accessibility tree because the links around
+it already name the range.
+
+## Guidelines
+
+### When to use
+
+Use a Pagination when a result set is longer than one screen and the total is
+known. The page a reader is on, and how many pages exist, are both part of the
+information the control carries.
+
+### When not to use
+
+Do not use it for a short list that fits on one page. A single page link is
+furniture around nothing.
+
+Do not use it as a step control in a wizard. A checkout or an onboarding flow
+has a fixed order and no page numbers, so a pair of previous and next buttons
+describes it better.
+
+Do not replace it with infinite scroll and no page numbers. A reader who cannot
+return to a position loses their place.
+
+### Best practices
+
+- Render the current page as a link with `isActive`, so it is announced with
+  `aria-current="page"` and stays consistent in the row.
+- Show a window of pages, not every page. Use `PaginationEllipsis` for the
+  hidden run and keep the first, last and neighbours visible.
+- Keep `PaginationPrevious` and `PaginationNext` at the ends of the row. On
+  narrow layouts their labels collapse to the chevron and the accessible name
+  stays complete.
+- Pass a real `href` on each link. A page of results is a location, so the link
+  should be right-clickable and openable in a new tab.
+- State the range near the control, for example "1 to 20 of 348". Page numbers
+  alone do not tell the reader how much remains.
+
+**A paged result set with the second page current.**
+
+```tsx
+import {
+  Pagination,
+  PaginationContent,
+  PaginationEllipsis,
+  PaginationItem,
+  PaginationLink,
+  PaginationNext,
+  PaginationPrevious,
+} from '@nanisoft/prism-ui/components/pagination'
+
+/** A paged result set with the second page current. */
+export default function PaginationDemo() {
+  return (
+    <Pagination>
+      <PaginationContent>
+        <PaginationItem>
+          <PaginationPrevious href="#" />
+        </PaginationItem>
+        <PaginationItem>
+          <PaginationLink href="#">1</PaginationLink>
+        </PaginationItem>
+        <PaginationItem>
+          <PaginationLink href="#" isActive>
+            2
+          </PaginationLink>
+        </PaginationItem>
+        <PaginationItem>
+          <PaginationLink href="#">3</PaginationLink>
+        </PaginationItem>
+        <PaginationItem>
+          <PaginationEllipsis />
+        </PaginationItem>
+        <PaginationItem>
+          <PaginationNext href="#" />
+        </PaginationItem>
+      </PaginationContent>
+    </Pagination>
+  )
+}
+```
+
+## Props
+
+> Extends: the native `<nav>` element. No additional Prism-specific props.