@grampro/kit 2.6.3 → 2.7.1

package/source/components/date-picker/passport.json

@@ -10,8 +10,9 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.6.3",
+    "libraryVersion": "2.7.1",
     "files": [
+      "core/agent.ts",
       "core/calendar.ts",
       "core/format.ts",
       "core/index.ts",
@@ -29,8 +30,9 @@
       "react/props.ts",
       "react/useDatePicker.ts"
     ],
-    "sourceHash": "sha256:2370299b9b495fd18671fb31106c1ba88e834227e3b9632207c048da66982370"
+    "sourceHash": "sha256:abe15583c9bca1d5cce8aa9a3cbbcfcfd29ad44b7e63a3b66956089dc2d18f72"
   },
+  "purpose": "DatePicker and DateRangePicker: a text field people can type dates into, plus a calendar, both honouring the locale's order and separators.",
   "props": [
     {
       "name": "allowInput",
@@ -126,7 +128,8 @@
       "required": false,
       "origin": "derived",
       "description": "How the chosen date is displayed. `Intl.DateTimeFormatOptions` for the\nusual cases, or a function for a shape Intl cannot express. Left out,\nthe locale's own date format is used - which is the right default far\nmore often than a hand-written one.",
-      "descriptionOrigin": "jsdoc"
+      "descriptionOrigin": "jsdoc",
+      "note": "How a typed string is parsed as well as displayed. Changing it can turn a valid entry into a different day."
     },
     {
       "name": "id",
@@ -238,7 +241,8 @@
       "required": false,
       "origin": "derived",
       "description": "Shortcuts shown beside the calendar (\"Last 7 days\").",
-      "descriptionOrigin": "jsdoc"
+      "descriptionOrigin": "jsdoc",
+      "note": "Labelled shortcuts such as last quarter. They write the same value the calendar does."
     },
     {
       "name": "readOnly",
@@ -404,20 +408,107 @@
     }
   ],
   "accessibility": {
-    "supplied": [],
-    "required": []
+    "supplied": [
+      "the calendar is a grid with arrow keys between days, PageUp/PageDown between months, Home and End within a week",
+      "the selected and focused days are distinguished for assistive technology, not only by colour",
+      "the field accepts typing, so the calendar is never the only way in",
+      "Escape closes the calendar and returns focus to the field"
+    ],
+    "required": [
+      "a `label`, or `aria-label` when the field is visually unlabelled",
+      "a `locale` matching the user's, since 03/04 is two different days in two places"
+    ]
+  },
+  "composition": {
+    "notes": "The calendar renders in the top layer. `presets` are shortcuts into the same value, not a separate control."
+  },
+  "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
+    },
+    "open": {
+      "summary": "Open the field's calendar or option list.",
+      "effects": [
+        "shows the overlay"
+      ],
+      "reversible": true
+    },
+    "close": {
+      "summary": "Close the field's calendar or option list.",
+      "effects": [
+        "hides the overlay"
+      ],
+      "reversible": true
+    }
+  },
+  "intentDomains": [
+    "TemporalInterpretation",
+    "ActionIntent"
+  ],
+  "safeMutations": {
+    "allowed": [
+      "size",
+      "placeholder",
+      "description",
+      "numberOfMonths",
+      "showToday",
+      "showWeekNumbers",
+      "fixedWeeks",
+      "presets",
+      "clearable",
+      "closeOnSelect",
+      "allowInput"
+    ],
+    "forbidden": [
+      "value",
+      "defaultValue",
+      "name",
+      "min",
+      "max",
+      "isDateDisabled",
+      "format",
+      "locale",
+      "weekStartsOn",
+      "required",
+      "disabled",
+      "readOnly",
+      "onChange",
+      "error"
+    ],
+    "rationale": "Calendar chrome is presentation. `min`, `max` and `isDateDisabled` are the rules about which dates are legal, and `format` and `locale` decide how a typed string is read — changing either can reinterpret a date the user already entered."
   },
-  "composition": {},
-  "operations": {},
-  "intentDomains": [],
-  "safeMutations": {},
   "examples": [],
   "coverage": {
     "propsTotal": 28,
     "propsDescribed": 22,
     "describedPct": 79,
     "authoredSections": [
-      "accessibility"
+      "accessibility",
+      "composition",
+      "intentDomains",
+      "operations",
+      "purpose",
+      "safeMutations"
     ]
   }
 }

package/source/components/date-picker/passport.manual.json

@@ -0,0 +1,100 @@
+{
+  "$schema": "../../../schema/passport-overlay-v1.schema.json",
+  "component": "DatePicker",
+  "purpose": "DatePicker and DateRangePicker: a text field people can type dates into, plus a calendar, both honouring the locale's order and separators.",
+  "intentDomains": [
+    "TemporalInterpretation",
+    "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
+    },
+    "open": {
+      "summary": "Open the field's calendar or option list.",
+      "effects": [
+        "shows the overlay"
+      ],
+      "reversible": true
+    },
+    "close": {
+      "summary": "Close the field's calendar or option list.",
+      "effects": [
+        "hides the overlay"
+      ],
+      "reversible": true
+    }
+  },
+  "accessibility": {
+    "supplied": [
+      "the calendar is a grid with arrow keys between days, PageUp/PageDown between months, Home and End within a week",
+      "the selected and focused days are distinguished for assistive technology, not only by colour",
+      "the field accepts typing, so the calendar is never the only way in",
+      "Escape closes the calendar and returns focus to the field"
+    ],
+    "required": [
+      "a `label`, or `aria-label` when the field is visually unlabelled",
+      "a `locale` matching the user's, since 03/04 is two different days in two places"
+    ]
+  },
+  "composition": {
+    "notes": "The calendar renders in the top layer. `presets` are shortcuts into the same value, not a separate control."
+  },
+  "safeMutations": {
+    "allowed": [
+      "size",
+      "placeholder",
+      "description",
+      "numberOfMonths",
+      "showToday",
+      "showWeekNumbers",
+      "fixedWeeks",
+      "presets",
+      "clearable",
+      "closeOnSelect",
+      "allowInput"
+    ],
+    "forbidden": [
+      "value",
+      "defaultValue",
+      "name",
+      "min",
+      "max",
+      "isDateDisabled",
+      "format",
+      "locale",
+      "weekStartsOn",
+      "required",
+      "disabled",
+      "readOnly",
+      "onChange",
+      "error"
+    ],
+    "rationale": "Calendar chrome is presentation. `min`, `max` and `isDateDisabled` are the rules about which dates are legal, and `format` and `locale` decide how a typed string is read — changing either can reinterpret a date the user already entered."
+  },
+  "propNotes": {
+    "format": "How a typed string is parsed as well as displayed. Changing it can turn a valid entry into a different day.",
+    "presets": "Labelled shortcuts such as last quarter. They write the same value the calendar does."
+  }
+}

package/source/components/date-picker/react/DatePicker.tsx

@@ -124,6 +124,12 @@ export function DatePicker(props: DatePickerProps) {
       toggle: () => picker.setOpen(!picker.open),
       focus: () => inputRef.current?.focus({ preventScroll: true }),
       clear: picker.clear,
+      // `applyRange` is what the presets already use; a single picker is a
+      // range whose two ends are the same day.
+      setValue: (next) => {
+        const date = toDate(next as DateInput);
+        picker.applyRange({ start: date, end: date }, true);
+      },
       getValue: () => picker.selection.start,
     }),
     [picker],

package/source/components/date-picker/react/DateRangePicker.tsx

@@ -136,6 +136,10 @@ export function DateRangePicker(props: DateRangePickerProps) {
       toggle: () => picker.setOpen(!picker.open),
       focus: () => startRef.current?.focus({ preventScroll: true }),
       clear: picker.clear,
+      setValue: (next) => {
+        const range = (next ?? { start: null, end: null }) as { start?: DateInput; end?: DateInput };
+        picker.applyRange({ start: toDate(range.start ?? null), end: toDate(range.end ?? null) }, true);
+      },
       getValue: () => picker.selection,
     }),
     [picker],

package/source/components/date-picker/react/props.ts

@@ -18,6 +18,23 @@ export interface DatePickerHandle<TValue> {
   toggle(): void;
   focus(): void;
   clear(): void;
+  /**
+   * Set the value, as picking from the calendar would: the change handler
+   * fires and an uncontrolled picker updates itself.
+   *
+   * Takes what the component's own `value` prop takes — a `Date`, an ISO
+   * `yyyy-mm-dd` string, or `null` for the single picker; a `{ start, end }`
+   * range for the range picker. A range given the wrong way round is
+   * normalised rather than refused, which is what choosing those two days in
+   * that order on the calendar already does.
+   *
+   * It respects `disabled` and `readOnly` and does nothing when either is set.
+   * It does *not* check `min`, `max` or `isDateDisabled`: those describe what
+   * a person may pick, and a host setting a value programmatically is not a
+   * person. The agent runtime's policy layer enforces them for anything that
+   * arrives from a model.
+   */
+  setValue(next: TValue | string | null): void;
   getValue(): TValue;
 }
 

package/source/components/dialog/passport.json

@@ -9,7 +9,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.6.3",
+    "libraryVersion": "2.7.1",
     "files": [
       "core/api.ts",
       "core/dialog.ts",
@@ -25,6 +25,7 @@
     ],
     "sourceHash": "sha256:f0b7d7683418b4981af453e5bf4dc08034a6d854dbca6e192283a555e77fdd0d"
   },
+  "purpose": "Alert, confirm and prompt dialogs you call from an event handler and await, so there is no open state to hold. For short questions; a form belongs in Modal.",
   "props": [
     {
       "name": "cancelLabel",
@@ -158,7 +159,8 @@
       "default": "confirm",
       "origin": "derived",
       "description": "`alert` has one button, `confirm` two, `prompt` adds a text field. Default `confirm`.",
-      "descriptionOrigin": "jsdoc"
+      "descriptionOrigin": "jsdoc",
+      "note": "alert, confirm or prompt. It decides the shape of what the promise resolves to."
     },
     {
       "name": "localeText",
@@ -263,7 +265,8 @@
       "required": false,
       "origin": "derived",
       "description": "Return a message to block confirming.",
-      "descriptionOrigin": "jsdoc"
+      "descriptionOrigin": "jsdoc",
+      "note": "Prompt only. Returning a string keeps the dialog open and shows it as the error."
     }
   ],
   "inherits": [
@@ -339,20 +342,62 @@
     }
   ],
   "accessibility": {
-    "supplied": [],
-    "required": []
+    "supplied": [
+      "built on the same native <dialog> as Modal: top layer, inert page, focus trapped and returned",
+      "the confirm button takes initial focus, and Enter resolves it",
+      "Escape resolves as a cancel rather than leaving the promise hanging",
+      "the intent is conveyed in text, not only by the icon's colour"
+    ],
+    "required": [
+      "a question that reads as a question, and button labels that name the action rather than saying Yes and No",
+      "`intent: \"danger\"` on anything destructive, so the styling matches the stakes"
+    ]
+  },
+  "composition": {
+    "mustNotContain": [
+      "Dialog",
+      "Modal",
+      "dialog"
+    ],
+    "notes": "Called as a function, not composed as a tree. Mount the host once; do not nest it inside another dialog."
   },
-  "composition": {},
   "operations": {},
-  "intentDomains": [],
-  "safeMutations": {},
+  "intentDomains": [
+    "ActionIntent"
+  ],
+  "safeMutations": {
+    "allowed": [
+      "size",
+      "icon",
+      "confirmLabel",
+      "cancelLabel"
+    ],
+    "forbidden": [
+      "open",
+      "kind",
+      "intent",
+      "onConfirm",
+      "onClose",
+      "validate",
+      "store",
+      "defaultValue",
+      "required",
+      "inputType",
+      "dismissible"
+    ],
+    "rationale": "Labels and the icon are presentation, provided the labels still name the same action. `kind` changes whether it returns a boolean or a string, `intent` is the warning, and `validate` decides what a prompt will accept."
+  },
   "examples": [],
   "coverage": {
     "propsTotal": 21,
     "propsDescribed": 16,
     "describedPct": 76,
     "authoredSections": [
-      "accessibility"
+      "accessibility",
+      "composition",
+      "intentDomains",
+      "purpose",
+      "safeMutations"
     ]
   }
 }

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

@@ -0,0 +1,54 @@
+{
+  "$schema": "../../../schema/passport-overlay-v1.schema.json",
+  "component": "Dialog",
+  "purpose": "Alert, confirm and prompt dialogs you call from an event handler and await, so there is no open state to hold. For short questions; a form belongs in Modal.",
+  "intentDomains": [
+    "ActionIntent"
+  ],
+  "accessibility": {
+    "supplied": [
+      "built on the same native <dialog> as Modal: top layer, inert page, focus trapped and returned",
+      "the confirm button takes initial focus, and Enter resolves it",
+      "Escape resolves as a cancel rather than leaving the promise hanging",
+      "the intent is conveyed in text, not only by the icon's colour"
+    ],
+    "required": [
+      "a question that reads as a question, and button labels that name the action rather than saying Yes and No",
+      "`intent: \"danger\"` on anything destructive, so the styling matches the stakes"
+    ]
+  },
+  "composition": {
+    "mustNotContain": [
+      "Dialog",
+      "Modal",
+      "dialog"
+    ],
+    "notes": "Called as a function, not composed as a tree. Mount the host once; do not nest it inside another dialog."
+  },
+  "safeMutations": {
+    "allowed": [
+      "size",
+      "icon",
+      "confirmLabel",
+      "cancelLabel"
+    ],
+    "forbidden": [
+      "open",
+      "kind",
+      "intent",
+      "onConfirm",
+      "onClose",
+      "validate",
+      "store",
+      "defaultValue",
+      "required",
+      "inputType",
+      "dismissible"
+    ],
+    "rationale": "Labels and the icon are presentation, provided the labels still name the same action. `kind` changes whether it returns a boolean or a string, `intent` is the warning, and `validate` decides what a prompt will accept."
+  },
+  "propNotes": {
+    "kind": "alert, confirm or prompt. It decides the shape of what the promise resolves to.",
+    "validate": "Prompt only. Returning a string keeps the dialog open and shows it as the error."
+  }
+}

package/source/components/file-uploader/passport.json

@@ -13,7 +13,7 @@
     ]
   },
   "source": {
-    "libraryVersion": "2.6.3",
+    "libraryVersion": "2.7.1",
     "files": [
       "core/format.ts",
       "core/index.ts",
@@ -31,6 +31,7 @@
     ],
     "sourceHash": "sha256:f77a12b14c2d24bc55a922a38f2f85dca85eafe89f63ffb28932e0dc4639d965"
   },
+  "purpose": "Drop, browse or paste files, validate them against size and type, and upload in chunks that can pause, resume and retry.",
   "props": [
     {
       "name": "accept",
@@ -58,7 +59,8 @@
       "default": false,
       "origin": "derived",
       "description": "Upload as soon as files are added. Default false.",
-      "descriptionOrigin": "jsdoc"
+      "descriptionOrigin": "jsdoc",
+      "note": "Off means the host triggers the upload; on means dropping a file starts a network request immediately."
     },
     {
       "name": "chunkSize",
@@ -116,7 +118,8 @@
       "required": false,
       "origin": "derived",
       "description": "Where chunks are POSTed. Without `endpoint` or `transport`, files are only selected.",
-      "descriptionOrigin": "jsdoc"
+      "descriptionOrigin": "jsdoc",
+      "note": "Where files are sent. Never an agent's to set."
     },
     {
       "name": "error",
@@ -409,7 +412,8 @@
       "required": false,
       "origin": "derived",
       "description": "Replaces the built-in HTTP transport, e.g. for presigned URLs or an SDK.",
-      "descriptionOrigin": "jsdoc"
+      "descriptionOrigin": "jsdoc",
+      "note": "Replaces the whole upload mechanism. Treat as code, not configuration."
     },
     {
       "name": "validate",
@@ -525,20 +529,71 @@
     }
   ],
   "accessibility": {
-    "supplied": [],
-    "required": []
+    "supplied": [
+      "the drop zone is a real button, so it is reachable and operable from the keyboard",
+      "upload progress is announced through a live region rather than only drawn",
+      "each file row names its own state and its own remove control",
+      "rejection reasons are text, not just a red border"
+    ],
+    "required": [
+      "a `label` on the drop zone saying what should be uploaded",
+      "`accept` and `maxSize` matching what the server enforces, so a file is refused before it is sent rather than after"
+    ]
+  },
+  "composition": {
+    "notes": "The uploader owns the file list it renders. `existingFiles` describes files already on the server and is a different thing from the queue."
   },
-  "composition": {},
   "operations": {},
-  "intentDomains": [],
-  "safeMutations": {},
+  "intentDomains": [
+    "Extraction",
+    "Classification"
+  ],
+  "safeMutations": {
+    "allowed": [
+      "size",
+      "description",
+      "preview",
+      "removable",
+      "label"
+    ],
+    "forbidden": [
+      "endpoint",
+      "method",
+      "headers",
+      "params",
+      "transport",
+      "chunkSize",
+      "concurrency",
+      "retries",
+      "retryDelay",
+      "withCredentials",
+      "accept",
+      "maxSize",
+      "minSize",
+      "maxFiles",
+      "multiple",
+      "validate",
+      "autoUpload",
+      "name",
+      "required",
+      "disabled",
+      "onChange",
+      "onUploadComplete",
+      "parseResponse"
+    ],
+    "rationale": "This is the one component where a wrong prop sends data somewhere. Everything describing the destination, the credentials sent with it, or what is allowed through is off-limits to an agent; only how the queue looks is safe."
+  },
   "examples": [],
   "coverage": {
     "propsTotal": 39,
     "propsDescribed": 36,
     "describedPct": 92,
     "authoredSections": [
-      "accessibility"
+      "accessibility",
+      "composition",
+      "intentDomains",
+      "purpose",
+      "safeMutations"
     ]
   }
 }

package/source/components/file-uploader/passport.manual.json

@@ -0,0 +1,64 @@
+{
+  "$schema": "../../../schema/passport-overlay-v1.schema.json",
+  "component": "FileUploader",
+  "purpose": "Drop, browse or paste files, validate them against size and type, and upload in chunks that can pause, resume and retry.",
+  "intentDomains": [
+    "Extraction",
+    "Classification"
+  ],
+  "accessibility": {
+    "supplied": [
+      "the drop zone is a real button, so it is reachable and operable from the keyboard",
+      "upload progress is announced through a live region rather than only drawn",
+      "each file row names its own state and its own remove control",
+      "rejection reasons are text, not just a red border"
+    ],
+    "required": [
+      "a `label` on the drop zone saying what should be uploaded",
+      "`accept` and `maxSize` matching what the server enforces, so a file is refused before it is sent rather than after"
+    ]
+  },
+  "composition": {
+    "notes": "The uploader owns the file list it renders. `existingFiles` describes files already on the server and is a different thing from the queue."
+  },
+  "safeMutations": {
+    "allowed": [
+      "size",
+      "description",
+      "preview",
+      "removable",
+      "label"
+    ],
+    "forbidden": [
+      "endpoint",
+      "method",
+      "headers",
+      "params",
+      "transport",
+      "chunkSize",
+      "concurrency",
+      "retries",
+      "retryDelay",
+      "withCredentials",
+      "accept",
+      "maxSize",
+      "minSize",
+      "maxFiles",
+      "multiple",
+      "validate",
+      "autoUpload",
+      "name",
+      "required",
+      "disabled",
+      "onChange",
+      "onUploadComplete",
+      "parseResponse"
+    ],
+    "rationale": "This is the one component where a wrong prop sends data somewhere. Everything describing the destination, the credentials sent with it, or what is allowed through is off-limits to an agent; only how the queue looks is safe."
+  },
+  "propNotes": {
+    "endpoint": "Where files are sent. Never an agent's to set.",
+    "transport": "Replaces the whole upload mechanism. Treat as code, not configuration.",
+    "autoUpload": "Off means the host triggers the upload; on means dropping a file starts a network request immediately."
+  }
+}