@handamade/psi-react 0.20.0 → 0.22.0

package/dist/patterns.json

@@ -51,6 +51,233 @@
       "blocked": false,
       "preset": "<Toast action={<Button variant=\"ghost\">Undo</Button>} variant=\"success\">[what just happened]</Toast>\n"
     },
+    {
+      "id": "announcer",
+      "intent": "Under a ToastProvider, do not render this — call useToast().announce() (D91). For an application with its own ToastRegion and no provider: one region holding visible toasts and speech-only Announcements, each routed by politeness rather than by tone. For a single confirmation toast, use action-feedback.",
+      "match": [
+        "announcer",
+        "live region",
+        "screen reader announcement",
+        "aria-live",
+        "status message",
+        "announce without a toast",
+        "polite and assertive"
+      ],
+      "compose": {
+        "component": "ToastRegion",
+        "slots": {
+          "body": [
+            {
+              "component": "Toast",
+              "props": {
+                "variant": "success",
+                "politeness": "{param:outcome-politeness}"
+              },
+              "slots": {
+                "body": [
+                  "{content:outcome}"
+                ]
+              }
+            },
+            {
+              "component": "Announcement",
+              "props": {
+                "politeness": "polite"
+              },
+              "slots": {
+                "body": [
+                  "{content:state-change}"
+                ]
+              }
+            },
+            {
+              "component": "Announcement",
+              "props": {
+                "politeness": "assertive"
+              },
+              "slots": {
+                "body": [
+                  "{content:field-errors}"
+                ]
+              }
+            }
+          ]
+        }
+      },
+      "parameters": [
+        {
+          "key": "outcome-politeness",
+          "ask": "Should the outcome of the user's own action interrupt, success included?",
+          "options": [
+            "assertive",
+            "polite"
+          ],
+          "default": "assertive"
+        }
+      ],
+      "content": {
+        "outcome": "[the outcome of the action the user just took]",
+        "state-change": "[a change to the object on screen, spoken and not shown]",
+        "field-errors": "[how many fields need attention, spoken after a failed submission]"
+      },
+      "gaps": [],
+      "blocked": false,
+      "preset": "<ToastRegion>\n  <Toast politeness=\"assertive\" variant=\"success\">[the outcome of the action the user just took]</Toast>\n  <Announcement politeness=\"polite\">[a change to the object on screen, spoken and not shown]</Announcement>\n  <Announcement politeness=\"assertive\">[how many fields need attention, spoken after a failed submission]</Announcement>\n</ToastRegion>\n"
+    },
+    {
+      "id": "app-shell",
+      "intent": "An application frame: a skip link, a full-width header with a Menu toggle that names the sidebar (aria-expanded and aria-controls — wire both and sidebarOpen to one piece of state), a dark sub-themed sidebar holding a NavTree, and a main region that scrolls on its own so nothing hides under the header. A closed sidebar is hidden, not narrowed. A desktop frame, not a responsive drawer. Put a link of your own router in each NavItem instead of href, and aria-current=\"page\" on the current one",
+      "match": [
+        "app shell",
+        "application shell",
+        "sidebar layout",
+        "admin layout",
+        "side navigation"
+      ],
+      "compose": {
+        "component": "AppShell",
+        "props": {
+          "sidebarOpen": true,
+          "sidebarTheme": "dark"
+        },
+        "slots": {
+          "skipLink": [
+            {
+              "component": "SkipLink",
+              "props": {
+                "href": "#main"
+              },
+              "content": "skip-label"
+            }
+          ],
+          "header": [
+            {
+              "component": "NavBar",
+              "props": {
+                "fluid": true
+              },
+              "slots": {
+                "brand": [
+                  {
+                    "component": "Button",
+                    "props": {
+                      "variant": "ghost",
+                      "size": 32,
+                      "aria-expanded": true,
+                      "aria-controls": "sidebar"
+                    },
+                    "content": "menu-label"
+                  },
+                  "{content:brand}"
+                ],
+                "actions": [
+                  {
+                    "component": "Button",
+                    "props": {
+                      "variant": "neutral",
+                      "size": 32
+                    },
+                    "content": "account-label"
+                  }
+                ]
+              }
+            }
+          ],
+          "sidebar": [
+            {
+              "component": "NavTree",
+              "props": {
+                "aria-label": "{content:nav-label}"
+              },
+              "slots": {
+                "body": [
+                  {
+                    "component": "NavItem",
+                    "props": {
+                      "href": "#overview",
+                      "current": true
+                    },
+                    "content": "overview-label"
+                  },
+                  {
+                    "component": "NavGroup",
+                    "props": {
+                      "label": "{content:group-1-label}",
+                      "open": true
+                    },
+                    "slots": {
+                      "body": [
+                        {
+                          "component": "NavItem",
+                          "props": {
+                            "href": "#group-1-first"
+                          },
+                          "content": "group-1-first-label"
+                        },
+                        {
+                          "component": "NavItem",
+                          "props": {
+                            "href": "#group-1-second"
+                          },
+                          "content": "group-1-second-label"
+                        }
+                      ]
+                    }
+                  },
+                  {
+                    "component": "NavGroup",
+                    "props": {
+                      "label": "{content:group-2-label}",
+                      "open": true
+                    },
+                    "slots": {
+                      "body": [
+                        {
+                          "component": "NavItem",
+                          "props": {
+                            "href": "#group-2-first"
+                          },
+                          "content": "group-2-first-label"
+                        },
+                        {
+                          "component": "NavItem",
+                          "props": {
+                            "href": "#group-2-second"
+                          },
+                          "content": "group-2-second-label"
+                        }
+                      ]
+                    }
+                  }
+                ]
+              }
+            }
+          ],
+          "body": [
+            "{content:page}"
+          ]
+        }
+      },
+      "parameters": [],
+      "content": {
+        "skip-label": "Skip to content",
+        "menu-label": "Menu",
+        "brand": "[product name]",
+        "account-label": "[account]",
+        "nav-label": "Main",
+        "overview-label": "Overview",
+        "group-1-label": "[group name]",
+        "group-1-first-label": "[page name]",
+        "group-1-second-label": "[page name]",
+        "group-2-label": "[group name]",
+        "group-2-first-label": "[page name]",
+        "group-2-second-label": "[page name]",
+        "page": "[the page; it scrolls on its own]"
+      },
+      "gaps": [],
+      "blocked": false,
+      "preset": "<AppShell\n  header={<NavBar\n    actions={<Button size={32} variant=\"neutral\">[account]</Button>}\n    brand={<>\n      <Button aria-controls=\"sidebar\" aria-expanded={true} size={32} variant=\"ghost\">Menu</Button>\n      [product name]\n    </>}\n    fluid={true}\n  />}\n  sidebar={<NavTree\n    aria-label=\"Main\"\n  >\n    <NavItem current={true} href=\"#overview\">Overview</NavItem>\n    <NavGroup\n      label=\"[group name]\"\n      open={true}\n    >\n      <NavItem href=\"#group-1-first\">[page name]</NavItem>\n      <NavItem href=\"#group-1-second\">[page name]</NavItem>\n    </NavGroup>\n    <NavGroup\n      label=\"[group name]\"\n      open={true}\n    >\n      <NavItem href=\"#group-2-first\">[page name]</NavItem>\n      <NavItem href=\"#group-2-second\">[page name]</NavItem>\n    </NavGroup>\n  </NavTree>}\n  sidebarOpen={true}\n  sidebarTheme=\"dark\"\n  skipLink={<SkipLink href=\"#main\">Skip to content</SkipLink>}\n>\n  [the page; it scrolls on its own]\n</AppShell>\n"
+    },
     {
       "id": "bulk-action-bar",
       "intent": "Bar that appears when table rows are selected: selection count, bulk actions, and a clear-selection control",
@@ -110,9 +337,110 @@
       "blocked": false,
       "preset": "<Toolbar\n  gap={12}\n>\n  <Tag subtle={true} variant=\"accent\">[n] selected</Tag>\n  <Button variant=\"neutral\">Export</Button>\n  <Button variant=\"danger-subtle\">Delete</Button>\n  <Button variant=\"ghost\">Clear selection</Button>\n</Toolbar>\n"
     },
+    {
+      "id": "copyable-id",
+      "intent": "A labelled identifier with a button that copies it; the button announces nothing, the application speaks the result",
+      "match": [
+        "copy id",
+        "copyable identifier",
+        "copy to clipboard",
+        "reference number",
+        "request id"
+      ],
+      "compose": {
+        "component": "DescriptionList",
+        "props": {
+          "layout": "inline"
+        },
+        "slots": {
+          "body": [
+            {
+              "component": "DescriptionItem",
+              "props": {
+                "term": "{content:term}"
+              },
+              "slots": {
+                "body": [
+                  "{content:value}",
+                  {
+                    "component": "CopyButton",
+                    "props": {
+                      "value": "{content:value}",
+                      "size": 24
+                    }
+                  }
+                ]
+              }
+            }
+          ]
+        }
+      },
+      "parameters": [],
+      "content": {
+        "term": "[identifier name]",
+        "value": "[the identifier — set it in a mono class such as psi-text-mono-14-20-regular]"
+      },
+      "gaps": [],
+      "blocked": false,
+      "preset": "<DescriptionList\n  layout=\"inline\"\n>\n  <DescriptionItem\n    term=\"[identifier name]\"\n  >\n    [the identifier — set it in a mono class such as psi-text-mono-14-20-regular]\n    <CopyButton size={24} value=\"[the identifier — set it in a mono class such as psi-text-mono-14-20-regular]\" />\n  </DescriptionItem>\n</DescriptionList>\n"
+    },
+    {
+      "id": "cursor-pagination",
+      "intent": "Page-size selector and previous/next control beneath a list that pages by opaque token — no page count, no page numbers; pair with a TableCaption whose detail states the range and takes focus after a page change",
+      "match": [
+        "cursor pagination",
+        "token pagination",
+        "next page token",
+        "previous next",
+        "load more",
+        "keyset pagination",
+        "page size"
+      ],
+      "compose": {
+        "component": "Toolbar",
+        "props": {
+          "gap": 12,
+          "align": "end"
+        },
+        "slots": {
+          "body": [
+            {
+              "component": "Field",
+              "slots": {
+                "label": [
+                  "{content:page-size-label}"
+                ],
+                "body": [
+                  {
+                    "component": "Select",
+                    "props": {
+                      "size": 32
+                    }
+                  }
+                ]
+              }
+            },
+            {
+              "component": "CursorPagination",
+              "props": {
+                "hasPrevious": true,
+                "hasNext": true
+              }
+            }
+          ]
+        }
+      },
+      "parameters": [],
+      "content": {
+        "page-size-label": "Rows per page"
+      },
+      "gaps": [],
+      "blocked": false,
+      "preset": "<Toolbar\n  align=\"end\"\n  gap={12}\n>\n  <Field\n    label=\"Rows per page\"\n  >\n    <Select size={32} />\n  </Field>\n  <CursorPagination hasNext={true} hasPrevious={true} />\n</Toolbar>\n"
+    },
     {
       "id": "data-table",
-      "intent": "Sortable, selectable table of records with numeric columns and a per-row actions menu — compose the row menu from the row-actions pattern",
+      "intent": "Sortable, selectable table of records with a caption stating the range, numeric columns and a per-row actions menu — compose the row menu from the row-actions pattern",
       "match": [
         "data table",
         "transactions table",
@@ -128,6 +456,13 @@
         },
         "slots": {
           "body": [
+            {
+              "component": "TableCaption",
+              "props": {
+                "detail": "{content:range}"
+              },
+              "content": "caption"
+            },
             {
               "component": "TableHead",
               "slots": {
@@ -209,6 +544,8 @@
       },
       "parameters": [],
       "content": {
+        "caption": "[what the table lists — its visible name]",
+        "range": "[the rows shown, e.g. Rows 1–50 of 1,204; focus moves here after a page change]",
         "date-label": "Date",
         "payee-label": "Payee",
         "amount-label": "Amount",
@@ -220,7 +557,7 @@
       },
       "gaps": [],
       "blocked": false,
-      "preset": "<Table\n  selectable={true}\n  sortable={true}\n>\n  <TableHead>\n    <TableRow>\n      <TableHeaderCell sortKey=\"date\">Date</TableHeaderCell>\n      <TableHeaderCell sortKey=\"payee\">Payee</TableHeaderCell>\n      <TableHeaderCell numeric={true} sortKey=\"amount\">Amount</TableHeaderCell>\n      <TableHeaderCell>[a visible \"Actions\" header — the column needs an accessible name, so never an empty th]</TableHeaderCell>\n    </TableRow>\n  </TableHead>\n  <TableBody>\n    <TableRow\n      rowId=\"row-id\"\n    >\n      <TableCell>[one row per record]</TableCell>\n      <TableCell>[the record's payee]</TableCell>\n      <TableCell numeric={true}>[numeric columns align right and use tabular figures]</TableCell>\n      <TableCell>[the row-actions menu — compose it from the row-actions pattern]</TableCell>\n    </TableRow>\n  </TableBody>\n</Table>\n"
+      "preset": "<Table\n  selectable={true}\n  sortable={true}\n>\n  <TableCaption detail=\"[the rows shown, e.g. Rows 1–50 of 1,204; focus moves here after a page change]\">[what the table lists — its visible name]</TableCaption>\n  <TableHead>\n    <TableRow>\n      <TableHeaderCell sortKey=\"date\">Date</TableHeaderCell>\n      <TableHeaderCell sortKey=\"payee\">Payee</TableHeaderCell>\n      <TableHeaderCell numeric={true} sortKey=\"amount\">Amount</TableHeaderCell>\n      <TableHeaderCell>[a visible \"Actions\" header — the column needs an accessible name, so never an empty th]</TableHeaderCell>\n    </TableRow>\n  </TableHead>\n  <TableBody>\n    <TableRow\n      rowId=\"row-id\"\n    >\n      <TableCell>[one row per record]</TableCell>\n      <TableCell>[the record's payee]</TableCell>\n      <TableCell numeric={true}>[numeric columns align right and use tabular figures]</TableCell>\n      <TableCell>[the row-actions menu — compose it from the row-actions pattern]</TableCell>\n    </TableRow>\n  </TableBody>\n</Table>\n"
     },
     {
       "id": "date-range-filter",
@@ -470,9 +807,85 @@
       "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"
     },
+    {
+      "id": "filter-form",
+      "intent": "Labelled filters above a list, submitted together with a Find button: a Toolbar rendered as a named form (as=\"form\", so Find and Enter submit — wire onSubmit), aligned to the start so every control sits on one line under its visible Field label and Find drops onto that line. A field's description or error line hangs below its control and moves nothing else; the error line is the Field's own, with its usual aria-describedby wiring — set error on the Field, not beside the row. Every label in the row must be one line: a label that wraps pushes its control off the shared line. Add IconSearch before the Find label. For filters that apply as they change, named without a visible label, use filter-toolbar instead; never name a control by its placeholder alone",
+      "match": [
+        "filter form",
+        "search form",
+        "labelled filters",
+        "filters with labels",
+        "find button",
+        "submit filters"
+      ],
+      "compose": {
+        "component": "Toolbar",
+        "props": {
+          "as": "form",
+          "align": "start",
+          "gap": 12,
+          "aria-label": "{content:form-label}"
+        },
+        "slots": {
+          "body": [
+            {
+              "component": "Field",
+              "slots": {
+                "label": [
+                  "{content:text-label}"
+                ],
+                "body": [
+                  {
+                    "component": "Input",
+                    "props": {
+                      "size": 32
+                    }
+                  }
+                ]
+              }
+            },
+            {
+              "component": "Field",
+              "slots": {
+                "label": [
+                  "{content:select-label}"
+                ],
+                "body": [
+                  {
+                    "component": "Select",
+                    "props": {
+                      "size": 32
+                    }
+                  }
+                ]
+              }
+            },
+            {
+              "component": "Button",
+              "props": {
+                "type": "submit",
+                "variant": "accent",
+                "size": 32
+              },
+              "content": "find-label"
+            }
+          ]
+        }
+      },
+      "parameters": [],
+      "content": {
+        "form-label": "Filters",
+        "text-label": "[field name]",
+        "select-label": "[field name]",
+        "find-label": "Find"
+      },
+      "gaps": [],
+      "blocked": false,
+      "preset": "<Toolbar\n  align=\"start\"\n  aria-label=\"Filters\"\n  as=\"form\"\n  gap={12}\n>\n  <Field\n    label=\"[field name]\"\n  >\n    <Input size={32} />\n  </Field>\n  <Field\n    label=\"[field name]\"\n  >\n    <Select size={32} />\n  </Field>\n  <Button size={32} type=\"submit\" variant=\"accent\">Find</Button>\n</Toolbar>\n"
+    },
     {
       "id": "filter-toolbar",
-      "intent": "Toolbar of filter controls: search, category select, active-filter tags — controls are named by aria-label/placeholder, not a visible label, so no Field (contrast table-pagination)",
+      "intent": "Toolbar of filter controls that apply as they change: search, category select, active-filter tags — controls are named by aria-label/placeholder, not a visible label, so no Field (contrast table-pagination). For filters with visible labels, submitted together with a Find button, use filter-form",
       "match": [
         "filter toolbar",
         "filter bar",
@@ -515,6 +928,261 @@
       "blocked": false,
       "preset": "<Toolbar>\n  <Input aria-label=\"Search transactions\" placeholder=\"Search transactions\" type=\"search\" />\n  <Select aria-label=\"Category\" />\n  <Tag>[active filter]</Tag>\n</Toolbar>\n"
     },
+    {
+      "id": "form-feedback",
+      "intent": "A message above a form after a rejected submission, holding the reason and a copyable identifier; not a live region — the application speaks it",
+      "match": [
+        "form error summary",
+        "submission failed",
+        "rejected form",
+        "error id",
+        "support reference"
+      ],
+      "compose": {
+        "component": "InlineAlert",
+        "props": {
+          "variant": "danger"
+        },
+        "slots": {
+          "title": [
+            "{content:title}"
+          ],
+          "body": [
+            "{content:message}",
+            {
+              "component": "CopyButton",
+              "props": {
+                "value": "{content:identifier}",
+                "label": "{content:copy-label}"
+              }
+            }
+          ]
+        }
+      },
+      "parameters": [],
+      "content": {
+        "title": "[what was rejected]",
+        "message": "[why, and what to change]",
+        "identifier": "[the request or error id, for support]",
+        "copy-label": "Copy id"
+      },
+      "gaps": [],
+      "blocked": false,
+      "preset": "<InlineAlert\n  title=\"[what was rejected]\"\n  variant=\"danger\"\n>\n  [why, and what to change]\n  <CopyButton label=\"Copy id\" value=\"[the request or error id, for support]\" />\n</InlineAlert>\n"
+    },
+    {
+      "id": "loading-table",
+      "intent": "A table whose rows are still loading — Skeleton lines in the cells, aria-busy on the body; the skeletons are hidden from assistive tech, the busy state is what it reads",
+      "match": [
+        "loading table",
+        "table skeleton",
+        "placeholder rows",
+        "loading state",
+        "busy table"
+      ],
+      "compose": {
+        "component": "Table",
+        "props": {
+          "aria-label": "{content:table-label}"
+        },
+        "slots": {
+          "body": [
+            {
+              "component": "TableHead",
+              "slots": {
+                "body": [
+                  {
+                    "component": "TableRow",
+                    "slots": {
+                      "body": [
+                        {
+                          "component": "TableHeaderCell",
+                          "content": "col-1"
+                        },
+                        {
+                          "component": "TableHeaderCell",
+                          "content": "col-2"
+                        },
+                        {
+                          "component": "TableHeaderCell",
+                          "content": "col-3"
+                        }
+                      ]
+                    }
+                  }
+                ]
+              }
+            },
+            {
+              "component": "TableBody",
+              "props": {
+                "aria-busy": "true"
+              },
+              "slots": {
+                "body": [
+                  {
+                    "component": "TableRow",
+                    "slots": {
+                      "body": [
+                        {
+                          "component": "TableCell",
+                          "slots": {
+                            "body": [
+                              {
+                                "component": "Skeleton"
+                              }
+                            ]
+                          }
+                        },
+                        {
+                          "component": "TableCell",
+                          "slots": {
+                            "body": [
+                              {
+                                "component": "Skeleton"
+                              }
+                            ]
+                          }
+                        },
+                        {
+                          "component": "TableCell",
+                          "slots": {
+                            "body": [
+                              {
+                                "component": "Skeleton"
+                              }
+                            ]
+                          }
+                        }
+                      ]
+                    }
+                  }
+                ]
+              }
+            }
+          ]
+        }
+      },
+      "parameters": [],
+      "content": {
+        "table-label": "[what the table lists], loading",
+        "col-1": "[first column]",
+        "col-2": "[second column]",
+        "col-3": "[third column]"
+      },
+      "gaps": [],
+      "blocked": false,
+      "preset": "<Table\n  aria-label=\"[what the table lists], loading\"\n>\n  <TableHead>\n    <TableRow>\n      <TableHeaderCell>[first column]</TableHeaderCell>\n      <TableHeaderCell>[second column]</TableHeaderCell>\n      <TableHeaderCell>[third column]</TableHeaderCell>\n    </TableRow>\n  </TableHead>\n  <TableBody\n    aria-busy=\"true\"\n  >\n    <TableRow>\n      <TableCell>\n        <Skeleton />\n      </TableCell>\n      <TableCell>\n        <Skeleton />\n      </TableCell>\n      <TableCell>\n        <Skeleton />\n      </TableCell>\n    </TableRow>\n  </TableBody>\n</Table>\n"
+    },
+    {
+      "id": "page-banner",
+      "intent": "A full-width, page-level message above the content, with a Refresh action; it is what the page shows, and announcing stays the application's (route the same event through the announcer)",
+      "match": [
+        "page banner",
+        "site-wide message",
+        "stale data",
+        "service notice",
+        "maintenance banner"
+      ],
+      "compose": {
+        "component": "Banner",
+        "props": {
+          "variant": "{param:variant}"
+        },
+        "slots": {
+          "title": [
+            "{content:title}"
+          ],
+          "body": [
+            "{content:message}"
+          ],
+          "action": [
+            {
+              "component": "Button",
+              "props": {
+                "variant": "ghost",
+                "size": 32
+              },
+              "content": "action-label"
+            }
+          ]
+        }
+      },
+      "parameters": [
+        {
+          "key": "variant",
+          "ask": "What kind of message is this?",
+          "options": [
+            "neutral",
+            "warning",
+            "danger",
+            "success"
+          ],
+          "default": "neutral"
+        }
+      ],
+      "content": {
+        "title": "[what changed, in a few words]",
+        "message": "[what it means for the user and what to do]",
+        "action-label": "Refresh"
+      },
+      "gaps": [],
+      "blocked": false,
+      "preset": "<Banner action={<Button size={32} variant=\"ghost\">Refresh</Button>} title=\"[what changed, in a few words]\" variant=\"neutral\">[what it means for the user and what to do]</Banner>\n"
+    },
+    {
+      "id": "required-field",
+      "intent": "A required field that says so in text, not by a glyph alone: a Field with required and requiredText around an Input, with a description",
+      "match": [
+        "required field",
+        "mandatory field",
+        "required in text",
+        "required label",
+        "(Required)"
+      ],
+      "compose": {
+        "component": "Field",
+        "props": {
+          "required": true,
+          "requiredText": "{content:required-text}"
+        },
+        "slots": {
+          "label": [
+            "{content:label}"
+          ],
+          "body": [
+            {
+              "component": "Input",
+              "props": {
+                "size": "{param:size}"
+              }
+            }
+          ],
+          "description": [
+            "{content:description}"
+          ]
+        }
+      },
+      "parameters": [
+        {
+          "key": "size",
+          "ask": "Control size?",
+          "options": [
+            32,
+            40
+          ],
+          "default": 32
+        }
+      ],
+      "content": {
+        "label": "[field name]",
+        "required-text": "(Required)",
+        "description": "[why it is needed]"
+      },
+      "gaps": [],
+      "blocked": false,
+      "preset": "<Field\n  description=\"[why it is needed]\"\n  label=\"[field name]\"\n  required={true}\n  requiredText=\"(Required)\"\n>\n  <Input size={32} />\n</Field>\n"
+    },
     {
       "id": "row-actions",
       "intent": "List or table row with an icon-only actions menu, including a destructive item — hand the destructive item's confirmation off to the destructive-confirm pattern",