@reddb-io/ui-kit 0.3.4 → 0.3.6

package/vendor/ds/kits/base/src/core/a11y.ts

@@ -0,0 +1,106 @@
+/** Development detection works in Vite and native React build pipelines. */
+function a11yDevelopment(): boolean {
+  return (import.meta as { env?: { DEV?: boolean } }).env?.DEV ??
+    (globalThis as { process?: { env?: { NODE_ENV?: string } } }).process?.env?.NODE_ENV === "development";
+}
+
+// Framework-independent accessible-name diagnostics. Never changes DOM semantics.
+
+const warned = new Set<string>();
+
+/**
+ * Warn, once per session and only in development, that `component` broke an
+ * accessibility contract. `problem` says what is missing, `fix` the props that
+ * supply it. The sibling of `warnDeprecated`, for the same audience.
+ */
+export function warnA11y(component: string, problem: string, fix: string): void {
+  if (!a11yDevelopment()) return;
+  const key = `${component}\u0000${problem}`;
+  if (warned.has(key)) return;
+  warned.add(key);
+  console.warn(`[reddb ${component}] ${problem}. ${fix}`);
+}
+
+function nonEmpty(value: string | null | undefined): boolean {
+  return typeof value === "string" && value.trim() !== "";
+}
+
+/** Text a subtree contributes to a name, skipping what is hidden from assistive technology. */
+function namedContent(node: Node): boolean {
+  if (node.nodeType === 3) return nonEmpty(node.textContent);
+  if (node.nodeType !== 1) return false;
+  const element = node as Element;
+  if (element.getAttribute("aria-hidden") === "true") return false;
+  if (nonEmpty(element.getAttribute("aria-label"))) return true;
+  if (element.tagName === "IMG" && nonEmpty(element.getAttribute("alt"))) return true;
+  if (element.tagName.toLowerCase() === "title") return nonEmpty(element.textContent);
+  for (const child of element.childNodes) if (namedContent(child)) return true;
+  return false;
+}
+
+/**
+ * Whether `element` has an accessible name a screen reader can announce:
+ * `aria-label`, an `aria-labelledby` that resolves to text, a native `<label>`
+ * (wrapping or `for`), a `title`, or — for a button — its own content.
+ *
+ * A pragmatic approximation of the accessible-name computation, used only to
+ * decide whether to warn in development, never to change what renders.
+ */
+export function hasAccessibleName(element: Element, { fromContent = false } = {}): boolean {
+  if (nonEmpty(element.getAttribute("aria-label"))) return true;
+  const labelledBy = element.getAttribute("aria-labelledby");
+  if (nonEmpty(labelledBy)) {
+    const root = element.getRootNode() as Document | ShadowRoot;
+    for (const id of labelledBy!.trim().split(/\s+/)) {
+      const target = root.getElementById?.(id) ?? element.ownerDocument.getElementById(id);
+      if (target && nonEmpty(target.textContent)) return true;
+    }
+  }
+  const labels = (element as HTMLInputElement).labels;
+  if (labels) for (const label of labels) if (nonEmpty(label.textContent)) return true;
+  if (nonEmpty(element.getAttribute("title"))) return true;
+  return fromContent && namedContent(element);
+}
+
+/** The ways a field gets its name, quoted in every field warning. */
+export const FIELD_NAME_FIX =
+  "Wrap it in a Field with a `label`, or pass `aria-label` or `aria-labelledby`, or point a native <label for> at its id";
+
+/**
+ * Warn in development when a mounted form control has no accessible name.
+ * Checked after mount, so a `<label for>` written anywhere in the document
+ * counts, exactly as it does for the browser.
+ */
+export function checkFieldName(component: string, element: Element | undefined): void {
+  if (!a11yDevelopment() || !element) return;
+  if (hasAccessibleName(element)) return;
+  warnA11y(component, "renders a form control with no accessible name", `${FIELD_NAME_FIX}.`);
+}
+
+/** Visible words for Label in Name; screen-reader-only content and decorative SVG are excluded. */
+function contentWords(node: Node): string {
+  if (node.nodeType === 3) return node.textContent ?? "";
+  if (node.nodeType !== 1) return "";
+  const element = node as Element;
+  if (element.matches('[hidden], .hidden, .sr-only, svg, script, style')) return "";
+  return [...element.childNodes].map(contentWords).join(" ");
+}
+
+/** Buttons keep their visible words in the accessible name (WCAG 2.5.3). */
+export function checkButtonName(component: string, element: Element | undefined): void {
+  if (!a11yDevelopment() || !element) return;
+  if (!hasAccessibleName(element, { fromContent: true })) {
+    warnA11y(component, "renders with no text and no `aria-label`, so it has no accessible name", "Pass `aria-label` (or `aria-labelledby`) to an icon-only Button.");
+    return;
+  }
+  const normalize = (text: string) => text.replace(/\s+/g, " ").trim().toLocaleLowerCase();
+  const visible = normalize(contentWords(element));
+  if (!/[\p{L}\p{N}]/u.test(visible)) return;
+  const ids = element.getAttribute("aria-labelledby")?.trim().split(/\s+/).filter(Boolean) ?? [];
+  const root = element.getRootNode() as Document | ShadowRoot;
+  const referenced = ids.map(id => (root.getElementById?.(id) ?? element.ownerDocument.getElementById(id))?.textContent ?? "").join(" ");
+  const name = normalize(referenced || element.getAttribute("aria-label") || visible);
+  if (!name.includes(visible)) {
+    warnA11y(component, "visible text is missing from its accessible name", "Keep the visible action in the name; use `aria-describedby` for row context instead of replacing the action with `aria-labelledby`.");
+  }
+}

package/vendor/ds/kits/base/src/core/appearance-switch.ts

@@ -0,0 +1,39 @@
+import { applyAppearance, type AppearanceAxis, type AppearanceOption, type AppearanceStorage } from "../appearance-switch.behavior";
+
+export interface AppearanceSwitchContract {
+  /** Visible accessible control name. */
+  label: string;
+  /** The single independent axis this control changes. */
+  axis: AppearanceAxis;
+  /** Caller-owned values; the component invents no Theme, scheme, or stop. */
+  options: readonly AppearanceOption[];
+  /** Current axis value; caller-owned in controlled React use. */
+  value?: string;
+  /** Initial uncontrolled value, restored by native form reset. */
+  defaultValue?: string;
+  /** Root receiving the axis attribute. Defaults to the document root. */
+  root?: HTMLElement;
+  /** Persistence seam. Defaults to browser localStorage when available. */
+  storage?: AppearanceStorage;
+  /** Stable persistence key. Defaults to one key per independent axis. */
+  persistKey?: string;
+}
+
+/** Only enabled caller-owned options can change an appearance axis. */
+export function appearanceValue(options: readonly AppearanceOption[], ...candidates: (string | null | undefined)[]): string | undefined {
+  for (const value of candidates) if (options.some(option => !option.disabled && option.value === value)) return value!;
+  return options.find(option => !option.disabled)?.value;
+}
+export function appearancePersistence(storage?: AppearanceStorage): AppearanceStorage | undefined {
+  if (storage) return storage;
+  try { return globalThis.localStorage; } catch { return undefined; }
+}
+export function readAppearance(storage: AppearanceStorage | undefined, key: string): string | undefined {
+  try { return storage?.getItem(key) ?? undefined; } catch { return undefined; }
+}
+/** Persistence is optional; blocked storage cannot prevent an appearance change. */
+export function commitAppearance(root: HTMLElement | undefined, axis: AppearanceAxis, value: string | undefined, storage: AppearanceStorage | undefined, key: string): void {
+  if (value === undefined) return;
+  if (root) applyAppearance(root, axis, value);
+  try { storage?.setItem(key, value); } catch { /* Browser policy or quota: retain the usable in-memory choice. */ }
+}

package/vendor/ds/kits/base/src/core/avatar.ts

@@ -0,0 +1,27 @@
+import type { AvatarSize } from "../avatar.variants";
+
+/** Identity and appearance shared by the native Avatar adapters. */
+export interface AvatarContract {
+  /** Optional image source. Omitting it renders the fallback immediately. */
+  src?: string;
+  /** Accessible name for the person or entity represented. */
+  name: string;
+  /** Visible text required when no icon alternative is supplied. */
+  fallback?: string;
+  /** Density-responsive avatar size. */
+  size?: AvatarSize;
+  /** Extra classes merged onto the image. */
+  imageClass?: string;
+  /** Extra classes merged onto the fallback layer. */
+  fallbackClass?: string;
+}
+
+/** A failure belongs to its source; a replacement image gets its own attempt. */
+export function avatarImageVisible(src: string | undefined, failedSrc: string | undefined): src is string {
+  return Boolean(src) && src !== failedSrc;
+}
+
+/** The browser may finish a failed SSR image before hydration installs handlers. */
+export function avatarImageFailed(image: HTMLImageElement | null | undefined): boolean {
+  return Boolean(image?.complete && image.naturalWidth === 0);
+}

package/vendor/ds/kits/base/src/core/breadcrumbs.ts

@@ -0,0 +1,11 @@
+/** One stable item in a native breadcrumb trail. */
+export interface BreadcrumbItem {
+  /** Stable item identity. */
+  id: string;
+  /** Visible destination name. */
+  label: string;
+  /** Link destination; omitted, the item is plain text. */
+  href?: string;
+  /** Marks the current page without linking it. */
+  current?: boolean;
+}

package/vendor/ds/kits/base/src/core/calendar.ts

@@ -0,0 +1,95 @@
+import { getDayOfWeek, getLocalTimeZone, parseDate, startOfMonth, today, type DateValue } from "@internationalized/date";
+/** A range can be incomplete while its second bound is being chosen. */
+export interface CalendarRange { start: DateValue | undefined; end: DateValue | undefined }
+/** Calendar semantics independent of either headless rendering implementation. */
+export interface CalendarContract {
+  /** Base accessible name; the visible month and year are appended. */
+  label: string;
+  /** Month shown when no value is selected; moves with keyboard or month navigation. */
+  placeholder?: DateValue;
+  /** Earliest selectable date. */
+  minValue?: DateValue;
+  /** Latest selectable date. */
+  maxValue?: DateValue;
+  /** Prevent focus and selection of every date and navigation control. */
+  disabled?: boolean;
+  /** Permit navigation and focus without changing selection. */
+  readonly?: boolean;
+  /** Prevent clearing a selected date by selecting it again. */
+  preventDeselect?: boolean;
+  /** Mark individual dates disabled and exclude them from keyboard focus. */
+  isDateDisabled?: (date: DateValue) => boolean;
+  /** Mark dates unavailable for selection. */
+  isDateUnavailable?: (date: DateValue) => boolean;
+  /** Locale for calendar labels, date announcements and right-to-left direction. */
+  locale?: string;
+  /** First weekday, Sunday=0 through Saturday=6. */
+  weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6;
+  /** Width of weekday names; defaults to short. */
+  weekdayFormat?: Intl.DateTimeFormatOptions["weekday"];
+  /** Render six weeks per month to keep the height stable. Defaults to true. */
+  fixedWeeks?: boolean;
+  /** Number of simultaneous months; defaults to one. */
+  numberOfMonths?: number;
+  /** Move by the number of visible months rather than one month. */
+  pagedNavigation?: boolean;
+  /** Disable dates drawn outside each grid's named month. */
+  disableDaysOutsideMonth?: boolean;
+  /** Formatting of the visible month name. */
+  monthFormat?: Intl.DateTimeFormatOptions["month"] | ((month: number) => string);
+  /** Formatting of the visible year. */
+  yearFormat?: Intl.DateTimeFormatOptions["year"] | ((year: number) => string);
+  /** Extra classes merged onto both month navigation controls. */
+  navigationClass?: string;
+  /** Extra classes merged onto every day control. */
+  dayClass?: string;
+}
+export function parseCalendarDate(value?: string): DateValue | undefined {
+  try { return value ? parseDate(value) : undefined; } catch { return undefined; }
+}
+export function currentCalendarDate() { return today(getLocalTimeZone()); }
+export function calendarMonths(date: DateValue, count: number, weekStart: number, fixed: boolean, locale: string) {
+  return Array.from({ length: Math.max(1, Math.trunc(count) || 1) }, (_, index) => {
+    const month = startOfMonth(date.add({ months: index }));
+    const first = month.subtract({ days: (getDayOfWeek(month, locale, "sun") - weekStart + 7) % 7 });
+    const length = fixed ? 42 : Math.ceil(((getDayOfWeek(month, locale, "sun") - weekStart + 7) % 7 + month.calendar.getDaysInMonth(month)) / 7) * 7;
+    return { month, days: Array.from({ length }, (_, index) => first.add({ days: index })) };
+  });
+}
+export function calendarDisabled(date: DateValue, options: Pick<CalendarContract, "disabled" | "minValue" | "maxValue" | "isDateDisabled">) {
+  return !!(options.disabled || (options.minValue && date.compare(options.minValue) < 0) || (options.maxValue && date.compare(options.maxValue) > 0) || options.isDateDisabled?.(date));
+}
+export function calendarRangeValid(start: DateValue, end: DateValue, options: CalendarContract & { minDays?: number; maxDays?: number; excludeDisabled?: boolean }) {
+  const length = end.calendar.toJulianDay(end) - start.calendar.toJulianDay(start) + 1;
+  if (length < (options.minDays ?? 1) || length > (options.maxDays ?? Infinity)) return false;
+  if (options.excludeDisabled) for (let day = start; day.compare(end) <= 0; day = day.add({ days: 1 })) {
+    if (calendarDisabled(day, options) || options.isDateUnavailable?.(day)) return false;
+  }
+  return true;
+}
+/** Arrow/day, week-edge and month/year moves; disabled dates are skipped within the bounds. */
+export function calendarKeyTarget(date: DateValue, key: string, options: CalendarContract, shift = false, rtl = false): DateValue | undefined {
+  const weekStart = options.weekStartsOn ?? 0, weekday = getDayOfWeek(date, options.locale ?? "en", "sun");
+  let next = key === "ArrowLeft" ? date.add({ days: rtl ? 1 : -1 }) : key === "ArrowRight" ? date.add({ days: rtl ? -1 : 1 }) : key === "ArrowUp" ? date.subtract({ days: 7 }) : key === "ArrowDown" ? date.add({ days: 7 }) : key === "Home" ? date.subtract({ days: (weekday - weekStart + 7) % 7 }) : key === "End" ? date.add({ days: 6 - (weekday - weekStart + 7) % 7 }) : key === "PageUp" ? date.subtract(shift ? { years: 1 } : { months: 1 }) : key === "PageDown" ? date.add(shift ? { years: 1 } : { months: 1 }) : undefined;
+  if (!next || options.disabled) return undefined;
+  if (options.minValue && next.compare(options.minValue) < 0) next = options.minValue;
+  if (options.maxValue && next.compare(options.maxValue) > 0) next = options.maxValue;
+  const step = next.compare(date) >= 0 ? 1 : -1;
+  for (let attempt = 0; attempt < 366; attempt++) {
+    if (!calendarDisabled(next, options)) return next;
+    next = next.add({ days: step });
+    if ((options.minValue && next.compare(options.minValue) < 0) || (options.maxValue && next.compare(options.maxValue) > 0)) return undefined;
+  }
+  return undefined;
+}
+
+/** Resolve text direction for language and script locales across modern Intl implementations. */
+export function calendarDirection(locale: string): "ltr" | "rtl" {
+  const info = new Intl.Locale(locale) as Intl.Locale & { textInfo?: { direction: string }; getTextInfo?: () => { direction: string } };
+  return (info.getTextInfo?.().direction ?? info.textInfo?.direction ?? (/^(ar|fa|he|ur)(-|$)/.test(locale) ? "rtl" : "ltr")) === "rtl" ? "rtl" : "ltr";
+}
+
+/** Keep a DateValue's calendar identity when a renderer derives its calendar from locale. */
+export function calendarLocale(locale: string, date: DateValue | undefined): string {
+  return date ? new Intl.Locale(locale, { calendar: date.calendar.identifier }).toString() : locale;
+}

package/vendor/ds/kits/base/src/core/carousel.ts

@@ -0,0 +1,8 @@
+import type { ImageAsset } from "../image.variants";
+/** Portable content properties of one carousel slide. */
+export interface CarouselSlideContract {
+  /** Visible meaning included in the slide's accessible position label. */
+  label: string;
+  /** Base Image used when the adapter has no custom slide content. */
+  image?: ImageAsset;
+}

package/vendor/ds/kits/base/src/core/choices.ts

@@ -0,0 +1,29 @@
+/** One flat native Select option; richer groups arrive as native option children. */
+export interface SelectOption {
+  /** Native serialized value. */
+  value: string;
+  /** Visible option name. */
+  label: string;
+  /** Keep this option unavailable to native selection. */
+  disabled?: boolean;
+}
+
+/** Native selected values; multiple selections preserve option order. */
+export type SelectValue = string | number | readonly string[];
+
+/** Read native selection for binding and reset; callbacks keep their first-value dialect. */
+export function readSelectValue(element: HTMLSelectElement): string | string[] {
+  return element.multiple ? Array.from(element.selectedOptions, option => option.value) : element.value;
+}
+
+/** Apply a controlled selection after native form reset without dispatching change. */
+export function writeSelectValue(element: HTMLSelectElement, value: SelectValue): void {
+  const values = new Set((Array.isArray(value) ? value : [value]).map(String));
+  let matched = false;
+  for (const option of element.options) {
+    const selected: boolean = values.has(option.value) && (element.multiple || !matched);
+    option.selected = selected;
+    matched ||= selected;
+  }
+  if (!matched && !element.multiple) element.selectedIndex = -1;
+}

package/vendor/ds/kits/base/src/core/code-block.ts

@@ -0,0 +1,23 @@
+/** Copy exact source; unavailable or denied clipboard access is a recoverable result. */
+export async function copyCodeSource(code: string): Promise<boolean> {
+  try {
+    await navigator.clipboard.writeText(code);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Measure again on content/layout updates; dispose observers with the native adapter. */
+export function observeCodeOverflow(element: HTMLPreElement, changed: (overflowing: boolean) => void): () => void {
+  const measure = () => changed(element.scrollWidth > element.clientWidth || element.scrollHeight > element.clientHeight);
+  measure();
+  if (typeof ResizeObserver === "undefined") {
+    window.addEventListener("resize", measure);
+    return () => window.removeEventListener("resize", measure);
+  }
+  const observer = new ResizeObserver(measure);
+  observer.observe(element);
+  if (element.firstElementChild) observer.observe(element.firstElementChild);
+  return () => observer.disconnect();
+}

package/vendor/ds/kits/base/src/core/confirmation.ts

@@ -0,0 +1,24 @@
+/** A confirmation belongs to one overlay session; stale work cannot close a reopened session. */
+export function createConfirmationSession(changed: (pending: boolean) => void) {
+  let generation = 0, pending = false;
+  return {
+    reset() { generation++; pending = false; changed(false); },
+    confirm(action: () => unknown | Promise<unknown>, commit: () => void): void | Promise<void> {
+      if (pending) return;
+      const ticket = ++generation;
+      pending = true; changed(true);
+      const finish = (accepted: boolean) => {
+        if (ticket !== generation) return;
+        pending = false; changed(false);
+        if (accepted) commit();
+      };
+      try {
+        const result = action();
+        if (result && typeof (result as PromiseLike<unknown>).then === "function") {
+          return Promise.resolve(result).then(() => finish(true), () => finish(false));
+        }
+        finish(true);
+      } catch { finish(false); }
+    },
+  };
+}

package/vendor/ds/kits/base/src/core/contracts/accordion.ts

@@ -0,0 +1,28 @@
+import type { AccordionItem } from "../../accordion.variants";
+
+/** Canonical portable Accordion properties, shared by native adapters. */
+export interface AccordionContract {
+/** Accessible name for the collection of sections. */
+    label: string;
+/**
+     * The sections, in order: each has a unique `value`, a visible `label` and an optional
+     * `disabled` flag.
+     */
+    items: readonly AccordionItem[];
+/** Expanded item values, bindable (ADR 0026). Single mode retains at most one value. */
+    value?: string[];
+/**
+     * Lets several sections stay open at once. When omitted, opening a section closes the previous
+     * one.
+     */
+    multiple?: boolean;
+/**
+     * Disables the whole Accordion so no section can be toggled; one section is disabled through
+     * its own item.
+     */
+    disabled?: boolean;
+/** Extra classes merged onto every section's trigger Button. */
+    triggerClass?: string;
+/** Extra classes merged onto every section's content region. */
+    contentClass?: string;
+}

package/vendor/ds/kits/base/src/core/contracts/carousel.ts

@@ -0,0 +1,23 @@
+
+/** Shared canonical Carousel properties. */
+export interface CarouselContract {
+/** Accessible name for the carousel region. */
+    label: string;
+/** Initially selected zero-based slide index. */
+    initialIndex?: number;
+/** Opt-in automatic rotation, suspended under reduced motion. A pause/resume control is always rendered when enabled. */
+    autoplay?: boolean;
+/** Milliseconds between automatic selections. */
+    interval?: number;
+/**
+     * The slide shown first holds the page's Largest Contentful Paint: its `image` is fetched
+     * eagerly at high priority. Every other slide image stays lazy.
+     */
+    priority?: boolean;
+/** Extra classes merged onto the viewport that wraps the slides. */
+    viewportClass?: string;
+/** Extra classes merged onto each slide's group element. */
+    slideClass?: string;
+/** Extra classes merged onto the row holding the previous, next and rotation controls. */
+    controlsClass?: string;
+}

package/vendor/ds/kits/base/src/core/contracts/combobox.ts

@@ -0,0 +1,35 @@
+import type { ComboboxOption, ComboboxSize } from "../../combobox.variants";
+
+/** Canonical portable Combobox properties, shared by native adapters. */
+export interface ComboboxContract {
+/** Visible Field label for the typeahead input. */
+    label: string;
+/** Caller-owned selectable values and their searchable labels. */
+    options: readonly ComboboxOption[];
+/** Native form name applied to the selected value. */
+    name?: string;
+/** Selected option value. */
+    value?: string;
+/** Current text in the typeahead input. */
+    inputValue?: string;
+/** Supporting text announced with the input. */
+    help?: string;
+/** Current validation error announced with the input. */
+    error?: string;
+/** Marks the input as required: the label shows it and the native control enforces it. */
+    required?: boolean;
+/** Disables the input and the listbox, so nothing can be typed or chosen. */
+    disabled?: boolean;
+/** Hint text shown in the input while it is empty. */
+    placeholder?: string;
+/** Whether the anchored listbox is open. */
+    open?: boolean;
+/** The control height step, matching Button's `size` (default `md`). */
+    controlSize?: ComboboxSize;
+/** Extra classes merged onto the typeahead input. */
+    inputClass?: string;
+/** Extra classes merged onto the anchored listbox surface. */
+    contentClass?: string;
+/** Extra classes merged onto every option row. */
+    itemClass?: string;
+}

package/vendor/ds/kits/base/src/core/contracts/datefield.ts

@@ -0,0 +1,23 @@
+
+
+/** Canonical portable DateField properties, shared by native adapters. */
+export interface DateFieldContract {
+/** Visible label text owned by the caller. */
+    label: string;
+/** Native form name receiving a complete, possible date. */
+    name?: string;
+/** Complete ISO calendar date. */
+    value?: string;
+/** Supporting text associated with every segment. */
+    help?: string;
+/** Current validation error associated with every segment. */
+    error?: string;
+/** Applies native required validation to every segment. */
+    required?: boolean;
+/** Disables every native segment. */
+    disabled?: boolean;
+/** Explicit id for the year segment. */
+    id?: string;
+/** Extra classes merged onto every native segment. */
+    segmentClass?: string;
+}

package/vendor/ds/kits/base/src/core/contracts/datepicker.ts

@@ -0,0 +1,62 @@
+type Side = "top" | "right" | "bottom" | "left";
+type Align = "start" | "center" | "end";
+import type { DateValue } from "@internationalized/date";
+
+/** Canonical portable DatePicker properties, shared by native adapters. */
+export interface DatePickerContract {
+/** Visible DateField label. */
+    label: string;
+/** Accessible name for the Calendar grid and Popover dialog. */
+    calendarLabel: string;
+/** Accessible name for the canonical Button that opens the calendar. */
+    triggerLabel?: string;
+/** Native form name receiving the synchronized complete date. */
+    name?: string;
+/** Complete ISO calendar date shared by DateField and Calendar. */
+    value?: string;
+/** Supporting text associated with every date segment. */
+    help?: string;
+/** Current validation error associated with every date segment. */
+    error?: string;
+/** Applies native required validation to every date segment and marks the label as required. */
+    required?: boolean;
+/** Disables the date segments, the trigger Button and the Calendar. */
+    disabled?: boolean;
+/** Explicit id for the year segment. A generated one is used when omitted. */
+    id?: string;
+/** Whether the calendar Popover is open. */
+    open?: boolean;
+/** Calendar month shown when no value is selected. */
+    placeholder?: DateValue;
+/** Earliest date the Calendar lets the user select. */
+    minValue?: DateValue;
+/** Latest date the Calendar lets the user select. */
+    maxValue?: DateValue;
+/** Called with each date; return `true` to show it in the Calendar but make it unselectable. */
+    isDateUnavailable?: (date: DateValue) => boolean;
+/**
+     * Preferred side of the trigger for the Popover; collision handling may flip it. Defaults to
+     * `bottom`.
+     */
+    side?: Side;
+/** Preferred alignment of the Popover along the selected side. Defaults to `start`. */
+    align?: Align;
+/** Distance in pixels between the trigger and the Popover. Defaults to `8`. */
+    sideOffset?: number;
+/** Safe distance in pixels kept between the Popover and the viewport edges. Defaults to `8`. */
+    collisionPadding?: number;
+/** Extra classes merged onto the DateField root. */
+    fieldClass?: string;
+/** Extra classes merged onto each native date segment. */
+    segmentClass?: string;
+/** Extra classes merged onto the Button that opens the calendar. */
+    triggerClass?: string;
+/** Extra classes merged onto the Popover surface that holds the Calendar. */
+    contentClass?: string;
+/** Extra classes merged onto the Calendar root. */
+    calendarClass?: string;
+/** Extra classes merged onto the Calendar's previous-month and next-month Buttons. */
+    navigationClass?: string;
+/** Extra classes merged onto each day button in the Calendar. */
+    dayClass?: string;
+}

package/vendor/ds/kits/base/src/core/contracts/daterangefield.ts

@@ -0,0 +1,33 @@
+
+
+/** Canonical portable DateRangeField properties, shared by native adapters. */
+export interface DateRangeFieldContract {
+/** Visible legend naming the related bounds. */
+    label: string;
+/** Visible label for the first DateField. */
+    startLabel: string;
+/** Visible label for the second DateField. */
+    endLabel: string;
+/** Native form name receiving the ordered start value. */
+    startName?: string;
+/** Native form name receiving the ordered end value. */
+    endName?: string;
+/** Complete start calendar date. */
+    startValue?: string;
+/** Complete end calendar date. */
+    endValue?: string;
+/** Supporting text associated with the complete range. */
+    help?: string;
+/** Caller-owned message used when the end precedes the start. */
+    rangeError?: string;
+/** Applies native required validation to every segment. */
+    required?: boolean;
+/** Disables the native group and both composed fields. */
+    disabled?: boolean;
+/** Explicit id prefix for group associations and both fields. */
+    id?: string;
+/** Extra classes merged onto each DateField root. */
+    fieldClass?: string;
+/** Extra classes merged onto all six date segments. */
+    segmentClass?: string;
+}