@cosmicdrift/kumiko-renderer 0.233.0 → 0.234.0

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

@@ -0,0 +1,146 @@
+// ToolbarActionView collapses a group of >2 icon-carrying toolbar actions to
+// icon-only buttons (`shouldRenderActionsIconOnly`). The button then has no
+// accessible name from its children, so the label has to move to `ariaLabel`
+// and must NOT stay in the children — otherwise the text renders inside a
+// button sized for an icon.
+
+import { describe, expect, test } from "bun:test";
+import type {
+  EntityDefinition,
+  EntityListScreenDefinition,
+} from "@cosmicdrift/kumiko-framework/ui-types";
+import { render, screen as rtlScreen } from "@testing-library/react";
+import type { ComponentType, ReactNode } from "react";
+import { createStaticLocaleResolver, LocaleProvider } from "../../i18n";
+import { kumikoDefaultTranslations } from "../../i18n-defaults";
+import {
+  type ButtonProps,
+  type CorePrimitives,
+  type DataTableProps,
+  PrimitivesProvider,
+} from "../../primitives";
+import { RenderList, type ToolbarActionButton } from "../render-list";
+
+const TestButton: ComponentType<ButtonProps> = ({ children, onClick, testId, ariaLabel, size }) => (
+  <button
+    type="button"
+    data-testid={testId}
+    data-size={size ?? "md"}
+    aria-label={ariaLabel}
+    onClick={() => {
+      void onClick?.();
+    }}
+  >
+    {children}
+  </button>
+);
+
+const toolbarOnlyDataTable: ComponentType<DataTableProps> = ({ toolbarEnd }) => (
+  <div>{toolbarEnd}</div>
+);
+
+const noop = (): ReactNode => null;
+const passChildren = ({ children }: { readonly children?: ReactNode }): ReactNode => children;
+
+const testPrimitives: CorePrimitives = {
+  Button: TestButton,
+  Banner: passChildren,
+  Field: passChildren,
+  Input: noop,
+  DataTable: toolbarOnlyDataTable,
+  Form: passChildren,
+  Section: passChildren,
+  Card: passChildren,
+  Grid: passChildren,
+  GridCell: passChildren,
+  Text: passChildren,
+  Heading: noop,
+  Dialog: noop,
+  Modal: noop,
+  Lightbox: noop,
+  ConfigSourceBadge: noop,
+  ConfigCascadeView: noop,
+  Link: noop,
+};
+
+const entity: EntityDefinition = {
+  fields: {
+    name: { type: "text", maxLength: 50, required: false, searchable: false, sortable: false },
+  },
+};
+
+const listScreen: EntityListScreenDefinition = {
+  id: "widget-list",
+  type: "entityList",
+  entity: "widget",
+  columns: ["name"],
+};
+
+function toolbarAction(id: string, label: string, withIcon: boolean): ToolbarActionButton {
+  return {
+    id,
+    label,
+    onTrigger: () => {},
+    ...(withIcon && { icon: "archive" as const }),
+  };
+}
+
+function renderToolbar(actions: readonly ToolbarActionButton[]): void {
+  render(
+    <LocaleProvider
+      resolver={createStaticLocaleResolver({ locale: "en" })}
+      fallbackBundles={[kumikoDefaultTranslations]}
+    >
+      <PrimitivesProvider value={testPrimitives}>
+        <RenderList
+          screen={listScreen}
+          entity={entity}
+          rows={[]}
+          featureName="toolbar-fixture"
+          toolbarActions={actions}
+        />
+      </PrimitivesProvider>
+    </LocaleProvider>,
+  );
+}
+
+describe("RenderList toolbar actions collapse to icon-only", () => {
+  test("three icon actions render buttons with no visible text but an aria-label", () => {
+    renderToolbar([
+      toolbarAction("sync", "Sync", true),
+      toolbarAction("export", "Export", true),
+      toolbarAction("archive", "Archive", true),
+    ]);
+
+    for (const [id, label] of [
+      ["sync", "Sync"],
+      ["export", "Export"],
+      ["archive", "Archive"],
+    ] as const) {
+      const button = rtlScreen.getByTestId(`render-list-toolbar-action-${id}`);
+      expect(button.getAttribute("data-size")).toBe("icon");
+      expect(button.getAttribute("aria-label")).toBe(label);
+      expect(button.textContent).toBe("");
+    }
+  });
+
+  test("two actions stay on text buttons carrying the label as children", () => {
+    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.textContent).toBe("Sync");
+  });
+
+  test("an icon-less member keeps the whole group on text buttons", () => {
+    renderToolbar([
+      toolbarAction("sync", "Sync", true),
+      toolbarAction("export", "Export", true),
+      toolbarAction("archive", "Archive", false),
+    ]);
+
+    const button = rtlScreen.getByTestId("render-list-toolbar-action-sync");
+    expect(button.getAttribute("data-size")).toBe("md");
+    expect(button.textContent).toBe("Sync");
+  });
+});

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

@@ -93,26 +93,36 @@ export function RelatedListSection({
         }
       : undefined;
 
+  const content =
+    rowsQuery.loading && rowsQuery.data === null ? (
+      <Banner padded variant="loading" testId="related-list-loading">
+        Loading…
+      </Banner>
+    ) : rowsQuery.error ? (
+      <Banner padded variant="error" testId="related-list-error">
+        {dispatcherErrorText(rowsQuery.error, effectiveTranslate)}
+      </Banner>
+    ) : (
+      <RenderList
+        screen={listScreen}
+        entity={entity}
+        rows={rowsQuery.data?.rows ?? []}
+        featureName={featureName}
+        translate={effectiveTranslate}
+        {...(onRowClick !== undefined && { onRowClick })}
+      />
+    );
+
+  // hideTitle (tabs mode) → this section carries no header content of its
+  // own, and RenderList's DataTable already draws its own card frame — a
+  // Section wrapper here would only add a second, nested card (fw record-
+  // screen-type polish). Stacked (non-tabs) sections keep their Section
+  // card since they render a visible title.
+  if (hideTitle) return content;
+
   return (
-    <Section title={hideTitle ? undefined : section.title} testId={`related-list-${section.title}`}>
-      {rowsQuery.loading && rowsQuery.data === null ? (
-        <Banner padded variant="loading" testId="related-list-loading">
-          Loading…
-        </Banner>
-      ) : rowsQuery.error ? (
-        <Banner padded variant="error" testId="related-list-error">
-          {dispatcherErrorText(rowsQuery.error, effectiveTranslate)}
-        </Banner>
-      ) : (
-        <RenderList
-          screen={listScreen}
-          entity={entity}
-          rows={rowsQuery.data?.rows ?? []}
-          featureName={featureName}
-          translate={effectiveTranslate}
-          {...(onRowClick !== undefined && { onRowClick })}
-        />
-      )}
+    <Section title={section.title} testId={`related-list-${section.title}`}>
+      {content}
     </Section>
   );
 }

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

@@ -9,11 +9,15 @@ import type { RenderEditAction } from "./render-edit-types";
 // to hook into like the built-in onDelete/onSubmit paths have).
 export function RenderEditActionButton({
   action,
+  iconOnly = false,
   Button,
   Dialog,
   onError,
 }: {
   readonly action: RenderEditAction;
+  /** Group-level collapse (see `shouldRenderActionsIconOnly`) — only takes
+   *  effect when this action actually resolved an icon. */
+  readonly iconOnly?: boolean;
   readonly Button: ReturnType<typeof usePrimitives>["Button"];
   readonly Dialog: ReturnType<typeof usePrimitives>["Dialog"];
   readonly onError: (text: string | null) => void;
@@ -37,6 +41,7 @@ export function RenderEditActionButton({
   // Same rule as RowActionWriteHandler: "danger" forces a confirm even
   // without an explicit confirm key.
   const needsConfirm = action.confirm !== undefined || action.style === "danger";
+  const showIconOnly = iconOnly && action.icon !== undefined;
 
   return (
     <>
@@ -44,6 +49,8 @@ export function RenderEditActionButton({
         type="button"
         variant={variant}
         loading={busy}
+        {...(action.icon !== undefined && { icon: action.icon })}
+        {...(showIconOnly && { size: "icon" as const, ariaLabel: action.label })}
         onClick={() => {
           if (needsConfirm) {
             setConfirmOpen(true);
@@ -53,7 +60,7 @@ export function RenderEditActionButton({
         }}
         testId={`render-edit-action-${action.id}`}
       >
-        {action.label}
+        {showIconOnly ? null : action.label}
       </Button>
       <Dialog
         open={confirmOpen}

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

@@ -1,6 +1,7 @@
 import type {
   EntityDefinition,
   EntityEditScreenDefinition,
+  IconKey,
 } from "@cosmicdrift/kumiko-framework/ui-types";
 import type {
   FormSnapshot,
@@ -156,6 +157,10 @@ export type RenderEditAction = {
   readonly style?: "primary" | "secondary" | "danger";
   readonly confirm?: string;
   readonly confirmLabel?: string;
+  /** Resolved icon (author `RowAction.icon` or the id-derived default) —
+   *  drives both the icon-left-of-text render and the icon-only collapse
+   *  rule (see `shouldRenderActionsIconOnly`). */
+  readonly icon?: IconKey;
 };
 
 export type RenderEditChangeState<TValues extends FormValues> = {

package/src/components/render-edit.tsx

@@ -36,7 +36,7 @@ import { useDraftStorage } from "../context/draft-storage-context";
 import { formatWhen } from "../format-when";
 import { useForm } from "../hooks/use-form";
 import { useTranslation } from "../i18n";
-import { usePrimitives } from "../primitives";
+import { shouldRenderActionsIconOnly, usePrimitives } from "../primitives";
 import { RelatedListSection } from "./related-list-section";
 import {
   filterEditSections,
@@ -922,6 +922,10 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
     onCopyLink !== undefined ||
     (actions !== undefined && actions.length > 0) ||
     onCancel !== undefined;
+  // Teil-C collapse rule: driven by the custom `actions` group only — a
+  // resolved true also folds the Copy-Link button (same visual group in the
+  // footer), but never Delete/Cancel, which keep their text regardless.
+  const iconOnlyMidActions = actions !== undefined && shouldRenderActionsIconOnly(actions);
   const secondaryFormActions = (
     <>
       {onDelete !== undefined && (
@@ -939,21 +943,30 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
       {onCopyLink !== undefined && (
         <Button
           type="button"
-          variant="link"
+          variant={iconOnlyMidActions ? "secondary" : "link"}
           icon={linkCopied ? "check" : "link"}
           testId="render-edit-copy-link"
+          {...(iconOnlyMidActions && {
+            size: "icon" as const,
+            ariaLabel: translate(
+              linkCopied ? "kumiko.actions.copyLinkCopied" : "kumiko.actions.copyLink",
+            ),
+          })}
           onClick={async () => {
             await onCopyLink();
             setLinkCopied(true);
           }}
         >
-          {translate(linkCopied ? "kumiko.actions.copyLinkCopied" : "kumiko.actions.copyLink")}
+          {iconOnlyMidActions
+            ? null
+            : translate(linkCopied ? "kumiko.actions.copyLinkCopied" : "kumiko.actions.copyLink")}
         </Button>
       )}
       {actions?.map((action) => (
         <RenderEditActionButton
           key={action.id}
           action={action}
+          iconOnly={iconOnlyMidActions}
           Button={Button}
           Dialog={Dialog}
           onError={setActionError}
@@ -972,6 +985,14 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
       )}
     </>
   );
+  // Mirrors every branch inside formActions below — without this guard
+  // DefaultForm renders an empty footer strip (border + padding, no content)
+  // on read-only detail screens, since `actions` would otherwise always be
+  // a defined (if empty) fragment.
+  const hasFormActions =
+    (isWizard && currentStep > 0) ||
+    (isWizard && !isLastWizardStep) ||
+    ((isFormEditable || hasExtensionRegistrations) && (!isWizard || isLastWizardStep));
   const formActions = (
     <>
       {isWizard && currentStep > 0 && (
@@ -1039,7 +1060,7 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
         {...(hideSectionTitles !== true && { title: formTitle })}
         {...(hideSectionTitles !== true &&
           formSubtitle !== undefined && { subtitle: formSubtitle })}
-        {...(hideActions !== true && { actions: formActions })}
+        {...(hideActions !== true && hasFormActions && { actions: formActions })}
         {...(hideActions !== true &&
           hasSecondaryFormActions && { secondaryActions: secondaryFormActions })}
         testId="render-edit-form"
@@ -1206,6 +1227,7 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
               key={sectionKey}
               {...(sectionTitle !== undefined && { title: sectionTitle })}
               {...(section.description !== undefined && { subtitle: section.description })}
+              {...(section.icon !== undefined && { icon: section.icon })}
               testId={`section-${sectionKey}`}
             >
               <Grid columns={section.columns}>

package/src/components/render-field.tsx

@@ -1,5 +1,6 @@
 import {
   type EntityEditScreenDefinition,
+  type FieldIconKey,
   type FieldRenderer,
   isFormatSpec,
 } from "@cosmicdrift/kumiko-framework/ui-types";
@@ -146,7 +147,6 @@ export function RenderField({
       {...(issues !== undefined && { issues })}
       {...(labelAppendix !== undefined && { labelAppendix })}
       {...(fieldAppendix !== undefined && { fieldAppendix })}
-      {...(field.type === "boolean" && { layout: "inline" as const })}
       testId={`field-${field.field}`}
     >
       {control}
@@ -435,6 +435,44 @@ function isComplexFieldType(type: string): boolean {
   return type === "embedded" || type === "jsonb" || type === "files" || type === "images";
 }
 
+// Mirrors ACTION_ICON_BY_ID (kumiko-screen.tsx) for fields: only names with
+// an unambiguous matching FieldIconKey are listed here, everything else
+// stays iconless rather than guessing.
+const FIELD_ICON_BY_NAME: Readonly<Partial<Record<string, FieldIconKey>>> = {
+  email: "mail",
+  phone: "phone",
+  tel: "phone",
+  mobile: "phone",
+  url: "link",
+  website: "link",
+  link: "link",
+  password: "lock",
+  search: "search",
+  city: "map-pin",
+  address: "map-pin",
+  street: "map-pin",
+  user: "user",
+  owner: "user",
+  assignee: "user",
+};
+
+function kebabLastSegment(value: string): string {
+  const kebab = toKebab(value);
+  const lastDash = kebab.lastIndexOf("-");
+  return lastDash === -1 ? kebab : kebab.slice(lastDash + 1);
+}
+
+// Derives a prefix icon when the field declares none: field.icon wins, then
+// the field name. Deliberately no type-based fallback — a hash in front of a
+// number field restates what the field already shows and reads as noise.
+function resolveFieldIcon(field: EditFieldViewModel): FieldIconKey | undefined {
+  if (field.icon !== undefined) return field.icon;
+  const byName =
+    FIELD_ICON_BY_NAME[field.field.toLowerCase()] ??
+    FIELD_ICON_BY_NAME[kebabLastSegment(field.field)];
+  return byName;
+}
+
 // Dispatches field.type → Input-kind. Select threads options through
 // from the EditFieldViewModel (computeEditViewModel pulls them from
 // SelectFieldDef.options). Structural types without a widget (embedded,
@@ -478,6 +516,7 @@ function renderInput({
     // beyond what "number" already does (#1925).
     case "number":
     case "bigInt": {
+      const icon = resolveFieldIcon(field);
       const unit = resolveNumberUnit(field.unit, row);
       return (
         <Input
@@ -485,15 +524,16 @@ function renderInput({
           {...common}
           value={numberValue(field.value)}
           onChange={(v) => onChange(v)}
-          {...(field.icon !== undefined && { icon: field.icon })}
+          {...(icon !== undefined && { icon })}
           {...(unit !== undefined && { unit })}
         />
       );
     }
-    case "decimal":
+    case "decimal": {
       // step="any" disables the native stepMismatch constraint — without it
       // <input type="number"> defaults to step=1 and blocks form submit on
       // any fractional value via silent browser-native validation.
+      const icon = resolveFieldIcon(field);
       return (
         <Input
           kind="number"
@@ -501,9 +541,10 @@ function renderInput({
           value={numberValue(field.value)}
           onChange={(v) => onChange(v)}
           step="any"
-          {...(field.icon !== undefined && { icon: field.icon })}
+          {...(icon !== undefined && { icon })}
         />
       );
+    }
     case "tz":
       return (
         <Input
@@ -683,13 +724,14 @@ function renderInput({
           />
         );
       }
+      const icon = resolveFieldIcon(field);
       return (
         <Input
           kind="text"
           {...common}
           value={stringValue(field.value)}
           onChange={(v) => onChange(v)}
-          {...(field.icon !== undefined && { icon: field.icon })}
+          {...(icon !== undefined && { icon })}
         />
       );
     }

package/src/components/render-list.tsx

@@ -2,6 +2,7 @@ import type { EagerloadedRow } from "@cosmicdrift/kumiko-framework/db";
 import type {
   EntityDefinition,
   EntityListScreenDefinition,
+  IconKey,
 } from "@cosmicdrift/kumiko-framework/ui-types";
 import type {
   ListColumnViewModel,
@@ -16,7 +17,13 @@ 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 { type DataTableFacet, type DataTableRowAction, usePrimitives } from "../primitives";
+import {
+  type DataTableFacet,
+  type DataTableRowAction,
+  type DataTableRowActionMode,
+  shouldRenderActionsIconOnly,
+  usePrimitives,
+} from "../primitives";
 
 // RenderList — präsentationaler View für entityList-Screens.
 //
@@ -85,6 +92,10 @@ export type RenderListProps = {
    *  EntityListScreenDefinition.rowActions: handler-QN → dispatcher-Call,
    *  i18n-Keys → translated Strings). */
   readonly rowActions?: readonly DataTableRowAction[];
+  /** How the row-action column renders (see `DataTableProps.rowActionMode`).
+   *  KumikoScreen derives it from the actions themselves; without it the
+   *  DataTable falls back to its adaptive default. */
+  readonly rowActionMode?: DataTableRowActionMode;
   /** Toolbar-Aktionen im List-Header — Resolved-Form (KumikoScreen baut
    *  das aus EntityListScreenDefinition.toolbarActions: navigate-target
    *  → useNav, handler-QN → dispatcher-Call). RenderList rendert die
@@ -112,6 +123,9 @@ export type ToolbarActionButton = {
   readonly confirm?: string;
   readonly confirmLabel?: string;
   readonly onTrigger: () => Promise<void> | void;
+  /** Id-derived default icon (ACTION_ICON_BY_ID in kumiko-screen.tsx) —
+   *  ToolbarAction has no author-declared icon field, unlike RowAction. */
+  readonly icon?: IconKey;
 };
 
 const SEARCH_DEBOUNCE_MS = 300;
@@ -138,6 +152,7 @@ export function RenderList(props: RenderListProps): ReactNode {
     loadingMore,
     hasMore,
     rowActions,
+    rowActionMode,
     toolbarActions,
     filterFacets,
     filterValues,
@@ -274,6 +289,7 @@ export function RenderList(props: RenderListProps): ReactNode {
   // "+ Neu" zuletzt weil das die häufigste/auffälligste CTA ist.
   const hasToolbarActions = toolbarActions !== undefined && toolbarActions.length > 0;
   const hasHeaderSlot = screen.slots?.header !== undefined;
+  const toolbarIconOnly = hasToolbarActions && shouldRenderActionsIconOnly(toolbarActions);
   const toolbarEnd =
     hasHeaderSlot || hasToolbarActions || onCreate !== undefined ? (
       <>
@@ -283,6 +299,7 @@ export function RenderList(props: RenderListProps): ReactNode {
             <ToolbarActionView
               key={a.id}
               action={a}
+              iconOnly={toolbarIconOnly}
               Button={Button}
               Dialog={Dialog}
               Banner={Banner}
@@ -350,6 +367,7 @@ export function RenderList(props: RenderListProps): ReactNode {
         {...(loadingMore !== undefined && { loadingMore })}
         {...(hasMore !== undefined && { hasMore })}
         {...(rowActions !== undefined && { rowActions })}
+        {...(rowActionMode !== undefined && { rowActionMode })}
         {...(filterFacets !== undefined && { filterFacets })}
         {...(filterValues !== undefined && { filterValues })}
         {...(onFilterChange !== undefined && { onFilterChange })}
@@ -427,11 +445,15 @@ function ReferenceLookupBridge({
 // öffnet sich vor dem Trigger wenn confirm/danger gesetzt.
 function ToolbarActionView({
   action,
+  iconOnly = false,
   Button,
   Dialog,
   Banner,
 }: {
   readonly action: ToolbarActionButton;
+  /** Group-level collapse (see `shouldRenderActionsIconOnly`) — only takes
+   *  effect when this action actually resolved an icon. */
+  readonly iconOnly?: boolean;
   readonly Button: ReturnType<typeof usePrimitives>["Button"];
   readonly Dialog: ReturnType<typeof usePrimitives>["Dialog"];
   readonly Banner: ReturnType<typeof usePrimitives>["Banner"];
@@ -459,12 +481,15 @@ function ToolbarActionView({
 
   const variant: "primary" | "secondary" | "danger" = action.style ?? "secondary";
   const needsConfirm = action.confirm !== undefined || action.style === "danger";
+  const showIconOnly = iconOnly && action.icon !== undefined;
 
   return (
     <>
       <Button
         variant={variant}
         loading={busy}
+        {...(action.icon !== undefined && { icon: action.icon })}
+        {...(showIconOnly && { size: "icon" as const, ariaLabel: action.label })}
         onClick={() => {
           if (needsConfirm) {
             setConfirmOpen(true);
@@ -474,7 +499,7 @@ function ToolbarActionView({
         }}
         testId={`render-list-toolbar-action-${action.id}`}
       >
-        {action.label}
+        {showIconOnly ? null : action.label}
       </Button>
       <Dialog
         open={confirmOpen}

package/src/index.ts

@@ -206,7 +206,12 @@ export type {
   TextProps,
   WizardStepGroupProps,
 } from "./primitives";
-export { PrimitivesProvider, usePrimitives } from "./primitives";
+export {
+  PrimitivesProvider,
+  shouldRenderActionsIconOnly,
+  statusToneForValue,
+  usePrimitives,
+} from "./primitives";
 export { sortByAccessor } from "./sort-by-accessor";
 export type { LiveEvent, LiveEventSubscriber, LiveEventsProviderProps } from "./sse/live-events";
 export { LiveEventsProvider, useLiveEvents } from "./sse/live-events";

package/src/primitives.tsx

@@ -35,7 +35,12 @@ import type {
   ConfigScope,
   ConfigValueSource,
 } from "@cosmicdrift/kumiko-framework/engine";
-import type { FieldIconKey, FormWidth, NavIconKey } from "@cosmicdrift/kumiko-framework/ui-types";
+import type {
+  FieldIconKey,
+  FormWidth,
+  IconKey,
+  NavIconKey,
+} from "@cosmicdrift/kumiko-framework/ui-types";
 import type {
   FieldIssue,
   ListColumnViewModel,
@@ -492,8 +497,22 @@ export type DataTableRowAction = {
   readonly onTrigger: (row: ListRowViewModel) => Promise<void> | void;
   /** Conditional Visibility pro Row (z.B. "Start" nur wenn status==="scheduled"). */
   readonly isVisible?: (row: ListRowViewModel) => boolean;
+  /** Resolved icon (author `RowAction.icon` or the id-derived default) —
+   *  drives both the icon-left-of-text render and the icon-only collapse
+   *  rule (see `shouldRenderActionsIconOnly`). */
+  readonly icon?: IconKey;
 };
 
+/** Teil-C action-icon collapse rule: a group of more than two actions where
+ *  every member carries an icon renders icon-only instead of wall-to-wall
+ *  text buttons; any icon-less member keeps the whole group on text so it
+ *  doesn't fall apart visually mid-group. */
+export function shouldRenderActionsIconOnly(
+  actions: readonly { readonly icon?: IconKey }[],
+): boolean {
+  return actions.length > 2 && actions.every((a) => a.icon !== undefined);
+}
+
 // Ein Faceted-Filter-Slot in der Toolbar: ein Outline-Dropdown-Button
 // (wie shadcns "Columns"-Toggle) mit Multi-Select-Checkboxen. KumikoScreen
 // baut das aus den filterable select/boolean-Feldern des Entity.
@@ -747,6 +766,10 @@ export type SectionProps = {
    *  Default "default" (normal card border). */
   readonly variant?: "default" | "destructive";
   readonly testId?: string;
+  /** Rendered left of the title, `text-muted-foreground`, same optical
+   *  size as the title. No effect without a `title` — an icon alone would
+   *  have nothing to sit next to. */
+  readonly icon?: IconKey;
 };
 
 /** Columns-basiertes Layout. Web: CSS grid, Native: Flex-Wrap mit
@@ -988,6 +1011,45 @@ export type StatusBadgeProps = {
   readonly testId?: string;
 };
 
+// Status value -> StatusTone heuristic, shared by every surface that shows a
+// raw status value without a tone of its own (projectionDetail header badge,
+// list cells). Covers the common status vocabularies; unknown values stay
+// undefined so the caller keeps its own neutral default.
+const STATUS_TONE_BY_VALUE: Readonly<Record<string, StatusTone>> = {
+  ok: "ok",
+  active: "ok",
+  done: "ok",
+  complete: "ok",
+  completed: "ok",
+  paid: "ok",
+  approved: "ok",
+  published: "ok",
+  success: "ok",
+  pending: "warn",
+  processing: "warn",
+  review: "warn",
+  "in-review": "warn",
+  waiting: "warn",
+  open: "warn",
+  draft: "warn",
+  failed: "bad",
+  error: "bad",
+  overdue: "bad",
+  rejected: "bad",
+  blocked: "bad",
+  critical: "bad",
+};
+
+export function statusToneForValue(value: string): StatusTone | undefined {
+  const slug = value
+    .trim()
+    .toLowerCase()
+    .replace(/[\s_]+/g, "-");
+  // Own-key check: the value comes from row data, and a plain object lookup
+  // would hand back `Object.prototype.constructor` & friends as a "tone".
+  return Object.hasOwn(STATUS_TONE_BY_VALUE, slug) ? STATUS_TONE_BY_VALUE[slug] : undefined;
+}
+
 /** Compact label/value tile (record-detail metrics band). `testId` is the
  *  tile's own id — the impl derives `${testId}-label`/`${testId}-value` for
  *  the two rendered nodes, so a caller only ever needs to know the base id. */