@handamade/psi-react 0.25.0 → 0.27.0

package/dist/manifest.json

@@ -231,6 +231,118 @@
         }
       ]
     },
+    {
+      "name": "Stack",
+      "description": "A column with a gap from the space scale (D109): Toolbar's vertical counterpart, minus the wrap. A plain <div> with no role. It gives a pattern tree a layout context, which Panel and the psi-gap-* utilities do not.",
+      "slots": [
+        {
+          "name": "body",
+          "accepts": {},
+          "cardinality": "0..*",
+          "order": 1
+        }
+      ],
+      "props": [
+        {
+          "name": "children",
+          "type": "ReactNode",
+          "required": false,
+          "default": null,
+          "description": "Stack contents, laid out top to bottom."
+        },
+        {
+          "name": "gap",
+          "type": "4 | 8 | 12 | 16 | 24 | 32",
+          "required": false,
+          "default": 16,
+          "description": "Space between children in px, from the space scale."
+        },
+        {
+          "name": "align",
+          "type": "\"stretch\" | \"start\" | \"center\" | \"end\"",
+          "required": false,
+          "default": "stretch",
+          "description": "Cross-axis alignment. `stretch` (the default) makes each child full\nwidth; `start` keeps a Button or a short line at its own width."
+        },
+        {
+          "name": "ref",
+          "type": "Ref<HTMLDivElement>",
+          "required": false,
+          "default": null,
+          "description": "Forwarded ref to the root element."
+        },
+        {
+          "name": "className",
+          "type": "string",
+          "required": false,
+          "default": null,
+          "description": "Additional CSS class name(s) merged onto the component's root element."
+        }
+      ]
+    },
+    {
+      "name": "Text",
+      "description": "A line or paragraph of text at one of Psi's text styles (D109). It gives a pattern tree an element per line, so a headline and its explanation do not run together. Margin 0: a Stack's gap does the spacing.",
+      "slots": [
+        {
+          "name": "body",
+          "accepts": {},
+          "cardinality": "0..*",
+          "order": 1
+        }
+      ],
+      "props": [
+        {
+          "name": "children",
+          "type": "ReactNode",
+          "required": false,
+          "default": null,
+          "description": "The text."
+        },
+        {
+          "name": "as",
+          "type": "\"p\" | \"span\" | \"div\" | \"h2\" | \"h3\" | \"h4\"",
+          "required": false,
+          "default": "p",
+          "description": "The element. A heading's level follows the document outline, its size\nthe design, so `as` and `size` are separate."
+        },
+        {
+          "name": "size",
+          "type": "12 | 14 | 16 | 18",
+          "required": false,
+          "default": 14,
+          "description": "Font size in px; each size carries its own line height."
+        },
+        {
+          "name": "weight",
+          "type": "\"regular\" | \"medium\"",
+          "required": false,
+          "default": "regular",
+          "description": ""
+        },
+        {
+          "name": "tone",
+          "type": "\"primary\" | \"secondary\"",
+          "required": false,
+          "default": "primary",
+          "description": "`secondary` for supporting text."
+        },
+        {
+          "name": "ref",
+          "type": "Ref<HTMLElement>",
+          "required": false,
+          "default": null,
+          "description": "Forwarded ref to the element."
+        },
+        {
+          "name": "className",
+          "type": "string",
+          "required": false,
+          "default": null,
+          "description": "Additional CSS class name(s) merged onto the component's root element."
+        }
+      ]
+    },
     {
       "name": "DescriptionList",
       "description": "Key/value display (D70): a `<dl>` of term/value pairs, the body `detail-drawer` has always described and never had a component for. No `size` prop — this is type, and the type scale is already expressed by --psi-text-*. Consumers restyle via the token family, not a prop.",
@@ -602,7 +714,28 @@
           "type": "boolean",
           "required": false,
           "default": true,
-          "description": "false = no close button, Esc and backdrop swallowed — footer is the only exit."
+          "description": "false = no close button, Esc and backdrop swallowed — footer is the only exit.\n`closeOnEscape` can give Escape back on its own (D101)."
+        },
+        {
+          "name": "closeOnEscape",
+          "type": "boolean",
+          "required": false,
+          "default": "dismissible",
+          "description": "Whether Escape reports onClose(\"esc\"), separately from the close button\nand the backdrop (D101). A consequential confirmation is\n`dismissible={false} closeOnEscape`: no close button, no backdrop\ndismissal, and Escape cancels."
+        },
+        {
+          "name": "initialFocus",
+          "type": "RefObject<HTMLElement | null>",
+          "required": false,
+          "default": null,
+          "description": "The element to focus each time the dialog opens, after the platform's own\nfocusing (D101), e.g. a ref to the footer's Cancel button. Without it, the\nplatform focuses the first focusable control, as before."
+        },
+        {
+          "name": "closeLabel",
+          "type": "string",
+          "required": false,
+          "default": null,
+          "description": "Visible text for the close button (D101). When set, the close button is a\nghost Button with this text instead of the icon-only \"Close dialog\"\nbutton."
         },
         {
           "name": "ref",
@@ -622,7 +755,7 @@
     },
     {
       "name": "Checkbox",
-      "description": "Native checkbox with a built-in label; for independent binary choices.",
+      "description": "Native checkbox with a built-in label; for independent binary choices. In an invalid group Field it is aria-invalid, and an unchecked box marked aria-invalid outlines in the error colour (D108).",
       "slots": [],
       "props": [
         {
@@ -639,6 +772,13 @@
           "default": null,
           "description": "Accessible name when there is no visible label — a table's row-selection\ncheckbox, say. Optional, unlike IconButton's required form (D60): a\nlabelled checkbox is still the common case."
         },
+        {
+          "name": "indeterminate",
+          "type": "boolean",
+          "required": false,
+          "default": null,
+          "description": "The mixed state, e.g. a \"select all\" over a partial selection (D103).\nSets the input's DOM property, which the platform exposes as\naria-checked=\"mixed\", and draws a dash. Re-applied on every render,\nbecause a click clears the property before the consumer re-renders.\nWhen absent, the property is left alone, so a state set through the ref\nsurvives."
+        },
         {
           "name": "ref",
           "type": "Ref<HTMLInputElement>",
@@ -683,6 +823,199 @@
         }
       ]
     },
+    {
+      "name": "Textarea",
+      "description": "Multi-line text input (D104): the Input recipe on a native `<textarea>`. Inside a Field, id/aria-describedby/aria-invalid/required are wired as for Input (D49). `minLength` and `maxLength` are the native attributes. With `maxLength`, a counter under the control shows the length; it is not a live region (a count spoken on every keystroke is noise) and joins aria-describedby, so it is read with the field on focus.",
+      "slots": [],
+      "props": [
+        {
+          "name": "rows",
+          "type": "number",
+          "required": false,
+          "default": 3,
+          "description": "Visible rows. A textarea's height is its rows; there is no `size`."
+        },
+        {
+          "name": "minLength",
+          "type": "number",
+          "required": false,
+          "default": null,
+          "description": "Native minimum length, reported by constraint validation."
+        },
+        {
+          "name": "maxLength",
+          "type": "number",
+          "required": false,
+          "default": null,
+          "description": "Native maximum length, enforced while typing. With it, the counter shows\n`{length} / {maxLength}` unless `showCounter={false}`."
+        },
+        {
+          "name": "error",
+          "type": "boolean",
+          "required": false,
+          "default": false,
+          "description": "Show error styling. Inside a Field, the Field's error also lights this."
+        },
+        {
+          "name": "showCounter",
+          "type": "boolean",
+          "required": false,
+          "default": true,
+          "description": "With `maxLength`, show the `{length} / {maxLength}` counter under the\ncontrol. It is not a live region; it describes the textarea."
+        },
+        {
+          "name": "ref",
+          "type": "Ref<HTMLTextAreaElement>",
+          "required": false,
+          "default": null,
+          "description": "Forwarded ref to the underlying `<textarea>` element."
+        },
+        {
+          "name": "placeholder",
+          "type": "string",
+          "required": false,
+          "default": null,
+          "description": "Native placeholder text shown while the field is empty (only on components whose host element supports it)."
+        },
+        {
+          "name": "className",
+          "type": "string",
+          "required": false,
+          "default": null,
+          "description": "Additional CSS class name(s) merged onto the component's root element."
+        }
+      ]
+    },
+    {
+      "name": "RadioGroup",
+      "description": "A set of native radios sharing one name (D104). The browser supplies the keyboard: Tab enters on the checked radio, and the arrows move and select. Inside `Field group` the fieldset and legend form and name the group, so this adds no role; standalone it is `role=\"radiogroup\"` and needs `aria-label` or `aria-labelledby`. A required or invalid Field makes every radio `required` and `aria-invalid`.",
+      "slots": [
+        {
+          "name": "body",
+          "accepts": {
+            "components": [
+              "Radio"
+            ]
+          },
+          "cardinality": "1..*",
+          "order": 1
+        }
+      ],
+      "props": [
+        {
+          "name": "children",
+          "type": "ReactNode",
+          "required": false,
+          "default": null,
+          "description": "`Radio` children."
+        },
+        {
+          "name": "name",
+          "type": "string",
+          "required": false,
+          "default": null,
+          "description": "The radios' shared `name`. Generated when absent."
+        },
+        {
+          "name": "value",
+          "type": "string",
+          "required": false,
+          "default": null,
+          "description": "The selected value (controlled)."
+        },
+        {
+          "name": "defaultValue",
+          "type": "string",
+          "required": false,
+          "default": null,
+          "description": "The initially selected value (uncontrolled)."
+        },
+        {
+          "name": "onValueChange",
+          "type": "((value: string) => void)",
+          "required": false,
+          "default": null,
+          "description": "Called with the value of the radio the user selects."
+        },
+        {
+          "name": "disabled",
+          "type": "boolean",
+          "required": false,
+          "default": false,
+          "description": "Disables every radio in the group."
+        },
+        {
+          "name": "orientation",
+          "type": "\"vertical\" | \"horizontal\"",
+          "required": false,
+          "default": "vertical",
+          "description": "Stack the radios, or lay them in a row."
+        },
+        {
+          "name": "aria-label",
+          "type": "string",
+          "required": false,
+          "default": null,
+          "description": "Accessible name when the group stands alone. Inside `Field group` the\nlegend names the group instead."
+        },
+        {
+          "name": "ref",
+          "type": "Ref<HTMLDivElement>",
+          "required": false,
+          "default": null,
+          "description": "Forwarded ref to the root element."
+        },
+        {
+          "name": "className",
+          "type": "string",
+          "required": false,
+          "default": null,
+          "description": "Additional CSS class name(s) merged onto the component's root element."
+        }
+      ]
+    },
+    {
+      "name": "Radio",
+      "description": "One choice in a RadioGroup (D104): a native radio with a built-in label, drawn like Checkbox on a circle. Takes its name, checked state, required and aria-invalid from the group.",
+      "slots": [],
+      "props": [
+        {
+          "name": "value",
+          "type": "string",
+          "required": true,
+          "default": null,
+          "description": "The value this radio selects."
+        },
+        {
+          "name": "children",
+          "type": "ReactNode",
+          "required": false,
+          "default": null,
+          "description": "Label text."
+        },
+        {
+          "name": "disabled",
+          "type": "boolean",
+          "required": false,
+          "default": null,
+          "description": "Disables this radio; a disabled RadioGroup disables all of them."
+        },
+        {
+          "name": "className",
+          "type": "string",
+          "required": false,
+          "default": null,
+          "description": "Additional CSS class name(s) merged onto the component's root element."
+        },
+        {
+          "name": "ref",
+          "type": "Ref<HTMLInputElement>",
+          "required": false,
+          "default": null,
+          "description": "Forwarded ref to the underlying `<input type=\"radio\">` element."
+        }
+      ]
+    },
     {
       "name": "Tag",
       "description": "Compact label for status or category; semantic variants, optional subtle tint and dismiss button.",
@@ -805,7 +1138,7 @@
           "type": "ReactElement<Record<string, unknown>, string | JSXElementConstructor<any>>",
           "required": true,
           "default": null,
-          "description": "The trigger element (must accept ref, onMouseEnter/Leave, onFocus/Blur)."
+          "description": "The trigger element (must accept onFocus/Blur)."
         },
         {
           "name": "placement",
@@ -1243,10 +1576,10 @@
         },
         {
           "name": "onClose",
-          "type": "(reason: \"item-select\" | \"esc\" | \"outside\") => void",
+          "type": "(reason: MenuCloseReason) => void",
           "required": true,
           "default": null,
-          "description": "Called when a dismissal is *requested*; the consumer flips `open`.\n\nMenu never closes itself on `\"esc\"` or `\"item-select\"` — the popover stays\nopen until `open` becomes false (D50). `\"outside\"` is the one exception:\nlight dismiss is performed by the browser before it tells us, so by the\ntime that reason is reported the popover is already closed. Flipping\n`open` to false is still required, to keep React's state in step.\n\nInvariant (D58): a dismissal is only ever reported for a menu that is\ncurrently open according to its own `open` prop. The platform can close\nan auto popover before the consumer's state catches up — clicking another\nmenu's trigger light-dismisses this one before the consumer's click\nhandler runs — and a report for an already-closed menu would clear a\nselection that has since moved on."
+          "description": "Called when a dismissal is *requested*; the consumer flips `open`.\n\nMenu never closes itself on `\"esc\"` or `\"item-select\"` — the popover stays\nopen until `open` becomes false (D50). `\"outside\"` is the one exception:\nlight dismiss is performed by the browser before it tells us, so by the\ntime that reason is reported the popover is already closed. Flipping\n`open` to false is still required, to keep React's state in step.\n\nInvariant (D58): a dismissal is only ever reported for a menu that is\ncurrently open according to its own `open` prop. The platform can close\nan auto popover before the consumer's state catches up — clicking another\nmenu's trigger light-dismisses this one before the consumer's click\nhandler runs — and a report for an already-closed menu would clear a\nselection that has since moved on.\n\n`\"tab\"` (D102): Tab or Shift Tab inside the open menu. Focus moves on to\nthe next control as the browser moves it; the consumer flips `open`."
         },
         {
           "name": "trigger",
@@ -1262,6 +1595,13 @@
           "default": "bottom-start",
           "description": "Placement relative to the trigger."
         },
+        {
+          "name": "id",
+          "type": "string",
+          "required": false,
+          "default": null,
+          "description": "The menu element's id, which the trigger's `aria-controls` names (D102).\nGenerated when absent."
+        },
         {
           "name": "aria-label",
           "type": "string",

package/dist/patterns.json

@@ -846,14 +846,39 @@
         },
         "slots": {
           "body": [
-            "{content:headline}",
-            "{content:explanation}",
             {
-              "component": "Button",
+              "component": "Stack",
               "props": {
-                "variant": "neutral"
+                "gap": 8,
+                "align": "start"
               },
-              "content": "reset-label"
+              "slots": {
+                "body": [
+                  {
+                    "component": "Text",
+                    "props": {
+                      "as": "h3",
+                      "size": 16,
+                      "weight": "medium"
+                    },
+                    "content": "headline"
+                  },
+                  {
+                    "component": "Text",
+                    "props": {
+                      "tone": "secondary"
+                    },
+                    "content": "explanation"
+                  },
+                  {
+                    "component": "Button",
+                    "props": {
+                      "variant": "neutral"
+                    },
+                    "content": "reset-label"
+                  }
+                ]
+              }
             }
           ]
         }
@@ -866,7 +891,129 @@
       },
       "gaps": [],
       "blocked": false,
-      "preset": "<Panel\n  padding={24}\n>\n  [nothing matches these filters]\n  [say whether the dataset is empty or the filters are too narrow]\n  <Button variant=\"neutral\">Clear filters</Button>\n</Panel>\n"
+      "preset": "<Panel\n  padding={24}\n>\n  <Stack\n    align=\"start\"\n    gap={8}\n  >\n    <Text as=\"h3\" size={16} weight=\"medium\">[nothing matches these filters]</Text>\n    <Text tone=\"secondary\">[say whether the dataset is empty or the filters are too narrow]</Text>\n    <Button variant=\"neutral\">Clear filters</Button>\n  </Stack>\n</Panel>\n"
+    },
+    {
+      "id": "feedback-form",
+      "intent": "A short report form: a required choice of category as radios, a bounded description with a length counter, and a submit button",
+      "match": [
+        "feedback form",
+        "report a problem",
+        "radio buttons",
+        "text area",
+        "character counter"
+      ],
+      "compose": {
+        "component": "Panel",
+        "props": {
+          "padding": 24
+        },
+        "slots": {
+          "body": [
+            {
+              "component": "Stack",
+              "props": {
+                "gap": 24
+              },
+              "slots": {
+                "body": [
+                  {
+                    "component": "Field",
+                    "props": {
+                      "group": true,
+                      "required": true,
+                      "requiredText": "(Required)"
+                    },
+                    "slots": {
+                      "label": [
+                        "{content:category-label}"
+                      ],
+                      "body": [
+                        {
+                          "component": "RadioGroup",
+                          "slots": {
+                            "body": [
+                              {
+                                "component": "Radio",
+                                "props": {
+                                  "value": "problem"
+                                },
+                                "content": "first-option"
+                              },
+                              {
+                                "component": "Radio",
+                                "props": {
+                                  "value": "idea"
+                                },
+                                "content": "second-option"
+                              },
+                              {
+                                "component": "Radio",
+                                "props": {
+                                  "value": "other"
+                                },
+                                "content": "third-option"
+                              }
+                            ]
+                          }
+                        }
+                      ]
+                    }
+                  },
+                  {
+                    "component": "Field",
+                    "slots": {
+                      "label": [
+                        "{content:description-label}"
+                      ],
+                      "body": [
+                        {
+                          "component": "Textarea",
+                          "props": {
+                            "maxLength": 500,
+                            "rows": 4
+                          }
+                        }
+                      ],
+                      "description": [
+                        "{content:description-help}"
+                      ]
+                    }
+                  },
+                  {
+                    "component": "Toolbar",
+                    "slots": {
+                      "body": [
+                        {
+                          "component": "Button",
+                          "props": {
+                            "type": "submit",
+                            "variant": "accent"
+                          },
+                          "content": "submit-label"
+                        }
+                      ]
+                    }
+                  }
+                ]
+              }
+            }
+          ]
+        }
+      },
+      "parameters": [],
+      "content": {
+        "category-label": "Category",
+        "first-option": "Something is broken",
+        "second-option": "An idea",
+        "third-option": "Something else",
+        "description-label": "Description",
+        "description-help": "[what happened, and what you expected]",
+        "submit-label": "Send"
+      },
+      "gaps": [],
+      "blocked": false,
+      "preset": "<Panel\n  padding={24}\n>\n  <Stack\n    gap={24}\n  >\n    <Field\n      group={true}\n      label=\"Category\"\n      required={true}\n      requiredText=\"(Required)\"\n    >\n      <RadioGroup>\n        <Radio value=\"problem\">Something is broken</Radio>\n        <Radio value=\"idea\">An idea</Radio>\n        <Radio value=\"other\">Something else</Radio>\n      </RadioGroup>\n    </Field>\n    <Field\n      description=\"[what happened, and what you expected]\"\n      label=\"Description\"\n    >\n      <Textarea maxLength={500} rows={4} />\n    </Field>\n    <Toolbar>\n      <Button type=\"submit\" variant=\"accent\">Send</Button>\n    </Toolbar>\n  </Stack>\n</Panel>\n"
     },
     {
       "id": "filter-form",