@cosmicdrift/kumiko-types 0.413.1 → 0.415.0

package/dist/screen-dashboard.d.ts

@@ -1,3 +1,4 @@
+import type { SelectOptionTone } from "./fields.ts";
 import type { AccessRule, AgentScreenHints } from "./handlers.ts";
 import type { PlatformComponent, ScreenNavSugar, ScreenSlots } from "./screen.ts";
 import type { ListColumnSpec, RowAction } from "./screen-entity-list.ts";
@@ -56,7 +57,14 @@ export type DashboardPanelQueryOptions = {
 export type DashboardPanelGate = {
     readonly visibleWhen?: DashboardPanelVisibility;
 };
-export type DashboardPanelSpan = "half" | "full";
+/** Phone layout switch shared by every panel kind. */
+export type DashboardPanelNarrow = {
+    /** Leaves the panel out below the `sm` breakpoint (phone). Not valid on a stat-group child: hide the group. */
+    readonly hideOnNarrow?: true;
+    /** Position below `sm`, like CSS `order`: panels are laid out by ascending value, a panel without one counts as 0, equal values keep the declared order. Integer ≥ 0. Desktop keeps the declared order. */
+    readonly narrowOrder?: number;
+};
+export type DashboardPanelSpan = "half" | "full" | "third" | "two-thirds";
 export type DashboardPanelEmptyState = {
     readonly span?: DashboardPanelSpan;
     readonly emptyLabel?: string;
@@ -65,7 +73,7 @@ export type DashboardPanelEmptyState = {
 };
 export declare const DASHBOARD_STAT_TONES: readonly ["default", "positive", "ok", "warn", "negative"];
 export type DashboardStatTone = (typeof DASHBOARD_STAT_TONES)[number];
-export type DashboardStatPanel = DashboardPanelQueryOptions & DashboardPanelGate & {
+export type DashboardStatPanel = DashboardPanelQueryOptions & DashboardPanelGate & DashboardPanelNarrow & {
     readonly kind: "stat";
     /** Stable id: kebab-case, unique within the panel set. */
     readonly id: string;
@@ -73,6 +81,10 @@ export type DashboardStatPanel = DashboardPanelQueryOptions & DashboardPanelGate
     readonly label: string;
     readonly query: string;
     readonly valueField: string;
+    /** Field of the query answer holding the label text, e.g. "Contracts ending by 31.01.2027"; it replaces the static `label` while it holds a non-empty string. The static `label` stays the fallback and the loading/error title. */
+    readonly labelField?: string;
+    /** i18n key shown instead of the label in the one-line phone strip of a titled stat-group ("2 requests"). Only used for stats inside a stat-group. */
+    readonly narrowLabel?: string;
     readonly subField?: string;
     readonly toneField?: string;
     /** Formats a numeric value as currency (minor units) or, with `relativeTime`, as
@@ -110,6 +122,8 @@ export type DashboardStatPanel = DashboardPanelQueryOptions & DashboardPanelGate
     readonly navigate?: {
         readonly screen: string;
         readonly namedFilter?: string;
+        /** Search params for the target list, e.g. { tab: "failed" }; merged with the namedFilter param. */
+        readonly params?: Readonly<Record<string, string>>;
     };
 };
 export type DashboardChartKind = "timeseries" | "stacked-bars" | "segment-bars" | "stacked-area";
@@ -134,7 +148,7 @@ export type DashboardChartRanges = {
     readonly options: readonly DashboardChartRangeOption[];
     readonly default: string;
 };
-export type DashboardChartPanel = DashboardPanelQueryOptions & DashboardPanelEmptyState & DashboardPanelGate & {
+export type DashboardChartPanel = DashboardPanelQueryOptions & DashboardPanelEmptyState & DashboardPanelGate & DashboardPanelNarrow & {
     readonly kind: "chart";
     readonly id: string;
     readonly label: string;
@@ -175,77 +189,181 @@ export type DashboardChartPanel = DashboardPanelQueryOptions & DashboardPanelEmp
     /** Only for chart "stacked-area": true writes each marker label vertically next to its guide line on wide panels; narrow panels keep the pins. Default false. */
     readonly markerLabels?: boolean;
 };
-export type DashboardListPanel = DashboardPanelQueryOptions & DashboardPanelEmptyState & DashboardPanelGate & {
+export type DashboardListPanel = DashboardPanelQueryOptions & DashboardPanelEmptyState & DashboardPanelGate & DashboardPanelNarrow & {
     readonly kind: "list";
     readonly id: string;
     readonly label: string;
     readonly query: string;
     readonly columns: readonly ListColumnSpec[];
+    /** Row field holding a SelectOptionTone; tints the row and is the default tone of `hint` columns. */
+    readonly rowToneField?: string;
+    /** How `rowToneField` marks a table row from `sm` up: "bar" (default) draws a stripe at the left edge, "dot" a small dot in front of the first cell. Cards below `sm` always get the stripe. */
+    readonly rowToneMarker?: DashboardListRowToneMarker;
+    /** Icon left of the one-line phone variant (`narrow.layout: "line"`); not drawn from `sm` up. Resolved like `DashboardStatGroupPanel.icon`. */
+    readonly icon?: PlatformComponent;
+    /** `false` drops the column header row; default true. */
+    readonly showHeader?: boolean;
+    /** i18n key, a line under `label`; with `showTotal` it stands before the count. */
+    readonly subtitle?: string;
+    /** Adds "n of m" to the subtitle from the rows shown and the query's `total`. An object sets the text: `text` is an i18n key with `{shown}` and `{total}` ("the {shown} most urgent of {total} items"), `narrowText` replaces it below `sm`. */
+    readonly showTotal?: true | DashboardListShowTotal;
+    /** Link under the table to the full list; with a known `total` above the rows shown, "k more" stands before it. */
+    readonly footerLink?: DashboardListFooterLink;
+    /** Phone layout below `sm`; the table stays from `sm` up. */
+    readonly narrow?: DashboardListNarrow;
+    /** Makes each table row a link to a screen; a small icon at the right edge marks it. The cards below `sm` get no extra icon. */
+    readonly rowLink?: DashboardListRowLink;
+};
+/** "bar": stripe at the left edge of the row. "dot": small tone dot in front of the first cell. */
+export type DashboardListRowToneMarker = "bar" | "dot";
+/** Row link of a list panel: one fixed target screen (`screen`) or, when the rows point to different places, the screen named by each row (`screenField`). */
+export type DashboardListRowLink = {
+    /** "arrow" (default) draws ↗ for a jump to another place, "chevron" draws › for opening the row. */
+    readonly icon?: "arrow" | "chevron";
+} & ({
+    /** Target screen, `feature:screen:name` or the short id in the same feature. */
+    readonly screen: string;
+    /** Row field holding the params object of the target (`entityId` opens that record, other keys become search params). */
+    readonly paramField?: string;
+    readonly screenField?: never;
+    readonly paramsField?: never;
+} | {
+    /** Row field holding the qualified screen name of the target; a row without one is no link. */
+    readonly screenField: string;
+    /** Row field holding the params object of the target, like `paramField`. */
+    readonly paramsField?: string;
+    readonly screen?: never;
+    readonly paramField?: never;
+});
+/** Texts of the "n of m" count in a list panel's subtitle; without `text` the default i18n text stands. */
+export type DashboardListShowTotal = {
+    /** i18n key, placeholders `{shown}` and `{total}`. */
+    readonly text?: string;
+    /** i18n key used instead of `text` below `sm`. */
+    readonly narrowText?: string;
+};
+/** "cards": one card per row (tone stripe; badge column and `hint.detailField` on top, the hint sentence bold, button column bottom right,
+ *  `showOnNarrowOnly` columns bottom left; the button column bottom right). "line": a single clickable line "<label> · <value of the first row> · k more" to `footerLink`, which it needs;
+ *  k is the total of the list (the query's `total`, else the rows loaded) minus one.
+ *  Default "cards". `limit` shows only the first n rows; subtitle count and footer follow it. */
+export type DashboardListNarrow = {
+    readonly limit?: number;
+    readonly layout?: "cards" | "line";
+    /** Query output field whose value of the first row stands behind the label in the "line" layout; it need not be a column of the panel. Default: the first text column. */
+    readonly field?: string;
+    /** i18n key replacing "k more" in the "line" layout; `{count}` is the total minus the first row. */
+    readonly moreText?: string;
+    /** Row field replacing the card title (the hint sentence) in the "cards" layout, e.g. a shorter sentence for the phone. Needs a hint column. */
+    readonly titleField?: string;
+};
+/** Link to a screen from a panel; `label` is an i18n key, `namedFilter` only for list screens. */
+export type DashboardListFooterLink = {
+    readonly label: string;
+    /** i18n key of the text before the link when more rows exist than shown; `{count}` is the rest. Default "k more". */
+    readonly moreText?: string;
+    /** i18n key used instead of `moreText` below `sm`. */
+    readonly narrowMoreText?: string;
+    /** Draw the link only below `sm`, where it is the target of the "line" layout; from `sm` up the panel shows no footer link. */
+    readonly narrowOnly?: boolean;
+    readonly screen: string;
+    readonly namedFilter?: string;
+    readonly params?: Readonly<Record<string, string>>;
+};
+/** Link at the right edge of a stat-group panel; `label` is an i18n key. */
+export type DashboardStatGroupLink = {
+    readonly label: string;
+    readonly screen: string;
+    readonly params?: Readonly<Record<string, string>>;
 };
-export type DashboardStatGroupPanel = DashboardPanelGate & {
+export type DashboardStatGroupLayout = "cards" | "strip";
+export type DashboardStatGroupPanel = DashboardPanelGate & DashboardPanelNarrow & {
     readonly kind: "stat-group";
     readonly id: string;
     readonly label?: string;
     /** i18n key, a line under `label`; the boot validator requires `label`. */
     readonly subtitle?: string;
     readonly span?: DashboardPanelSpan;
+    /** Default: "strip" without `label`, "cards" with. "strip" with a `label` puts label and subtitle
+     *  left, then one box per stat (number large, label bold, sub line small) and the link at the right edge; under sm it collapses to
+     *  one line "<title> · <n> <narrowLabel ?? label> · …" with a chevron, clickable to the `link`. */
+    readonly layout?: DashboardStatGroupLayout;
+    /** Icon left of the one-line phone strip (below `sm`); not drawn on wider screens. Resolved like `DashboardStatPanel.icon`. */
+    readonly icon?: PlatformComponent;
+    /** Link at the right edge of the panel (label + chevron). */
+    readonly link?: DashboardStatGroupLink;
+    /** Phone look of the one-line strip; needs a label and layout "strip". */
+    readonly narrow?: DashboardStatGroupNarrow;
+    /** Tiles per row from `md` up, only with `layout: "cards"`; one column below `sm`. Default: follows the number of tiles. */
+    readonly columns?: 2 | 3 | 4;
     readonly stats: readonly DashboardStatPanel[];
 };
-export type DashboardFeedPanel = DashboardPanelQueryOptions & DashboardPanelEmptyState & DashboardPanelGate & {
+export type DashboardStatGroupNarrow = {
+    /** Tints the one-line phone strip (background and border) in this tone, e.g. "accent" for a promo-blue inbox line. */
+    readonly tone?: SelectOptionTone;
+};
+export type DashboardFeedPanel = DashboardPanelQueryOptions & DashboardPanelEmptyState & DashboardPanelGate & DashboardPanelNarrow & {
     readonly kind: "feed";
     readonly id: string;
     readonly label: string;
     readonly query: string;
 };
 export type DashboardProgressTone = "default" | "danger";
-export type DashboardProgressListPanel = DashboardPanelQueryOptions & DashboardPanelEmptyState & DashboardPanelGate & {
+export type DashboardProgressListPanel = DashboardPanelQueryOptions & DashboardPanelEmptyState & DashboardPanelGate & DashboardPanelNarrow & {
     readonly kind: "progress-list";
     readonly id: string;
     readonly label: string;
     readonly query: string;
 };
-export type DashboardCustomPanel = {
+export type DashboardCustomPanel = DashboardPanelNarrow & {
     readonly kind: "custom";
     readonly id: string;
     readonly component: PlatformComponent;
+    /** Grid width like the other panels; default is the full row. */
+    readonly span?: DashboardPanelSpan;
     /** Static author values laid over the screen's filterParams, like
      *  `DashboardPanelQueryOptions.params`; the panel wins on a name clash. */
     readonly params?: Readonly<Record<string, unknown>>;
 };
 export type DashboardTextBlock = {
     readonly kind: "heading";
-    readonly text: string;
+    readonly text: DashboardText;
 } | {
     readonly kind: "paragraph";
-    readonly text: string;
-    /** Default "muted", like body copy inside panels. */
-    readonly emphasis?: "muted" | "strong";
+    readonly text: DashboardText;
+    /** Default "muted", like body copy inside panels. "lead" is the larger serif opening sentence of a briefing. */
+    readonly emphasis?: "muted" | "strong" | "lead";
 } | {
     readonly kind: "list";
-    readonly items: readonly string[];
+    readonly items: readonly DashboardText[];
 } | {
     readonly kind: "code";
     readonly code: string;
 } | {
     readonly kind: "hint";
-    readonly text: string;
+    readonly text: DashboardText;
 } | {
     readonly kind: "link";
-    /** Link label (i18n key). */
-    readonly text: string;
+    /** Link label (i18n key or DashboardI18nText). */
+    readonly text: DashboardText;
     /** Same-feature short id or cross-feature QN `<feature>:screen:<id>`. */
     readonly screen: string;
     /** Show the link only to users holding one of these roles. Display
      *  gate only: the target screen's own `access` stays the enforcement. */
     readonly roles?: readonly string[];
 };
-export type DashboardTextPanel = DashboardPanelGate & {
+export type DashboardTextPanel = DashboardPanelGate & DashboardPanelQueryOptions & DashboardPanelNarrow & {
     readonly kind: "text";
     readonly id: string;
     /** Panel title (i18n key). */
     readonly label?: string;
     readonly span?: DashboardPanelSpan;
-    readonly blocks: readonly DashboardTextBlock[];
+    /** Query answering `{ blocks: DashboardTextBlock[] }`; its blocks replace the static ones.
+     *  Static blocks show while it loads, on error and when it answers empty. It may add
+     *  `narrowBlocks`, which the renderer shows below `sm` instead of `blocks`. */
+    readonly query?: string;
+    readonly blocks?: readonly DashboardTextBlock[];
+    /** Shown instead of `blocks` below `sm`; a query answering `{ blocks, narrowBlocks }` replaces both. Needs `blocks`. */
+    readonly narrowBlocks?: readonly DashboardTextBlock[];
 };
 export type DashboardPanelVisibility = {
     readonly query: string;
@@ -257,7 +375,7 @@ export type ScreenVisibility = DashboardPanelVisibility & {
      *  the gate query runs with an empty payload. */
     readonly idParam?: string;
 };
-export type DashboardScreenPanel = {
+export type DashboardScreenPanel = DashboardPanelNarrow & {
     readonly kind: "screen";
     readonly id: string;
     /** Same-feature short id or cross-feature QN `<feature>:screen:<id>`. */
@@ -355,9 +473,8 @@ export type DashboardScreenDefinition = {
     readonly timeRange?: DashboardTimeRangeDefinition;
     /** Marks the screen as spanning more than the caller's own scope. */
     readonly scope?: DashboardScopeDefinition;
-    /** Show the "Updated at" timestamp in the toolbar. Default true; turn off for
-     *  dashboards that host forms rather than live metrics, where a load time
-     *  next to the form reads as stale data. */
+    /** Show today's date (server clock, weekday and day, no time) in the top bar next to the title; hidden below `sm`.
+     *  Default true; turn off for dashboards that host forms rather than live metrics. */
     readonly showUpdatedAt?: boolean;
     readonly slots?: ScreenSlots;
     readonly access?: AccessRule;

package/dist/screen-entity-edit.d.ts

@@ -440,6 +440,8 @@ export type EntityEditScreenDefinition = {
     readonly entity: string;
     /** Entity field whose value names the loaded record in the header breadcrumb (edit mode only). */
     readonly recordTitleField?: string;
+    /** Focused shell while the record is open: the app header actions leave the shell header, and on phones a top bar with the record title, a back arrow to the parent list and the page-header overflow menu replaces it. Default off. */
+    readonly focus?: boolean;
     /** Screen title (i18n key) with `{field}` placeholders filled from the
      *  current form values, so the title follows what the user types (create
      *  wizard: "Add {make} {model}"). Falls back to the plain title while the

package/dist/screen-entity-list.d.ts

@@ -1,6 +1,6 @@
 import type { FieldCondition } from "./fields.ts";
 import type { AccessRule, AgentScreenHints } from "./handlers.ts";
-import type { NamedListFilterRef } from "./named-list-filters.ts";
+import type { ListSortDir, ListSortOption, ListSortSpec, NamedFilterFacetOptions, NamedListFilterRef } from "./named-list-filters.ts";
 import type { IconKey } from "./nav-icon.ts";
 import type { FieldRenderer, PlatformComponent, ScreenNavSugar, ScreenSlots } from "./screen.ts";
 import type { ActionFormRedirect } from "./screen-action-form.ts";
@@ -9,7 +9,7 @@ import type { ListEmptyStateSpec } from "./screen-entity-edit.ts";
 import type { EntityListExpandableRow } from "./screen-expandable-row.ts";
 import type { ScreenFallback } from "./screen-fallback.ts";
 import type { ListBulkAction } from "./screen-list-bulk.ts";
-import type { ListColumnPin, ListTableOptions } from "./screen-list-table.ts";
+import type { ListColumnPin, ListNarrowFacets, ListTableOptions, ListToolbarActionsPlacement } from "./screen-list-table.ts";
 export type ListColumnSpec = string | {
     readonly field: string;
     readonly renderer?: FieldRenderer;
@@ -45,47 +45,85 @@ export type ListColumnSpec = string | {
      *  `sortable` on. Ignored on `entityList` columns, where the entity
      *  field's own `sortable` flag wins. */
     readonly sortable?: boolean;
-    /** Value type of a relatedList column, which has no `EntityDefinition`
+    /** Value type of a projectionList or relatedList column, which has no `EntityDefinition`
      *  field to derive it from. Numeric types right-align the column and its
      *  header with tabular figures, like an entityList column of that field
      *  type. Ignored on entityList columns, where the field's own type wins. */
     readonly valueType?: "number" | "decimal" | "bigInt" | "money";
+    /** `false` leaves an empty cell blank instead of drawing the "—" placeholder. Not combinable with `hint`, whose empty sentence is `hint.emptyLabel`. */
+    readonly emptyPlaceholder?: false;
     /** Leaves the column out of the compact card layout used below the
      *  `md` breakpoint (tables keep it). For columns that only make sense
      *  next to the others, like a sort key. */
     readonly hideOnNarrow?: boolean;
+    /** Counterpart of `hideOnNarrow`: the column shows only in the compact card layout and not in the table.
+     *  Not combinable with `hideOnNarrow`, `hidden` or `pinned`. */
+    readonly showOnNarrowOnly?: true;
+    /** In the compact card, consecutive `narrowInline` columns stand side by side on one line (12px gap, no separator) instead of one line each. */
+    readonly narrowInline?: true;
     /** Start state for the column picker: the column begins hidden and the
      *  user can show it. Only valid together with `table.columnPicker`. */
     readonly hidden?: boolean;
     /** Start pin for the column: it sticks to this edge while the table scrolls
      *  horizontally. Only valid together with `table.pinning`. */
     readonly pinned?: ListColumnPin;
-    /** Start width in px. Only valid together with `table.resizing`. */
+    /** Start width in px. Needs `table.resizing`, except on a hint column, which sizes itself. */
     readonly width?: number;
-    /** Smallest width in px the user can resize to. Only valid together with `table.resizing`. */
+    /** Smallest width in px the user can resize to. Needs `table.resizing`, except on a hint column. */
     readonly minWidth?: number;
-    /** Dashboard list panels only. "bar": field holds a 0..1 fraction, drawn
-     *  as bar + percent. "badge": field holds a label, drawn as a pill whose
-     *  tone comes from `badgeToneField`. "datetime": field holds an ISO string or
-     *  epoch ms, shown in the user's locale and time zone. Other list renderers
-     *  ignore it. */
+    /** One of "bar" | "badge" | "datetime" | "button". "bar": field holds a 0..1 fraction,
+     *  drawn as bar + percent (dashboard list panels only). "badge": field holds a label,
+     *  drawn as a pill whose tone comes from `badgeToneField` (dashboard list panels and the
+     *  RenderList tables of entityList and projectionList). "datetime": field holds an ISO
+     *  string or epoch ms, shown in the user's locale and time zone (dashboard list panels
+     *  only). "button": a column with a screen link (linkScreenField or refEntity) draws the
+     *  link as a small outline button, in dashboard list panels only; a row button in an
+     *  entityList or projectionList table is a rowAction with display "button" (boot-rejected
+     *  on columns there). Other list renderers ignore `display`. */
     readonly display?: ListColumnDisplay;
     /** Row field naming the badge tone; only with `display: "badge"`. */
     readonly badgeToneField?: string;
+    /** `false` draws the badge pill without its leading dot; only with `display: "badge"`. */
+    readonly badgeDot?: false;
     /** Row field holding a screen QN (`<feature>:screen:<id>`): the cell links
      *  to that screen when the row sets it and the user may open it. For
      *  query-backed lists (projectionList, relatedList), whose rows can point
      *  at a different screen each. */
     readonly linkScreenField?: string;
+    /** Row field holding a params object for the linkScreenField target: `entityId` opens that record, the other keys become search params (e.g. actionForm prefill). Only with linkScreenField. */
+    readonly linkParamsField?: string;
+    /** "To do" cell: the column's field holds a sentence, shown emphasized in the row tone; an empty value shows `emptyLabel`. Owns the cell rendering, so no `renderer`. */
+    readonly hint?: ListColumnHint;
 };
-export type ListColumnDisplay = "bar" | "badge" | "datetime";
+export type ListColumnHint = {
+    /** Row field with a second, muted line (e.g. the due date as text). */
+    readonly detailField?: string;
+    /** Row field shown as the detail line below `sm` instead of `detailField` (a shorter line, e.g. "5 days · Anna Schneider"). Needs `detailField`. */
+    readonly narrowDetailField?: string;
+    /** Row field shown as the sentence on the phone card instead of the column's own value (a shorter sentence); the table keeps the column value. An empty value falls back to it. */
+    readonly narrowField?: string;
+    /** Row field holding a SelectOptionTone; defaults to the screen's `rowToneField`. Tone `neutral` draws the sentence muted and not bold, like `emptyLabel`, and no stripe on the phone card. */
+    readonly toneField?: string;
+    /** Row field with a longer reason, shown behind a "Why?" toggle in the cell. */
+    readonly reasonField?: string;
+    /** Row field (boolean): while true, the `reasonField` text stands open as a box under the row, over the full row width, in the table view (entity/projection lists from `md` up, dashboard lists from `sm` up); the (i) stays and closes it. Cards and narrower views keep the plain toggle. Needs `reasonField`. */
+    readonly reasonOpenField?: string;
+    /** Row field with a bold lead-in of the reason paragraph ("Rule 10 · Case open."); without it the reason has none. Needs `reasonField`. */
+    readonly reasonTitleField?: string;
+    /** i18n key for an empty sentence; default `kumiko.list.hint.empty`. */
+    readonly emptyLabel?: string;
+    /** The sentence keeps the normal text color (still bold); the tone stays on the row stripe, a badge and the detail line. */
+    readonly plainSentence?: true;
+};
+/** Computed fields for the loaded rows: `query` calls with `{ ...params, ids }`, answering `{ rows: [{ id, ...fields }] }`. Fields are merged into the rows and win over same-named row fields. The ids go out in batches of the first page size (later pages send only the newly loaded ids; a reload re-asks all loaded rows batch by batch), so `ids.max` must cover at least the page size; a failing call shows plain rows. */
+export type ListRowDecoration = {
+    readonly query: string;
+    readonly params?: Readonly<Record<string, unknown>>;
+};
+export type ListColumnDisplay = "bar" | "badge" | "datetime" | "button";
 export type ListBadgeTone = "positive" | "warn" | "negative" | "neutral";
 export type ListPaginationMode = "pages" | "infinite" | false;
-export type ListSortDir = "asc" | "desc";
-export type ListSortSpec = {
-    readonly field: string;
-    readonly dir: ListSortDir;
-};
+export type { ListSortDir, ListSortOption, ListSortSpec };
 export type ScreenFilterOp = "eq" | "ne" | "lt" | "gt" | "lte" | "gte" | "in";
 export type ScreenFilter = {
     readonly field: string;
@@ -116,8 +154,11 @@ export type RowFieldExtractor = {
 export type RowActionDisplay = "button" | "link" | "icon" | "responsive";
 /** Row-action column layout. `"adaptive"` (default): primary action as link,
  *  the rest in a kebab menu — except actions with an explicit `display`, which
- *  stay inline. `"inline"`: every action inline, no kebab. */
-export type RowActionMode = "adaptive" | "inline";
+ *  stay inline. `"inline"`: every action inline, no kebab. `"menu"`: every
+ *  action in the kebab menu at the row end, none inline, the row opener
+ *  (`rowClick: true`) included as an entry, so every row has a kebab; phone
+ *  cards draw no kebab when the row opens, a card without a row target keeps it. */
+export type RowActionMode = "adaptive" | "inline" | "menu";
 export type RowAction = RowActionWriteHandler | RowActionNavigate | RowActionDrawer | RowActionClientAction;
 export type RowActionWriteHandler = {
     /** Default for RowActions without an explicitly set `kind` —
@@ -330,6 +371,8 @@ export type ToolbarAction = ({
     /** Line under the drawer heading (i18n key). */
     readonly subtitle?: string;
 }) & {
+    /** Icon of the button, in every list (entityList, projectionList, relatedList). Without it the id-derived default applies (`create` → plus). */
+    readonly icon?: IconKey;
     /** Shown only while the query's `field` equals `eq` (live, empty payload). Hidden while the
      *  query loads and when it fails. Named like the screen and panel gates because it is
      *  query-based; a list toolbar has no record to evaluate a row condition against. */
@@ -372,6 +415,8 @@ export type EntityListFacetExtraOption = {
     readonly values: readonly string[];
     /** Where the chip sits relative to the field's own options. Default "start". */
     readonly position?: "start" | "end";
+    /** Draws a divider line below this choice in the select dropdown (e.g. after a "needs action" bundle). */
+    readonly separatorAfter?: boolean;
 };
 export type EntityListFacetConfig = {
     /** `"select"` (default): dropdown with checkboxes. `"chips"`: one toggle
@@ -386,6 +431,8 @@ export type EntityListFacetConfig = {
      *  `showCounts`'s requests even when the number itself is not shown. */
     readonly hideEmpty?: boolean;
     readonly extraOptions?: readonly EntityListFacetExtraOption[];
+    /** "behind-filter": the facet opens behind the filter icon next to the search field instead of standing as a pill. Only below `sm`; otherwise it stays a pill. The remaining facets follow the usual phone rules and share the toggle panel. */
+    readonly narrowPlacement?: "behind-filter";
 };
 export type EntityListScreenDefinition = {
     readonly id: string;
@@ -414,8 +461,11 @@ export type EntityListScreenDefinition = {
     /** `false` hides this list's "+ New" button (and the empty-state create CTA) while the entity's edit screen keeps its create branch for other entry points, e.g. a prefilled action. Default `true`. */
     readonly allowCreate?: boolean;
     readonly columns: readonly ListColumnSpec[];
+    /** Row field holding a SelectOptionTone; the row is toned like relatedList `rowTone`, other values leave it untoned. */
+    readonly rowToneField?: string;
+    /** Computed row fields from an app query, readable by `rowToneField`, column `hint`, `linkScreenField`/`linkParamsField` and rowAction `visible`/`params`/`payload`; a column may name a decoration field. */
+    readonly rowDecoration?: ListRowDecoration;
     readonly rowRenderer?: PlatformComponent;
-    readonly cardRenderer?: PlatformComponent;
     /** Per-row actions, rendered as an actions column on the right.
      *  Adaptive (default, see `rowActionMode`): the primary action as a link,
      *  the rest in the kebab menu; actions with an explicit `display` stay
@@ -444,6 +494,8 @@ export type EntityListScreenDefinition = {
     /** Opt-in table behaviour: remembered state, reset, column picker, density. */
     readonly table?: ListTableOptions;
     readonly defaultSort?: ListSortSpec;
+    /** Choices of the "Sorted by" select in the toolbar (and the narrow-width sort control) instead of one entry per column; every field must be sortable. */
+    readonly sortOptions?: readonly ListSortOption[];
     /** Initial facet selection, per filterable field: option values (string
      *  facets) or a boolean. Applies only while the URL carries no value for
      *  that field, so a link or the user's own choice wins; picking "no filter"
@@ -459,10 +511,22 @@ export type EntityListScreenDefinition = {
      *  `label` an i18n key. Selected through the `<screenId>.filter` URL key; a dashboard stat's
      *  `navigate.namedFilter` links here. While one is active `defaultFilters` are not applied. */
     readonly namedFilters?: readonly NamedListFilterRef[];
+    /** Presentation of `namedFilters` in the toolbar; needs `namedFilters`. */
+    readonly namedFilterFacet?: NamedFilterFacetOptions;
     /** Replaces the default empty-list title/hint; the create button stays when the list can create. */
     readonly emptyState?: ListEmptyStateSpec;
     /** i18n key for the primary create button label (default `kumiko.actions.create`). */
     readonly createLabel?: string;
+    /** "toolbar": from `md` up (below md the compact header keeps its "+") the create button ends the filter row instead of standing in the header. Default "header". Needs a create button (no `allowCreate: false`). */
+    readonly createPlacement?: "header" | "toolbar";
+    /** From `sm` up, a "Sorted by" select in the filter row (same options as the narrow sort control); column headers stay sortable. */
+    readonly toolbarSort?: true;
+    /** "pills": below `sm` the select facets render as rounded pill triggers with a stronger border; from `sm` up unchanged. */
+    readonly narrowFacets?: ListNarrowFacets;
+    /** "toolbar": from `md` up the `toolbarActions` end the filter row, after the "Sorted by" select and the create button, instead of standing in the page header. Below `md` they stay in the header. Default "header". Needs `toolbarActions`. */
+    readonly toolbarActionsPlacement?: ListToolbarActionsPlacement;
+    /** i18n key of the plural noun for the list size in the phone sort line (`{count}` pluralised). Default `<feature>:entity:<entity>:noun`. */
+    readonly itemNounKey?: string;
     /** i18n key for the search field placeholder (default `kumiko.list.search-placeholder`). */
     readonly searchPlaceholder?: string;
     readonly searchable?: boolean;

package/dist/screen-list-table.d.ts

@@ -1,9 +1,41 @@
 import type { ListAggregateMeasureKind } from "./list-aggregate-types.ts";
-export declare const LIST_TABLE_DENSITIES: readonly ["comfortable", "compact"];
+export declare const LIST_TABLE_DENSITIES: readonly ["comfortable", "compact", "relaxed"];
 export type ListTableDensity = (typeof LIST_TABLE_DENSITIES)[number];
+/** Upper bound for a list column width in pixels; the renderer clamps to it, the boot validator rejects above it. */
+export declare const LIST_COLUMN_MAX_WIDTH_PX = 2000;
 export declare const LIST_COLUMN_PINS: readonly ["left", "right"];
 export type ListColumnPin = (typeof LIST_COLUMN_PINS)[number];
-export declare const LIST_TABLE_OPTION_KEYS: readonly ["rememberState", "resetAll", "columnPicker", "density", "pinning", "resizing", "keyboardNavigation", "export", "grouping", "totals", "compactHeader"];
+export declare const LIST_TABLE_OPTION_KEYS: readonly ["rememberState", "resetAll", "columnPicker", "density", "pinning", "resizing", "keyboardNavigation", "export", "grouping", "totals", "summaryRow", "compactHeader", "frame"];
+export declare const LIST_TABLE_FRAMES: readonly ["card"];
+export type ListTableFrame = (typeof LIST_TABLE_FRAMES)[number];
+export declare const LIST_TOOLBAR_ACTIONS_PLACEMENTS: readonly ["header", "toolbar"];
+export type ListToolbarActionsPlacement = (typeof LIST_TOOLBAR_ACTIONS_PLACEMENTS)[number];
+export declare const LIST_NARROW_FACETS: readonly ["pills"];
+export type ListNarrowFacets = (typeof LIST_NARROW_FACETS)[number];
+export declare const LIST_TABLE_SUMMARY_ROW_KEYS: readonly ["query", "params"];
+export type ListPayloadCapabilities = {
+    readonly searchable: boolean;
+    readonly filters: boolean;
+    readonly namedFilters: boolean;
+    readonly screenFilter: boolean;
+};
+export declare function listPayloadKeysSent(capabilities: ListPayloadCapabilities): readonly string[];
+type FlaggedFields = {
+    readonly fields: Readonly<Record<string, object>>;
+} | undefined;
+/** True when the entity has a `filterable` field; the facet dropdowns and the `filters` payload key rest on it. */
+export declare function entityHasFilterableFields(entity: FlaggedFields): boolean;
+/** An explicit `searchable` wins, otherwise a searchable field turns search on. The renderer additionally needs a search adapter. */
+export declare function entityListDeclaresSearch(screen: {
+    readonly searchable?: boolean;
+}, entity: FlaggedFields): boolean;
+/** Whether an entityList can send `filters`: filterable fields, default filters or a range facet. */
+export declare function entityListDeclaresFilters(screen: {
+    readonly defaultFilters?: object;
+    readonly facets?: Readonly<Record<string, false | {
+        readonly display?: string;
+    }>>;
+}, entity: FlaggedFields): boolean;
 export declare const LIST_TABLE_GROUPING_KEYS: readonly ["field", "label", "labels", "collapsedWhen", "userChoice", "fields"];
 export declare const LIST_TABLE_TOTAL_KEYS: readonly ["field", "kind"];
 export declare const LIST_TABLE_EXPORT_KEYS: readonly ["xlsx", "maxRows"];
@@ -27,8 +59,10 @@ export type ListTableOptions = {
     readonly keyboardNavigation?: boolean;
     /** Renders the header row smaller (12px) and semibold. */
     readonly compactHeader?: boolean;
+    /** "card": from `sm` up the table, summary row and pager sit in one bordered, rounded card (toolbar and description stay above it); below `sm` the cards of the card layout are bordered, rounded cards with a gap. Default: the table runs frameless over the page width. */
+    readonly frame?: ListTableFrame;
     readonly density?: {
-        /** Row density on first visit. Default "comfortable". */
+        /** Row density on first visit. Default "comfortable"; "relaxed" gives the body cells 12px vertical padding from sm, the header row stays as is. */
         readonly default?: ListTableDensity;
         /** Shows the density choice in the view menu and remembers it per session. */
         readonly userChoice?: boolean;
@@ -39,6 +73,17 @@ export type ListTableOptions = {
     readonly grouping?: ListTableGrouping;
     /** Footer row under the rows, computed by the server over all rows matching the current filters and search. In grouped mode the same measures show in each group header. */
     readonly totals?: readonly ListTableTotal[];
+    /** One line under the rows (above `totals`), computed by a query of your own: "label value · label value"; an item without `label` shows its value alone. */
+    readonly summaryRow?: ListTableSummaryRow;
+};
+/** The query receives the list's current search, filters and named filter (no paging, no sort) plus `params`, and answers `{ items: [{ label?, value, tone?, column? }] }`.
+ *  When an item names a `column` (a column field of the list), the table draws the row as a table row: the values stand in the cells under their columns, without labels; items without `column` go to the first column.
+ *  Without any `column` the row stays one line "label value · label value". */
+export type ListTableSummaryRow = {
+    /** Qualified query name, e.g. `feature:query:order:summary`. Its Zod schema accepts every list key the screen sends (search, filters, namedFilter, ...). */
+    readonly query: string;
+    /** Extra payload keys merged over the list's own. */
+    readonly params?: Readonly<Record<string, unknown>>;
 };
 export type ListTableGrouping = {
     /** Start grouping. Without it the list starts ungrouped and the user picks from `fields`. */
@@ -70,3 +115,4 @@ export type BundledListsOptions = {
     /** Pins the first column left on every bundled list where no column is pinned. Needs `table.pinning: true`. */
     readonly pinFirstColumn?: boolean;
 };
+export {};

package/dist/screen-list-table.js

@@ -1,4 +1,6 @@
-export const LIST_TABLE_DENSITIES = ["comfortable", "compact"];
+export const LIST_TABLE_DENSITIES = ["comfortable", "compact", "relaxed"];
+/** Upper bound for a list column width in pixels; the renderer clamps to it, the boot validator rejects above it. */
+export const LIST_COLUMN_MAX_WIDTH_PX = 2000;
 export const LIST_COLUMN_PINS = ["left", "right"];
 export const LIST_TABLE_OPTION_KEYS = [
     "rememberState",
@@ -11,8 +13,40 @@ export const LIST_TABLE_OPTION_KEYS = [
     "export",
     "grouping",
     "totals",
+    "summaryRow",
     "compactHeader",
+    "frame",
 ];
+export const LIST_TABLE_FRAMES = ["card"];
+export const LIST_TOOLBAR_ACTIONS_PLACEMENTS = ["header", "toolbar"];
+export const LIST_NARROW_FACETS = ["pills"];
+export const LIST_TABLE_SUMMARY_ROW_KEYS = ["query", "params"];
+// The optional list-query keys a list screen sends for what it declares, in one place so the boot
+// validator (summary-row schema check) and the renderer's payload tests agree on them.
+export function listPayloadKeysSent(capabilities) {
+    return [
+        ...(capabilities.searchable ? ["search"] : []),
+        ...(capabilities.filters ? ["filters"] : []),
+        ...(capabilities.namedFilters ? ["namedFilter"] : []),
+        ...(capabilities.screenFilter ? ["filter"] : []),
+    ];
+}
+function someFieldFlagged(entity, flag) {
+    return Object.values(entity?.fields ?? {}).some((field) => Reflect.get(field, flag) === true);
+}
+/** True when the entity has a `filterable` field; the facet dropdowns and the `filters` payload key rest on it. */
+export function entityHasFilterableFields(entity) {
+    return someFieldFlagged(entity, "filterable");
+}
+/** An explicit `searchable` wins, otherwise a searchable field turns search on. The renderer additionally needs a search adapter. */
+export function entityListDeclaresSearch(screen, entity) {
+    return screen.searchable ?? someFieldFlagged(entity, "searchable");
+}
+/** Whether an entityList can send `filters`: filterable fields, default filters or a range facet. */
+export function entityListDeclaresFilters(screen, entity) {
+    const hasRangeFacet = Object.values(screen.facets ?? {}).some((facet) => facet !== false && facet.display === "range");
+    return entityHasFilterableFields(entity) || screen.defaultFilters !== undefined || hasRangeFacet;
+}
 export const LIST_TABLE_GROUPING_KEYS = [
     "field",
     "label",