@multiplatform.one/forms 7.4.1 → 7.6.0

package/src/DescriptionList/DescriptionList.spec.tsx

@@ -0,0 +1,254 @@
+/**
+ * @vitest-environment jsdom
+ */
+
+import { act } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+import { Preset } from "@multiplatform.one/theme";
+import { FORM_GRID_COLLAPSE_WIDTH } from "../FormGrid";
+import { EMPTY, formatDateText, formatNumericText } from "../FieldDisplay/formatters";
+import { DescriptionList, PropertyList } from "./index";
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+  vi.restoreAllMocks();
+});
+
+function stubContainerWidth(width: number) {
+  vi.spyOn(HTMLElement.prototype, "getBoundingClientRect").mockReturnValue({
+    width,
+    height: 100,
+    top: 0,
+    left: 0,
+    right: width,
+    bottom: 100,
+    x: 0,
+    y: 0,
+    toJSON: () => ({}),
+  } as DOMRect);
+
+  vi.stubGlobal(
+    "ResizeObserver",
+    class {
+      cb: ResizeObserverCallback;
+      constructor(cb: ResizeObserverCallback) {
+        this.cb = cb;
+      }
+      observe(target: Element) {
+        this.cb(
+          [
+            {
+              target,
+              contentRect: { width } as DOMRectReadOnly,
+              borderBoxSize: [],
+              contentBoxSize: [],
+              devicePixelContentBoxSize: [],
+            } as ResizeObserverEntry,
+          ],
+          this as unknown as ResizeObserver,
+        );
+      }
+      unobserve() {}
+      disconnect() {}
+    },
+  );
+}
+
+function list(root: HTMLElement) {
+  return root.querySelector("[data-mpo-description-list]") as HTMLElement | null;
+}
+
+function host(root: HTMLElement) {
+  return root.querySelector("[data-mpo-description-list-host]") as HTMLElement | null;
+}
+
+describe("DescriptionList", () => {
+  it("composes FieldDisplay for each typed row — never a parallel formatter (LC-12)", () => {
+    const created = new Date(2025, 6, 1);
+    const result = renderWithProviders(
+      <DescriptionList
+        placement="side"
+        items={[
+          { term: "Hostname", field: "input", value: "compose01.hel1.hetzner" },
+          {
+            term: "Status",
+            field: "select",
+            value: "active",
+            fieldProps: { options: [{ label: "Active", value: "active", color: "green" }] },
+          },
+          { term: "Created", field: "datepicker", value: created },
+          {
+            term: "Monthly cost",
+            field: "stepper",
+            value: 38.4,
+            fieldProps: { currency: "EUR", precision: 2 },
+          },
+          { term: "Decommissioned", field: "input", value: null },
+        ]}
+      />,
+    );
+
+    const displays = result.container.querySelectorAll("[data-component='FieldDisplay']");
+    expect(displays).toHaveLength(5);
+    expect(displays[0]?.getAttribute("data-field")).toBe("input");
+    expect(displays[1]?.getAttribute("data-field")).toBe("select");
+    expect(displays[2]?.getAttribute("data-field")).toBe("datepicker");
+    expect(displays[3]?.getAttribute("data-field")).toBe("stepper");
+    expect(displays[3]?.textContent).toBe(
+      formatNumericText(38.4, { currency: "EUR", precision: 2 }),
+    );
+    expect(displays[2]?.textContent).toBe(formatDateText(created));
+    expect(displays[2]?.textContent).not.toMatch(/\d{4}-\d{2}-\d{2}/);
+    expect(result.container.textContent).toContain("Active");
+    expect(result.container.textContent).not.toMatch(/\bactive\b/);
+    expect(displays[4]?.textContent).toBe(EMPTY);
+    expect(result.container.textContent).toContain("Hostname");
+  });
+
+  it("collapses a side list to stacked when the container is under 480", () => {
+    stubContainerWidth(280);
+    let result!: ReturnType<typeof renderWithProviders>;
+    act(() => {
+      result = renderWithProviders(
+        <DescriptionList
+          placement="side"
+          items={[
+            { term: "Hostname", field: "input", value: "compose01", onChange: () => undefined },
+            { term: "Region", field: "input", value: "hel1" },
+          ]}
+        />,
+      );
+    });
+    const root = list(result.container);
+    expect(root?.getAttribute("data-placement")).toBe("side");
+    expect(root?.getAttribute("data-stacked")).toBe("true");
+  });
+
+  it("keeps a side list in columns when the container is at least 480", () => {
+    stubContainerWidth(FORM_GRID_COLLAPSE_WIDTH + 40);
+    let result!: ReturnType<typeof renderWithProviders>;
+    act(() => {
+      result = renderWithProviders(
+        <DescriptionList
+          placement="side"
+          items={[{ term: "Hostname", field: "input", value: "compose01" }]}
+        />,
+      );
+    });
+    const root = list(result.container);
+    expect(root?.getAttribute("data-stacked")).toBe("false");
+    expect(root?.style.gridTemplateColumns).toContain("min(max-content, 24ch)");
+  });
+
+  it("the optional Change action is a keyboard-reachable button", () => {
+    const onChange = vi.fn();
+    const result = renderWithProviders(
+      <DescriptionList
+        placement="top"
+        items={[
+          {
+            term: "Hostname",
+            field: "input",
+            value: "compose01",
+            onChange,
+          },
+        ]}
+      />,
+    );
+    const action = result.container.querySelector(
+      "[data-mpo-description-list-action] [role='button'], [data-mpo-description-list-action] button",
+    ) as HTMLElement | null;
+    expect(action).not.toBeNull();
+    expect(action?.getAttribute("aria-disabled")).not.toBe("true");
+    expect(action?.textContent).toContain("Change");
+    expect(Number(action?.getAttribute("tabindex") ?? "0")).toBeGreaterThanOrEqual(0);
+    action?.click();
+    expect(onChange).toHaveBeenCalledTimes(1);
+  });
+
+  it("FieldDisplay slots are chromeless and start-align numbers (LC-39 / LC-44)", () => {
+    const result = renderWithProviders(
+      <DescriptionList
+        placement="top"
+        items={[
+          {
+            term: "Count",
+            field: "stepper",
+            value: 47,
+          },
+        ]}
+      />,
+    );
+    const display = result.container.querySelector(
+      "[data-component='FieldDisplay']",
+    ) as HTMLElement | null;
+    expect(display?.hasAttribute("data-chromeless")).toBe(true);
+    expect(display?.textContent).toBe(formatNumericText(47));
+    const valueText = display?.querySelector("*");
+    const align = valueText ? getComputedStyle(valueText).textAlign : "";
+    expect(align === "left" || align === "start" || align === "").toBe(true);
+  });
+
+  it("top placement is stacked without a container measure", () => {
+    const result = renderWithProviders(
+      <DescriptionList
+        placement="top"
+        items={[{ term: "Owner", field: "input", value: "Clay" }]}
+      />,
+    );
+    expect(list(result.container)?.getAttribute("data-stacked")).toBe("true");
+  });
+
+  it("PropertyList is the DescriptionList alias", () => {
+    expect(PropertyList).toBe(DescriptionList);
+  });
+
+  it("framed variant paints a surface (LC-39 earned inset)", () => {
+    const result = renderWithProviders(
+      <DescriptionList
+        framed
+        placement="top"
+        items={[{ term: "Host", field: "input", value: "a" }]}
+      />,
+    );
+    expect(list(result.container)?.getAttribute("data-framed")).toBe("true");
+    expect(host(result.container)).not.toBeNull();
+  });
+
+  it("quiet separators mark the list", () => {
+    const result = renderWithProviders(
+      <DescriptionList
+        quiet
+        placement="top"
+        items={[
+          { term: "A", field: "input", value: "1" },
+          { term: "B", field: "input", value: "2" },
+        ]}
+      />,
+    );
+    expect(list(result.container)?.getAttribute("data-quiet")).toBe("true");
+    expect(result.container.querySelectorAll("[data-mpo-description-list-rule]").length).toBe(1);
+  });
+
+  it("rides fieldLabelPlacement=top from the preset when placement is omitted", () => {
+    const result = renderWithProviders(
+      <Preset overrides={{ fieldLabelPlacement: "top" }}>
+        <DescriptionList items={[{ term: "A", field: "input", value: "1" }]} />
+      </Preset>,
+    );
+    expect(list(result.container)?.getAttribute("data-placement")).toBe("top");
+    expect(list(result.container)?.getAttribute("data-stacked")).toBe("true");
+  });
+
+  it("compact density marks the list", () => {
+    const result = renderWithProviders(
+      <DescriptionList
+        compact
+        placement="top"
+        items={[{ term: "A", field: "input", value: "1" }]}
+      />,
+    );
+    expect(list(result.container)?.getAttribute("data-compact")).toBe("true");
+  });
+});

package/src/DescriptionList/DescriptionList.stories.tsx

@@ -0,0 +1,244 @@
+import type { Meta, StoryObj } from "@storybook/react-native-web-vite";
+import { Paragraph, YStack } from "tamagui";
+import { FormGrid } from "../FormGrid";
+import { FormSection, FormSectionStack } from "../FormSection";
+import { DescriptionList, type DescriptionListItem } from "./index";
+
+const meta: Meta<typeof DescriptionList> = {
+  title: "Forms/DescriptionList",
+  component: DescriptionList,
+  parameters: { status: { type: "beta" } },
+  argTypes: {
+    placement: { control: "radio", options: ["side", "top"] },
+    compact: { control: "boolean" },
+    framed: { control: "boolean" },
+    quiet: { control: "boolean" },
+  },
+  args: {
+    placement: "side",
+    compact: false,
+    framed: false,
+    quiet: false,
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof DescriptionList>;
+
+const HOST: DescriptionListItem[] = [
+  {
+    term: "Hostname",
+    field: "input",
+    value: "compose01.hel1.hetzner",
+    onChange: () => undefined,
+  },
+  {
+    term: "Status",
+    field: "select",
+    value: "active",
+    fieldProps: { options: [{ label: "Active", value: "active", color: "green" }] },
+  },
+  {
+    term: "Region",
+    field: "input",
+    value: "hel1 · Helsinki",
+    onChange: () => undefined,
+  },
+  { term: "Instance ID", field: "input", value: "i-0f9c2a7d44e1b6c83" },
+  {
+    term: "Monthly cost",
+    field: "stepper",
+    value: 38.4,
+    fieldProps: { currency: "EUR", precision: 2 },
+  },
+  { term: "Created", field: "datepicker", value: new Date(2025, 6, 1) },
+  { term: "Owner", field: "input", value: "Clay Risser", onChange: () => undefined },
+  {
+    term: "Notes",
+    field: "textarea",
+    value:
+      "Nightly restic snapshot to hz-s3. Retention 30 days, prune weekly. Verify runs first Monday of the month.",
+  },
+  {
+    term: "Docs",
+    field: "input",
+    value: "https://docs.selfhostedcloud.org/stacks/compose01",
+  },
+  { term: "Decommissioned", field: "input", value: null },
+];
+
+export const Anatomy: Story = {
+  name: "Anatomy — term · value · Change",
+  render: (args) => <DescriptionList {...args} items={HOST} />,
+};
+
+export const SideDefault: Story = {
+  name: "Side (record register)",
+  render: () => (
+    <DescriptionList placement="side" items={HOST.map(({ onChange: _onChange, ...row }) => row)} />
+  ),
+};
+
+export const TopPlacement: Story = {
+  name: "Top — fieldLabelPlacement=top",
+  render: () => <DescriptionList placement="top" items={HOST} />,
+};
+
+export const CollapseNarrow: Story = {
+  name: "Container under 480 auto-stacks",
+  render: () => (
+    <YStack width={280} borderWidth={1} borderColor="$borderColor" padding="$3">
+      <DescriptionList
+        placement="side"
+        maxWidth="fluid"
+        items={[
+          {
+            term: "Hostname",
+            field: "input",
+            value: "compose01.hel1.hetzner",
+            onChange: () => undefined,
+          },
+          {
+            term: "Status",
+            field: "select",
+            value: "active",
+            fieldProps: { options: [{ label: "Active", value: "active", color: "green" }] },
+          },
+          {
+            term: "Instance ID",
+            field: "input",
+            value: "i-0f9c2a7d44e1b6c83",
+            truncate: true,
+          },
+        ]}
+      />
+    </YStack>
+  ),
+};
+
+export const RecordPage: Story = {
+  name: "Record page — FormSection + FormGrid",
+  render: () => (
+    <FormGrid columns={2}>
+      <FormSectionStack>
+        <FormSection label="Host">
+          <DescriptionList maxWidth="fluid" placement="side" items={HOST.slice(0, 6)} />
+        </FormSection>
+      </FormSectionStack>
+      <FormSectionStack>
+        <FormSection label="Backups">
+          <DescriptionList
+            maxWidth="fluid"
+            placement="side"
+            items={[
+              {
+                term: "Schedule",
+                field: "select",
+                value: "weekly",
+                fieldProps: { options: [{ label: "Weekly", value: "weekly" }] },
+              },
+              {
+                term: "Last run",
+                field: "datetimepicker",
+                value: new Date(2026, 7, 26, 3, 30),
+              },
+              {
+                term: "Window",
+                field: "daterangepicker",
+                value: new Date(2025, 6, 1),
+                linkedValue: new Date(2026, 7, 28),
+              },
+              { term: "Encrypted", field: "checkbox", value: true },
+              { term: "Disk used", field: "progress", value: 62, fieldProps: { max: 100 } },
+            ]}
+          />
+        </FormSection>
+        <FormSection label="Access">
+          <DescriptionList
+            maxWidth="fluid"
+            placement="side"
+            items={[
+              { term: "Owner", field: "input", value: "Clay Risser", onChange: () => undefined },
+              {
+                term: "Team",
+                field: "combobox",
+                value: ["infra", "ops"],
+                fieldProps: {
+                  options: [
+                    { label: "infra", value: "infra", color: "blue" },
+                    { label: "ops", value: "ops" },
+                  ],
+                },
+              },
+              {
+                term: "Docs",
+                field: "input",
+                value: "https://docs.selfhostedcloud.org/stacks/compose01",
+              },
+            ]}
+          />
+        </FormSection>
+      </FormSectionStack>
+    </FormGrid>
+  ),
+};
+
+export const FramedAndQuiet: Story = {
+  render: () => (
+    <YStack gap="$5" maxWidth={560}>
+      <Paragraph size="$2">Framed — Card paints, so it earns the inset</Paragraph>
+      <DescriptionList
+        framed
+        placement="side"
+        items={HOST.slice(0, 4).map(({ onChange: _onChange, ...row }) => row)}
+      />
+      <Paragraph size="$2">Quiet separators — 1px at opacity .5</Paragraph>
+      <DescriptionList
+        quiet
+        placement="side"
+        items={HOST.slice(0, 4).map(({ onChange: _onChange, ...row }) => row)}
+      />
+    </YStack>
+  ),
+};
+
+export const Slots: Story = {
+  name: "FieldDisplay slots (LC-12)",
+  render: () => (
+    <DescriptionList
+      placement="side"
+      items={[
+        { term: "Data", field: "input", value: "compose01.hel1.hetzner" },
+        {
+          term: "Long Text",
+          field: "textarea",
+          value: "Nightly restic snapshot to hz-s3. Retention 30 days, prune weekly.",
+        },
+        { term: "Int", field: "stepper", value: 47 },
+        {
+          term: "Currency",
+          field: "stepper",
+          value: 38.4,
+          fieldProps: { currency: "EUR", precision: 2 },
+        },
+        { term: "Date", field: "datepicker", value: new Date(2025, 6, 1) },
+        { term: "Check", field: "checkbox", value: true },
+        {
+          term: "Select",
+          field: "select",
+          value: "weekly",
+          fieldProps: { options: [{ label: "Weekly", value: "weekly" }] },
+        },
+        { term: "Color", field: "colorpicker", value: "#3d8f5e" },
+        { term: "Percent", field: "progress", value: 88, fieldProps: { max: 100 } },
+        { term: "Attach", field: "fileupload", value: "compose01-backup.tar.gz" },
+        { term: "URL", field: "input", value: "https://status.selfhostedcloud.org" },
+        { term: "Empty", field: "input", value: null },
+      ]}
+    />
+  ),
+};
+
+export const Compact: Story = {
+  render: () => <DescriptionList compact placement="side" items={HOST.slice(0, 3)} />,
+};