@reddb-io/ui-kit 0.3.4 → 0.3.5

package/vendor/ds/kits/base/test/fixtures/progress-feedback-consumer.ts

@@ -0,0 +1,21 @@
+export {
+  LOADING_INDICATOR_SIZES,
+  RADIAL_PROGRESS_SIZES,
+  SKELETON_SHAPES,
+  LoadingIndicator,
+  Meter,
+  Progress,
+  RadialProgress,
+  Skeleton,
+  formatPercent,
+  isDeterminate,
+  loadingIndicator,
+  meter,
+  normalizeRange,
+  progress,
+  radialProgress,
+  skeleton,
+  type LoadingIndicatorSize,
+  type RadialProgressSize,
+  type SkeletonShape,
+} from "@reddb-io/design-system/base";

package/vendor/ds/kits/base/test/fixtures/range-pressed-consumer.ts

@@ -0,0 +1,16 @@
+// Range and pressed-state capabilities through the public Base consumer seam.
+export {
+  Rating,
+  Slider,
+  ToggleButton,
+  ToggleGroup,
+  rating,
+  slider,
+  toggleButton,
+  toggleGroup,
+  type RatingVariants,
+  type SliderVariants,
+  type ToggleButtonVariants,
+  type ToggleGroupOption,
+  type ToggleGroupVariants,
+} from "@reddb-io/design-system/base";

package/vendor/ds/kits/base/test/fixtures/specialized-entry-consumer.ts

@@ -0,0 +1,15 @@
+// Specialized entry and grouping contracts through the Base subpath a Product
+// Application consumes. Private source files cannot satisfy these tests.
+
+export {
+  ControlGroup,
+  FileInput,
+  OneTimeCodeInput,
+  controlGroup,
+  fileInput,
+  oneTimeCodeInput,
+  type ControlGroupOrientation,
+  type ControlGroupVariants,
+  type FileInputVariants,
+  type OneTimeCodeInputVariants,
+} from "@reddb-io/design-system/base";

package/vendor/ds/kits/base/test/fixtures/status-vocabulary-consumer.ts

@@ -0,0 +1,22 @@
+// Status vocabulary contracts through the Base subpath a Product Application
+// consumes. Private source files cannot satisfy these tests.
+export {
+  BADGE_VARIANTS,
+  DEPRECATED_BADGE_VARIANTS,
+  Badge,
+  INDICATOR_POSITIONS,
+  Indicator,
+  STATUS_INDICATOR_STATUSES,
+  STATUS_INDICATOR_TONES,
+  TONES,
+  StatusIndicator,
+  badge,
+  indicator,
+  statusIndicator,
+  type BadgeVariant,
+  type BadgeVariants,
+  type IndicatorPosition,
+  type IndicatorVariants,
+  type StatusIndicatorStatus,
+  type StatusIndicatorVariants,
+} from "@reddb-io/design-system/base";

package/vendor/ds/kits/base/test/fixtures/surface-controls-consumer.ts

@@ -0,0 +1,22 @@
+// The four surface controls through the distributed Base subpath a consumer uses.
+
+export {
+  APPEARANCE_AXES,
+  AppearanceSwitch,
+  SCROLL_AREA_ORIENTATIONS,
+  SECTION_HEADING_LEVELS,
+  SECTION_HEADING_SIZES,
+  ScrollArea,
+  SectionHeading,
+  Swap,
+  appearanceAttribute,
+  appearanceStorageKey,
+  scrollArea,
+  sectionHeading,
+  swap,
+  type AppearanceAxis,
+  type AppearanceOption,
+  type ScrollAreaOrientation,
+  type SectionHeadingLevel,
+  type SectionHeadingSize,
+} from "@reddb-io/design-system/base";

package/vendor/ds/kits/base/test/fixtures/surface-separation-consumer.ts

@@ -0,0 +1,31 @@
+export {
+  AspectRatio,
+  CARD_ACTIONS_ALIGNMENTS,
+  CARD_MEDIA_FITS,
+  CARD_MEDIA_POSITIONS,
+  CARD_MEDIA_RATIOS,
+  CARD_MEDIA_SPANS,
+  CARD_ORIENTATIONS,
+  CARD_PADDINGS,
+  CARD_TONES,
+  CARD_VARIANTS,
+  DEPRECATED_CARD_TONES,
+  TONES,
+  Card,
+  DEFAULT_ASPECT_RATIO,
+  DIVIDER_ORIENTATIONS,
+  Divider,
+  aspectRatio,
+  card,
+  divider,
+  type CardPadding,
+  type CardTone,
+  type CardActionsAlign,
+  type CardMediaFit,
+  type CardMediaPosition,
+  type CardMediaRatio,
+  type CardMediaSpan,
+  type CardOrientation,
+  type CardVariant,
+  type DividerOrientation,
+} from "@reddb-io/design-system/base";

package/vendor/ds/kits/base/test/fixtures/textarea-select-consumer.ts

@@ -0,0 +1,13 @@
+// Textarea and Select through the Base subpath a Product Application uses.
+//
+// This fixture keeps the behavior suites at the distributed public seam: a
+// private component or appearance function does not satisfy the capability.
+
+export {
+  Select,
+  Textarea,
+  select,
+  textarea,
+  type SelectVariants,
+  type TextareaVariants,
+} from "@reddb-io/design-system/base";

package/vendor/ds/kits/base/test/fixtures/time-entry-consumer.ts

@@ -0,0 +1,11 @@
+// Time entry contracts through the Base subpath a Product Application uses.
+// Private source files cannot satisfy this distributed-export seam.
+
+export {
+  TimeField,
+  TimeRangeField,
+  timeField,
+  timeRangeField,
+  type TimeFieldVariants,
+  type TimeRangeFieldVariants,
+} from "@reddb-io/design-system/base";

package/vendor/ds/kits/base/test/form.test.ts

@@ -0,0 +1,72 @@
+import { flushSync } from "svelte";
+import { describe, expect, it, vi } from "vitest";
+import FormScaffoldingConsumer from "./fixtures/FormScaffoldingConsumer.svelte";
+import { Form, form } from "./fixtures/form-scaffolding-consumer";
+import { classes, classesOf, render, rendered } from "./mount";
+
+describe("the Base Form", () => {
+  it("is available with its Extension Seam through the Base consumer subpath", () => {
+    expect(Form).toBeDefined();
+    expect(form).toBeTypeOf("function");
+  });
+
+  it("is a native form and forwards its submission contract", () => {
+    const onsubmit = vi.fn((event: SubmitEvent) => event.preventDefault());
+    const root = rendered(render(FormScaffoldingConsumer, { onsubmit }));
+    const element = root.querySelector<HTMLFormElement>('[data-testid="profile-form"]')!;
+
+    expect(element.tagName).toBe("FORM");
+    expect(element.method).toBe("post");
+    expect(element.getAttribute("action")).toBe("/profiles");
+    expect(element.getAttribute("autocomplete")).toBe("off");
+    expect(element.noValidate).toBe(true);
+
+    const submitted = element.dispatchEvent(
+      new SubmitEvent("submit", { bubbles: true, cancelable: true }),
+    );
+    flushSync();
+    expect(submitted).toBe(false);
+    expect(onsubmit).toHaveBeenCalledTimes(1);
+  });
+
+  it("composes canonical labels, groups, and controls into native form data", () => {
+    const root = rendered(render(FormScaffoldingConsumer, {}));
+    const element = root.querySelector<HTMLFormElement>('[data-testid="profile-form"]')!;
+    const name = element.querySelector<HTMLInputElement>('#display-name')!;
+    const notices = element.querySelector<HTMLInputElement>('#email-notices')!;
+
+    name.value = "Ada";
+    notices.checked = true;
+
+    expect(element.querySelector('label[for="display-name"]')).not.toBeNull();
+    expect(element.querySelector("fieldset > legend")?.textContent).toContain(
+      "Contact preferences",
+    );
+    expect(Object.fromEntries(new FormData(element))).toEqual({
+      displayName: "Ada",
+      notices: "email",
+    });
+  });
+
+  it("wears exactly its exported appearance and merges consumer classes", () => {
+    const root = rendered(render(FormScaffoldingConsumer, {}));
+    const element = root.querySelector<HTMLFormElement>('[data-testid="profile-form"]')!;
+
+    expect(classes(element)).toEqual(classesOf(form({ class: "max-w-xl" })));
+    // The Form owns its row rhythm from the Density layout tier (ADR 0024).
+    expect(classes(element).has("gap-[var(--reddb-spatial-layout-gap-md)]")).toBe(true);
+    expect(classes(element).has("max-w-xl")).toBe(true);
+  });
+
+  it("inherits a nested appearance without selecting any axis itself", () => {
+    const root = rendered(render(FormScaffoldingConsumer, {}));
+    const element = root.querySelector<HTMLFormElement>(
+      '[data-appearance-scope] [data-testid="nested-form"]',
+    )!;
+
+    expect(element.hasAttribute("data-theme")).toBe(false);
+    expect(element.hasAttribute("data-color-scheme")).toBe(false);
+    expect(element.hasAttribute("data-density")).toBe(false);
+    expect(classes(element)).toEqual(classesOf(form()));
+  });
+});

package/vendor/ds/kits/base/test/framework-appearance.test.ts

@@ -0,0 +1,53 @@
+import { mount, unmount, flushSync } from "svelte";
+import { act, createElement as h, type ComponentType } from "react";
+import { createRoot } from "react-dom/client";
+import { expect, it } from "vitest";
+import * as react from "../react/src";
+import SveltePrimitive from "./fixtures/FrameworkPrimitive.svelte";
+
+Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
+const scenarios: Array<{ name: string; options?: Record<string, unknown> }> = [
+  ...["neutral", "info", "success", "warning", "danger"].flatMap(tone => ["tinted", "filled", "outline"].map(variant => ({ name: "Badge", options: { tone, variant } }))),
+  ...["primary", "secondary", "ghost"].flatMap(variant => ["sm", "md", "lg"].map(size => ({ name: "Button", options: { variant, size } }))),
+  { name: "Button", options: { href: "/detail", disabled: true } },
+  { name: "Button", options: { href: "/detail" } },
+  { name: "Button", options: { loading: true } },
+  { name: "Button", options: { block: true, tone: "danger" } },
+  ...["prose", "content", "wide", "full"].map(size => ({ name: "Container", options: { size } })),
+  ...["horizontal", "vertical"].map(orientation => ({ name: "Divider", options: { orientation } })),
+  ...[1, 2, 3, 4, 5, 6].map(level => ({ name: "Heading", options: { level } })),
+  { name: "Label", options: { for: "named-control" } },
+  ...["sm", "md", "lg"].flatMap(size => [false, true].map(labelHidden => ({ name: "LoadingIndicator", options: { size, labelHidden, label: "Fetching results" } }))),
+  ...["row", "column"].flatMap(direction => [false, true].map(wrap => ({ name: "Stack", options: { direction, wrap, gap: "layout-sm", align: "center", justify: "between" } }))),
+  ...["body", "caption"].flatMap(role => ["p", "span", "div", "small"].map(as => ({ name: "Text", options: { role, as } }))),
+];
+
+function snapshot(target: HTMLElement) {
+  // Compare the public DOM contract and recipes, ignoring renderer markers and
+  // Svelte's comment anchors. Every nested spinner/label still participates.
+  return [...target.querySelectorAll("*")].map(element => ({
+    tag: element.tagName,
+    classes: [...element.classList].sort(),
+    attributes: Object.fromEntries([...element.attributes]
+      .filter(attribute => /^(aria-|role$|type$|href$|tabindex$|disabled$|for$|data-(badge|tone|variant|container-size|divider|heading|type-role|loading-indicator|stack|text)$)/.test(attribute.name))
+      .map(attribute => [attribute.name, attribute.name.startsWith("data-") && attribute.value === "true" ? "" : attribute.value]).sort()),
+    text: element.children.length ? undefined : element.textContent?.trim(),
+  }));
+}
+
+for (const { name, options = {} } of scenarios) it(`shares ${name} appearance and native semantics ${JSON.stringify(options)}`, async () => {
+  const svelteTarget = document.createElement("div"); const reactTarget = document.createElement("div");
+  document.body.append(svelteTarget, reactTarget);
+  const svelte = mount(SveltePrimitive, { target: svelteTarget, props: { name, options } }); flushSync();
+  const root = createRoot(reactTarget);
+  try {
+    const { for: htmlFor, ...native } = options;
+    await act(() => root.render(h((react as unknown as Record<string, ComponentType<Record<string, unknown>>>)[name]!, { ...native, ...(htmlFor ? { htmlFor } : {}), ...(name === "Divider" ? {} : { children: "Content" }) })));
+    expect(snapshot(reactTarget)).toEqual(snapshot(svelteTarget));
+    if (name === "LoadingIndicator") {
+      expect(reactTarget.querySelector('[role="status"]')?.textContent).toContain("Fetching results");
+      expect(reactTarget.querySelector('[aria-live="polite"]')).not.toBeNull();
+    }
+    if (name === "Button" && options.disabled) expect(reactTarget.querySelector("a")?.getAttribute("aria-disabled")).toBe("true");
+  } finally { await act(() => root.unmount()); await unmount(svelte); svelteTarget.remove(); reactTarget.remove(); }
+});

package/vendor/ds/kits/base/test/framework-base.test.ts

@@ -0,0 +1,128 @@
+import { mount, unmount, flushSync } from "svelte";
+import { act, createElement as h, type ComponentType } from "react";
+import { createRoot } from "react-dom/client";
+import { describe, expect, it } from "vitest";
+import * as react from "../react/src";
+import type { FieldsetControlProps } from "../src/core/fieldset";
+import { CONTENT_MASK_SHAPES } from "../src/content-mask.variants";
+import { SKELETON_SHAPES } from "../src/skeleton.variants";
+import { INDICATOR_POSITIONS } from "../src/indicator.variants";
+import SvelteBase from "./fixtures/FrameworkBase.svelte";
+
+Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
+type Scenario = { name: string; options?: Record<string, unknown>; content?: boolean; rich?: boolean };
+const scenarios: Scenario[] = [
+  ...[undefined, 1, 4 / 3, 21 / 9].map(ratio => ({ name: "AspectRatio", options: { ...(ratio === undefined ? {} : { ratio }), style: { opacity: "0.9" } } })),
+  ...SKELETON_SHAPES.flatMap(shape => [undefined, "Loading results"].map(label => ({ name: "Skeleton", options: { shape, label }, content: false }))),
+  ...["div", "article", "section"].flatMap(as => ["prose", "content", "full"].flatMap(measure => [false, true].map(striped => ({ name: "Prose", options: { as, measure, striped } })))),
+  ...["p", "span", "div"].map(as => ({ name: "Eyebrow", options: { as } })),
+  { name: "Kbd", options: { keys: ["Ctrl", "K"], size: "sm" }, content: false },
+  { name: "Kbd", options: { keys: ["Alt", "Shift", "P"], separator: " / " }, content: false },
+  { name: "Kbd", options: { keys: ["ignored"] } }, { name: "Kbd", content: false },
+  { name: "Form" },
+  ...[{}, { help: "Choose a team" }, { error: "Selection required" }, { help: "Choose a team", error: "Selection required", disabled: true }].map(messages => ({ name: "Fieldset", options: { legend: "Teams", id: "group", ...messages } })),
+  { name: "SkipLink" }, { name: "SkipLink", content: false },
+  ...["neutral", "info", "success", "warning", "danger"].flatMap(tone => ["stacked", "inline"].flatMap(layout => [false, true].map(labelHidden => ({ name: "Meter", options: { value: 72, tone, layout, labelHidden }, content: false })))),
+  ...["Progress", "RadialProgress"].flatMap(name => [undefined, null, 0, 45, 100, 150, -10, Number.NaN].map(value => ({ name, options: { value, ...(name === "Progress" ? { summary: true } : { size: "lg" }) }, content: false }))),
+  ...["Meter", "Progress", "RadialProgress"].flatMap(name => [
+    { value: 10, min: 10, max: 10 }, { value: 30, min: 50, max: -10 }, { value: 10, min: Number.NaN, max: Infinity },
+    { value: 30, min: 10, max: 50, formatValue: (value: number) => `${value} requests` },
+  ].map(options => ({ name, options, content: false }))),
+  ...INDICATOR_POSITIONS.map(position => ({ name: "Indicator", options: { position } })),
+  ...["neutral", "info", "success", "warning", "danger"].flatMap(tone => [false, true].map(showLabel => ({ name: "StatusIndicator", options: { tone, showLabel, label: "Available" }, content: false }))),
+  ...[false, true].flatMap(ordered => ["sm", "md", "lg"].map(gap => ({ name: "List", options: { ordered, gap } }))),
+  ...[1, 2, 3, 4].flatMap(columns => [false, true].map(list => ({ name: "GridList", options: { columns, list } }))),
+  ...["sm", "md", "lg"].map(gap => ({ name: "DescriptionList", options: { gap, items: [{ term: "Region", detail: "Brazil" }] }, content: false })),
+  { name: "DescriptionList", rich: true }, { name: "DescriptionList", content: false },
+  ...["horizontal", "vertical"].map(orientation => ({ name: "ControlGroup", options: { label: "Actions", orientation } })),
+  ...CONTENT_MASK_SHAPES.map(shape => ({ name: "ContentMask", options: { shape, style: { opacity: "0.9" } } })),
+  ...[1, 2, 3, 4, 5, 6].flatMap(level => ["sm", "md", "lg", "display"].map(size => ({ name: "SectionHeading", options: { level, size, title: "Requests", description: "Last hour", titleId: "requests", rule: level % 2 === 0 }, rich: true }))),
+  { name: "SectionHeading", options: { title: "Requests" }, content: false },
+  { name: "Statistic", options: { label: "Total", value: 1200, description: "This month", formatValue: (value: number | string) => Number(value).toLocaleString("en-US") }, content: false },
+  { name: "Statistic", options: { label: "Uptime", value: "99.99%" }, content: false },
+];
+
+function reactProps({ name, options = {}, content = true, rich }: Scenario) {
+  const props = { ...options, className: "contract-extra", "data-consumer": "forwarded" };
+  if (name === "Fieldset") return { ...props, children: (control: FieldsetControlProps) => h("input", { ...control, name: "choice", "aria-label": "Choice", defaultValue: "chosen" }) };
+  if (name === "Indicator") return { ...props, marker: h("span", { "aria-label": "3 unread" }, "3"), children: h("button", { type: "button" }, "Inbox") };
+  if (name === "SectionHeading") return { ...props, ...(rich ? { actions: h("button", { type: "button" }, "Details") } : {}) };
+  if (name === "DescriptionList") return { ...props, ...(rich ? { items: [{ term: h("strong", null, "Requests"), detail: h("a", { href: "/detail" }, "View details") }] } : {}) };
+  if (name === "Form") return { ...props, children: [h("input", { key: "input", name: "query", "aria-label": "Query", defaultValue: "original", required: true }), h("button", { key: "submit", type: "submit" }, "Submit"), h("button", { key: "reset", type: "reset" }, "Reset")] };
+  if (name === "List" || name === "GridList") return { ...props, children: ["Alpha", "Beta"].map(text => h(options.list === false ? "div" : "li", { key: text }, text)) };
+  return { ...props, ...(content ? { children: h("span", { "data-test-content": true }, "Content") } : {}) };
+}
+async function renderScenario(scenario: Scenario) {
+  const svelteTarget = document.createElement("div"); const reactTarget = document.createElement("div"); document.body.append(svelteTarget, reactTarget);
+  // Both renderers receive their native style representation.
+  const { style, ...attributes } = scenario.options ?? {};
+  const options = { ...attributes, ...(style ? { style: Object.entries(style as Record<string, string>).map(([key, value]) => `${key}: ${value}`).join(";") } : {}), class: "contract-extra", "data-consumer": "forwarded" };
+  const svelte = mount(SvelteBase, { target: svelteTarget, props: { ...scenario, options } }); flushSync();
+  const root = createRoot(reactTarget);
+  await act(() => root.render(h((react as unknown as Record<string, ComponentType<Record<string, unknown>>>)[scenario.name]!, reactProps(scenario))));
+  return { svelteTarget, reactTarget, update: async (next: Record<string, unknown>) => {
+    flushSync(() => svelte.update({ ...next, class: "contract-extra", "data-consumer": "forwarded" }));
+    await act(() => root.render(h((react as unknown as Record<string, ComponentType<Record<string, unknown>>>)[scenario.name]!, reactProps({ ...scenario, options: next }))));
+  }, cleanup: async () => { await act(() => root.unmount()); await unmount(svelte); svelteTarget.remove(); reactTarget.remove(); } };
+}
+function snapshot(target: HTMLElement) {
+  return [...target.querySelectorAll("*")].map(element => ({ tag: element.tagName, classes: [...element.classList].sort(),
+    attributes: Object.fromEntries([...element.attributes].filter(attribute => attribute.name !== "class" && attribute.name !== "style" && attribute.name !== "value" && !attribute.name.startsWith("data-svelte"))
+      .map(attribute => [attribute.name, attribute.name.startsWith("data-") && attribute.value === "true" ? "" : attribute.value]).sort()),
+    style: element.getAttribute("style") ? Object.fromEntries([...((element as HTMLElement).style)].sort().map(name => [name, (element as HTMLElement).style.getPropertyValue(name)])) : undefined,
+    text: element.children.length ? undefined : element.textContent?.trim(),
+  }));
+}
+
+for (const scenario of scenarios) it(`matches ${scenario.name} public DOM, appearance and semantics ${JSON.stringify(scenario.options ?? {})}`, async () => {
+  const { svelteTarget, reactTarget, cleanup } = await renderScenario(scenario);
+  try {
+    expect(snapshot(reactTarget)).toEqual(snapshot(svelteTarget));
+    expect([...reactTarget.querySelectorAll("input")].map(input => input.value)).toEqual([...svelteTarget.querySelectorAll("input")].map(input => input.value));
+  } finally { await cleanup(); }
+});
+
+for (const framework of ["react", "svelte"] as const) describe(`${framework}: native Base behavior`, () => {
+  it("Fieldset updates error relationships, preserves group ids and enforces native disabled behavior", async () => {
+    const rendered = await renderScenario({ name: "Fieldset", options: { legend: "Teams", id: "stable-group", help: "Pick a team", error: "Required", disabled: true } });
+    try {
+      const target = framework === "react" ? rendered.reactTarget : rendered.svelteTarget;
+      const input = target.querySelector("input")!;
+      expect(input.matches(":disabled")).toBe(true);
+      expect(input.getAttribute("aria-invalid")).toBe("true");
+      const original = input.getAttribute("aria-describedby")!.split(" ");
+      expect(original.map(id => document.getElementById(id)?.textContent)).toEqual(["Pick a team", "Required"]);
+      await rendered.update({ legend: "Teams", id: "stable-group", help: "Pick a team" });
+      expect(input.matches(":disabled")).toBe(false);
+      expect(input.getAttribute("aria-invalid")).toBeNull();
+      expect(input.getAttribute("aria-describedby")).toBe(original[0]);
+      expect(target.querySelector('[role="alert"]')).toBeNull();
+    } finally { await rendered.cleanup(); }
+  });
+
+  it("Form preserves native submission, FormData and reset", async () => {
+    let submitted = 0;
+    const rendered = await renderScenario({ name: "Form", options: framework === "react" ? { onSubmit: (event: Event) => { event.preventDefault(); submitted++; } } : { onsubmit: (event: Event) => { event.preventDefault(); submitted++; } } });
+    try {
+      const target = framework === "react" ? rendered.reactTarget : rendered.svelteTarget;
+      const form = target.querySelector("form")!;
+      const input = form.querySelector("input")!;
+      input.value = "updated";
+      expect(new FormData(form).get("query")).toBe("updated");
+      form.querySelector<HTMLButtonElement>('[type="submit"]')!.click();
+      expect(submitted).toBe(1);
+      form.reset();
+      expect(input.value).toBe("original");
+    } finally { await rendered.cleanup(); }
+  });
+
+  it.each([{}, { cancelled: true }, { malformed: true }, { encoded: true }])("SkipLink respects focus and consumer cancellation %j", async ({ cancelled, malformed, encoded }: { cancelled?: boolean; malformed?: boolean; encoded?: boolean }) => {
+    const main = document.createElement("main"); main.id = encoded ? "main content" : "main-content"; main.tabIndex = -1; document.body.append(main);
+    const rendered = await renderScenario({ name: "SkipLink", content: false, options: { href: malformed ? "#bad%" : encoded ? "#main%20content" : "#main-content", [framework === "react" ? "onClick" : "onclick"]: cancelled ? (event: Event) => event.preventDefault() : undefined } });
+    try {
+      const target = framework === "react" ? rendered.reactTarget : rendered.svelteTarget;
+      target.querySelector("a")!.click();
+      expect(document.activeElement === main).toBe(!cancelled && !malformed);
+    } finally { await rendered.cleanup(); main.remove(); }
+  });
+});

package/vendor/ds/kits/base/test/framework-choices.test.ts

@@ -0,0 +1,137 @@
+import { mount, unmount, flushSync } from "svelte";
+import { act, createElement as h, createRef, useState, type ComponentType } from "react";
+import { createRoot } from "react-dom/client";
+import { renderToString } from "react-dom/server";
+import { describe, expect, it, vi } from "vitest";
+import * as react from "../react/src";
+import Fixture from "./fixtures/FrameworkChoices.svelte";
+Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
+type Name = "Checkbox" | "Switch" | "RadioGroup" | "Select";
+const options = [{ value: "sa", label: "South America", description: "Primary region" }, { value: "us", label: "North America", description: "Read replica" }, { value: "disabled", label: "Unavailable", description: "No capacity", disabled: true }];
+const base = { Checkbox: { label: "Share diagnostics", name: "diagnostics" }, Switch: { label: "Email digest", name: "digest" }, RadioGroup: { legend: "Region", name: "region", options }, Select: { "aria-label": "Region", name: "region", options } };
+function native(options: Record<string, unknown>) { return Object.fromEntries(Object.entries(options).map(([key, value]) => [key === "className" ? "class" : key.startsWith("on") ? key.toLowerCase() : key, value])); }
+function props(name: Name, options: Record<string, unknown>, rich: boolean) {
+  const shared = { ...base[name], className: "consumer-extra", ...options };
+  if (name === "RadioGroup" && rich) return { ...shared, optionMedia: (option: react.RadioGroupOption) => h("span", { "aria-hidden": true }, option.value) };
+  if (name === "Select" && rich) return { ...shared, children: h("optgroup", { label: "More regions" }, h("option", { value: "eu" }, "Europe"), h("option", { value: "ap", disabled: true }, "Asia Pacific")) };
+  return shared;
+}
+async function render(name: Name, supplied: Record<string, unknown> = {}, rich = false) {
+  const a = document.createElement("div"), b = document.createElement("div"); document.body.append(a, b);
+  const component = mount(Fixture, { target: a, props: { name, options: native({ ...base[name], className: "consumer-extra", ...supplied }), rich } }); flushSync();
+  const root = createRoot(b);
+  await act(() => root.render(h("form", null, h(react[name] as ComponentType<any>, props(name, supplied, rich)))));
+  return { a, b, update: async (options: Record<string, unknown>) => {
+    flushSync(() => component.update(native({ ...base[name], className: "consumer-extra", ...options })));
+    await act(() => root.render(h("form", null, h(react[name] as ComponentType<any>, props(name, options, rich)))));
+  }, cleanup: async () => { await act(() => root.unmount()); await unmount(component); a.remove(); b.remove(); } };
+}
+function snapshot(target: HTMLElement) {
+  const ids = [...target.querySelectorAll("[id]")].map(el => el.id);
+  const normalize = (v: string) => v.split(" ").map(token => ids.includes(token) ? `id-${ids.indexOf(token)}` : token).join(" ");
+  return [...target.querySelectorAll("*")].map(el => ({ tag: el.tagName, classes: [...el.classList].sort(),
+    attrs: Object.fromEntries([...el.attributes].filter(a => !["class", "checked", "selected"].includes(a.name) && !a.name.startsWith("data-svelte"))
+      .map(a => [a.name, ["id", "for", "aria-labelledby", "aria-describedby", "aria-errormessage"].includes(a.name) ? normalize(a.value) : a.name.startsWith("data-") && a.value === "true" ? "" : a.value]).sort()),
+    checked: el instanceof HTMLInputElement ? el.checked : undefined,
+    selected: el instanceof HTMLOptionElement ? el.selected : undefined,
+    text: el.children.length ? undefined : el.textContent?.trim() }));
+}
+const cases: Array<[Name, Record<string, unknown>?, boolean?]> = [
+  ...(["Checkbox", "Switch"] as const).flatMap(name => [undefined, false, true].flatMap(checked => [false, true].map(disabled => [name, { checked, disabled, required: true, help: "Shared help", error: "Review this choice", value: "enabled", fieldClass: "field-extra" }] as [Name, Record<string, unknown>]))),
+  ["Checkbox", { defaultChecked: true }], ["Switch", { defaultChecked: true }],
+  ["RadioGroup"], ["RadioGroup", { defaultValue: "us" }], ["RadioGroup", { value: "sa", disabled: true, required: true, help: "Shared help", error: "Choose a region", optionClass: "option-extra", controlClass: "control-extra" }],
+  ["RadioGroup", { defaultValue: "us", variant: "cards" }, true], ["RadioGroup", { options: [] }],
+  ["Select", { value: "missing" }],
+  ["Select"], ["Select", { defaultValue: "us" }], ["Select", { value: "us", controlSize: "sm", disabled: true, required: true }],
+  ["Select", { multiple: true, defaultValue: ["sa", "eu"], size: 4 }, true], ["Select", { defaultValue: "eu", controlSize: "lg" }, true],
+];
+for (const [name, options, rich] of cases) it(`matches ${name} shared appearance, native selection and associations ${JSON.stringify(options ?? {})}`, async () => {
+  const r = await render(name, options, rich);
+  try { expect(snapshot(r.b)).toEqual(snapshot(r.a)); } finally { await r.cleanup(); }
+});
+async function reset(form: HTMLFormElement) { await act(async () => { form.reset(); await new Promise(resolve => setTimeout(resolve, 0)); flushSync(); }); }
+for (const framework of ["svelte", "react"] as const) describe(`${framework} native choice contracts`, () => {
+  for (const name of ["Checkbox", "Switch"] as const) it(`${name} retains native state, callback ordering, required/disabled and reset`, async () => {
+    const order: string[] = []; const state = vi.fn();
+    const supplied = { defaultChecked: false, required: true, value: "enabled", onChange: () => order.push("native"), onCheckedChange: (next: boolean) => { order.push("checked"); state(next); } };
+    const r = await render(name, supplied); const target = framework === "react" ? r.b : r.a;
+    try {
+      const input = target.querySelector<HTMLInputElement>("input")!, form = target.querySelector("form")!;
+      expect(input.checkValidity()).toBe(false);
+      await act(async () => { input.click(); flushSync(); });
+      expect(input.checked).toBe(true); expect(state).toHaveBeenCalledWith(true); expect(order).toEqual(["native", "checked"]);
+      expect(new FormData(form).get(input.name)).toBe("enabled");
+      await r.update({ ...supplied, help: "Updated help" }); expect(input.checked).toBe(true);
+      await reset(form); expect(input.checked).toBe(false); expect(state).toHaveBeenCalledTimes(1);
+      await act(async () => { input.click(); flushSync(); });
+      form.addEventListener("reset", event => event.preventDefault(), { once: true }); await reset(form); expect(input.checked).toBe(true);
+      await r.update({ ...supplied, disabled: true }); expect(new FormData(form).has(input.name)).toBe(false);
+      await act(async () => { input.click(); flushSync(); }); expect(state).toHaveBeenCalledTimes(2);
+    } finally { await r.cleanup(); }
+  });
+  it("keeps RadioGroup's names exclusive, relationships stable and resets the default", async () => {
+    const change = vi.fn(); const r = await render("RadioGroup", { defaultValue: "sa", help: "Group help", onValueChange: change }, true); const target = framework === "react" ? r.b : r.a;
+    try {
+      const form = target.querySelector("form")!, radios = target.querySelectorAll<HTMLInputElement>("input"), id = radios[0]!.id;
+      await act(async () => { radios[1]!.click(); flushSync(); });
+      expect(new FormData(form).get("region")).toBe("us"); expect(change).toHaveBeenCalledWith("us");
+      await r.update({ defaultValue: "sa", error: "Review region", onValueChange: change });
+      expect(radios[0]!.id).toBe(id); expect(radios[0]!.getAttribute("aria-errormessage")).toBe(target.querySelector('[role="alert"]')!.id);
+      expect(radios[0]!.getAttribute("aria-labelledby")).toBe(`${id}-label`);
+      await reset(form); expect(new FormData(form).get("region")).toBe("sa"); expect(change).toHaveBeenCalledTimes(1);
+      await reset(form); expect(new FormData(form).get("region")).toBe("sa");
+      await r.update({ disabled: true, defaultValue: "sa" }); expect(new FormData(form).has("region")).toBe(false);
+    } finally { await r.cleanup(); }
+  });
+  it("submits all multiple selections while keeping the callback's canonical first-value dialect", async () => {
+    const change = vi.fn(), nativeChange = vi.fn(); const r = await render("Select", { multiple: true, defaultValue: ["sa", "eu"], onChange: nativeChange, onValueChange: change }, true); const target = framework === "react" ? r.b : r.a;
+    try {
+      const form = target.querySelector("form")!, select = target.querySelector("select")!;
+      expect(new FormData(form).getAll("region")).toEqual(["sa", "eu"]);
+      await act(async () => { for (const option of select.options) option.selected = option.value === "us" || option.value === "eu"; select.dispatchEvent(new Event("change", { bubbles: true })); flushSync(); });
+      expect(change).toHaveBeenCalledWith("us"); expect(nativeChange).toHaveBeenCalledTimes(1); expect(new FormData(form).getAll("region")).toEqual(["us", "eu"]);
+      await r.update({ multiple: true, defaultValue: ["sa", "eu"], help: undefined }); expect(new FormData(form).getAll("region")).toEqual(["us", "eu"]);
+      await reset(form); expect(new FormData(form).getAll("region")).toEqual(["sa", "eu"]); expect(change).toHaveBeenCalledTimes(1);
+    } finally { await r.cleanup(); }
+  });
+});
+it("keeps an explicit removed Select value empty in both native adapters", async () => {
+  const r = await render("Select", { value: "us", required: true });
+  try {
+    await r.update({ value: "us", options: options.slice(0, 1), required: true });
+    for (const target of [r.a, r.b]) {
+      const select = target.querySelector("select")!;
+      expect(select.selectedIndex).toBe(-1); expect(select.checkValidity()).toBe(false);
+      expect(new FormData(target.querySelector("form")!).has("region")).toBe(false);
+    }
+  } finally { await r.cleanup(); }
+});
+it("keeps controlled React choices caller-owned until props update, including native reset", async () => {
+  for (const name of ["Checkbox", "Switch", "RadioGroup", "Select"] as const) {
+    const change = vi.fn(); const binary = name === "Checkbox" || name === "Switch";
+    const r = await render(name, binary ? { checked: false, onCheckedChange: change } : { value: "sa", onValueChange: change });
+    try {
+      await act(() => {
+        if (binary) r.b.querySelector<HTMLInputElement>("input")!.click();
+        else if (name === "RadioGroup") r.b.querySelectorAll<HTMLInputElement>("input")[1]!.click();
+        else { const select = r.b.querySelector("select")!; select.value = "us"; select.dispatchEvent(new Event("change", { bubbles: true })); }
+      });
+      expect(change).toHaveBeenCalledWith(binary ? true : "us");
+      expect(new FormData(r.b.querySelector("form")!).get(binary ? name === "Checkbox" ? "diagnostics" : "digest" : "region")).toBe(binary ? null : "sa");
+      await r.update(binary ? { checked: true } : { value: "us" }); await reset(r.b.querySelector("form")!);
+      expect(new FormData(r.b.querySelector("form")!).get(binary ? name === "Checkbox" ? "diagnostics" : "digest" : "region")).toBe(binary ? "on" : "us");
+    } finally { await r.cleanup(); }
+  }
+});
+it("forwards native React refs and renders selected options and labels during SSR", async () => {
+  const error = vi.spyOn(console, "error");
+  try {
+    for (const name of ["Checkbox", "Switch", "RadioGroup", "Select"] as const) {
+      const ref = createRef<HTMLElement>(); const r = await render(name, { ref });
+      try { expect(ref.current?.tagName).toBe(name === "RadioGroup" ? "FIELDSET" : name === "Select" ? "SELECT" : "INPUT"); } finally { await r.cleanup(); }
+      const html = renderToString(h(react[name] as ComponentType<any>, { ...base[name], ...(name === "RadioGroup" || name === "Select" ? { defaultValue: "us" } : { defaultChecked: true }) }));
+      expect(html).toContain(name === "RadioGroup" || name === "Select" ? "us" : 'checked=""');
+    }
+    expect(error).not.toHaveBeenCalled();
+  } finally { error.mockRestore(); }
+});