@pearpages/pulp-react 0.2.2 → 0.3.0

package/dist/component-manifest.json

@@ -36,6 +36,7 @@
       ],
       "import": "import { Accordion } from '@pearpages/pulp-react/accordion';",
       "css": "@pearpages/pulp-react/accordion.css",
+      "client": true,
       "tokens": "--accordion-*",
       "props": [
         {
@@ -171,6 +172,7 @@
       ],
       "import": "import { Alert } from '@pearpages/pulp-react/alert';",
       "css": "@pearpages/pulp-react/alert.css",
+      "client": false,
       "tokens": "--alert-*",
       "props": [
         {
@@ -243,14 +245,85 @@
       ],
       "parts": []
     },
+    {
+      "name": "Avatar",
+      "description": "A person, as a picture or as initials. The initials take over when no image\nis given and when the image fails to load, so a broken URL never shows a\nbroken-image glyph. Every value comes from `--avatar-*` tokens; the\nbackground is one token for everyone, not a colour computed from the name.",
+      "status": "experimental",
+      "category": "Utilities",
+      "accessibility": "With an image, the `img` carries the name as its `alt`. With initials, the root is `role=\"img\"` named by `alt` or `name`, and the letters are hidden from assistive technology (\"AR\" read aloud means nothing). `alt=\"\"` makes the avatar decorative (`aria-hidden`): use it when the name is written next to it. Not focusable and not interactive; wrap it in a Link or a Button to make it one.",
+      "do": [
+        "Pass `name` always, even with an image: it is the fallback when the image fails.",
+        "Pass `alt=\"\"` when the person's name is visible beside the avatar."
+      ],
+      "dont": [
+        "Colour avatars per person from a hash of the name; the colours will not be tokens and will not pass contrast in both schemes.",
+        "Use it for a logo or an illustration; it crops to a circle and falls back to initials."
+      ],
+      "import": "import { Avatar } from '@pearpages/pulp-react/avatar';",
+      "css": "@pearpages/pulp-react/avatar.css",
+      "client": true,
+      "tokens": "--avatar-*",
+      "props": [
+        {
+          "name": "alt",
+          "type": "string",
+          "required": false,
+          "default": null,
+          "description": "Accessible name. Defaults to `name`. Pass `\"\"` next to the visible name, so it is not read twice."
+        },
+        {
+          "name": "children",
+          "type": "ReactElement<unknown, string | JSXElementConstructor<any>>",
+          "required": false,
+          "default": null,
+          "description": "An image element to use instead of `img`: a framework's image component\n(`<Avatar name=\"Ana\"><Image src={url} alt=\"\" width={40} height={40} /></Avatar>`).\nIt receives the styles and the error handling; its own `alt` is replaced by the avatar's."
+        },
+        {
+          "name": "name",
+          "type": "string",
+          "required": false,
+          "default": null,
+          "description": "The person's name. Its initials show when there is no image or the image fails, and it names the avatar unless `alt` does."
+        },
+        {
+          "name": "ref",
+          "type": "Ref<HTMLSpanElement>",
+          "required": false,
+          "default": null,
+          "description": ""
+        },
+        {
+          "name": "size",
+          "type": "enum",
+          "values": [
+            "\"sm\"",
+            "\"md\"",
+            "\"lg\"",
+            "\"xl\""
+          ],
+          "required": false,
+          "default": "md",
+          "description": "`sm` and `md` match the control heights, so an avatar lines up with a button."
+        },
+        {
+          "name": "src",
+          "type": "string",
+          "required": false,
+          "default": null,
+          "description": "Image URL. Ignored when an image element is passed as the child."
+        }
+      ],
+      "parts": []
+    },
     {
       "name": "Badge",
       "description": "A small label for status, counts and tags. Tone and variant resolve\nthrough `--badge-*` onto the status tokens, whose contrast is proven by\nthe token tests. Not interactive: for a removable chip, compose with a\nButton.",
       "status": "stable",
       "category": "Feedback",
-      "accessibility": "Plain text: no role, no interaction. Every tone × variant pair meets WCAG AA, proven by the token tests. Tone is reinforced by the text, not only by colour.",
+      "accessibility": "Plain text: no role, no interaction, and deliberately no live region: a badge that is there when the page renders must not be announced as news (put `role=\"status\"` on a wrapper yourself if a count changes while the user is on the page). A `dot` has no visible text, so its `label` is rendered visually hidden; a `count` above `max` reads as \"99+\", followed by the `label` if there is one. Every tone × variant pair meets WCAG AA, proven by the token tests. Tone is reinforced by the text, not only by colour.",
       "do": [
         "Keep the text to one or two words.",
+        "Give a `dot` a `label` that says what it marks, and a `count` a `label` that says what is counted.",
         "Pair a leading icon with text, never alone."
       ],
       "dont": [
@@ -259,8 +332,16 @@
       ],
       "import": "import { Badge } from '@pearpages/pulp-react/badge';",
       "css": "@pearpages/pulp-react/badge.css",
+      "client": false,
       "tokens": "--badge-*",
       "props": [
+        {
+          "name": "count",
+          "type": "number",
+          "required": false,
+          "default": null,
+          "description": "A number to show instead of children, clamped to `max` (\"99+\"). Zero or less\nrenders nothing: an empty inbox has no badge."
+        },
         {
           "name": "icon",
           "type": "ReactNode",
@@ -268,6 +349,20 @@
           "default": null,
           "description": "Leading glyph, decorative."
         },
+        {
+          "name": "label",
+          "type": "string",
+          "required": false,
+          "default": null,
+          "description": "What the badge means, for assistive technology. Required for `variant=\"dot\"`\n(\"Unread messages\"), where it is the only content. With a `count` it is read\nafter the number: `count={3} label=\"unread\"` is announced as \"3 unread\"."
+        },
+        {
+          "name": "max",
+          "type": "number",
+          "required": false,
+          "default": "99",
+          "description": "The highest count shown as is."
+        },
         {
           "name": "ref",
           "type": "Ref<HTMLSpanElement>",
@@ -305,11 +400,12 @@
           "type": "enum",
           "values": [
             "\"solid\"",
-            "\"subtle\""
+            "\"subtle\"",
+            "\"dot\""
           ],
           "required": false,
           "default": "subtle",
-          "description": "`solid` fills with the tone; `subtle` tints and uses the tone as text."
+          "description": "`solid` fills with the tone; `subtle` tints and uses the tone as text; `dot` is a\nsmall filled circle with no visible text, which needs a `label`."
         }
       ],
       "parts": []
@@ -322,7 +418,8 @@
       "accessibility": "A native `button` (or the child element with `asChild`). `loading` sets `aria-disabled` and `aria-busy` and keeps focus; only `disabled` removes it from the tab order. Icon-only use warns in development: use IconButton, which requires a name.",
       "do": [
         "One `primary` per view.",
-        "Use `asChild` for links that look like buttons, keeping the `a` semantics."
+        "Use `asChild` for links that look like buttons, keeping the `a` semantics.",
+        "Use `tone=\"danger\"` for the action that destroys, and say what it destroys in the label (\"Delete place\"), since colour alone must not carry it."
       ],
       "dont": [
         "Use `loading` on a button that is not the one that started the work.",
@@ -330,6 +427,7 @@
       ],
       "import": "import { Button } from '@pearpages/pulp-react/button';",
       "css": "@pearpages/pulp-react/button.css",
+      "client": false,
       "tokens": "--button-*",
       "props": [
         {
@@ -379,6 +477,17 @@
           "default": "md",
           "description": ""
         },
+        {
+          "name": "tone",
+          "type": "enum",
+          "values": [
+            "\"default\"",
+            "\"danger\""
+          ],
+          "required": false,
+          "default": "default",
+          "description": "`danger` for an action that destroys something (delete, remove, leave). It\nrecolours whichever `variant` is in use, so emphasis and danger stay two\nseparate decisions: `variant=\"ghost\" tone=\"danger\"` is a quiet delete."
+        },
         {
           "name": "variant",
           "type": "enum",
@@ -410,6 +519,7 @@
       ],
       "import": "import { Calendar } from '@pearpages/pulp-react/calendar';",
       "css": "@pearpages/pulp-react/calendar.css",
+      "client": true,
       "tokens": "--calendar-*",
       "props": [
         {
@@ -522,6 +632,7 @@
       ],
       "import": "import { Card } from '@pearpages/pulp-react/card';",
       "css": "@pearpages/pulp-react/card.css",
+      "client": false,
       "tokens": "--card-*",
       "props": [
         {
@@ -628,6 +739,7 @@
       ],
       "import": "import { Checkbox } from '@pearpages/pulp-react/checkbox';",
       "css": "@pearpages/pulp-react/checkbox.css",
+      "client": true,
       "tokens": "--checkbox-*",
       "props": [
         {
@@ -687,6 +799,93 @@
       ],
       "parts": []
     },
+    {
+      "name": "Chip",
+      "description": "A small pill for a choice or a value the user controls: a filter that\ntoggles (`selected`), a tag that can be removed (`onRemove`), or both. The\nlabel is a button only when pressing it does something.",
+      "status": "experimental",
+      "category": "Actions",
+      "accessibility": "A toggle chip is a native `button` with `aria-pressed`, so Space and Enter work and the state is announced. The remove control is a second `button`, a sibling of the first (a button inside a button is invalid HTML and unreachable by keyboard), named by `removeLabel` plus the chip's own label through `aria-labelledby`: \"Remove Vegan\", not \"Remove\" six times. The pair is wrapped in a `role=\"group\"` named by the label only when there are two controls. `disabled` disables both. After removing a chip, move focus yourself (to the next chip or the input): the button that had it is gone.",
+      "do": [
+        "Use a group of toggle chips for filters where several can be on at once.",
+        "Keep the label to a word or two; a chip does not wrap."
+      ],
+      "dont": [
+        "Use a chip that does nothing as a label or a status: that is a Badge.",
+        "Use chips for one choice out of several; that is a SegmentedControl or a RadioGroup."
+      ],
+      "import": "import { Chip } from '@pearpages/pulp-react/chip';",
+      "css": "@pearpages/pulp-react/chip.css",
+      "client": true,
+      "tokens": "--chip-*",
+      "props": [
+        {
+          "name": "defaultSelected",
+          "type": "boolean",
+          "required": false,
+          "default": null,
+          "description": "Uncontrolled initial pressed state."
+        },
+        {
+          "name": "onRemove",
+          "type": "(() => void)",
+          "required": false,
+          "default": null,
+          "description": "Adds a remove button after the label: a second button beside the chip, never inside it."
+        },
+        {
+          "name": "onSelectedChange",
+          "type": "((selected: boolean) => void)",
+          "required": false,
+          "default": null,
+          "description": "Called with the next state when the chip is pressed."
+        },
+        {
+          "name": "ref",
+          "type": "Ref<HTMLButtonElement>",
+          "required": false,
+          "default": null,
+          "description": "The `button` that carries the label, or the `span` when the chip neither toggles nor has an `onClick`."
+        },
+        {
+          "name": "removeLabel",
+          "type": "string",
+          "required": false,
+          "default": "Remove",
+          "description": "The remove button is named \"`removeLabel` + the chip's label\" (\"Remove Vegan\")."
+        },
+        {
+          "name": "selected",
+          "type": "boolean",
+          "required": false,
+          "default": null,
+          "description": "Controlled pressed state. Passing it (or `defaultSelected`, or `onSelectedChange`) makes the chip a toggle."
+        },
+        {
+          "name": "size",
+          "type": "enum",
+          "values": [
+            "\"sm\"",
+            "\"md\"",
+            "\"lg\""
+          ],
+          "required": false,
+          "default": "md",
+          "description": "`sm` is 24px high, the minimum target size."
+        },
+        {
+          "name": "tone",
+          "type": "enum",
+          "values": [
+            "\"neutral\"",
+            "\"action\""
+          ],
+          "required": false,
+          "default": "neutral",
+          "description": "`action` takes the brand's colour; a selected chip is filled in either tone."
+        }
+      ],
+      "parts": []
+    },
     {
       "name": "Combobox",
       "description": "A text input that suggests options as the user types, on React Aria's\ncombobox (decision record 001): the list is announced through\n`aria-activedescendant`, arrows move, Enter selects, Escape closes and\nthen clears. Static lists filter themselves; for async options, control\n`inputValue`, fetch, and pass the results with `filter=\"none\"` and\n`loading` while they arrive. Options look the same as Listbox's.",
@@ -703,6 +902,7 @@
       ],
       "import": "import { Combobox } from '@pearpages/pulp-react/combobox';",
       "css": "@pearpages/pulp-react/combobox.css",
+      "client": true,
       "tokens": "--combobox-*",
       "props": [
         {
@@ -914,6 +1114,7 @@
       ],
       "import": "import { DatePicker } from '@pearpages/pulp-react/date-picker';",
       "css": "@pearpages/pulp-react/date-picker.css",
+      "client": true,
       "tokens": "--date-picker-*",
       "props": [
         {
@@ -1064,6 +1265,7 @@
       ],
       "import": "import { DialogSystem } from '@pearpages/pulp-react/dialog';",
       "css": "@pearpages/pulp-react/dialog.css",
+      "client": true,
       "tokens": "--dialog-*",
       "props": [
         {
@@ -1099,6 +1301,7 @@
       ],
       "import": "import { Dialog } from '@pearpages/pulp-react/dialog';",
       "css": "@pearpages/pulp-react/dialog.css",
+      "client": true,
       "tokens": "--dialog-*",
       "props": [
         {
@@ -1132,6 +1335,149 @@
       ],
       "parts": []
     },
+    {
+      "name": "Divider",
+      "description": "A hairline between two groups of content, horizontal or vertical. A vertical\ndivider stretches to its flex or grid row, so it needs a parent that lays it out.",
+      "status": "experimental",
+      "category": "Layout",
+      "accessibility": "Decorative by default: `role=\"none\"`, nothing is announced, because headings and landmarks should already carry the structure. With `decorative={false}` it is a `separator`, and a vertical one says so through `aria-orientation`. It is never focusable: a separator that moves is a splitter, which this is not.",
+      "do": [
+        "Put it between groups inside a Card, a Menu-like list or a toolbar.",
+        "Let `spacing` set the distance, so it stays on the spacing scale."
+      ],
+      "dont": [
+        "Use it to draw a border around something; that is the container's border.",
+        "Rely on it alone to tell a screen reader that a new section starts; use a heading."
+      ],
+      "import": "import { Divider } from '@pearpages/pulp-react/divider';",
+      "css": "@pearpages/pulp-react/divider.css",
+      "client": false,
+      "tokens": "--divider-*",
+      "props": [
+        {
+          "name": "decorative",
+          "type": "boolean",
+          "required": false,
+          "default": "true",
+          "description": "A decorative line is hidden from assistive technology. Pass `false` when the\nline is the only thing that says two groups are separate."
+        },
+        {
+          "name": "orientation",
+          "type": "enum",
+          "values": [
+            "\"horizontal\"",
+            "\"vertical\""
+          ],
+          "required": false,
+          "default": "horizontal",
+          "description": ""
+        },
+        {
+          "name": "ref",
+          "type": "Ref<HTMLDivElement>",
+          "required": false,
+          "default": null,
+          "description": ""
+        },
+        {
+          "name": "spacing",
+          "type": "enum",
+          "values": [
+            "\"none\"",
+            "\"sm\"",
+            "\"md\"",
+            "\"lg\""
+          ],
+          "required": false,
+          "default": "none",
+          "description": "Space on both sides, along the axis the line separates."
+        }
+      ],
+      "parts": []
+    },
+    {
+      "name": "EmptyState",
+      "description": "What a list, a search or a page shows instead of its content: nothing yet,\nnothing found, or it failed to load. An icon, a title, a sentence and one\naction, centred. Composes Heading, Text and Stack, so the type follows the\nbrand without tokens of its own.",
+      "status": "experimental",
+      "category": "Feedback",
+      "accessibility": "The title is a real heading at `headingLevel`, so the empty region shows up in the outline; pick the level from the page, as with Heading. The icon is `aria-hidden`. Nothing is announced on its own: an empty state that is there when the page loads is just content. When it **replaces** content after the user did something (a search with no results, a failed reload), pass `role=\"status\"` (or `role=\"alert\"` for an error that needs attention) so it is read out; do not put `role=\"alert\"` on one that renders with the page. The action is whatever you pass, with its own semantics.",
+      "do": [
+        "Say what to do next in the description, and make the action that next step.",
+        "Use `tone=\"error\"` with a retry action when loading failed."
+      ],
+      "dont": [
+        "Use it for a validation error or a transient message; that is a Field error, an Alert or a Toast.",
+        "Offer several actions; an empty state has one way forward."
+      ],
+      "import": "import { EmptyState } from '@pearpages/pulp-react/empty-state';",
+      "css": "@pearpages/pulp-react/empty-state.css",
+      "client": false,
+      "tokens": "--empty-state-*",
+      "props": [
+        {
+          "name": "title",
+          "type": "ReactNode",
+          "required": true,
+          "default": null,
+          "description": "What is missing, or what went wrong, in a few words. Rendered as a heading."
+        },
+        {
+          "name": "action",
+          "type": "ReactNode",
+          "required": false,
+          "default": null,
+          "description": "One control: a Button, or a Link. For an error, the retry."
+        },
+        {
+          "name": "description",
+          "type": "ReactNode",
+          "required": false,
+          "default": null,
+          "description": "One or two sentences: why it is empty and what to do about it."
+        },
+        {
+          "name": "headingLevel",
+          "type": "enum",
+          "values": [
+            "1",
+            "2",
+            "3",
+            "4",
+            "5",
+            "6"
+          ],
+          "required": false,
+          "default": "3",
+          "description": "The heading's outline level, from where the empty state sits in the page."
+        },
+        {
+          "name": "icon",
+          "type": "ReactNode",
+          "required": false,
+          "default": null,
+          "description": "A glyph, shown in a tinted disc. Decorative: the title carries the meaning."
+        },
+        {
+          "name": "ref",
+          "type": "Ref<HTMLDivElement>",
+          "required": false,
+          "default": null,
+          "description": ""
+        },
+        {
+          "name": "tone",
+          "type": "enum",
+          "values": [
+            "\"neutral\"",
+            "\"error\""
+          ],
+          "required": false,
+          "default": "neutral",
+          "description": "`error` tints the icon with the error colours. It does not announce anything: see the accessibility notes."
+        }
+      ],
+      "parts": []
+    },
     {
       "name": "Field",
       "description": "The wiring every form control shares: a label pointing at the control, a\ndescription and an error exposed through `aria-describedby`, and invalid,\ndisabled and required state in one place. Only parts that are mounted end\nup in `aria-describedby`, so no id ever dangles. Compose with\n`Field.Label`, `Field.Control`, `Field.Description` and `Field.Error`\n(one of each); state on the DOM as `data-invalid`, `data-disabled`,\n`data-required`.\n\nKnown limitation: parts register in a layout effect, so server-rendered\nHTML carries no `aria-describedby` until hydration. The relationship is\ncomplete for every interactive use; static HTML consumers should not rely\non it yet.",
@@ -1146,6 +1492,7 @@
       ],
       "import": "import { Field } from '@pearpages/pulp-react/field';",
       "css": "@pearpages/pulp-react/field.css",
+      "client": true,
       "tokens": "--field-*",
       "props": [
         {
@@ -1271,6 +1618,7 @@
       ],
       "import": "import { Heading } from '@pearpages/pulp-react/heading';",
       "css": "@pearpages/pulp-react/heading.css",
+      "client": false,
       "tokens": "--heading-*",
       "props": [
         {
@@ -1337,6 +1685,7 @@
       ],
       "import": "import { Icon } from '@pearpages/pulp-react/icon';",
       "css": "@pearpages/pulp-react/icon.css",
+      "client": false,
       "tokens": "--icon-*",
       "props": [
         {
@@ -1390,6 +1739,7 @@
       ],
       "import": "import { IconButton } from '@pearpages/pulp-react/icon-button';",
       "css": "@pearpages/pulp-react/icon-button.css",
+      "client": false,
       "tokens": "--icon-button-*",
       "props": [
         {
@@ -1446,6 +1796,17 @@
           "default": "'md'",
           "description": ""
         },
+        {
+          "name": "tone",
+          "type": "enum",
+          "values": [
+            "\"default\"",
+            "\"danger\""
+          ],
+          "required": false,
+          "default": "'default'",
+          "description": "`danger` for an action that destroys something (delete, remove, leave). It\nrecolours whichever `variant` is in use, so emphasis and danger stay two\nseparate decisions: `variant=\"ghost\" tone=\"danger\"` is a quiet delete."
+        },
         {
           "name": "variant",
           "type": "enum",
@@ -1475,6 +1836,7 @@
       ],
       "import": "import { Inline } from '@pearpages/pulp-react/inline';",
       "css": "@pearpages/pulp-react/inline.css",
+      "client": false,
       "tokens": "--inline-*",
       "props": [
         {
@@ -1552,6 +1914,65 @@
       ],
       "parts": []
     },
+    {
+      "name": "Link",
+      "description": "A text link. Underlined by default, because colour alone must not be what\ntells a link from the words around it. With `asChild` the styles and props\nland on a router's own link, so client-side navigation keeps working.",
+      "status": "experimental",
+      "category": "Typography",
+      "accessibility": "A native `a`: focusable and activated with Enter only when it has an `href` (or the `asChild` element provides one). The focus ring comes from the semantic focus tokens. `underline=\"hover\"` removes the only non-colour cue, so it is for lists of links, never for a link inside a sentence (WCAG 1.4.1).",
+      "do": [
+        "Use `asChild` with the router's link: `<Link asChild><NextLink href=\"/feed\">Feed</NextLink></Link>`.",
+        "Write link text that makes sense out of context; screen readers list links on their own."
+      ],
+      "dont": [
+        "Use it for an action that does not navigate; that is a Button (`variant=\"ghost\"`).",
+        "Use `underline=\"hover\"` for a link inside running text."
+      ],
+      "import": "import { Link } from '@pearpages/pulp-react/link';",
+      "css": "@pearpages/pulp-react/link.css",
+      "client": false,
+      "tokens": "--link-*",
+      "props": [
+        {
+          "name": "asChild",
+          "type": "boolean",
+          "required": false,
+          "default": "false",
+          "description": "Render the single child instead of an `a`: a router's link component."
+        },
+        {
+          "name": "ref",
+          "type": "Ref<E>",
+          "required": false,
+          "default": null,
+          "description": ""
+        },
+        {
+          "name": "tone",
+          "type": "enum",
+          "values": [
+            "\"action\"",
+            "\"default\"",
+            "\"muted\""
+          ],
+          "required": false,
+          "default": "action",
+          "description": "`action` is the brand's link colour; `default` and `muted` take the text colours."
+        },
+        {
+          "name": "underline",
+          "type": "enum",
+          "values": [
+            "\"always\"",
+            "\"hover\""
+          ],
+          "required": false,
+          "default": "always",
+          "description": "`hover` drops the underline until the pointer is over it. Only for links that\nare obviously links from where they sit (a nav, a footer list)."
+        }
+      ],
+      "parts": []
+    },
     {
       "name": "Listbox",
       "description": "A visible list of options with single or multiple selection, on React\nAria's listbox (decision record 001): arrow keys move, Space toggles,\ntyping jumps, Shift and Ctrl/Cmd extend a multiple selection, Ctrl/Cmd+A\nselects all. For a list that opens from a control, use Picker; for one\nthat filters as you type, use Combobox. Both render these options.",
@@ -1567,6 +1988,7 @@
       ],
       "import": "import { Listbox } from '@pearpages/pulp-react/listbox';",
       "css": "@pearpages/pulp-react/listbox.css",
+      "client": true,
       "tokens": "--listbox-*",
       "props": [
         {
@@ -1675,6 +2097,7 @@
       ],
       "import": "import { Menu } from '@pearpages/pulp-react/menu';",
       "css": "@pearpages/pulp-react/menu.css",
+      "client": true,
       "tokens": "--menu-*",
       "props": [
         {
@@ -1810,6 +2233,7 @@
       ],
       "import": "import { Pagination } from '@pearpages/pulp-react/pagination';",
       "css": "@pearpages/pulp-react/pagination.css",
+      "client": false,
       "tokens": "--pagination-*",
       "props": [
         {
@@ -1918,6 +2342,7 @@
       ],
       "import": "import { Picker } from '@pearpages/pulp-react/picker';",
       "css": "@pearpages/pulp-react/picker.css",
+      "client": true,
       "tokens": "--picker-*",
       "props": [
         {
@@ -2056,6 +2481,7 @@
       ],
       "import": "import { Popover } from '@pearpages/pulp-react/popover';",
       "css": "@pearpages/pulp-react/popover.css",
+      "client": true,
       "tokens": "--popover-*",
       "props": [
         {
@@ -2167,6 +2593,7 @@
       ],
       "import": "import { Progress } from '@pearpages/pulp-react/progress';",
       "css": "@pearpages/pulp-react/progress.css",
+      "client": false,
       "tokens": "--progress-*",
       "props": [
         {
@@ -2252,6 +2679,7 @@
       ],
       "import": "import { RadioGroup } from '@pearpages/pulp-react/radio';",
       "css": "@pearpages/pulp-react/radio.css",
+      "client": true,
       "tokens": "--radio-*",
       "props": [
         {
@@ -2364,6 +2792,7 @@
       ],
       "import": "import { Radio } from '@pearpages/pulp-react/radio';",
       "css": "@pearpages/pulp-react/radio.css",
+      "client": true,
       "tokens": "--radio-*",
       "props": [
         {
@@ -2397,6 +2826,197 @@
       ],
       "parts": []
     },
+    {
+      "name": "SegmentedControl",
+      "description": "One choice out of a few, all visible, switching what is shown in place: a\nview mode, a unit, a sort order. Generic over a string union, so `value`\nand `onValueChange` are typed by the options. For links that navigate to\nanother page use `SegmentedControl.Nav`, which looks the same and is a `nav`.",
+      "status": "experimental",
+      "category": "Forms",
+      "accessibility": "A `radiogroup` of native radio inputs, exactly as RadioGroup: the keyboard is the browser's own (arrows move and select, Tab enters on the checked radio and leaves the group), nothing is re-implemented. Name the group with `label` or `aria-labelledby`. The inputs are visually hidden, not removed, so the focus ring is drawn on the visible segment and the control takes part in a form (`name`). Icons are decorative.",
+      "do": [
+        "Use it for two to five short options that change the view in place.",
+        "Use `SegmentedControl.Nav` when each option is a URL."
+      ],
+      "dont": [
+        "Use it for on/off; that is a Switch. For several at once, toggle Chips.",
+        "Use it for a form question with longer labels or a description; that is a RadioGroup."
+      ],
+      "import": "import { SegmentedControl } from '@pearpages/pulp-react/segmented-control';",
+      "css": "@pearpages/pulp-react/segmented-control.css",
+      "client": true,
+      "tokens": "--segmented-control-*",
+      "props": [
+        {
+          "name": "options",
+          "type": "readonly SegmentedControlOption<T>[]",
+          "required": true,
+          "default": null,
+          "description": ""
+        },
+        {
+          "name": "defaultValue",
+          "type": "string",
+          "required": false,
+          "default": null,
+          "description": "Initially selected value when uncontrolled."
+        },
+        {
+          "name": "disabled",
+          "type": "boolean",
+          "required": false,
+          "default": "false",
+          "description": ""
+        },
+        {
+          "name": "fullWidth",
+          "type": "boolean",
+          "required": false,
+          "default": "false",
+          "description": "Segments share the container's width equally. `segmented` look only."
+        },
+        {
+          "name": "label",
+          "type": "string",
+          "required": false,
+          "default": null,
+          "description": "Names the group for assistive technology. Not rendered; label it visibly with `aria-labelledby` instead when there is a heading."
+        },
+        {
+          "name": "look",
+          "type": "enum",
+          "values": [
+            "\"segmented\"",
+            "\"chips\""
+          ],
+          "required": false,
+          "default": "segmented",
+          "description": "`segmented` is one track with a raised thumb; `chips` is separate pills that wrap."
+        },
+        {
+          "name": "name",
+          "type": "string",
+          "required": false,
+          "default": null,
+          "description": "Form field name shared by the radios. Generated when omitted."
+        },
+        {
+          "name": "onValueChange",
+          "type": "((value: T) => void)",
+          "required": false,
+          "default": null,
+          "description": ""
+        },
+        {
+          "name": "ref",
+          "type": "Ref<HTMLDivElement>",
+          "required": false,
+          "default": null,
+          "description": ""
+        },
+        {
+          "name": "size",
+          "type": "enum",
+          "values": [
+            "\"sm\"",
+            "\"md\""
+          ],
+          "required": false,
+          "default": "md",
+          "description": ""
+        },
+        {
+          "name": "value",
+          "type": "string",
+          "required": false,
+          "default": null,
+          "description": "Controlled selected value."
+        }
+      ],
+      "parts": [
+        {
+          "name": "SegmentedControl.Nav",
+          "description": "The same look for links that navigate: a labelled `nav` with a list of\nlinks, the current one marked `aria-current=\"page\"`. Not a radiogroup and\nnot tabs: following a link loads another page, and a screen reader user\nshould be told so.",
+          "props": [
+            {
+              "name": "children",
+              "type": "ReactNode",
+              "required": true,
+              "default": null,
+              "description": "`SegmentedControl.NavItem`s."
+            },
+            {
+              "name": "label",
+              "type": "string",
+              "required": true,
+              "default": null,
+              "description": "Names the landmark (\"Feed view\"). Required: a page with several `nav`s needs them told apart."
+            },
+            {
+              "name": "fullWidth",
+              "type": "boolean",
+              "required": false,
+              "default": "false",
+              "description": ""
+            },
+            {
+              "name": "look",
+              "type": "enum",
+              "values": [
+                "\"segmented\"",
+                "\"chips\""
+              ],
+              "required": false,
+              "default": "segmented",
+              "description": ""
+            },
+            {
+              "name": "ref",
+              "type": "Ref<HTMLElement>",
+              "required": false,
+              "default": null,
+              "description": ""
+            },
+            {
+              "name": "size",
+              "type": "enum",
+              "values": [
+                "\"sm\"",
+                "\"md\""
+              ],
+              "required": false,
+              "default": "md",
+              "description": ""
+            }
+          ]
+        },
+        {
+          "name": "SegmentedControl.NavItem",
+          "description": "One link of a `SegmentedControl.Nav`. With `asChild`, the router's own link takes the styles.",
+          "props": [
+            {
+              "name": "asChild",
+              "type": "boolean",
+              "required": false,
+              "default": "false",
+              "description": "Render the single child instead of an `a`: a router's link component."
+            },
+            {
+              "name": "current",
+              "type": "boolean",
+              "required": false,
+              "default": "false",
+              "description": "This link is the page being shown: `aria-current=\"page\"` and the selected look."
+            },
+            {
+              "name": "ref",
+              "type": "Ref<E>",
+              "required": false,
+              "default": null,
+              "description": ""
+            }
+          ]
+        }
+      ]
+    },
     {
       "name": "Select",
       "description": "A native `<select>` on top of Field: the browser's own popup, keyboard and\nassistive-technology support, with the closed control drawn from\n`--select-*` tokens. For rich options or multi-select, a listbox component\ncomes later on a headless layer; this one stays native on purpose.",
@@ -2411,6 +3031,7 @@
       ],
       "import": "import { Select } from '@pearpages/pulp-react/select';",
       "css": "@pearpages/pulp-react/select.css",
+      "client": true,
       "tokens": "--select-*",
       "props": [
         {
@@ -2482,7 +3103,7 @@
       "description": "A dialog docked to an edge of the viewport: a side panel for detail or settings that keeps the\npage in view, or a bottom sheet on a phone. It is Dialog with a `placement`: the same parts\n(`Sheet.Trigger`, `Sheet.Content`, `Sheet.Header`, `Sheet.Title`, `Sheet.Description`,\n`Sheet.Close`, `Sheet.Body`, `Sheet.Footer`), the same focus trap, stacking and dismissal, and\nthe same colours and type, from Dialog's tokens. Only the size is Sheet's: `--sheet-width`,\n`--sheet-height` and `--sheet-motion-translate`, the distance it slides in from its edge.\n\nIt needs what Dialog needs: `DialogSystem` mounted once near the app root, and\n`@pearpages/modals/styles.css` imported into the `vendor` layer.",
       "status": "experimental",
       "category": "Overlays",
-      "accessibility": "Dialog's: `role=\"dialog\"` with `aria-modal`, named by `Sheet.Title` and described by `Sheet.Description`; focus moves in on open, is trapped, and returns to the trigger on close; Escape and the backdrop dismiss it; the page behind is inert. Docking changes the layout only, never the semantics.",
+      "accessibility": "The drag handle of a bottom sheet is a pointer and touch shortcut, hidden from assistive technology and not focusable: it adds no keyboard stop, and closing by keyboard stays Escape or `Sheet.Close`, so always render a `Sheet.Close` in a sheet that can be dragged. Otherwise Dialog's: `role=\"dialog\"` with `aria-modal`, named by `Sheet.Title` and described by `Sheet.Description`; focus moves in on open, is trapped, and returns to the trigger on close; Escape and the backdrop dismiss it; the page behind is inert. Docking changes the layout only, never the semantics.",
       "do": [
         "Always render a `Sheet.Title`.",
         "Dock to `end` for detail and settings beside the page, and to `bottom` for choices on a narrow screen."
@@ -2493,6 +3114,7 @@
       ],
       "import": "import { Sheet } from '@pearpages/pulp-react/sheet';",
       "css": "@pearpages/pulp-react/sheet.css",
+      "client": true,
       "tokens": "--sheet-*",
       "props": [
         {
@@ -2564,6 +3186,13 @@
               "default": null,
               "description": "Whether pressing Esc closes topmost modal (default: true)"
             },
+            {
+              "name": "dragToDismiss",
+              "type": "boolean",
+              "required": false,
+              "default": "true",
+              "description": "`placement=\"bottom\"` only: a grab handle at the top of the sheet that can be dragged down to\nclose it (past a quarter of the sheet's height, or with a flick). Pointer and touch only, and\noff under `prefers-reduced-motion`; Escape, the backdrop and `Sheet.Close` are unchanged."
+            },
             {
               "name": "onInteractOutside",
               "type": "((e: { target: EventTarget; preventDefault(): void; }) => void)",
@@ -2616,6 +3245,7 @@
       ],
       "import": "import { Skeleton } from '@pearpages/pulp-react/skeleton';",
       "css": "@pearpages/pulp-react/skeleton.css",
+      "client": false,
       "tokens": "--skeleton-*",
       "props": [
         {
@@ -2675,6 +3305,7 @@
       ],
       "import": "import { Slider } from '@pearpages/pulp-react/slider';",
       "css": "@pearpages/pulp-react/slider.css",
+      "client": true,
       "tokens": "--slider-*",
       "props": [
         {
@@ -2824,6 +3455,7 @@
       ],
       "import": "import { Spinner } from '@pearpages/pulp-react/spinner';",
       "css": "@pearpages/pulp-react/spinner.css",
+      "client": false,
       "tokens": "--spinner-*",
       "props": [
         {
@@ -2888,6 +3520,7 @@
       ],
       "import": "import { Stack } from '@pearpages/pulp-react/stack';",
       "css": "@pearpages/pulp-react/stack.css",
+      "client": false,
       "tokens": "--stack-*",
       "props": [
         {
@@ -2972,6 +3605,7 @@
       ],
       "import": "import { Switch } from '@pearpages/pulp-react/switch';",
       "css": "@pearpages/pulp-react/switch.css",
+      "client": true,
       "tokens": "--switch-*",
       "props": [
         {
@@ -3040,6 +3674,7 @@
       ],
       "import": "import { Table } from '@pearpages/pulp-react/table';",
       "css": "@pearpages/pulp-react/table.css",
+      "client": true,
       "tokens": "--table-*",
       "props": [
         {
@@ -3333,6 +3968,7 @@
       ],
       "import": "import { Tabs } from '@pearpages/pulp-react/tabs';",
       "css": "@pearpages/pulp-react/tabs.css",
+      "client": true,
       "tokens": "--tabs-*",
       "props": [
         {
@@ -3456,6 +4092,7 @@
       ],
       "import": "import { Text } from '@pearpages/pulp-react/text';",
       "css": "@pearpages/pulp-react/text.css",
+      "client": false,
       "tokens": "--text-*",
       "props": [
         {
@@ -3556,10 +4193,11 @@
       "description": "A single-line text input on top of `Field`: label, description and error\nwired for assistive technology. Controlled and uncontrolled behave exactly\nlike the native input (`value`/`onChange` or `defaultValue`). Every value\ncomes from `--text-field-*` and `--field-*` tokens; state is exposed as\n`data-size`, `data-invalid`, `data-disabled` and `data-readonly` on the\nwrapper.",
       "status": "stable",
       "category": "Forms",
-      "accessibility": "A native text `input` wired through Field: `label[for]`, `aria-describedby` for description and error, `aria-invalid` and `aria-required`. Everything the browser gives a native input (autofill, IME, forms) applies.",
+      "accessibility": "A native text `input` wired through Field: `label[for]`, `aria-describedby` for description and error, `aria-invalid` and `aria-required`. Everything the browser gives a native input (autofill, IME, forms) applies. `hideLabel` hides the label visually, never from assistive technology. The leading icon is decorative. The clear button is a real `button` named by `clearLabel`, after the input in the tab order, present only while there is a value; pressing it (or Escape in the field) empties the field and leaves focus in the input. `type=\"search\"` gives the input the `searchbox` role; wrap the form in `<search>` or `role=\"search\"` yourself when it is the page's search.",
       "do": [
         "Always pass `label`; use a visible one.",
-        "Prefer `error` text that says how to fix the value."
+        "Prefer `error` text that says how to fix the value.",
+        "For a search box: `type=\"search\"`, `hideLabel` if a heading names it, and `onClear`."
       ],
       "dont": [
         "Use `placeholder` as the label.",
@@ -3567,6 +4205,7 @@
       ],
       "import": "import { TextField } from '@pearpages/pulp-react/text-field';",
       "css": "@pearpages/pulp-react/text-field.css",
+      "client": true,
       "tokens": "--text-field-*",
       "props": [
         {
@@ -3583,6 +4222,13 @@
           "default": null,
           "description": "Applied to the wrapper, not the input."
         },
+        {
+          "name": "clearLabel",
+          "type": "string",
+          "required": false,
+          "default": "Clear",
+          "description": "The clear button's name, for other languages."
+        },
         {
           "name": "description",
           "type": "ReactNode",
@@ -3597,6 +4243,27 @@
           "default": null,
           "description": "Error message. Its presence marks the input invalid (`aria-invalid`,\n`data-invalid`) and the message is announced as an alert."
         },
+        {
+          "name": "hideLabel",
+          "type": "boolean",
+          "required": false,
+          "default": "false",
+          "description": "Keeps the label for assistive technology only. For a search box that a heading or its place in the page already names."
+        },
+        {
+          "name": "iconStart",
+          "type": "ReactNode",
+          "required": false,
+          "default": null,
+          "description": "A decorative glyph inside the field, before the text. `type=\"search\"` gets the Search glyph unless you pass another (or `null`)."
+        },
+        {
+          "name": "onClear",
+          "type": "(() => void)",
+          "required": false,
+          "default": null,
+          "description": "Adds a clear button that appears once the field has a value. Called when it\nis pressed and when Escape is pressed with a value. Controlled: set your\nvalue to `''` here. Uncontrolled: the input is emptied for you."
+        },
         {
           "name": "ref",
           "type": "Ref<HTMLInputElement>",
@@ -3633,6 +4300,7 @@
       ],
       "import": "import { Textarea } from '@pearpages/pulp-react/textarea';",
       "css": "@pearpages/pulp-react/textarea.css",
+      "client": true,
       "tokens": "--textarea-*",
       "props": [
         {
@@ -3706,7 +4374,7 @@
     },
     {
       "name": "ToastProvider",
-      "description": "Mount once near the app root. Owns a portal element with a polite live\nregion; `useToast()` adds notifications to it. Timers pause while the\nregion is hovered or holds focus, Escape dismisses the focused toast, and\nerror toasts stay until dismissed. Each toast is an Alert.",
+      "description": "Mount once near the app root. Owns a portal element with a polite live\nregion; `useToast()` adds notifications to it. Timers pause while the\nregion is hovered or holds focus, Escape dismisses the focused toast, and\nerror toasts stay until dismissed. Each toast is an Alert.\n`toast.undo(message, onUndo)` is the shorthand for a reversible action.",
       "status": "stable",
       "category": "Feedback",
       "accessibility": "Owns a `region` named \"Notifications\" with `aria-live=\"polite\"`; each toast is an Alert with its live role off (the region announces). Timers pause while the region is hovered or holds focus; Escape dismisses the focused toast; error toasts stay until dismissed.",
@@ -3720,6 +4388,7 @@
       ],
       "import": "import { ToastProvider } from '@pearpages/pulp-react/toast';",
       "css": "@pearpages/pulp-react/toast.css",
+      "client": true,
       "tokens": "--toast-*",
       "props": [
         {
@@ -3773,6 +4442,7 @@
       ],
       "import": "import { Tooltip } from '@pearpages/pulp-react/tooltip';",
       "css": "@pearpages/pulp-react/tooltip.css",
+      "client": true,
       "tokens": "--tooltip-*",
       "props": [
         {
@@ -3830,6 +4500,7 @@
       ],
       "import": "import { VisuallyHidden } from '@pearpages/pulp-react/visually-hidden';",
       "css": "@pearpages/pulp-react/visually-hidden.css",
+      "client": false,
       "tokens": "--visually-hidden-*",
       "props": [
         {