@nanisoft/prism-llms 0.4.0 → 0.5.1

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.

package/dist/md/components/textarea.md

@@ -0,0 +1,101 @@
+# Textarea
+
+The multi-line text control for a form.
+
+```tsx
+import { Textarea } from '@nanisoft/prism-ui/components/textarea'
+```
+
+## Overview
+
+A Textarea is the multi-line text control. It renders a native `<textarea>` with
+a minimum height and a resize grip, so a reader can see more than one line of
+what they have written.
+
+It shares the Input's focus treatment: a full-strength ring on focus and a
+destructive border and ring when the control is marked with `aria-invalid`. The
+height follows the content where the browser supports field sizing, and `rows`
+remains the fallback.
+
+## Guidelines
+
+### When to use
+
+Use a Textarea for free-form text that runs past a line: a note, a comment, a
+bio, a support message, a release description.
+
+Pair it with a Field label and a helper line, and set `rows` to a height that
+shows the expected answer rather than one line.
+
+### When not to use
+
+Do not use a Textarea for a single-line value. A name or a search term does not
+need a resize grip.
+
+Do not use one for structured data the product can model as separate fields. If
+the parts have names, they deserve their own controls and validation.
+
+Do not use a Textarea for rich text. Formatting, links and embeds need an
+editor the design system does not ship.
+
+### Best practices
+
+- Set a minimum height that matches the expected answer. A box that shows one
+  line suggests the answer is one line.
+- Keep the label above the control and the helper line below it, exactly as an
+  Input does, so a form reads as one pattern.
+- Leave the resize grip available. Readers with motor or vision differences
+  often size the box to the draft they are writing.
+- Show the current and maximum length next to the field when there is a limit,
+  and count down rather than up so the remaining space is obvious.
+- Mark a failed field with `aria-invalid` and put the reason in a FieldError.
+  The border is not the message.
+
+### Content guidelines
+
+- A helper line may state the limit or the format: "Up to 500 characters",
+  "Plain text only".
+- A placeholder may sketch the expected answer, and should be shorter than the
+  label it sits under.
+- Do not repeat the label inside the placeholder. The two are read together by
+  a screen reader.
+
+**A textarea with a label and helper line, plus a disabled one.**
+
+```tsx
+import {
+  Field,
+  FieldDescription,
+  FieldLabel,
+} from '@nanisoft/prism-ui/components/field'
+import { Textarea } from '@nanisoft/prism-ui/components/textarea'
+
+/** A textarea with a label and helper line, plus a disabled one. */
+export default function TextareaDemo() {
+  return (
+    <div className="flex max-w-measure-narrow flex-col gap-4">
+      <Field>
+        <FieldLabel htmlFor="textarea-note">Release note</FieldLabel>
+        <Textarea
+          id="textarea-note"
+          rows={4}
+          placeholder="What changed, and who it affects."
+        />
+        <FieldDescription>Plain text. Markdown is added later.</FieldDescription>
+      </Field>
+      <Field>
+        <FieldLabel htmlFor="textarea-summary">Generated summary</FieldLabel>
+        <Textarea
+          id="textarea-summary"
+          defaultValue="Written by the pipeline."
+          disabled
+        />
+      </Field>
+    </div>
+  )
+}
+```
+
+## Props
+
+> Extends: the native `<textarea>` element. No additional Prism-specific props.

package/dist/md/components/tooltip.md

@@ -1,14 +1,102 @@
 # Tooltip
 
-antd Tooltip, unchanged — a pass-through re-export. Import from '@nanisoft/prism-ui'.
+The short label shown on hover or focus beside a control.
 
-```ts
-import { Tooltip } from '@nanisoft/prism-ui/components';
+```tsx
+import { Tooltip, TooltipTrigger, TooltipContent } from '@nanisoft/prism-ui/components/tooltip'
 ```
 
-`Tooltip` is antd's [Tooltip](https://ant.design/components/tooltip), re-exported unchanged.
+## Overview
 
-- Extends: antd **Tooltip** — for inherited props and demos, use the antd MCP (`antd_info Tooltip`).
-- Always import from '@nanisoft/prism-ui', never from `antd` directly.
+A Tooltip is a short label that appears on hover or focus beside the control it
+explains. It ships as `Tooltip`, `TooltipTrigger` and `TooltipContent`, all from
+the same module. The trigger stays focusable, and the tooltip opens on keyboard
+focus as well as on hover, so it is not a mouse-only affordance.
 
-_No additional props beyond the antd base component._
+The content is positioned by the library and flips when there is no room on the
+chosen side. Escape dismisses it. Because it is unavailable on touch, a tooltip
+never carries the only copy of information a reader needs.
+
+## Guidelines
+
+### When to use
+
+Use a Tooltip to name or briefly explain a control that is already visible: an
+icon-only button, an abbreviated label, or a term a reader may not know.
+
+### When not to use
+
+Do not put essential content in a Tooltip. Keyboard and pointer users can reach
+it, but touch users cannot, so anything required belongs in visible text.
+
+Do not use a Tooltip for a form field's validation message. Errors need to be
+persistent and programmatically tied to the field; a tooltip disappears.
+
+Do not use one for rich content such as a form or a menu. That is a Popover.
+
+### Best practices
+
+- Keep the content to a short phrase. A sentence is the ceiling; a paragraph
+  belongs in a Popover or on the page.
+- Attach the Tooltip to a focusable trigger. A tooltip on a plain span is
+  unreachable by keyboard.
+- Give an icon-only trigger an `aria-label` as well. The tooltip is visual help;
+  the accessible name must stand on its own.
+- Choose a side that does not cover the content the reader is looking at, and
+  let the library flip it near an edge.
+- Do not nest interactive content in a Tooltip. It opens on focus and closes on
+  blur, so anything inside it is hard to reach.
+
+### Content guidelines
+
+- Write a noun phrase or one short sentence that adds information, not a repeat
+  of the trigger's label.
+- Use sentence case and no closing period on a fragment; use one on a full
+  sentence.
+- Never make the tooltip the first place a key term appears. Explain the term
+  where it is introduced, and let the tooltip remind.
+
+**Tooltips on a text trigger and on an icon-only control.**
+
+```tsx
+'use client'
+
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipTrigger,
+} from '@nanisoft/prism-ui/components/tooltip'
+
+/** Tooltips on a text trigger and on an icon-only control. */
+export default function TooltipDemo() {
+  return (
+    <div className="flex flex-wrap items-center gap-8 text-sm">
+      <Tooltip>
+        <TooltipTrigger className="underline decoration-dotted underline-offset-4">
+          Beta feature
+        </TooltipTrigger>
+        <TooltipContent>Not covered by the uptime target.</TooltipContent>
+      </Tooltip>
+      <Tooltip>
+        <TooltipTrigger aria-label="Copy link" className="font-medium">
+          Copy link
+        </TooltipTrigger>
+        <TooltipContent side="bottom">Copies the current page URL.</TooltipContent>
+      </Tooltip>
+    </div>
+  )
+}
+```
+
+## Props
+
+**`open`** `boolean` · optional · default: — — The controlled open state.
+**`defaultOpen`** `boolean` · optional · default: — — The initially open state, for an uncontrolled tooltip.
+**`onOpenChange`** `(open: boolean) => void` · optional · default: — — Called when the open state changes.
+**`disabled`** `boolean` · optional · default: — — Whether the tooltip is disabled.
+**`children`** `React.ReactNode` · optional · default: — — The trigger and content.
+**`delay`** `number` · optional · default: `600` — How long to wait before opening on hover, in milliseconds.
+**`closeDelay`** `number` · optional · default: `0` — How long to wait before closing, in milliseconds.
+**`side`** `'top' | 'right' | 'bottom' | 'left'` · optional · default: `top` — Which side of the trigger the tooltip is placed on.
+**`align`** `'start' | 'center' | 'end'` · optional · default: `center` — How the tooltip aligns against the trigger.
+**`sideOffset`** `number` · optional · default: `4` — The distance in pixels between the trigger and the tooltip.

package/dist/md/components/typography.md

@@ -1,14 +1,89 @@
 # Typography
 
-antd Typography, unchanged — a pass-through re-export. Import from '@nanisoft/prism-ui'.
+The text and heading components that apply the type scale.
 
-```ts
-import { Typography } from '@nanisoft/prism-ui/components';
+```tsx
+import { Text, Heading } from '@nanisoft/prism-ui/components/typography'
 ```
 
-`Typography` is antd's [Typography](https://ant.design/components/typography), re-exported unchanged.
+## Overview
 
-- Extends: antd **Typography** — for inherited props and demos, use the antd MCP (`antd_info Typography`).
-- Always import from '@nanisoft/prism-ui', never from `antd` directly.
+Typography is the pair of text exports that apply the type scale. `Heading`
+renders a document heading and `Text` renders a run of body copy, both from the
+same module.
 
-_No additional props beyond the antd base component._
+`Heading` separates the element from the visual step. The `as` prop chooses the
+outline, and `size` chooses the scale, so a section that needs an `h2` attuned
+to a compact card keeps the outline while taking a smaller visual size. `Text`
+offers `size` and a `tone`, where `tone="muted"` is the supporting copy that
+sits beside a heading.
+
+## Guidelines
+
+### When to use
+
+Use `Heading` and `Text` for long-form content and documentation, where the
+outline and the scale are the structure the reader navigates by.
+
+Use the `as` and `size` split when a heading's place in the outline and its
+visual weight are not the same decision.
+
+### When not to use
+
+Do not use Typography for a control label or a card title. Components such as
+Button and CardTitle own their own text treatment, and restyling them from the
+outside is the override the system forbids.
+
+Do not use `Heading` to make text bigger. A paragraph that is important is still
+a paragraph; emphasis comes from placement and copy.
+
+Do not use Typography to fix spacing. Rhythm comes from the container, not from
+a text size chosen to close a gap.
+
+### Best practices
+
+- Choose `as` by the document outline and `size` by the layout. One page has one
+  `h1`, and the levels below it never skip a step.
+- Let `Heading` default to `h2`. A block or an article body is composed under a
+  page heading, so the surrounding document already owns the top level.
+- Keep a prose measure near the container token. A line that runs the full
+  window is hard to track back to its start.
+- Use `tone="muted"` for supporting copy and keep it to a sentence or two. If
+  the muted text carries the point, promote it.
+- Keep headings in sentence case and leave the full stop off. A heading is a
+  label, not a sentence.
+- Do not scale text with `className`. Size is a token decision, and a one-off
+  value breaks the scale for the next reader.
+
+**The scale: a display heading, a subheading and both text tones.**
+
+```tsx
+import {
+  Heading,
+  Text,
+} from '@nanisoft/prism-ui/components/typography'
+
+/** The scale: a display heading, a subheading and both text tones. */
+export default function TypographyDemo() {
+  return (
+    <div className="flex max-w-measure flex-col gap-3">
+      <Heading as="h3" size="3xl">
+        Release notes
+      </Heading>
+      <Text tone="muted">What shipped in the last two weeks, in reading order.</Text>
+      <Heading as="h4" size="xl">
+        Fixes
+      </Heading>
+      <Text>Three defects in the table toolbar and one in the theme switcher.</Text>
+      <Text as="span" size="sm" tone="muted">
+        Updated 12 August.
+      </Text>
+    </div>
+  )
+}
+```
+
+## Props
+
+**`size`** `"sm" | "lg" | "base" | null | undefined` · optional · default: —
+**`tone`** `"default" | "muted" | null | undefined` · optional · default: —

package/dist/md/content/about-content.md

@@ -0,0 +1,36 @@
+# About content
+
+What "content" means at NaniSoft, and the scope of this section.
+
+Content is the information in a user interface that works alongside the visual
+design. It includes every string a person reads inside a product: labels,
+headings, helper text, button text, empty states, error messages, tooltips,
+notifications and confirmation dialogs.
+
+RULE: Content is product text. It is not marketing copy, and it does not live on
+this documentation site.
+
+## Who this section is for
+
+This section is for anyone at NaniSoft who writes text a customer will read:
+designers writing labels, engineers writing empty states and errors, product
+managers writing release notes, and support staff writing help text.
+
+RULE: Anyone who writes product copy MUST follow this section. It applies to
+first drafts as much as to reviews.
+
+## What this section is not
+
+This section is not a style guide for source code, commit messages or internal
+documents. Those have their own conventions. It is also not the design system's
+vocabulary; that is the [Glossary](/content/glossary).
+
+## The register
+
+RULE: This section MUST use RFC 2119 keywords (MUST, SHOULD, MAY) so a rule can
+be read unambiguously, and it MUST prefix each rule line with `RULE:` so the
+rules are machine-greppable.
+
+Outside this section, Prism write in plain language and avoid those keywords.
+The difference is deliberate: a rule that a reader must follow is stated as a
+rule, and everything else is explanation.

package/dist/md/content/audience.md

@@ -0,0 +1,43 @@
+# Audience
+
+The three people NaniSoft product copy serves, and what each one needs from a sentence.
+
+Product copy serves three audiences. A piece of text MUST land for the person who
+reads it in that moment, and the three do not always want the same thing.
+
+## The operator
+
+The operator uses the product to finish a job, often repeatedly. They know the
+interface and resent being told what they already know, but they need
+confirmation that a consequential action will do what they expect.
+
+- They read errors, confirmations and destructive-action warnings closely.
+- They skip onboarding and explanation.
+- RULE: For the operator, be brief and specific. State the consequence, not the
+  mechanism.
+
+## The evaluator
+
+The evaluator is deciding whether the product does what they need. They meet the
+product once, with a task in mind, and they are quick to leave.
+
+- They read empty states, first-run text and headings.
+- They need the next step to be obvious.
+- RULE: For the evaluator, name the outcome and give exactly one clear next
+  action.
+
+## The builder
+
+The builder integrates NaniSoft into something they own. They read documentation
+more than product copy, but the two meet in import errors, configuration screens
+and generated code.
+
+- They need exact names: packs, tokens, props and package paths.
+- They are unforgiving of a label that does not match the API.
+- RULE: For the builder, use the exact, cased term from the glossary. Do not
+  paraphrase a name of anything.
+
+## Reading level
+
+RULE: Write for a general professional audience. Prefer common words, active
+voice and a single idea per sentence.