@ds-mo/ui 14.35.0 → 14.36.0

package/dist/mcp-data/registry/calendar.json

@@ -0,0 +1,273 @@
+{
+  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
+  "name": "calendar",
+  "title": "Calendar",
+  "description": "Month calendar grid for choosing one calendar date or an inclusive date range, reused by form date fields and filter range selection.",
+  "type": "registry:ui",
+  "meta": {
+    "library": "@ds-mo/ui",
+    "distribution": "npm",
+    "storybook": "https://zainadeel.github.io/compomo/?path=/story/calendar",
+    "source": "src/wc/components/Calendar/Calendar.tsx",
+    "intentStatus": "complete",
+    "intent": {
+      "audience": "general",
+      "status": "experimental",
+      "summary": "Month calendar grid for choosing one calendar date or an inclusive date range, reused by form date fields and filter range selection.",
+      "useWhen": [
+        "A user picks one calendar day from a month grid.",
+        "A user builds an inclusive start and end date by choosing two days.",
+        "A date field or filter needs the shared month navigation, weekday headings, and selected-day treatment."
+      ],
+      "avoidWhen": [
+        "The user types a date without opening a calendar; the owning field keeps that editable value.",
+        "The user chooses a relative preset such as last 7 days rather than fixed calendar days.",
+        "The popup also has to host filter categories, search, or apply actions; that surface stays with FilterMenu."
+      ],
+      "alternatives": [
+        {
+          "when": "The date is a form field that can be typed or picked.",
+          "component": "component:ds-input-date",
+          "reason": "InputDate owns the editable field, form association, and the calendar popup."
+        },
+        {
+          "when": "The value is a clock time rather than a calendar date.",
+          "component": "component:ds-time-picker",
+          "reason": "TimePicker owns bounded hour, minute, and AM/PM lists with the same 32px tile geometry."
+        },
+        {
+          "when": "The user chooses relative presets or mixed filter families from one trigger.",
+          "component": "component:ds-filter-menu",
+          "reason": "FilterMenu owns relative date presets and hosts this calendar only for fixed ranges."
+        }
+      ],
+      "commonlyComposedWith": [
+        "component:ds-input-date",
+        "component:ds-filter-menu",
+        "component:ds-button-unfilled",
+        "component:ds-text"
+      ],
+      "accessibility": [
+        "The month grid is labelled with the visible month and year. Days are grid cells with an accessible date name.",
+        "The grid keeps one tab stop. Arrow keys move by day or week, Home and End move within the week, and Page Up or Page Down change month.",
+        "In range mode, the first chosen day applies immediately as a one-day range. Hovering or focusing another day previews the inclusive span without changing the value until the second activation.",
+        "Month navigation buttons are named Previous month and Next month. Inactive calendars disable day and month controls."
+      ],
+      "states": [
+        "Single selection paints the current value with the shared interaction-fill selected wash and primary text. A committed range paints inclusive days with the faint brand fill and both edges boldly.",
+        "Today uses emphasized primary text without becoming selected on its own.",
+        "Days outside the visible month remain in the six-week grid and use tertiary text. Optional min and max dates disable days outside that inclusive bound.",
+        "After the first range day is chosen, that day keeps the shared pressed overlay. Hovering or focusing toward another day paints the inclusive span with the shared hover overlay on top of the previous committed range, which stays visible until the replacement is completed. Completing the end day orders the two dates inclusively and replaces those overlays with brand fill."
+      ],
+      "responsiveBehavior": [
+        "The grid fills the width supplied by its owner. Seven equal day columns and the shared 4px gaps are owned here; the owner supplies the popup or pane width."
+      ],
+      "frameworkCaveats": {
+        "customElements": [
+          "Listen for dsChange. Single mode emits YYYY-MM-DD. Range mode emits range:start/end using the shared date-filter string."
+        ],
+        "react": [
+          "Use DsCalendar, bind value, and handle onDsChange."
+        ]
+      },
+      "references": [
+        {
+          "label": "Storybook examples",
+          "path": "src/wc/components/Calendar/Calendar.stories.ts"
+        }
+      ]
+    },
+    "api": {
+      "props": {
+        "autoFocus": {
+          "type": "boolean",
+          "resolvedType": "boolean",
+          "attribute": "auto-focus",
+          "default": "false",
+          "required": false,
+          "mutable": false,
+          "description": "Move keyboard focus into the grid after the calendar is rendered."
+        },
+        "isInactive": {
+          "type": "boolean",
+          "resolvedType": "boolean",
+          "attribute": "is-inactive",
+          "default": "false",
+          "required": false,
+          "mutable": false
+        },
+        "max": {
+          "type": "string | undefined",
+          "resolvedType": "string | undefined",
+          "attribute": "max",
+          "required": false,
+          "mutable": false
+        },
+        "min": {
+          "type": "string | undefined",
+          "resolvedType": "string | undefined",
+          "attribute": "min",
+          "required": false,
+          "mutable": false
+        },
+        "selectionMode": {
+          "type": "CalendarSelectionMode",
+          "resolvedType": "\"range\" | \"single\"",
+          "attribute": "selection-mode",
+          "default": "'single'",
+          "required": false,
+          "mutable": false,
+          "description": "Single date emits YYYY-MM-DD. Range emits the shared `range:start/end` string."
+        },
+        "value": {
+          "type": "string",
+          "resolvedType": "string",
+          "attribute": "value",
+          "default": "''",
+          "required": false,
+          "mutable": false
+        }
+      },
+      "events": [
+        {
+          "name": "dsChange",
+          "detail": "string",
+          "bubbles": true,
+          "cancelable": true,
+          "composed": true
+        }
+      ],
+      "methods": [
+        {
+          "name": "setFocus",
+          "signature": "setFocus() => Promise<void>"
+        }
+      ],
+      "slots": []
+    },
+    "props": {
+      "autoFocus": {
+        "type": "boolean",
+        "resolvedType": "boolean",
+        "attribute": "auto-focus",
+        "default": "false",
+        "required": false,
+        "mutable": false,
+        "description": "Move keyboard focus into the grid after the calendar is rendered."
+      },
+      "isInactive": {
+        "type": "boolean",
+        "resolvedType": "boolean",
+        "attribute": "is-inactive",
+        "default": "false",
+        "required": false,
+        "mutable": false
+      },
+      "max": {
+        "type": "string | undefined",
+        "resolvedType": "string | undefined",
+        "attribute": "max",
+        "required": false,
+        "mutable": false
+      },
+      "min": {
+        "type": "string | undefined",
+        "resolvedType": "string | undefined",
+        "attribute": "min",
+        "required": false,
+        "mutable": false
+      },
+      "selectionMode": {
+        "type": "CalendarSelectionMode",
+        "resolvedType": "\"range\" | \"single\"",
+        "attribute": "selection-mode",
+        "default": "'single'",
+        "required": false,
+        "mutable": false,
+        "description": "Single date emits YYYY-MM-DD. Range emits the shared `range:start/end` string."
+      },
+      "value": {
+        "type": "string",
+        "resolvedType": "string",
+        "attribute": "value",
+        "default": "''",
+        "required": false,
+        "mutable": false
+      }
+    },
+    "events": [
+      {
+        "name": "dsChange",
+        "detail": "string",
+        "bubbles": true,
+        "cancelable": true,
+        "composed": true
+      }
+    ],
+    "methods": [
+      {
+        "name": "setFocus",
+        "signature": "setFocus() => Promise<void>"
+      }
+    ],
+    "slots": [],
+    "exports": {
+      "customElement": "ds-calendar",
+      "react": "DsCalendar",
+      "vue": "DsCalendar",
+      "angular": "DsCalendar"
+    },
+    "consumption": {
+      "install": "npm install @ds-mo/ui @ds-mo/tokens @ds-mo/icons",
+      "cssSetup": "import '@ds-mo/tokens';\nimport '@ds-mo/tokens/reset';\nimport '@ds-mo/tokens/globals';",
+      "customElements": {
+        "import": "import '@ds-mo/ui/dist/components/ds-calendar.js';",
+        "example": "<ds-calendar></ds-calendar>"
+      },
+      "react": {
+        "import": "import { DsCalendar } from '@ds-mo/ui/react';",
+        "example": "<DsCalendar />"
+      },
+      "vue": {
+        "import": "import { DsCalendar } from '@ds-mo/ui/vue';",
+        "example": "<DsCalendar />"
+      },
+      "angular": {
+        "import": "import { DsCalendar } from '@ds-mo/ui/angular/ds-calendar';",
+        "example": "<ds-calendar></ds-calendar>"
+      },
+      "peerDependencies": {
+        "required": [
+          "@ds-mo/tokens ^6.5.1",
+          "@ds-mo/icons ^7.0.0"
+        ],
+        "frameworks": "Custom Elements; React 18/19 wrappers; Vue 3 wrappers; Angular 19-22 standalone adapters."
+      }
+    }
+  },
+  "dependencies": [
+    "@ds-mo/ui",
+    "@ds-mo/tokens"
+  ],
+  "registryDependencies": [
+    "button-unfilled",
+    "text"
+  ],
+  "files": [
+    {
+      "path": "src/wc/components/Calendar/Calendar.css",
+      "content": "@import '../../utils/radius.css';\n@import '../../utils/control-density.css';\n@import '../../utils/focus-ring.css';\n@import '../../utils/interaction-fill.css';\n@import '../../utils/forced-colors.css';\n\n:host {\n  display: flex;\n  min-height: 0;\n  flex-direction: column;\n}\n\n.calendar {\n  display: flex;\n  min-height: 0;\n  flex-direction: column;\n  min-width: calc(\n    (var(--dimension-size-400) * 7) + (var(--dimension-space-050) * 6) +\n      (var(--dimension-space-100) * 2)\n  );\n  padding: var(--ds-calendar-padding, var(--dimension-space-100));\n}\n\n.calendar-heading {\n  display: grid;\n  grid-template-columns: var(--dimension-size-400) minmax(0, 1fr) var(--dimension-size-400);\n  align-items: center;\n  text-align: center;\n}\n\n.calendar-nav--previous {\n  justify-self: start;\n}\n\n.calendar-nav--next {\n  justify-self: end;\n}\n\n.calendar-weekdays,\n.calendar-grid__row {\n  display: grid;\n  grid-template-columns: repeat(7, minmax(0, 1fr));\n  column-gap: var(--dimension-space-050);\n}\n\n.calendar-grid {\n  display: flex;\n  flex-direction: column;\n  row-gap: var(--dimension-space-050);\n}\n\n.calendar-weekdays {\n  align-items: center;\n  min-height: var(--dimension-size-400);\n  margin-block-start: var(--dimension-space-050);\n  color: var(--color-foreground-secondary);\n  text-align: center;\n}\n\n.calendar-day {\n  appearance: none;\n  position: relative;\n  display: flex;\n  align-items: center;\n  justify-content: center;\n  min-width: 0;\n  width: 100%;\n  height: var(--dimension-size-400);\n  padding: 0;\n  border: 0;\n  border-radius: var(--dimension-radius-025);\n  background: transparent;\n  color: var(--color-foreground-primary);\n  cursor: default;\n}\n\n.calendar-day:disabled {\n  cursor: not-allowed;\n}\n\n.calendar-day--outside {\n  color: var(--color-foreground-tertiary);\n}\n\n.calendar-day--in-range {\n  background: var(--color-background-faint-brand);\n  color: var(--color-foreground-primary);\n}\n\n/* In-progress span uses the shared hover overlay; the first day keeps pressed via --surface-open. */\n.calendar-day.ds-interaction-fill.calendar-day--range-preview:not(:disabled)::after {\n  background: var(--ds-interaction-hover);\n}\n\n.calendar-day.ds-interaction-fill.calendar-day--range-preview:active:not(:disabled)::after {\n  background: var(--ds-interaction-pressed);\n}\n\n.calendar-day--today {\n  color: var(--color-foreground-primary);\n}\n\n.calendar-day--range-edge {\n  background: var(--color-background-bold-brand);\n  color: var(--color-foreground-on-bold-background-primary);\n}\n\n@media (forced-colors: active) {\n  .calendar-day--range-edge {\n    outline: var(--dimension-stroke-width-012) solid var(--ds-forced-color-content);\n  }\n}\n",
+      "type": "registry:ui"
+    },
+    {
+      "path": "src/wc/components/Calendar/Calendar.tsx",
+      "content": "import {\n  Component,\n  Element,\n  Event,\n  EventEmitter,\n  Method,\n  Prop,\n  State,\n  Watch,\n  h,\n  Host,\n} from '@stencil/core';\nimport {\n  dateFilterRangeValue,\n  isIsoCalendarDate,\n  parseDateFilterValue,\n  shiftIsoCalendarDate,\n} from '../../utils';\nimport {\n  CALENDAR_WEEKDAYS,\n  calendarDays,\n  calendarMonth,\n  calendarMonthLabel,\n  calendarPaintedRange,\n  calendarToday,\n  shiftCalendarMonth,\n  type CalendarDateRange,\n} from './calendar-grid';\n\nexport type CalendarSelectionMode = 'single' | 'range';\n\n@Component({\n  tag: 'ds-calendar',\n  styleUrl: 'Calendar.css',\n  scoped: true,\n})\nexport class Calendar {\n  @Element() el!: HTMLElement;\n\n  /** Single date emits YYYY-MM-DD. Range emits the shared `range:start/end` string. */\n  @Prop() selectionMode: CalendarSelectionMode = 'single';\n  @Prop() value: string = '';\n  @Prop() min: string | undefined;\n  @Prop() max: string | undefined;\n  @Prop() isInactive: boolean = false;\n  /** Move keyboard focus into the grid after the calendar is rendered. */\n  @Prop() autoFocus: boolean = false;\n\n  @Event() dsChange!: EventEmitter<string>;\n\n  @State() private month = calendarMonth(calendarToday());\n  @State() private pendingStart = '';\n  @State() private previewEnd = '';\n  @State() private heldRange: CalendarDateRange | null = null;\n\n  componentWillLoad() {\n    this.month = calendarMonth(this.anchorDate());\n  }\n\n  componentDidLoad() {\n    if (this.autoFocus) void this.setFocus();\n  }\n\n  @Watch('value')\n  onValueChange() {\n    this.month = calendarMonth(this.anchorDate());\n  }\n\n  @Method()\n  async setFocus() {\n    this.el.querySelector<HTMLElement>('.calendar-day[tabindex=\"0\"]')?.focus();\n  }\n\n  private anchorDate(): string {\n    if (this.selectionMode === 'range') {\n      const parsed = parseDateFilterValue(this.value);\n      if (parsed?.kind === 'range') return parsed.start;\n      return calendarToday();\n    }\n    return isIsoCalendarDate(this.value) ? this.value : calendarToday();\n  }\n\n  private isDisabled(day: string): boolean {\n    if (this.isInactive) return true;\n    if (this.min && isIsoCalendarDate(this.min) && day < this.min) return true;\n    if (this.max && isIsoCalendarDate(this.max) && day > this.max) return true;\n    return false;\n  }\n\n  private moveMonth = (offset: number) => {\n    this.previewEnd = '';\n    this.month = shiftCalendarMonth(this.month, offset);\n  };\n\n  private selectDate = (day: string) => {\n    if (this.isDisabled(day)) return;\n    this.previewEnd = '';\n    if (this.selectionMode === 'single') {\n      this.pendingStart = '';\n      this.heldRange = null;\n      this.dsChange.emit(day);\n      return;\n    }\n    const pending = this.pendingStart;\n    if (pending) {\n      this.pendingStart = '';\n      this.heldRange = null;\n      this.dsChange.emit(dateFilterRangeValue(pending, day));\n      return;\n    }\n    const current = parseDateFilterValue(this.value);\n    this.heldRange = current?.kind === 'range' ? { start: current.start, end: current.end } : null;\n    this.pendingStart = day;\n    this.dsChange.emit(dateFilterRangeValue(day, day));\n  };\n\n  private previewRange = (day: string) => {\n    if (!this.pendingStart || this.previewEnd === day) return;\n    this.previewEnd = day;\n  };\n\n  private clearPreview = () => {\n    if (!this.previewEnd) return;\n    this.previewEnd = '';\n  };\n\n  private focusDate(day: string) {\n    this.previewRange(day);\n    const targetMonth = calendarMonth(day);\n    if (this.month !== targetMonth) this.month = targetMonth;\n    requestAnimationFrame(() => {\n      this.el.querySelector<HTMLElement>(`[data-date-option=\"${day}\"]`)?.focus();\n    });\n  }\n\n  private handleDayKeyDown = (event: KeyboardEvent, day: string) => {\n    let offset: number | null = null;\n    if (event.key === 'ArrowLeft') offset = -1;\n    else if (event.key === 'ArrowRight') offset = 1;\n    else if (event.key === 'ArrowUp') offset = -7;\n    else if (event.key === 'ArrowDown') offset = 7;\n    else if (event.key === 'Home') {\n      offset = -new Date(`${day}T00:00:00Z`).getUTCDay();\n    } else if (event.key === 'End') {\n      offset = 6 - new Date(`${day}T00:00:00Z`).getUTCDay();\n    } else if (event.key === 'PageUp' || event.key === 'PageDown') {\n      const month = shiftCalendarMonth(calendarMonth(day), event.key === 'PageUp' ? -1 : 1);\n      const candidate = `${month}-${day.slice(8, 10)}`;\n      event.preventDefault();\n      this.focusDate(isIsoCalendarDate(candidate) ? candidate : `${month}-01`);\n      return;\n    }\n    if (offset === null) return;\n    event.preventDefault();\n    this.focusDate(shiftIsoCalendarDate(day, offset));\n  };\n\n  render() {\n    const liveRange = this.selectionMode === 'range' ? parseDateFilterValue(this.value) : null;\n    const liveRangeValue = liveRange?.kind === 'range' ? liveRange : null;\n    const rangeValue = calendarPaintedRange(this.pendingStart, this.heldRange, liveRangeValue);\n    const days = calendarDays(this.month);\n    const weeks = Array.from({ length: 6 }, (_, index) => days.slice(index * 7, index * 7 + 7));\n    const today = calendarToday();\n    const previewStart =\n      this.pendingStart && this.previewEnd ? [this.pendingStart, this.previewEnd].sort()[0] : null;\n    const previewFinish =\n      this.pendingStart && this.previewEnd ? [this.pendingStart, this.previewEnd].sort()[1] : null;\n    const selectedSingle =\n      this.selectionMode === 'single' && isIsoCalendarDate(this.value) ? this.value : '';\n    const preferredFocus =\n      this.pendingStart ||\n      selectedSingle ||\n      rangeValue?.end ||\n      (this.month === today.slice(0, 7) ? today : '');\n    const focusDate = days.some(day => day.value === preferredFocus)\n      ? preferredFocus\n      : (days.find(day => day.inMonth)?.value ?? days[0]?.value);\n\n    return (\n      <Host>\n        <div class=\"calendar\">\n          <div class=\"calendar-heading ds-control--md\">\n            <ds-button-unfilled\n              class=\"calendar-nav calendar-nav--previous\"\n              variant=\"icon\"\n              icon=\"ChevronLeft\"\n              size=\"md\"\n              hasBorder={false}\n              isInactive={this.isInactive}\n              ariaLabel=\"Previous month\"\n              onDsClick={() => this.moveMonth(-1)}\n            />\n            <ds-text as=\"span\" variant=\"text-body-medium\" emphasis color=\"primary\">\n              {calendarMonthLabel(this.month)}\n            </ds-text>\n            <ds-button-unfilled\n              class=\"calendar-nav calendar-nav--next\"\n              variant=\"icon\"\n              icon=\"ChevronRight\"\n              size=\"md\"\n              hasBorder={false}\n              isInactive={this.isInactive}\n              ariaLabel=\"Next month\"\n              onDsClick={() => this.moveMonth(1)}\n            />\n          </div>\n          <div class=\"calendar-weekdays\" aria-hidden=\"true\">\n            {CALENDAR_WEEKDAYS.map(day => (\n              <ds-text as=\"span\" variant=\"text-body-small\" color=\"secondary\">\n                {day}\n              </ds-text>\n            ))}\n          </div>\n          <div\n            class=\"calendar-grid\"\n            role=\"grid\"\n            aria-label={calendarMonthLabel(this.month)}\n            onMouseLeave={this.clearPreview}\n          >\n            {weeks.map((week, weekIndex) => (\n              <div class=\"calendar-grid__row\" role=\"row\" key={`week-${weekIndex}`}>\n                {week.map(day => {\n                  const selectedInRange = Boolean(\n                    liveRangeValue &&\n                    day.value >= liveRangeValue.start &&\n                    day.value <= liveRangeValue.end\n                  );\n                  const paintedInRange = Boolean(\n                    rangeValue && day.value >= rangeValue.start && day.value <= rangeValue.end\n                  );\n                  const pendingStartDay =\n                    this.selectionMode === 'range' &&\n                    Boolean(this.pendingStart) &&\n                    day.value === this.pendingStart;\n                  const previewInRange = Boolean(\n                    this.pendingStart &&\n                    previewStart &&\n                    previewFinish &&\n                    day.value >= previewStart &&\n                    day.value <= previewFinish &&\n                    day.value !== this.pendingStart\n                  );\n                  const inRange = this.selectionMode === 'range' && paintedInRange;\n                  const rangeEdge = Boolean(\n                    this.selectionMode === 'range' &&\n                    rangeValue &&\n                    (day.value === rangeValue.start || day.value === rangeValue.end)\n                  );\n                  const selected = this.selectionMode === 'single' && day.value === selectedSingle;\n                  const textColor = rangeEdge\n                    ? 'on-bold'\n                    : selected ||\n                        inRange ||\n                        pendingStartDay ||\n                        previewInRange ||\n                        day.value === today\n                      ? 'primary'\n                      : day.inMonth\n                        ? 'secondary'\n                        : 'tertiary';\n                  return (\n                    <button\n                      type=\"button\"\n                      role=\"gridcell\"\n                      data-date-option={day.value}\n                      class={{\n                        'calendar-day': true,\n                        'calendar-day--outside': !day.inMonth,\n                        'calendar-day--today': day.value === today,\n                        'calendar-day--in-range': inRange,\n                        'calendar-day--range-preview': previewInRange,\n                        'calendar-day--range-edge': rangeEdge,\n                        'calendar-day--selected': selected,\n                        'ds-focus-ring-inset': true,\n                        'ds-interaction-fill': true,\n                        'ds-interaction-fill--on-bold': rangeEdge,\n                        'ds-interaction-fill--surface-open':\n                          pendingStartDay && !this.isDisabled(day.value),\n                        'ds-interaction-fill--selected': selected && !this.isDisabled(day.value),\n                      }}\n                      disabled={this.isDisabled(day.value)}\n                      aria-label={day.label}\n                      aria-selected={selectedInRange || selected ? 'true' : 'false'}\n                      tabIndex={day.value === focusDate ? 0 : -1}\n                      onMouseEnter={() => this.previewRange(day.value)}\n                      onFocus={() => this.previewRange(day.value)}\n                      onClick={() => this.selectDate(day.value)}\n                      onKeyDown={event => this.handleDayKeyDown(event, day.value)}\n                    >\n                      <ds-text\n                        class=\"ds-interaction-fill__content\"\n                        as=\"span\"\n                        variant=\"text-body-medium\"\n                        color={textColor}\n                        emphasis={day.value === today}\n                      >\n                        {day.day}\n                      </ds-text>\n                    </button>\n                  );\n                })}\n              </div>\n            ))}\n          </div>\n        </div>\n      </Host>\n    );\n  }\n}\n",
+      "type": "registry:ui"
+    },
+    {
+      "path": "src/wc/components/Calendar/calendar-grid.ts",
+      "content": "import { isIsoCalendarDate, shiftIsoCalendarDate } from '../../utils';\n\nexport interface CalendarDateRange {\n  start: string;\n  end: string;\n}\n\nexport interface CalendarDay {\n  value: string;\n  day: number;\n  inMonth: boolean;\n  label: string;\n}\n\nexport const CALENDAR_WEEKDAYS = ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'];\n\nconst MONTH_FORMATTER = new Intl.DateTimeFormat('en-US', {\n  month: 'long',\n  year: 'numeric',\n  timeZone: 'UTC',\n});\nconst DATE_FORMATTER = new Intl.DateTimeFormat('en-US', {\n  weekday: 'long',\n  month: 'long',\n  day: 'numeric',\n  year: 'numeric',\n  timeZone: 'UTC',\n});\n\nexport function calendarToday(): string {\n  const today = new Date();\n  const year = today.getFullYear();\n  const month = String(today.getMonth() + 1).padStart(2, '0');\n  const day = String(today.getDate()).padStart(2, '0');\n  return `${year}-${month}-${day}`;\n}\n\nexport function calendarMonth(value: string): string {\n  return isIsoCalendarDate(value) ? value.slice(0, 7) : calendarToday().slice(0, 7);\n}\n\nexport function shiftCalendarMonth(value: string, offset: number): string {\n  const [year, month] = value.split('-').map(Number);\n  const date = new Date(Date.UTC(year, month - 1 + offset, 1));\n  return `${date.getUTCFullYear()}-${String(date.getUTCMonth() + 1).padStart(2, '0')}`;\n}\n\nexport function calendarMonthLabel(value: string): string {\n  const [year, month] = value.split('-').map(Number);\n  return MONTH_FORMATTER.format(new Date(Date.UTC(year, month - 1, 1)));\n}\n\nexport function calendarDays(value: string): CalendarDay[] {\n  const [year, month] = value.split('-').map(Number);\n  const firstOfMonth = `${year}-${String(month).padStart(2, '0')}-01`;\n  const firstWeekday = new Date(`${firstOfMonth}T00:00:00Z`).getUTCDay();\n  const gridStart = shiftIsoCalendarDate(firstOfMonth, -firstWeekday);\n  return Array.from({ length: 42 }, (_, index) => {\n    const dateValue = shiftIsoCalendarDate(gridStart, index);\n    const date = new Date(`${dateValue}T00:00:00Z`);\n    return {\n      value: dateValue,\n      day: date.getUTCDate(),\n      inMonth: dateValue.startsWith(`${value}-`),\n      label: DATE_FORMATTER.format(date),\n    };\n  });\n}\n\n/** Keep the previous committed range visible while a replacement range is being chosen. */\nexport function calendarPaintedRange(\n  pendingStart: string,\n  heldRange: CalendarDateRange | null,\n  valueRange: CalendarDateRange | null\n): CalendarDateRange | null {\n  return pendingStart ? heldRange : valueRange;\n}\n",
+      "type": "registry:ui"
+    }
+  ]
+}

package/dist/mcp-data/registry/card-navigation.json

@@ -51,10 +51,12 @@
         "The native link owns hover, pressed, and focus-visible states across the complete card in navigation-only mode.",
         "In content mode, the native link owns those interaction states only across the header while the body remains application-owned.",
         "An empty or unsafe href renders non-interactive card chrome without a false keyboard target.",
+        "Copy is always stacked, so a missing description keeps the heading at the start of the column instead of centering it in the header.",
         "The application owns destination loading, authorization, not-found, and recovery states after navigation."
       ],
       "responsiveBehavior": [
         "Choose sm, md, or lg from the parent layout; the surface never exceeds its parent width.",
+        "The heading stays at the start of the stacked copy column whether or not supporting copy is present, so mixed destination lists keep titles aligned. The chevron stays vertically centered in the header.",
         "Supporting copy wraps while the chevron remains visible at the trailing edge.",
         "The parent owns wrapping, columns, stacking, and breakpoint changes between cards."
       ],
@@ -243,12 +245,12 @@
   "files": [
     {
       "path": "src/wc/components/CardNavigation/CardNavigation.css",
-      "content": "@import '../../utils/radius.css';\n@import '../../utils/chrome-header.css';\n@import '../../utils/interaction-fill.css';\n@import '../../utils/focus-ring.css';\n@import '../../utils/forced-colors.css';\n\n:host {\n  position: relative;\n  display: flex;\n  flex-direction: column;\n  box-sizing: border-box;\n  width: var(--_card-navigation-width);\n  max-width: 100%;\n  overflow: hidden;\n  border: none;\n  border-radius: var(--ds-radius-card);\n  background-color: var(--color-background-primary);\n  box-shadow: var(--effect-shadow-elevated-sm);\n}\n\n:host(.card-navigation--content) {\n  min-height: var(--_card-navigation-min-height);\n}\n\n:host::after {\n  content: '';\n  position: absolute;\n  inset: 0;\n  z-index: 4;\n  border-radius: inherit;\n  box-shadow: var(--effect-highlight-elevated-sm);\n  pointer-events: none;\n}\n\n.card-navigation__target {\n  color: inherit;\n  text-decoration: none;\n  cursor: pointer;\n}\n\n.card-navigation__header {\n  flex: 0 0 auto;\n  border-radius: inherit;\n}\n\n:host(.card-navigation--content) .card-navigation__header {\n  border-radius: var(--ds-radius-card) var(--ds-radius-card) 0 0;\n  --ds-interaction-divider-width: var(--dimension-stroke-width-012);\n  --ds-interaction-divider-color: var(--color-border-tertiary);\n}\n\n.card-navigation__copy {\n  min-height: var(--dimension-size-400);\n  justify-content: center;\n}\n\nds-text.card-navigation__title,\nds-text.card-navigation__description {\n  overflow-wrap: anywhere;\n}\n\n.card-navigation__chevron {\n  justify-content: center;\n  width: var(--dimension-size-400);\n  color: var(--color-foreground-secondary);\n}\n\n.card-navigation__body {\n  display: flex;\n  flex: 1 1 auto;\n  flex-direction: column;\n  min-height: 0;\n  box-sizing: border-box;\n  background-color: var(--color-background-primary);\n  border-radius: 0 0 var(--ds-radius-card) var(--ds-radius-card);\n}\n\n@media (forced-colors: active) {\n  :host {\n    box-shadow: none;\n    outline: var(--dimension-stroke-width-012) solid var(--ds-forced-color-content);\n    outline-offset: calc(-1 * var(--dimension-stroke-width-012));\n  }\n\n  :host::after {\n    box-shadow: none;\n  }\n}\n",
+      "content": "@import '../../utils/radius.css';\n@import '../../utils/chrome-header.css';\n@import '../../utils/interaction-fill.css';\n@import '../../utils/focus-ring.css';\n@import '../../utils/forced-colors.css';\n\n:host {\n  position: relative;\n  display: flex;\n  flex-direction: column;\n  box-sizing: border-box;\n  width: var(--_card-navigation-width);\n  max-width: 100%;\n  overflow: hidden;\n  border: none;\n  border-radius: var(--ds-radius-card);\n  background-color: var(--color-background-primary);\n  box-shadow: var(--effect-shadow-elevated-sm);\n}\n\n:host(.card-navigation--content) {\n  min-height: var(--_card-navigation-min-height);\n}\n\n:host::after {\n  content: '';\n  position: absolute;\n  inset: 0;\n  z-index: 4;\n  border-radius: inherit;\n  box-shadow: var(--effect-highlight-elevated-sm);\n  pointer-events: none;\n}\n\n.card-navigation__target {\n  color: inherit;\n  text-decoration: none;\n  cursor: pointer;\n}\n\n.card-navigation__header {\n  flex: 0 0 auto;\n  align-items: flex-start;\n  border-radius: inherit;\n}\n\n:host(.card-navigation--content) .card-navigation__header {\n  border-radius: var(--ds-radius-card) var(--ds-radius-card) 0 0;\n  --ds-interaction-divider-width: var(--dimension-stroke-width-012);\n  --ds-interaction-divider-color: var(--color-border-tertiary);\n}\n\n.card-navigation__copy {\n  min-height: var(--dimension-size-400);\n  justify-content: flex-start;\n}\n\nds-text.card-navigation__title,\nds-text.card-navigation__description {\n  overflow-wrap: anywhere;\n}\n\n.card-navigation__chevron {\n  align-self: center;\n  justify-content: center;\n  width: var(--dimension-size-400);\n  color: var(--color-foreground-secondary);\n}\n\n.card-navigation__body {\n  display: flex;\n  flex: 1 1 auto;\n  flex-direction: column;\n  min-height: 0;\n  box-sizing: border-box;\n  background-color: var(--color-background-primary);\n  border-radius: 0 0 var(--ds-radius-card) var(--ds-radius-card);\n}\n\n@media (forced-colors: active) {\n  :host {\n    box-shadow: none;\n    outline: var(--dimension-stroke-width-012) solid var(--ds-forced-color-content);\n    outline-offset: calc(-1 * var(--dimension-stroke-width-012));\n  }\n\n  :host::after {\n    box-shadow: none;\n  }\n}\n",
       "type": "registry:ui"
     },
     {
       "path": "src/wc/components/CardNavigation/CardNavigation.tsx",
-      "content": "import { Component, Event, EventEmitter, h, Host, Prop } from '@stencil/core';\nimport { resolveSafeUrl } from '../../utils';\n\nexport type CardNavigationWidth = 'sm' | 'md' | 'lg';\nexport type CardNavigationVariant = 'navigation-only' | 'content';\n\nexport interface CardNavigationDetail {\n  href: string;\n  originalEvent: MouseEvent;\n}\n\nconst CARD_WIDTH_VARS: Record<CardNavigationWidth, string> = {\n  sm: 'var(--dimension-card-width-sm)',\n  md: 'var(--dimension-card-width-md)',\n  lg: 'var(--dimension-card-width-lg)',\n};\n\nconst CARD_HEIGHT_VARS: Record<CardNavigationWidth, string> = {\n  sm: 'var(--dimension-card-height-sm)',\n  md: 'var(--dimension-card-height-md)',\n  lg: 'var(--dimension-card-height-lg)',\n};\n\n@Component({\n  tag: 'ds-card-navigation',\n  styleUrl: 'CardNavigation.css',\n  scoped: true,\n})\nexport class CardNavigation {\n  /** Destination for the card's native link. */\n  @Prop() href!: string;\n\n  /** Section or destination heading shown in the card header. */\n  @Prop() heading!: string;\n\n  /** Optional supporting copy shown below the heading. */\n  @Prop() description: string | undefined;\n\n  /**\n   * `navigation-only` makes the complete card the link. `content` keeps the\n   * header as the link and exposes a non-interactive body slot below it.\n   */\n  @Prop() variant: CardNavigationVariant = 'navigation-only';\n\n  /** Card width token (`sm` / `md` / `lg`). */\n  @Prop() cardWidth: CardNavigationWidth = 'md';\n\n  /**\n   * Emits before native navigation. Prevent this event to take over routing;\n   * the component will then prevent the original link navigation.\n   */\n  @Event({ cancelable: true }) dsNavigate!: EventEmitter<CardNavigationDetail>;\n\n  private handleNavigation(href: string, originalEvent: MouseEvent) {\n    const navigateEvent = this.dsNavigate.emit({ href, originalEvent });\n    if (navigateEvent.defaultPrevented) originalEvent.preventDefault();\n  }\n\n  private renderHeader(href: string | undefined) {\n    const Target = href ? 'a' : 'div';\n    const description = this.description?.trim();\n\n    return (\n      <Target\n        class={{\n          'card-navigation__target': true,\n          'card-navigation__header': true,\n          'ds-chrome-header': true,\n          'ds-interaction-fill': !!href,\n          'ds-focus-ring-inset': !!href,\n        }}\n        href={href}\n        onClick={href ? (event: MouseEvent) => this.handleNavigation(href, event) : undefined}\n      >\n        <div\n          class={{\n            'card-navigation__copy': true,\n            'ds-chrome-header__copy': true,\n            'ds-chrome-header__copy--stacked': !!description,\n            'ds-control--md': true,\n            'ds-interaction-fill__content': true,\n          }}\n        >\n          <ds-text\n            class=\"card-navigation__title ds-chrome-header__heading\"\n            variant=\"text-title-small\"\n            emphasis\n            color=\"primary\"\n            as=\"h2\"\n          >\n            {this.heading}\n          </ds-text>\n          {description ? (\n            <ds-text\n              class=\"card-navigation__description ds-chrome-header__description\"\n              variant=\"text-body-small\"\n              color=\"secondary\"\n              as=\"span\"\n            >\n              {description}\n            </ds-text>\n          ) : null}\n        </div>\n        <span class=\"card-navigation__chevron ds-chrome-header__trailing ds-interaction-fill__content\">\n          <ds-icon name=\"ChevronRight\" size=\"md\" color=\"inherit\" aria-hidden=\"true\" />\n        </span>\n      </Target>\n    );\n  }\n\n  render() {\n    const href = resolveSafeUrl(this.href);\n    const hasContent = this.variant === 'content';\n\n    return (\n      <Host\n        class={{\n          'card-navigation': true,\n          'card-navigation--navigation-only': !hasContent,\n          'card-navigation--content': hasContent,\n        }}\n        style={{\n          '--_card-navigation-width': CARD_WIDTH_VARS[this.cardWidth],\n          '--_card-navigation-min-height': CARD_HEIGHT_VARS[this.cardWidth],\n        }}\n      >\n        {this.renderHeader(href)}\n        {hasContent ? (\n          <div class=\"card-navigation__body\">\n            <slot />\n          </div>\n        ) : null}\n      </Host>\n    );\n  }\n}\n",
+      "content": "import { Component, Event, EventEmitter, h, Host, Prop } from '@stencil/core';\nimport { resolveSafeUrl } from '../../utils';\n\nexport type CardNavigationWidth = 'sm' | 'md' | 'lg';\nexport type CardNavigationVariant = 'navigation-only' | 'content';\n\nexport interface CardNavigationDetail {\n  href: string;\n  originalEvent: MouseEvent;\n}\n\nconst CARD_WIDTH_VARS: Record<CardNavigationWidth, string> = {\n  sm: 'var(--dimension-card-width-sm)',\n  md: 'var(--dimension-card-width-md)',\n  lg: 'var(--dimension-card-width-lg)',\n};\n\nconst CARD_HEIGHT_VARS: Record<CardNavigationWidth, string> = {\n  sm: 'var(--dimension-card-height-sm)',\n  md: 'var(--dimension-card-height-md)',\n  lg: 'var(--dimension-card-height-lg)',\n};\n\n@Component({\n  tag: 'ds-card-navigation',\n  styleUrl: 'CardNavigation.css',\n  scoped: true,\n})\nexport class CardNavigation {\n  /** Destination for the card's native link. */\n  @Prop() href!: string;\n\n  /** Section or destination heading shown in the card header. */\n  @Prop() heading!: string;\n\n  /** Optional supporting copy shown below the heading. */\n  @Prop() description: string | undefined;\n\n  /**\n   * `navigation-only` makes the complete card the link. `content` keeps the\n   * header as the link and exposes a non-interactive body slot below it.\n   */\n  @Prop() variant: CardNavigationVariant = 'navigation-only';\n\n  /** Card width token (`sm` / `md` / `lg`). */\n  @Prop() cardWidth: CardNavigationWidth = 'md';\n\n  /**\n   * Emits before native navigation. Prevent this event to take over routing;\n   * the component will then prevent the original link navigation.\n   */\n  @Event({ cancelable: true }) dsNavigate!: EventEmitter<CardNavigationDetail>;\n\n  private handleNavigation(href: string, originalEvent: MouseEvent) {\n    const navigateEvent = this.dsNavigate.emit({ href, originalEvent });\n    if (navigateEvent.defaultPrevented) originalEvent.preventDefault();\n  }\n\n  private renderHeader(href: string | undefined) {\n    const Target = href ? 'a' : 'div';\n    const description = this.description?.trim();\n\n    return (\n      <Target\n        class={{\n          'card-navigation__target': true,\n          'card-navigation__header': true,\n          'ds-chrome-header': true,\n          'ds-interaction-fill': !!href,\n          'ds-focus-ring-inset': !!href,\n        }}\n        href={href}\n        onClick={href ? (event: MouseEvent) => this.handleNavigation(href, event) : undefined}\n      >\n        <div\n          class={{\n            'card-navigation__copy': true,\n            'ds-chrome-header__copy': true,\n            'ds-chrome-header__copy--stacked': true,\n            'ds-control--md': true,\n            'ds-interaction-fill__content': true,\n          }}\n        >\n          <ds-text\n            class=\"card-navigation__title ds-chrome-header__heading\"\n            variant=\"text-title-small\"\n            emphasis\n            color=\"primary\"\n            as=\"h2\"\n          >\n            {this.heading}\n          </ds-text>\n          {description ? (\n            <ds-text\n              class=\"card-navigation__description ds-chrome-header__description\"\n              variant=\"text-body-small\"\n              color=\"secondary\"\n              as=\"span\"\n            >\n              {description}\n            </ds-text>\n          ) : null}\n        </div>\n        <span class=\"card-navigation__chevron ds-chrome-header__trailing ds-interaction-fill__content\">\n          <ds-icon name=\"ChevronRight\" size=\"md\" color=\"inherit\" aria-hidden=\"true\" />\n        </span>\n      </Target>\n    );\n  }\n\n  render() {\n    const href = resolveSafeUrl(this.href);\n    const hasContent = this.variant === 'content';\n\n    return (\n      <Host\n        class={{\n          'card-navigation': true,\n          'card-navigation--navigation-only': !hasContent,\n          'card-navigation--content': hasContent,\n        }}\n        style={{\n          '--_card-navigation-width': CARD_WIDTH_VARS[this.cardWidth],\n          '--_card-navigation-min-height': CARD_HEIGHT_VARS[this.cardWidth],\n        }}\n      >\n        {this.renderHeader(href)}\n        {hasContent ? (\n          <div class=\"card-navigation__body\">\n            <slot />\n          </div>\n        ) : null}\n      </Host>\n    );\n  }\n}\n",
       "type": "registry:ui"
     }
   ]

package/dist/mcp-data/registry/field.json

@@ -2,7 +2,7 @@
   "$schema": "https://ui.shadcn.com/schema/registry-item.json",
   "name": "field",
   "title": "Field",
-  "description": "Accessible form-field composition that gives one Input, Textarea, or Select a persistent label, optional guidance, shared error presentation, stable IDs, and observable interaction state.",
+  "description": "Accessible form-field composition that gives one Input, InputDate, InputTime, Textarea, or Select an optional visible label, optional guidance, shared error presentation, stable IDs, and observable interaction state.",
   "type": "registry:ui",
   "meta": {
     "library": "@ds-mo/ui",
@@ -13,9 +13,10 @@
     "intent": {
       "audience": "general",
       "status": "stable",
-      "summary": "Accessible form-field composition that gives one Input, Textarea, or Select a persistent label, optional guidance, shared error presentation, stable IDs, and observable interaction state.",
+      "summary": "Accessible form-field composition that gives one Input, InputDate, InputTime, Textarea, or Select an optional visible label, optional guidance, shared error presentation, stable IDs, and observable interaction state.",
       "useWhen": [
-        "An Input, Textarea, or Select needs a persistent visible label in a form.",
+        "An Input, InputDate, InputTime, Textarea, or Select needs a persistent visible label in a form.",
+        "A nearby heading already names the field, and the control still needs Field's error association and message rhythm.",
         "Help text or an error message must be programmatically associated with one control.",
         "A form layout needs one consistent label-control-message rhythm."
       ],
@@ -33,19 +34,23 @@
       ],
       "commonlyComposedWith": [
         "component:ds-input",
+        "component:ds-input-date",
+        "component:ds-input-time",
         "component:ds-textarea",
         "component:ds-select",
         "component:ds-text"
       ],
       "accessibility": [
-        "Slot exactly one form control. Field assigns its stable control ID and connects the visible label automatically.",
+        "Slot exactly one form control. When a visible label is provided, Field assigns its stable control ID and connects that label automatically.",
+        "Omit the visible label when a nearby heading already names the field. Keep a programmatic name on the slotted control, such as aria-label, and do not set aria-labelledby to an empty value.",
         "The visible description or error ID is merged with any authored aria-describedby references; a rendered error replaces the description.",
         "The error prop forwards aria-invalid and supported design-system control error styling; put visible error text on Field, not again on the child control.",
         "Clicking the label focuses the slotted design-system control without opening a Select popup.",
         "Do not use placeholder text as the only label. Keep label text concise and put format or consequence guidance in description."
       ],
       "states": [
-        "Label, control, description, and error content follow the shared 4px vertical field flow without changing the slotted control's width or semantics.",
+        "The visible label is optional. Omit it when a nearby heading already names the field; Field still associates description and error text with the slotted control.",
+        "Label, control, description, and error content follow the shared 4px vertical field flow without changing the slotted control's width or semantics. When the slotted control is borderless, description and error copy inset to that control's text origin instead of the resting bordered edge.",
         "Field exposes data-focused, data-filled, data-dirty, data-touched, data-invalid, data-disabled, and data-required hooks while the slotted control remains the source of value and interaction behavior.",
         "A rendered error replaces the description; preserve essential guidance in the error message so users retain what they need to correct the field.",
         "Field owns validation presentation but not validation timing; the form decides when to set error and errorMessage.",
@@ -61,7 +66,7 @@
           "Assign child component values and option arrays through their normal JavaScript properties."
         ],
         "react": [
-          "Compose one DsInput, DsTextarea, or DsSelect child and control validation timing in the form owner."
+          "Compose one DsInput, DsInputDate, DsInputTime, DsTextarea, or DsSelect child and control validation timing in the form owner."
         ],
         "angular": [
           "Compose the generated Field adapter around the control adapter and its matching Angular value accessor."
@@ -115,11 +120,11 @@
         },
         "label": {
           "type": "string",
-          "resolvedType": "string",
+          "resolvedType": "string | undefined",
           "attribute": "label",
-          "required": true,
+          "required": false,
           "mutable": false,
-          "description": "Persistent visible label for the single slotted control."
+          "description": "Visible label for the slotted control. Omit when a nearby heading already names the field."
         }
       },
       "events": [],
@@ -162,11 +167,11 @@
       },
       "label": {
         "type": "string",
-        "resolvedType": "string",
+        "resolvedType": "string | undefined",
         "attribute": "label",
-        "required": true,
+        "required": false,
         "mutable": false,
-        "description": "Persistent visible label for the single slotted control."
+        "description": "Visible label for the slotted control. Omit when a nearby heading already names the field."
       }
     },
     "events": [],
@@ -216,12 +221,12 @@
   "files": [
     {
       "path": "src/wc/components/Field/Field.css",
-      "content": "@import '../../utils/field-stack.css';\n\n:host {\n  display: block;\n}\n\n.field__control {\n  display: flex;\n  min-width: 0;\n}\n\n.field__control > * {\n  width: 100%;\n}\n",
+      "content": "@import '../../utils/control-density.css';\n@import '../../utils/field-stack.css';\n\n:host {\n  display: block;\n}\n\n.field__control {\n  display: flex;\n  min-width: 0;\n}\n\n.field__control > * {\n  width: 100%;\n}\n",
       "type": "registry:ui"
     },
     {
       "path": "src/wc/components/Field/Field.tsx",
-      "content": "import { Component, Element, Prop, State, Watch, h, Host } from '@stencil/core';\n\ninterface FieldControl extends HTMLElement {\n  value?: string | string[];\n  inputId?: string;\n  error?: boolean;\n  disabled?: boolean;\n  isInactive?: boolean;\n  required?: boolean;\n  setFocus?: () => Promise<void> | void;\n}\n\ninterface AuthoredAria {\n  labelledby: string[];\n  describedby: string[];\n}\n\nlet fieldCounter = 0;\n\nconst tokens = (value: string | null | undefined): string[] =>\n  value?.split(/\\s+/).filter(Boolean) ?? [];\n\nconst uniqueTokens = (...groups: string[][]): string[] => [...new Set(groups.flat())];\n\n@Component({\n  tag: 'ds-field',\n  styleUrl: 'Field.css',\n  scoped: true,\n})\nexport class Field {\n  @Element() el!: HTMLElement;\n\n  /** Persistent visible label for the single slotted control. */\n  @Prop() label!: string;\n  /** Explicit ID for the slotted control; generated when omitted. */\n  @Prop() fieldId: string | undefined;\n  /** Optional guidance associated with the slotted control while no visible error is shown. */\n  @Prop() description: string | undefined;\n  /** Invalid visual and accessible state forwarded to supported ds controls. */\n  @Prop() error: boolean = false;\n  /** Visible error associated with the slotted control while error is true. */\n  @Prop() errorMessage: string | undefined;\n\n  @State() private focused = false;\n  @State() private filled = false;\n  @State() private dirty = false;\n  @State() private touched = false;\n  @State() private controlDisabled = false;\n  @State() private controlRequired = false;\n  /** Bumped to let Stencil relocate a control added after the initial render. */\n  @State() private slotRevision = 0;\n\n  private readonly generatedId = `ds-field-${++fieldCounter}`;\n  private controlContainer?: HTMLDivElement;\n  private control?: FieldControl;\n  private initialValue = '';\n  private authoredAria = new WeakMap<FieldControl, AuthoredAria>();\n  private childObserver?: MutationObserver;\n  private didLoad = false;\n\n  connectedCallback() {\n    if (this.didLoad) this.observeLateControls();\n  }\n\n  disconnectedCallback() {\n    this.childObserver?.disconnect();\n    this.childObserver = undefined;\n  }\n\n  componentDidLoad() {\n    this.syncControl();\n    this.didLoad = true;\n    this.observeLateControls();\n    requestAnimationFrame(() => this.syncControl());\n  }\n\n  componentDidRender() {\n    this.syncControl();\n  }\n\n  @Watch('fieldId')\n  @Watch('description')\n  @Watch('error')\n  @Watch('errorMessage')\n  onFieldContractChange() {\n    this.syncControl();\n  }\n\n  private get controlId(): string {\n    return this.fieldId || this.generatedId;\n  }\n\n  private get labelId(): string {\n    return `${this.controlId}-label`;\n  }\n\n  private get descriptionId(): string {\n    return `${this.controlId}-description`;\n  }\n\n  private get errorId(): string {\n    return `${this.controlId}-error`;\n  }\n\n  private get renderedDescription(): boolean {\n    return Boolean(this.description) && !this.renderedError;\n  }\n\n  private get renderedError(): boolean {\n    return this.error && Boolean(this.errorMessage);\n  }\n\n  private readValue(control: FieldControl): string {\n    const value = control.value;\n    return Array.isArray(value) ? value.join('\\u001f') : String(value ?? '');\n  }\n\n  private updateControlAttribute(control: FieldControl, name: string, value: string | undefined) {\n    if (value === undefined) {\n      if (control.hasAttribute(name)) control.removeAttribute(name);\n      return;\n    }\n    if (control.getAttribute(name) !== value) control.setAttribute(name, value);\n  }\n\n  private findControl(): FieldControl | undefined {\n    return this.controlContainer?.querySelector<FieldControl>(':scope > :not(slot)') ?? undefined;\n  }\n\n  private observeLateControls() {\n    if (this.childObserver || typeof MutationObserver === 'undefined') return;\n    this.childObserver = new MutationObserver(records => {\n      const addedControl = records.some(record =>\n        Array.from(record.addedNodes).some(node => node.nodeType === 1)\n      );\n      if (addedControl) this.slotRevision++;\n    });\n    this.childObserver.observe(this.el, { childList: true });\n  }\n\n  private syncControl = () => {\n    const control = this.findControl();\n    if (!control) return;\n\n    if (control !== this.control) {\n      this.control = control;\n      this.initialValue = this.readValue(control);\n      this.authoredAria.set(control, {\n        labelledby: tokens(control.getAttribute('aria-labelledby')),\n        describedby: tokens(control.getAttribute('aria-describedby')),\n      });\n    }\n\n    const isDsControl = control.tagName.startsWith('DS-');\n    if (isDsControl && 'inputId' in control) control.inputId = this.controlId;\n    else this.updateControlAttribute(control, 'id', this.controlId);\n\n    const authored = this.authoredAria.get(control) ?? { labelledby: [], describedby: [] };\n    const labelledby = uniqueTokens(authored.labelledby, [this.labelId]).join(' ');\n    const describedby = uniqueTokens(\n      authored.describedby,\n      this.renderedDescription ? [this.descriptionId] : [],\n      this.renderedError ? [this.errorId] : []\n    ).join(' ');\n\n    this.updateControlAttribute(control, 'aria-labelledby', labelledby);\n    this.updateControlAttribute(control, 'aria-describedby', describedby || undefined);\n    this.updateControlAttribute(control, 'aria-invalid', this.error ? 'true' : undefined);\n\n    if (isDsControl && 'error' in control && control.error !== this.error)\n      control.error = this.error;\n\n    const value = this.readValue(control);\n    this.filled = value.length > 0;\n    this.dirty = value !== this.initialValue;\n    this.controlDisabled = Boolean(\n      control.disabled || control.isInactive || control.hasAttribute('disabled')\n    );\n    this.controlRequired = Boolean(control.required || control.hasAttribute('required'));\n  };\n\n  private handleLabelClick = (event: MouseEvent) => {\n    if (!this.control?.tagName.startsWith('DS-')) return;\n    event.preventDefault();\n    this.control.setFocus?.();\n  };\n\n  private handleFocusIn = () => {\n    this.focused = true;\n  };\n\n  private handleFocusOut = (event: FocusEvent) => {\n    if (event.relatedTarget instanceof Node && this.el.contains(event.relatedTarget)) return;\n    this.focused = false;\n    this.touched = true;\n  };\n\n  private handleValueChange = () => {\n    this.syncControl();\n  };\n\n  render() {\n    return (\n      <Host\n        data-focused={this.focused ? '' : undefined}\n        data-filled={this.filled ? '' : undefined}\n        data-dirty={this.dirty ? '' : undefined}\n        data-touched={this.touched ? '' : undefined}\n        data-invalid={this.error ? '' : undefined}\n        data-disabled={this.controlDisabled ? '' : undefined}\n        data-required={this.controlRequired ? '' : undefined}\n        onFocusin={this.handleFocusIn}\n        onFocusout={this.handleFocusOut}\n        onInput={this.handleValueChange}\n        onChange={this.handleValueChange}\n        onDsChange={this.handleValueChange}\n      >\n        <div class=\"field ds-field-stack\">\n          <ds-text\n            class=\"field__label\"\n            as=\"label\"\n            variant=\"text-body-small\"\n            color=\"primary\"\n            emphasis\n            for={this.controlId}\n            textId={this.labelId}\n            onClick={this.handleLabelClick}\n          >\n            {this.label}\n          </ds-text>\n          <div class=\"field__control\" ref={el => (this.controlContainer = el)}>\n            <slot onSlotchange={this.syncControl} />\n          </div>\n          {this.renderedDescription && (\n            <ds-text\n              class=\"field__description\"\n              as=\"div\"\n              variant=\"text-body-small\"\n              color=\"secondary\"\n              textId={this.descriptionId}\n            >\n              {this.description}\n            </ds-text>\n          )}\n          {this.renderedError && (\n            <ds-text\n              class=\"field__error\"\n              as=\"div\"\n              variant=\"text-body-small\"\n              color=\"negative\"\n              textId={this.errorId}\n              role=\"alert\"\n            >\n              {this.errorMessage}\n            </ds-text>\n          )}\n        </div>\n      </Host>\n    );\n  }\n}\n",
+      "content": "import { Component, Element, Prop, State, Watch, h, Host } from '@stencil/core';\n\ninterface FieldControl extends HTMLElement {\n  value?: string | string[];\n  inputId?: string;\n  error?: boolean;\n  disabled?: boolean;\n  isInactive?: boolean;\n  required?: boolean;\n  hasBorder?: boolean;\n  size?: string;\n  setFocus?: () => Promise<void> | void;\n}\n\ninterface AuthoredAria {\n  labelledby: string[];\n  describedby: string[];\n}\n\nlet fieldCounter = 0;\n\nconst tokens = (value: string | null | undefined): string[] =>\n  value?.split(/\\s+/).filter(Boolean) ?? [];\n\nconst uniqueTokens = (...groups: string[][]): string[] => [...new Set(groups.flat())];\n\nconst CONTROL_SIZES = ['lg', 'md', 'sm', 'xs'] as const;\ntype FieldControlSize = (typeof CONTROL_SIZES)[number];\n\nconst readControlSize = (control: FieldControl): FieldControlSize =>\n  CONTROL_SIZES.includes(control.size as FieldControlSize)\n    ? (control.size as FieldControlSize)\n    : 'md';\n\n@Component({\n  tag: 'ds-field',\n  styleUrl: 'Field.css',\n  scoped: true,\n})\nexport class Field {\n  @Element() el!: HTMLElement;\n\n  /** Visible label for the slotted control. Omit when a nearby heading already names the field. */\n  @Prop() label?: string;\n  /** Explicit ID for the slotted control; generated when omitted. */\n  @Prop() fieldId: string | undefined;\n  /** Optional guidance associated with the slotted control while no visible error is shown. */\n  @Prop() description: string | undefined;\n  /** Invalid visual and accessible state forwarded to supported ds controls. */\n  @Prop() error: boolean = false;\n  /** Visible error associated with the slotted control while error is true. */\n  @Prop() errorMessage: string | undefined;\n\n  @State() private focused = false;\n  @State() private filled = false;\n  @State() private dirty = false;\n  @State() private touched = false;\n  @State() private controlDisabled = false;\n  @State() private controlRequired = false;\n  @State() private controlBorderless = false;\n  @State() private controlSize: 'lg' | 'md' | 'sm' | 'xs' = 'md';\n  /** Bumped to let Stencil relocate a control added after the initial render. */\n  @State() private slotRevision = 0;\n\n  private readonly generatedId = `ds-field-${++fieldCounter}`;\n  private controlContainer?: HTMLDivElement;\n  private control?: FieldControl;\n  private initialValue = '';\n  private authoredAria = new WeakMap<FieldControl, AuthoredAria>();\n  private childObserver?: MutationObserver;\n  private controlAttrObserver?: MutationObserver;\n  private didLoad = false;\n\n  connectedCallback() {\n    if (this.didLoad) this.observeLateControls();\n  }\n\n  disconnectedCallback() {\n    this.childObserver?.disconnect();\n    this.childObserver = undefined;\n    this.controlAttrObserver?.disconnect();\n    this.controlAttrObserver = undefined;\n  }\n\n  componentDidLoad() {\n    this.syncControl();\n    this.didLoad = true;\n    this.observeLateControls();\n    requestAnimationFrame(() => this.syncControl());\n  }\n\n  componentDidRender() {\n    this.syncControl();\n  }\n\n  @Watch('fieldId')\n  @Watch('label')\n  @Watch('description')\n  @Watch('error')\n  @Watch('errorMessage')\n  onFieldContractChange() {\n    this.syncControl();\n  }\n\n  private get hasLabel(): boolean {\n    return Boolean(this.label?.trim());\n  }\n\n  private get controlId(): string {\n    return this.fieldId || this.generatedId;\n  }\n\n  private get labelId(): string {\n    return `${this.controlId}-label`;\n  }\n\n  private get descriptionId(): string {\n    return `${this.controlId}-description`;\n  }\n\n  private get errorId(): string {\n    return `${this.controlId}-error`;\n  }\n\n  private get renderedDescription(): boolean {\n    return Boolean(this.description) && !this.renderedError;\n  }\n\n  private get renderedError(): boolean {\n    return this.error && Boolean(this.errorMessage);\n  }\n\n  private readValue(control: FieldControl): string {\n    const value = control.value;\n    return Array.isArray(value) ? value.join('\\u001f') : String(value ?? '');\n  }\n\n  private updateControlAttribute(control: FieldControl, name: string, value: string | undefined) {\n    if (value === undefined) {\n      if (control.hasAttribute(name)) control.removeAttribute(name);\n      return;\n    }\n    if (control.getAttribute(name) !== value) control.setAttribute(name, value);\n  }\n\n  private findControl(): FieldControl | undefined {\n    return this.controlContainer?.querySelector<FieldControl>(':scope > :not(slot)') ?? undefined;\n  }\n\n  private observeLateControls() {\n    if (this.childObserver || typeof MutationObserver === 'undefined') return;\n    this.childObserver = new MutationObserver(records => {\n      const addedControl = records.some(record =>\n        Array.from(record.addedNodes).some(node => node.nodeType === 1)\n      );\n      if (addedControl) this.slotRevision++;\n    });\n    this.childObserver.observe(this.el, { childList: true });\n  }\n\n  private syncControl = () => {\n    const control = this.findControl();\n    if (!control) return;\n\n    if (control !== this.control) {\n      this.control = control;\n      this.initialValue = this.readValue(control);\n      this.authoredAria.set(control, {\n        labelledby: tokens(control.getAttribute('aria-labelledby')),\n        describedby: tokens(control.getAttribute('aria-describedby')),\n      });\n      this.observeControlAttributes(control);\n    }\n\n    const isDsControl = control.tagName.startsWith('DS-');\n    if (isDsControl && 'inputId' in control) control.inputId = this.controlId;\n    else this.updateControlAttribute(control, 'id', this.controlId);\n\n    const authored = this.authoredAria.get(control) ?? { labelledby: [], describedby: [] };\n    const labelledby = uniqueTokens(authored.labelledby, this.hasLabel ? [this.labelId] : []).join(\n      ' '\n    );\n    const describedby = uniqueTokens(\n      authored.describedby,\n      this.renderedDescription ? [this.descriptionId] : [],\n      this.renderedError ? [this.errorId] : []\n    ).join(' ');\n\n    this.updateControlAttribute(control, 'aria-labelledby', labelledby || undefined);\n    this.updateControlAttribute(control, 'aria-describedby', describedby || undefined);\n    this.updateControlAttribute(control, 'aria-invalid', this.error ? 'true' : undefined);\n\n    if (isDsControl && 'error' in control && control.error !== this.error)\n      control.error = this.error;\n\n    const value = this.readValue(control);\n    this.filled = value.length > 0;\n    this.dirty = value !== this.initialValue;\n    this.controlDisabled = Boolean(\n      control.disabled || control.isInactive || control.hasAttribute('disabled')\n    );\n    this.controlRequired = Boolean(control.required || control.hasAttribute('required'));\n    this.controlBorderless = control.hasBorder === false;\n    this.controlSize = readControlSize(control);\n  };\n\n  private observeControlAttributes(control: FieldControl) {\n    this.controlAttrObserver?.disconnect();\n    this.controlAttrObserver = new MutationObserver(() => this.syncControl());\n    this.controlAttrObserver.observe(control, {\n      attributes: true,\n      attributeFilter: ['has-border', 'size', 'class'],\n    });\n  }\n\n  private handleLabelClick = (event: MouseEvent) => {\n    if (!this.control?.tagName.startsWith('DS-')) return;\n    event.preventDefault();\n    this.control.setFocus?.();\n  };\n\n  private handleFocusIn = () => {\n    this.focused = true;\n  };\n\n  private handleFocusOut = (event: FocusEvent) => {\n    if (event.relatedTarget instanceof Node && this.el.contains(event.relatedTarget)) return;\n    this.focused = false;\n    this.touched = true;\n  };\n\n  private handleValueChange = () => {\n    this.syncControl();\n  };\n\n  render() {\n    return (\n      <Host\n        data-focused={this.focused ? '' : undefined}\n        data-filled={this.filled ? '' : undefined}\n        data-dirty={this.dirty ? '' : undefined}\n        data-touched={this.touched ? '' : undefined}\n        data-invalid={this.error ? '' : undefined}\n        data-disabled={this.controlDisabled ? '' : undefined}\n        data-required={this.controlRequired ? '' : undefined}\n        onFocusin={this.handleFocusIn}\n        onFocusout={this.handleFocusOut}\n        onInput={this.handleValueChange}\n        onChange={this.handleValueChange}\n        onDsChange={this.handleValueChange}\n      >\n        <div\n          class={{\n            field: true,\n            'ds-field-stack': true,\n            'ds-field-stack--supporting-inset': this.controlBorderless,\n            [`ds-control--${this.controlSize}`]: true,\n          }}\n        >\n          {this.hasLabel ? (\n            <ds-text\n              class=\"field__label\"\n              as=\"label\"\n              variant=\"text-body-small\"\n              color=\"primary\"\n              emphasis\n              for={this.controlId}\n              textId={this.labelId}\n              onClick={this.handleLabelClick}\n            >\n              {this.label}\n            </ds-text>\n          ) : null}\n          <div class=\"field__control\" ref={el => (this.controlContainer = el)}>\n            <slot onSlotchange={this.syncControl} />\n          </div>\n          {this.renderedDescription && (\n            <ds-text\n              class=\"field__description\"\n              as=\"div\"\n              variant=\"text-body-small\"\n              color=\"secondary\"\n              textId={this.descriptionId}\n            >\n              {this.description}\n            </ds-text>\n          )}\n          {this.renderedError && (\n            <ds-text\n              class=\"field__error\"\n              as=\"div\"\n              variant=\"text-body-small\"\n              color=\"negative\"\n              textId={this.errorId}\n              role=\"alert\"\n            >\n              {this.errorMessage}\n            </ds-text>\n          )}\n        </div>\n      </Host>\n    );\n  }\n}\n",
       "type": "registry:ui"
     }
   ]