@cosmicdrift/kumiko-renderer 0.327.0 → 0.328.0

package/src/components/render-field.tsx

@@ -11,7 +11,7 @@ import {
   type EditFieldViewModel,
   type FieldIssue,
 } from "@cosmicdrift/kumiko-headless";
-import { type ReactNode, useCallback, useMemo, useState } from "react";
+import { createContext, type ReactNode, useCallback, useContext, useMemo, useState } from "react";
 import { useAppFeatures } from "../app/app-features-context";
 import { useColumnRenderer } from "../app/column-renderers";
 import { extensionSectionName } from "../app/extension-sections";
@@ -71,8 +71,14 @@ export type RenderFieldProps = {
    *  field's sibling-field `unit`. Omitted → falls back to a single-key
    *  `{ [field.field]: field.value }` row. */
   readonly row?: Readonly<Record<string, unknown>>;
+  /** Marks the field as modified against the loaded record (edit mode only). */
+  readonly changed?: boolean;
 };
 
+const AllFieldsRequiredContext = createContext(false);
+
+export const AllFieldsRequiredProvider = AllFieldsRequiredContext.Provider;
+
 export function RenderField({
   field,
   issues,
@@ -83,6 +89,7 @@ export function RenderField({
   allIssues,
   valueDisplay = "form",
   row,
+  changed,
 }: RenderFieldProps): ReactNode {
   const { Field, Input, Banner, Text, JsonView } = usePrimitives();
   // App-Locale (i18n) für money/date-Inputs — sonst fielen sie auf
@@ -92,6 +99,7 @@ export function RenderField({
   // Standalone-Consumer/Tests müssen wrappen (createKumikoApp tut es).
   const appLocale = useLocale().locale();
   const t = useTranslation();
+  const allFieldsRequired = useContext(AllFieldsRequiredContext);
   if (!field.visible) return null;
 
   const id = inputId(field);
@@ -157,10 +165,11 @@ export function RenderField({
     <Field
       id={id}
       label={field.label}
-      required={field.required}
+      required={field.required && !allFieldsRequired}
       {...(issues !== undefined && { issues })}
       {...(labelAppendix !== undefined && { labelAppendix })}
       {...(fieldAppendix !== undefined && { fieldAppendix })}
+      {...(changed === true && { changed })}
       testId={`field-${field.field}`}
     >
       {control}

package/src/components/render-list.tsx

@@ -17,6 +17,7 @@ import { extensionSectionName, useExtensionSectionComponent } from "../app/exten
 import type { ListSort } from "../hooks/use-list-url-state";
 import { type ReferenceLookupMap, useReferenceLookup } from "../hooks/use-reference-lookup";
 import { useTranslation } from "../i18n";
+import { usePageHeaderSlotAvailable } from "../page-header-slot";
 import {
   type DataTableDateRangeFacet,
   type DataTableFacet,
@@ -63,6 +64,10 @@ export type RenderListProps = {
   /** Placeholder für das Search-Input. Default kommt aus dem i18n-
    *  Bundle (`kumiko.list.search-placeholder`). */
   readonly searchPlaceholder?: string;
+  /** Hint at the left of the toolbar when there is no search box (already translated). */
+  readonly description?: string;
+  /** Plural-forms key for the footer count noun; default is the entity's `:noun` convention key. */
+  readonly itemNounKey?: string;
   /** Aktueller Search-Term (vom URL-State / Parent). RenderList puffert
    *  Tipps lokal mit 300ms Debounce, bevor onSearchChange gefeuert
    *  wird — sonst macht jeder Tastendruck einen Server-Roundtrip. */
@@ -167,6 +172,8 @@ export function RenderList(props: RenderListProps): ReactNode {
     createLabel,
     searchable = false,
     searchPlaceholder,
+    description,
+    itemNounKey,
     searchValue,
     onSearchChange,
     sort,
@@ -192,7 +199,10 @@ export function RenderList(props: RenderListProps): ReactNode {
   // wären Column-Header raw i18n-Keys.
   const t = useTranslation();
   const translate: Translate = translateProp ?? t;
-  const { DataTable, Button, Dialog, Input, Text, Banner } = usePrimitives();
+  const { DataTable, Button, Dialog, Input, Text, Banner, PageHeader } = usePrimitives();
+  const pageHeaderSlotAvailable = usePageHeaderSlotAvailable();
+  const createInPageHeader =
+    onCreate !== undefined && PageHeader !== undefined && pageHeaderSlotAvailable;
 
   // Local search buffer + debounce. External changes (browser back,
   // cross-component reset) are mirrored back; typing only fires
@@ -300,9 +310,19 @@ export function RenderList(props: RenderListProps): ReactNode {
   // i18n-Defaults für Toolbar/Empty-State Strings — Caller kann jeden
   // einzeln per Prop überschreiben, sonst kommen die Framework-Bundles
   // (kumiko.actions.create, kumiko.list.search-placeholder, …).
-  const effectiveCreateLabel = createLabel ?? translate("kumiko.actions.create");
-  const effectiveSearchPlaceholder =
-    searchPlaceholder ?? translate("kumiko.list.search-placeholder");
+  const effectiveCreateLabel = translate(
+    createLabel ?? screen.createLabel ?? "kumiko.actions.create",
+  );
+  const effectiveSearchPlaceholder = translate(
+    searchPlaceholder ?? screen.searchPlaceholder ?? "kumiko.list.search-placeholder",
+  );
+
+  const nounKey = itemNounKey ?? `${featureName}:entity:${screen.entity}:noun`;
+  const itemNoun =
+    (itemNounKey !== undefined || !screen.entity.startsWith("__")) &&
+    translate(nounKey, { count: 2 }) !== nounKey
+      ? (count: number): string => translate(nounKey, { count })
+      : undefined;
 
   const toolbarStart = searchable ? (
     <Input
@@ -324,8 +344,20 @@ export function RenderList(props: RenderListProps): ReactNode {
   const hasToolbarActions = toolbarActions !== undefined && toolbarActions.length > 0;
   const hasHeaderSlot = screen.slots?.header !== undefined;
   const toolbarIconOnly = hasToolbarActions && shouldRenderActionsIconOnly(toolbarActions);
+  const createButton =
+    onCreate !== undefined ? (
+      <Button
+        variant="primary"
+        icon="plus"
+        onClick={onCreate}
+        testId="render-list-create"
+        className="px-3.5"
+      >
+        {effectiveCreateLabel}
+      </Button>
+    ) : undefined;
   const toolbarEnd =
-    hasHeaderSlot || hasToolbarActions || onCreate !== undefined ? (
+    hasHeaderSlot || hasToolbarActions || (onCreate !== undefined && !createInPageHeader) ? (
       <>
         {hasHeaderSlot && <ListHeaderSlotMount screen={screen} />}
         {hasToolbarActions &&
@@ -339,11 +371,7 @@ export function RenderList(props: RenderListProps): ReactNode {
               Banner={Banner}
             />
           ))}
-        {onCreate !== undefined && (
-          <Button variant="primary" onClick={onCreate} testId="render-list-create">
-            {`+ ${effectiveCreateLabel}`}
-          </Button>
-        )}
+        {!createInPageHeader && createButton}
       </>
     ) : undefined;
 
@@ -357,8 +385,8 @@ export function RenderList(props: RenderListProps): ReactNode {
       <>
         <Text>{translate("kumiko.list.empty.title")}</Text>
         <Text variant="small">{translate("kumiko.list.empty.hint")}</Text>
-        <Button variant="primary" onClick={onCreate} testId="render-list-empty-create">
-          {`+ ${effectiveCreateLabel}`}
+        <Button variant="primary" icon="plus" onClick={onCreate} testId="render-list-empty-create">
+          {effectiveCreateLabel}
         </Button>
       </>
     ) : undefined);
@@ -374,6 +402,7 @@ export function RenderList(props: RenderListProps): ReactNode {
   // ListSort = DataTableSort (use-list-url-state aliased) — kein Cast nötig.
   return (
     <>
+      {createInPageHeader && PageHeader !== undefined && <PageHeader actions={createButton} />}
       {referenceColumns.map(
         (rc: { field: string; refEntity: string; refFeature: string; labelField: string }) => (
           <ReferenceLookupBridge
@@ -393,6 +422,7 @@ export function RenderList(props: RenderListProps): ReactNode {
         {...(onRowClick !== undefined && { onRowClick })}
         {...(composedEmptyState !== undefined && { emptyState: composedEmptyState })}
         {...(toolbarStart !== undefined && { toolbarStart })}
+        {...(description !== undefined && !searchable && { toolbarDescription: description })}
         {...(toolbarEnd !== undefined && { toolbarEnd })}
         {...(sort !== undefined && { sort })}
         {...(onSortChange !== undefined && { onSortChange })}
@@ -400,6 +430,7 @@ export function RenderList(props: RenderListProps): ReactNode {
         {...(onReachEnd !== undefined && { onReachEnd })}
         {...(loadingMore !== undefined && { loadingMore })}
         {...(hasMore !== undefined && { hasMore })}
+        {...(itemNoun !== undefined && { itemNoun })}
         {...(rowActions !== undefined && { rowActions })}
         {...(rowActionMode !== undefined && { rowActionMode })}
         {...(filterFacets !== undefined && { filterFacets })}
@@ -529,7 +560,8 @@ function ToolbarActionView({
         variant={variant}
         loading={busy}
         {...(action.icon !== undefined && { icon: action.icon })}
-        {...(showIconOnly && { size: "icon" as const, ariaLabel: action.label })}
+        size={showIconOnly ? "icon" : "sm"}
+        {...(showIconOnly && { ariaLabel: action.label })}
         onClick={() => {
           if (needsConfirm) {
             setConfirmOpen(true);

package/src/components/write-form-section.tsx

@@ -144,7 +144,6 @@ export function WriteFormSection({
     <Button
       type="button"
       variant="primary"
-      icon="check"
       disabled={isSubmitting}
       loading={isSubmitting}
       onClick={() => void handleSubmit()}

package/src/hooks/__tests__/use-query.test.tsx

@@ -0,0 +1,149 @@
+import { afterEach, beforeEach, describe, expect, jest, test } from "bun:test";
+import type { Dispatcher } from "@cosmicdrift/kumiko-headless";
+import { act, renderHook } from "@testing-library/react";
+import type { ReactNode } from "react";
+import { DispatcherProvider } from "../../context/dispatcher-context";
+import { useQuery } from "../use-query";
+
+type QueryFn = Dispatcher["query"];
+
+function makeDispatcher(query: QueryFn): Dispatcher {
+  return {
+    write: (async () => ({ isSuccess: true, data: {} })) as unknown as Dispatcher["write"],
+    query,
+    batch: (async () => ({ isSuccess: true, results: [] })) as unknown as Dispatcher["batch"],
+    statusStore: {
+      getState: () => "online",
+      subscribe: () => () => {},
+    } as unknown as Dispatcher["statusStore"],
+    async *stream() {},
+    pendingWrites: () => [],
+    pendingFiles: () => [],
+  };
+}
+
+function wrapperFor(dispatcher: Dispatcher) {
+  return ({ children }: { readonly children: ReactNode }) => (
+    <DispatcherProvider dispatcher={dispatcher}>{children}</DispatcherProvider>
+  );
+}
+
+function countingDispatcher(): { dispatcher: Dispatcher; calls: () => number } {
+  let calls = 0;
+  const query = (async () => {
+    calls += 1;
+    return { isSuccess: true, data: { n: calls } };
+  }) as unknown as QueryFn;
+  return { dispatcher: makeDispatcher(query), calls: () => calls };
+}
+
+async function advance(ms: number): Promise<void> {
+  await act(async () => {
+    jest.advanceTimersByTime(ms);
+  });
+}
+
+const QUERY_TYPE = "f:query:x:list";
+
+describe("useQuery refetchIntervalMs", () => {
+  beforeEach(() => {
+    jest.useFakeTimers();
+  });
+  afterEach(() => {
+    jest.useRealTimers();
+  });
+
+  test("re-runs the query on every interval tick", async () => {
+    const { dispatcher, calls } = countingDispatcher();
+    const { result } = renderHook(
+      () => useQuery<{ n: number }>(QUERY_TYPE, {}, { refetchIntervalMs: 1000 }),
+      {
+        wrapper: wrapperFor(dispatcher),
+      },
+    );
+    await advance(0);
+    expect(calls()).toBe(1);
+
+    await advance(1000);
+    expect(calls()).toBe(2);
+    await advance(1000);
+    expect(calls()).toBe(3);
+    expect(result.current.data).toEqual({ n: 3 });
+  });
+
+  test("unmount stops the ticks", async () => {
+    const { dispatcher, calls } = countingDispatcher();
+    const { unmount } = renderHook(() => useQuery(QUERY_TYPE, {}, { refetchIntervalMs: 1000 }), {
+      wrapper: wrapperFor(dispatcher),
+    });
+    await advance(1000);
+    const before = calls();
+    unmount();
+    await advance(5000);
+    expect(calls()).toBe(before);
+  });
+
+  test("enabled: false never ticks", async () => {
+    const { dispatcher, calls } = countingDispatcher();
+    renderHook(() => useQuery(QUERY_TYPE, {}, { enabled: false, refetchIntervalMs: 1000 }), {
+      wrapper: wrapperFor(dispatcher),
+    });
+    await advance(5000);
+    expect(calls()).toBe(0);
+  });
+
+  test("a tick while a fetch is in flight is skipped instead of aborting it", async () => {
+    let calls = 0;
+    let release: (() => void) | undefined;
+    const query = (async (_type: string, _payload: unknown, opts?: { signal?: AbortSignal }) => {
+      calls += 1;
+      await new Promise<void>((resolve) => {
+        release = resolve;
+      });
+      return opts?.signal?.aborted
+        ? { isSuccess: false, error: { code: "aborted", message: "aborted", i18nKey: "x" } }
+        : { isSuccess: true, data: { done: true } };
+    }) as unknown as QueryFn;
+    const { result } = renderHook(
+      () => useQuery<{ done: boolean }>(QUERY_TYPE, {}, { refetchIntervalMs: 1000 }),
+      {
+        wrapper: wrapperFor(makeDispatcher(query)),
+      },
+    );
+    await advance(0);
+    expect(calls).toBe(1);
+
+    await advance(3000);
+    expect(calls).toBe(1);
+
+    await act(async () => {
+      release?.();
+    });
+    expect(result.current.data).toEqual({ done: true });
+
+    await advance(1000);
+    expect(calls).toBe(2);
+  });
+
+  test("background ticks do not flip loading to true", async () => {
+    const { dispatcher, calls } = countingDispatcher();
+    const seenLoading: boolean[] = [];
+    const { result } = renderHook(
+      () => {
+        const r = useQuery<{ n: number }>(QUERY_TYPE, {}, { refetchIntervalMs: 1000 });
+        seenLoading.push(r.loading);
+        return r;
+      },
+      { wrapper: wrapperFor(dispatcher) },
+    );
+    await advance(0);
+    expect(result.current.loading).toBe(false);
+    seenLoading.length = 0;
+
+    await advance(1000);
+    await advance(1000);
+    expect(calls()).toBe(3);
+    expect(result.current.data).toEqual({ n: 3 });
+    expect(seenLoading.every((l) => l === false)).toBe(true);
+  });
+});

package/src/hooks/use-list-url-state.ts

@@ -30,6 +30,8 @@ export type ListUrlState = {
   /** 1-basierte Page-Nummer. Bei pagination="infinite" oder false ist
    *  der Wert ignoriert; Caller liest ihn nur wenn relevant. */
   readonly page: number;
+  /** User-chosen page size from `PAGE_SIZE_OPTIONS`; undefined = screen default. */
+  readonly pageSize: number | undefined;
   /** Aktive Faceted-Filter: field → ausgewählte Werte (Strings; Caller
    *  coerced pro Field-Type). Leer wenn kein Filter gesetzt. */
   readonly filters: Readonly<Record<string, readonly string[]>>;
@@ -43,6 +45,8 @@ export type ListUrlStateApi = ListUrlState & {
   readonly setQ: (next: string) => void;
   /** Setzt die Page. 1 oder kleiner löscht den Key (Default-Page). */
   readonly setPage: (next: number) => void;
+  /** Sets the page size and resets the page; undefined clears the key. */
+  readonly setPageSize: (next: number | undefined) => void;
   /** Setzt die ausgewählten Werte eines Facet-Felds. Leeres Array löscht
    *  den Key. Resettet die Page (wie sort/search). */
   readonly setFilter: (field: string, values: readonly string[]) => void;
@@ -61,6 +65,14 @@ export type ListUrlStateApi = ListUrlState & {
 // `.` als Trenner: lesbar (`?orders.sort=name`), kollidiert nicht mit
 // üblichen Field-Namen (kebab- oder camelCase ohne Punkt). Boot-Validator
 // pinnt screen.id ohne Punkt — siehe boot-validator entityList Section.
+export const PAGE_SIZE_OPTIONS: readonly number[] = [25, 50, 100];
+
+function parsePageSize(value: string | undefined): number | undefined {
+  if (value === undefined) return undefined;
+  const n = Number.parseInt(value, 10);
+  return PAGE_SIZE_OPTIONS.includes(n) ? n : undefined;
+}
+
 function key(screenId: string, suffix: string): string {
   return `${screenId}.${suffix}`;
 }
@@ -88,6 +100,7 @@ export function useListUrlState(screenId: string): ListUrlStateApi {
 
   const q = params[key(screenId, "q")] ?? "";
   const page = parsePage(params[key(screenId, "page")]);
+  const pageSize = parsePageSize(params[key(screenId, "size")]);
 
   const filterPrefix = `${screenId}.f.`;
   const filters = useMemo<Readonly<Record<string, readonly string[]>>>(() => {
@@ -140,6 +153,16 @@ export function useListUrlState(screenId: string): ListUrlStateApi {
     [nav, screenId],
   );
 
+  const setPageSize = useCallback(
+    (next: number | undefined) => {
+      nav.setSearchParams({
+        [key(screenId, "size")]: next === undefined ? null : String(next),
+        [key(screenId, "page")]: null,
+      });
+    },
+    [nav, screenId],
+  );
+
   const setFilter = useCallback(
     (field: string, values: readonly string[]) => {
       nav.setSearchParams({
@@ -167,5 +190,18 @@ export function useListUrlState(screenId: string): ListUrlStateApi {
     nav.setSearchParams(updates);
   }, [nav, screenId, filters]);
 
-  return { sort, q, page, filters, setSort, setQ, setPage, setFilter, clearFilters, setDateRange };
+  return {
+    sort,
+    q,
+    page,
+    pageSize,
+    filters,
+    setSort,
+    setQ,
+    setPage,
+    setPageSize,
+    setFilter,
+    clearFilters,
+    setDateRange,
+  };
 }

package/src/hooks/use-query.ts

@@ -38,6 +38,10 @@ export type UseQueryOptions = {
   // `<feature>:query:<entity>:<verb>` convention — if the type
   // doesn't follow that shape, live-mode is a no-op.
   readonly live?: boolean;
+  // Re-runs the query every N ms while enabled. Ticks are silent (no
+  // `loading` flip) and skipped while a fetch is still in flight. Only
+  // timers are used, so it behaves the same on web and React Native.
+  readonly refetchIntervalMs?: number;
 };
 
 // Extract the entity-name from a standard Kumiko query type. Returns
@@ -57,7 +61,7 @@ export function useQuery<TData = unknown>(
   options: UseQueryOptions = {},
 ): UseQueryResult<TData> {
   const dispatcher = useDispatcher();
-  const { enabled = true, live = false } = options;
+  const { enabled = true, live = false, refetchIntervalMs } = options;
 
   const [data, setData] = useState<TData | null>(null);
   const [error, setError] = useState<DispatcherError | null>(null);
@@ -67,6 +71,9 @@ export function useQuery<TData = unknown>(
   // call can cancel the older one. Ref, not state, because the
   // controller identity shouldn't trigger a re-render.
   const activeCtrl = useRef<AbortController | null>(null);
+  // A tick that aborted a running fetch would starve slow queries, so
+  // ticks consult this flag instead.
+  const fetchInFlight = useRef(false);
 
   // Serialize payload so object-identity-changes across renders (the
   // caller building a fresh `{}` every render) don't loop. Strings are
@@ -77,29 +84,42 @@ export function useQuery<TData = unknown>(
   // are the meaningful re-run triggers. `payload` itself is intentionally
   // not in deps — it's serialized into payloadKey above.
   // biome-ignore lint/correctness/useExhaustiveDependencies: payload goes through payloadKey
-  const run = useCallback(async (): Promise<void> => {
-    // Abort whatever's in flight. observer on Safari 17+ handles this
-    // without raising a fetch-throw in the previous caller — they
-    // already set the error path.
-    activeCtrl.current?.abort();
-    const ctrl = new AbortController();
-    activeCtrl.current = ctrl;
+  const runFetch = useCallback(
+    async (background: boolean): Promise<void> => {
+      // Abort whatever's in flight. observer on Safari 17+ handles this
+      // without raising a fetch-throw in the previous caller — they
+      // already set the error path.
+      activeCtrl.current?.abort();
+      const ctrl = new AbortController();
+      activeCtrl.current = ctrl;
 
-    setLoading(true);
-    const result = await dispatcher.query<TData>(type, payload, { signal: ctrl.signal });
-    // skip: a newer fetch already superseded this one, don't clobber its state
-    if (ctrl.signal.aborted) return;
-    if (result.isSuccess) {
-      setData(result.data);
-      setError(null);
-    } else {
-      // A cancelled request comes back with code "aborted" from the
-      // skip: aborted request, a newer run already replaces this result
-      if (result.error.code === "aborted") return;
-      setError(result.error);
-    }
-    setLoading(false);
-  }, [dispatcher, type, payloadKey]);
+      fetchInFlight.current = true;
+      if (!background) setLoading(true);
+      let result: Awaited<ReturnType<typeof dispatcher.query<TData>>>;
+      try {
+        result = await dispatcher.query<TData>(type, payload, { signal: ctrl.signal });
+      } finally {
+        // A rejected fetch must not leave polling stuck; a superseded one must
+        // not clear the newer fetch's flag.
+        if (activeCtrl.current === ctrl) fetchInFlight.current = false;
+      }
+      // skip: a newer fetch already superseded this one, don't clobber its state
+      if (ctrl.signal.aborted) return;
+      if (result.isSuccess) {
+        setData(result.data);
+        setError(null);
+      } else {
+        // A cancelled request comes back with code "aborted" from the
+        // skip: aborted request, a newer run already replaces this result
+        if (result.error.code === "aborted") return;
+        setError(result.error);
+      }
+      setLoading(false);
+    },
+    [dispatcher, type, payloadKey],
+  );
+
+  const run = useCallback((): Promise<void> => runFetch(false), [runFetch]);
 
   useEffect(() => {
     if (!enabled) {
@@ -110,9 +130,23 @@ export function useQuery<TData = unknown>(
     void run();
     return () => {
       activeCtrl.current?.abort();
+      fetchInFlight.current = false;
     };
   }, [enabled, run]);
 
+  useEffect(() => {
+    // skip: polling off or disabled query
+    if (!enabled || refetchIntervalMs === undefined) return;
+    // skip: non-positive or non-finite interval disables polling
+    if (!Number.isFinite(refetchIntervalMs) || refetchIntervalMs <= 0) return;
+    const timer = setInterval(() => {
+      // skip: a fetch is still running, the next tick retries
+      if (fetchInFlight.current) return;
+      void runFetch(true);
+    }, refetchIntervalMs);
+    return () => clearInterval(timer);
+  }, [enabled, refetchIntervalMs, runFetch]);
+
   // Live-mode: auf SSE-Events für die Query-Entity hören und refetchen.
   // Separater Effect, damit eine Änderung an `live` oder `type` das
   // Subscription-Lifecycle genau einmal durchwalzt.

package/src/i18n-defaults.ts

@@ -65,15 +65,31 @@ export const kumikoDefaultTranslations: TranslationsByLocale = {
     "kumiko.list.sort.label": "Sort",
     "kumiko.list.sort.unsorted": "Unsorted",
     "kumiko.list.filter.reset": "Reset",
+    "kumiko.list.filter.toggle": "Filters",
     "kumiko.list.related-list-truncated":
       "Showing the first {count} entries. More are available but not loaded — this list does not paginate.",
     "kumiko.reference.system-tenant": "System",
     "kumiko.reference.system-user": "System",
 
     "kumiko.pager.status": "{from}–{to} of {total}",
+    "kumiko.pager.pageOf": "Page {page} of {pages}",
+    "kumiko.form.all-required": "All fields are required.",
+    "kumiko.pager.status.noun": "{from}–{to} of {total} {noun}",
+    "kumiko.pager.pageSize": "{size} per page",
+    "kumiko.pager.pageSizeLabel": "Entries per page",
+    "kumiko.list.count.noun": "{count} {noun}",
+    "kumiko.list.count.one": "1 entry",
+    "kumiko.list.count.other": "{count} entries",
+    "kumiko.list.row-actions.more": "More actions",
+    "kumiko.list.sort.by": "Sorted by {column}",
+    "kumiko.form.changed": "changed",
+    "kumiko.form.on-this-page": "On this page",
+    "kumiko.form.unsaved.one": "1 unsaved change",
+    "kumiko.form.unsaved.other": "{count} unsaved changes",
+    "kumiko.wizard.next-with-title": "Next: {title}",
+    "kumiko.wizard.save-and-close": "Save and close",
     "kumiko.pager.previousPage": "Previous page",
     "kumiko.pager.nextPage": "Next page",
-    "kumiko.pager.page": "Page {entry}",
 
     "kumiko.combobox.search-placeholder": "Search…",
     "kumiko.combobox.empty": "No matches.",
@@ -123,6 +139,10 @@ export const kumikoDefaultTranslations: TranslationsByLocale = {
     "kumiko.dialog.confirm": "Confirm",
     "kumiko.dialog.cancel": "Cancel",
     "kumiko.dialog.close": "Close",
+    "kumiko.drawer.discard.title": "Discard changes?",
+    "kumiko.drawer.discard.body": "Your input in this form will be lost.",
+    "kumiko.drawer.discard.confirm": "Discard",
+    "kumiko.drawer.discard.cancel": "Keep editing",
 
     "kumiko.aiText.acceptHint": "Tab = accept, Esc = discard",
     "kumiko.aiText.correct": "Correct",

package/src/index.ts

@@ -188,6 +188,8 @@ export {
   useTranslation,
 } from "./i18n";
 export { kumikoDefaultTranslations } from "./i18n-defaults";
+export { InsideDrawerProvider, useInsideDrawer } from "./inside-drawer";
+export { PageHeaderSlotAvailableProvider, usePageHeaderSlotAvailable } from "./page-header-slot";
 export type {
   ActionMenuItemSpec,
   ActionOverflowMenuProps,
@@ -212,9 +214,11 @@ export type {
   EmbeddedListColumn,
   EmbeddedListInputProps,
   EmbeddedListTotal,
+  FieldCellWidth,
   FieldProps,
   FillContainerProps,
   FormProps,
+  FormSectionNavItem,
   FormWidth,
   GridCellProps,
   GridProps,
@@ -223,8 +227,10 @@ export type {
   JsonViewProps,
   LightboxProps,
   LinkProps,
+  MetricBandProps,
   MetricProps,
   ModalProps,
+  PageHeaderProps,
   PrimitivesProviderProps,
   PrimitivesRegistry,
   ProgressProps,
@@ -249,6 +255,7 @@ export {
   PrimitivesProvider,
   STICKY_PRIMARY_ACTION_PROP,
   shouldRenderActionsIconOnly,
+  statusToneForOptionTone,
   statusToneForValue,
   usePrimitives,
 } from "./primitives";

package/src/inside-drawer.ts

@@ -0,0 +1,12 @@
+import { createContext, useContext } from "react";
+
+// True while a form renders inside the Drawer primitive (DrawerHost). The form
+// then drops its own title and card chrome (the drawer header carries the
+// title) and lays out as scrolling body plus pinned footer.
+const InsideDrawerContext = createContext(false);
+
+export const InsideDrawerProvider = InsideDrawerContext.Provider;
+
+export function useInsideDrawer(): boolean {
+  return useContext(InsideDrawerContext);
+}

package/src/page-header-slot.ts

@@ -0,0 +1,12 @@
+import { createContext, useContext } from "react";
+
+// True while the screen renders below an app shell that offers page-header
+// slots (see the PageHeader primitive). Embedded hosts (drawer, dashboard
+// panel) reset it to false so their inner screens keep their own placement.
+const PageHeaderSlotAvailableContext = createContext(false);
+
+export const PageHeaderSlotAvailableProvider = PageHeaderSlotAvailableContext.Provider;
+
+export function usePageHeaderSlotAvailable(): boolean {
+  return useContext(PageHeaderSlotAvailableContext);
+}