@cosmicdrift/kumiko-renderer-web 0.262.0 → 0.264.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-renderer-web",
-  "version": "0.262.0",
+  "version": "0.264.0",
   "description": "Web-platform bindings for @cosmicdrift/kumiko-renderer. HTML default-primitives, browser history-based navigation, EventSource-backed live events, and a one-call createKumikoApp that mounts the whole stack via react-dom.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -16,9 +16,9 @@
     "./styles.css": "./src/styles.css"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.262.0",
-    "@cosmicdrift/kumiko-headless": "0.262.0",
-    "@cosmicdrift/kumiko-renderer": "0.262.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.264.0",
+    "@cosmicdrift/kumiko-headless": "0.264.0",
+    "@cosmicdrift/kumiko-renderer": "0.264.0",
     "@radix-ui/react-dialog": "^1.1.15",
     "@radix-ui/react-dropdown-menu": "^2.1.16",
     "@radix-ui/react-label": "^2.1.8",
@@ -66,7 +66,7 @@
     "@types/react-dom": "^19.2.3",
     "jsdom": "^29.1.1",
     "tailwindcss": "^4.3.0",
-    "@cosmicdrift/kumiko-locale-de": "0.262.0"
+    "@cosmicdrift/kumiko-locale-de": "0.264.0"
   },
   "repository": {
     "type": "git",

package/src/__tests__/entity-edit-redirect.test.tsx

@@ -60,6 +60,8 @@ function buildParentRedirectSchema(): FeatureSchema {
     entity: "product",
     layout: { sections: [{ fields: ["name", "parentId"] }] },
     redirect: { screen: "parent-detail", idFrom: "parentId" },
+    // Hand-built schema; production derives urlPrefillFields from declared navigate params.
+    urlPrefillFields: ["parentId"],
   };
   const parentDetailScreen: ScreenDefinition = {
     id: "parent-detail",

package/src/__tests__/kumiko-screen.test.tsx

@@ -16,8 +16,10 @@ import {
   kumikoDefaultTranslations,
   NavProvider,
   UserRolesProvider,
+  useNavigateWithInitialValues,
 } from "@cosmicdrift/kumiko-renderer";
 import userEvent from "@testing-library/user-event";
+import { type ReactNode, useState } from "react";
 import { createMockDispatcher, fireEvent, render, screen, waitFor, within } from "./test-utils";
 
 const taskEntity = {
@@ -2610,6 +2612,7 @@ describe("KumikoScreen", () => {
       layout: {
         sections: [{ title: "x", fields: ["title", "priority", "isDone"] }],
       },
+      urlPrefillFields: ["title", "priority", "isDone"],
     };
 
     const { NavProvider } = await import("@cosmicdrift/kumiko-renderer");
@@ -2647,6 +2650,7 @@ describe("KumikoScreen", () => {
       handler: "tasks:write:task:approve",
       fields: { priority: { type: "number", default: 7 } },
       layout: { sections: [{ title: "x", fields: ["priority"] }] },
+      urlPrefillFields: ["priority"],
     };
     const { NavProvider } = await import("@cosmicdrift/kumiko-renderer");
     render(
@@ -2662,6 +2666,121 @@ describe("KumikoScreen", () => {
     expect(priorityInput.value).toBe("7"); // Fallback auf default
   });
 
+  const payoutScreen: ActionFormScreenDefinition = {
+    id: "payout",
+    type: "actionForm",
+    handler: "tasks:write:task:payout",
+    fields: {
+      title: { type: "text", default: "default-title" },
+      iban: { type: "text", default: "own-iban" },
+      secret: { type: "text", sensitive: true },
+    },
+    layout: { sections: [{ title: "x", fields: ["title", "iban", "secret"] }] },
+    urlPrefillFields: ["title", "secret"],
+  };
+
+  function inputValue(fieldName: string): string {
+    const input = screen.getByTestId(`field-${fieldName}`).querySelector("input");
+    if (input === null) throw new Error(`expected an <input> inside field-${fieldName}`);
+    return input.value;
+  }
+
+  test("actionForm: a crafted link prefills only urlPrefillFields, never a sensitive one", async () => {
+    const memoryNav = {
+      route: { screenId: "payout" },
+      navigate: () => undefined,
+      replace: () => undefined,
+      hrefFor: () => "/x",
+      searchParams: { title: "declared", iban: "attacker-iban", secret: "leak" },
+      setSearchParams: () => undefined,
+    };
+    const { NavProvider } = await import("@cosmicdrift/kumiko-renderer");
+    render(
+      <NavProvider value={memoryNav}>
+        <DispatcherProvider dispatcher={makeDispatcher()}>
+          <KumikoScreen schema={{ ...schema, screens: [payoutScreen] }} qn="tasks:screen:payout" />
+        </DispatcherProvider>
+      </NavProvider>,
+    );
+    expect(inputValue("title")).toBe("declared");
+    expect(inputValue("iban")).toBe("own-iban");
+    expect(inputValue("secret")).toBe("");
+  });
+
+  test("actionForm: useNavigateWithInitialValues hands values over without touching the query string", async () => {
+    const searchParamWrites: unknown[] = [];
+    function Harness(): ReactNode {
+      const [route, setRoute] = useState<{ screenId: string }>({ screenId: "home" });
+      const nav = {
+        route,
+        navigate: (target: NavTarget) => {
+          if ("screenId" in target) setRoute({ screenId: target.screenId });
+        },
+        replace: () => undefined,
+        hrefFor: () => "/x",
+        searchParams: {},
+        setSearchParams: (u: Record<string, string | null>) => searchParamWrites.push(u),
+      };
+      return (
+        <NavProvider value={nav}>
+          {route.screenId === "payout" ? (
+            <KumikoScreen
+              schema={{ ...schema, screens: [payoutScreen] }}
+              qn="tasks:screen:payout"
+            />
+          ) : (
+            <OpenPayout />
+          )}
+        </NavProvider>
+      );
+    }
+    function OpenPayout(): ReactNode {
+      const navigateWithInitialValues = useNavigateWithInitialValues();
+      return (
+        <button
+          type="button"
+          data-testid="open-payout"
+          onClick={() =>
+            navigateWithInitialValues(
+              { screenId: "payout" },
+              { iban: "DE-from-agent", secret: "leak" },
+            )
+          }
+        />
+      );
+    }
+    render(
+      <DispatcherProvider dispatcher={makeDispatcher()}>
+        <Harness />
+      </DispatcherProvider>,
+    );
+    fireEvent.click(screen.getByTestId("open-payout"));
+    await waitFor(() => expect(screen.getByTestId("field-iban")).toBeTruthy());
+    expect(inputValue("iban")).toBe("DE-from-agent");
+    expect(inputValue("secret")).toBe("");
+    expect(searchParamWrites).toEqual([]);
+  });
+
+  test("actionForm: the same values as URL params do not prefill fields outside urlPrefillFields", async () => {
+    const memoryNav = {
+      route: { screenId: "payout" },
+      navigate: () => undefined,
+      replace: () => undefined,
+      hrefFor: () => "/x",
+      searchParams: { iban: "DE-from-agent", agentPrefill: "1" },
+      setSearchParams: () => undefined,
+    };
+    const { NavProvider } = await import("@cosmicdrift/kumiko-renderer");
+    render(
+      <NavProvider value={memoryNav}>
+        <DispatcherProvider dispatcher={makeDispatcher()}>
+          <KumikoScreen schema={{ ...schema, screens: [payoutScreen] }} qn="tasks:screen:payout" />
+        </DispatcherProvider>
+      </NavProvider>,
+    );
+    expect(inputValue("iban")).toBe("own-iban");
+  });
+
   test("actionForm submitLabel: i18n-Key landet auf dem Submit-Button (übersteuert default)", () => {
     const dispatcher = makeDispatcher();
     const actionScreen: ActionFormScreenDefinition = {
@@ -2960,6 +3079,7 @@ describe("KumikoScreen: actionForm extension-section", () => {
           { title: "Update", fields: ["incidentId", "body"] },
         ],
       },
+      urlPrefillFields: ["incidentId"],
     };
     const UpdateTimeline = ({
       initialValues,

package/src/__tests__/primitives.test.tsx

@@ -1860,6 +1860,15 @@ describe("Card", () => {
     );
     expect(screen.getByTestId("c").innerHTML).not.toContain("grow");
   });
+
+  test("dataAttributes forwards data-* attributes to the root node", () => {
+    render(
+      <Card testId="c" dataAttributes={{ "data-path": "widgets/entity-card.tsx" }}>
+        body
+      </Card>,
+    );
+    expect(screen.getByTestId("c").getAttribute("data-path")).toBe("widgets/entity-card.tsx");
+  });
 });
 
 describe("Section", () => {

package/src/layout/__tests__/shell-header.test.tsx

@@ -0,0 +1,21 @@
+import { describe, expect, test } from "bun:test";
+import type { AppSchema } from "@cosmicdrift/kumiko-renderer";
+import { renderWithSidebar, screen } from "../../__tests__/test-utils";
+import { ShellHeader } from "../shell-header";
+
+const emptySchema: AppSchema = { features: [] };
+
+describe("ShellHeader", () => {
+  test("default: h-16, collapses to h-12 with the icon rail (unchanged regression)", () => {
+    renderWithSidebar(<ShellHeader schema={emptySchema} />);
+    const header = screen.getByRole("banner");
+    expect(header.className).toContain("h-16");
+    expect(header.className).toContain("group-has-data-[collapsible=icon]/sidebar-wrapper:h-12");
+  });
+
+  test('carries the data-kumiko-layout="shell-header" marker that drives --shell-header-height', () => {
+    renderWithSidebar(<ShellHeader schema={emptySchema} />);
+    const header = screen.getByRole("banner");
+    expect(header.getAttribute("data-kumiko-layout")).toBe("shell-header");
+  });
+});

package/src/layout/shell-header.tsx

@@ -3,6 +3,10 @@
 // rechtsbündige headerActions. Geteilt von DefaultAppShell und WorkspaceShell,
 // damit beide dieselbe Kopfzeile tragen (Höhe h-16, kollabiert auf h-12 mit
 // der Icon-Rail).
+//
+// The `data-kumiko-layout="shell-header"` marker drives `--shell-header-height`
+// in styles.css (:has() selector) — the single source for the header height
+// that Drawer's `belowHeader` prop also reads.
 
 import type { NavNode } from "@cosmicdrift/kumiko-headless";
 import { resolveNavigation } from "@cosmicdrift/kumiko-headless";
@@ -57,7 +61,10 @@ export function ShellHeader({
   }, [allScreens, screenId, t, tree]);
 
   return (
-    <header className="flex h-16 shrink-0 items-center gap-2 border-b transition-[width,height] ease-linear group-has-data-[collapsible=icon]/sidebar-wrapper:h-12">
+    <header
+      data-kumiko-layout="shell-header"
+      className="flex h-16 shrink-0 items-center gap-2 border-b transition-[width,height] ease-linear group-has-data-[collapsible=icon]/sidebar-wrapper:h-12"
+    >
       <div className="flex items-center gap-2 px-4">
         <SidebarTrigger className="-ml-1" />
         <Separator orientation="vertical" className="mr-2 data-[orientation=vertical]:h-4" />

package/src/primitives/__tests__/button.test.tsx

@@ -24,6 +24,15 @@ describe("DefaultButton className/ref (fw#1831)", () => {
     );
     expect(ref.current).toBe(screen.getByTestId("btn"));
   });
+
+  test("dataAttributes forwards data-* attributes to the <button>", () => {
+    render(
+      <Button dataAttributes={{ "data-action": "save" }} testId="btn">
+        Save
+      </Button>,
+    );
+    expect(screen.getByTestId("btn").getAttribute("data-action")).toBe("save");
+  });
 });
 
 describe("DefaultButton icon (fw-ui-defaults)", () => {

package/src/primitives/__tests__/input-data-attributes.test.tsx

@@ -0,0 +1,45 @@
+import { describe, expect, test } from "bun:test";
+import { render, screen } from "@testing-library/react";
+import { defaultPrimitives } from "../index";
+
+const { Input } = defaultPrimitives;
+const noop = () => {};
+
+describe("Input dataAttributes forwarding", () => {
+  test("kind=text: data-* lands on the <input>", () => {
+    render(
+      <Input
+        kind="text"
+        id="x"
+        name="x"
+        value=""
+        onChange={noop}
+        testId="tid"
+        dataAttributes={{ "data-1p-ignore": "true" }}
+      />,
+    );
+    expect(screen.getByTestId("tid").getAttribute("data-1p-ignore")).toBe("true");
+  });
+
+  test("kind=textarea: data-* lands on the <textarea>", () => {
+    const { container } = render(
+      <Input
+        kind="textarea"
+        id="notes"
+        name="notes"
+        value=""
+        onChange={noop}
+        dataAttributes={{ "data-testid": "notes-area" }}
+      />,
+    );
+    const textarea = container.querySelector("textarea");
+    expect(textarea?.getAttribute("data-testid")).toBe("notes-area");
+  });
+
+  test("kind=text without dataAttributes: no extra attributes, unchanged default rendering", () => {
+    render(<Input kind="text" id="x" name="x" value="" onChange={noop} testId="tid" />);
+    const input = screen.getByTestId("tid");
+    expect(input.tagName).toBe("INPUT");
+    expect(input.getAttribute("data-1p-ignore")).toBeNull();
+  });
+});

package/src/primitives/__tests__/input-keydown.test.tsx

@@ -0,0 +1,81 @@
+// Agent-Panel composer needs "Enter sends, Shift+Enter inserts a newline" at
+// the field itself — InputProps.onKeyDown gives kind="text"/"textarea" raw
+// keydown access instead of forcing that logic onto a wrapping <form>.
+import { describe, expect, test } from "bun:test";
+import { fireEvent, render, screen } from "@testing-library/react";
+import { defaultPrimitives } from "../index";
+
+const { Input } = defaultPrimitives;
+const noop = () => {};
+
+describe("Input onKeyDown", () => {
+  test("kind=text: fires with key info on every keydown", () => {
+    const events: string[] = [];
+    render(
+      <Input
+        kind="text"
+        id="x"
+        name="x"
+        value=""
+        onChange={noop}
+        testId="tid"
+        onKeyDown={(e) => events.push(e.key)}
+      />,
+    );
+    fireEvent.keyDown(screen.getByTestId("tid"), { key: "Enter" });
+    fireEvent.keyDown(screen.getByTestId("tid"), { key: "a" });
+    expect(events).toEqual(["Enter", "a"]);
+  });
+
+  test("kind=textarea: fires with shiftKey so the caller can distinguish Enter from Shift+Enter", () => {
+    const events: Array<{ key: string; shiftKey: boolean }> = [];
+    const { container } = render(
+      <Input
+        kind="textarea"
+        id="notes"
+        name="notes"
+        value=""
+        onChange={noop}
+        onKeyDown={(e) => events.push({ key: e.key, shiftKey: e.shiftKey })}
+      />,
+    );
+    const textarea = container.querySelector("textarea");
+    if (textarea === null) throw new Error("no textarea rendered");
+    fireEvent.keyDown(textarea, { key: "Enter" });
+    fireEvent.keyDown(textarea, { key: "Enter", shiftKey: true });
+    expect(events).toEqual([
+      { key: "Enter", shiftKey: false },
+      { key: "Enter", shiftKey: true },
+    ]);
+  });
+
+  test("kind=textarea: composes with onSubmitShortcut — both fire on Ctrl+Enter", () => {
+    let keyDownCalls = 0;
+    let submitCalls = 0;
+    const { container } = render(
+      <Input
+        kind="textarea"
+        id="notes"
+        name="notes"
+        value=""
+        onChange={noop}
+        onKeyDown={() => {
+          keyDownCalls += 1;
+        }}
+        onSubmitShortcut={() => {
+          submitCalls += 1;
+        }}
+      />,
+    );
+    const textarea = container.querySelector("textarea");
+    if (textarea === null) throw new Error("no textarea rendered");
+    fireEvent.keyDown(textarea, { key: "Enter", ctrlKey: true });
+    expect(keyDownCalls).toBe(1);
+    expect(submitCalls).toBe(1);
+  });
+
+  test("without onKeyDown: unchanged default rendering (no crash, no listener)", () => {
+    render(<Input kind="text" id="x" name="x" value="" onChange={noop} testId="tid" />);
+    expect(() => fireEvent.keyDown(screen.getByTestId("tid"), { key: "Enter" })).not.toThrow();
+  });
+});

package/src/primitives/__tests__/link-data-attributes.test.tsx

@@ -0,0 +1,28 @@
+import { describe, expect, test } from "bun:test";
+import { render, screen } from "@testing-library/react";
+import { defaultPrimitives } from "../index";
+
+const { Link } = defaultPrimitives;
+
+describe("DefaultLink", () => {
+  test("default rendering unchanged: href + variant class, no data attributes", () => {
+    render(
+      <Link href="/settings" testId="lnk">
+        Settings
+      </Link>,
+    );
+    const link = screen.getByTestId("lnk");
+    expect(link.tagName).toBe("A");
+    expect(link.getAttribute("href")).toBe("/settings");
+    expect(link.className).toContain("text-primary");
+  });
+
+  test("dataAttributes forwards data-* attributes to the <a>, e.g. for a Designer file link", () => {
+    render(
+      <Link href="#some-file" testId="lnk" dataAttributes={{ "data-path": "some-file.tsx" }}>
+        some-file.tsx
+      </Link>,
+    );
+    expect(screen.getByTestId("lnk").getAttribute("data-path")).toBe("some-file.tsx");
+  });
+});

package/src/primitives/index.tsx

@@ -190,6 +190,7 @@ function DefaultButton({
   ref,
   icon,
   iconEnd,
+  dataAttributes,
 }: ButtonProps): ReactNode {
   // link-Variant rendert text-artig (Inline-Link im Fließtext/Banner), nicht als
   // gepolsterte Fläche; width="full" streckt CTA-Buttons in Karten/Panels.
@@ -217,6 +218,7 @@ function DefaultButton({
       type={type}
       onClick={onClick}
       disabled={disabled === true || loading === true}
+      {...dataAttributes}
       data-testid={testId}
       data-loading={loading === true ? "true" : undefined}
       variant={BUTTON_VARIANT[variant]}
@@ -567,10 +569,12 @@ function DefaultInput(props: InputProps): ReactNode {
         <UiInput
           type="text"
           {...common}
+          {...props.dataAttributes}
           data-testid={props.testId}
           readOnly={props.readOnly}
           value={props.value}
           onChange={(e: ChangeEvent<HTMLInputElement>) => props.onChange(e.target.value)}
+          onKeyDown={props.onKeyDown}
           {...(props.placeholder !== undefined && { placeholder: props.placeholder })}
           {...(props.autoComplete !== undefined && { autoComplete: props.autoComplete })}
           className={cn(fieldIconFor(props.icon) !== undefined ? "pl-8" : undefined)}
@@ -815,9 +819,11 @@ function DefaultInput(props: InputProps): ReactNode {
     case "textarea": {
       const rows = normalizedTextareaRows(props.rows);
       const onSubmitShortcut = props.onSubmitShortcut;
+      const onKeyDown = props.onKeyDown;
       return (
         <Textarea
           {...common}
+          {...props.dataAttributes}
           readOnly={props.readOnly}
           value={props.value}
           onChange={(e: ChangeEvent<HTMLTextAreaElement>) => props.onChange(e.target.value)}
@@ -825,10 +831,14 @@ function DefaultInput(props: InputProps): ReactNode {
           className="resize-y"
           {...(props.placeholder !== undefined && { placeholder: props.placeholder })}
           {...(rows !== undefined && { style: textareaMinHeight(rows) })}
-          {...(onSubmitShortcut !== undefined && {
-            "aria-keyshortcuts": "Control+Enter Meta+Enter",
+          {...((onSubmitShortcut !== undefined || onKeyDown !== undefined) && {
+            ...(onSubmitShortcut !== undefined && {
+              "aria-keyshortcuts": "Control+Enter Meta+Enter",
+            }),
             onKeyDown: (e: KeyboardEvent<HTMLTextAreaElement>) => {
-              if (e.key !== "Enter" || !(e.metaKey || e.ctrlKey)) return;
+              onKeyDown?.(e);
+              if (onSubmitShortcut === undefined || e.key !== "Enter" || !(e.metaKey || e.ctrlKey))
+                return;
               e.preventDefault();
               onSubmitShortcut();
             },
@@ -2782,6 +2792,7 @@ function DefaultLink({
   className,
   children,
   testId,
+  dataAttributes,
 }: LinkProps): ReactNode {
   const variantClass =
     variant === "button"
@@ -2794,6 +2805,7 @@ function DefaultLink({
       href={isSafeHref(href) ? href : "#"}
       target={target}
       rel={target === "_blank" ? "noreferrer" : undefined}
+      {...dataAttributes}
       data-testid={testId}
       className={cn(variantClass, className)}
     >
@@ -2859,7 +2871,14 @@ import { ConfigSourceBadge as DefaultConfigSourceBadge } from "../components/con
 
 // Generische Card-Chrome (rounded-xl wie die Entity-Card) — slot- + options-
 // basiert, damit der Contract additiv wächst und Consumer nie migriert werden.
-export function DefaultCard({ slots, options, className, testId, children }: CardProps): ReactNode {
+export function DefaultCard({
+  slots,
+  options,
+  className,
+  testId,
+  dataAttributes,
+  children,
+}: CardProps): ReactNode {
   const padded = options?.padded ?? true;
   const radius = options?.radius ?? "xl";
   const footerBordered = options?.footerBordered ?? true;
@@ -2883,6 +2902,7 @@ export function DefaultCard({ slots, options, className, testId, children }: Car
   return (
     <div
       data-slot="card"
+      {...dataAttributes}
       data-testid={testId}
       className={cn(cardSurface({ radius }), "overflow-hidden", className)}
     >

package/src/styles.css

@@ -110,6 +110,22 @@
   --card-radius: var(--radius-xl);
   --card-shadow: 0 1px 3px 0 rgb(0 0 0 / 0.1), 0 1px 2px -1px rgb(0 0 0 / 0.1);
   --kumiko-grid-row-h: 2.5rem;
+  /* 0 = no ShellHeader mounted (e.g. a Drawer used outside a shell) — a
+     consumer offsetting by this variable then gets today's edge-to-edge
+     behavior for free. */
+  --shell-header-height: 0px;
+}
+
+/* Mirrors ShellHeader's own h-16/h-12 (icon-rail collapsed) via the same
+   [data-collapsible=icon] state Tailwind's group-has-data variant reads —
+   kept in CSS (not a React state) so a Drawer rendered into a portal
+   (outside ShellHeader's DOM subtree) still resolves the right value from
+   this shared :root ancestor. */
+:root:has([data-kumiko-layout="shell-header"]) {
+  --shell-header-height: 4rem;
+}
+:root:has([data-kumiko-layout="shell-header"]):has([data-collapsible="icon"]) {
+  --shell-header-height: 3rem;
 }
 
 /* Light-Mode-Overrides — aktiv wenn `<html>` KEINE `.dark` Klasse

package/src/widgets/__tests__/drawer.test.tsx

@@ -151,6 +151,87 @@ describe("Drawer", () => {
     });
   });
 
+  describe("belowHeader", () => {
+    test("default (false): variant=flush keeps inset-y-0, no header offset", () => {
+      render(
+        <Drawer open={true} onOpenChange={() => {}} side="right" variant="flush" testId="drawer">
+          <div>Body</div>
+        </Drawer>,
+      );
+      const content = screen.getByTestId("drawer");
+      expect(content.className).toContain("inset-y-0");
+      expect(content.style.top).toBe("");
+    });
+
+    test("true + variant=flush + side=right: offsets top by the header var via inline style, sticks to bottom", () => {
+      render(
+        <Drawer
+          open={true}
+          onOpenChange={() => {}}
+          side="right"
+          variant="flush"
+          belowHeader
+          testId="drawer"
+        >
+          <div>Body</div>
+        </Drawer>,
+      );
+      const content = screen.getByTestId("drawer");
+      // Inline style (not a class) — className keeps `inset-y-0` since
+      // tailwind-merge doesn't dedupe it against `top-*`/`bottom-*`; style
+      // wins over the class regardless, so this is the reliable assertion.
+      expect(content.style.top).toBe("var(--shell-header-height)");
+      expect(content.style.bottom).toBe("0px");
+      expect(content.className).toContain("inset-y-0");
+    });
+
+    test("true + variant=flush + side=top: top offset instead of top-0", () => {
+      render(
+        <Drawer
+          open={true}
+          onOpenChange={() => {}}
+          side="top"
+          variant="flush"
+          belowHeader
+          testId="drawer"
+        >
+          <div>Body</div>
+        </Drawer>,
+      );
+      const content = screen.getByTestId("drawer");
+      expect(content.className).toContain("top-(--shell-header-height)");
+      expect(content.className).not.toContain("top-0");
+    });
+
+    test("true + variant=flush + side=bottom: unaffected (still bottom-anchored)", () => {
+      render(
+        <Drawer
+          open={true}
+          onOpenChange={() => {}}
+          side="bottom"
+          variant="flush"
+          belowHeader
+          testId="drawer"
+        >
+          <div>Body</div>
+        </Drawer>,
+      );
+      expect(screen.getByTestId("drawer").className).toContain("bottom-0");
+      expect(screen.getByTestId("drawer").className).not.toContain("--shell-header-height");
+    });
+
+    test("true + variant=floating (default variant): ignored, floating classes unchanged", () => {
+      render(
+        <Drawer open={true} onOpenChange={() => {}} side="right" belowHeader testId="drawer">
+          <div>Body</div>
+        </Drawer>,
+      );
+      const content = screen.getByTestId("drawer");
+      expect(content.className).toContain("inset-y-8");
+      expect(content.className).not.toContain("--shell-header-height");
+    });
+  });
+
   describe("width", () => {
     test("width={420}: reflected as inline pixel width", () => {
       render(
@@ -570,6 +651,25 @@ describe("Drawer", () => {
       expect(screen.queryByRole("button", { name: /maximize drawer width/i })).toBeNull();
     });
 
+    test("narrow with belowHeader: fullscreen branch unaffected (already covers the header)", () => {
+      mockMatchMedia(true);
+      render(
+        <Drawer
+          open={true}
+          onOpenChange={() => {}}
+          side="right"
+          variant="flush"
+          belowHeader
+          testId="drawer"
+        >
+          <div>Body</div>
+        </Drawer>,
+      );
+      const content = screen.getByTestId("drawer");
+      expect(content.className).toContain("inset-0");
+      expect(content.className).not.toContain("--shell-header-height");
+    });
+
     test("wide (regression clamp): inline width and handle still present with resize set", () => {
       mockMatchMedia(false);
       render(

package/src/widgets/drawer.tsx

@@ -34,6 +34,13 @@ export type DrawerProps = {
    *  only on the edge facing the app content. Ignored in the narrow-viewport
    *  fullscreen layout. */
   readonly variant?: "floating" | "flush";
+  /** `variant="flush"` only: dock the panel below the app's ShellHeader
+   *  (offset top by `--shell-header-height`, height shrunk to match)
+   *  instead of covering it. Default `false` keeps today's edge-to-edge
+   *  behavior. No ShellHeader mounted → the variable is `0`, so this is a
+   *  no-op. Ignored in the narrow-viewport fullscreen layout, which already
+   *  takes over the whole screen including the header. */
+  readonly belowHeader?: boolean;
   /** Panel width for `side="left"|"right"` (ignored for top/bottom and in
    *  the narrow-viewport layout). A number is pixels, a string any CSS
    *  length. Superseded by `resize` when that's set. Default matches the
@@ -96,14 +103,22 @@ function sidePanelClass(
   side: "left" | "right" | "top" | "bottom",
   narrow: boolean,
   variant: "floating" | "flush",
+  belowHeader: boolean,
 ): string {
   if (narrow) return "inset-0 h-full w-full max-w-none rounded-none border-0 overflow-hidden";
   if (variant === "flush") {
     switch (side) {
+      // left/right keep the `inset-y-0` class here even when belowHeader is
+      // set — DrawerSheetContent's own base className already carries
+      // `inset-y-0` for these sides, and tailwind-merge (v3.6, checked
+      // directly) does NOT dedupe `top-*`/`bottom-*` against it (unlike
+      // same-group `top-0` vs `top-(--x)`, which it does). Overriding top
+      // via inline `style` instead (Drawer's `verticalOffsetStyle`) always
+      // wins over both, without depending on that gap.
       case "left":
         return `inset-y-0 left-0 h-full ${WIDTH_CLASS} border-r shadow-2xl overflow-hidden`;
       case "top":
-        return "inset-x-0 top-0 h-auto max-h-[80vh] border-b shadow-2xl overflow-hidden";
+        return `inset-x-0 ${belowHeader ? "top-(--shell-header-height)" : "top-0"} h-auto max-h-[80vh] border-b shadow-2xl overflow-hidden`;
       case "bottom":
         return "inset-x-0 bottom-0 h-auto max-h-[80vh] border-t shadow-2xl overflow-hidden";
       default:
@@ -136,6 +151,7 @@ export function Drawer({
   testId,
   showCloseButton = true,
   variant = "floating",
+  belowHeader = false,
   width,
   resize,
   backdrop,
@@ -167,6 +183,17 @@ export function Drawer({
 
   const effectiveWidthPx = maximized ? effectiveMaxWidthPx() : resizedWidthPx;
 
+  // Overrides the base className's `inset-y-0` (top:0) as inline style —
+  // tailwind-merge doesn't dedupe `top-*`/`bottom-*` against `inset-y-*`
+  // (verified directly against the pinned tailwind-merge), so a class-only
+  // override would leave both `inset-y-0` and the offset in the className,
+  // with the winner then depending on Tailwind's generated CSS order. style
+  // always wins over a class for the same property, no such dependency.
+  const verticalOffsetStyle: React.CSSProperties | undefined =
+    belowHeader && variant === "flush" && !narrow && (side === "left" || side === "right")
+      ? { top: "var(--shell-header-height)", bottom: 0 }
+      : undefined;
+
   const onHandlePointerDown = (event: React.PointerEvent<HTMLDivElement>): void => {
     event.preventDefault();
     event.currentTarget.setPointerCapture(event.pointerId);
@@ -216,10 +243,13 @@ export function Drawer({
         data-testid={testId}
         overlayStyle={overlayStyle}
         showCloseButton={showCloseButton}
-        className={sidePanelClass(side, narrow, variant)}
-        style={
-          canResize && !narrow ? { width: effectiveWidthPx, maxWidth: "none" } : customWidthStyle
-        }
+        className={sidePanelClass(side, narrow, variant, belowHeader)}
+        style={{
+          ...(canResize && !narrow
+            ? { width: effectiveWidthPx, maxWidth: "none" }
+            : customWidthStyle),
+          ...verticalOffsetStyle,
+        }}
       >
         {canResize && !narrow && (
           <button