@reddb-io/ui-kit 0.3.4 → 0.3.6

package/vendor/ds/kits/app/test/list-row.test.ts

@@ -0,0 +1,117 @@
+// ListRow, as an application meets it.
+//
+// The element the row renders is the contract. A row that does something has
+// to be reachable by keyboard, which means it must really be an <a> or a
+// <button> and not a <div> wearing a click handler — and a row that does
+// nothing must not wear the styling that says it does. Both directions are
+// asserted here, because only asserting the first would let a decorative row
+// look pressable forever.
+
+import { describe, expect, it, vi } from "vitest";
+import { quietControl } from "@reddb-io/design-system/base";
+import ListRow from "../src/primitives/ListRow.svelte";
+import { LIST_ROW_SIZES, listRow } from "../src/primitives/list-row.variants";
+import { classes, classesOf, click, render, rendered, text } from "./mount";
+
+describe("ListRow", () => {
+  it("renders a plain <div> when the row does nothing", () => {
+    const element = rendered(render(ListRow, { title: "reddb-01" }));
+    expect(element.tagName).toBe("DIV");
+    expect(element.textContent?.trim()).toBe("reddb-01");
+  });
+
+  it("renders an <a> when given a destination", () => {
+    const element = rendered(render(ListRow, { title: "reddb-01", href: "/nodes/reddb-01" }));
+    expect(element.tagName).toBe("A");
+    expect(element.getAttribute("href")).toBe("/nodes/reddb-01");
+  });
+
+  it("renders a <button> when given something to do, and calls it once", () => {
+    const onclick = vi.fn();
+    const element = rendered(render(ListRow, { title: "reddb-01", onclick }));
+    expect(element.tagName).toBe("BUTTON");
+    // A row inside a form must not submit it just by being pressed.
+    expect(element.getAttribute("type")).toBe("button");
+
+    click(element);
+    expect(onclick).toHaveBeenCalledTimes(1);
+  });
+
+  it("wears the interactive styling only when it is really interactive", () => {
+    const inert = rendered(render(ListRow, { title: "reddb-01" }));
+    expect(classes(inert)).toEqual(classesOf(listRow({ interactive: false }).root()));
+    expect(classes(inert).has("cursor-pointer")).toBe(false);
+
+    for (const props of [{ href: "/nodes" }, { onclick: () => {} }]) {
+      const live = rendered(render(ListRow, { title: "reddb-01", ...props }));
+      // An interactive row wears the quiet-control contract around its slot (wave 6A).
+      expect(classes(live)).toEqual(classesOf(quietControl({ ink: "inherit", class: listRow({ interactive: true }).root() })));
+    }
+  });
+
+  it("wears exactly the classes its variants module produces", () => {
+    for (const size of LIST_ROW_SIZES) {
+      for (const selected of [true, false]) {
+        const element = rendered(render(ListRow, { title: "reddb-01", size, selected }));
+        expect(classes(element)).toEqual(
+          classesOf(listRow({ size, selected, interactive: false }).root()),
+        );
+      }
+    }
+  });
+
+  it("defaults to the medium size, unselected", () => {
+    expect(classes(rendered(render(ListRow, { title: "reddb-01" })))).toEqual(
+      classesOf(listRow({ size: "md", selected: false, interactive: false }).root()),
+    );
+  });
+
+  it("says which row the list is about, where the platform has a word for it", () => {
+    const link = rendered(render(ListRow, { title: "reddb-01", href: "/nodes", selected: true }));
+    expect(link.getAttribute("aria-current")).toBe("true");
+    // On a <div> there is nothing to be current within, so the attribute would
+    // be noise rather than information.
+    const plain = rendered(render(ListRow, { title: "reddb-01", selected: true }));
+    expect(plain.getAttribute("aria-current")).toBeNull();
+  });
+
+  it("renders the title and description as two lines", () => {
+    const element = rendered(
+      render(ListRow, { title: "reddb-01", description: "eu-west-1 · leader" }),
+    );
+    const lines = [...element.querySelectorAll("span")].filter(
+      (span) => span.children.length === 0,
+    );
+    expect(lines.map((line) => line.textContent)).toEqual(["reddb-01", "eu-west-1 · leader"]);
+  });
+
+  it("lets a children snippet replace the title and description", () => {
+    const element = rendered(
+      render(ListRow, { title: "reddb-01", description: "ignored", children: text("Custom") }),
+    );
+    expect(element.textContent?.trim()).toBe("Custom");
+    expect(element.textContent).not.toContain("ignored");
+  });
+
+  it("renders the leading and trailing rails only when given one", () => {
+    const both = rendered(
+      render(ListRow, { title: "reddb-01", leading: text("●"), trailing: text("3") }),
+    );
+    expect(classes(both.firstElementChild!)).toEqual(classesOf(listRow({}).leading()));
+    expect(classes(both.lastElementChild!)).toEqual(classesOf(listRow({}).trailing()));
+
+    const neither = rendered(render(ListRow, { title: "reddb-01" }));
+    expect(neither.children.length).toBe(1);
+  });
+
+  it("merges a caller's classes over the root slot's own", () => {
+    const element = rendered(render(ListRow, { title: "reddb-01", class: "rounded-md" }));
+    expect(classes(element).has("rounded-md")).toBe(true);
+    expect(classes(element).has("flex")).toBe(true);
+  });
+
+  it("passes native attributes straight through", () => {
+    const element = rendered(render(ListRow, { title: "reddb-01", id: "row-1" }));
+    expect(element.id).toBe("row-1");
+  });
+});

package/vendor/ds/kits/app/test/main-ownership.test.ts

@@ -0,0 +1,56 @@
+// Who owns `<main>` (wave 5A, DESIGN.md "Landmarks"): ApplicationShell does.
+// A SidebarLayout or a second ApplicationShell inside it renders a plain
+// region, so composing them never yields a duplicate or a nested `main`.
+// SidebarLayout's `main` and ApplicationShell's `embedded` override the default.
+
+import { describe, expect, it } from "vitest";
+import MainOwnershipConsumer from "./fixtures/MainOwnershipConsumer.svelte";
+import { render } from "./mount";
+
+describe("main landmark ownership", () => {
+  it("gives the one <main> to the ApplicationShell around a SidebarLayout", () => {
+    const root = render(MainOwnershipConsumer, { case: "sidebar-in-shell" });
+    const mains = root.querySelectorAll("main");
+    const region = root.querySelector<HTMLElement>('[data-sidebar-layout-region="main"]')!;
+
+    expect(mains).toHaveLength(1);
+    expect(mains[0]!.matches('[data-application-shell-region="main"]')).toBe(true);
+    expect(region.tagName).toBe("DIV");
+    // No second "main-content": the region takes no id unless given one.
+    expect(region.hasAttribute("id")).toBe(false);
+    expect(root.querySelectorAll("#main-content")).toHaveLength(1);
+  });
+
+  it("lets SidebarLayout take <main> explicitly when the shell yields it", () => {
+    const root = render(MainOwnershipConsumer, { case: "sidebar-forced-main" });
+    const mains = root.querySelectorAll("main");
+
+    expect(mains).toHaveLength(1);
+    expect(mains[0]!.matches('[data-sidebar-layout-region="main"]')).toBe(true);
+    expect(mains[0]!.id).toBe("workspace");
+  });
+
+  it("lets an embedded shell's SidebarLayout render the one <main>: the shell claims nothing", () => {
+    const root = render(MainOwnershipConsumer, { case: "sidebar-in-embedded-shell" });
+    const mains = root.querySelectorAll("main");
+
+    expect(mains).toHaveLength(1);
+    expect(mains[0]!.matches('[data-sidebar-layout-region="main"]')).toBe(true);
+  });
+
+  it("embeds an ApplicationShell nested in another one", () => {
+    const root = render(MainOwnershipConsumer, { case: "shell-in-shell" });
+
+    expect(root.querySelectorAll("main")).toHaveLength(1);
+    expect(root.querySelector("#preview")?.tagName).toBe("DIV");
+  });
+
+  it("keeps a standalone SidebarLayout's <main>, and honours main={false}", () => {
+    const alone = render(MainOwnershipConsumer, { case: "sidebar-alone" });
+    expect(alone.querySelector("main")?.id).toBe("main-content");
+
+    const optOut = render(MainOwnershipConsumer, { case: "sidebar-opt-out" });
+    expect(optOut.querySelector("main")).toBeNull();
+    expect(optOut.querySelector('[data-sidebar-layout-region="main"]')?.tagName).toBe("DIV");
+  });
+});

package/vendor/ds/kits/app/test/markers.test.ts

@@ -0,0 +1,94 @@
+// The guard that keeps `tree-shaking.test.ts` honest, held against a catalogue
+// built to break it.
+//
+// That file measures a real build, so its own failures take two production
+// bundles to reach and read as bundle problems whatever their cause. The two
+// properties a marker map has to keep — every component measured, every marker
+// naming one component — are decided before any of that, from source text
+// alone, so they are decided here instead: against `test/fixtures/markers`,
+// two stand-in components that share an idiom and where only one is marked.
+//
+// What the fixture demonstrates is the red state. `fixture-chip` is in the
+// catalogue and absent from the marker map, exactly as `diff` was after #158,
+// and the first test below is the assertion that would have caught it the day
+// it landed.
+
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { componentOf, componentsWriting, coverage, emitters, kebab } from "./markers";
+
+const FIXTURES = join(import.meta.dirname, "fixtures", "markers");
+
+/** A catalogue of two components, the way the real one is read off disk. */
+const CATALOGUE = ["fixture-badge", "fixture-chip"];
+
+/** An idiom both stand-ins write, and so a string that attributes nothing. */
+const SHARED = "inline-flex rounded-full border";
+
+const sources = emitters([
+  join(FIXTURES, "fixture-badge.variants.ts"),
+  join(FIXTURES, "fixture-chip.variants.ts"),
+]);
+
+describe("a catalogue measured by a marker map", () => {
+  it("reports a component that was added without a marker", () => {
+    // The #158 shape: a component ships, the map is not extended, and every
+    // bundle assertion silently stops covering it.
+    expect(coverage(CATALOGUE, { FixtureBadge: "fixture-badge-cap" })).toEqual({
+      unmarked: ["fixture-chip"],
+      uncatalogued: [],
+    });
+  });
+
+  it("reports a marker left behind by a component that is gone", () => {
+    expect(
+      coverage(["fixture-badge"], { FixtureBadge: "fixture-badge-cap", FixtureChip: SHARED }),
+    ).toEqual({ unmarked: [], uncatalogued: ["fixture-chip"] });
+  });
+
+  it("is satisfied when the two lists name the same components", () => {
+    expect(
+      coverage(CATALOGUE, { FixtureBadge: "fixture-badge-cap", FixtureChip: "fixture-chip-cap" }),
+    ).toEqual({ unmarked: [], uncatalogued: [] });
+  });
+
+  it("compares the map's names in the catalogue's spelling", () => {
+    // The map is keyed the way a component is imported, the catalogue the way
+    // its files are named; a comparison that skipped the conversion would call
+    // every multi-word component uncovered.
+    expect(kebab("ProductQuickview")).toBe("product-quickview");
+    expect(kebab("Kbd")).toBe("kbd");
+  });
+});
+
+describe("a marker held against the source that can write it", () => {
+  it("names one component when only that component writes it", () => {
+    expect(componentsWriting("fixture-badge-cap", sources)).toEqual(["fixture-badge"]);
+  });
+
+  it("names both components when either can write it", () => {
+    // What a non-distinctive marker looks like from here, and the reason the
+    // real suite asserts a single name rather than a non-empty list: a bundle
+    // containing this string is evidence for neither component.
+    expect(componentsWriting(SHARED, sources)).toEqual(["fixture-badge", "fixture-chip"]);
+  });
+
+  it("names nothing when the marker has been edited out from under the map", () => {
+    expect(componentsWriting("fixture-badge-brim", sources)).toEqual([]);
+  });
+});
+
+describe("the component a source file belongs to", () => {
+  it("gathers every file that shares a stem", () => {
+    // A component puts class strings into a bundle from all of its files, so
+    // a marker written in one of them is that component's either way.
+    expect(["Kbd.svelte", "kbd.variants.ts"].map(componentOf)).toEqual(["kbd", "kbd"]);
+    expect(componentOf("dropdown-menu.behavior.ts")).toBe("dropdown-menu");
+  });
+
+  it("reads a PascalCase component file as its catalogue name", () => {
+    expect(componentOf(join("src", "composites", "ProductQuickview.svelte"))).toBe(
+      "product-quickview",
+    );
+  });
+});

package/vendor/ds/kits/app/test/markers.ts

@@ -0,0 +1,94 @@
+// What a marker has to be, written as functions instead of assertions.
+//
+// `tree-shaking.test.ts` attributes a bundle by looking in it for class
+// strings the Kits' components write. That reading — "the marker is here, so
+// the component is here" — only holds while two properties do:
+//
+//   coverage        every catalogued component has a marker, or the bundle
+//                   assertions quietly stop measuring the ones that do not;
+//   distinctiveness no marker can be written by a second component, or a hit
+//                   attributes the bundle to the wrong one.
+//
+// Both used to be asserted inline in that file and neither was itself tested,
+// which is how coverage drifted the moment Diff landed (#158) and stayed
+// drifted until the two lists were compared by eye. They live here so
+// `markers.test.ts` can hold them against a fixture catalogue built to break
+// them: a guard nothing exercises is a guard nobody knows the shape of.
+
+import { readFileSync } from "node:fs";
+import { basename } from "node:path";
+
+/** A marker map's key (`ProductQuickview`) as the catalogue names it. */
+export function kebab(name: string): string {
+  return name.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
+}
+
+/**
+ * The component a source file belongs to.
+ *
+ * A component is spread across files that share a stem — `Kbd.svelte`,
+ * `kbd.variants.ts`, `dropdown-menu.behavior.ts` — and every one of them can
+ * put a class string into a bundle, so every one of them counts as that
+ * component's output. Reading only the `.variants.ts` half would call a marker
+ * distinctive while a neighbour's markup writes it inline.
+ */
+export function componentOf(file: string): string {
+  const stem = basename(file)
+    .replace(/\.(svelte|ts)$/, "")
+    .replace(/\.(variants|behavior|appearance)$/, "");
+  return kebab(stem);
+}
+
+/** A source file, paired with the component it would put into a bundle. */
+export interface Emitter {
+  readonly component: string;
+  readonly text: string;
+}
+
+/** Read `files` once, so a whole marker map can be checked against them. */
+export function emitters(files: readonly string[]): Emitter[] {
+  return files.map((file) => ({
+    component: componentOf(file),
+    text: readFileSync(file, "utf8"),
+  }));
+}
+
+/**
+ * Every component whose own source writes `marker`, sorted.
+ *
+ * One is the only answer that lets a marker attribute a bundle. Two means the
+ * string is an idiom rather than a signature, and `bundle.includes(marker)`
+ * has started answering a question nobody asked; zero means the marker has
+ * been edited out from under the map and every assertion using it is vacuous.
+ */
+export function componentsWriting(marker: string, sources: readonly Emitter[]): string[] {
+  const writers = sources.filter((source) => source.text.includes(marker));
+  return [...new Set(writers.map((source) => source.component))].sort();
+}
+
+/** Where a catalogue and a marker map disagree about what is measured. */
+export interface Coverage {
+  /** Catalogued components no marker measures — a silent hole in the suite. */
+  readonly unmarked: string[];
+  /** Markers naming no catalogued component — a measurement of nothing. */
+  readonly uncatalogued: string[];
+}
+
+/**
+ * Compare the components that exist against the components that are measured.
+ *
+ * Reported as two lists rather than one equality, because the two failures
+ * want different repairs: something added to the Kit needs a marker, and a
+ * marker left behind by a removed component needs deleting.
+ */
+export function coverage(
+  catalogue: readonly string[],
+  markers: Readonly<Record<string, string>>,
+): Coverage {
+  const marked = new Set(Object.keys(markers).map(kebab));
+  const catalogued = new Set(catalogue);
+  return {
+    unmarked: [...catalogued].filter((name) => !marked.has(name)).sort(),
+    uncatalogued: [...marked].filter((name) => !catalogued.has(name)).sort(),
+  };
+}

package/vendor/ds/kits/app/test/menubar.test.ts

@@ -0,0 +1,93 @@
+import { flushSync, tick } from "svelte";
+import { describe, expect, it } from "vitest";
+import { Menubar, menubar, type MenubarMenu } from "../src/index";
+import TestGlyph from "./fixtures/TestGlyph.svelte";
+import { classes, classesOf, render } from "./mount";
+
+const MENUS: readonly MenubarMenu[] = [
+  { id: "file", label: "File", items: [{ id: "new", label: "New file" }, { id: "open", label: "Open" }] },
+  { id: "edit", label: "Edit", items: [{ id: "undo", label: "Undo" }] },
+];
+
+async function settle(): Promise<void> {
+  await tick();
+  await new Promise((resolve) => setTimeout(resolve, 10));
+  flushSync();
+}
+
+function press(element: Element, key: string): void {
+  element.dispatchEvent(new KeyboardEvent("keydown", { key, bubbles: true, cancelable: true }));
+  flushSync();
+}
+
+describe("the application Menubar", () => {
+  it("renders shared icon items through aligned decorative slots", async () => {
+    const root = render(Menubar, {
+      label: "Editor commands",
+      menus: [
+        {
+          id: "file",
+          label: "File",
+          items: [
+            { id: "new", label: "New", icon: TestGlyph },
+            { id: "open", label: "Open" },
+          ],
+        },
+      ],
+      size: "lg",
+    });
+    const trigger = root.querySelector<HTMLElement>("[data-menubar-trigger]")!;
+    trigger.focus();
+    press(trigger, "Enter");
+    await settle();
+
+    const surface = document.querySelector<HTMLElement>("[data-menubar-surface]")!;
+    const rows = [...surface.querySelectorAll<HTMLElement>('[role="menuitem"]')];
+    const icon = rows[0]!.querySelector<SVGElement>("[data-icon]")!;
+    expect(icon.getAttribute("aria-hidden")).toBe("true");
+    expect(icon.getAttribute("width")).toBe("var(--reddb-spatial-icon-size-lg)");
+    expect(rows.map((row) => row.querySelector("[data-menu-item-icon]") !== null)).toEqual([
+      true,
+      true,
+    ]);
+    expect(
+      classes(rows[1]!.querySelector("[data-menu-item-icon]")!).has(
+        "size-[var(--reddb-spatial-icon-size-lg)]",
+      ),
+    ).toBe(true);
+    expect(rows.map((row) => row.textContent?.trim())).toEqual(["New", "Open"]);
+  });
+
+  it("provides one named horizontal menu with roving top-level focus", async () => {
+    const root = render(Menubar, { label: "Editor commands", menus: MENUS });
+    const bar = root.querySelector<HTMLElement>('[role="menubar"]')!;
+    const triggers = [...bar.querySelectorAll<HTMLElement>("[data-menubar-trigger]")];
+
+    expect(bar.getAttribute("aria-label")).toBe("Editor commands");
+    expect(triggers.filter((trigger) => trigger.tabIndex === 0)).toHaveLength(1);
+    triggers[0]!.focus();
+    press(triggers[0]!, "ArrowRight");
+    await settle();
+    expect(document.activeElement).toBe(triggers[1]);
+  });
+
+  it("opens a Popover-composed menu and selects its focused command", async () => {
+    const selected: string[] = [];
+    const root = render(Menubar, {
+      label: "Editor commands",
+      menus: [{ id: "file", label: "File", items: [{ id: "new", label: "New", onselect: () => selected.push("new") }] }],
+    });
+    const trigger = root.querySelector<HTMLElement>("[data-menubar-trigger]")!;
+    trigger.focus();
+    press(trigger, "Enter");
+    await settle();
+
+    const surface = document.querySelector<HTMLElement>("[data-menubar-surface]")!;
+    const item = surface.querySelector<HTMLElement>('[role="menuitem"]')!;
+    expect(classes(surface)).toEqual(classesOf(menubar().content()));
+    expect(document.activeElement).toBe(item);
+    press(item, "Enter");
+    await settle();
+    expect(selected).toEqual(["new"]);
+  });
+});

package/vendor/ds/kits/app/test/mount.ts

@@ -0,0 +1,86 @@
+// Mounting a Kit component the way an application does.
+//
+// Svelte 5's `mount` is the whole harness: it takes a component and a target
+// and gives back the instance, which is enough to render, interact and assert
+// against real DOM. No testing-library sits in between, deliberately — the
+// thing under test is a Primitive whose entire contract is "renders this
+// element, wearing these classes, passing everything else through", and that
+// contract is read off the DOM directly.
+
+import { afterEach, expect } from "vitest";
+import {
+  createRawSnippet,
+  flushSync,
+  mount,
+  unmount,
+  type Component,
+  type Snippet,
+} from "svelte";
+
+const mounted: { instance: Record<string, unknown>; target: HTMLElement }[] = [];
+
+/** Mount `component` with `props` into a fresh detached element. */
+export function render<Props extends Record<string, unknown>>(
+  component: Component<Props>,
+  props: Props = {} as Props,
+): HTMLElement {
+  const target = document.createElement("div");
+  document.body.appendChild(target);
+  const instance = mount(component, { target, props }) as Record<string, unknown>;
+  mounted.push({ instance, target });
+  flushSync();
+  return target;
+}
+
+/** The single root element the component rendered. */
+export function rendered(target: HTMLElement): HTMLElement {
+  const element = target.firstElementChild;
+  expect(element, "the component rendered no element").not.toBeNull();
+  return element as HTMLElement;
+}
+
+/**
+ * Click `element` and let Svelte settle before the assertions run.
+ *
+ * `element.click()` rather than a dispatched MouseEvent, because the platform's
+ * click steps are part of what is under test: a disabled control swallows a
+ * click there, and a synthetic event dispatched straight at the element would
+ * sail past that and prove the opposite of what it looks like it proves.
+ */
+export function click(element: HTMLElement): void {
+  element.click();
+  flushSync();
+}
+
+/** A class string as a set, so assertions never depend on class order. */
+export function classesOf(className: string): Set<string> {
+  return new Set(className.split(/\s+/).filter(Boolean));
+}
+
+/**
+ * The element's classes as a set.
+ *
+ * Read off the attribute rather than off `className`, because on an SVG
+ * element — such as an inline SVG — `className` is an
+ * `SVGAnimatedString` and not a string at all.
+ */
+export function classes(element: Element): Set<string> {
+  return classesOf(element.getAttribute("class") ?? "");
+}
+
+/** Content for a component's `children`, as a consumer's markup would be. */
+export function text(content: string): Snippet {
+  return createRawSnippet(() => ({ render: () => `<span>${content}</span>` }));
+}
+
+afterEach(async () => {
+  for (const { instance, target } of mounted.splice(0)) {
+    unmount(instance);
+    target.remove();
+  }
+
+  // Bits UI restores its shared body scroll lock 24ms after the final
+  // overlay is destroyed. Keep jsdom alive through that bounded cleanup so
+  // the callback cannot outlive the document when test files run in parallel.
+  await new Promise<void>((resolve) => window.setTimeout(resolve, 30));
+});

package/vendor/ds/kits/app/test/multi-column-layout.test.ts

@@ -0,0 +1,106 @@
+import { createRawSnippet } from "svelte";
+import { describe, expect, it } from "vitest";
+import MultiColumnLayout from "../src/composites/MultiColumnLayout.svelte";
+import { multiColumnLayout } from "../src/composites/multi-column-layout.variants";
+import ApplicationLayoutsConsumer from "./fixtures/ApplicationLayoutsConsumer.svelte";
+import { expectLayoutReadiness } from "./layout-readiness";
+import { classes, classesOf, render, rendered } from "./mount";
+
+const snippet = (html: string) => createRawSnippet(() => ({ render: () => html }));
+
+describe("MultiColumnLayout", () => {
+  it("arranges two named columns without taking ownership of their content", () => {
+    const layout = rendered(
+      render(MultiColumnLayout, {
+        start: snippet("<p>Filters</p>"),
+        children: snippet("<article>Deployments</article>"),
+      }),
+    );
+
+    expect(layout.dataset.columns).toBe("two");
+    expect([...layout.children].map((column) => column.getAttribute("data-column"))).toEqual([
+      "start",
+      "main",
+    ]);
+    expect(layout.querySelector('[data-column="start"]')?.textContent).toBe("Filters");
+    expect(layout.querySelector('[data-column="main"] article')?.textContent).toBe(
+      "Deployments",
+    );
+  });
+
+  it("adds the optional end column as the canonical three-column arrangement", () => {
+    const layout = rendered(
+      render(MultiColumnLayout, {
+        start: snippet("<p>Navigation</p>"),
+        children: snippet("<p>Workspace</p>"),
+        end: snippet("<p>Inspector</p>"),
+      }),
+    );
+
+    expect(layout.dataset.columns).toBe("three");
+    expect([...layout.children].map((column) => column.getAttribute("data-column"))).toEqual([
+      "start",
+      "main",
+      "end",
+    ]);
+    expect(classes(layout)).toEqual(classesOf(multiColumnLayout({ columns: "three" }).root()));
+  });
+
+  it("preserves document and keyboard order across the visual columns", () => {
+    const layout = rendered(
+      render(MultiColumnLayout, {
+        start: snippet('<button type="button">First</button>'),
+        children: snippet('<button type="button">Second</button>'),
+        end: snippet('<button type="button">Third</button>'),
+      }),
+    );
+
+    expect([...layout.querySelectorAll("button")].map((button) => button.textContent)).toEqual([
+      "First",
+      "Second",
+      "Third",
+    ]);
+    expect([...layout.querySelectorAll("button")].every((button) => button.tabIndex === 0)).toBe(
+      true,
+    );
+  });
+
+  it("composes canonical Stacks and leaves Density live in every column", () => {
+    const layout = rendered(
+      render(MultiColumnLayout, {
+        gap: "sm",
+        start: snippet("<p>One</p>"),
+        children: snippet("<p>Two</p>"),
+        end: snippet("<p>Three</p>"),
+      }),
+    );
+
+    expect(classes(layout).has("gap-[var(--reddb-spatial-layout-gap-md)]")).toBe(true);
+    for (const column of layout.querySelectorAll<HTMLElement>("[data-column]")) {
+      expect(column.hasAttribute("data-stack")).toBe(true);
+      expect(classes(column).has("gap-[var(--reddb-spatial-gap-sm)]")).toBe(true);
+      expect(column.hasAttribute("data-density")).toBe(false);
+    }
+  });
+
+  it("passes native attributes, merges classes, and inherits nested appearance", () => {
+    const layout = rendered(
+      render(MultiColumnLayout, { id: "columns", class: "relative" }),
+    );
+    expect(layout.id).toBe("columns");
+    expect(classes(layout)).toEqual(
+      classesOf(multiColumnLayout({ columns: "two" }).root({ class: "relative" })),
+    );
+
+    const consumer = render(ApplicationLayoutsConsumer);
+    const nested = consumer.querySelector<HTMLElement>("[data-multi-column-layout]")!;
+    expect(nested.closest('[data-density="compact"]')).not.toBeNull();
+    expect(nested.hasAttribute("data-theme")).toBe(false);
+    expect(nested.hasAttribute("data-color-scheme")).toBe(false);
+    expect(nested.hasAttribute("data-density")).toBe(false);
+  });
+
+  it("ships complete showcase, consumer, distributed export, and readiness evidence", () => {
+    expectLayoutReadiness("multi-column-layout", "MultiColumnLayout");
+  });
+});