@grampro/kit 2.6.3 → 2.7.0

package/source/components/alert/passport.manual.json

@@ -0,0 +1,42 @@
+{
+  "$schema": "../../../schema/passport-overlay-v1.schema.json",
+  "component": "Alert",
+  "purpose": "A message that stays in the page — neither interrupting like a dialog nor leaving like a toast. For conditions the user needs to keep seeing.",
+  "intentDomains": [
+    "Summarization"
+  ],
+  "accessibility": {
+    "supplied": [
+      "role=alert on the error and warning variants, so they are announced when they appear",
+      "the variant is carried in text and icon, not by colour alone",
+      "the dismiss control is a real button with an accessible name"
+    ],
+    "required": [
+      "a message that says what to do, not only what went wrong",
+      "do not use `onDismiss` for something the user must act on — a dismissible error can be dismissed unread"
+    ]
+  },
+  "composition": {
+    "mustNotContain": [
+      "Alert"
+    ],
+    "notes": "Actions belong in `actions`, which keeps them in the alert's landmark rather than loose in the body."
+  },
+  "safeMutations": {
+    "allowed": [
+      "size",
+      "icon",
+      "description"
+    ],
+    "forbidden": [
+      "variant",
+      "children",
+      "actions",
+      "onDismiss"
+    ],
+    "rationale": "`variant` is the severity. Downgrading an error to info changes what the page is telling the user, and it changes whether it is announced at all."
+  },
+  "propNotes": {
+    "variant": "Decides the role: error and warning are announced, info and success are not."
+  }
+}

package/source/components/avatar/passport.json

@@ -9,7 +9,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.6.3",
+    "libraryVersion": "2.7.0",
     "files": [
       "core/identity.ts",
       "core/index.ts",
@@ -22,6 +22,7 @@
     ],
     "sourceHash": "sha256:541aa6ca5c99e64fba414881c07cc3c29244e03c09b665a4934690d633cc20e1"
   },
+  "purpose": "A person as a picture or their initials, on a colour derived from their name, with a presence dot and an overflow count for groups.",
   "props": [
     {
       "name": "aria-describedby",
@@ -75,7 +76,8 @@
       "default": false,
       "origin": "derived",
       "description": "Marks the avatar as decoration, for a name printed next to it.",
-      "descriptionOrigin": "jsdoc"
+      "descriptionOrigin": "jsdoc",
+      "note": "Hides it from assistive technology. Correct when the name is already adjacent in text."
     },
     {
       "name": "hidden",
@@ -277,20 +279,51 @@
     }
   ],
   "accessibility": {
-    "supplied": [],
-    "required": []
+    "supplied": [
+      "the image falls back to initials, and initials to a generic icon, so there is never a broken image",
+      "the colour is derived from the name, which makes it stable rather than meaningful — it is never the only signal",
+      "a decorative avatar is hidden from assistive technology instead of announcing a name twice",
+      "the presence status is given as text, not only as a coloured dot"
+    ],
+    "required": [
+      "`name` for the accessible label, or `decorative` when the name is already beside it",
+      "`alt`-worthy `label` text where the avatar stands alone as a link to a person"
+    ]
+  },
+  "composition": {
+    "allowedChildren": [
+      "Avatar"
+    ],
+    "notes": "AvatarGroup takes Avatar children and collapses the overflow past `max`."
   },
-  "composition": {},
   "operations": {},
   "intentDomains": [],
-  "safeMutations": {},
+  "safeMutations": {
+    "allowed": [
+      "size",
+      "shape",
+      "max",
+      "decorative"
+    ],
+    "forbidden": [
+      "name",
+      "src",
+      "initials",
+      "status",
+      "label"
+    ],
+    "rationale": "Shape and size are presentation; the person and their presence are data."
+  },
   "examples": [],
   "coverage": {
     "propsTotal": 10,
     "propsDescribed": 10,
     "describedPct": 100,
     "authoredSections": [
-      "accessibility"
+      "accessibility",
+      "composition",
+      "purpose",
+      "safeMutations"
     ]
   }
 }

package/source/components/avatar/passport.manual.json

@@ -0,0 +1,43 @@
+{
+  "$schema": "../../../schema/passport-overlay-v1.schema.json",
+  "component": "Avatar",
+  "purpose": "A person as a picture or their initials, on a colour derived from their name, with a presence dot and an overflow count for groups.",
+  "intentDomains": [],
+  "accessibility": {
+    "supplied": [
+      "the image falls back to initials, and initials to a generic icon, so there is never a broken image",
+      "the colour is derived from the name, which makes it stable rather than meaningful — it is never the only signal",
+      "a decorative avatar is hidden from assistive technology instead of announcing a name twice",
+      "the presence status is given as text, not only as a coloured dot"
+    ],
+    "required": [
+      "`name` for the accessible label, or `decorative` when the name is already beside it",
+      "`alt`-worthy `label` text where the avatar stands alone as a link to a person"
+    ]
+  },
+  "composition": {
+    "allowedChildren": [
+      "Avatar"
+    ],
+    "notes": "AvatarGroup takes Avatar children and collapses the overflow past `max`."
+  },
+  "safeMutations": {
+    "allowed": [
+      "size",
+      "shape",
+      "max",
+      "decorative"
+    ],
+    "forbidden": [
+      "name",
+      "src",
+      "initials",
+      "status",
+      "label"
+    ],
+    "rationale": "Shape and size are presentation; the person and their presence are data."
+  },
+  "propNotes": {
+    "decorative": "Hides it from assistive technology. Correct when the name is already adjacent in text."
+  }
+}

package/source/components/badge/passport.json

@@ -9,7 +9,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.6.3",
+    "libraryVersion": "2.7.0",
     "files": [
       "core/count.ts",
       "core/index.ts",
@@ -22,6 +22,7 @@
     ],
     "sourceHash": "sha256:16f626a94da3bac9b1a105718010edd7e1ce5a6118823ed8a53c97d658d89a3e"
   },
+  "purpose": "Short labels: a status, a category, a count that stops at 99+, and chips the user can take off.",
   "props": [
     {
       "name": "appearance",
@@ -163,7 +164,8 @@
       "default": 99,
       "origin": "derived",
       "description": "Where the count stops. Default 99.",
-      "descriptionOrigin": "jsdoc"
+      "descriptionOrigin": "jsdoc",
+      "note": "Counts above this render as `max`+. Default 99."
     },
     {
       "name": "onRemove",
@@ -315,20 +317,54 @@
     }
   ],
   "accessibility": {
-    "supplied": [],
-    "required": []
+    "supplied": [
+      "a count is announced with its meaning rather than as a bare number",
+      "the remove control on a chip is a real button with an accessible name",
+      "a dot badge is marked decorative, since a dot alone says nothing"
+    ],
+    "required": [
+      "text alongside a status badge — colour is not a label",
+      "an accessible name on a dot or icon-only badge, or mark it decorative and say it elsewhere"
+    ]
+  },
+  "composition": {
+    "mustNotContain": [
+      "button",
+      "a"
+    ],
+    "notes": "Use `onRemove` for a chip rather than nesting a button inside the badge."
   },
-  "composition": {},
   "operations": {},
   "intentDomains": [],
-  "safeMutations": {},
+  "safeMutations": {
+    "allowed": [
+      "variant",
+      "appearance",
+      "size",
+      "icon",
+      "dot",
+      "max",
+      "showZero",
+      "formatValue"
+    ],
+    "forbidden": [
+      "count",
+      "label",
+      "children",
+      "onRemove"
+    ],
+    "rationale": "Appearance is safe. The count and the label are the data."
+  },
   "examples": [],
   "coverage": {
     "propsTotal": 13,
     "propsDescribed": 11,
     "describedPct": 85,
     "authoredSections": [
-      "accessibility"
+      "accessibility",
+      "composition",
+      "purpose",
+      "safeMutations"
     ]
   }
 }

package/source/components/badge/passport.manual.json

@@ -0,0 +1,46 @@
+{
+  "$schema": "../../../schema/passport-overlay-v1.schema.json",
+  "component": "Badge",
+  "purpose": "Short labels: a status, a category, a count that stops at 99+, and chips the user can take off.",
+  "intentDomains": [],
+  "accessibility": {
+    "supplied": [
+      "a count is announced with its meaning rather than as a bare number",
+      "the remove control on a chip is a real button with an accessible name",
+      "a dot badge is marked decorative, since a dot alone says nothing"
+    ],
+    "required": [
+      "text alongside a status badge — colour is not a label",
+      "an accessible name on a dot or icon-only badge, or mark it decorative and say it elsewhere"
+    ]
+  },
+  "composition": {
+    "mustNotContain": [
+      "button",
+      "a"
+    ],
+    "notes": "Use `onRemove` for a chip rather than nesting a button inside the badge."
+  },
+  "safeMutations": {
+    "allowed": [
+      "variant",
+      "appearance",
+      "size",
+      "icon",
+      "dot",
+      "max",
+      "showZero",
+      "formatValue"
+    ],
+    "forbidden": [
+      "count",
+      "label",
+      "children",
+      "onRemove"
+    ],
+    "rationale": "Appearance is safe. The count and the label are the data."
+  },
+  "propNotes": {
+    "max": "Counts above this render as `max`+. Default 99."
+  }
+}

package/source/components/breadcrumb/passport.json

@@ -8,7 +8,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.6.3",
+    "libraryVersion": "2.7.0",
     "files": [
       "core/index.ts",
       "core/trail.ts",
@@ -20,6 +20,7 @@
     ],
     "sourceHash": "sha256:3b7fef8f48d1a1290c25a263d2e92ef5dcb706b1a06899ffe5a4df1cdab663e1"
   },
+  "purpose": "Where a page sits in the app: a trail that collapses in the middle when it is long, renders through your router's link, and can emit schema.org JSON-LD.",
   "props": [
     {
       "name": "aria-describedby",
@@ -163,7 +164,8 @@
       "default": false,
       "origin": "derived",
       "description": "Add schema.org `BreadcrumbList` JSON-LD for search engines. Pass\n`{ baseUrl }` so relative links become absolute, as search engines require.",
-      "descriptionOrigin": "jsdoc"
+      "descriptionOrigin": "jsdoc",
+      "note": "Emits a schema.org BreadcrumbList as JSON-LD. It must describe real, reachable URLs."
     },
     {
       "name": "style",
@@ -226,20 +228,47 @@
     }
   ],
   "accessibility": {
-    "supplied": [],
-    "required": []
+    "supplied": [
+      "a nav landmark with an accessible name",
+      "the current page is marked aria-current and is not a link",
+      "the collapsed middle is a real button that expands, not an inert ellipsis",
+      "separators are decorative and hidden from assistive technology"
+    ],
+    "required": [
+      "`renderLink` to use your router, so a breadcrumb does not full-page-reload the app",
+      "a trail that matches the page's actual position — a wrong one is worse than none"
+    ]
+  },
+  "composition": {
+    "notes": "Items come from the `items` array. The last item is the current page and is rendered as text."
   },
-  "composition": {},
   "operations": {},
   "intentDomains": [],
-  "safeMutations": {},
+  "safeMutations": {
+    "allowed": [
+      "size",
+      "separator",
+      "maxItems",
+      "itemsBeforeCollapse",
+      "itemsAfterCollapse"
+    ],
+    "forbidden": [
+      "items",
+      "renderLink",
+      "structuredData"
+    ],
+    "rationale": "Collapsing and the separator are presentation. `items` is the page's position, `renderLink` is the router binding, and `structuredData` emits markup search engines consume."
+  },
   "examples": [],
   "coverage": {
     "propsTotal": 8,
     "propsDescribed": 8,
     "describedPct": 100,
     "authoredSections": [
-      "accessibility"
+      "accessibility",
+      "composition",
+      "purpose",
+      "safeMutations"
     ]
   }
 }

package/source/components/breadcrumb/passport.manual.json

@@ -0,0 +1,39 @@
+{
+  "$schema": "../../../schema/passport-overlay-v1.schema.json",
+  "component": "Breadcrumb",
+  "purpose": "Where a page sits in the app: a trail that collapses in the middle when it is long, renders through your router's link, and can emit schema.org JSON-LD.",
+  "intentDomains": [],
+  "accessibility": {
+    "supplied": [
+      "a nav landmark with an accessible name",
+      "the current page is marked aria-current and is not a link",
+      "the collapsed middle is a real button that expands, not an inert ellipsis",
+      "separators are decorative and hidden from assistive technology"
+    ],
+    "required": [
+      "`renderLink` to use your router, so a breadcrumb does not full-page-reload the app",
+      "a trail that matches the page's actual position — a wrong one is worse than none"
+    ]
+  },
+  "composition": {
+    "notes": "Items come from the `items` array. The last item is the current page and is rendered as text."
+  },
+  "safeMutations": {
+    "allowed": [
+      "size",
+      "separator",
+      "maxItems",
+      "itemsBeforeCollapse",
+      "itemsAfterCollapse"
+    ],
+    "forbidden": [
+      "items",
+      "renderLink",
+      "structuredData"
+    ],
+    "rationale": "Collapsing and the separator are presentation. `items` is the page's position, `renderLink` is the router binding, and `structuredData` emits markup search engines consume."
+  },
+  "propNotes": {
+    "structuredData": "Emits a schema.org BreadcrumbList as JSON-LD. It must describe real, reachable URLs."
+  }
+}

package/source/components/button/passport.json

@@ -8,7 +8,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.6.3",
+    "libraryVersion": "2.7.0",
     "files": [
       "core/index.ts",
       "core/state.ts",

package/source/components/button/passport.manual.json

@@ -1,5 +1,5 @@
 {
-  "$schema": "../../../schema/passport-v1.schema.json",
+  "$schema": "../../../schema/passport-overlay-v1.schema.json",
   "component": "Button",
   "purpose": "Trigger an action. Not for navigation unless `render` supplies a link element.",
   "intentDomains": ["ActionIntent"],

package/source/components/card/passport.json

@@ -12,7 +12,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.6.3",
+    "libraryVersion": "2.7.0",
     "files": [
       "core/index.ts",
       "core/trend.ts",
@@ -24,6 +24,7 @@
     ],
     "sourceHash": "sha256:5b40d5a873d8c4bd0ea3423f5a9b0ca06f2515aa1ea45149d36be3b2b4aa63e1"
   },
+  "purpose": "A surface that groups related content, with header, body and footer, plus Stat for a single figure and its trend.",
   "props": [
     {
       "name": "actions",
@@ -134,7 +135,8 @@
       "default": false,
       "origin": "derived",
       "description": "Lifts the card on hover, for a card that is clickable by other means.",
-      "descriptionOrigin": "jsdoc"
+      "descriptionOrigin": "jsdoc",
+      "note": "Makes the whole surface a button. Do not combine with controls inside it."
     },
     {
       "name": "label",
@@ -233,7 +235,8 @@
       "required": false,
       "origin": "derived",
       "description": "The change beside the figure: direction, a formatted label, and\nwhether down is the good outcome. Left out, no arrow is shown.",
-      "descriptionOrigin": "jsdoc"
+      "descriptionOrigin": "jsdoc",
+      "note": "Stat only. The direction is also stated in text, so it survives being read aloud."
     },
     {
       "name": "value",
@@ -326,20 +329,54 @@
     }
   ],
   "accessibility": {
-    "supplied": [],
-    "required": []
+    "supplied": [
+      "an interactive card is a real button or link, not a div with a click handler",
+      "the trend on Stat is given as text as well as a direction and colour",
+      "the loading state renders placeholder bars announced as loading"
+    ],
+    "required": [
+      "`href` or `interactive`, never a bare onClick on the surface — otherwise it is unreachable by keyboard",
+      "a heading that names the group, where the card is a section of a page"
+    ]
+  },
+  "composition": {
+    "mustNotContain": [
+      "Card"
+    ],
+    "notes": "An interactive card must not contain its own buttons or links: a control inside a clickable surface is a nested interactive element, and neither target is predictable."
   },
-  "composition": {},
   "operations": {},
   "intentDomains": [],
-  "safeMutations": {},
+  "safeMutations": {
+    "allowed": [
+      "variant",
+      "padding",
+      "icon",
+      "description",
+      "help"
+    ],
+    "forbidden": [
+      "href",
+      "target",
+      "rel",
+      "interactive",
+      "value",
+      "trend",
+      "loading",
+      "actions"
+    ],
+    "rationale": "Surface styling is safe. `href` and `interactive` decide what the card *is*, and `value` and `trend` are the figure it reports."
+  },
   "examples": [],
   "coverage": {
     "propsTotal": 16,
     "propsDescribed": 14,
     "describedPct": 88,
     "authoredSections": [
-      "accessibility"
+      "accessibility",
+      "composition",
+      "purpose",
+      "safeMutations"
     ]
   }
 }

package/source/components/card/passport.manual.json

@@ -0,0 +1,47 @@
+{
+  "$schema": "../../../schema/passport-overlay-v1.schema.json",
+  "component": "Card",
+  "purpose": "A surface that groups related content, with header, body and footer, plus Stat for a single figure and its trend.",
+  "intentDomains": [],
+  "accessibility": {
+    "supplied": [
+      "an interactive card is a real button or link, not a div with a click handler",
+      "the trend on Stat is given as text as well as a direction and colour",
+      "the loading state renders placeholder bars announced as loading"
+    ],
+    "required": [
+      "`href` or `interactive`, never a bare onClick on the surface — otherwise it is unreachable by keyboard",
+      "a heading that names the group, where the card is a section of a page"
+    ]
+  },
+  "composition": {
+    "mustNotContain": [
+      "Card"
+    ],
+    "notes": "An interactive card must not contain its own buttons or links: a control inside a clickable surface is a nested interactive element, and neither target is predictable."
+  },
+  "safeMutations": {
+    "allowed": [
+      "variant",
+      "padding",
+      "icon",
+      "description",
+      "help"
+    ],
+    "forbidden": [
+      "href",
+      "target",
+      "rel",
+      "interactive",
+      "value",
+      "trend",
+      "loading",
+      "actions"
+    ],
+    "rationale": "Surface styling is safe. `href` and `interactive` decide what the card *is*, and `value` and `trend` are the figure it reports."
+  },
+  "propNotes": {
+    "interactive": "Makes the whole surface a button. Do not combine with controls inside it.",
+    "trend": "Stat only. The direction is also stated in text, so it survives being read aloud."
+  }
+}

package/source/components/checkbox/core/agent.ts

@@ -0,0 +1,33 @@
+/*
+ * Checkbox's agent contract.
+ *
+ * A boolean field, so the write sets `checked` rather than `value`. The
+ * indeterminate state is not settable by an agent: it means "some of the group",
+ * which is a conclusion about other checkboxes rather than a value of this one.
+ *
+ * Pure: no React, no DOM. The contract is what this instance will accept, and
+ * the validator in shared/core/agent decides everything from it. Build it from
+ * props on every render so that a field which has just become read-only stops
+ * accepting writes immediately.
+ */
+
+import type { FieldContract } from "../../shared/core/agent";
+
+export interface CheckboxAgentProps {
+  label?: string;
+  disabled?: boolean;
+  readOnly?: boolean;
+  required?: boolean;
+}
+
+export function checkboxContract(props: CheckboxAgentProps = {}): FieldContract {
+  return {
+    component: "Checkbox",
+    kind: "boolean",
+    operations: ["setValue", "clear", "focus"],
+    label: props.label,
+    disabled: props.disabled,
+    readOnly: props.readOnly,
+    required: props.required,
+  };
+}

package/source/components/checkbox/core/index.ts

@@ -1,3 +1,5 @@
 // Framework-free: selection rules for checkbox groups.
 export { groupState, toggleAll, toggleValue } from "./group";
 export type * from "./types";
+// The agent contract: what a model may ask this field to do.
+export { checkboxContract, type CheckboxAgentProps } from "./agent";