@elabs-ai/components-ui 4.2.0 → 5.0.0

package/src/components/progress/progress.test.tsx

@@ -32,4 +32,51 @@ describe("Progress", () => {
       "Exceeded — 100 of 100",
     );
   });
+
+  // marker (pace / target reference tick)
+  it("renders no tick and leaves the DOM unchanged when marker is unset", () => {
+    const { container } = render(<Progress value={40} />);
+    expect(container.querySelector('[data-slot="progress-marker"]')).toBeNull();
+    // The Indicator stays the progressbar's direct child (no wrapper added).
+    const directChild = container.querySelector('[role="progressbar"] > *');
+    expect(directChild).toHaveAttribute("data-slot", "progress-indicator");
+  });
+
+  it("positions the tick at marker% via insetInlineStart", () => {
+    const { container } = render(<Progress value={40} marker={70} />);
+    const tick = container.querySelector('[data-slot="progress-marker"]');
+    expect(tick).toHaveStyle({ insetInlineStart: "70%" });
+  });
+
+  it("clamps marker to 0–100", () => {
+    const { container } = render(<Progress value={40} marker={140} />);
+    const tick = container.querySelector('[data-slot="progress-marker"]');
+    expect(tick).toHaveStyle({ insetInlineStart: "100%" });
+  });
+
+  it("is decorative and leaves aria-valuetext unchanged when markerLabel is absent", () => {
+    render(<Progress value={62} marker={70} />);
+    const progressbar = screen.getByRole("progressbar");
+    expect(progressbar).not.toHaveAttribute("aria-valuetext");
+  });
+
+  it("composes aria-valuetext from value + markerLabel when both marker and markerLabel are set", () => {
+    render(<Progress value={62} marker={70} markerLabel="expected 70% by today" />);
+    expect(screen.getByRole("progressbar")).toHaveAttribute(
+      "aria-valuetext",
+      "62%, expected 70% by today",
+    );
+  });
+
+  it("lets a caller-supplied aria-valuetext win over the composed marker text", () => {
+    render(
+      <Progress
+        aria-valuetext="Custom text"
+        marker={70}
+        markerLabel="expected 70% by today"
+        value={62}
+      />,
+    );
+    expect(screen.getByRole("progressbar")).toHaveAttribute("aria-valuetext", "Custom text");
+  });
 });

package/src/components/progress/progress.tsx

@@ -23,7 +23,25 @@ export const progressIndicatorVariants = cva("size-full flex-1 transition-transf
 export interface ProgressProps
   extends
     ComponentPropsWithoutRef<typeof ProgressPrimitive.Root>,
-    VariantProps<typeof progressIndicatorVariants> {}
+    VariantProps<typeof progressIndicatorVariants> {
+  /**
+   * Reference point (0–100, same scale as `value`) — e.g. an "expected by
+   * today" pace or a target — rendered as a thin vertical tick on the track.
+   * Unset (default) renders no tick and leaves the DOM/layout byte-identical
+   * to a marker-less `Progress`.
+   */
+  marker?: number;
+  /**
+   * What `marker` represents (already localized by the caller — e.g.
+   * `"expected 70% by today"`). When set, it is appended to the progress
+   * bar's accessible value text so assistive tech hears the reference point
+   * alongside the value; a caller-supplied `aria-valuetext` always wins over
+   * this composition. When `marker` is set but `markerLabel` is not, the
+   * tick is purely decorative and `aria-valuetext` is left untouched — this
+   * component never invents its own English copy (i18n-strings).
+   */
+  markerLabel?: string;
+}
 
 /**
  * Color must not be the only signal a guardrail tripped: set `aria-valuetext`
@@ -32,12 +50,27 @@ export interface ProgressProps
  * `...props` (Radix's `ProgressPrimitive.Root` already supports it).
  */
 export const Progress = forwardRef<ElementRef<typeof ProgressPrimitive.Root>, ProgressProps>(
-  function Progress({ className, value, variant, ...props }, ref) {
-    return (
+  function Progress(
+    { className, value, variant, marker, markerLabel, "aria-valuetext": ariaValuetext, ...props },
+    ref,
+  ) {
+    const hasMarker = typeof marker === "number" && Number.isFinite(marker);
+    const clampedMarker = hasMarker ? Math.min(100, Math.max(0, marker as number)) : undefined;
+    // No invented English glue words (i18n-strings) — just the numeric value
+    // plus the caller's own, already-localized `markerLabel`. A caller's own
+    // `aria-valuetext` always wins and is never overwritten.
+    const resolvedValuetext =
+      ariaValuetext ??
+      (hasMarker && markerLabel && typeof value === "number"
+        ? `${Math.round(value)}%, ${markerLabel}`
+        : undefined);
+
+    const root = (
       <ProgressPrimitive.Root
         ref={ref}
         data-slot="progress"
         value={value}
+        aria-valuetext={resolvedValuetext}
         className={cn("relative h-2 w-full overflow-hidden rounded-full bg-muted", className)}
         {...props}
       >
@@ -48,5 +81,26 @@ export const Progress = forwardRef<ElementRef<typeof ProgressPrimitive.Root>, Pr
         />
       </ProgressPrimitive.Root>
     );
+
+    if (!hasMarker) {
+      return root;
+    }
+
+    return (
+      // Root keeps `overflow-hidden` (clips the indicator fill, unchanged
+      // above); the tick lives OUTSIDE it as a sibling so it is never
+      // clipped. The wrapper mirrors `className` so it matches the track's
+      // own box exactly (width/height/flex sizing), which is what the
+      // tick's `insetInlineStart` percentage is measured against.
+      <div className={cn("relative", className)}>
+        {root}
+        <span
+          aria-hidden={markerLabel ? undefined : "true"}
+          className="pointer-events-none absolute -top-0.5 -bottom-0.5 w-0.5 bg-foreground"
+          data-slot="progress-marker"
+          style={{ insetInlineStart: `${clampedMarker}%` }}
+        />
+      </div>
+    );
   },
 );

package/src/components/reveal-on-enter/index.ts

@@ -0,0 +1,5 @@
+export {
+  RevealOnEnter,
+  type RevealOnEnterElement,
+  type RevealOnEnterProps,
+} from "./reveal-on-enter";

package/src/components/reveal-on-enter/reveal-on-enter.css

@@ -0,0 +1,32 @@
+/*
+ * RevealOnEnter — once-only entrance. The server HTML never carries the hidden state: the
+ * component sets `data-reveal="hidden"` only after hydration, only when the motion gate is open,
+ * only for content still outside the viewport, and flips it to "shown" the first time it
+ * intersects (never back). Timing and easing are the gated tokens (`--t-base`,
+ * `--ease-entrance`); the stagger step scales with `--motion-factor`. `opacity`/`transform` only.
+ */
+@layer base {
+  [data-slot="reveal-on-enter"] {
+    /* Per-child delay step for `stagger`; multiplied by --motion-factor below. */
+    --reveal-stagger-step: 60ms;
+  }
+
+  [data-slot="reveal-on-enter"][data-reveal]:not([data-stagger]),
+  [data-slot="reveal-on-enter"][data-reveal][data-stagger] > * {
+    transition-property: opacity, transform;
+    transition-duration: var(--t-base);
+    transition-timing-function: var(--ease-entrance);
+  }
+
+  [data-slot="reveal-on-enter"][data-reveal][data-stagger] > * {
+    transition-delay: calc(
+      var(--reveal-index, 0) * var(--reveal-stagger-step) * var(--motion-factor)
+    );
+  }
+
+  [data-slot="reveal-on-enter"][data-reveal="hidden"]:not([data-stagger]),
+  [data-slot="reveal-on-enter"][data-reveal="hidden"][data-stagger] > * {
+    opacity: 0;
+    transform: translateY(24px);
+  }
+}

package/src/components/reveal-on-enter/reveal-on-enter.stories.tsx

@@ -0,0 +1,100 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { expect, waitFor } from "storybook/test";
+import { Card, CardDescription, CardHeader, CardTitle } from "../card";
+import { RevealOnEnter } from "./reveal-on-enter";
+
+const ITEMS = [
+  {
+    id: "once",
+    title: "Once",
+    description: "Content reveals the first time it enters, never again.",
+  },
+  { id: "visible", title: "Visible first", description: "The server HTML is fully visible." },
+  { id: "gated", title: "Gated", description: "Reduced motion shows everything at once." },
+];
+
+function Reveals({ stagger = false }: { stagger?: boolean }) {
+  return (
+    <div className="p-8">
+      <p className="text-body text-muted-foreground">Scroll down to reveal the cards.</p>
+      <div className="min-h-screen" />
+      <RevealOnEnter as="ul" stagger={stagger} className="grid gap-6 sm:grid-cols-3">
+        {ITEMS.map((item) => (
+          <li key={item.id}>
+            <Card>
+              <CardHeader>
+                <CardTitle>{item.title}</CardTitle>
+                <CardDescription>{item.description}</CardDescription>
+              </CardHeader>
+            </Card>
+          </li>
+        ))}
+      </RevealOnEnter>
+      <div className="min-h-96" />
+    </div>
+  );
+}
+
+const meta = {
+  title: "Display/RevealOnEnter",
+  component: RevealOnEnter,
+  parameters: { layout: "fullscreen" },
+  tags: ["autodocs"],
+  render: () => <Reveals />,
+} satisfies Meta<typeof RevealOnEnter>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/** Names a running animation so a failing reduced-motion play says what still moves. */
+function describeAnimation(a: Animation) {
+  const effect = a.effect as KeyframeEffect | null;
+  const target = effect?.target as Element | null | undefined;
+  const name = (a as CSSAnimation).animationName ?? (a as CSSTransition).transitionProperty ?? a.id;
+  return `${name} on ${target?.getAttribute("data-slot") ?? target?.tagName ?? "?"}${effect?.pseudoElement ?? ""}`;
+}
+
+export const Default: Story = {
+  play: async ({ canvasElement }) => {
+    const el = canvasElement.querySelector<HTMLElement>('[data-slot="reveal-on-enter"]')!;
+    el.scrollIntoView();
+    await waitFor(() => expect(el.getAttribute("data-reveal")).not.toBe("hidden"));
+  },
+};
+
+/** Each child reveals 60 ms × `--motion-factor` after the one before. */
+export const Stagger: Story = {
+  render: () => <Reveals stagger />,
+};
+
+export const Dark: Story = {
+  parameters: { themes: { themeOverride: "dark" } },
+};
+
+export const Decoration10: Story = {
+  globals: { decoration: "10" },
+};
+
+/** Under reduced motion nothing is ever hidden and nothing animates. */
+export const ReducedMotion: Story = {
+  // The real gate on :root (Storybook motion toolbar) plus a subtree dial, because the toolbar
+  // writes :root after the story has mounted.
+  globals: { motionPref: "reduced" },
+  render: () => (
+    <div data-motion-pref="reduced">
+      <Reveals stagger />
+    </div>
+  ),
+  play: async ({ canvasElement }) => {
+    await expect(canvasElement.querySelector("[data-reveal]")).toBeNull();
+    // Transitions the harness started before the gate applied (theme/decoration swaps between
+    // stories) settle; a primitive that still animates under the gate never would.
+    await waitFor(() =>
+      expect(
+        document
+          .getAnimations()
+          .filter((a) => a.playState === "running")
+          .map(describeAnimation),
+      ).toEqual([]),
+    );
+  },
+};

package/src/components/reveal-on-enter/reveal-on-enter.test.tsx

@@ -0,0 +1,87 @@
+import type * as React from "react";
+import { act, render } from "@testing-library/react";
+import { renderToString } from "react-dom/server";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { RevealOnEnter } from "./reveal-on-enter";
+
+type ObserverCallback = (entries: Array<{ isIntersecting: boolean }>) => void;
+let fire: ObserverCallback = () => {};
+
+function stubObserver() {
+  vi.stubGlobal(
+    "IntersectionObserver",
+    class {
+      constructor(cb: ObserverCallback) {
+        fire = cb;
+      }
+      observe() {}
+      disconnect() {}
+    },
+  );
+}
+
+function belowTheFold(el: Element) {
+  vi.spyOn(el, "getBoundingClientRect").mockReturnValue({ top: 5000, bottom: 5100 } as DOMRect);
+}
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+  vi.restoreAllMocks();
+  document.documentElement.style.removeProperty("--motion-factor");
+});
+
+describe("RevealOnEnter", () => {
+  it("server-renders its children fully visible", () => {
+    const html = renderToString(
+      <RevealOnEnter as="section" stagger>
+        <p>One</p>
+        <p>Two</p>
+      </RevealOnEnter>,
+    );
+    expect(html).toContain("<section");
+    expect(html).toContain("One");
+    expect(html).not.toMatch(/opacity|hidden|data-reveal/);
+  });
+
+  it("hides off-screen content after hydration and reveals it once", () => {
+    stubObserver();
+    const proto = HTMLElement.prototype;
+    belowTheFold(proto);
+    const { container } = render(<RevealOnEnter>Hello</RevealOnEnter>);
+    const el = container.firstElementChild!;
+    expect(el).toHaveAttribute("data-reveal", "hidden");
+    act(() => fire([{ isIntersecting: true }]));
+    expect(el).toHaveAttribute("data-reveal", "shown");
+    act(() => fire([{ isIntersecting: false }]));
+    expect(el).toHaveAttribute("data-reveal", "shown");
+  });
+
+  it("indexes children for the stagger", () => {
+    stubObserver();
+    belowTheFold(HTMLElement.prototype);
+    const { container } = render(
+      <RevealOnEnter stagger>
+        <p>One</p>
+        <p>Two</p>
+      </RevealOnEnter>,
+    );
+    const second = container.querySelectorAll("p")[1]!;
+    expect(second.style.getPropertyValue("--reveal-index")).toBe("1");
+  });
+
+  it("never hides content at the motion floor or without an observer", () => {
+    belowTheFold(HTMLElement.prototype);
+    vi.stubGlobal("IntersectionObserver", undefined);
+    const { container: noObserver } = render(<RevealOnEnter>A</RevealOnEnter>);
+    expect(noObserver.firstElementChild).not.toHaveAttribute("data-reveal");
+    stubObserver();
+    // A subtree dials motion through --motion-factor; jsdom does not inherit custom
+    // properties, so the dial sits on the element itself here.
+    const { container: reduced } = render(
+      <RevealOnEnter style={{ "--motion-factor": "0.0001" } as React.CSSProperties}>
+        B
+      </RevealOnEnter>,
+    );
+    expect(reduced.firstElementChild).not.toHaveAttribute("data-reveal");
+  });
+});

package/src/components/reveal-on-enter/reveal-on-enter.tsx

@@ -0,0 +1,75 @@
+"use client";
+
+import * as React from "react";
+import { isMotionAtFloor, readMotionFactor } from "../../lib/use-scroll-progress";
+import "./reveal-on-enter.css";
+
+/** Elements RevealOnEnter may render as. */
+export type RevealOnEnterElement =
+  | "div"
+  | "section"
+  | "article"
+  | "aside"
+  | "header"
+  | "footer"
+  | "ul"
+  | "ol"
+  | "li";
+
+export interface RevealOnEnterProps extends React.HTMLAttributes<HTMLElement> {
+  /** The element to render. Default `div`. */
+  as?: RevealOnEnterElement;
+  /** Reveal each direct child in turn (60 ms × `--motion-factor` apart) instead of the whole. */
+  stagger?: boolean;
+}
+
+type RevealPhase = "idle" | "hidden" | "shown";
+
+/**
+ * Fades and lifts its content in the first time it scrolls into view — once, never re-hiding.
+ * Content is never hidden from a reader or a crawler: the server HTML is fully visible, and the
+ * hidden state is applied only after hydration, only when the motion gate is open, only when
+ * `IntersectionObserver` exists, and only for content that is not already on screen.
+ */
+export const RevealOnEnter = React.forwardRef<HTMLElement, RevealOnEnterProps>(
+  ({ as: Comp = "div", stagger = false, ...props }, ref) => {
+    const innerRef = React.useRef<HTMLElement>(null);
+    React.useImperativeHandle(ref, () => innerRef.current as HTMLElement, []);
+    const [phase, setPhase] = React.useState<RevealPhase>("idle");
+
+    React.useEffect(() => {
+      const el = innerRef.current;
+      if (!el || typeof IntersectionObserver === "undefined") return;
+      if (isMotionAtFloor(readMotionFactor(el))) return;
+      const rect = el.getBoundingClientRect();
+      if (rect.top < window.innerHeight && rect.bottom > 0) return; // already seen: leave it be
+      if (stagger) {
+        Array.from(el.children).forEach((child, index) => {
+          (child as HTMLElement).style.setProperty("--reveal-index", String(index));
+        });
+      }
+      setPhase("hidden");
+      const observer = new IntersectionObserver((entries) => {
+        if (!entries.some((entry) => entry.isIntersecting)) return;
+        setPhase("shown");
+        observer.disconnect();
+      });
+      observer.observe(el);
+      return () => observer.disconnect();
+    }, [stagger]);
+
+    // Every `as` option is a block element with the same attribute surface; typing the tag as
+    // `div` keeps JSX (and its `data-slot` declaration) without a per-tag ref union.
+    const Tag = Comp as "div";
+    return (
+      <Tag
+        ref={innerRef as React.Ref<HTMLDivElement>}
+        data-slot="reveal-on-enter"
+        data-reveal={phase === "idle" ? undefined : phase}
+        data-stagger={stagger ? "" : undefined}
+        {...props}
+      />
+    );
+  },
+);
+RevealOnEnter.displayName = "RevealOnEnter";

package/src/components/revision-timeline/revision-timeline.tsx

@@ -528,9 +528,7 @@ function DayHeader({ label }: DayHeaderProps) {
       style={{ height: DAY_HEADER_H }}
       className="box-border flex items-center gap-3 px-3"
     >
-      <span className="text-meta font-medium uppercase tracking-wide text-muted-foreground">
-        {label}
-      </span>
+      <span className="text-eyebrow uppercase text-muted-foreground">{label}</span>
       <div className="h-px flex-1 bg-border" aria-hidden="true" />
     </div>
   );

package/src/components/schema-form/index.ts

@@ -33,6 +33,7 @@ export {
 export {
   fieldSpecSchema,
   formSpecSchema,
+  formSectionSchema,
   enumOptionSchema,
   keyValueRowSchema,
   stringFieldSchema,
@@ -73,6 +74,7 @@ export {
   type GroupFieldSpec,
   type FieldSpec,
   type FormSpec,
+  type FormSectionSpec,
   type FormValue,
   type FormValues,
   type FormSubmitState,

package/src/components/schema-form/schema-form-spec.ts

@@ -91,6 +91,11 @@ const baseField = {
       equals: z.union([z.string(), z.number(), z.boolean()]),
     })
     .optional(),
+  /**
+   * Show the value as read-only text (a `Descriptions` item) instead of an
+   * editable control. The value still belongs to the form's `values`.
+   */
+  readOnly: z.boolean().optional(),
 };
 
 /** A single-line or multi-line text field. */
@@ -306,7 +311,25 @@ export const formSpecSchema = z.object({
   fields: z.array(fieldSpecSchema),
   /** Submit button label. @default "Submit" */
   submitLabel: z.string().optional(),
+  /**
+   * Collapsible groups of top-level fields, in display order. Fields not named
+   * in any section render first, ungrouped. Omit for the flat layout.
+   */
+  sections: z.array(z.lazy(() => formSectionSchema)).optional(),
+});
+
+/** One collapsible group of top-level fields in a `FormSpec`. */
+export const formSectionSchema = z.object({
+  /** Stable key for the section. */
+  id: z.string(),
+  /** Heading on the section's disclosure trigger. */
+  label: z.string(),
+  /** Names of the top-level fields the section holds, in display order. */
+  fields: z.array(z.string()),
+  /** Start collapsed. @default false */
+  collapsed: z.boolean().optional(),
 });
+export type FormSectionSpec = z.infer<typeof formSectionSchema>;
 export type FormSpec = Omit<z.infer<typeof formSpecSchema>, "fields"> & { fields: FieldSpec[] };
 
 // ---------------------------------------------------------------------------
@@ -345,6 +368,8 @@ export interface NormalizedFormSpec {
   description?: string;
   submitLabel?: string;
   fields: FieldSpec[];
+  /** Collapsible field groups; absent when the spec declares none. */
+  sections?: FormSectionSpec[];
 }
 
 /**
@@ -415,10 +440,21 @@ export function normalizeFormSpec(
       description: typeof raw.description === "string" ? raw.description : undefined,
       submitLabel: typeof raw.submitLabel === "string" ? raw.submitLabel : undefined,
       fields,
+      ...normalizeSections(raw.sections),
     },
   };
 }
 
+/** Keep only well-formed sections; `{}` when there are none, so the normalized shape is unchanged. */
+function normalizeSections(raw: unknown): { sections?: FormSectionSpec[] } {
+  if (!Array.isArray(raw)) return {};
+  const sections = raw.flatMap((candidate) => {
+    const parsed = formSectionSchema.safeParse(candidate);
+    return parsed.success ? [parsed.data] : [];
+  });
+  return sections.length > 0 ? { sections } : {};
+}
+
 // ---------------------------------------------------------------------------
 // Field tree helpers (fields can nest inside `group` branches)
 // ---------------------------------------------------------------------------

package/src/components/schema-form/schema-form.stories.tsx

@@ -564,3 +564,36 @@ export const FromJsonSchema: Story = {
     return <SchemaForm spec={spec} onSubmit={(state) => console.info("submit", state)} />;
   },
 };
+
+// SchemaForm sections — RM-080
+const sectionedSpec: FormSpec = {
+  formName: "tile_properties",
+  title: "Tile properties",
+  fields: [
+    { type: "string", name: "id", label: "Tile id", readOnly: true, default: "chart-1" },
+    { type: "string", name: "title", label: "Title" },
+    { type: "string", name: "subtitle", label: "Subtitle" },
+    { type: "string", name: "visibleWhen", label: "Show when" },
+    { type: "integer", name: "minW", label: "Minimum width (cells)", min: 1 },
+  ],
+  sections: [
+    { id: "general", label: "General", fields: ["title", "subtitle"] },
+    { id: "visibility", label: "Visibility", fields: ["visibleWhen"] },
+    { id: "size", label: "Size", fields: ["minW"], collapsed: true },
+  ],
+};
+
+/** `sections` groups fields into disclosures; `readOnly` shows a value as text. */
+export const Sections: Story = {
+  args: { spec: sectionedSpec },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await expect(canvas.getByText("chart-1")).toBeInTheDocument();
+    await expect(canvas.queryByRole("textbox", { name: "Tile id" })).toBeNull();
+    await expect(canvas.queryByLabelText(/Minimum width/)).toBeNull();
+    await userEvent.click(canvas.getByRole("button", { name: "Size" }));
+    await waitFor(() => expect(canvas.getByLabelText(/Minimum width/)).toBeVisible());
+    await userEvent.click(canvas.getByRole("button", { name: "General" }));
+    await waitFor(() => expect(canvas.queryByLabelText("Title")).toBeNull());
+  },
+};

package/src/components/schema-form/schema-form.test.tsx

@@ -1019,3 +1019,46 @@ describe("SchemaForm — per-field subscription (#review 3.4: one context re-ren
     expect(counts.clientId).toBe(1);
   });
 });
+
+// SchemaForm sections — RM-080
+describe("SchemaForm sections and readOnly", () => {
+  const spec: FormSpec = {
+    formName: "sections",
+    fields: [
+      { type: "string", name: "free", label: "Free" },
+      { type: "string", name: "id", label: "Id", readOnly: true, default: "abc" },
+      { type: "string", name: "title", label: "Title" },
+      { type: "integer", name: "minW", label: "Min width" },
+    ],
+    sections: [
+      { id: "general", label: "General", fields: ["title"] },
+      { id: "size", label: "Size", fields: ["minW"], collapsed: true },
+    ],
+  };
+
+  it("renders ungrouped fields first, then collapsible sections", async () => {
+    render(<SchemaForm spec={spec} />);
+    const free = screen.getByLabelText("Free");
+    const general = screen.getByRole("button", { name: "General" });
+    expect(free.compareDocumentPosition(general) & Node.DOCUMENT_POSITION_FOLLOWING).toBeTruthy();
+    expect(screen.getByLabelText("Title")).toBeInTheDocument();
+    expect(screen.queryByLabelText("Min width")).toBeNull();
+    await userEvent.click(screen.getByRole("button", { name: "Size" }));
+    expect(screen.getByLabelText("Min width")).toBeInTheDocument();
+    await userEvent.click(general);
+    expect(screen.queryByLabelText("Title")).toBeNull();
+  });
+
+  it("renders a readOnly field as text, not a control", () => {
+    render(<SchemaForm spec={spec} />);
+    expect(screen.getByText("abc")).toBeInTheDocument();
+    expect(screen.queryByRole("textbox", { name: "Id" })).toBeNull();
+  });
+
+  it("keeps the normalized shape unchanged when no sections are declared", () => {
+    const result = normalizeFormSpec({ formName: "x", fields: [] });
+    expect(result.ok && "sections" in result.spec).toBe(false);
+    const withBad = normalizeFormSpec({ formName: "x", fields: [], sections: [{ id: 1 }] });
+    expect(withBad.ok && "sections" in withBad.spec).toBe(false);
+  });
+});