@grampro/kit 2.6.3 → 2.7.1

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

@@ -0,0 +1,36 @@
+/*
+ * Input's agent contract.
+ *
+ * Its ref is the <input> element, so the write goes through the element
+ * itself, exactly as `clear()` has always done.
+ *
+ * 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 InputAgentProps {
+  label?: string;
+  disabled?: boolean;
+  readOnly?: boolean;
+  required?: boolean;
+  maxLength?: number;
+  pattern?: string;
+}
+
+export function inputContract(props: InputAgentProps = {}): FieldContract {
+  return {
+    component: "Input",
+    kind: "text",
+    operations: ["setValue", "clear", "focus"],
+    label: props.label,
+    disabled: props.disabled,
+    readOnly: props.readOnly,
+    required: props.required,
+    maxLength: props.maxLength,
+    pattern: props.pattern,
+  };
+}

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

@@ -9,3 +9,5 @@ export {
   separatorsAfter,
 } from "./otp";
 export type * from "./types";
+// The agent contract: what a model may ask this field to do.
+export { inputContract, type InputAgentProps } from "./agent";

package/source/components/input/passport.json

@@ -9,8 +9,9 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.6.3",
+    "libraryVersion": "2.7.1",
     "files": [
+      "core/agent.ts",
       "core/count.ts",
       "core/index.ts",
       "core/otp.ts",
@@ -23,8 +24,9 @@
       "react/locale.ts",
       "react/props.ts"
     ],
-    "sourceHash": "sha256:50ff11f4a9255189704b330123d35d4f4e3550bd4cf2eed2d0735c92ba876b03"
+    "sourceHash": "sha256:6d1ef1229a82962e2bd3bf32a15de6f7d9e43c2270e65df9f7303cd74dd479d4"
   },
+  "purpose": "A single-line text field with its label, hint and error wired together. OtpInput is the same field split into one box per character for a one-time code.",
   "props": [
     {
       "name": "aria-describedby",
@@ -130,7 +132,8 @@
       "required": false,
       "origin": "derived",
       "description": "Message below the field; also marks it invalid.",
-      "descriptionOrigin": "jsdoc"
+      "descriptionOrigin": "jsdoc",
+      "note": "Set by the host after validating. The component never derives it."
     },
     {
       "name": "form",
@@ -205,7 +208,8 @@
       "default": 6,
       "origin": "derived",
       "description": "Number of characters. Default 6.",
-      "descriptionOrigin": "jsdoc"
+      "descriptionOrigin": "jsdoc",
+      "note": "OtpInput only: the number of boxes, which is also the expected code length."
     },
     {
       "name": "localeText",
@@ -222,7 +226,8 @@
       "default": false,
       "origin": "derived",
       "description": "Show dots instead of the characters.",
-      "descriptionOrigin": "jsdoc"
+      "descriptionOrigin": "jsdoc",
+      "note": "Shapes what can be typed. Changing it can make an already-valid value unreachable."
     },
     {
       "name": "max",
@@ -523,20 +528,92 @@
     }
   ],
   "accessibility": {
-    "supplied": [],
-    "required": []
+    "supplied": [
+      "the label is a real <label> bound to the input, so clicking it focuses the field",
+      "description and error are linked by aria-describedby",
+      "aria-invalid while `error` is set",
+      "the character counter is a live region when `showCount` is on",
+      "OtpInput moves focus between boxes and handles paste of a whole code"
+    ],
+    "required": [
+      "a `label`, or `aria-label` when the field is visually unlabelled",
+      "`type` matching the data — email, tel, url — so the right keyboard and autofill appear",
+      "`autoComplete` on anything a browser or password manager should fill"
+    ]
+  },
+  "composition": {
+    "mustNotContain": [
+      "label",
+      "input"
+    ],
+    "notes": "The component renders its own <label> and <input>. Wrapping it in another label binds the text to the wrong control and breaks the click target."
+  },
+  "operations": {
+    "setValue": {
+      "summary": "Write a value into the field, as though a person had entered it.",
+      "effects": [
+        "replaces the field's current value",
+        "fires the host's change handler"
+      ],
+      "reversible": true
+    },
+    "clear": {
+      "summary": "Empty the field.",
+      "effects": [
+        "discards the field's current value",
+        "fires the host's change handler"
+      ],
+      "reversible": true
+    },
+    "focus": {
+      "summary": "Move keyboard focus to the field.",
+      "effects": [
+        "moves focus"
+      ],
+      "reversible": false
+    }
+  },
+  "intentDomains": [
+    "ActionIntent"
+  ],
+  "safeMutations": {
+    "allowed": [
+      "size",
+      "placeholder",
+      "description",
+      "leading",
+      "trailing",
+      "clearable",
+      "showCount",
+      "revealPassword"
+    ],
+    "forbidden": [
+      "value",
+      "defaultValue",
+      "name",
+      "type",
+      "required",
+      "disabled",
+      "readOnly",
+      "pattern",
+      "mask",
+      "onValueChange",
+      "error"
+    ],
+    "rationale": "Appearance and affordances are safe. `value` and `name` are the form's data, `type`/`pattern`/`mask` decide what is accepted, and `error` is the host's verdict on validity — an agent that writes it is claiming a validation result it did not compute."
   },
-  "composition": {},
-  "operations": {},
-  "intentDomains": [],
-  "safeMutations": {},
   "examples": [],
   "coverage": {
     "propsTotal": 18,
     "propsDescribed": 16,
     "describedPct": 89,
     "authoredSections": [
-      "accessibility"
+      "accessibility",
+      "composition",
+      "intentDomains",
+      "operations",
+      "purpose",
+      "safeMutations"
     ]
   }
 }

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

@@ -0,0 +1,86 @@
+{
+  "$schema": "../../../schema/passport-overlay-v1.schema.json",
+  "component": "Input",
+  "purpose": "A single-line text field with its label, hint and error wired together. OtpInput is the same field split into one box per character for a one-time code.",
+  "intentDomains": [
+    "ActionIntent"
+  ],
+  "$operationsNote": "Mirrors shared/core/agent/field.ts, which is what the runtime dispatches on. source/components/shared/core/agent/__tests__/field-passport.test.ts fails if the two drift. No `apiMethod`: a field is written through its ref — the element for most of these, a handle for Combobox and DatePicker — and that is a normal case, not a gap.",
+  "operations": {
+    "setValue": {
+      "summary": "Write a value into the field, as though a person had entered it.",
+      "effects": [
+        "replaces the field's current value",
+        "fires the host's change handler"
+      ],
+      "reversible": true
+    },
+    "clear": {
+      "summary": "Empty the field.",
+      "effects": [
+        "discards the field's current value",
+        "fires the host's change handler"
+      ],
+      "reversible": true
+    },
+    "focus": {
+      "summary": "Move keyboard focus to the field.",
+      "effects": [
+        "moves focus"
+      ],
+      "reversible": false
+    }
+  },
+  "accessibility": {
+    "supplied": [
+      "the label is a real <label> bound to the input, so clicking it focuses the field",
+      "description and error are linked by aria-describedby",
+      "aria-invalid while `error` is set",
+      "the character counter is a live region when `showCount` is on",
+      "OtpInput moves focus between boxes and handles paste of a whole code"
+    ],
+    "required": [
+      "a `label`, or `aria-label` when the field is visually unlabelled",
+      "`type` matching the data — email, tel, url — so the right keyboard and autofill appear",
+      "`autoComplete` on anything a browser or password manager should fill"
+    ]
+  },
+  "composition": {
+    "mustNotContain": [
+      "label",
+      "input"
+    ],
+    "notes": "The component renders its own <label> and <input>. Wrapping it in another label binds the text to the wrong control and breaks the click target."
+  },
+  "safeMutations": {
+    "allowed": [
+      "size",
+      "placeholder",
+      "description",
+      "leading",
+      "trailing",
+      "clearable",
+      "showCount",
+      "revealPassword"
+    ],
+    "forbidden": [
+      "value",
+      "defaultValue",
+      "name",
+      "type",
+      "required",
+      "disabled",
+      "readOnly",
+      "pattern",
+      "mask",
+      "onValueChange",
+      "error"
+    ],
+    "rationale": "Appearance and affordances are safe. `value` and `name` are the form's data, `type`/`pattern`/`mask` decide what is accepted, and `error` is the host's verdict on validity — an agent that writes it is claiming a validation result it did not compute."
+  },
+  "propNotes": {
+    "mask": "Shapes what can be typed. Changing it can make an already-valid value unreachable.",
+    "length": "OtpInput only: the number of boxes, which is also the expected code length.",
+    "error": "Set by the host after validating. The component never derives it."
+  }
+}

package/source/components/menu/passport.json

@@ -16,7 +16,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.6.3",
+    "libraryVersion": "2.7.1",
     "files": [
       "core/index.ts",
       "core/navigation.ts",
@@ -31,6 +31,7 @@
     ],
     "sourceHash": "sha256:9a6248a4986051f6506746c084b9e89728fecd0a0b430d1962f5f3ed544ce1e5"
   },
+  "purpose": "A menu of commands with arrow keys, typeahead, checkbox and radio items and submenus, following the WAI-ARIA menu pattern.",
   "props": [
     {
       "name": "align",
@@ -105,7 +106,8 @@
       "default": false,
       "origin": "derived",
       "description": "Styles it as a destructive action.",
-      "descriptionOrigin": "jsdoc"
+      "descriptionOrigin": "jsdoc",
+      "note": "Styles the item as dangerous. Remove it only if the item stops being dangerous."
     },
     {
       "name": "disabled",
@@ -216,7 +218,8 @@
       "required": false,
       "origin": "derived",
       "description": "A hint such as ⌘K. The menu shows it; binding the key is up to you.",
-      "descriptionOrigin": "jsdoc"
+      "descriptionOrigin": "jsdoc",
+      "note": "Displayed only. The component does not bind the key; the application does."
     },
     {
       "name": "side",
@@ -319,20 +322,72 @@
     }
   ],
   "accessibility": {
-    "supplied": [],
-    "required": []
+    "supplied": [
+      "the menu pattern: role=menu with menuitem, menuitemcheckbox and menuitemradio children",
+      "arrow keys move, typeahead jumps to a matching item, Escape closes and returns focus to the trigger",
+      "submenus open on ArrowRight and close on ArrowLeft",
+      "a disabled item stays focusable so it can be read, and is not activated"
+    ],
+    "required": [
+      "an accessible name on the trigger when it is an icon",
+      "`destructive` on items that delete, so they are not styled as ordinary commands"
+    ]
+  },
+  "composition": {
+    "allowedChildren": [
+      "MenuItem",
+      "MenuCheckboxItem",
+      "MenuRadioItem",
+      "MenuGroup",
+      "MenuSeparator",
+      "MenuSub"
+    ],
+    "mustNotContain": [
+      "input",
+      "textarea",
+      "Modal"
+    ],
+    "notes": "A menu holds commands, not fields. The roving focus of the menu pattern and a text field's own key handling cannot both own the arrow keys."
   },
-  "composition": {},
   "operations": {},
-  "intentDomains": [],
-  "safeMutations": {},
+  "intentDomains": [
+    "ActionIntent"
+  ],
+  "safeMutations": {
+    "allowed": [
+      "side",
+      "align",
+      "gap",
+      "icon",
+      "shortcut",
+      "closeOnSelect"
+    ],
+    "forbidden": [
+      "open",
+      "defaultOpen",
+      "onOpenChange",
+      "onSelect",
+      "onValueChange",
+      "onCheckedChange",
+      "value",
+      "checked",
+      "trigger",
+      "destructive",
+      "disabled"
+    ],
+    "rationale": "Placement and ornament are safe. `onSelect` is the command itself, and `destructive` is a warning an agent must not remove."
+  },
   "examples": [],
   "coverage": {
     "propsTotal": 20,
     "propsDescribed": 17,
     "describedPct": 85,
     "authoredSections": [
-      "accessibility"
+      "accessibility",
+      "composition",
+      "intentDomains",
+      "purpose",
+      "safeMutations"
     ]
   }
 }

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

@@ -0,0 +1,64 @@
+{
+  "$schema": "../../../schema/passport-overlay-v1.schema.json",
+  "component": "Menu",
+  "purpose": "A menu of commands with arrow keys, typeahead, checkbox and radio items and submenus, following the WAI-ARIA menu pattern.",
+  "intentDomains": [
+    "ActionIntent"
+  ],
+  "accessibility": {
+    "supplied": [
+      "the menu pattern: role=menu with menuitem, menuitemcheckbox and menuitemradio children",
+      "arrow keys move, typeahead jumps to a matching item, Escape closes and returns focus to the trigger",
+      "submenus open on ArrowRight and close on ArrowLeft",
+      "a disabled item stays focusable so it can be read, and is not activated"
+    ],
+    "required": [
+      "an accessible name on the trigger when it is an icon",
+      "`destructive` on items that delete, so they are not styled as ordinary commands"
+    ]
+  },
+  "composition": {
+    "allowedChildren": [
+      "MenuItem",
+      "MenuCheckboxItem",
+      "MenuRadioItem",
+      "MenuGroup",
+      "MenuSeparator",
+      "MenuSub"
+    ],
+    "mustNotContain": [
+      "input",
+      "textarea",
+      "Modal"
+    ],
+    "notes": "A menu holds commands, not fields. The roving focus of the menu pattern and a text field's own key handling cannot both own the arrow keys."
+  },
+  "safeMutations": {
+    "allowed": [
+      "side",
+      "align",
+      "gap",
+      "icon",
+      "shortcut",
+      "closeOnSelect"
+    ],
+    "forbidden": [
+      "open",
+      "defaultOpen",
+      "onOpenChange",
+      "onSelect",
+      "onValueChange",
+      "onCheckedChange",
+      "value",
+      "checked",
+      "trigger",
+      "destructive",
+      "disabled"
+    ],
+    "rationale": "Placement and ornament are safe. `onSelect` is the command itself, and `destructive` is a warning an agent must not remove."
+  },
+  "propNotes": {
+    "shortcut": "Displayed only. The component does not bind the key; the application does.",
+    "destructive": "Styles the item as dangerous. Remove it only if the item stops being dangerous."
+  }
+}

package/source/components/modal/passport.json

@@ -8,7 +8,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.6.3",
+    "libraryVersion": "2.7.1",
     "files": [
       "core/dismiss.ts",
       "core/index.ts",
@@ -21,6 +21,7 @@
     ],
     "sourceHash": "sha256:078ceea5f6cf953d95a999fd958a6b2ed8a61e3c9060665eeca4efd53fb70413"
   },
+  "purpose": "Forms, details and drawers above the page, on the native <dialog> element, with focus trapped inside and the rest of the page inert.",
   "props": [
     {
       "name": "aria-label",
@@ -70,7 +71,8 @@
       "default": true,
       "origin": "derived",
       "description": "Default true.",
-      "descriptionOrigin": "jsdoc"
+      "descriptionOrigin": "jsdoc",
+      "note": "Turning it off should be reserved for work that would be lost. A user who cannot dismiss a dialog is stuck."
     },
     {
       "name": "closeOnEscape",
@@ -150,7 +152,8 @@
       "required": false,
       "origin": "derived",
       "description": "Return `false` (or a promise of it) to keep the modal open, e.g. for unsaved changes.",
-      "descriptionOrigin": "jsdoc"
+      "descriptionOrigin": "jsdoc",
+      "note": "Return false to refuse a close, for unsaved work. It runs for Escape and the backdrop too."
     },
     {
       "name": "onOpenChange",
@@ -276,20 +279,60 @@
     }
   ],
   "accessibility": {
-    "supplied": [],
-    "required": []
+    "supplied": [
+      "native <dialog> semantics: the top layer, :modal, and the rest of the page genuinely inert rather than merely covered",
+      "focus moves in on open and returns to the trigger on close",
+      "Escape closes, unless onBeforeClose refuses",
+      "the heading is linked as the dialog's accessible name"
+    ],
+    "required": [
+      "a `description` or a heading — a modal with no name announces as nothing",
+      "`initialFocus` when the first focusable element is not the one a user should land on"
+    ]
+  },
+  "composition": {
+    "mustNotContain": [
+      "Modal",
+      "dialog"
+    ],
+    "notes": "A modal inside a modal puts two dialogs in the top layer and the focus trap of the inner one fights the outer. Use one modal and change its contents. Short questions belong in Dialog, not here."
   },
-  "composition": {},
   "operations": {},
-  "intentDomains": [],
-  "safeMutations": {},
+  "intentDomains": [
+    "ActionIntent"
+  ],
+  "safeMutations": {
+    "allowed": [
+      "size",
+      "placement",
+      "closeButton",
+      "description"
+    ],
+    "forbidden": [
+      "open",
+      "defaultOpen",
+      "onOpenChange",
+      "onBeforeClose",
+      "closeOnBackdrop",
+      "closeOnEscape",
+      "initialFocus",
+      "keepMounted",
+      "footer",
+      "children"
+    ],
+    "rationale": "Size and placement are presentation. `open` is the application's state, and the dismissal props decide whether a user can get out — removing an escape route is never a cosmetic change."
+  },
   "examples": [],
   "coverage": {
     "propsTotal": 17,
     "propsDescribed": 14,
     "describedPct": 82,
     "authoredSections": [
-      "accessibility"
+      "accessibility",
+      "composition",
+      "intentDomains",
+      "purpose",
+      "safeMutations"
     ]
   }
 }

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

@@ -0,0 +1,52 @@
+{
+  "$schema": "../../../schema/passport-overlay-v1.schema.json",
+  "component": "Modal",
+  "purpose": "Forms, details and drawers above the page, on the native <dialog> element, with focus trapped inside and the rest of the page inert.",
+  "intentDomains": [
+    "ActionIntent"
+  ],
+  "accessibility": {
+    "supplied": [
+      "native <dialog> semantics: the top layer, :modal, and the rest of the page genuinely inert rather than merely covered",
+      "focus moves in on open and returns to the trigger on close",
+      "Escape closes, unless onBeforeClose refuses",
+      "the heading is linked as the dialog's accessible name"
+    ],
+    "required": [
+      "a `description` or a heading — a modal with no name announces as nothing",
+      "`initialFocus` when the first focusable element is not the one a user should land on"
+    ]
+  },
+  "composition": {
+    "mustNotContain": [
+      "Modal",
+      "dialog"
+    ],
+    "notes": "A modal inside a modal puts two dialogs in the top layer and the focus trap of the inner one fights the outer. Use one modal and change its contents. Short questions belong in Dialog, not here."
+  },
+  "safeMutations": {
+    "allowed": [
+      "size",
+      "placement",
+      "closeButton",
+      "description"
+    ],
+    "forbidden": [
+      "open",
+      "defaultOpen",
+      "onOpenChange",
+      "onBeforeClose",
+      "closeOnBackdrop",
+      "closeOnEscape",
+      "initialFocus",
+      "keepMounted",
+      "footer",
+      "children"
+    ],
+    "rationale": "Size and placement are presentation. `open` is the application's state, and the dismissal props decide whether a user can get out — removing an escape route is never a cosmetic change."
+  },
+  "propNotes": {
+    "closeOnBackdrop": "Turning it off should be reserved for work that would be lost. A user who cannot dismiss a dialog is stuck.",
+    "onBeforeClose": "Return false to refuse a close, for unsaved work. It runs for Escape and the backdrop too."
+  }
+}

package/source/components/number-input/core/agent.ts

@@ -0,0 +1,38 @@
+/*
+ * NumberInput's agent contract.
+ *
+ * `min`, `max` and `step` become policy: a proposal outside them is refused
+ * by name rather than silently clamped, so the caller learns which rule it hit.
+ *
+ * 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 NumberInputAgentProps {
+  label?: string;
+  disabled?: boolean;
+  readOnly?: boolean;
+  required?: boolean;
+  min?: number;
+  max?: number;
+  step?: number;
+}
+
+export function numberInputContract(props: NumberInputAgentProps = {}): FieldContract {
+  return {
+    component: "NumberInput",
+    kind: "number",
+    operations: ["setValue", "clear", "focus"],
+    label: props.label,
+    disabled: props.disabled,
+    readOnly: props.readOnly,
+    required: props.required,
+    min: props.min,
+    max: props.max,
+    step: props.step,
+  };
+}

package/source/components/number-input/core/index.ts

@@ -2,3 +2,5 @@ export { formatNumber, numberFormat } from "./format";
 export { localeParts, parseNumber, toEditText, type NumberLocaleParts } from "./parse";
 export { clamp, decimalsOf, round, snapToStep, stepBy } from "./step";
 export type * from "./types";
+// The agent contract: what a model may ask this field to do.
+export { numberInputContract, type NumberInputAgentProps } from "./agent";