@grampro/kit 2.6.3 → 2.7.0

package/source/components/number-input/passport.json

@@ -8,8 +8,9 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.6.3",
+    "libraryVersion": "2.7.0",
     "files": [
+      "core/agent.ts",
       "core/format.ts",
       "core/index.ts",
       "core/parse.ts",
@@ -21,8 +22,9 @@
       "react/locale.ts",
       "react/props.ts"
     ],
-    "sourceHash": "sha256:0cb6347602f25bd7c77b8738d9d1ac5216ee1a6ef50b5bf54f34deeb2d914f7b"
+    "sourceHash": "sha256:b62e20ffb71a95c6e30e7c55f895750de1015364734a3cceacea972e3dc89e6a"
   },
+  "purpose": "A numeric field that reads and writes numbers the way the locale does, with a stepper, clamping and currency formatting.",
   "props": [
     {
       "name": "aria-describedby",
@@ -79,7 +81,8 @@
       "default": "blur",
       "origin": "derived",
       "description": "When a value outside the limits is pulled back. Default `blur`.",
-      "descriptionOrigin": "jsdoc"
+      "descriptionOrigin": "jsdoc",
+      "note": "Decides whether an out-of-range entry is corrected as it is typed or left for validation. Changing it changes what the user is allowed to leave in the field."
     },
     {
       "name": "className",
@@ -456,7 +459,8 @@
       "default": false,
       "origin": "derived",
       "description": "Let the wheel change the value while the field has focus. Default **false**:\r\na wheel that edits a focused field turns an ordinary page scroll into a\r\nsilent change to someone's data.",
-      "descriptionOrigin": "jsdoc"
+      "descriptionOrigin": "jsdoc",
+      "note": "Scroll-to-change is off by default because it fires while a page is being scrolled past."
     }
   ],
   "inherits": [
@@ -534,20 +538,97 @@
     }
   ],
   "accessibility": {
-    "supplied": [],
-    "required": []
+    "supplied": [
+      "role=spinbutton semantics with aria-valuenow, aria-valuemin and aria-valuemax",
+      "ArrowUp and ArrowDown step; PageUp and PageDown use `largeStep`",
+      "the stepper buttons are aria-hidden, because the keyboard already does what they do",
+      "description and error linked by aria-describedby"
+    ],
+    "required": [
+      "a `label`, or `aria-label` when the field is visually unlabelled",
+      "`min` and `max` where a range exists, so assistive technology can announce it"
+    ]
+  },
+  "composition": {
+    "mustNotContain": [
+      "label",
+      "input"
+    ],
+    "notes": "Renders its own label and input."
+  },
+  "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",
+      "stepper",
+      "leading",
+      "trailing",
+      "selectOnFocus",
+      "useGrouping",
+      "clearable"
+    ],
+    "forbidden": [
+      "value",
+      "defaultValue",
+      "name",
+      "min",
+      "max",
+      "step",
+      "largeStep",
+      "decimals",
+      "currency",
+      "locale",
+      "clampBehavior",
+      "snapToStep",
+      "required",
+      "disabled",
+      "readOnly",
+      "onValueChange",
+      "error"
+    ],
+    "rationale": "Everything that defines the number — its bounds, its precision, its currency, how it snaps — is domain truth, not styling. Changing `decimals` or `currency` silently reinterprets a stored value."
   },
-  "composition": {},
-  "operations": {},
-  "intentDomains": [],
-  "safeMutations": {},
   "examples": [],
   "coverage": {
     "propsTotal": 24,
     "propsDescribed": 23,
     "describedPct": 96,
     "authoredSections": [
-      "accessibility"
+      "accessibility",
+      "composition",
+      "intentDomains",
+      "operations",
+      "purpose",
+      "safeMutations"
     ]
   }
 }

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

@@ -0,0 +1,90 @@
+{
+  "$schema": "../../../schema/passport-overlay-v1.schema.json",
+  "component": "NumberInput",
+  "purpose": "A numeric field that reads and writes numbers the way the locale does, with a stepper, clamping and currency formatting.",
+  "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": [
+      "role=spinbutton semantics with aria-valuenow, aria-valuemin and aria-valuemax",
+      "ArrowUp and ArrowDown step; PageUp and PageDown use `largeStep`",
+      "the stepper buttons are aria-hidden, because the keyboard already does what they do",
+      "description and error linked by aria-describedby"
+    ],
+    "required": [
+      "a `label`, or `aria-label` when the field is visually unlabelled",
+      "`min` and `max` where a range exists, so assistive technology can announce it"
+    ]
+  },
+  "composition": {
+    "mustNotContain": [
+      "label",
+      "input"
+    ],
+    "notes": "Renders its own label and input."
+  },
+  "safeMutations": {
+    "allowed": [
+      "size",
+      "placeholder",
+      "description",
+      "stepper",
+      "leading",
+      "trailing",
+      "selectOnFocus",
+      "useGrouping",
+      "clearable"
+    ],
+    "forbidden": [
+      "value",
+      "defaultValue",
+      "name",
+      "min",
+      "max",
+      "step",
+      "largeStep",
+      "decimals",
+      "currency",
+      "locale",
+      "clampBehavior",
+      "snapToStep",
+      "required",
+      "disabled",
+      "readOnly",
+      "onValueChange",
+      "error"
+    ],
+    "rationale": "Everything that defines the number — its bounds, its precision, its currency, how it snaps — is domain truth, not styling. Changing `decimals` or `currency` silently reinterprets a stored value."
+  },
+  "propNotes": {
+    "clampBehavior": "Decides whether an out-of-range entry is corrected as it is typed or left for validation. Changing it changes what the user is allowed to leave in the field.",
+    "wheel": "Scroll-to-change is off by default because it fires while a page is being scrolled past."
+  }
+}

package/source/components/popover/passport.json

@@ -8,7 +8,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.6.3",
+    "libraryVersion": "2.7.0",
     "files": [
       "core/index.ts",
       "core/types.ts",
@@ -19,6 +19,7 @@
     ],
     "sourceHash": "sha256:71722134c43ba8dec7c9139a8c2c84ab4009247f7b8e1699308f6abbc634f278"
   },
+  "purpose": "A panel anchored to the control that opened it, in the top layer, with light dismiss, Escape, and flipping when there is no room.",
   "props": [
     {
       "name": "align",
@@ -166,7 +167,8 @@
       "default": "bottom",
       "origin": "derived",
       "description": "Side of the trigger to open on, before flipping for space. Default `bottom`.",
-      "descriptionOrigin": "jsdoc"
+      "descriptionOrigin": "jsdoc",
+      "note": "A preference, not a guarantee: it flips when there is no room, which is the behaviour you want."
     },
     {
       "name": "style",
@@ -227,20 +229,57 @@
     }
   ],
   "accessibility": {
-    "supplied": [],
-    "required": []
+    "supplied": [
+      "the trigger carries aria-expanded and aria-controls",
+      "Escape closes and focus returns to the trigger",
+      "a click outside dismisses without trapping focus, which is what makes it a popover and not a modal",
+      "the panel renders in the top layer, so no ancestor's overflow clips it"
+    ],
+    "required": [
+      "an accessible name on the trigger when it is an icon",
+      "do not put a form that must be completed in here — focus is not trapped, so a user can wander out of it. That is a Modal."
+    ]
+  },
+  "composition": {
+    "mustNotContain": [
+      "Modal",
+      "Dialog"
+    ],
+    "notes": "A popover does not trap focus. Anything that must be finished before the user moves on belongs in a Modal instead."
   },
-  "composition": {},
   "operations": {},
-  "intentDomains": [],
-  "safeMutations": {},
+  "intentDomains": [
+    "ActionIntent"
+  ],
+  "safeMutations": {
+    "allowed": [
+      "side",
+      "align",
+      "gap",
+      "scrollable",
+      "description"
+    ],
+    "forbidden": [
+      "open",
+      "defaultOpen",
+      "onOpenChange",
+      "trigger",
+      "autoFocus",
+      "children"
+    ],
+    "rationale": "Placement is presentation and the component re-flips it anyway when space runs out. `open` is the application's state."
+  },
   "examples": [],
   "coverage": {
     "propsTotal": 14,
     "propsDescribed": 12,
     "describedPct": 86,
     "authoredSections": [
-      "accessibility"
+      "accessibility",
+      "composition",
+      "intentDomains",
+      "purpose",
+      "safeMutations"
     ]
   }
 }

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

@@ -0,0 +1,48 @@
+{
+  "$schema": "../../../schema/passport-overlay-v1.schema.json",
+  "component": "Popover",
+  "purpose": "A panel anchored to the control that opened it, in the top layer, with light dismiss, Escape, and flipping when there is no room.",
+  "intentDomains": [
+    "ActionIntent"
+  ],
+  "accessibility": {
+    "supplied": [
+      "the trigger carries aria-expanded and aria-controls",
+      "Escape closes and focus returns to the trigger",
+      "a click outside dismisses without trapping focus, which is what makes it a popover and not a modal",
+      "the panel renders in the top layer, so no ancestor's overflow clips it"
+    ],
+    "required": [
+      "an accessible name on the trigger when it is an icon",
+      "do not put a form that must be completed in here — focus is not trapped, so a user can wander out of it. That is a Modal."
+    ]
+  },
+  "composition": {
+    "mustNotContain": [
+      "Modal",
+      "Dialog"
+    ],
+    "notes": "A popover does not trap focus. Anything that must be finished before the user moves on belongs in a Modal instead."
+  },
+  "safeMutations": {
+    "allowed": [
+      "side",
+      "align",
+      "gap",
+      "scrollable",
+      "description"
+    ],
+    "forbidden": [
+      "open",
+      "defaultOpen",
+      "onOpenChange",
+      "trigger",
+      "autoFocus",
+      "children"
+    ],
+    "rationale": "Placement is presentation and the component re-flips it anyway when space runs out. `open` is the application's state."
+  },
+  "propNotes": {
+    "side": "A preference, not a guarantee: it flips when there is no room, which is the behaviour you want."
+  }
+}

package/source/components/progress/passport.json

@@ -9,7 +9,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.6.3",
+    "libraryVersion": "2.7.0",
     "files": [
       "core/index.ts",
       "core/progress.ts",
@@ -22,6 +22,7 @@
     ],
     "sourceHash": "sha256:8c989dc440492a833963b37e6c28fd90a99e54435c545a4f053b77c83d745eaf"
   },
+  "purpose": "A bar or a ring for work with a known end, where an unknown length is a different thing from zero per cent.",
   "props": [
     {
       "name": "aria-describedby",
@@ -176,7 +177,8 @@
       "default": null,
       "origin": "derived",
       "description": "How far along. `null` means the length is not known yet.",
-      "descriptionOrigin": "jsdoc"
+      "descriptionOrigin": "jsdoc",
+      "note": "Undefined means indeterminate, which is announced differently from 0."
     },
     {
       "name": "valueText",
@@ -185,7 +187,8 @@
       "required": false,
       "origin": "derived",
       "description": "Replace what is shown and read, e.g. \"3.2 MB of 8 MB\".",
-      "descriptionOrigin": "jsdoc"
+      "descriptionOrigin": "jsdoc",
+      "note": "Overrides the announced string, for units that are not percentages."
     },
     {
       "name": "variant",
@@ -251,20 +254,46 @@
     }
   ],
   "accessibility": {
-    "supplied": [],
-    "required": []
+    "supplied": [
+      "role=progressbar with aria-valuenow, aria-valuemin and aria-valuemax",
+      "an indeterminate progress omits aria-valuenow rather than reporting zero, which is what tells a screen reader the length is unknown",
+      "`valueText` for when a percentage is not the useful reading"
+    ],
+    "required": [
+      "a `label` saying what is in progress",
+      "leave `value` undefined for work of unknown length — zero is a claim that nothing has happened"
+    ]
+  },
+  "composition": {
+    "notes": "A bar and a ring are the same component with a different `variant`."
   },
-  "composition": {},
   "operations": {},
   "intentDomains": [],
-  "safeMutations": {},
+  "safeMutations": {
+    "allowed": [
+      "variant",
+      "size",
+      "thickness",
+      "showValue",
+      "label"
+    ],
+    "forbidden": [
+      "value",
+      "max",
+      "valueText"
+    ],
+    "rationale": "The shape is presentation; the value is the measurement."
+  },
   "examples": [],
   "coverage": {
     "propsTotal": 9,
     "propsDescribed": 8,
     "describedPct": 89,
     "authoredSections": [
-      "accessibility"
+      "accessibility",
+      "composition",
+      "purpose",
+      "safeMutations"
     ]
   }
 }

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

@@ -0,0 +1,39 @@
+{
+  "$schema": "../../../schema/passport-overlay-v1.schema.json",
+  "component": "Progress",
+  "purpose": "A bar or a ring for work with a known end, where an unknown length is a different thing from zero per cent.",
+  "intentDomains": [],
+  "accessibility": {
+    "supplied": [
+      "role=progressbar with aria-valuenow, aria-valuemin and aria-valuemax",
+      "an indeterminate progress omits aria-valuenow rather than reporting zero, which is what tells a screen reader the length is unknown",
+      "`valueText` for when a percentage is not the useful reading"
+    ],
+    "required": [
+      "a `label` saying what is in progress",
+      "leave `value` undefined for work of unknown length — zero is a claim that nothing has happened"
+    ]
+  },
+  "composition": {
+    "notes": "A bar and a ring are the same component with a different `variant`."
+  },
+  "safeMutations": {
+    "allowed": [
+      "variant",
+      "size",
+      "thickness",
+      "showValue",
+      "label"
+    ],
+    "forbidden": [
+      "value",
+      "max",
+      "valueText"
+    ],
+    "rationale": "The shape is presentation; the value is the measurement."
+  },
+  "propNotes": {
+    "value": "Undefined means indeterminate, which is announced differently from 0.",
+    "valueText": "Overrides the announced string, for units that are not percentages."
+  }
+}

package/source/components/radio-group/core/agent.ts

@@ -0,0 +1,34 @@
+/*
+ * RadioGroup's agent contract.
+ *
+ * A choice over the group's own options, so an unknown value is refused by
+ * the reference layer with the nearest real option suggested.
+ *
+ * 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 RadioGroupAgentProps {
+  label?: string;
+  disabled?: boolean;
+  readOnly?: boolean;
+  required?: boolean;
+  options?: readonly { value: string; label: string; disabled?: boolean }[];
+}
+
+export function radioGroupContract(props: RadioGroupAgentProps = {}): FieldContract {
+  return {
+    component: "RadioGroup",
+    kind: "choice",
+    operations: ["setValue", "clear", "focus"],
+    label: props.label,
+    disabled: props.disabled,
+    readOnly: props.readOnly,
+    required: props.required,
+    options: props.options,
+  };
+}

package/source/components/radio-group/core/index.ts

@@ -1,2 +1,4 @@
 export { hasEnabledOption, normalizeOptions, resolveValue } from "./group";
 export type * from "./types";
+// The agent contract: what a model may ask this field to do.
+export { radioGroupContract, type RadioGroupAgentProps } from "./agent";

package/source/components/radio-group/passport.json

@@ -10,8 +10,9 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.6.3",
+    "libraryVersion": "2.7.0",
     "files": [
+      "core/agent.ts",
       "core/group.ts",
       "core/index.ts",
       "core/types.ts",
@@ -22,8 +23,9 @@
       "react/locale.ts",
       "react/props.ts"
     ],
-    "sourceHash": "sha256:7e13b8cd8a2bab1ee7a89cf691c1dc388951723939ca4a87def57d6301d8aa33"
+    "sourceHash": "sha256:8630723accbd754b823c4f2d7f5c1c0da02252d3a51f87b8abeaad117bd75064"
   },
+  "purpose": "One choice out of a few, on native radios: a single tab stop, arrow keys between the choices, and a card variant for richer options.",
   "props": [
     {
       "name": "aria-describedby",
@@ -394,7 +396,8 @@
       "default": "default",
       "origin": "derived",
       "description": "Default `default`. `card` draws each choice as a tile.",
-      "descriptionOrigin": "jsdoc"
+      "descriptionOrigin": "jsdoc",
+      "note": "`card` renders each option as a selectable surface; the semantics are identical."
     }
   ],
   "inherits": [
@@ -476,20 +479,84 @@
     }
   ],
   "accessibility": {
-    "supplied": [],
-    "required": []
+    "supplied": [
+      "native radio semantics: one tab stop for the group, arrow keys to move and select",
+      "a fieldset with the group label as its legend",
+      "description and error linked by aria-describedby"
+    ],
+    "required": [
+      "a `label` for the group — a set of radios with no question is meaningless",
+      "`name`, so the browser treats them as one group"
+    ]
+  },
+  "composition": {
+    "allowedChildren": [
+      "Radio",
+      "RadioCard"
+    ],
+    "notes": "Children or `options`, not both. A radio outside a RadioGroup loses the arrow-key behaviour."
+  },
+  "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",
+      "orientation",
+      "variant",
+      "description"
+    ],
+    "forbidden": [
+      "value",
+      "defaultValue",
+      "name",
+      "options",
+      "required",
+      "disabled",
+      "readOnly",
+      "onChange",
+      "onValueChange",
+      "error"
+    ],
+    "rationale": "The selected value is the user's answer and `options` is the question."
   },
-  "composition": {},
-  "operations": {},
-  "intentDomains": [],
-  "safeMutations": {},
   "examples": [],
   "coverage": {
     "propsTotal": 20,
     "propsDescribed": 16,
     "describedPct": 80,
     "authoredSections": [
-      "accessibility"
+      "accessibility",
+      "composition",
+      "intentDomains",
+      "operations",
+      "purpose",
+      "safeMutations"
     ]
   }
 }