@adia-ai/web-modules 0.8.35 → 0.8.37

package/dashboard/date-range-selector/date-range-selector.a2ui.json

@@ -0,0 +1,236 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://adiaui.dev/a2ui/v0_9/components/DateRangeSelector.json",
+  "title": "DateRangeSelector",
+  "description": "Page-level \"current time window\" chooser for dashboards. A module-tier\ncomposite that pairs a preset chip-row (Today / 7d / 30d / 90d / QTD /\nYTD / Custom) with an embedded <date-range-picker-ui> and broadcasts\nthe active range to every range-aware panel on the page.\n\nOne chooser, one event bus, every panel follows. The composite owns\nthe range value, resolves preset keys to ISO 8601 from/to pairs, and\nemits a `range-change` CustomEvent on the configured broadcast target\n(default `document`). It also writes `data-range-from` /\n`data-range-to` to that target so CSS-only subscribers can match\nattribute selectors.\n\nUse for dashboard toolbars (typically <dashboard-layout-ui slot=\"toolbar\">\nor <admin-page-header slot=\"action\">). For card-local per-panel\ncomparison overlays, set [broadcast=\"self\"] so the secondary instance\nscopes to its host.\n\nSpec: .claude/docs/specs/implementation-ready/SPEC-019-date-range-selector-global.md.\n",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "common_types.json#/$defs/ComponentCommon"
+    },
+    {
+      "$ref": "common_types.json#/$defs/CatalogComponentCommon"
+    }
+  ],
+  "properties": {
+    "aria-label": {
+      "description": "Accessible name for the toolbar group (role=group). Defaults to\n\"Time period\"; override when multiple range selectors sit on the\nsame page (e.g., \"Primary range\" / \"Comparison range\").\n",
+      "type": "string",
+      "default": "Time period"
+    },
+    "broadcast": {
+      "description": "Broadcast scope. `document` fires `range-change` on\n`document.documentElement` AND writes `data-range-from` /\n`data-range-to` there (page-global). `self` fires on the host and\nwrites the same attributes to the host (scoped subscribers).\n`none` suppresses broadcast entirely; only the host-level `change`\nevent fires.\n",
+      "type": "string",
+      "enum": [
+        "document",
+        "self",
+        "none"
+      ],
+      "default": "document"
+    },
+    "component": {
+      "const": "DateRangeSelector"
+    },
+    "disabled": {
+      "description": "Non-interactive; chips and the embedded picker dim and suppress\npointer-events via the CSS scope.\n",
+      "type": "boolean",
+      "default": false
+    },
+    "from": {
+      "description": "Start of the resolved range, ISO-8601 date (YYYY-MM-DD). Read-only\noutput — set by the composite when value resolves or when the\nembedded picker commits a custom range. Consumers read this after\n`range-change`.\n",
+      "$ref": "common_types.json#/$defs/DynamicString"
+    },
+    "name": {
+      "description": "Form field name (UIFormElement convention). When set, the\ncomposite participates in form submission — the resolved range\nserializes as a colon-pair \"{from}:{to}\" via ElementInternals.\nWithout it, the composite emits events only.\n",
+      "type": "string",
+      "default": ""
+    },
+    "presets": {
+      "description": "Override the preset chip list as a comma-separated subset of the\n`value` enum. Order matters. `custom` is optional but recommended\nas the trailing chip. Unknown keys are ignored at runtime.\n",
+      "type": "string",
+      "default": "today,7d,30d,90d,qtd,ytd,custom"
+    },
+    "to": {
+      "description": "End of the resolved range, ISO-8601 date. Same read-only output\nsemantics as `from`.\n",
+      "$ref": "common_types.json#/$defs/DynamicString"
+    },
+    "value": {
+      "description": "Active preset key. Drives the chip-row selection and re-resolves\nthe from/to range on change. `custom` defers to the embedded\npicker's value (consumer-supplied from/to).\n",
+      "$ref": "common_types.json#/$defs/DynamicString"
+    }
+  },
+  "required": [
+    "component"
+  ],
+  "unevaluatedProperties": false,
+  "x-adiaui": {
+    "anti_patterns": [
+      {
+        "description": "Two document-broadcasters on the same page. The late mounter wins\nsilently for the data-range-* attributes on <html>, and CSS-only\nsubscribers see flicker as the attributes are rewritten.\n",
+        "right": "<date-range-selector-ui broadcast=\"document\"></date-range-selector-ui>\n<date-range-selector-ui broadcast=\"self\"></date-range-selector-ui>\n",
+        "rule": "Pick ONE global broadcaster; route secondary instances via\nbroadcast=\"self\" so they emit only on the host.\n",
+        "wrong": "<date-range-selector-ui broadcast=\"document\"></date-range-selector-ui>\n<date-range-selector-ui broadcast=\"document\"></date-range-selector-ui>\n"
+      },
+      {
+        "description": "Using DateRangeSelector for single-date selection. The composite\nresolves a range; the picker UI exposes two-pane selection. For\nsingle-date use <input-ui type=\"date\"> or <calendar-picker-ui>.\n",
+        "right": "<input-ui type=\"date\" name=\"d\"></input-ui>\n",
+        "rule": "Range chooser → DateRangeSelector. Single-date chooser → input-ui\ntype=date or calendar-picker-ui.\n",
+        "wrong": "<date-range-selector-ui value=\"today\"></date-range-selector-ui>\n<!-- The selector still resolves a range (from=today, to=today). -->\n"
+      },
+      {
+        "description": "Custom selected with no from/to. The composite falls back to the\nprevious resolved range, which may be empty on first mount —\nconsumers see mystery behavior.\n",
+        "right": "<date-range-selector-ui value=\"custom\" from=\"2026-05-01\" to=\"2026-05-07\"></date-range-selector-ui>\n",
+        "rule": "value=\"custom\" requires either declarative from/to or a follow-on\nsetRange(\"custom\", from, to) call before the chooser is meaningful.\n",
+        "wrong": "<date-range-selector-ui value=\"custom\"></date-range-selector-ui>\n"
+      },
+      {
+        "description": "Unknown preset key. The composite resolves to the default (\"7d\")\nand the consumer sees an unexpected range.\n",
+        "right": "<date-range-selector-ui value=\"qtd\"></date-range-selector-ui>\n",
+        "rule": "Use documented enum keys only — today, 7d, 30d, 90d, qtd, ytd,\ncustom. Quarter-to-date is `qtd`.\n",
+        "wrong": "<date-range-selector-ui value=\"lastQuarter\"></date-range-selector-ui>\n"
+      }
+    ],
+    "category": "input",
+    "composes": [
+      "date-range-picker-ui",
+      "segmented-ui",
+      "segment-ui",
+      "button-ui",
+      "text-ui"
+    ],
+    "events": {
+      "change": {
+        "description": "Alias of range-change, fires on the host element only (UIFormElement\nconvention). When [name] is set, the form value is the colon-pair\n\"{from}:{to}\".\n",
+        "detail": {
+          "from": "string",
+          "to": "string",
+          "value": "string"
+        }
+      },
+      "range-change": {
+        "description": "Fired when the resolved range changes — preset clicked, custom\nrange applied, or programmatic setRange(). Fires on the broadcast\ntarget per [broadcast]. Guaranteed once per resolved range; never\nfires for in-progress picker interactions.\n",
+        "detail": {
+          "from": "string",
+          "preset": "string",
+          "to": "string",
+          "value": "string"
+        }
+      }
+    },
+    "examples": [
+      {
+        "description": "Page-global selector in a dashboard toolbar; charts subscribe to range-change on document.",
+        "a2ui": "[\n  {\n    \"id\": \"dr-global\",\n    \"component\": \"DateRangeSelector\",\n    \"value\": \"30d\",\n    \"presets\": \"today,7d,30d,90d,qtd,ytd,custom\",\n    \"broadcast\": \"document\"\n  }\n]\n",
+        "name": "dashboard-toolbar-global"
+      },
+      {
+        "description": "Card-local secondary picker broadcasting only on the host (no document writes).",
+        "a2ui": "[\n  {\n    \"id\": \"dr-overlay\",\n    \"component\": \"DateRangeSelector\",\n    \"broadcast\": \"self\",\n    \"presets\": \"7d,30d,90d\"\n  }\n]\n",
+        "name": "scoped-self-broadcast"
+      },
+      {
+        "description": "Form-participating selector emitting a colon-pair value on submit.",
+        "a2ui": "[\n  {\n    \"id\": \"dr-form\",\n    \"component\": \"DateRangeSelector\",\n    \"name\": \"period\",\n    \"value\": \"ytd\"\n  }\n]\n",
+        "name": "form-participating"
+      }
+    ],
+    "keywords": [
+      "date-range-selector",
+      "date-range",
+      "range-selector",
+      "period-selector",
+      "time-window",
+      "dashboard-range",
+      "period",
+      "global-range",
+      "range-bus",
+      "timeframe"
+    ],
+    "name": "DateRangeSelector",
+    "related": [
+      "DateRangePicker",
+      "Segmented",
+      "Segment",
+      "Button",
+      "Text",
+      "DashboardLayout",
+      "AdminPageHeader"
+    ],
+    "slots": {
+      "default": {
+        "description": "The composite stamps its own chip row + picker; children placed in\nthe default slot are ignored. Use prefix/suffix slots for label\ntext or auxiliary controls.\n"
+      },
+      "prefix": {
+        "description": "Optional leading content (e.g., a \"Period:\" caption). Renders\nbefore the chip row.\n"
+      },
+      "suffix": {
+        "description": "Optional trailing content (e.g., a comparison-mode toggle).\nRenders after the picker.\n"
+      }
+    },
+    "states": [
+      {
+        "description": "Default — preset chip selected, custom picker closed.",
+        "name": "idle"
+      },
+      {
+        "description": "Custom preset active; embedded picker is exposed for editing.",
+        "attribute": "value",
+        "name": "custom"
+      },
+      {
+        "description": "Embedded picker popover is open (reflected from <date-range-picker-ui>).",
+        "attribute": "picker-open",
+        "name": "picker-open"
+      },
+      {
+        "description": "Non-interactive; chips + picker dimmed; pointer-events suppressed.",
+        "attribute": "disabled",
+        "name": "disabled"
+      }
+    ],
+    "status": "experimental",
+    "synonyms": {
+      "period": [
+        "range",
+        "timeframe",
+        "reporting-period"
+      ],
+      "range": [
+        "period",
+        "timeframe",
+        "window"
+      ],
+      "selector": [
+        "chooser",
+        "picker"
+      ],
+      "tags": [
+        "DateRangeSelector",
+        "RangeSelector",
+        "PeriodSelector",
+        "TimeWindow"
+      ]
+    },
+    "tag": "date-range-selector-ui",
+    "tokens": {
+      "--date-range-selector-gap": {
+        "description": "Inline gap between prefix slot, chip row, picker, readout, and suffix slot.",
+        "default": "var(--a-space-3)"
+      },
+      "--date-range-selector-picker-trigger-py": {
+        "description": "Vertical padding on the embedded picker trigger (cascades into the inner button-ui).",
+        "default": "var(--a-space-2)"
+      },
+      "--date-range-selector-readout-fg": {
+        "description": "Resolved-range readout foreground color.",
+        "default": "var(--a-fg-muted)"
+      },
+      "--date-range-selector-readout-size": {
+        "description": "Resolved-range readout font size.",
+        "default": "var(--a-font-size-sm)"
+      }
+    },
+    "traits": [],
+    "version": 1
+  }
+}

package/dashboard/date-range-selector/date-range-selector.css

@@ -0,0 +1,84 @@
+/* ═══════════════════════════════════════════════════════════════
+   <date-range-selector-ui> — Page-level time-window chooser.
+
+   Module-tier composite that composes <segmented-ui> (preset chips),
+   <date-range-picker-ui> (custom-range editor), and <text-ui>
+   (readout). The host is an inline-flex row laying out the
+   prefix/chips/picker/readout/suffix regions in DOM order.
+
+   SPEC: docs/specs/implementation-ready/SPEC-019-date-range-selector-global.md
+   Two-block @scope pattern per docs/specs/component-token-contract.md.
+   Zero raw color values; zero raw px ≥ 3 (rem only).
+   ═══════════════════════════════════════════════════════════════ */
+
+/* ── Block 1: TOKEN DECLARATIONS ──────────────────────────────── */
+
+date-range-selector-ui {
+  --date-range-selector-gap:                var(--a-space-3);
+  --date-range-selector-readout-size:       var(--a-font-size-sm);
+  --date-range-selector-readout-fg:         var(--a-fg-muted);
+  --date-range-selector-picker-trigger-py:  var(--a-space-2);
+
+  /* Disabled visual — shared --a-opacity-disabled escalation. */
+  --date-range-selector-disabled-opacity:   var(--a-opacity-disabled, 0.5);
+}
+
+/* ── Block 2: SCOPED LAYOUT ──────────────────────────────────── */
+
+@scope (date-range-selector-ui) {
+
+  :scope {
+    display: inline-flex;
+    align-items: center;
+    gap: var(--date-range-selector-gap);
+    color: var(--date-range-selector-readout-fg);
+    font-size: var(--date-range-selector-readout-size);
+  }
+
+  /* ── Region ordering ── */
+  :scope > [slot="prefix"]            { order: 0; }
+  :scope > [data-region="chips"]      { order: 1; }
+  :scope > [data-region="picker"]     { order: 2; }
+  :scope > [data-region="readout"]    { order: 3; }
+  :scope > [slot="suffix"]            { order: 4; }
+
+  /* ── Picker visibility — only when value="custom" ──
+     Non-custom presets communicate the range through the chip label
+     itself; the picker collapses to keep the toolbar compact.        */
+  :scope:not([value="custom"]) > [data-region="picker"] {
+    display: none;
+  }
+
+  /* Cascade the picker trigger padding via the picker's L3 token. */
+  :scope > [data-region="picker"] {
+    --date-range-picker-py: var(--date-range-selector-picker-trigger-py);
+  }
+
+  /* ── Readout visibility ── */
+  /* Default readout is hidden (JS toggles `hidden` based on from/to).
+     For value="custom", reveal it so the resolved range is legible
+     next to the picker trigger. */
+  :scope:not([value="custom"]) > [data-region="readout"] {
+    display: none;
+  }
+
+  :scope > [data-region="readout"] {
+    color: var(--date-range-selector-readout-fg);
+    font-size: var(--date-range-selector-readout-size);
+    white-space: nowrap;
+  }
+
+  /* ── Disabled state ── */
+  :scope[disabled] {
+    opacity: var(--date-range-selector-disabled-opacity);
+    pointer-events: none;
+  }
+
+  /* ── Slot containers — strip any margin defaults from author content ── */
+  :scope > [slot="prefix"],
+  :scope > [slot="suffix"] {
+    display: inline-flex;
+    align-items: center;
+    gap: var(--a-space-2);
+  }
+}