@cueplusplus/ui 0.13.0

package/manifest/components/date-field.json

@@ -0,0 +1,93 @@
+{
+  "name": "DateField",
+  "slug": "date-field",
+  "group": "date",
+  "importPath": "@cueplusplus/ui/date",
+  "peerDependencies": [
+    "react-aria-components"
+  ],
+  "clientOnly": true,
+  "description": "A typed date, one segment at a time — day, month, year — with no calendar.\n\nThe right control when the user already knows the date: typing `08172026` is\nfaster than three clicks, and a segmented field cannot produce an ambiguous\n`03/04`. Wraps React Aria's `DateField`, so locale-aware segment order,\narrow-key stepping, overflow between segments and the `spinbutton` ARIA\nwiring are the library's; this layer restyles it onto the form chassis.\n\nValues are `@internationalized/date` objects (`CalendarDate`,\n`CalendarDateTime`, `ZonedDateTime`) — not `Date`, which cannot represent\n\"a day\" without dragging a timezone along.\n\n`react-aria-components` is an **optional peer**: import this from\n`@cueplusplus/ui/date`.",
+  "props": [
+    {
+      "name": "size",
+      "type": "\"sm\" | \"md\" | \"lg\"",
+      "required": false,
+      "defaultValue": null,
+      "description": "Rung of the control ladder. Defaults to `\"md\"`.",
+      "control": {
+        "kind": "enum",
+        "members": [
+          "sm",
+          "md",
+          "lg"
+        ]
+      }
+    },
+    {
+      "name": "inputClassName",
+      "type": "ClassNameOrFunction<DateInputRenderProps>",
+      "required": false,
+      "defaultValue": null,
+      "description": "Extra classes for the segment group itself.",
+      "control": {
+        "kind": "opaque"
+      }
+    }
+  ],
+  "typeReferences": [
+    "Omit<AriaDateFieldProps<T>, \"children\">"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-accent",
+    "--cue-accent-fg",
+    "--cue-border",
+    "--cue-border-strong",
+    "--cue-control-lg",
+    "--cue-control-md",
+    "--cue-control-sm",
+    "--cue-danger",
+    "--cue-fg",
+    "--cue-fg-subtle",
+    "--cue-focus",
+    "--cue-font-mono",
+    "--cue-radius-control",
+    "--cue-space-1",
+    "--cue-space-3",
+    "--cue-space-4",
+    "--cue-space-5",
+    "--cue-sunken",
+    "--cue-text-body",
+    "--cue-text-label",
+    "--cue-text-ui"
+  ],
+  "summary": "A typed date, one segment at a time — day, month, year — with no calendar.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<DateField aria-label=\"Go live\" value={date} onChange={setDate} />\n<DateField label={undefined} aria-label=\"Cutoff\" granularity=\"minute\" size=\"sm\" />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/date-field",
+  "mdUrl": "/docs/components/date-field.md",
+  "jsonUrl": "/r/components/date-field.json",
+  "specimens": [
+    {
+      "title": "DateField",
+      "group": "date",
+      "components": [
+        "DateField"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"value\">\n    <DateField aria-label=\"Go live\" defaultValue={new CalendarDate(2026, 8, 17)} />\n  </Specimen>\n  <Specimen label=\"empty\">\n    <DateField aria-label=\"Go live, empty\" />\n  </Specimen>\n  <Specimen label=\"sm\">\n    <DateField aria-label=\"Go live, small\" size=\"sm\" defaultValue={new CalendarDate(2026, 8, 17)} />\n  </Specimen>\n  <Specimen label=\"invalid\">\n    <DateField aria-label=\"Go live, invalid\" isInvalid defaultValue={new CalendarDate(2026, 8, 17)} />\n  </Specimen>\n  <Specimen label=\"disabled\">\n    <DateField aria-label=\"Go live, disabled\" isDisabled defaultValue={new CalendarDate(2026, 8, 17)} />\n  </Specimen>\n</Specimens>",
+      "note": "Typed, one segment at a time, with no calendar. Values are `@internationalized/date` objects, which can hold a day without a timezone attached.",
+      "interaction": "each segment is a `spinbutton`: arrow keys step it, typing overflows into the next one."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/date-picker.json

@@ -0,0 +1,255 @@
+{
+  "name": "DatePicker",
+  "slug": "date-picker",
+  "group": "date",
+  "importPath": "@cueplusplus/ui/date",
+  "peerDependencies": [
+    "date-fns",
+    "react-day-picker"
+  ],
+  "clientOnly": true,
+  "description": "A single day, picked from a calendar in a popover.\n\nThe trigger is a control-chassis button carrying the formatted day, so a date\nfield lines up with the inputs beside it at every density. The calendar is\n`Calendar` (react-day-picker) inside the kit's `Popover`, which means it is\nportalled through the portal contract and renders at the theme and density of\nthe tree it was opened from — not the body's.\n\nPicking a day closes the popup: a single-date picker has nothing left to ask.\n\n`react-day-picker` and `date-fns` are **optional peers**: import this from\n`@cueplusplus/ui/date`.",
+  "props": [
+    {
+      "name": "value",
+      "type": "Date | null",
+      "required": false,
+      "defaultValue": null,
+      "description": "The chosen day. Use with `onValueChange` for a controlled field.",
+      "control": {
+        "kind": "opaque",
+        "nullable": true
+      }
+    },
+    {
+      "name": "defaultValue",
+      "type": "Date | null",
+      "required": false,
+      "defaultValue": null,
+      "description": "Initially chosen day for an uncontrolled field.",
+      "control": {
+        "kind": "opaque",
+        "nullable": true
+      }
+    },
+    {
+      "name": "onValueChange",
+      "type": "((value: Date) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called with the new day, or `undefined` when the day is unpicked.",
+      "control": {
+        "kind": "callback",
+        "fixture": "callback.log"
+      }
+    },
+    {
+      "name": "placeholder",
+      "type": "string",
+      "required": false,
+      "defaultValue": "Pick a date",
+      "description": "Read out while nothing is chosen. Defaults to `\"Pick a date\"`.",
+      "control": {
+        "kind": "string"
+      }
+    },
+    {
+      "name": "dateFormat",
+      "type": "string",
+      "required": false,
+      "defaultValue": "d MMM yyyy",
+      "description": "date-fns pattern for the readout. Defaults to `\"d MMM yyyy\"`.",
+      "control": {
+        "kind": "string"
+      }
+    },
+    {
+      "name": "size",
+      "type": "\"sm\" | \"md\" | \"lg\"",
+      "required": false,
+      "defaultValue": null,
+      "description": "Rung of the control ladder. Defaults to `\"md\"`.",
+      "control": {
+        "kind": "enum",
+        "members": [
+          "sm",
+          "md",
+          "lg"
+        ]
+      }
+    },
+    {
+      "name": "disabled",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": null,
+      "description": "Prevent opening and grey the trigger out.",
+      "control": {
+        "kind": "boolean"
+      }
+    },
+    {
+      "name": "invalid",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": null,
+      "description": "Paint the danger rim — pair it with a `FieldError`.",
+      "control": {
+        "kind": "boolean"
+      }
+    },
+    {
+      "name": "name",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Name for the hidden input, when the field is part of a form. The submitted\nvalue is the ISO date (`yyyy-MM-dd`), never the formatted readout.",
+      "control": {
+        "kind": "string"
+      }
+    },
+    {
+      "name": "id",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Id forwarded to the trigger.",
+      "control": {
+        "kind": "string"
+      }
+    },
+    {
+      "name": "aria-label",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Accessible name for the trigger, when no `FieldLabel` names it.",
+      "control": {
+        "kind": "string"
+      }
+    },
+    {
+      "name": "aria-labelledby",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Id of the element naming the trigger.",
+      "control": {
+        "kind": "string"
+      }
+    },
+    {
+      "name": "className",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Extra classes for the trigger.",
+      "control": {
+        "kind": "string"
+      }
+    },
+    {
+      "name": "popupClassName",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Extra classes for the popup surface.",
+      "control": {
+        "kind": "string"
+      }
+    },
+    {
+      "name": "calendarProps",
+      "type": "DatePickerCalendarProps",
+      "required": false,
+      "defaultValue": null,
+      "description": "Everything else the calendar takes — month bounds, disabled days, locale.",
+      "control": {
+        "kind": "opaque"
+      }
+    },
+    {
+      "name": "open",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": null,
+      "description": "Open state, for a controlled popover.",
+      "control": {
+        "kind": "boolean"
+      }
+    },
+    {
+      "name": "defaultOpen",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": null,
+      "description": "Initial open state.",
+      "control": {
+        "kind": "boolean"
+      }
+    },
+    {
+      "name": "onOpenChange",
+      "type": "((open: boolean) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called when the popover opens or closes.",
+      "control": {
+        "kind": "callback",
+        "fixture": "callback.log"
+      }
+    }
+  ],
+  "typeReferences": [],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-border",
+    "--cue-border-strong",
+    "--cue-control-lg",
+    "--cue-control-md",
+    "--cue-control-sm",
+    "--cue-danger",
+    "--cue-fg",
+    "--cue-fg-subtle",
+    "--cue-focus",
+    "--cue-font-mono",
+    "--cue-icon-sm",
+    "--cue-radius-control",
+    "--cue-space-2",
+    "--cue-space-3",
+    "--cue-space-4",
+    "--cue-space-5",
+    "--cue-sunken",
+    "--cue-text-body",
+    "--cue-text-label",
+    "--cue-text-ui"
+  ],
+  "summary": "A single day, picked from a calendar in a popover.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<DatePicker aria-label=\"Show date\" value={date} onValueChange={setDate} />\n<DatePicker name=\"showDate\" dateFormat=\"EEE d MMM\" calendarProps={{ disabled: past }} />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/date-picker",
+  "mdUrl": "/docs/components/date-picker.md",
+  "jsonUrl": "/r/components/date-picker.json",
+  "specimens": [
+    {
+      "title": "DatePicker",
+      "group": "date",
+      "components": [
+        "DatePicker"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"value\">\n    <DatePicker aria-label=\"Go live\" defaultValue={TODAY} />\n  </Specimen>\n  <Specimen label=\"empty\">\n    <DatePicker aria-label=\"Go live, empty\" placeholder=\"Pick a day\" />\n  </Specimen>\n  <Specimen label=\"invalid\">\n    <DatePicker aria-label=\"Go live, invalid\" defaultValue={TODAY} invalid />\n  </Specimen>\n  <Specimen label=\"disabled\">\n    <DatePicker aria-label=\"Go live, disabled\" defaultValue={TODAY} disabled />\n  </Specimen>\n  <Specimen label=\"sm\">\n    <DatePicker aria-label=\"Go live, small\" defaultValue={TODAY} size=\"sm\" />\n  </Specimen>\n</Specimens>",
+      "note": "The calendar inside a popover, on the form chassis. The trigger prints the formatted date, or the placeholder when there is none.",
+      "interaction": "the popup is portalled through the stamping contract, so it keeps the theme and density of the island it was opened from."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/date-range-picker.json

@@ -0,0 +1,255 @@
+{
+  "name": "DateRangePicker",
+  "slug": "date-range-picker",
+  "group": "date",
+  "importPath": "@cueplusplus/ui/date",
+  "peerDependencies": [
+    "date-fns",
+    "react-day-picker"
+  ],
+  "clientOnly": true,
+  "description": "A span of days, picked from a two-month calendar in a popover.\n\nThe sibling of `DatePicker`, sharing its trigger skin — but *not* its\ndismissal: a range takes two clicks, so the popup stays open through the\nfirst one and the caller hears about both. Close it from `onValueChange` when\n`to` arrives if a one-shot flow suits the page better.\n\n`react-day-picker` and `date-fns` are **optional peers**: import this from\n`@cueplusplus/ui/date`.",
+  "props": [
+    {
+      "name": "value",
+      "type": "DateRange | null",
+      "required": false,
+      "defaultValue": null,
+      "description": "The chosen span. Use with `onValueChange` for a controlled field.",
+      "control": {
+        "kind": "opaque",
+        "nullable": true
+      }
+    },
+    {
+      "name": "defaultValue",
+      "type": "DateRange | null",
+      "required": false,
+      "defaultValue": null,
+      "description": "Initially chosen span for an uncontrolled field.",
+      "control": {
+        "kind": "opaque",
+        "nullable": true
+      }
+    },
+    {
+      "name": "onValueChange",
+      "type": "((value: DateRange) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called after every click inside the calendar — once with `{ from }` when\nthe span opens, again with `{ from, to }` when it closes.",
+      "control": {
+        "kind": "callback",
+        "fixture": "callback.log"
+      }
+    },
+    {
+      "name": "placeholder",
+      "type": "string",
+      "required": false,
+      "defaultValue": "Pick a range",
+      "description": "Read out while nothing is chosen. Defaults to `\"Pick a range\"`.",
+      "control": {
+        "kind": "string"
+      }
+    },
+    {
+      "name": "dateFormat",
+      "type": "string",
+      "required": false,
+      "defaultValue": "d MMM yyyy",
+      "description": "date-fns pattern for both ends of the readout. Defaults to `\"d MMM yyyy\"`.",
+      "control": {
+        "kind": "string"
+      }
+    },
+    {
+      "name": "size",
+      "type": "\"sm\" | \"md\" | \"lg\"",
+      "required": false,
+      "defaultValue": null,
+      "description": "Rung of the control ladder. Defaults to `\"md\"`.",
+      "control": {
+        "kind": "enum",
+        "members": [
+          "sm",
+          "md",
+          "lg"
+        ]
+      }
+    },
+    {
+      "name": "disabled",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": null,
+      "description": "Prevent opening and grey the trigger out.",
+      "control": {
+        "kind": "boolean"
+      }
+    },
+    {
+      "name": "invalid",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": null,
+      "description": "Paint the danger rim — pair it with a `FieldError`.",
+      "control": {
+        "kind": "boolean"
+      }
+    },
+    {
+      "name": "name",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Base name for the hidden inputs; they submit `<name>From` / `<name>To`.",
+      "control": {
+        "kind": "string"
+      }
+    },
+    {
+      "name": "id",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Id forwarded to the trigger.",
+      "control": {
+        "kind": "string"
+      }
+    },
+    {
+      "name": "aria-label",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Accessible name for the trigger, when no `FieldLabel` names it.",
+      "control": {
+        "kind": "string"
+      }
+    },
+    {
+      "name": "aria-labelledby",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Id of the element naming the trigger.",
+      "control": {
+        "kind": "string"
+      }
+    },
+    {
+      "name": "className",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Extra classes for the trigger.",
+      "control": {
+        "kind": "string"
+      }
+    },
+    {
+      "name": "popupClassName",
+      "type": "string",
+      "required": false,
+      "defaultValue": null,
+      "description": "Extra classes for the popup surface.",
+      "control": {
+        "kind": "string"
+      }
+    },
+    {
+      "name": "calendarProps",
+      "type": "DateRangePickerCalendarProps",
+      "required": false,
+      "defaultValue": null,
+      "description": "Everything else the calendar takes. `numberOfMonths` defaults to `2`.",
+      "control": {
+        "kind": "opaque"
+      }
+    },
+    {
+      "name": "open",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": null,
+      "description": "Open state, for a controlled popover.",
+      "control": {
+        "kind": "boolean"
+      }
+    },
+    {
+      "name": "defaultOpen",
+      "type": "boolean",
+      "required": false,
+      "defaultValue": null,
+      "description": "Initial open state.",
+      "control": {
+        "kind": "boolean"
+      }
+    },
+    {
+      "name": "onOpenChange",
+      "type": "((open: boolean) => void)",
+      "required": false,
+      "defaultValue": null,
+      "description": "Called when the popover opens or closes.",
+      "control": {
+        "kind": "callback",
+        "fixture": "callback.log"
+      }
+    }
+  ],
+  "typeReferences": [],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-border",
+    "--cue-border-strong",
+    "--cue-control-lg",
+    "--cue-control-md",
+    "--cue-control-sm",
+    "--cue-danger",
+    "--cue-fg",
+    "--cue-fg-subtle",
+    "--cue-focus",
+    "--cue-font-mono",
+    "--cue-icon-sm",
+    "--cue-radius-control",
+    "--cue-space-2",
+    "--cue-space-3",
+    "--cue-space-4",
+    "--cue-space-5",
+    "--cue-sunken",
+    "--cue-text-body",
+    "--cue-text-label",
+    "--cue-text-ui"
+  ],
+  "summary": "A span of days, picked from a two-month calendar in a popover.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "<DateRangePicker aria-label=\"Window\" value={range} onValueChange={setRange} />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/date-range-picker",
+  "mdUrl": "/docs/components/date-range-picker.md",
+  "jsonUrl": "/r/components/date-range-picker.json",
+  "specimens": [
+    {
+      "title": "DateRangePicker",
+      "group": "date",
+      "components": [
+        "DateRangePicker"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"value\">\n    <DateRangePicker aria-label=\"Run of show\" defaultValue={{ from: TODAY, to: IN_FIVE_DAYS }} />\n  </Specimen>\n  <Specimen label=\"empty\">\n    <DateRangePicker aria-label=\"Run of show, empty\" placeholder=\"Pick a run\" />\n  </Specimen>\n  <Specimen label=\"disabled\">\n    <DateRangePicker\n      aria-label=\"Run of show, disabled\"\n      defaultValue={{ from: TODAY, to: IN_FIVE_DAYS }}\n      disabled\n    />\n  </Specimen>\n</Specimens>",
+      "note": "Two days in one control, formatted as one string.",
+      "interaction": "the first click sets the start, the second the end; clicking before the start restarts the range."
+    }
+  ],
+  "todo": true
+}

package/manifest/components/day-separator.json

@@ -0,0 +1,63 @@
+{
+  "name": "DaySeparator",
+  "slug": "day-separator",
+  "group": "elements",
+  "importPath": "@cueplusplus/ui/elements",
+  "peerDependencies": [],
+  "clientOnly": true,
+  "description": "Chronology in a long thread: days marked, times on hover.",
+  "props": [
+    {
+      "name": "messages",
+      "type": "readonly DatedMessage[]",
+      "required": true,
+      "defaultValue": null,
+      "description": "Turns in order. A separator is inserted wherever day changes from the previous\nmessage, so grouping needs no pre-processing.",
+      "control": {
+        "kind": "array",
+        "fixture": "thread.days"
+      }
+    }
+  ],
+  "typeReferences": [
+    "Omit<ComponentProps<\"div\">, \"children\" | \"messages\"> & {\n  /**\n   * Turns in order. A separator is inserted wherever day changes from the previous\n   * message, so grouping needs no pre-processing.\n   */\n  messages: readonly DatedMessage[];\n}"
+  ],
+  "subcomponents": [],
+  "parts": [],
+  "variants": {},
+  "defaultVariants": {},
+  "tokensUsed": [
+    "--cue-fg-muted",
+    "--cue-fg-subtle",
+    "--cue-leading-ui",
+    "--cue-radius-overlay",
+    "--cue-surface-1",
+    "--cue-surface-2",
+    "--cue-text-body"
+  ],
+  "summary": "Chronology in a long thread: days marked, times on hover.",
+  "examples": [
+    {
+      "title": "Usage",
+      "code": "import { DaySeparator } from \"@cueplusplus/ui/elements\";\n\n<DaySeparator messages={messages} />",
+      "language": "tsx"
+    }
+  ],
+  "status": "todo-docs",
+  "url": "/docs/components/day-separator",
+  "mdUrl": "/docs/components/day-separator.md",
+  "jsonUrl": "/r/components/day-separator.json",
+  "specimens": [
+    {
+      "title": "DaySeparator",
+      "group": "elements-thread",
+      "components": [
+        "DaySeparator"
+      ],
+      "code": "<Specimens>\n  <Specimen label=\"two days, four turns\" wide>\n    <DaySeparator messages={DAYS} />\n  </Specimen>\n</Specimens>",
+      "note": "Chronology in a thread long enough to have some: a rule wherever the day changes, and per-message times that only appear when you go looking. The caller pre-formats both — the element compares the day strings and does no date arithmetic at all.",
+      "interaction": "hover a turn and its timestamp fades up beside it. The rules are decorative; nothing here is a control."
+    }
+  ],
+  "todo": true
+}