@cosmicdrift/kumiko-renderer 0.326.1 → 0.328.0

package/src/changes.json

@@ -1,4 +1,56 @@
 [
+  {
+    "version": "0.328.0",
+    "type": "breaking",
+    "title": "Screens fill the shell height by default",
+    "detail": "entityList, projectionList, projectionDetail, entityEdit, actionForm and wizard screens now fill the height of the shell content. The table or the form body scrolls inside, the toolbar stays on top and the pager or action bar stays pinned at the bottom (`scrollBody`, `stickyActions`). The shell header is 56px. Custom screens and direct DataTable or Form usage are unchanged.",
+    "migration": "Set `fillHeight: false` on a screen to restore the old page scrolling (table grows with its rows, pager below the last row, form footer in the flow). Apps with e2e or screenshot tests that scroll the page to reach the pager or the form footer need to adjust them or opt out per screen."
+  },
+  {
+    "version": "0.328.0",
+    "type": "breaking",
+    "title": "Pager shows a status line, page size select and Page X of Y instead of page numbers",
+    "detail": "The numbered page list is gone. The list footer shows \"1-19 of 19 <entities>\" (with the entity plural label when known), \"Page X of Y\", previous and next buttons and a page size select (25, 50, 100). Lists without a pager show a plain entry count. The chosen size is kept in the URL under `<screen>.size`.",
+    "migration": "Remove code and tests that click numbered page buttons (`-page-N` test ids); use the next and previous buttons. The screen's declared `pageSize` stays the default, `<screen>.size` in the URL overrides it. The new keys `kumiko.pager.pageOf`, `kumiko.pager.status.noun`, `kumiko.pager.pageSize`, `kumiko.pager.pageSizeLabel`, `kumiko.list.count.*` exist in en, de and es; apps with their own locale need them too."
+  },
+  {
+    "version": "0.328.0",
+    "type": "breaking",
+    "title": "rowActionMode adaptive has new semantics and mobile rows lose the kebab for plain navigation",
+    "detail": "With `rowActionMode: \"adaptive\"` (the default), a table with `onRowClick` renders the first cell as a keyboard-operable link and puts all row actions into the kebab. Without `onRowClick` the primary row action is a link-button and the remaining actions go into the kebab (a single action gets no kebab). Below the md breakpoint a row that only navigates shows a chevron and no kebab.",
+    "migration": "Code or tests that expect up to two inline row action buttons must open the kebab or use `rowActionMode: \"inline\"`, which is unchanged. To keep a visible action next to the row link, drop `onRowClick` and declare the action as the primary row action."
+  },
+  {
+    "version": "0.328.0",
+    "type": "breaking",
+    "title": "Form, wizard and detail screens use the board layout",
+    "detail": "Screen forms have no card, sections are separated by lines, fields flow in rows with widths by type (text 240px, number 96px, money 160px, date and select 200px, textarea full row) and the page title lives in the shell header. Delete and Copy link move into the header kebab, the footer reads status, Cancel, Save, and the wizard footer has no Cancel. Wizard steps sit in a vertical rail from the lg breakpoint. The first detail header action is a button, further ones sit in the kebab. Detail screens have no header card and use the full width: metrics render as a dl band, tabs are underlined only when active, related lists are full-bleed with a count footer. Required-field asterisks are omitted when every field is required and \"All fields are required.\" is shown instead.",
+    "migration": "Adjust screenshots and DOM tests that pin the old card layout. `fillHeight: false` restores page scrolling only; the footer order, the moved actions and the new field layout apply in both modes. Empty list cells render a dash."
+  },
+  {
+    "version": "0.328.0",
+    "type": "improvement",
+    "title": "PageHeader slot, MetricBand, wizard Save and close, drawer row actions with unsaved-input guard",
+    "detail": "Core primitives `PageHeader` (status and actions portalled into the shell header when a shell provides the slot, otherwise the caller keeps its placement) and `MetricBand` (borderless dl of metrics) are new and optional. Wizards on an existing record show \"Save and close\". Row actions and related list row actions with `kind: \"drawer\"` open the action form in a flush drawer. Closing it with unsaved input (X, Escape, overlay, Cancel) asks for confirmation first; nothing is asked after a successful submit. Row action drawers are prefilled from the row through `params`. The action form `summary` renders a context box above the fields."
+  },
+  {
+    "version": "0.328.0",
+    "type": "fix",
+    "title": "Related list no longer claims \"showing the first N entries\" for a complete list",
+    "detail": "The hint \"Zeigt die ersten 1 Einträge. Es gibt weitere, die hier nicht angezeigt werden.\" appeared for a single row even when nothing else existed. It now appears only when more rows exist than were loaded."
+  },
+  {
+    "version": "0.328.0",
+    "type": "improvement",
+    "title": "writeForm section Save button without icon, parity with entityEdit",
+    "detail": "The Save button of a writeForm section no longer shows a check icon; it matches the entityEdit submit button. Tests that look for the icon inside the section Save button need updating."
+  },
+  {
+    "version": "0.328.0",
+    "type": "improvement",
+    "title": "useQuery gains a refetchIntervalMs option for polling",
+    "detail": "With `refetchIntervalMs` set, an enabled query re-runs on a timer. Background ticks keep `loading` false, are skipped while a fetch is still in flight, and stop on unmount or when enabled, the interval, type or payload change. Only timers are used, so it works on web and React Native."
+  },
   {
     "version": "0.325.2",
     "type": "fix",

package/src/components/__tests__/related-list-section.test.tsx

@@ -1,4 +1,4 @@
-import { describe, expect, spyOn, test } from "bun:test";
+import { beforeEach, describe, expect, spyOn, test } from "bun:test";
 import type { EntityEditScreenDefinition, RowAction } from "@cosmicdrift/kumiko-framework/ui-types";
 import type { Dispatcher, EditRelatedListSectionViewModel } from "@cosmicdrift/kumiko-headless";
 import { act, fireEvent, render, screen as rtlScreen, waitFor } from "@testing-library/react";
@@ -6,6 +6,7 @@ import type { ComponentType, ReactNode } from "react";
 import { AppFeaturesProvider } from "../../app/app-features-context";
 import type { FeatureSchema } from "../../app/feature-schema";
 import { type NavApi, NavProvider } from "../../app/nav";
+import { resetDrawerActionWarningsForTests } from "../../app/row-actions";
 import { DispatcherProvider } from "../../context/dispatcher-context";
 import { UserRolesProvider } from "../../context/user-roles-context";
 import { createStaticLocaleResolver, LocaleProvider } from "../../i18n";
@@ -95,6 +96,7 @@ function testPrimitives(): CorePrimitives {
 function stubDispatcher(
   rows: readonly Record<string, unknown>[] = [{ id: "r1", name: "Alice" }],
   nextCursor: string | null = null,
+  envelope: { readonly total?: number; readonly omitCursor?: boolean } = {},
 ): {
   dispatcher: Dispatcher;
   writes: Array<{ type: string; payload: unknown }>;
@@ -109,7 +111,14 @@ function stubDispatcher(
     }) as Dispatcher["write"],
     query: (async () => {
       queryCalls += 1;
-      return { isSuccess: true, data: { rows, nextCursor } };
+      return {
+        isSuccess: true,
+        data: {
+          rows,
+          ...(envelope.omitCursor !== true && { nextCursor }),
+          ...(envelope.total !== undefined && { total: envelope.total }),
+        },
+      };
     }) as Dispatcher["query"],
     batch: (async () => ({ isSuccess: true, results: [] })) as Dispatcher["batch"],
     statusStore: {
@@ -188,6 +197,42 @@ function renderRelatedList(
   );
 }
 
+describe("RelatedListSection column value type", () => {
+  test("a column declaring valueType money reaches the table as a money column", async () => {
+    const { dispatcher } = stubDispatcher();
+    let capturedTypes: Record<string, string | undefined> = {};
+    const capturingDataTable: ComponentType<DataTableProps> = (props) => {
+      capturedTypes = Object.fromEntries(props.columns.map((c) => [c.field, c.type]));
+      return testDataTable(props);
+    };
+    render(
+      <LocaleProvider
+        resolver={createStaticLocaleResolver({ locale: "en-US" })}
+        fallbackBundles={[kumikoDefaultTranslations]}
+      >
+        <DispatcherProvider dispatcher={dispatcher}>
+          <PrimitivesProvider value={{ ...testPrimitives(), DataTable: capturingDataTable }}>
+            <NavProvider value={stubNav().nav}>
+              <RelatedListSection
+                section={{
+                  ...historySection,
+                  columns: [{ field: "name" }, { field: "betrag", valueType: "money" }],
+                }}
+                parentId="order-1"
+                record={{ id: "order-1" }}
+                featureName="orders"
+              />
+            </NavProvider>
+          </PrimitivesProvider>
+        </DispatcherProvider>
+      </LocaleProvider>,
+    );
+    await waitFor(() => expect(rtlScreen.getByTestId("row-r1")).toBeTruthy());
+    expect(capturedTypes["betrag"]).toBe("money");
+    expect(capturedTypes["name"]).toBe("text");
+  });
+});
+
 describe("RelatedListSection — tabs-mode card chrome (fw#2722)", () => {
   test("hideTitle (tabs mode) renders the list without a Section wrapper, drops the table frame (the tab card frames it), and marks scrollBody", async () => {
     const { dispatcher } = stubDispatcher();
@@ -736,6 +781,10 @@ describe("RelatedListSection — rowActions", () => {
 // pins that hand-off, not the Drawer UI itself (covered by kumiko-screen's
 // own tests).
 describe("RelatedListSection — rowActions drawer-kind (fw#2710)", () => {
+  beforeEach(() => {
+    resetDrawerActionWarningsForTests();
+  });
+
   test("clicking a drawer rowAction calls onOpenDrawer with the action and the row's extracted values", async () => {
     const { dispatcher } = stubDispatcher([{ id: "item-7", name: "Rent 2024", amount: 1200 }]);
     const openDrawerCalls: unknown[][] = [];
@@ -1041,6 +1090,26 @@ describe("RelatedListSection — truncation banner (fw#2722 review)", () => {
     expect(rtlScreen.queryByTestId("related-list-truncated")).toBeNull();
   });
 
+  test("a handler that omits nextCursor renders no truncation banner, even at exactly one row", async () => {
+    const { dispatcher } = stubDispatcher([{ id: "r1", name: "Alice" }], null, {
+      omitCursor: true,
+    });
+    renderRelatedList(dispatcher);
+
+    await waitFor(() => expect(rtlScreen.getByTestId("row-r1")).toBeTruthy());
+    expect(rtlScreen.queryByTestId("related-list-truncated")).toBeNull();
+  });
+
+  test("a cursor with a total the rows already cover renders no truncation banner", async () => {
+    const { dispatcher } = stubDispatcher([{ id: "r1", name: "Alice" }], "cursor-abc", {
+      total: 1,
+    });
+    renderRelatedList(dispatcher);
+
+    await waitFor(() => expect(rtlScreen.getByTestId("row-r1")).toBeTruthy());
+    expect(rtlScreen.queryByTestId("related-list-truncated")).toBeNull();
+  });
+
   test("the banner shows regardless of an active sort — an unsorted truncated list is equally misleading", async () => {
     const { dispatcher } = stubDispatcher(
       [

package/src/components/__tests__/render-list-toolbar-icon-only.test.tsx

@@ -128,7 +128,7 @@ describe("RenderList toolbar actions collapse to icon-only", () => {
     renderToolbar([toolbarAction("sync", "Sync", true), toolbarAction("export", "Export", true)]);
 
     const button = rtlScreen.getByTestId("render-list-toolbar-action-sync");
-    expect(button.getAttribute("data-size")).toBe("md");
+    expect(button.getAttribute("data-size")).toBe("sm");
     expect(button.textContent).toBe("Sync");
   });
 
@@ -140,7 +140,7 @@ describe("RenderList toolbar actions collapse to icon-only", () => {
     ]);
 
     const button = rtlScreen.getByTestId("render-list-toolbar-action-sync");
-    expect(button.getAttribute("data-size")).toBe("md");
+    expect(button.getAttribute("data-size")).toBe("sm");
     expect(button.textContent).toBe("Sync");
   });
 });

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

@@ -188,7 +188,7 @@ describe("WriteFormSection", () => {
 
     expect(actions.contains(button)).toBe(true);
     expect(body.contains(button)).toBe(false);
-    expect(button.dataset["icon"]).toBe("check");
+    expect(button.dataset["icon"]).toBeUndefined();
   });
 
   test("submit dispatches through the section's configured write handler with the entered values", async () => {

package/src/components/grid-cell-for-field.tsx

@@ -1,6 +1,6 @@
 import type { EditFieldViewModel, FieldIssue } from "@cosmicdrift/kumiko-headless";
 import type { ReactNode } from "react";
-import type { usePrimitives } from "../primitives";
+import type { FieldCellWidth, usePrimitives } from "../primitives";
 import { RenderField } from "./render-field";
 
 // Extracted out of render-edit.tsx so write-form-section.tsx can reuse it
@@ -23,8 +23,33 @@ export type GridCellForFieldProps = {
   readonly valueDisplay: "form" | "text";
   /** Passed through to RenderField as `row` — see RenderFieldProps.row. */
   readonly row: Readonly<Record<string, unknown>>;
+  readonly changed?: boolean;
+  readonly flow?: boolean;
 };
 
+const FIELD_CELL_WIDTH_BY_TYPE: Readonly<Record<string, FieldCellWidth>> = {
+  number: "number",
+  decimal: "number",
+  bigInt: "number",
+  money: "money",
+  date: "date",
+  select: "select",
+  multiSelect: "select",
+  boolean: "auto",
+  longText: "full",
+  embedded: "full",
+  jsonb: "full",
+  file: "full",
+  files: "full",
+  image: "full",
+  images: "full",
+};
+
+function fieldCellWidth(field: EditFieldViewModel): FieldCellWidth {
+  if (field.span !== undefined || (field.type === "text" && field.multiline)) return "full";
+  return FIELD_CELL_WIDTH_BY_TYPE[field.type] ?? "text";
+}
+
 export function GridCellForField({
   field,
   columns,
@@ -37,13 +62,15 @@ export function GridCellForField({
   allIssues,
   valueDisplay,
   row,
+  changed,
+  flow,
 }: GridCellForFieldProps): ReactNode {
   // RenderField renders nothing for a hidden field, but the GridCell around it still claims the row.
   if (!field.visible) return null;
 
   const effectiveSpan = field.span !== undefined ? Math.min(field.span, columns) : 1;
   return (
-    <GridCell span={effectiveSpan}>
+    <GridCell span={effectiveSpan} {...(flow === true && { width: fieldCellWidth(field) })}>
       <RenderField
         field={field}
         {...(issues !== undefined && { issues })}
@@ -54,6 +81,7 @@ export function GridCellForField({
         allIssues={allIssues}
         valueDisplay={valueDisplay}
         row={row}
+        {...(changed === true && { changed })}
       />
     </GridCell>
   );

package/src/components/related-list-section.tsx

@@ -35,6 +35,7 @@ import { useUserRoles } from "../context/user-roles-context";
 import type { ListSort } from "../hooks/use-list-url-state";
 import { useQuery } from "../hooks/use-query";
 import { useTranslation } from "../i18n";
+import { PageHeaderSlotAvailableProvider } from "../page-header-slot";
 import { type DataTableFacet, usePrimitives } from "../primitives";
 import { sortByAccessor } from "../sort-by-accessor";
 import { RenderEditActionButton } from "./render-edit-action-button";
@@ -58,10 +59,13 @@ type PagedRows = {
 function synthesizeRelatedListEntity(
   columns: EditRelatedListSectionViewModel["columns"],
 ): EntityDefinition {
-  const fields: Record<string, { type: "text"; sortable: boolean }> = {};
+  const fields: Record<string, { type: string; sortable: boolean }> = {};
   for (const col of columns) {
     const normalized = normalizeListColumn(col);
-    fields[normalized.field] = { type: "text", sortable: normalized.sortable === true };
+    fields[normalized.field] = {
+      type: normalized.valueType ?? "text",
+      sortable: normalized.sortable === true,
+    };
   }
   return { fields } as unknown as EntityDefinition;
 }
@@ -84,6 +88,7 @@ export function RelatedListSection({
   featureName,
   translate,
   hideTitle,
+  grow,
   onOpenDrawer,
   actions,
 }: {
@@ -96,6 +101,8 @@ export function RelatedListSection({
   readonly featureName: string;
   readonly translate?: Translate;
   readonly hideTitle?: boolean;
+  /** Under a fixed-height screen the tab panel chain stretches so the count footer sits at the bottom. */
+  readonly grow?: boolean;
   /** Opens a drawer-kind rowAction (fw#2710). Supplied by the parent
    *  (ProjectionDetailBody), which owns schema + the actual Drawer render —
    *  this component only ever invokes the callback. */
@@ -379,7 +386,12 @@ export function RelatedListSection({
   // are really just "the first N in the server's own order" (fw#2722 review).
   // `nextCursor` is exactly how the paged envelope marks that: non-null means
   // more rows exist server-side beyond what was fetched.
-  const truncated = rowsQuery.data !== null && rowsQuery.data.nextCursor !== null;
+  // A handler that omits `nextCursor` (or reports a `total` the fetched rows
+  // already cover) has no further rows — only a real cursor marks truncation.
+  const truncated =
+    rowsQuery.data !== null &&
+    typeof rowsQuery.data.nextCursor === "string" &&
+    (rowsQuery.data.total === undefined || rowsQuery.data.total > rowsQuery.data.rows.length);
 
   const content =
     rowsQuery.loading && rowsQuery.data === null ? (
@@ -404,31 +416,39 @@ export function RelatedListSection({
             {emptyStateActionError}
           </Banner>
         )}
-        <RenderList
-          screen={listScreen}
-          entity={entity}
-          rows={sortedRows}
-          featureName={featureName}
-          translate={effectiveTranslate}
-          sort={sort}
-          onSortChange={setSort}
-          {...(section.searchable === true && {
-            searchable: true,
-            searchValue: search,
-            onSearchChange: setSearch,
-          })}
-          {...(filterFacets.length > 0 && {
-            filterFacets,
-            filterValues: filters,
-            onFilterChange,
-            onFilterReset,
-          })}
-          {...(onRowClick !== undefined && { onRowClick })}
-          {...(rowActions !== undefined && { rowActions })}
-          {...(toolbarActionButtons !== undefined && { toolbarActions: toolbarActionButtons })}
-          {...(emptyStateContent !== undefined && { emptyState: emptyStateContent })}
-          {...(hideTitle === true && { scrollBody: true, screenPadding: false, chromeless: true })}
-        />
+        <PageHeaderSlotAvailableProvider value={false}>
+          <RenderList
+            screen={listScreen}
+            entity={entity}
+            rows={sortedRows}
+            featureName={featureName}
+            translate={effectiveTranslate}
+            {...(section.description !== undefined && { description: section.description })}
+            {...(section.itemNoun !== undefined && { itemNounKey: section.itemNoun })}
+            sort={sort}
+            onSortChange={setSort}
+            {...(section.searchable === true && {
+              searchable: true,
+              searchValue: search,
+              onSearchChange: setSearch,
+            })}
+            {...(filterFacets.length > 0 && {
+              filterFacets,
+              filterValues: filters,
+              onFilterChange,
+              onFilterReset,
+            })}
+            {...(onRowClick !== undefined && { onRowClick })}
+            {...(rowActions !== undefined && { rowActions })}
+            {...(toolbarActionButtons !== undefined && { toolbarActions: toolbarActionButtons })}
+            {...(emptyStateContent !== undefined && { emptyState: emptyStateContent })}
+            {...(hideTitle === true && {
+              scrollBody: true,
+              screenPadding: false,
+              chromeless: true,
+            })}
+          />
+        </PageHeaderSlotAvailableProvider>
       </>
     );
 
@@ -447,7 +467,11 @@ export function RelatedListSection({
     return (
       <>
         {bridges}
-        {FillContainer !== undefined ? <FillContainer>{content}</FillContainer> : content}
+        {FillContainer !== undefined ? (
+          <FillContainer {...(grow === true && { grow: true })}>{content}</FillContainer>
+        ) : (
+          content
+        )}
       </>
     );
   }

package/src/components/render-edit-action-button.tsx

@@ -45,6 +45,7 @@ export function RenderEditActionConfirmDialog({
 export function RenderEditActionButton({
   action,
   iconOnly = false,
+  hideIcon = false,
   Button,
   Dialog,
   onError,
@@ -53,6 +54,8 @@ export function RenderEditActionButton({
   /** Group-level collapse (see `shouldRenderActionsIconOnly`) — only takes
    *  effect when this action actually resolved an icon. */
   readonly iconOnly?: boolean;
+  /** Record-header actions are text-only; the icon still shows when collapsed to icon-only. */
+  readonly hideIcon?: boolean;
   readonly Button: ReturnType<typeof usePrimitives>["Button"];
   readonly Dialog: ReturnType<typeof usePrimitives>["Dialog"];
   readonly onError: (text: string | null) => void;
@@ -81,7 +84,7 @@ export function RenderEditActionButton({
         type="button"
         variant={variant}
         loading={busy}
-        {...(action.icon !== undefined && { icon: action.icon })}
+        {...(action.icon !== undefined && (!hideIcon || showIconOnly) && { icon: action.icon })}
         {...(showIconOnly && { size: "icon" as const, ariaLabel: action.label })}
         onClick={() => {
           if (needsActionConfirm(action)) {

package/src/components/render-edit-types.ts

@@ -53,6 +53,9 @@ export type RenderEditProps<TValues extends FormValues, TCtx = unknown> = {
   readonly onDelete?: () => Promise<void> | void;
   readonly onCancel?: () => void;
   readonly onReload?: () => void;
+  /** Fires when the form gains or loses unsaved input (field changes or a
+   *  dirty extension section). Lets a host such as a drawer guard closing. */
+  readonly onDirtyChange?: (dirty: boolean) => void;
   /** Copy-link action (issue #912) — only set in update mode (create mode
    *  has no entity id yet, hence no permalink). The callback is already fully
    *  bound (URL building + clipboard happen outside, in
@@ -83,6 +86,8 @@ export type RenderEditProps<TValues extends FormValues, TCtx = unknown> = {
   readonly submitLabel?: string;
   /** Visual style of the submit button (actionForm `submitStyle`). Default "primary". */
   readonly submitVariant?: "primary" | "danger";
+  /** Context box above the drawer form (title + optional subtitle, already resolved). */
+  readonly summary?: { readonly title: string; readonly subtitle?: string };
   /** Per-field extra content inline after the label (e.g.
    *  ConfigSourceBadge). Called with the field name, returns a ReactNode or
    *  undefined. */
@@ -161,6 +166,11 @@ export type RenderEditProps<TValues extends FormValues, TCtx = unknown> = {
    *  redundant title above its content. Omitting this prop keeps unchanged
    *  behavior. */
   readonly hideSectionTitles?: boolean;
+  /** Screen body fills the shell height: the form gets `fillHeight` and
+   *  `stickyActions` (sections scroll, footer pinned). Set by KumikoScreen for
+   *  screens with `fillHeight !== false`; dialogs and other embedded hosts
+   *  omit it and keep document-flow height. */
+  readonly fillScreenHeight?: boolean;
   /** Extra content rendered above the card, sharing its left padding and
    *  width — for a host with its own header region (title/metrics/tabs)
    *  that would otherwise render as unpadded siblings before RenderEdit.