@reddb-io/ui-kit 0.3.3 → 0.3.5

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

@@ -0,0 +1,88 @@
+type Side = "top" | "right" | "bottom" | "left";
+type Align = "start" | "center" | "end";
+import type { DateValue } from "@internationalized/date";
+
+/** Canonical portable DateRangePicker properties, shared by native adapters. */
+export interface DateRangePickerContract {
+/** Visible legend naming the related DateFields. */
+    label: string;
+/** Visible label for the start DateField. */
+    startLabel: string;
+/** Visible label for the end DateField. */
+    endLabel: string;
+/** Accessible name for the RangeCalendar grid and Popover dialog. */
+    calendarLabel: string;
+/**
+     * Accessible name for the Button that opens the calendar. Defaults to `Choose` followed by
+     * `label`.
+     */
+    triggerLabel?: string;
+/** Native form name receiving the start date. */
+    startName?: string;
+/**
+     * Native form name receiving the end date; it is not submitted while the end precedes the
+     * start.
+     */
+    endName?: string;
+/** Complete ISO bounds shared by DateRangeField and RangeCalendar. */
+    startValue?: string;
+/** Complete ISO end date, bindable, shared with `startValue` by the field and the calendar. */
+    endValue?: string;
+/** Supporting text associated with the complete range. */
+    help?: string;
+/**
+     * Message announced when the end precedes the start. Defaults to `End date cannot be before
+     * start date.`
+     */
+    rangeError?: string;
+/** Applies native required validation to every segment of both date fields. */
+    required?: boolean;
+/** Disables both date fields, the trigger Button and the RangeCalendar. */
+    disabled?: boolean;
+/**
+     * Explicit id prefix for the group associations and both date fields. A generated one is used
+     * when omitted.
+     */
+    id?: string;
+/** Whether the calendar Popover is open, bindable. Defaults to closed. */
+    open?: boolean;
+/** Calendar month shown when no range is selected. Defaults to the month of `startValue`. */
+    placeholder?: DateValue;
+/** Earliest date the RangeCalendar lets the user select. */
+    minValue?: DateValue;
+/** Latest date the RangeCalendar lets the user select. */
+    maxValue?: DateValue;
+/** Fewest days a selected range may span. */
+    minDays?: number;
+/** Most days a selected range may span. */
+    maxDays?: number;
+/** 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 DateRangeField's Fieldset root. */
+    fieldClass?: string;
+/** Extra classes merged onto each of the two DateField roots. */
+    dateFieldClass?: string;
+/** Extra classes merged onto all six native date segments. */
+    segmentClass?: string;
+/** Extra classes merged onto the Button that opens the calendar. */
+    triggerClass?: string;
+/** Extra classes merged onto the Popover surface that holds the RangeCalendar. */
+    contentClass?: string;
+/** Extra classes merged onto the RangeCalendar 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/dialog.ts

@@ -0,0 +1,24 @@
+import type { DialogSize } from "../../dialog.variants";
+
+/** Canonical portable Dialog properties, shared by native adapters. */
+export interface DialogContract {
+/**
+     * Accessible name for the DS-owned trigger. Omit it to render no trigger
+     * and open the Dialog through `bind:open` instead.
+     */
+    triggerLabel?: string;
+/** Visible Dialog title and its accessible name. */
+    title: string;
+/** Optional visible detail associated with the Dialog. */
+    description?: string;
+/** Where focus enters when the Dialog opens. Defaults to its body. */
+    initialFocus?: "body" | "actions";
+/** Whether to render the standard close control. Defaults to true. */
+    showClose?: boolean;
+/** Whether the Dialog is open. Bindable; defaults to closed. */
+    open?: boolean;
+/** Whether a click outside the surface dismisses it. Defaults to true. */
+    dismissible?: boolean;
+/** Maximum inline size of the surface. Defaults to `md`. */
+    size?: DialogSize;
+}

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

@@ -0,0 +1,15 @@
+
+
+/** Canonical portable Disclosure properties, shared by native adapters. */
+export interface DisclosureContract {
+/** Visible text of the trigger Button that toggles the region. */
+    label: string;
+/** Whether the region is expanded, bindable. Defaults to closed. */
+    open?: boolean;
+/** Disables the trigger, so the region cannot be toggled. */
+    disabled?: boolean;
+/** Extra classes merged onto the trigger Button. */
+    triggerClass?: string;
+/** Extra classes merged onto the expandable region. */
+    contentClass?: string;
+}

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

@@ -0,0 +1,29 @@
+type Side = "top" | "right" | "bottom" | "left";
+type Align = "start" | "center" | "end";
+
+
+/** Canonical portable LinkPreview properties, shared by native adapters. */
+export interface LinkPreviewContract {
+/** Native destination retained whether or not the preview is available. */
+    href: string;
+/** Visible fallback link text. */
+    label: string;
+/** Accessible name for the preview dialog. */
+    previewLabel: string;
+/** Whether the preview is open. Bindable for controlled consumers. */
+    open?: boolean;
+/** Delay before keyboard focus or pointer hover opens the preview. */
+    openDelay?: number;
+/** Delay before leaving the trigger and preview closes it. */
+    closeDelay?: number;
+/** Preferred side of the link; collision handling may flip it. */
+    side?: Side;
+/** Preferred alignment along the selected side. */
+    align?: Align;
+/** Distance from the link in pixels. */
+    sideOffset?: number;
+/** Safe distance from viewport collision edges in pixels. */
+    collisionPadding?: number;
+/** Optional classes for the native link itself. */
+    triggerClass?: string;
+}

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

@@ -0,0 +1,30 @@
+import type { NavbarLink, NavbarCollapse, NavbarAlign } from "../navbar";
+
+/** Shared canonical Navbar properties. */
+export interface NavbarContract {
+/**
+     * The destinations, in order; shown in the rail and repeated in the compact menu panel. Each
+     * entry with an `href` renders a link, one without renders a ghost Button that calls its
+     * `onselect`.
+     */
+    links?: readonly NavbarLink[];
+/**
+     * How the bar arranges itself: `responsive` follows the bar's own width, `expanded` always
+     * shows the rail, `collapsed` always shows the compact menu. Defaults to `responsive`.
+     */
+    collapse?: NavbarCollapse;
+/**
+     * Where the links sit between the brand and the actions: `start` keeps them beside the brand,
+     * `center` centers them. Defaults to `start`.
+     */
+    align?: NavbarAlign;
+/**
+     * Whether the compact menu panel is open; bindable. Escape closes it and returns focus to the
+     * menu button.
+     */
+    open?: boolean;
+/** Accessible name of the navigation landmark; defaults to `Main`. */
+    label?: string;
+/** Text and accessible name of the button that opens the compact menu; defaults to `Menu`. */
+    menuLabel?: string;
+}

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

@@ -0,0 +1,35 @@
+import type { NavigationMenuEntry } from "../../navigation-menu.behavior";
+import type { NavigationMenuOrientation, NavigationMenuSize } from "../../navigation-menu.variants";
+
+/** Shared canonical NavigationMenu properties. */
+export interface NavigationMenuContract {
+/** Accessible name of the navigation landmark. */
+    label: string;
+/**
+     * The top-level entries: a link with an `href` renders a direct destination, one with `links`
+     * renders a trigger that opens a surface of links. Defaults to none.
+     */
+    items?: readonly NavigationMenuEntry[];
+/** The `id` of the section whose links are open, or an empty string when none is; bindable. */
+    value?: string;
+/**
+     * Direction the entries run: `horizontal` in a row, `vertical` in a column. Defaults to
+     * `horizontal`.
+     */
+    orientation?: NavigationMenuOrientation;
+/**
+     * Size of the top-level controls, following the Density control heights: `sm`, `md` or `lg`.
+     * Defaults to `md`.
+     */
+    size?: NavigationMenuSize;
+/**
+     * Milliseconds from the pointer entering a trigger until its content opens, as Bits UI
+     * defines it; defaults to `200`.
+     */
+    delayDuration?: number;
+/**
+     * Milliseconds in which moving to another trigger skips the open delay again, as Bits UI
+     * defines it; defaults to `300`.
+     */
+    skipDelayDuration?: number;
+}

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

@@ -0,0 +1,55 @@
+import type { CountryCode } from "libphonenumber-js/min";
+import type { InputSize } from "../../input.variants";
+/** Geographic country/territory supported by the pinned telephone metadata. */
+export type PhoneCountry = CountryCode;
+/** Framework-independent telephone field contract. */
+export interface PhoneInputContract {
+  /** Visible label associated with the national-number input. */
+  label: string;
+  /** International unmasked value: + followed by digits, or an empty string. Partial edits remain drafts until native validation succeeds. */
+  value?: string;
+  /** Initial uncontrolled international value, restored by form reset. */
+  defaultValue?: string;
+  /** Starting country for empty/national values. International values infer their country. Defaults to US. */
+  defaultCountry?: PhoneCountry;
+  /** Allowed geographic countries. Omitted means every country in the pinned metadata. */
+  countries?: readonly PhoneCountry[];
+  /** Locale used for country names and sorting; defaults to en. */
+  locale?: string;
+  /** Native form name. Exactly one unmasked international value is submitted. */
+  name?: string;
+  /** Optional external form id shared by the native controls. */
+  form?: string;
+  /** Native telephone input id; generated when omitted. */
+  id?: string;
+  /** Supporting text associated with the telephone input. */
+  help?: string;
+  /** Application error displayed separately from the label. */
+  error?: string;
+  /** Require a complete telephone number before the form can submit. */
+  required?: boolean;
+  /** Disable editing and omit the value from native form submission. */
+  disabled?: boolean;
+  /** Input by default; text renders a selectable formatted value without an editable control. */
+  presentation?: "input" | "text";
+  /** Optional caller-supplied provenance shown in text presentation. */
+  sourceLabel?: string;
+  /** Text used for an empty value in text presentation. Defaults to No phone number. */
+  emptyLabel?: string;
+  /** Placeholder for the national-number input. */
+  placeholder?: string;
+  /** Autofill token for the national-number control; defaults to tel-national. */
+  autoComplete?: string;
+  /** Prefix for the accessible country selector label, followed by the selected country name. Defaults to Country. */
+  countryLabel?: string;
+  /** Placeholder in the country search. */
+  searchPlaceholder?: string;
+  /** Message for a country search with no results. */
+  emptyText?: string;
+  /** Message when a required field is empty. */
+  requiredMessage?: string;
+  /** Message for an incomplete number or a country outside the allowed list. Metadata checks structure/length, not ownership. */
+  invalidMessage?: string;
+  /** Shared height for the country selector and national-number input. Defaults to md. */
+  controlSize?: InputSize;
+}

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

@@ -0,0 +1,29 @@
+type Side = "top" | "right" | "bottom" | "left";
+type Align = "start" | "center" | "end";
+import type { ButtonSize, ButtonVariant } from "../../button.variants";
+
+/** Canonical portable Popover properties, shared by native adapters. */
+export interface PopoverContract {
+/** Accessible name for the Button that opens the Popover. */
+    triggerLabel: string;
+/** Accessible name for the opened non-modal dialog. */
+    contentLabel: string;
+/** Whether the Popover is open. Bindable for controlled consumers. */
+    open?: boolean;
+/** Disables the canonical trigger Button. */
+    disabled?: boolean;
+/** Button emphasis for the trigger. */
+    variant?: ButtonVariant;
+/** Button size for the trigger. */
+    size?: ButtonSize;
+/** Preferred side of the trigger; collision handling may flip it. */
+    side?: Side;
+/** Preferred alignment along the selected side. */
+    align?: Align;
+/** Distance from the trigger in pixels. */
+    sideOffset?: number;
+/** Safe distance from viewport collision edges in pixels. */
+    collisionPadding?: number;
+/** Extra classes merged onto the canonical trigger Button. */
+    triggerClass?: string;
+}

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

@@ -0,0 +1,38 @@
+import type { SearchSelectOption } from "../../search-select.variants";
+import type { InputSize } from "../../input.variants";
+
+/** Shared canonical SearchSelect properties. */
+export interface SearchSelectContract {
+/** Visible field label, also announced with the invoking control. */
+    label: string;
+/** Caller-owned choices with optional descriptions, search aliases and disabled states. */
+    options: readonly SearchSelectOption[];
+/** Native form name; multiple selection submits one entry per selected value. */
+    name?: string;
+/** Supporting text associated with the invoking control. */
+    help?: string;
+/** Validation error associated with the invoking control. */
+    error?: string;
+/** Enforces at least one selected value through native form validation. */
+    required?: boolean;
+/** Disables selection, clearing and chip removal, and excludes the value from form submission. */
+    disabled?: boolean;
+/** Text shown when the selection is empty. Defaults to Choose an option. */
+    placeholder?: string;
+/** Hint inside the search input. Defaults to Search options. */
+    searchPlaceholder?: string;
+/** Message shown when the query matches no choices. */
+    emptyText?: string;
+/** Validation message shown after a required empty field blocks form submission. */
+    requiredMessage?: string;
+/** Allows clearing the entire selection. Defaults to true. */
+    clearable?: boolean;
+/** Whether the searchable Popover is open. */
+    open?: boolean;
+/** Control height shared with Input and Button; defaults to md. */
+    controlSize?: InputSize;
+/** Extra classes merged onto the invoking Button. */
+    triggerClass?: string;
+/** Extra classes merged onto the Popover surface. */
+    contentClass?: string;
+}

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

@@ -0,0 +1,26 @@
+import type { TabItem } from "../../tabs.variants";
+
+/** Canonical portable Tabs properties, shared by native adapters. */
+export interface TabsContract {
+/** Accessible name for the tablist. */
+    label: string;
+/** Stable values and visible labels; panel content remains caller-owned. */
+    items: readonly TabItem[];
+/** Selected tab value; defaults to the first enabled tab. */
+    value?: string;
+/**
+     * Axis of the tablist, which sets `aria-orientation` and the arrow keys that move between
+     * tabs. Defaults to `horizontal`.
+     */
+    orientation?: "horizontal" | "vertical";
+/** Disables every tab, so none can be selected. */
+    disabled?: boolean;
+/** Select the panel containing a same-page fragment target. */
+    followHash?: boolean;
+/** Extra classes merged onto the tablist. */
+    listClass?: string;
+/** Extra classes merged onto every tab trigger Button. */
+    triggerClass?: string;
+/** Extra classes merged onto every tab panel. */
+    contentClass?: string;
+}

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

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

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

@@ -0,0 +1,33 @@
+
+
+/** Canonical portable TimeRangeField properties, shared by native adapters. */
+export interface TimeRangeFieldContract {
+/** Visible legend naming the related bounds. */
+    label: string;
+/** Visible label for the first TimeField. */
+    startLabel: string;
+/** Visible label for the second TimeField. */
+    endLabel: string;
+/** Native form name receiving the ordered start value. */
+    startName?: string;
+/** Native form name receiving the ordered end value. */
+    endName?: string;
+/** Complete start clock value. */
+    startValue?: string;
+/** Complete end clock value. */
+    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 TimeField root. */
+    fieldClass?: string;
+/** Extra classes merged onto all four time segments. */
+    segmentClass?: string;
+}

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

@@ -0,0 +1,12 @@
+
+
+/** Canonical portable Tooltip properties, shared by native adapters. */
+export interface TooltipContract {
+/**
+     * Accessible name of the DS-rendered trigger; it remains complete when the
+     * Tooltip is unavailable. Required unless `child` supplies the trigger.
+     */
+    label?: string;
+/** Supplemental description shown by the Tooltip. */
+    content: string;
+}

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

@@ -0,0 +1,13 @@
+/** Presentation of an already committed resource transfer, independent of renderer. */
+export interface TransferContract {
+  /** Source element ID; the source retains its own semantics. */
+  fromId: string;
+  /** Destination element ID; the application commits state before triggering motion. */
+  toId: string;
+  /** Change after a committed transfer; initial render does not animate. */
+  trigger?: string | number;
+  /** Presentation duration in milliseconds, bounded to 1500. */
+  duration?: number;
+  /** Suppress and cancel positional motion. */
+  paused?: boolean;
+}

package/vendor/ds/kits/base/src/core/date-segments.ts

@@ -0,0 +1,18 @@
+/** Parse a complete possible Gregorian date without timezone conversion. */
+export function possibleDate(candidate: string): RegExpMatchArray | null {
+  const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(candidate);
+  if (!match) return null;
+  const year = Number(match[1]), month = Number(match[2]), day = Number(match[3]);
+  if (year === 0 || month < 1 || month > 12) return null;
+  const leap = year % 4 === 0 && (year % 100 !== 0 || year % 400 === 0);
+  const days = [31, leap ? 29 : 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
+  return day >= 1 && day <= days[month - 1]! ? match : null;
+}
+export function possibleTime(candidate: string): RegExpMatchArray | null { return /^([01]\d|2[0-3]):([0-5]\d)$/.exec(candidate); }
+export type DateSegment = "year" | "month" | "day" | "hour" | "minute";
+export function segmentDigits(value: string, segment: DateSegment): string {
+  const length = segment === "year" ? 4 : 2, digits = value.replace(/\D/g, "").slice(0, length), number = Number(digits);
+  const limits: Record<DateSegment, readonly [number, number]> = { year: [1, 9999], month: [1, 12], day: [1, 31], hour: [0, 23], minute: [0, 59] };
+  const [min, max] = limits[segment];
+  return digits.length === length && (number < min || number > max) ? "" : digits;
+}

package/vendor/ds/kits/base/src/core/description-list.ts

@@ -0,0 +1,5 @@
+/** A term/detail association; each renderer supplies its native content type. */
+export interface DescriptionListEntry<Content> {
+  term: Content;
+  detail: Content;
+}

package/vendor/ds/kits/base/src/core/dropdown-menu.ts

@@ -0,0 +1,55 @@
+
+/** One selectable row in a DropdownMenu. */
+export interface DropdownMenuItem<Glyph = unknown> {
+  id: string;
+  label: string;
+  /** Optional decorative glyph rendered before the label through the DS Icon contract. */
+  icon?: Glyph;
+  /** A keyboard shortcut rendered as semantic key caps after the label. */
+  shortcut?: readonly string[];
+  href?: string;
+  disabled?: boolean;
+  onselect?: () => void;
+}
+
+/** A named or unnamed run of related menu rows. */
+export interface DropdownMenuGroup<Glyph = unknown> {
+  heading?: string;
+  items: readonly DropdownMenuItem<Glyph>[];
+}
+
+export type DropdownMenuEntry<Glyph = unknown> = DropdownMenuItem<Glyph> | DropdownMenuGroup<Glyph>;
+
+export function isDropdownMenuGroup<Glyph>(entry: DropdownMenuEntry<Glyph>): entry is DropdownMenuGroup<Glyph> {
+  return Array.isArray((entry as DropdownMenuGroup<Glyph>).items);
+}
+
+/** Fold consecutive bare rows into groups while retaining explicit group boundaries. */
+export function dropdownMenuGroups<Glyph>(
+  entries: readonly DropdownMenuEntry<Glyph>[],
+): readonly DropdownMenuGroup<Glyph>[] {
+  const groups: DropdownMenuGroup<Glyph>[] = [];
+  let run: DropdownMenuItem<Glyph>[] | undefined;
+
+  for (const entry of entries) {
+    if (isDropdownMenuGroup(entry)) {
+      run = undefined;
+      if (entry.items.length > 0) groups.push(entry);
+      continue;
+    }
+    if (run === undefined) {
+      run = [];
+      groups.push({ items: run });
+    }
+    run.push(entry);
+  }
+
+  return groups;
+}
+
+/** Flatten grouped entries back into their source-order menu rows. */
+export function dropdownMenuItems<Glyph>(
+  entries: readonly DropdownMenuEntry<Glyph>[],
+): readonly DropdownMenuItem<Glyph>[] {
+  return dropdownMenuGroups(entries).flatMap((group) => [...group.items]);
+}

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

@@ -0,0 +1,5 @@
+import type { Tone } from "../tone";
+/** Resolve the canonical tone before translating it into announcement urgency. */
+export function feedbackTone(tone?: Tone, legacy?: Tone): Tone { return tone ?? legacy ?? "neutral"; }
+/** Errors interrupt; other feedback is a polite status update. */
+export function feedbackAnnouncement(tone: Tone): "alert" | "status" { return tone === "danger" ? "alert" : "status"; }

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

@@ -0,0 +1,57 @@
+/** Field's layout vocabulary is shared by every renderer. */
+export const FIELD_LAYOUTS = ["stacked", "inline"] as const;
+export type FieldLayout = (typeof FIELD_LAYOUTS)[number];
+
+/** Semantic Field props; class, children and id generation belong to adapters. */
+export interface FieldContractProps {
+  /** Visible label text. */
+  label: string;
+  /** Supporting text announced with the control. */
+  help?: string;
+  /** Current validation error, announced and associated with the control. */
+  error?: string;
+  /** Makes the requirement visible and native. */
+  required?: boolean;
+  /** Explicit control id; otherwise the renderer supplies a stable generated one. */
+  id?: string;
+  /** Label placement: stacked above the control, or inline beside a binary choice. */
+  layout?: FieldLayout;
+}
+
+/** The framework-neutral association passed by Field to its control. */
+export interface FieldControlProps {
+  /** The id the label targets. */
+  id: string;
+  /** Native required semantics, when the Field declares them. */
+  required?: true;
+  /** Space-separated help and error ids. */
+  "aria-describedby"?: string;
+  /** Present only while the Field has an error. */
+  "aria-invalid"?: "true";
+  /** The Field's current error id. */
+  "aria-errormessage"?: string;
+}
+
+export interface FieldAssociationOptions {
+  /** Framework-generated or application-supplied stable control id. */
+  id: string;
+  /** Supporting text, if present. */
+  help?: string;
+  /** Validation error, if present. */
+  error?: string;
+  /** Whether the native control is required. */
+  required?: boolean;
+}
+
+/** Pure association logic; frameworks own id generation and reactive updates. */
+export function fieldAssociation({ id, help, error, required }: FieldAssociationOptions) {
+  const helpId = `${id}-help`;
+  const errorId = `${id}-error`;
+  const control: FieldControlProps = {
+    id, required: required || undefined,
+    "aria-describedby": [help ? helpId : undefined, error ? errorId : undefined].filter(Boolean).join(" ") || undefined,
+    "aria-invalid": error ? "true" : undefined,
+    "aria-errormessage": error ? errorId : undefined,
+  };
+  return { control, helpId, errorId };
+}

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

@@ -0,0 +1,10 @@
+import { fieldAssociation, type FieldControlProps } from "./field";
+
+/** A group association leaves every native control's id and requirement intact. */
+export type FieldsetControlProps = Omit<FieldControlProps, "id" | "required">;
+
+/** Group help/error links use the same normalization as a single Field. */
+export function fieldsetAssociation(options: { id: string; help?: string; error?: string }) {
+  const { control: { id, required, ...control }, helpId, errorId } = fieldAssociation(options);
+  return { control, helpId, errorId };
+}

package/vendor/ds/kits/base/src/core/focus-scope.ts

@@ -0,0 +1,27 @@
+import { modalFocusable } from "./modal";
+/** Keep boundary Tab moves inside a popup mounted in a native modal's top layer.
+ * Native dialogs can intercept the headless engine's off-surface focus guards.
+ * The innermost scope alone owns this boundary; ordinary moves stay native.
+ */
+export function trapScopeTab(scope: HTMLElement): () => void {
+  const keydown = (event: KeyboardEvent) => {
+    if (event.defaultPrevented || event.key !== "Tab" || !(event.target instanceof Element) || event.target.closest("[data-ds-focus-scope]") !== scope) return;
+    const nodes = [...scope.querySelectorAll<HTMLElement>(modalFocusable)].filter(element => !element.closest("[hidden],[inert]") && !element.matches(":disabled") && element.tabIndex >= 0 && getComputedStyle(element).display !== "none");
+    const first = nodes[0], last = nodes.at(-1);
+    if (!first || !last) { event.preventDefault(); scope.focus(); }
+    else if (event.shiftKey && document.activeElement === first) { event.preventDefault(); last.focus(); }
+    else if (!event.shiftKey && document.activeElement === last) { event.preventDefault(); first.focus(); }
+  };
+  scope.addEventListener("keydown", keydown, true);
+  return () => scope.removeEventListener("keydown", keydown, true);
+}
+
+/** A consumer may deliberately focus its next field while a popup closes.
+ * Restore the trigger only when focus still belongs to the popup or was lost.
+ */
+export function focusMovedOutside(anchor: HTMLElement | undefined, popupSelector: string): boolean {
+  const document = anchor?.ownerDocument;
+  const active = document?.activeElement;
+  return !!active && active !== document?.body && active !== document?.documentElement &&
+    !anchor?.contains(active) && !active.closest(popupSelector);
+}