@nanisoft/prism-llms 0.3.0 → 0.5.0

package/dist/md/components/product-switcher.md

@@ -0,0 +1,88 @@
+# ProductSwitcher
+
+A switch between the members of a set of products, each drawn with its own ProductMark and the current one marked aria-current.
+
+```tsx
+import { ProductSwitcher } from '@nanisoft/prism-ui/components/product-switcher'
+```
+
+## Overview
+
+A ProductSwitcher is a switch between the members of a set of products. Each
+member is drawn with its own `ProductMark`, so the two parts of a product's
+identity - the ring in the brand ink and the core in its own pack fill - are the
+same two colours in a switcher, in a row and on a page header.
+
+All four NaniSoft sites need it and each one wrote it: the company's own site
+moves between its products from a row of coloured marks, and each product site
+names its siblings in its header.
+
+## Guidelines
+
+### When to use
+
+Use a ProductSwitcher where a reader can move between whole products rather than
+between pages of one: a site header, a footer, a page that lists the family.
+
+Use one size across the whole switcher. A set where one mark is larger than the
+rest reads as a hierarchy that is not there.
+
+### When not to use
+
+Do not use a ProductSwitcher to switch between pages of one product. That is
+`Pagination` or `Tabs`, and a set of product marks is a claim about where the
+reader is, not a position in a sequence.
+
+Do not use it for a set of one. Pass nothing rather than a switcher with a single
+member; a switcher with nothing to switch to is a heading.
+
+Do not use it as a menu. It renders every member at once. If you want a control
+that opens a list, compose `DropdownMenu` with the marks.
+
+### Best practices
+
+- Pass `currentId` on the page a member is showing, and omit it on a page that is
+  not one of the members.
+- The current member is marked with `aria-current="page"`, never with a colour
+  alone. There is no prop that overrides that marking, which is the reason this
+  is a component rather than a list of anchors you write yourself.
+- Leave `pack` off the one member that has no pack of its own. That member wears
+  the full spectrum, which says "no single colour" once rather than five times.
+- Pass `label` when the set is not a set of products. The default name is
+  `Products`, and a consumer whose set is not products should pass its own word.
+
+### Content guidelines
+
+- Use each product's own name, in the case it uses everywhere else.
+- Keep a name to one or two words. The mark carries the identity; the name carries
+  the label.
+- Never abbreviate a name to fit beside its mark. Drop the mark, shorten the row,
+  or let the name wrap.
+
+**Three members, with the one the reader is on marked, and one wearing the spectrum.**
+
+```tsx
+import { ProductSwitcher } from '@nanisoft/prism-ui/components/product-switcher'
+
+/** Three members, with the one the reader is on marked, and one wearing the spectrum. */
+export default function ProductSwitcherDemo() {
+  return (
+    <ProductSwitcher
+      currentId="nexus"
+      products={[
+        { id: 'nexus', name: 'Nexus', pack: 'lavender', href: '#nexus' },
+        { id: 'atlas', name: 'Atlas', pack: 'mint', href: '#atlas' },
+        { id: 'www', name: 'NaniSoft', href: '#www' },
+      ]}
+    />
+  )
+}
+```
+
+## Props
+
+**`products`** `readonly SwitcherProduct[]` · required · default: — — The set to move between, in the order a reader should meet it. Order is the caller's because it is a claim about which product matters first.
+**`currentId`** `string` · optional · default: — — The `id` of the member the reader is on. Marked `aria-current="page"`, which is how a reader and a screen reader both know where they are. Omit it when the switcher is rendered on a page that is not one of the members.
+**`size`** `ProductMarkSize` · optional · default: `'sm'` — The drawn size of every mark, so a set shows one size rather than a mix. See `ProductMarkSize`.
+**`label`** `string` · optional · default: — — A heading for the set, for a switcher that is not inside a landmark the reader can already name. Rendered as the navigation's accessible name and as no visible text, because the marks beside it are the labels.
+**`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/progress.md

@@ -1,14 +1,95 @@
 # Progress
 
-antd Progress, unchanged — a pass-through re-export. Import from '@nanisoft/prism-ui'.
+The bar that reports how far a task has progressed.
 
-```ts
-import { Progress } from '@nanisoft/prism-ui/components';
+```tsx
+import { Progress } from '@nanisoft/prism-ui/components/progress'
 ```
 
-`Progress` is antd's [Progress](https://ant.design/components/progress), re-exported unchanged.
+## Overview
 
-- Extends: antd **Progress** — for inherited props and demos, use the antd MCP (`antd_info Progress`).
-- Always import from '@nanisoft/prism-ui', never from `antd` directly.
+A Progress bar reports how far a task has progressed. It exposes its value, its
+minimum and its maximum through ARIA, so a screen reader announces the position
+rather than the width of a coloured bar. Pass a number for a task of known
+length, or `value={null}` for a task whose end is unknown, which is announced as
+indeterminate.
 
-_No additional props beyond the antd base component._
+The bar is a status, not a control. The reader watches it; nothing about it is
+clickable or focusable. Decorative movement is deliberately absent: the bar
+changes width only when the value changes.
+
+## Guidelines
+
+### When to use
+
+Use Progress when a process has measurable steps and the reader benefits from
+knowing how much is left: an upload, a build, a migration, a batch import.
+
+### When not to use
+
+Do not use Progress for a short wait under about a second. A spinner or a
+disabled control is quieter and more honest.
+
+Do not use it as a loading placeholder for content whose shape you know. A
+Skeleton mirrors the layout that is coming and reduces the sense of waiting.
+
+Do not use an indeterminate bar for a task of known length. Showing a moving bar
+for a countable task hides real information.
+
+### Best practices
+
+- Give the bar an accessible name with `aria-label` or an adjacent heading, so
+  the value is announced against a subject.
+- Show the value as text next to the bar when the reader needs the number, and
+  keep it in step with the bar.
+- Use `value={null}` only while the length is genuinely unknown, and switch to a
+  number as soon as one is available.
+- Announce completion in the surrounding UI. A bar that disappears at 100
+  percent leaves the reader unsure whether it finished or failed.
+- For a task that fails partway, replace the bar with an Alert that names the
+  failure rather than leaving it frozen.
+
+### Content guidelines
+
+- Name the task in progress, not the component: "Uploading assets", "Preparing
+  preview".
+- Use sentence case and a verb ending in "ing" for the in-progress label.
+- Keep the completion message separate and past tense: "Upload complete".
+
+**Progress at a known value, an unknown length, and complete.**
+
+```tsx
+import { Progress } from '@nanisoft/prism-ui/components/progress'
+
+/** Progress at a known value, an unknown length, and complete. */
+export default function ProgressDemo() {
+  return (
+    <div className="flex max-w-measure-narrow flex-col gap-8">
+      <div className="flex flex-col gap-2">
+        <div className="flex items-center justify-between text-sm">
+          <span className="font-medium">Uploading assets</span>
+          <span className="text-muted-foreground">68%</span>
+        </div>
+        <Progress value={68} aria-label="Uploading assets" />
+      </div>
+      <div className="flex flex-col gap-2">
+        <span className="font-medium text-sm">Preparing preview</span>
+        <Progress value={null} aria-label="Preparing preview" />
+      </div>
+      <div className="flex flex-col gap-2">
+        <span className="font-medium text-sm">Build complete</span>
+        <Progress value={100} aria-label="Build complete" />
+      </div>
+    </div>
+  )
+}
+```
+
+## Props
+
+**`value`** `number | null` · required · default: — — The current value. Pass `null` for an indeterminate task. There is no default: a progress bar without a value is a claim, so the consumer states where the task is.
+**`max`** `number` · optional · default: `100` — The maximum value.
+**`min`** `number` · optional · default: `0` — The minimum value.
+**`format`** `Intl.NumberFormatOptions` · optional · default: — — Options passed to `Intl.NumberFormat` when the value is rendered.
+**`locale`** `Intl.LocalesArgument` · optional · default: — — The locale used when formatting the value.
+**`getAriaValueText`** `(formattedValue: string, value: number | null) => string` · optional · default: — — Returns the text alternative announced for a value.

package/dist/md/components/prose.md

@@ -0,0 +1,91 @@
+# Prose
+
+Consumer-authored body copy held to the reading measure and to the block rhythm, so a document does not restate either.
+
+```tsx
+import { Prose } from '@nanisoft/prism-ui/components/prose'
+```
+
+## Overview
+
+A Prose is a run of body copy you wrote, held to the reading measure and to the
+block rhythm so a document does not have to restate either. You pass the content
+as `children`; Prism owns the width, the spacing between blocks and the
+treatments.
+
+Every NaniSoft site publishes long-form pages, and each one re-derived the same
+answer: a column that stops growing, paragraphs that are too far apart or too
+close, and a link that is either an unstyled word or an over-decorated one. This
+is that answer once.
+
+## Guidelines
+
+### When to use
+
+Use a Prose wherever the content is authored somewhere else and Prism should own
+its presentation: a blog post body, a documentation page, a description that
+turned out to be three paragraphs.
+
+The treatments are child selectors, so your own elements are the ones styled.
+Writing a plain `<p>` and a plain `<h2>` gets the system treatment, and writing
+Prism's own `Heading` and `Text` gets the same result, because the two spellings
+converge on the same element.
+
+### When not to use
+
+Do not use a Prose for a supporting line under a heading. That is `Text`, and a
+measure around one sentence is a measure around one sentence.
+
+Do not use it to fix a width. The measure is the component's whole job, and a run
+set wider than the measure is the defect it exists to remove. `fullWidth` exists
+for the case where the prose genuinely is not a reading column, and it is opt-in
+on purpose.
+
+### Best practices
+
+- Pass plain semantic elements. Do not add class names of your own to size or
+  colour text; that is the override path this system does not have.
+- Keep heading levels consistent with the document. A Prose does not know what
+  surrounds it.
+- Use `size="lg"` for a marketing page's supporting copy and the default for a
+  document body. Do not mix the two on one page.
+
+### Content guidelines
+
+- Aim for a sentence or two per paragraph. A paragraph a reader scrolls past is a
+  paragraph that needed to be two.
+- Link the first mention of a term, not every mention.
+- Use a list when the items are peers. A list of sentences is a paragraph with
+  punctuation.
+
+**A run of prose, with the block treatments applied to the caller's own elements.**
+
+```tsx
+import { Prose } from '@nanisoft/prism-ui/components/prose'
+
+/** A run of prose, with the block treatments applied to the caller's own elements. */
+export default function ProseDemo() {
+  return (
+    <Prose>
+      <h2>A heading</h2>
+      <p>
+        A paragraph of body copy, held to the reading measure. The measure is the
+        emitted container-measure token, so a line stops growing at the same place
+        in every pack and in both modes.
+      </p>
+      <ul>
+        <li>Lists are styled as part of the run.</li>
+        <li>So are code, quotations, tables and headings.</li>
+      </ul>
+      <blockquote>A quotation keeps the muted ink and a left rule.</blockquote>
+    </Prose>
+  )
+}
+```
+
+## Props
+
+**`children`** `ReactNode` · required · default: — — The authored body. Any flow content: paragraphs, lists, headings, tables, code, images. The vertical rhythm and the treatments below apply to whatever is passed, so the caller writes plain elements and Prism styles them.
+**`size`** `ProseSize` · optional · default: `'base'` — The reading size. `base` is the document body; `lg` is the one step up a marketing page's supporting copy is set at.
+**`fullWidth`** `boolean` · optional · default: — — Drops the measure so the run fills the space it is given. The measure is the whole point of the component, so this is opt-in and not a prop a caller sets because the width looked wrong: a line longer than the measure is the defect this exists to remove.
+**`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/radio-group.md

@@ -0,0 +1,111 @@
+# RadioGroup
+
+The control that chooses exactly one option from a small visible set.
+
+```tsx
+import { RadioGroup, RadioGroupItem } from '@nanisoft/prism-ui/components/radio-group'
+```
+
+## Overview
+
+A RadioGroup chooses exactly one option from a small set that stays visible. It
+ships as `RadioGroup` and `RadioGroupItem`. The group owns the value and the
+keyboard model; each item contributes one value.
+
+The group is a single Tab stop. Once focus is inside, the arrow keys move
+between items and select as they move, Home and End jump to the ends, and Space
+selects the focused item. The selected item is exposed through the native radio
+input beside each control.
+
+## Guidelines
+
+### When to use
+
+Use a RadioGroup when the options are mutually exclusive and few enough that
+showing them all at once helps the reader compare. Two to five options is the
+comfortable range.
+
+### When not to use
+
+Do not use a RadioGroup for a long list. Past roughly seven options, a Select
+keeps the form compact and adds typeahead.
+
+Do not use one when several answers may stand together. Checkboxes state that
+each choice is independent; radio items imply a single answer.
+
+### Best practices
+
+- Give the group a visible legend or an `aria-label`. The group's name is what
+  the reader hears when focus enters, so it must describe the question.
+- Put one item per row with the label beside its control, and point `FieldLabel`
+  at the item's `id` so the whole row is clickable.
+- Do not pre-check an option the reader has not chosen unless it is a genuine
+  default you would defend.
+- Use `disabled` only with nearby text that explains why, not to hide an option
+  that should not be offered.
+- Keep the item order stable across renders. Reordering radio items when a
+  value changes makes the group feel unpredictable.
+
+### Content guidelines
+
+- Keep option labels parallel in form and length, so the differences are easy
+  to weigh.
+- Use sentence case and no trailing periods on the option labels.
+- Put an explanation in a helper line under the label, not in the label itself.
+
+**A radio group with one option preselected and one disabled.**
+
+```tsx
+'use client'
+
+import { FieldLabel } from '@nanisoft/prism-ui/components/field'
+import { RadioGroup, RadioGroupItem } from '@nanisoft/prism-ui/components/radio-group'
+
+/** A radio group with one option preselected and one disabled. */
+export default function RadioGroupDemo() {
+  return (
+    <RadioGroup
+      defaultValue="daily"
+      aria-label="Notification frequency"
+      className="max-w-measure-narrow"
+    >
+      <div className="flex items-start gap-3">
+        <RadioGroupItem id="radio-daily" value="daily" className="mt-0.5" />
+        <div className="flex flex-col gap-1">
+          <FieldLabel htmlFor="radio-daily">Daily digest</FieldLabel>
+          <span className="text-muted-foreground text-sm">One message each morning.</span>
+        </div>
+      </div>
+      <div className="flex items-start gap-3">
+        <RadioGroupItem id="radio-weekly" value="weekly" className="mt-0.5" />
+        <div className="flex flex-col gap-1">
+          <FieldLabel htmlFor="radio-weekly">Weekly summary</FieldLabel>
+          <span className="text-muted-foreground text-sm">One message on Monday.</span>
+        </div>
+      </div>
+      <div className="flex items-start gap-3">
+        <RadioGroupItem id="radio-never" value="never" disabled className="mt-0.5" />
+        <div className="flex flex-col gap-1">
+          <FieldLabel htmlFor="radio-never" className="text-muted-foreground">
+            Never
+          </FieldLabel>
+          <span className="text-muted-foreground text-sm">
+            Disabled while an audit hold is active.
+          </span>
+        </div>
+      </div>
+    </RadioGroup>
+  )
+}
+```
+
+## Props
+
+**`value`** `string` · optional · default: — — The selected item's value, when the group is controlled.
+**`defaultValue`** `string` · optional · default: — — The item selected initially, for an uncontrolled group.
+**`onValueChange`** `(value: string) => void` · optional · default: — — Called when the selection changes.
+**`name`** `string` · optional · default: — — The form field name submitted with the form.
+**`form`** `string` · optional · default: — — Identifies the form that owns the hidden inputs.
+**`disabled`** `boolean` · optional · default: — — Whether every item ignores user interaction.
+**`readOnly`** `boolean` · optional · default: — — Whether the user may not change the selection.
+**`required`** `boolean` · optional · default: — — Whether a value must be chosen before the form submits.

package/dist/md/components/section.md

@@ -0,0 +1,91 @@
+# Section
+
+The container and heading primitives every Block composes for rhythm.
+
+```tsx
+import { Section, SectionHeading } from '@nanisoft/prism-ui/components/section'
+```
+
+## Overview
+
+`Section` is the container primitive every Block composes. It owns the page
+container width and the vertical rhythm (`py-16 sm:py-24`), so one page keeps one
+rhythm instead of each block re-deriving its own padding.
+
+`SectionHeading` is the heading that sits inside it: an optional eyebrow, a
+title, and an optional description. Its `as` prop selects the heading level, and
+it defaults to `h2` because a Block is composed rather than a page.
+
+## Guidelines
+
+### When to use
+
+Use `Section` for any full-width band of a page, and `SectionHeading` for the
+heading that introduces it. A Block uses both, and a page composition uses them
+between blocks to keep the rhythm continuous.
+
+Use `SectionHeading` with `as="h1"` when the section is the page's primary
+heading, and with a deeper level when the document already names the content.
+
+### When not to use
+
+Do not use `Section` for a card or an inline group. It is a page-level band, and
+its padding is the page's vertical rhythm; nesting it produces uneven spacing.
+
+Do not re-declare the container width or the section padding at a call site. If
+a band needs a different width, that is a token or a component change, not a
+`max-w-*` on the section.
+
+### Best practices
+
+- One `h1` per page. Every other heading nests under it, and `SectionHeading`'s
+  default `h2` is the level below the page title.
+- Pass `headingLevel` or `as` at the call site when a Block sits under a heading
+  the document already owns, so the outline stays single-rooted.
+- Keep `eyebrow` opt-in. It has no default, because a hardcoded eyebrow makes
+  every consumer inherit a claim about their product.
+- Use `align="left"` for data sections and the centered default for hero and
+  closing sections, and keep the choice consistent within a page.
+
+### Content guidelines
+
+- A heading is a noun phrase in sentence case.
+- A description is one or two sentences and states the section's job.
+- An eyebrow is a short label, three words at most, and it never repeats the
+  heading.
+
+**A section band with a heading, at a heading level the demo owns.**
+
+```tsx
+import { Section, SectionHeading } from '@nanisoft/prism-ui/components/section'
+
+/** A section band with a heading, at a heading level the demo owns. */
+export default function SectionDemo() {
+  return (
+    <Section className="bg-muted/30 rounded-xl">
+      <SectionHeading
+        as="h3"
+        eyebrow="Release 2.4"
+        title="What changed"
+        description="Three fixes and one new block. No token changes."
+        align="left"
+        className="mb-6"
+      />
+      <p className="text-muted-foreground text-sm">
+        The section owns the container width and the vertical rhythm, so this
+        band keeps the page&apos;s spacing without re-declaring it.
+      </p>
+    </Section>
+  )
+}
+```
+
+## Props
+
+**`index`** `string` · optional · default: — — A short ordinal for the section: "01", "02", "7". It is rendered in the mono face above the title, because a section's position in a sequence is machine notation rather than a word, and the mono stack is what this repository annotates machine-readable values with. It is a separate prop from `eyebrow` and not a default value of it, because the two say different things: an eyebrow is a word a reader reads, and an index is a number that is only meaningful beside the section it counts. All four NaniSoft sites render one of these above every section heading, and three of them render it beside a label rather than above a title, which is the same fact in a different arrangement.
+**`eyebrow`** `ReactNode` · optional · default: —
+**`title`** `ReactNode` · required · default: —
+**`description`** `ReactNode` · optional · default: —
+**`align`** `'center' | 'left'` · optional · default: —
+**`as`** `HeadingLevel` · optional · default: — — Heading level. Defaults to `h2` because blocks compose under a page heading. A page that renders a block as its primary heading passes `as="h1"`; a document with no `h1` gives screen-reader and search engines no top-level entry point.
+**`className`** `string` · optional · default: —

package/dist/md/components/select.md

@@ -1,14 +1,150 @@
 # Select
 
-antd Select, unchanged — a pass-through re-export. Import from '@nanisoft/prism-ui'.
+The control that chooses one option from a list that opens on demand.
 
-```ts
-import { Select } from '@nanisoft/prism-ui/components';
+```tsx
+import { Select, SelectTrigger, SelectValue, SelectContent, SelectItem, SelectGroup, SelectLabel, SelectSeparator } from '@nanisoft/prism-ui/components/select'
 ```
 
-`Select` is antd's [Select](https://ant.design/components/select), re-exported unchanged.
+## Overview
 
-- Extends: antd **Select** — for inherited props and demos, use the antd MCP (`antd_info Select`).
-- Always import from '@nanisoft/prism-ui', never from `antd` directly.
+A Select chooses one option from a list that opens on demand. It ships as
+`Select`, `SelectTrigger`, `SelectValue`, `SelectContent`, `SelectItem`,
+`SelectGroup`, `SelectLabel` and `SelectSeparator`. `Select` holds the value,
+`SelectTrigger` shows the current choice, and `SelectContent` carries the
+options. Pass the options to the root as `items` too, so the trigger can render
+a label before any option has mounted.
 
-_No additional props beyond the antd base component._
+The trigger is a button with a combobox role, so it is reachable by Tab. In the
+open popup the arrow keys move through the options, typing letters jumps to a
+match, Enter chooses, and Escape closes without changing the value.
+
+## Guidelines
+
+### When to use
+
+Use a Select when the option set is long enough that a radio group would
+overwhelm the form, or when only the chosen value needs to stay visible. It fits
+settings and filters where the reader picks one value from a known list.
+
+### When not to use
+
+Do not use a Select for two or three mutually exclusive options. A RadioGroup
+shows every choice at once and needs no opening click.
+
+Do not use it when the reader may choose more than one value, or for navigation.
+Checkboxes state independence; a link handles a route change.
+
+### Best practices
+
+- Pair the Select with a `FieldLabel` whose `htmlFor` matches the trigger's
+  `id`. The value shows in the trigger, so the label names the field.
+- Pass `items` so the trigger can resolve a label before an option has mounted.
+  Without it, Base UI falls back to the raw value.
+- Give `SelectValue` a placeholder that says what to do, such as "Choose a
+  region", rather than naming a default the reader did not choose.
+- Add `SelectGroup` and `SelectLabel` once a list passes roughly eight options,
+  so the reader can scan by group.
+- A disabled option is still readable. Explain why it cannot be chosen in
+  adjacent text rather than leaving a dead row unexplained.
+
+### Content guidelines
+
+- Write option labels as sentence-case nouns: "Europe West", not "EUROPE WEST".
+- Order options by the reader's expectation: size, plan, region, or product.
+- Reserve the first option for a real choice. Do not add an empty "Select one"
+  row when the placeholder already asks the question.
+
+**A labelled Select with a grouped option list and a controlled value.**
+
+```tsx
+'use client'
+
+import { useState } from 'react'
+
+import { Field, FieldLabel } from '@nanisoft/prism-ui/components/field'
+import {
+  Select,
+  SelectContent,
+  SelectGroup,
+  SelectItem,
+  SelectLabel,
+  SelectTrigger,
+  SelectValue,
+} from '@nanisoft/prism-ui/components/select'
+
+/** A labelled Select with a grouped option list and a controlled value. */
+export default function SelectDemo() {
+  const [role, setRole] = useState('editor')
+
+  return (
+    <div className="flex max-w-measure-narrow flex-col gap-6">
+      <Field>
+        <FieldLabel htmlFor="select-role">Role</FieldLabel>
+        <Select
+          value={role}
+          onValueChange={(value) => setRole(value ?? '')}
+          items={{ viewer: 'Viewer', editor: 'Editor', admin: 'Admin' }}
+        >
+          <SelectTrigger id="select-role" className="w-full">
+            <SelectValue placeholder="Choose a role" />
+          </SelectTrigger>
+          <SelectContent>
+            <SelectGroup>
+              <SelectLabel>Team roles</SelectLabel>
+              <SelectItem value="viewer">Viewer</SelectItem>
+              <SelectItem value="editor">Editor</SelectItem>
+              <SelectItem value="admin">Admin</SelectItem>
+            </SelectGroup>
+          </SelectContent>
+        </Select>
+      </Field>
+      <Field>
+        <FieldLabel htmlFor="select-region">Region</FieldLabel>
+        <Select
+          defaultValue="eu-west"
+          items={{
+            'eu-west': 'Europe West',
+            'us-east': 'US East',
+            'ap-south': 'Asia South',
+          }}
+        >
+          <SelectTrigger id="select-region" className="w-full">
+            <SelectValue placeholder="Choose a region" />
+          </SelectTrigger>
+          <SelectContent>
+            <SelectItem value="eu-west">Europe West</SelectItem>
+            <SelectItem value="us-east">US East</SelectItem>
+            <SelectItem value="ap-south" disabled>
+              Asia South (paused)
+            </SelectItem>
+          </SelectContent>
+        </Select>
+      </Field>
+    </div>
+  )
+}
+```
+
+## Props
+
+**`value`** `string` · optional · default: — — The selected value, when the select is controlled.
+**`defaultValue`** `string` · optional · default: — — The value selected initially, for an uncontrolled select.
+**`onValueChange`** `(value: string | null) => void` · optional · default: — — Called when the selected value changes.
+**`open`** `boolean` · optional · default: — — The controlled open state of the popup.
+**`defaultOpen`** `boolean` · optional · default: — — The initially open state of the popup.
+**`onOpenChange`** `(open: boolean) => void` · optional · default: — — Called when the popup opens or closes.
+**`name`** `string` · optional · default: — — The form field name submitted with the form.
+**`form`** `string` · optional · default: — — Identifies the form that owns the hidden input.
+**`required`** `boolean` · optional · default: — — Whether a value must be chosen before the form submits.
+**`disabled`** `boolean` · optional · default: — — Whether the select ignores user interaction.
+**`readOnly`** `boolean` · optional · default: — — Whether the user may open the popup but not change the value.
+**`items`** `Record<string, React.ReactNode> | ReadonlyArray<{ label: React.ReactNode; value: string; }>` · optional · default: — — The options, keyed by value, so the trigger can render a label before any item has mounted. Without it, `SelectValue` shows the raw value.
+**`itemToStringLabel`** `(value: string) => string` · optional · default: — — Converts an item value to the label shown in the trigger.
+**`children`** `React.ReactNode` · optional · default: — — The trigger and the popup content.
+**`label`** `React.ReactNode` · required · default: —
+**`size`** `'sm' | 'default'` · optional · default: `default` — The trigger's height.
+**`placeholder`** `React.ReactNode` · optional · default: — — Shown when no value is selected.
+**`side`** `'top' | 'right' | 'bottom' | 'left'` · optional · default: `bottom` — Which side of the trigger the list is placed on.
+**`align`** `'start' | 'center' | 'end'` · optional · default: `center` — How the list aligns against the trigger.
+**`sideOffset`** `number` · optional · default: `4` — The distance in pixels between the trigger and the list.