@everystack/admin 0.4.2 → 0.4.4

package/src/types.ts

@@ -38,7 +38,11 @@ export interface ActionContext {
   adapter: DataAdapter;
   /** Re-fetch the current view after a mutation. */
   refetch: () => Promise<void> | void;
-  /** Navigate to an admin path, when the route layer provides it. */
+  /**
+   * Go to an admin path. Optional: RowActionButton passes it through when its
+   * caller supplies one, but the built-in ResourceList and ResourceShow do not,
+   * so it is undefined there. Check it before you call it.
+   */
   navigate?: (path: string) => void;
 }
 
@@ -53,6 +57,11 @@ export interface InputContext {
   field: FieldDefinition;
   record?: DataRecord;
   error?: string;
+  /**
+   * The whole form's current values, keyed by field name (what Save would
+   * send). Read another field here to render a block that depends on it.
+   */
+  values: Record<string, unknown>;
 }
 
 /**
@@ -100,7 +109,18 @@ export type FieldType =
   | 'enum'
   | 'relation'
   | 'image'
-  | 'file';
+  | 'file'
+  | 'tags';
+
+/**
+ * One group of options for a `tags` field. `label` is shown as a small heading
+ * above the group's pills; leave it out for a flat set. An option's label
+ * defaults to its value.
+ */
+export interface TagGroup {
+  label?: string;
+  options: Array<{ value: string; label?: string }>;
+}
 
 export interface FieldDefinition {
   /** Field name (matches data key) */
@@ -117,6 +137,19 @@ export interface FieldDefinition {
   filterable?: boolean;
   /** For enum types: allowed values */
   enumValues?: string[];
+  /**
+   * For enum types: edit the value from the list cell. The cell shows a picker
+   * of `enumValues` and saves a pick with `adapter.update(resource, id, { [name]: value })`.
+   * Ignored for other types, and when a `render` override is set.
+   * Follows `actions.edit`: a resource with `actions.edit: false` shows the plain text cell.
+   */
+  inlineEdit?: boolean;
+  /**
+   * For tags types (a text[] column): the options, as pills in groups. A press
+   * toggles one value and keeps every other stored value, including values in
+   * no group (they show in an "Other" row).
+   */
+  tagGroups?: TagGroup[];
   /** For relation types: related resource name */
   relation?: {
     resource: string;
@@ -131,6 +164,26 @@ export interface FieldDefinition {
     pattern?: string;
     message?: string;
   };
+  /**
+   * Fixed width of this field's list column, in px (list view only). The
+   * column then neither grows nor shrinks; without it the column shares the
+   * remaining space.
+   */
+  listWidth?: number;
+  /**
+   * How soon this field's list column drops when the list is too narrow
+   * (list view only; the Show page keeps every field). 1 (or less) never
+   * drops, a larger number drops sooner, and a field without one drops
+   * before every field that has one. Nothing drops until some field sets
+   * `listPriority` or `listHideBelow`; the Actions column never drops.
+   */
+  listPriority?: number;
+  /**
+   * Drop this field's list column while the list's container is narrower
+   * than this many px, even if it would fit (list view only). Ignored on a
+   * field that never drops (`listPriority` of 1 or less).
+   */
+  listHideBelow?: number;
   /** Renderer variant for this field type (e.g., 'avatar' for image fields) */
   renderer?: string;
   /**
@@ -146,6 +199,9 @@ export interface FieldDefinition {
   /**
    * Custom form input (create/edit) — wins over the type/renderer input. The
    * custom input owns its element (control + optional label/error frame).
+   * It is rendered as its own component, so hooks inside it are fine. Pass a
+   * stable function (declared once, not an inline arrow made on each render),
+   * or the input remounts and loses its state every render.
    */
   input?: (ctx: InputContext) => ReactNode;
   /**
@@ -162,6 +218,26 @@ export interface FieldDefinition {
 // Resource Configuration
 // =============================================================================
 
+/**
+ * One column of a Show/Edit/Create screen. `width`: 'wide' takes the space
+ * left over; 'narrow' is a fixed 320px; a number is a fixed width in px. The
+ * default is 'wide' for the first column and 'narrow' for the others.
+ */
+export interface LayoutColumn {
+  /** Field names, top to bottom. */
+  fields: string[];
+  width?: 'wide' | 'narrow' | number;
+}
+
+/**
+ * How a Show/Edit/Create screen places its fields. 'auto' puts long fields
+ * (custom render/input, json, image, file, tags, relation, rich or long text)
+ * in a wide main column and short ones in a narrow side column. A field no
+ * column lists goes at the end of the first column. Columns stack below a
+ * 720px container.
+ */
+export type ScreenLayout = 'auto' | { columns: LayoutColumn[] };
+
 /**
  * A declarative action on a single record (delete/restore, retry/cancel a job),
  * rendered on both the list and show views and gated by the `when` clause.
@@ -214,8 +290,22 @@ export interface ResourceConfig {
     edit?: boolean;
     delete?: boolean;
   };
+  /**
+   * Rows per page when the list opens. Default 20. The page bar also offers
+   * 20, 50 and 100 (and this size, when it is not one of them); the chosen
+   * size is kept in the URL as `size`. A value that is not a whole number
+   * above 0 is ignored; one above 500 is capped to 500.
+   */
+  perPage?: number;
   /** Fields to display in list view */
   listFields?: string[];
+  /**
+   * Fixed width of the list's Actions column, in px. Default, or when this is
+   * not a finite number above 0: an estimate from the idle labels of the
+   * actions the column renders, built-in and rowActions. A longer two-step
+   * confirm label wraps to a second line inside the cell.
+   */
+  actionsWidth?: number;
   /** Fields to display in detail/show view */
   showFields?: string[];
   /** Fields to display in create form */
@@ -224,6 +314,12 @@ export interface ResourceConfig {
   editFields?: string[];
   /** Primary key field name */
   primaryKey?: string;
+  /**
+   * PostgREST select string for list, show and edit, embeds included, e.g.
+   * '*,user:users(name)'. One string for all three. Show an embedded value
+   * through a field `render`. RPC-backed resources ignore it.
+   */
+  select?: string;
   /** How the show view fetches one record. 'rpc' calls the role-gated
    *  {camelResource}EventDetail RPC (the resource stays off the REST surface);
    *  'rest' (default) uses adapter.fetchOne. Lets a plain list (no dashboard) —
@@ -231,8 +327,45 @@ export interface ResourceConfig {
   detailVia?: 'rpc' | 'rest';
   /** Optional observability-style dashboard configuration */
   dashboard?: ResourceDashboardConfig;
-  /** RPC-backed record actions shown on the show view */
+  /**
+   * Custom record actions (rpc, onPress or render). They show on the show view
+   * and in the list's Actions column, after the built-in Show/Edit/Delete.
+   */
   rowActions?: RowActionConfig[];
+  /** Tabs above the list, each a named filter. Without this the list shows no tabs. */
+  scopes?: ScopeConfig[];
+  /**
+   * The table soft-deletes. Turns on Restore for deleted rows (in a scope with
+   * `deleted: 'only'`, and on Show) and makes Show load a deleted row. Delete
+   * stays shown unless `actions.delete` is false.
+   */
+  softDelete?: {
+    /** The soft-delete column, as the API names it. Default 'deletedAt'. */
+    column?: string;
+  };
+  /**
+   * Rows in other tables that point at this record. Before a delete, Show lists
+   * each one with a count of the linked rows (one request each, at most 12).
+   * Without it, Delete works as before.
+   */
+  associations?: AssociationConfig[];
+  /**
+   * Show a row count on each tab. Off unless set: counts cost queries. The values of one
+   * enum column share one grouped query; every other tab costs one count. Counts follow the
+   * search, and need an adapter with `aggregate`.
+   */
+  scopeCounts?: boolean;
+  /**
+   * Field columns for Show, Edit and Create. Without any layout, each screen
+   * shows one column of fields, as before.
+   */
+  layout?: ScreenLayout;
+  /** Show only: wins over `layout`. */
+  showLayout?: ScreenLayout;
+  /** Edit (and Create, unless `createLayout` is set): wins over `layout`. */
+  editLayout?: ScreenLayout;
+  /** Create only: wins over `editLayout` and `layout`. */
+  createLayout?: ScreenLayout;
 }
 
 // =============================================================================
@@ -452,6 +585,43 @@ export interface AdminConfig {
 // Data Types
 // =============================================================================
 
+/**
+ * A table that links to a record, counted in the delete preview. A polymorphic
+ * link (`resource_id` + `resource_type`, often with no foreign key) sets
+ * `typeColumn` and `typeValue` as well.
+ */
+export interface AssociationConfig {
+  /** Shown in the preview, e.g. 'Bookmarks'. */
+  label: string;
+  /** The related table or resource name, as the adapter knows it. */
+  resource: string;
+  /** The column on the related table that holds this record's id. */
+  foreignKey: string;
+  /** The polymorphic type column on the related table, e.g. 'resource_type'. */
+  typeColumn?: string;
+  /** The value of `typeColumn` that means this resource, e.g. 'Content'. */
+  typeValue?: string;
+}
+
+/**
+ * A named filter shown as a tab above a list ("Current", "Draft"). Scopes are
+ * ANDed with the search and any column filters.
+ */
+export interface ScopeConfig {
+  /** Stable id; this is what the URL carries (`?tab=draft`). */
+  id: string;
+  label: string;
+  /** Filter applied while this scope is active, in the adapter's filter syntax. None means all rows. */
+  filter?: Record<string, unknown>;
+  /** The scope active when the URL names none. If none is marked, the first is. */
+  default?: boolean;
+  /** Soft-deleted rows: 'include' adds them, 'only' lists nothing else. See ListParams.deleted. */
+  deleted?: DeletedMode;
+}
+
+/** Soft-delete reads: 'include' returns live and deleted rows, 'only' deleted rows. */
+export type DeletedMode = 'include' | 'only';
+
 export interface ListParams {
   /** Page number (1-indexed) */
   page?: number;
@@ -463,8 +633,25 @@ export interface ListParams {
   order?: 'asc' | 'desc';
   /** Filter conditions */
   filter?: Record<string, unknown>;
-  /** Search query */
+  /** Search text, matched (ILIKE, case-insensitive) in any of `searchFields`. */
   search?: string;
+  /**
+   * Columns `search` looks in. Required with `search`: the adapter does not know
+   * your schema, so it refuses search text without them rather than silently
+   * returning unfiltered rows. Plain column names only.
+   */
+  searchFields?: string[];
+  /**
+   * PostgREST select string, embeds included, e.g. '*,user:users(name)'.
+   * Passed verbatim to the query builder. Ignored by RPC-backed resources
+   * (listRpcs); an RPC decides its own shape.
+   */
+  select?: string;
+  /**
+   * Soft-deleted rows, sent as `?deleted=` to the API. RPC-backed resources
+   * get it in the RPC body, and the RPC owner decides.
+   */
+  deleted?: DeletedMode;
 }
 
 export interface ListResult<T = Record<string, unknown>> {
@@ -507,6 +694,12 @@ export interface AggregateParams {
   groupBy?: string[];
   /** Filter conditions */
   filter?: Record<string, unknown>;
+  /** Search text, matched in any of `searchFields`, exactly as `ListParams.search`. */
+  search?: string;
+  /** Columns `search` looks in. Required with `search`. Plain column names only. */
+  searchFields?: string[];
+  /** Soft-deleted rows, exactly as `ListParams.deleted`, so a Deleted tab counts deleted rows. */
+  deleted?: DeletedMode;
 }
 
 export interface AggregateResult {

package/src/utils/format-cell-value.ts

@@ -7,6 +7,7 @@
  */
 
 import type { FieldDefinition } from '../types';
+import { tagLabel, tagValues } from './tags';
 
 /**
  * A date-only ISO string has no time-of-day; `new Date(str)` parses it as UTC midnight, and
@@ -63,6 +64,10 @@ export function formatCellValue(field: FieldDefinition, value: unknown): string
       return value ? 'Yes' : 'No';
     case 'json':
       return typeof value === 'string' ? value : JSON.stringify(value);
+    case 'tags': {
+      const tags = tagValues(value);
+      return tags.length === 0 ? '—' : tags.map(tag => tagLabel(field, tag)).join(', ');
+    }
     default:
       return typeof value === 'object' ? JSON.stringify(value) : String(value);
   }

package/src/utils/list-query.ts

@@ -0,0 +1,202 @@
+/**
+ * Pure model of a list's query state: search text, scope tab, sort and page.
+ *
+ * The URL is the source of truth (see useViewState), so every list view is a
+ * link. This file holds the rules and nothing else: parse the URL, write it
+ * back, apply a change, and turn the state into the adapter's ListParams. It
+ * knows no React and no resource schema, which keeps it testable on its own.
+ *
+ * URL names: `q`, `tab`, `sort`, `dir`, `page`, `size`. They are reserved (see view-filters.ts), so a
+ * resource column with one of those names cannot be drilled into from the URL. `tab` and
+ * `dir`, not `scope` and `order`, because those are common column names.
+ *
+ * Column filters from the URL (`?state=draft`) are a separate mechanism
+ * (view-filters.ts) and are left alone here.
+ */
+
+import type { ViewParams } from '../hooks/useViewState';
+import type { DeletedMode, ListParams } from '../types';
+
+/** Longest search text kept. A pasted paragraph is not a search. */
+export const MAX_SEARCH_LENGTH = 200;
+
+/** Search text only: PostgreSQL text values cannot contain NUL. */
+export function normalizeSearchText(text?: string): string | undefined {
+  return text?.replace(/\u0000/g, '').trim().slice(0, MAX_SEARCH_LENGTH) || undefined;
+}
+
+export interface ListQuery {
+  search?: string;
+  scope?: string;
+  sort?: string;
+  order?: 'asc' | 'desc';
+  /** 1-based. Absent means page 1. */
+  page?: number;
+  /** Rows per page (`size` in the URL). Absent means the resource's default. */
+  perPage?: number;
+}
+
+/** Largest page size the list fetches. A larger `size` in the URL is capped to it. */
+export const MAX_PAGE_SIZE = 500;
+
+/**
+ * The page size to use for a resource's configured `perPage`: a whole number
+ * above 0, capped to MAX_PAGE_SIZE. Anything else gives `fallback`, so a bad
+ * config never reaches the adapter or the page bar.
+ */
+export function resolvePageSize(configured: number | undefined, fallback = 20): number {
+  if (configured === undefined || !Number.isInteger(configured) || configured <= 0) return fallback;
+  return Math.min(configured, MAX_PAGE_SIZE);
+}
+
+/**
+ * The page that holds the first row of `page` once the list shows `newSize`
+ * rows a page, so changing the size keeps that row in view.
+ */
+export function pageForSize(page: number, oldSize: number, newSize: number): number {
+  return Math.floor(((page - 1) * oldSize) / newSize) + 1;
+}
+
+const POSITIVE_INTEGER = /^[1-9]\d*$/;
+/** No real list has more pages. A larger number is not a page: sent on, it is read as an exponent. */
+const MAX_PAGE = 1_000_000;
+
+/** URL query → list state. Anything malformed is ignored, never thrown. */
+export function parseListQuery(params: ViewParams): ListQuery {
+  const query: ListQuery = {};
+
+  const search = normalizeSearchText(params.q);
+  if (search) query.search = search;
+
+  const scope = params.tab?.trim();
+  if (scope) query.scope = scope;
+
+  const sort = params.sort?.trim();
+  if (sort) query.sort = sort;
+
+  if (params.dir === 'asc' || params.dir === 'desc') query.order = params.dir;
+
+  if (params.page && POSITIVE_INTEGER.test(params.page) && Number(params.page) <= MAX_PAGE) query.page = Number(params.page);
+
+  if (params.size && POSITIVE_INTEGER.test(params.size)) query.perPage = Math.min(Number(params.size), MAX_PAGE_SIZE);
+
+  return query;
+}
+
+/**
+ * List state → a `setParams` delta. Every key is present, so a cleared field
+ * removes its key from the URL. Defaults (page 1, no search, the resource's
+ * `defaultPerPage` and `defaultScope`) are not written.
+ */
+export function listQueryToParams(
+  query: ListQuery,
+  options: { defaultPerPage?: number; defaultScope?: string } = {},
+): Record<string, string | undefined> {
+  return {
+    q: query.search || undefined,
+    tab: query.scope && query.scope !== options.defaultScope ? query.scope : undefined,
+    sort: query.sort || undefined,
+    dir: query.order,
+    page: query.page && query.page > 1 ? String(query.page) : undefined,
+    size: query.perPage && query.perPage !== options.defaultPerPage ? String(query.perPage) : undefined,
+  };
+}
+
+/**
+ * Apply a change. Changing what the list shows (search, scope, sort) returns to
+ * page 1, because the old page number no longer means anything. A patch that
+ * names a page keeps it.
+ */
+export function updateListQuery(prev: ListQuery, patch: Partial<ListQuery>): ListQuery {
+  const next: ListQuery = { ...prev, ...patch };
+  const changesView = (['search', 'scope', 'sort', 'order'] as const).some(
+    key => key in patch && patch[key] !== prev[key],
+  );
+  if (changesView && !('page' in patch)) next.page = undefined;
+  return next;
+}
+
+/**
+ * AND two filter objects together. Two conditions on one column are kept as an
+ * array (the adapter applies an array as several ANDed conditions), so a scope
+ * and a column filter on the same column cannot overwrite each other.
+ */
+export function mergeFilters(
+  a?: Record<string, unknown>,
+  b?: Record<string, unknown>,
+): Record<string, unknown> | undefined {
+  const merged: Record<string, unknown> = {};
+  for (const source of [a, b]) {
+    if (!source) continue;
+    for (const [key, value] of Object.entries(source)) {
+      if (value == null) continue;
+      merged[key] = key in merged ? [...toArray(merged[key]), ...toArray(value)] : value;
+    }
+  }
+  return Object.keys(merged).length ? merged : undefined;
+}
+
+const toArray = (value: unknown): unknown[] => (Array.isArray(value) ? value : [value]);
+
+export interface BuildListParamsOptions {
+  /** The resource's default page size, used when the query has none. */
+  perPage?: number;
+  /** Filters from outside the query (analytics header, URL column filters). */
+  baseFilter?: Record<string, unknown>;
+  /** The active scope's filter, already resolved from the scope id. */
+  scopeFilter?: Record<string, unknown>;
+  /** The active scope's `deleted`, copied into ListParams beside the filter. */
+  scopeDeleted?: DeletedMode;
+  /** Columns a user may sort by. A sort outside this set is dropped. */
+  sortableFields?: ReadonlySet<string>;
+  /** Used when the query has no valid sort of its own. */
+  defaultSort?: { field: string; order?: 'asc' | 'desc' };
+}
+
+/** List state → the adapter's ListParams. */
+export function buildListParams(query: ListQuery, options: BuildListParamsOptions): ListParams {
+  const sortAllowed = query.sort && (!options.sortableFields || options.sortableFields.has(query.sort));
+
+  let sort: string | undefined;
+  let order: 'asc' | 'desc' | undefined;
+  if (sortAllowed) {
+    sort = query.sort;
+    order = query.order ?? 'asc';
+  } else if (options.defaultSort && (!options.sortableFields || options.sortableFields.has(options.defaultSort.field))) {
+    sort = options.defaultSort.field;
+    order = options.defaultSort.order ?? 'asc';
+  }
+
+  return {
+    page: query.page ?? 1,
+    perPage: query.perPage ?? options.perPage,
+    search: query.search,
+    sort,
+    order,
+    filter: mergeFilters(options.baseFilter, options.scopeFilter),
+    ...(options.scopeDeleted ? { deleted: options.scopeDeleted } : {}),
+  };
+}
+
+/** What the list is sorted by right now, defaults included. */
+export interface EffectiveSort {
+  sort?: string;
+  order?: 'asc' | 'desc';
+}
+
+/**
+ * The next sort after a click on a column header: ascending, then descending,
+ * then off (back to the default sort). On the default sort's own column "off"
+ * would be the same view, so it flips between ascending and descending instead.
+ * `off` is `{ sort: undefined, order: undefined }`, which clears both from the URL.
+ */
+export function nextSort(
+  current: EffectiveSort,
+  key: string,
+  defaultSort?: { field: string; order?: 'asc' | 'desc' },
+): EffectiveSort {
+  if (current.sort !== key) return { sort: key, order: 'asc' };
+  if ((current.order ?? 'asc') === 'asc') return { sort: key, order: 'desc' };
+  if (defaultSort?.field === key) return { sort: key, order: 'asc' };
+  return { sort: undefined, order: undefined };
+}

package/src/utils/required.ts

@@ -0,0 +1,10 @@
+import type { FieldDefinition } from '../types';
+
+/**
+ * Whether a value fails `validation.required`: null, undefined or ''. For a
+ * tags field an empty array fails too.
+ */
+export function missingRequired(field: FieldDefinition, value: unknown): boolean {
+  if (value == null || value === '') return true;
+  return field.type === 'tags' && Array.isArray(value) && value.length === 0;
+}

package/src/utils/resolve-columns.ts

@@ -0,0 +1,107 @@
+/**
+ * Field columns for Show, Edit and Create: which field goes in which column,
+ * and how wide each column is. Pure; FieldColumns draws the result.
+ */
+
+import { editorFor } from './render-resolution';
+import type { EditorRegistry, FieldDefinition, LayoutColumn, ResourceConfig, ScreenLayout } from '../types';
+
+/** Width of a 'narrow' column, in px. */
+export const NARROW_COLUMN_WIDTH = 320;
+
+/** A column ready to draw: 'wide' takes the space left over, a number is fixed px. */
+export interface ResolvedColumn {
+  fields: FieldDefinition[];
+  width: 'wide' | number;
+}
+
+export type LayoutScreen = 'show' | 'edit' | 'create';
+
+/**
+ * The layout a screen uses: Show `showLayout ?? layout`, Edit
+ * `editLayout ?? layout`, Create `createLayout ?? editLayout ?? layout`.
+ * Undefined means the screen renders its single column as before.
+ */
+export function screenLayout(resource: ResourceConfig, screen: LayoutScreen): ScreenLayout | undefined {
+  switch (screen) {
+    case 'show':
+      return resource.showLayout ?? resource.layout;
+    case 'edit':
+      return resource.editLayout ?? resource.layout;
+    case 'create':
+      return resource.createLayout ?? resource.editLayout ?? resource.layout;
+  }
+}
+
+/**
+ * 'auto' puts a field in the main column when it needs room: a custom render
+ * or input, json, image, file, tags, relation, rich text, or a string longer
+ * than 255 characters.
+ */
+export function isMainField(field: FieldDefinition, editors?: EditorRegistry): boolean {
+  if (field.render || field.input) return true;
+  switch (field.type) {
+    case 'json':
+    case 'image':
+    case 'file':
+    case 'tags':
+    case 'relation':
+      return true;
+  }
+  if (field.format === 'html' || field.format === 'markdown') return true;
+  if (editorFor(field, editors)) return true;
+  return field.type === 'string' && (field.validation?.max ?? 0) > 255;
+}
+
+/**
+ * Place the screen's fields (already filtered and in screen order) into
+ * columns. A listed field the screen does not show is skipped; a field listed
+ * twice stays in its first column; a field no column lists goes at the end of
+ * the first column. Columns left empty are dropped. Default width: the first
+ * column wide, the others narrow.
+ */
+export function resolveColumns(
+  fields: FieldDefinition[],
+  layout: ScreenLayout,
+  editors?: EditorRegistry,
+): ResolvedColumn[] {
+  const placed: Array<{ fields: FieldDefinition[]; width?: 'wide' | 'narrow' | number }> =
+    layout === 'auto' ? autoColumns(fields, editors) : explicitColumns(fields, layout.columns);
+
+  return placed
+    .filter(col => col.fields.length > 0)
+    .map((col, index) => ({ fields: col.fields, width: columnWidth(col.width, index) }));
+}
+
+function autoColumns(fields: FieldDefinition[], editors?: EditorRegistry) {
+  const main = fields.filter(f => isMainField(f, editors));
+  const side = fields.filter(f => !isMainField(f, editors));
+  return [{ fields: main }, { fields: side }];
+}
+
+function explicitColumns(fields: FieldDefinition[], columns: LayoutColumn[]) {
+  const byName = new Map(fields.map(f => [f.name, f]));
+  const used = new Set<string>();
+  // A column that lists no field is ignored, so it never becomes the first.
+  const placed = columns.filter(col => col.fields.length > 0).map(col => {
+    const picked: FieldDefinition[] = [];
+    for (const name of col.fields) {
+      const field = byName.get(name);
+      if (!field || used.has(name)) continue;
+      used.add(name);
+      picked.push(field);
+    }
+    return { fields: picked, width: col.width };
+  });
+  const unlisted = fields.filter(f => !used.has(f.name));
+  if (placed.length === 0) return [{ fields: unlisted }];
+  placed[0] = { ...placed[0], fields: [...placed[0].fields, ...unlisted] };
+  return placed;
+}
+
+function columnWidth(width: 'wide' | 'narrow' | number | undefined, index: number): 'wide' | number {
+  if (typeof width === 'number' && Number.isFinite(width) && width > 0) return width;
+  if (width === 'wide') return 'wide';
+  if (width === 'narrow') return NARROW_COLUMN_WIDTH;
+  return index === 0 ? 'wide' : NARROW_COLUMN_WIDTH;
+}

package/src/utils/row-actions.ts

@@ -19,3 +19,31 @@ export function visibleRowActions(
     return action.when.in.includes(String(value));
   });
 }
+
+/**
+ * Estimated horizontal chrome of one action Button, in px: px-4 padding on both
+ * sides (2 x 16) plus a 1px border on both sides. An estimate, not a measurement.
+ */
+const ACTION_BUTTON_CHROME = 34;
+/**
+ * Estimated average width of one character in the Button's 14px medium label,
+ * in px. Measured in a browser on Show, Edit and Delete (70.3, 59.6 and 74.7px
+ * wide), which total 220.5px with the gaps; this gives 237px.
+ */
+const ACTION_CHAR_WIDTH = 8.5;
+/** Space between action buttons (the cell's gap-2), in px. */
+const ACTION_GAP = 8;
+
+/**
+ * Estimated width, in px, of a row of action buttons, each sized from its idle
+ * label. A two-step `confirm` label is not counted: it replaces the label only
+ * after the first press, and the Actions cell wraps if it does not fit. A
+ * resource's actionsWidth overrides this estimate.
+ */
+export function estimateActionsWidth(actions: RowActionConfig[]): number {
+  const buttons = actions.reduce(
+    (sum, action) => sum + ACTION_BUTTON_CHROME + Math.ceil(ACTION_CHAR_WIDTH * action.label.length),
+    0,
+  );
+  return buttons + Math.max(0, actions.length - 1) * ACTION_GAP;
+}