@adia-ai/web-components 0.6.33 → 0.6.35

package/components/command/command.js

@@ -10,7 +10,7 @@
  */
 
 import { defineIfFree } from '../../core/register.js';
-import { UICommand } from './class.js';
+import { UICommand } from './command.class.js';
 
 defineIfFree('command-ui', UICommand);
 

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

@@ -0,0 +1,300 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://adiaui.dev/a2ui/v0_9/components/DateRangePicker.json",
+  "title": "DateRangePicker",
+  "description": "Compound form primitive for selecting a start + end date pair with optional named preset shortcuts (\"Today\", \"Last 7 days\", \"This month\", ...). Default presentation is a trigger button showing the formatted range; on activation a popover opens with two synchronized calendar panes + a preset side rail. Composes <calendar-picker-ui> twice; emits {from, to} ISO 8601 dates. Optional comparison-range mode emits a secondary range for analytics surfaces.",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "common_types.json#/$defs/ComponentCommon"
+    },
+    {
+      "$ref": "common_types.json#/$defs/CatalogComponentCommon"
+    }
+  ],
+  "properties": {
+    "required": {
+      "description": "Required for validation when inside a `<form>`.",
+      "type": "boolean",
+      "default": false
+    },
+    "compareValue": {
+      "description": "Comparison range when `[comparison]` is set. Same `{from, to}` shape as `value`.",
+      "$ref": "common_types.json#/$defs/DynamicString"
+    },
+    "comparison": {
+      "description": "Enable comparison-range mode. Renders a second preset cluster and emits a secondary range under `<name>-compare`.",
+      "type": "boolean",
+      "default": false
+    },
+    "component": {
+      "const": "DateRangePicker"
+    },
+    "disabled": {
+      "description": "Block all interaction. Trigger remains rendered but does not open the popover.",
+      "type": "boolean",
+      "default": false
+    },
+    "format": {
+      "description": "Trigger button date format. `short`: `Jan 1, 2026`; `long`: `January 1, 2026`; `iso`: `2026-01-01`.",
+      "type": "string",
+      "enum": [
+        "short",
+        "long",
+        "iso"
+      ],
+      "default": "short"
+    },
+    "max": {
+      "description": "Latest selectable ISO date (inclusive). Days after are disabled in both panes.",
+      "type": "string",
+      "default": ""
+    },
+    "min": {
+      "description": "Earliest selectable ISO date (inclusive). Days before are disabled in both panes.",
+      "type": "string",
+      "default": ""
+    },
+    "name": {
+      "description": "Form field name for form data submission. The selected range serializes as JSON `{\"from\":\"...\",\"to\":\"...\"}` under this key.",
+      "type": "string",
+      "default": ""
+    },
+    "noPresets": {
+      "description": "Hide the preset side rail.",
+      "type": "boolean",
+      "default": false
+    },
+    "open": {
+      "description": "Whether the popover is currently open.",
+      "type": "boolean",
+      "default": false
+    },
+    "placeholder": {
+      "description": "Text shown in the trigger when the value is empty.",
+      "type": "string",
+      "default": "Select range"
+    },
+    "readonly": {
+      "description": "Block edits; allow keyboard navigation for screen-reader inspection.",
+      "type": "boolean",
+      "default": false
+    },
+    "value": {
+      "description": "Selected range as `{from, to}` ISO 8601 dates. Null when empty. Emitted on commit.",
+      "$ref": "common_types.json#/$defs/DynamicString"
+    }
+  },
+  "required": [
+    "component"
+  ],
+  "unevaluatedProperties": false,
+  "x-adiaui": {
+    "anti_patterns": [
+      {
+        "fix": "{\"component\": \"DateRangePicker\", \"value\": {\"from\": \"2026-01-01\", \"to\": \"2026-01-31\"}}\n",
+        "why": "`value` is a string, not an object. The contract is `{from, to}` ISO 8601 dates.\n",
+        "wrong": "{\"component\": \"DateRangePicker\", \"value\": \"2026-01-01 to 2026-01-31\"}\n"
+      },
+      {
+        "fix": "{\"component\": \"DateRangePicker\", \"value\": {\"from\": \"2026-01-01\", \"to\": \"2026-12-31\"}}\n",
+        "why": "Reversed range — `to < from`. This fires `invalid` and never commits.\n",
+        "wrong": "{\"component\": \"DateRangePicker\", \"value\": {\"from\": \"2026-12-31\", \"to\": \"2026-01-01\"}}\n"
+      },
+      {
+        "fix": "Use <date-range-picker-ui>.\n",
+        "why": "This is the pattern the primitive replaces. Reinvents linked-pane behavior,\nmisses preset rail, has no a11y range-announcement.\n",
+        "wrong": "Two adjacent <calendar-picker-ui> instances + JS synchronization.\n"
+      }
+    ],
+    "category": "input",
+    "composes": [
+      "calendar-grid-ui",
+      "button-ui",
+      "popover-ui",
+      "text-ui",
+      "divider-ui"
+    ],
+    "events": {
+      "change": {
+        "description": "Fired when the range commits (both `from` AND `to` selected, OR a preset clicked).",
+        "detail": {
+          "compareValue": "object",
+          "presetLabel": "string",
+          "value": "object"
+        }
+      },
+      "close": {
+        "description": "Popover closed (without commit, or after commit).",
+        "detail": {
+          "reason": "string"
+        }
+      },
+      "input": {
+        "description": "Fired during selection — e.g. user clicked `from` but has not yet picked `to`.",
+        "detail": {
+          "value": "object"
+        }
+      },
+      "invalid": {
+        "description": "A constraint failed (out of range, end < start).",
+        "detail": {
+          "reason": "string",
+          "value": "object"
+        }
+      },
+      "open": {
+        "description": "Popover opened (user clicked the trigger or pressed Enter / Space).",
+        "detail": {
+          "trigger": "string"
+        }
+      }
+    },
+    "examples": [
+      {
+        "description": "Form-field-wrapped picker with default presets.",
+        "a2ui": "[\n  {\n    \"id\": \"field\",\n    \"component\": \"Field\",\n    \"label\": \"Report period\",\n    \"children\": [\"dr\"]\n  },\n  {\n    \"id\": \"dr\",\n    \"component\": \"DateRangePicker\",\n    \"name\": \"report-period\",\n    \"min\": \"2026-01-01\",\n    \"max\": \"2026-12-31\"\n  }\n]\n",
+        "name": "canonical"
+      },
+      {
+        "description": "Analytics-surface picker with comparison range enabled.",
+        "a2ui": "[\n  {\n    \"id\": \"dr\",\n    \"component\": \"DateRangePicker\",\n    \"name\": \"period\",\n    \"comparison\": true,\n    \"value\": {\"from\": \"2026-05-01\", \"to\": \"2026-05-31\"},\n    \"compareValue\": {\"from\": \"2026-04-01\", \"to\": \"2026-04-30\"}\n  }\n]\n",
+        "name": "comparison"
+      },
+      {
+        "description": "Custom-only picker with the preset rail hidden.",
+        "a2ui": "[\n  {\n    \"id\": \"dr\",\n    \"component\": \"DateRangePicker\",\n    \"name\": \"period\",\n    \"noPresets\": true\n  }\n]\n",
+        "name": "no-presets"
+      }
+    ],
+    "keywords": [
+      "daterangepicker",
+      "date-range-picker",
+      "date-range",
+      "range",
+      "daterange",
+      "period",
+      "reporting-period"
+    ],
+    "name": "UIDateRangePicker",
+    "related": [
+      "calendar-picker",
+      "popover",
+      "field",
+      "button"
+    ],
+    "slots": {
+      "footer": {
+        "description": "Optional footer area below the calendars (e.g., \"Apply\" / \"Cancel\" buttons for explicit-commit flows)."
+      },
+      "presets": {
+        "description": "Custom preset content replacing the default preset rail."
+      },
+      "trigger": {
+        "description": "Custom trigger replacement. When omitted, a default `<button-ui>` is stamped."
+      }
+    },
+    "states": [
+      {
+        "description": "Closed, no pending selection.",
+        "name": "idle"
+      },
+      {
+        "description": "Popover open, user has not yet clicked a start date.",
+        "attribute": "open",
+        "name": "open-pending-from"
+      },
+      {
+        "description": "Start clicked, awaiting end click; hover preview active.",
+        "attribute": "open",
+        "name": "open-pending-to"
+      },
+      {
+        "description": "Both ends clicked, awaiting Apply (only in explicit-commit mode with `footer` slot).",
+        "attribute": "open",
+        "name": "open-committed"
+      },
+      {
+        "description": "Non-interactive; dimmed.",
+        "attribute": "disabled",
+        "name": "disabled"
+      },
+      {
+        "description": "Read-only; trigger keyboard-focusable but popover does not open.",
+        "attribute": "readonly",
+        "name": "readonly"
+      }
+    ],
+    "status": "experimental",
+    "synonyms": {
+      "period": [
+        "date-range",
+        "range",
+        "reporting-period"
+      ],
+      "range": [
+        "date-range",
+        "period",
+        "report-period"
+      ],
+      "tags": [
+        "DateRangePicker",
+        "DateRange",
+        "DateRangeInput"
+      ]
+    },
+    "tag": "date-range-picker-ui",
+    "tokens": {
+      "--date-range-picker-bg": {
+        "description": "Host background.",
+        "default": "var(--a-bg)"
+      },
+      "--date-range-picker-popover-bg": {
+        "description": "Popover background.",
+        "default": "var(--a-bg-subtle)"
+      },
+      "--date-range-picker-popover-border": {
+        "description": "Popover border color.",
+        "default": "var(--a-border-subtle)"
+      },
+      "--date-range-picker-popover-radius": {
+        "description": "Popover border radius.",
+        "default": "var(--a-radius-lg)"
+      },
+      "--date-range-picker-popover-shadow": {
+        "description": "Popover box shadow.",
+        "default": "var(--a-shadow-lg)"
+      },
+      "--date-range-picker-preset-bg": {
+        "description": "Preset row background (idle).",
+        "default": "transparent"
+      },
+      "--date-range-picker-preset-bg-hover": {
+        "description": "Preset row background on hover.",
+        "default": "var(--a-bg-hover)"
+      },
+      "--date-range-picker-preview-bg": {
+        "description": "In-range preview background (between from and pending to).",
+        "default": "var(--a-accent-muted)"
+      },
+      "--date-range-picker-px": {
+        "description": "Horizontal popover padding.",
+        "default": "var(--a-space-3)"
+      },
+      "--date-range-picker-py": {
+        "description": "Vertical popover padding.",
+        "default": "var(--a-space-2)"
+      },
+      "--date-range-picker-selected-bg": {
+        "description": "Selected day-cell background (cascaded into the inner calendar via --calendar-picker-day-bg-selected).",
+        "default": "var(--a-accent)"
+      },
+      "--date-range-picker-selected-fg": {
+        "description": "Selected day-cell foreground.",
+        "default": "var(--a-accent-fg)"
+      }
+    },
+    "traits": [],
+    "version": 1
+  }
+}