@reddb-io/ui 0.3.3 → 0.3.5

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

@@ -0,0 +1,15 @@
+/** Density-owned icon sizes shared by native adapters. */
+export const ICON_SIZES = ["sm", "md", "lg"] as const;
+export type IconSize = (typeof ICON_SIZES)[number];
+/** Semantic ink roles accepted by Icon. */
+export const ICON_COLORS = ["current", "foreground", "ink-muted", "primary", "on-primary", "feedback-danger-foreground", "feedback-success-foreground", "feedback-warning-foreground", "feedback-info-foreground"] as const;
+export type IconColor = (typeof ICON_COLORS)[number];
+/** @deprecated Use ink-muted; muted is a surface role. */
+export type DeprecatedIconColor = "muted";
+/** Resolve a semantic role, including the retained deprecated alias. */
+export function iconColor(color: IconColor | DeprecatedIconColor): string {
+  const role = color === "muted" ? "ink-muted" : color;
+  return role === "current" ? "currentColor" : `var(--reddb-color-${role})`;
+}
+/** Density controls glyph dimensions independently of the control hit area. */
+export function iconDimension(size: IconSize): string { return `var(--reddb-spatial-icon-size-${size})`; }

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

@@ -0,0 +1,2 @@
+export { fieldAssociation, FIELD_LAYOUTS, type FieldLayout, type FieldContractProps, type FieldControlProps, type FieldAssociationOptions } from "./field";
+export { inputValue, type InputValue } from "./input";

package/vendor/ds/kits/base/src/core/inline-edit.ts

@@ -0,0 +1,86 @@
+/** Portable field semantics shared by the native InlineEdit adapters. */
+export interface InlineEditContract {
+  /** Visible field name, also used to name its edit and input controls. */
+  label: string;
+  /** Read layout: compact text by default, or a full-width saved value that becomes an input only while editing. */
+  presentation?: "text" | "input";
+  /** Whether the edit action is always visible or revealed by hover/focus. Touch always shows it. */
+  editVisibility?: "always" | "hover";
+  /** Caller-supplied provenance, such as API, imported file or organization defaults. Never inferred. */
+  sourceLabel?: string;
+  /** Visible committed-state label in input presentation. Defaults to Saved. */
+  savedLabel?: string;
+  /** Native string input type while editing. Password values are masked in the read view. Defaults to text. */
+  inputType?: "text" | "password" | "email" | "url" | "tel";
+  /** Committed text. Draft keystrokes never change this value. */
+  value: string;
+  /** Whether the draft editor is open; caller-owned in controlled React use. */
+  editing?: boolean;
+  /** Initial uncontrolled editor state; later changes do not replace the user's choice. */
+  defaultEditing?: boolean;
+  /** Optional application validation; return an error to retain the draft. */
+  validate?: (value: string) => string | undefined;
+  /** Prevents opening or submitting the editor. */
+  disabled?: boolean;
+  /** Requires at least one non-whitespace character. Defaults to true. */
+  required?: boolean;
+  /** Optional maximum number of characters accepted by the native input. */
+  maxlength?: number;
+  /** Visible text when the committed value is empty. */
+  emptyLabel?: string;
+  /** Label of the action that opens the editor. */
+  editLabel?: string;
+  /** Label of the action that persists the draft. */
+  saveLabel?: string;
+  /** Label of the action that discards the draft. */
+  cancelLabel?: string;
+  /** Validation message for a required empty draft. */
+  requiredMessage?: string;
+  /** Message announced when persistence rejects. */
+  saveErrorMessage?: string;
+}
+
+export interface InlineEditState { draft: string; error: string; saving: boolean }
+export interface InlineEditSaveOptions {
+  required: boolean;
+  requiredMessage: string;
+  saveErrorMessage: string;
+  validate?: (value: string) => string | undefined;
+  confirm?: (value: string) => void | Promise<void>;
+}
+export type InlineEditResult = { status: "committed"; value: string } | { status: "invalid" | "failed" | "busy" | "stale" };
+
+/** A draft transaction; invalidated confirmations cannot commit a later editing session. */
+export function createInlineEditSession(value: string, changed: (state: InlineEditState) => void) {
+  let state: InlineEditState = { draft: value, error: "", saving: false };
+  let generation = 0;
+  const publish = (next: InlineEditState) => { state = next; changed(state); };
+  return {
+    get state() { return state; },
+    invalidate() { generation++; },
+    reset(value: string) { generation++; publish({ draft: value, error: "", saving: false }); },
+    change(draft: string) { if (!state.saving) publish({ ...state, draft, error: "" }); },
+    async save(options: InlineEditSaveOptions): Promise<InlineEditResult> {
+      if (state.saving) return { status: "busy" };
+      const candidate = state.draft;
+      const error = options.required && !candidate.trim() ? options.requiredMessage : options.validate?.(candidate) ?? "";
+      if (error) { publish({ ...state, error }); return { status: "invalid" }; }
+      const ticket = ++generation;
+      publish({ ...state, saving: true, error: "" });
+      try { await options.confirm?.(candidate); }
+      catch {
+        if (ticket !== generation) return { status: "stale" };
+        publish({ ...state, error: options.saveErrorMessage, saving: false });
+        return { status: "failed" };
+      }
+      if (ticket !== generation) return { status: "stale" };
+      publish({ ...state, saving: false });
+      return { status: "committed", value: candidate };
+    },
+  };
+}
+
+/** Read mode is selectable text; password values never enter the read DOM. */
+export function inlineEditReadValue(value: string, inputType: InlineEditContract["inputType"], emptyLabel: string): string {
+  return value ? (inputType === "password" ? "••••••••" : value) : emptyLabel;
+}

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

@@ -0,0 +1,9 @@
+/** The numeric native input types report numbers; an empty number reports null. */
+export type InputValue<Type extends string> = string extends Type ? string | number | null : Type extends "number" | "range" ? number | null : string;
+
+/** Read a platform input without depending on a rendering framework or globals. */
+export function inputValue<Type extends string>(input: { type: Type; value: string; valueAsNumber: number }): InputValue<Type> {
+  return (input.type === "number" || input.type === "range"
+    ? input.value === "" ? null : input.valueAsNumber
+    : input.value) as InputValue<Type>;
+}

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

@@ -0,0 +1,73 @@
+/** Native dialog lifecycle shared by every renderer, including nested scroll locks. */
+const locks = new WeakMap<Document, { count: number; overflow: string }>();
+
+/** A host shell must yield its shortcuts to events originating in a modal, including shadow DOM. */
+export function isEventFromModal(event: Event): boolean {
+  const path = event.composedPath();
+  const targets = path.length ? path : [event.target];
+  return targets.some(target => {
+    const element = target as Element | null;
+    return element?.nodeType === 1 && typeof element.closest === "function" &&
+      element.closest('dialog[open], [role="dialog"][aria-modal="true"], [role="alertdialog"][aria-modal="true"]') !== null;
+  });
+}
+export const modalFocusable = 'button:not([disabled]),a[href],input:not([disabled]),select:not([disabled]),textarea:not([disabled]),[tabindex]:not([tabindex="-1"])';
+export interface ModalOptions {
+  initialFocus(): "body" | "actions";
+  dismissible(): boolean;
+  requestOpen(open: boolean): void;
+}
+export function createModalController(dialog: HTMLDialogElement, options: ModalOptions) {
+  const document = dialog.ownerDocument;
+  let active = false, returnFocus: HTMLElement | null = null;
+  const focusables = () => [...dialog.querySelectorAll<HTMLElement>(modalFocusable)].filter(element => !element.closest('[hidden],[inert]') && !element.matches(":disabled") && element.tabIndex >= 0 && element.closest("dialog") === dialog);
+  function release(close = false) {
+    if (!active) return;
+    active = false;
+    const lock = locks.get(document);
+    if (lock && --lock.count === 0) { document.documentElement.style.overflow = lock.overflow; locks.delete(document); }
+    if (close && dialog.open) { if (typeof dialog.close === "function") dialog.close(); else dialog.removeAttribute("open"); }
+    if (returnFocus?.isConnected) returnFocus.focus();
+    returnFocus = null;
+  }
+  function sync(open: boolean) {
+    if (open && !active) {
+      returnFocus = document.activeElement instanceof HTMLElement ? document.activeElement : null;
+      if (!dialog.open) {
+        if (typeof dialog.showModal === "function") dialog.showModal(); else dialog.setAttribute("open", "");
+      }
+      active = true;
+      const lock = locks.get(document) ?? { count: 0, overflow: document.documentElement.style.overflow };
+      lock.count++; locks.set(document, lock); document.documentElement.style.overflow = "hidden";
+      const region = dialog.querySelector<HTMLElement>(options.initialFocus() === "actions" ? "[data-dialog-actions]" : "[data-dialog-body]");
+      (focusables().find(element => region?.contains(element)) ?? focusables()[0] ?? dialog).focus();
+    } else if (!open && active) {
+      release(true);
+    }
+  }
+  function keydown(event: KeyboardEvent) {
+    if (event.target instanceof Element && event.target.closest("dialog") !== dialog) return;
+    if (event.key !== "Tab") return;
+    if (event.target instanceof Element && event.target.closest("[data-ds-focus-scope]")) return;
+    const nodes = focusables(), first = nodes[0], last = nodes.at(-1);
+    if (!first || !last) { event.preventDefault(); dialog.focus(); }
+    else if (event.shiftKey && document.activeElement === first) { event.preventDefault(); last.focus(); }
+    else if (!event.shiftKey && document.activeElement === last) { event.preventDefault(); first.focus(); }
+  }
+  // Managed popups arbitrate Escape on Document. Listen after them at Window
+  // so one key dismisses only the innermost active layer, including portals.
+  function escape(event: KeyboardEvent) {
+    if (!active || event.defaultPrevented || event.key !== "Escape" || !(event.target instanceof Element) || event.target.closest("dialog") !== dialog) return;
+    event.preventDefault(); event.stopPropagation(); options.requestOpen(false);
+  }
+  function click(event: MouseEvent) {
+    if (!options.dismissible() || event.target !== dialog) return;
+    const box = dialog.getBoundingClientRect();
+    if (event.clientX < box.left || event.clientX > box.right || event.clientY < box.top || event.clientY > box.bottom) options.requestOpen(false);
+  }
+  function cancel(event: Event) { event.preventDefault(); options.requestOpen(false); }
+  function closed() { if (active && !dialog.open) { release(); options.requestOpen(false); } }
+  document.defaultView?.addEventListener("keydown", escape);
+  dialog.addEventListener("keydown", keydown); dialog.addEventListener("click", click); dialog.addEventListener("cancel", cancel); dialog.addEventListener("close", closed);
+  return { sync, destroy() { release(true); document.defaultView?.removeEventListener("keydown", escape); dialog.removeEventListener("keydown", keydown); dialog.removeEventListener("click", click); dialog.removeEventListener("cancel", cancel); dialog.removeEventListener("close", closed); } };
+}

package/vendor/ds/kits/base/src/core/native-controls.ts

@@ -0,0 +1,43 @@
+/** A locked selection reports no change when it is already pressed. */
+export function nextPressed(pressed: boolean, allowUnpress: boolean): boolean {
+  return pressed && !allowUnpress ? pressed : !pressed;
+}
+
+/** Keep a native radio group usable for fractional and non-finite stop counts. */
+export function ratingStops(max: number): number[] {
+  const count = Number.isFinite(max) ? Math.max(1, Math.floor(max)) : 5;
+  return Array.from({ length: count }, (_, index) => index + 1);
+}
+
+/** File feedback never exposes a local filesystem path. */
+export function fileNames(files: FileList | null | undefined): string[] {
+  return Array.from(files ?? [], file => file.name);
+}
+
+/**
+ * A browser may flush microtasks between reset listeners and the default action.
+ * Reconcile in the next task, after native controls and outputs have reset.
+ */
+export function afterFormReset(form: HTMLFormElement | null | undefined, reconcile: () => void): () => void {
+  const pending = new Set<ReturnType<typeof setTimeout>>();
+  const reset = (event: Event) => {
+    const timer = setTimeout(() => {
+      pending.delete(timer);
+      if (!event.defaultPrevented) reconcile();
+    }, 0);
+    pending.add(timer);
+  };
+  form?.addEventListener("reset", reset);
+  return () => {
+    form?.removeEventListener("reset", reset);
+    pending.forEach(timer => clearTimeout(timer));
+  };
+}
+
+/** Resolve explicit form ownership before a child snippet has patched its native attribute. */
+export function associatedForm(control: HTMLInputElement | HTMLFieldSetElement | null | undefined, formId?: string | null): HTMLFormElement | null {
+  if (!control) return null;
+  if (formId == null) return control.form;
+  const owner = control.ownerDocument.getElementById(formId);
+  return owner?.tagName === "FORM" ? owner as HTMLFormElement : null;
+}

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

@@ -0,0 +1,16 @@
+export type NavbarCollapse = "responsive" | "expanded" | "collapsed";
+export type NavbarAlign = "start" | "center";
+export const NAVBAR_ALIGNMENTS = ["start", "center"] as const satisfies readonly NavbarAlign[];
+export const NAVBAR_COLLAPSE = ["responsive", "expanded", "collapsed"] as const satisfies readonly NavbarCollapse[];
+export interface NavbarArrangements { rail: boolean; compact: boolean }
+/** Decide arrangements without consulting viewport state in JavaScript. */
+export function arrangements(collapse: NavbarCollapse): NavbarArrangements { return { rail: collapse !== "collapsed", compact: collapse !== "expanded" }; }
+export interface NavbarLink {
+  id: string;
+  label: string;
+  href?: string;
+  current?: boolean | "page" | "step" | "location" | "date" | "time" | "true";
+  active?: boolean;
+  disabled?: boolean;
+  onselect?: () => void;
+}

package/vendor/ds/kits/base/src/core/navigation-disclosures.ts

@@ -0,0 +1,10 @@
+/** A shell coordinates independent navigation disclosures without choosing any layout. */
+export function createNavigationDisclosures() {
+  const closers = new Set<() => void>();
+  return {
+    register(close: () => void) {
+      closers.add(close);
+      return { open() { for (const other of closers) if (other !== close) other(); }, destroy() { closers.delete(close); } };
+    },
+  };
+}

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

@@ -0,0 +1,48 @@
+/** What a consumer injects to route the links inside a scope. */
+export interface NavigationSeam {
+  /** Activate an in-app destination instead of letting the browser follow it. */
+  navigate: (href: string, event: MouseEvent) => void;
+  /**
+   * Turn a destination into the href a link renders. The Design System never
+   * builds a route itself; this is for the caller composing links in the scope.
+   */
+  resolve?: (to: string) => string;
+  /**
+   * Whether this scope routes `href`. The default takes same-origin paths and
+   * leaves fragments, other origins and non-HTTP schemes to the browser.
+   */
+  owns?: (href: string, anchor: HTMLAnchorElement) => boolean;
+}
+
+/** The default `owns`: a same-origin, non-fragment destination. */
+export function ownsSameOrigin(href: string, anchor: HTMLAnchorElement): boolean {
+  if (href === "" || href.startsWith("#")) return false;
+  const url = new URL(anchor.href, anchor.ownerDocument.baseURI);
+  if (url.protocol !== "http:" && url.protocol !== "https:") return false;
+  return url.origin === new URL(anchor.ownerDocument.baseURI).origin;
+}
+
+/**
+ * The anchor a click activates, when the scope should route it — or `null`
+ * when the browser should keep the activation: a modified or non-primary
+ * click (open in a new tab is the user's call), an already-handled event, a
+ * link that targets another browsing context, a download, or an explicit
+ * `data-native-navigation` opt-out.
+ */
+export function routableAnchor(
+  event: MouseEvent,
+  scope: Element,
+  owns: NonNullable<NavigationSeam["owns"]> = ownsSameOrigin,
+): HTMLAnchorElement | null {
+  if (event.defaultPrevented || event.button !== 0) return null;
+  if (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return null;
+  const target = event.target;
+  if (!(target instanceof Element)) return null;
+  const anchor = target.closest<HTMLAnchorElement>("a[href]");
+  if (!anchor || !scope.contains(anchor)) return null;
+  if (anchor.hasAttribute("download") || anchor.hasAttribute("data-native-navigation")) return null;
+  const targetContext = anchor.getAttribute("target");
+  if (targetContext !== null && targetContext !== "" && targetContext !== "_self") return null;
+  const href = anchor.getAttribute("href") ?? "";
+  return owns(href, anchor) ? anchor : null;
+}

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

@@ -0,0 +1,8 @@
+/** Native number constraints shared by both adapters; arithmetic stays in stepUp/stepDown. */
+export function numberConstraints(min: number | undefined, max: number | undefined, step: number) {
+  if ((min !== undefined && !Number.isFinite(min)) || (max !== undefined && !Number.isFinite(max)) ||
+    !Number.isFinite(step) || step <= 0 || (min !== undefined && max !== undefined && max < min)) {
+    throw new Error("NumberField: use finite bounds, max >= min, and a positive finite step.");
+  }
+  return { min, max, step };
+}

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

@@ -0,0 +1,17 @@
+/** An OTP always has a finite positive integer number of native segments. */
+export function codeLength(length: number): number {
+  if (!Number.isSafeInteger(length) || length < 1) throw new Error("OneTimeCodeInput: length must be a positive integer.");
+  return length;
+}
+/** Canonical ASCII alphanumeric entry; the caller's native pattern owns validation. */
+export function codeCharacters(text: string, limit: number): string[] {
+  return text.replace(/[^a-zA-Z0-9]/g, "").slice(0, limit).split("");
+}
+/** Keep empty positions while editing; flatten only for the public complete-code value. */
+export function codeSegments(value: string, length: number): string[] {
+  return Array.from({ length: codeLength(length) }, (_, index) => value[index] ?? "");
+}
+
+/** Native keyboard hint shared by both OTP adapters. */
+export const ONE_TIME_CODE_INPUT_MODES = ["none", "text", "decimal", "numeric", "tel", "search", "email", "url"] as const;
+export type OneTimeCodeInputMode = (typeof ONE_TIME_CODE_INPUT_MODES)[number];

package/vendor/ds/kits/base/src/core/operational-motion.ts

@@ -0,0 +1,174 @@
+/** Native visibility/motion observation with adapter-owned cleanup. */
+export function observeActivity(
+  element: Element,
+  change: (allowed: boolean) => void,
+) {
+  const doc = element.ownerDocument,
+    win = doc.defaultView;
+  if (!win) {
+    change(false);
+    return () => {};
+  }
+  const media = win.matchMedia?.("(prefers-reduced-motion: reduce)");
+  const bounds = element.getBoundingClientRect();
+  let inView =
+    typeof win.IntersectionObserver !== "function" ||
+    (bounds.width > 0 &&
+      bounds.height > 0 &&
+      bounds.bottom >= 0 &&
+      bounds.right >= 0 &&
+      bounds.top <= win.innerHeight &&
+      bounds.left <= win.innerWidth);
+  const update = () => change(inView && !doc.hidden && !media?.matches);
+  const observer =
+    typeof win.IntersectionObserver === "function"
+      ? new win.IntersectionObserver((entries) => {
+          inView = entries.some((e) => e.isIntersecting);
+          update();
+        })
+      : undefined;
+  observer?.observe(element);
+  doc.addEventListener("visibilitychange", update);
+  media?.addEventListener("change", update);
+  update();
+  return () => {
+    observer?.disconnect();
+    doc.removeEventListener("visibilitychange", update);
+    media?.removeEventListener("change", update);
+  };
+}
+/** Semantics update immediately; only paint receives an optional fade. */
+export function valuePresentation(element: HTMLElement) {
+  let key: unknown,
+    initial = true,
+    animation: Animation | undefined,
+    allowed = false;
+  const stop = observeActivity(element, (next) => {
+    allowed = next;
+    if (!next) animation?.cancel();
+  });
+  return {
+    update(next: unknown, enabled: boolean) {
+      const changed = !initial && key !== next;
+      initial = false;
+      key = next;
+      animation?.cancel();
+      if (changed && enabled && allowed)
+        animation = element.animate?.([{ opacity: 0.45 }, { opacity: 1 }], {
+          duration: 180,
+          easing: "ease-out",
+        });
+    },
+    destroy() {
+      animation?.cancel();
+      stop();
+    },
+  };
+}
+/** A decorative clone never owns committed state or focus. */
+export function transferPresentation(
+  host: HTMLElement,
+  fromId: string,
+  toId: string,
+  duration: number,
+) {
+  const doc = host.ownerDocument,
+    from = doc.getElementById(fromId),
+    to = doc.getElementById(toId),
+    win = doc.defaultView;
+  if (
+    !from ||
+    !to ||
+    from === to ||
+    doc.hidden ||
+    win?.matchMedia?.("(prefers-reduced-motion: reduce)").matches
+  )
+    return () => {};
+  const a = from.getBoundingClientRect(),
+    b = to.getBoundingClientRect();
+  if (
+    !a.width ||
+    !a.height ||
+    !b.width ||
+    !b.height ||
+    !win ||
+    a.bottom < 0 ||
+    a.top > win.innerHeight ||
+    a.right < 0 ||
+    a.left > win.innerWidth
+  )
+    return () => {};
+  const clone = from.cloneNode(true) as HTMLElement;
+  for (const node of [clone, ...clone.querySelectorAll<HTMLElement>("*")]) {
+    node.removeAttribute("id");
+    node.removeAttribute("name");
+    node.removeAttribute("autofocus");
+  }
+  clone.inert = true;
+  clone.setAttribute("aria-hidden", "true");
+  clone.setAttribute("data-transfer-clone", "");
+  Object.assign(clone.style, {
+    position: "fixed",
+    left: `${a.left}px`,
+    top: `${a.top}px`,
+    width: `${a.width}px`,
+    height: `${a.height}px`,
+    margin: "0",
+    pointerEvents: "none",
+    transformOrigin: "top left",
+    zIndex: "2147483647",
+  });
+  const material = win.getComputedStyle(from);
+  for (let i = 0; i < material.length; i++) {
+    const property = material.item(i);
+    if (property.startsWith("--reddb-"))
+      clone.style.setProperty(property, material.getPropertyValue(property));
+  }
+  Object.assign(clone.style, {
+    fontFamily: material.fontFamily,
+    fontSize: material.fontSize,
+    lineHeight: material.lineHeight,
+    color: material.color,
+  });
+  doc.body.append(clone);
+  let animation: Animation | undefined,
+    disposed = false;
+  let stop = () => {};
+  const destroy = () => {
+    if (disposed) return;
+    disposed = true;
+    stop();
+    animation?.cancel();
+    clone.remove();
+  };
+  stop = observeActivity(from, (allowed) => {
+    if (!allowed) destroy();
+  });
+  if (disposed) {
+    stop();
+    return destroy;
+  }
+  animation = clone.animate?.(
+    [
+      { transform: "translate(0, 0) scale(1)", opacity: 0.9 },
+      {
+        transform: `translate(${b.left - a.left}px, ${b.top - a.top}px) scale(${b.width / a.width}, ${b.height / a.height})`,
+        opacity: 0,
+      },
+    ],
+    {
+      duration: Math.max(
+        0,
+        Math.min(1500, Number.isFinite(duration) ? duration : 400),
+      ),
+      easing: "cubic-bezier(.16,1,.3,1)",
+      fill: "forwards",
+    },
+  );
+  if (animation) animation.finished.then(destroy, destroy);
+  else destroy();
+  return () => {
+    stop();
+    destroy();
+  };
+}

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

@@ -0,0 +1,8 @@
+export interface PaginationPage {
+  /** Visible page number and stable link identity. */
+  page: number;
+  /** Native link destination. */
+  href: string;
+  /** Whether this page is currently viewed. */
+  current?: boolean;
+}

package/vendor/ds/kits/base/src/core/phone-input.ts

@@ -0,0 +1,106 @@
+import { AsYouType, getCountries, getCountryCallingCode, parseIncompletePhoneNumber } from "libphonenumber-js/min";
+import type { PhoneCountry } from "./contracts/phoneinput";
+import type { SearchSelectOption } from "../search-select.variants";
+export type { PhoneCountry } from "./contracts/phoneinput";
+export interface PhoneState {
+  country: PhoneCountry;
+  display: string;
+  value: string;
+  international: string;
+  possible: boolean;
+}
+
+/** An empty allowlist is a configuration error, never an implicit unrestricted selector. */
+export function phoneCountries(countries?: readonly PhoneCountry[]): readonly PhoneCountry[] {
+  const supported = new Set(getCountries()), result = [...new Set(countries ?? getCountries())];
+  if (!result.length || result.some(country => !supported.has(country))) throw new RangeError("PhoneInput requires supported country codes and a non-empty country list.");
+  return result;
+}
+/** Unicode flag is decorative; the selector always also names the country and calling code. */
+export function phoneFlag(country: PhoneCountry): string {
+  return [...country].map(letter => String.fromCodePoint(127397 + letter.charCodeAt(0))).join("");
+}
+export function phoneCountryName(country: PhoneCountry, locale = "en"): string {
+  return new Intl.DisplayNames([locale], { type: "region" }).of(country) ?? country;
+}
+const optionCache = new Map<string, readonly SearchSelectOption[]>();
+/** Search accepts localized/English names, ISO code and calling code. No network or location inference.
+ * Before hydration, use ISO ordering/names: host ICU versions can disagree on translations and sort order. */
+export function phoneCountryOptions(countries: readonly PhoneCountry[], locale = "en", localized = true): readonly SearchSelectOption[] {
+  const key = `${localized ? locale : "iso"}:${countries.join(",")}`;
+  const cached = optionCache.get(key); if (cached) return cached;
+  const options = countries.map(country => ({ value: country, label: `${phoneFlag(country)} +${getCountryCallingCode(country)}`,
+    description: localized ? phoneCountryName(country, locale) : country, keywords: [country, ...(localized ? [phoneCountryName(country, "en")] : []), getCountryCallingCode(country)] }));
+  options.sort((a, b) => localized ? a.description.localeCompare(b.description, locale) : a.value < b.value ? -1 : 1);
+  optionCache.set(key, options); return options;
+}
+/** Preserve the actual international prefix when pasting; never silently prepend the old country's code. */
+export function phoneState(text: string, fallback: PhoneCountry): PhoneState {
+  const clean = parseIncompletePhoneNumber(text), international = clean.startsWith("+");
+  if (!clean || clean === "+") return { country: fallback, display: clean, value: "", international: clean, possible: false };
+  const formatter = new AsYouType(fallback), formatted = formatter.input(clean), number = formatter.getNumber();
+  const country = formatter.getCountry() ?? fallback;
+  const value = String(formatter.getNumberValue() ?? (international ? clean : `+${getCountryCallingCode(fallback)}${clean}`));
+  const display = international && formatter.getCountry() && number ? number.formatNational() : formatted;
+  const hasExtension = /(?:ext\.?|extension|[#x])\s*\d/i.test(text);
+  return { country, display, value, international: number && formatter.getCountry() ? number.formatInternational() : new AsYouType().input(value),
+    possible: Boolean(number?.isPossible() && formatter.getCountry() && value.length <= 16 && !hasExtension) };
+}
+export function phoneProblem(state: PhoneState, countries: readonly PhoneCountry[], required: boolean, requiredMessage: string, invalidMessage: string): string {
+  return !state.value && !state.display ? (required ? requiredMessage : "") : state.possible && countries.includes(state.country) ? "" : invalidMessage;
+}
+/** Count decimal digits rather than punctuation when preserving a selection through a mask. */
+export function phoneDigitCount(value: string): number { return [...value.matchAll(/\p{Decimal_Number}/gu)].length; }
+export function phoneCaret(display: string, digits: number): number {
+  if (!digits) return 0;
+  for (let i = 0, count = 0; i < display.length; i++) if (/\p{Decimal_Number}/u.test(display[i]!) && ++count >= digits) return i + 1;
+  return display.length;
+}
+/** Delete the adjacent digit when Backspace/Delete would otherwise merely remove an auto-inserted separator. */
+export function phoneSeparatorDeletion(display: string, type: string, start: number, end: number): { text: string; digits: number } | undefined {
+  if (start !== end || !["deleteContentBackward", "deleteContentForward"].includes(type)) return;
+  const backward = type === "deleteContentBackward", character = display[backward ? start - 1 : start];
+  if (!character || /\p{Decimal_Number}/u.test(character)) return;
+  const digits = parseIncompletePhoneNumber(display).replace(/\D/g, ""), before = phoneDigitCount(display.slice(0, start));
+  const index = backward ? before - 1 : before;
+  if (index < 0 || index >= digits.length) return;
+  return { text: digits.slice(0, index) + digits.slice(index + 1), digits: backward ? before - 1 : before };
+}
+/** Native editing mechanics shared by both adapters: caret, paste, IME and separator deletion. */
+export function bindPhoneEditing(element: HTMLInputElement, initial: PhoneState, changed: (next: PhoneState, previous: PhoneState) => void) {
+  let current = initial, composing = false;
+  const blocked = () => element.matches(":disabled");
+  function apply(text = element.value, digitPosition = phoneDigitCount(text.slice(0, element.selectionStart ?? text.length))) {
+    if (blocked()) return;
+    const next = phoneState(text, current.country), previous = current; current = next;
+    element.value = next.display;
+    const caret = phoneCaret(next.display, digitPosition);
+    element.setSelectionRange(caret, caret);
+    if (next.value !== previous.value || next.country !== previous.country || next.display !== previous.display) changed(next, previous);
+  }
+  function input(event: Event) { if (!composing && !(event as InputEvent).isComposing) apply(); }
+  function before(event: InputEvent) {
+    if (composing || event.isComposing || blocked()) return;
+    const deletion = phoneSeparatorDeletion(current.display, event.inputType, element.selectionStart ?? 0, element.selectionEnd ?? 0);
+    if (deletion) { event.preventDefault(); apply(deletion.text, deletion.digits); }
+  }
+  function compositionStart() { composing = true; }
+  function compositionEnd() { composing = false; apply(); }
+  element.addEventListener("input", input); element.addEventListener("beforeinput", before);
+  element.addEventListener("compositionstart", compositionStart); element.addEventListener("compositionend", compositionEnd);
+  return {
+    sync(next: PhoneState) { current = next; if (!composing && element.value !== next.display) element.value = next.display; },
+    destroy() { element.removeEventListener("input", input); element.removeEventListener("beforeinput", before); element.removeEventListener("compositionstart", compositionStart); element.removeEventListener("compositionend", compositionEnd); },
+  };
+}
+
+/** Keep the selected country accurate even when an international paste is outside the allowlist. */
+export function phoneOptions(countries: readonly PhoneCountry[], country: PhoneCountry, locale: string, localized = true) {
+  const options = phoneCountryOptions(countries, locale, localized);
+  return countries.includes(country) ? options : [...options, { ...phoneCountryOptions([country], locale, localized)[0]!, disabled: true }];
+}
+/** Focus only the first invalid control when native form validation reports several errors. */
+export function phoneInvalid(element: HTMLInputElement) {
+  const first = element.form ? [...element.form.elements].find(control => "willValidate" in control && (control as HTMLInputElement).willValidate && !(control as HTMLInputElement).validity.valid) : element;
+  if (first === element) element.focus();
+}

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

@@ -0,0 +1,15 @@
+/** Resolve before the first popup render so native modal portals never mount on body first. */
+export function modalPortalContainer(source: HTMLElement): HTMLElement | undefined {
+  return source.closest<HTMLDialogElement>("dialog[open]") ?? undefined;
+}
+/** The portal retains its source's independent appearance axes and native modal boundary. */
+export function observePortalAppearance(source: HTMLElement, changed: (state: { attributes: Record<string, string>; container: HTMLElement | undefined }) => void) {
+  const keys = ["data-theme", "data-color-scheme", "data-density"];
+  const read = () => changed({
+    attributes: Object.fromEntries(keys.flatMap(key => { const value = source.closest(`[${key}]`)?.getAttribute(key); return value == null ? [] : [[key, value]]; })),
+    container: modalPortalContainer(source),
+  });
+  read(); const observer = new MutationObserver(read);
+  for (let node: HTMLElement | null = source; node; node = node.parentElement) observer.observe(node, { attributes: true, attributeFilter: [...keys, "open"] });
+  return () => observer.disconnect();
+}