@proteinjs/db-ui 1.12.1 → 1.13.0

package/src/table/RecordTable.tsx

@@ -1,7 +1,22 @@
 import React from 'react';
 import { Delete, Add } from '@mui/icons-material';
 import S from 'string';
-import { CustomRenderer, TableButton, Table as TableComponent, TableLoader, TableProps } from '@proteinjs/ui';
+import { Typography } from '@mui/material';
+import {
+  BooleanCellValue,
+  ClampedTextCellValue,
+  CustomRenderer,
+  DateCellValue,
+  DateTimeCellValue,
+  EmptyCellValue,
+  JsonSnippetCellValue,
+  StatusChipCellValue,
+  TableButton,
+  Table as TableComponent,
+  TableLoader,
+  TableProps,
+  isStatusLikeColumnName,
+} from '@proteinjs/ui';
 import {
   Column,
   QueryBuilderFactory,
@@ -15,6 +30,7 @@ import { QueryTableLoader } from './QueryTableLoader';
 import { newRecordFormLink, recordFormLink } from '../pages/RecordFormPage';
 import { recordTableLink } from '../pages/RecordTablePage';
 import { tableDisplayName } from '../tableDisplayName';
+import { ReferenceArrayCellValue, ReferenceCellValue } from './ReferenceCellValue';
 import { isInstanceOf } from '@proteinjs/util';
 import {
   IntegerColumn,
@@ -27,7 +43,6 @@ import {
   ObjectColumn,
   ArrayColumn,
 } from '@proteinjs/db';
-import moment from 'moment';
 
 type TablePropsToOmit = 'tableLoader' | 'columns';
 type SpecificTableProps<T> = Omit<TableProps<T>, TablePropsToOmit>;
@@ -78,76 +93,147 @@ function createButton<T extends Record>(table: Table<T>): TableButton<T> {
   };
 }
 
-export function RecordTable<T extends Record>(props: RecordTableProps<T>) {
-  const { ...passthrough } = props;
-  function defaultColumns() {
-    const columnProperties: (keyof T)[] = [];
-    if ((props.table.columns as any)['name']) {
-      columnProperties.push('name' as keyof T);
-    }
+/**
+ * The meaningful-data default column pick (the founder's ask — a record table should surface
+ * what a human scans for, not the schema's first columns). Deterministic tiers over the
+ * visible (non-`ui.hidden`) columns:
+ *   name → identity strings (email/title/description/…) → status-like short strings →
+ *   booleans → references (they render as linked names now) → the rest in schema order,
+ *   with long-text columns (maxLength ≥ 1000) demoted to the back.
+ * Capped at five + created/updated, exactly as before — the tiers change WHICH five.
+ */
+export function defaultRecordTableColumns<T extends Record>(table: Table<T>): (keyof T)[] {
+  function isIdentityName(name: string) {
+    // suffix match so compound names promote too (userEmail, jobTitle)
+    return name.endsWith('email') || name.endsWith('title') || ['description', 'label', 'subject'].includes(name);
+  }
 
-    for (const columnProperty of Object.keys(props.table.columns)) {
-      if (columnProperties.length >= 5) {
-        break;
+  function tier(columnPropertyName: string, column: Column<T, any>): number {
+    const name = columnPropertyName.toLowerCase();
+    if (isIdentityName(name)) {
+      return 1;
+    }
+    if (isStatusLikeColumnName(name) && isInstanceOf(column, StringColumn)) {
+      return 2;
+    }
+    if (isInstanceOf(column, BooleanColumn)) {
+      return 3;
+    }
+    if (isInstanceOf(column, ReferenceColumn)) {
+      return 4;
+    }
+    if (isInstanceOf(column, StringColumn)) {
+      const { maxLength } = column as unknown as StringColumn;
+      if (maxLength === 'MAX' || maxLength >= 1000) {
+        return 6;
       }
+    }
+    return 5;
+  }
 
-      if (columnProperty == 'name' || columnProperty == 'created' || columnProperty == 'updated') {
-        continue;
+  const candidates = Object.keys(table.columns)
+    .filter((columnPropertyName) => {
+      if (['name', 'id', 'created', 'updated'].includes(columnPropertyName)) {
+        return false;
       }
 
-      const column: Column<T, any> = (props.table.columns as any)[columnProperty];
-      if (column.options?.ui?.hidden) {
-        continue;
-      }
+      const column: Column<T, any> = (table.columns as any)[columnPropertyName];
+      return !column.options?.ui?.hidden;
+    })
+    .map((columnPropertyName, index) => ({
+      columnPropertyName,
+      index,
+      tier: tier(columnPropertyName, (table.columns as any)[columnPropertyName]),
+    }))
+    .sort((a, b) => (a.tier !== b.tier ? a.tier - b.tier : a.index - b.index));
 
-      columnProperties.push(columnProperty as keyof T);
+  const columnProperties: (keyof T)[] = [];
+  if ((table.columns as any)['name']) {
+    columnProperties.push('name' as keyof T);
+  }
+
+  for (const candidate of candidates) {
+    if (columnProperties.length >= 5) {
+      break;
     }
 
-    columnProperties.push('created');
-    columnProperties.push('updated');
+    columnProperties.push(candidate.columnPropertyName as keyof T);
+  }
 
-    return columnProperties;
+  if ((table.columns as any)['created']) {
+    columnProperties.push('created' as keyof T);
+  }
+  if ((table.columns as any)['updated']) {
+    columnProperties.push('updated' as keyof T);
   }
 
-  function getDefaultRenderer(column: Column<any, any>): CustomRenderer<T, any> {
+  return columnProperties;
+}
+
+export function RecordTable<T extends Record>(props: RecordTableProps<T>) {
+  const { ...passthrough } = props;
+  function defaultColumns() {
+    return defaultRecordTableColumns(props.table);
+  }
+
+  /**
+   * The per-COLUMN-TYPE default presentations, on the base table's shared cell grammar
+   * (@proteinjs/ui cellValues): references as linked names, booleans as check/dash, dates
+   * humanized, blobs as mono snippets, status-like strings as quiet chips. A consumer's
+   * `columnConfig.renderer` replaces any of these per column.
+   */
+  function getDefaultRenderer(column: Column<any, any>, columnPropertyName: string): CustomRenderer<T, any> {
     return (value: any) => {
+      if (value == null || value === '') {
+        return <EmptyCellValue />;
+      }
       if (isInstanceOf(column, ReferenceColumn)) {
-        return value?._id || '';
+        const { referenceTable } = column as unknown as ReferenceColumn<any>;
+        return <ReferenceCellValue tableName={value?._table || referenceTable} id={value?._id} />;
       }
       if (isInstanceOf(column, ReferenceArrayColumn)) {
-        return value?._ids?.join(', ') || '';
+        const { referenceTable } = column as unknown as ReferenceArrayColumn<any>;
+        return <ReferenceArrayCellValue tableName={value?._table || referenceTable} ids={value?._ids} />;
       }
-      if (value && typeof value === 'object') {
-        if ('_id' in value && typeof value._id === 'string') {
-          return value._id;
-        }
-        if ('_ids' in value && Array.isArray(value._ids)) {
-          return value._ids.join(', ');
-        }
+      // Reference-shaped values on columns the registry didn't type (defensive: pre-rev rows)
+      if (value && typeof value === 'object' && '_id' in value && typeof value._id === 'string') {
+        return <ReferenceCellValue tableName={value._table} id={value._id} />;
+      }
+      if (value && typeof value === 'object' && '_ids' in value && Array.isArray(value._ids)) {
+        return <ReferenceArrayCellValue tableName={value._table} ids={value._ids} />;
       }
       if (isInstanceOf(column, ObjectColumn) || isInstanceOf(column, ArrayColumn)) {
-        return JSON.stringify(value);
+        return <JsonSnippetCellValue value={value} />;
       }
       if (
         isInstanceOf(column, IntegerColumn) ||
         isInstanceOf(column, FloatColumn) ||
         isInstanceOf(column, DecimalColumn)
       ) {
-        return value != null ? value.toString() : '';
-      }
-      if (isInstanceOf(column, StringColumn)) {
-        return value != null ? String(value) : '';
+        return (
+          <Typography variant='body2' component='span' sx={{ fontVariantNumeric: 'tabular-nums' }}>
+            {value.toString()}
+          </Typography>
+        );
       }
       if (isInstanceOf(column, BooleanColumn)) {
-        return value ? '✅' : '❌';
+        return <BooleanCellValue value={value} />;
       }
       if (isInstanceOf(column, DateColumn)) {
-        return value ? moment(value).format('YYYY-MM-DD') : '';
+        return <DateCellValue value={value} />;
       }
       if (isInstanceOf(column, DateTimeColumn)) {
-        return value ? moment(value).format('YYYY-MM-DD HH:mm:ss') : '';
+        return <DateTimeCellValue value={value} />;
+      }
+      if (isInstanceOf(column, StringColumn)) {
+        const text = String(value);
+        // Status-like short values scan as chips; anything longer stays clamped text.
+        if (isStatusLikeColumnName(columnPropertyName) && text.length <= 24) {
+          return <StatusChipCellValue value={text} />;
+        }
+        return <ClampedTextCellValue>{text}</ClampedTextCellValue>;
       }
-      return value != null ? value.toString() : '';
+      return <ClampedTextCellValue>{value.toString()}</ClampedTextCellValue>;
     };
   }
 
@@ -157,20 +243,39 @@ export function RecordTable<T extends Record>(props: RecordTableProps<T>) {
 
     for (const columnName of columns) {
       const column = (props.table.columns as any)[columnName];
+      const isNumeric =
+        isInstanceOf(column, IntegerColumn) || isInstanceOf(column, FloatColumn) || isInstanceOf(column, DecimalColumn);
+      // Plain strings ride the base Table's own default path (body2 + three-line clamp, quiet
+      // dash for empties, and the phone card's identity emphasis + empty-field omission) —
+      // a renderer here would just re-implement that and lose the card behaviors.
+      const isPlainString =
+        isInstanceOf(column, StringColumn) &&
+        !isStatusLikeColumnName(columnName as string) &&
+        !isInstanceOf(column, ReferenceColumn) &&
+        !isInstanceOf(column, ObjectColumn) &&
+        !isInstanceOf(column, DateColumn) &&
+        !isInstanceOf(column, DateTimeColumn);
+      if (isPlainString) {
+        continue;
+      }
+
       defaultConfig[columnName] = {
-        renderer: getDefaultRenderer(column),
+        renderer: getDefaultRenderer(column, columnName as string),
+        // The type renderers are value-driven: an empty value means an empty card field.
+        omitEmptyOnCard: true,
+        // Numbers right-align (they compare by magnitude); a consumer's cellProps replaces this.
+        ...(isNumeric ? { cellProps: { align: 'right' as const } } : {}),
       };
     }
 
-    // Merge with provided columnConfig, if any
+    // Merge with provided columnConfig, if any — including columns with no default entry
+    // (plain strings ride the base default, but a consumer's config must still land).
     if (props.columnConfig) {
       for (const columnName in props.columnConfig) {
-        if (defaultConfig[columnName]) {
-          defaultConfig[columnName] = {
-            ...defaultConfig[columnName],
-            ...props.columnConfig[columnName],
-          };
-        }
+        defaultConfig[columnName] = {
+          ...defaultConfig[columnName],
+          ...props.columnConfig[columnName],
+        };
       }
     }
 

package/src/table/ReferenceCellValue.tsx

@@ -0,0 +1,133 @@
+import React, { useEffect, useState } from 'react';
+import { Link, Typography } from '@mui/material';
+import { useNavigate } from 'react-router-dom';
+import { EmptyCellValue } from '@proteinjs/ui';
+import { Record, Reference } from '@proteinjs/db';
+import { recordFormLink } from '../pages/RecordFormPage';
+
+/**
+ * A reference rendered as the referenced record's NAME, linked to its record form — an admin
+ * scanning a table reads who/what, not a uuid. Resolution rides `Reference.get()` (the
+ * ReferenceCache-backed house path) and lands in a module cache so a page of rows resolves
+ * each distinct target once and re-renders never flicker. Until the name arrives — and for
+ * records without a usable `name` (or ones this session can't read) — the cell shows the
+ * short id in mono: truthful immediately, enriched when the name lands.
+ */
+
+/** `${table}:${id}` → display name (null: resolved, but no name to show). */
+const resolvedNames = new Map<string, string | null>();
+const inflight = new Map<string, Promise<string | null>>();
+
+function resolveDisplayName(tableName: string, id: string): Promise<string | null> {
+  const key = `${tableName}:${id}`;
+  const settled = resolvedNames.get(key);
+  if (settled !== undefined) {
+    return Promise.resolve(settled);
+  }
+
+  let pending = inflight.get(key);
+  if (!pending) {
+    pending = (async () => {
+      try {
+        const record = (await new Reference<Record>(tableName, id).get()) as any;
+        const name = record && typeof record.name === 'string' && record.name.trim() ? (record.name as string) : null;
+        resolvedNames.set(key, name);
+        return name;
+      } catch {
+        // Unreadable target (row gone, or not visible to this session): the short id stands.
+        resolvedNames.set(key, null);
+        return null;
+      } finally {
+        inflight.delete(key);
+      }
+    })();
+    inflight.set(key, pending);
+  }
+
+  return pending;
+}
+
+/** Test seam: a resolved-name cache survives unmounts by design; suites reset it between cases. */
+export function clearReferenceNameCache() {
+  resolvedNames.clear();
+  inflight.clear();
+}
+
+export const shortReferenceId = (id: string) => (id.length > 8 ? id.slice(0, 8) : id);
+
+export function ReferenceCellValue({ tableName, id }: { tableName?: string; id?: string | null }) {
+  const navigate = useNavigate();
+  const [name, setName] = useState<string | null>(() =>
+    tableName && id ? resolvedNames.get(`${tableName}:${id}`) ?? null : null
+  );
+
+  useEffect(() => {
+    if (!tableName || !id) {
+      return;
+    }
+
+    let cancelled = false;
+    resolveDisplayName(tableName, id).then((resolved) => {
+      if (!cancelled) {
+        setName(resolved);
+      }
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [tableName, id]);
+
+  if (!tableName || !id) {
+    return <EmptyCellValue />;
+  }
+
+  // recordFormLink already leads with '/' — no extra prefix (a '//'-prefixed href reads as
+  // a protocol-relative URL and breaks navigation).
+  const url = recordFormLink(tableName, id);
+  return (
+    <Link
+      href={url}
+      underline='hover'
+      onClick={(event) => {
+        // The row's own click navigates to the HOST record; this link goes to the TARGET.
+        event.stopPropagation();
+        event.preventDefault();
+        navigate(url);
+      }}
+      sx={{ whiteSpace: 'nowrap' }}
+    >
+      {name !== null ? (
+        <Typography variant='body2' component='span'>
+          {name}
+        </Typography>
+      ) : (
+        <Typography
+          variant='body2'
+          component='span'
+          title={id}
+          sx={{ fontFamily: 'ui-monospace, Menlo, monospace', fontSize: '0.8125rem' }}
+        >
+          {shortReferenceId(id)}
+        </Typography>
+      )}
+    </Link>
+  );
+}
+
+/** A reference array: each target renders through the single-reference presentation. */
+export function ReferenceArrayCellValue({ tableName, ids }: { tableName?: string; ids?: string[] | null }) {
+  if (!tableName || !ids || ids.length === 0) {
+    return <EmptyCellValue />;
+  }
+
+  return (
+    <Typography variant='body2' component='span' sx={{ overflowWrap: 'anywhere' }}>
+      {ids.map((id, index) => (
+        <React.Fragment key={id}>
+          {index > 0 && ', '}
+          <ReferenceCellValue tableName={tableName} id={id} />
+        </React.Fragment>
+      ))}
+    </Typography>
+  );
+}

package/test/recordFormStructuredFields.test.tsx

@@ -0,0 +1,169 @@
+/**
+ * @jest-environment jsdom
+ *
+ * RecordForm's long-text and structured-value fields (the admin-surface polish rev).
+ * Contracts as OUTCOMES:
+ *  1. Long-text columns (maxLength > 255) render as multiline textareas — a single-line
+ *     input truncates exactly what the form exists to show.
+ *  2. Object columns present pretty-printed JSON in a multiline field and the SAVE payload
+ *     carries the parsed OBJECT (round trip), never the display string.
+ *  3. Invalid JSON refuses the save with a message naming the field — the service update
+ *     never runs.
+ *  4. Readonly timestamps display compact ('MMM D, YYYY, h:mm A') with the relative read as
+ *     the field's helper line.
+ */
+import React from 'react';
+import moment from 'moment';
+import { createRoot, Root } from 'react-dom/client';
+import { act } from 'react-dom/test-utils';
+import { MemoryRouter } from 'react-router-dom';
+import { ObjectColumn, Record, StringColumn, Table, withRecordColumns } from '@proteinjs/db';
+import '../generated';
+import { RecordForm } from '../src/form/RecordForm';
+
+const mockDbService: { get: jest.Mock; insert: jest.Mock; update: jest.Mock; delete: jest.Mock } = {
+  get: jest.fn(),
+  insert: jest.fn(async (table: any, record: any) => record),
+  update: jest.fn(async (table: any, record: any) => record),
+  delete: jest.fn(async () => 1),
+};
+
+jest.mock('@proteinjs/db', () => ({
+  ...jest.requireActual('@proteinjs/db'),
+  getDbService: () => mockDbService,
+}));
+
+declare global {
+  // eslint-disable-next-line no-var
+  var IS_REACT_ACT_ENVIRONMENT: boolean;
+}
+globalThis.IS_REACT_ACT_ENVIRONMENT = true;
+
+interface Job extends Record {
+  title: string;
+  description: string;
+  payload: { retries: number } | null;
+}
+
+class JobTable extends Table<Job> {
+  public name = 'admin_test_job';
+  public columns = withRecordColumns<Job>({
+    title: new StringColumn('title'),
+    description: new StringColumn('description', {}, 4000),
+    payload: new ObjectColumn('payload', { ui: { hidden: false } }),
+  });
+}
+
+const created = moment('2026-01-02T03:04:05.000Z');
+const updated = moment('2026-02-03T04:05:06.000Z');
+
+function loadedRecord(): Job {
+  return {
+    id: 'job-1',
+    title: 'Nightly export',
+    description: 'A very long description of what the job does.',
+    payload: { retries: 3 },
+    created,
+    updated,
+  } as Job;
+}
+
+describe('RecordForm structured fields', () => {
+  let container: HTMLDivElement;
+  let root: Root;
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+    container = document.createElement('div');
+    document.body.appendChild(container);
+    root = createRoot(container);
+  });
+
+  afterEach(() => {
+    act(() => root.unmount());
+    container.remove();
+  });
+
+  const mount = async (record?: Job) => {
+    await act(async () => {
+      root.render(
+        <MemoryRouter>
+          <RecordForm table={new JobTable()} record={record} />
+        </MemoryRouter>
+      );
+    });
+    await act(async () => {
+      await new Promise((resolve) => setTimeout(resolve, 0));
+    });
+  };
+
+  const controlByLabel = (label: string): HTMLInputElement | HTMLTextAreaElement => {
+    const labels = Array.from(document.body.querySelectorAll('label'));
+    const match = labels.find((candidate) => candidate.textContent?.startsWith(label));
+    if (!match) {
+      throw new Error(`no field labeled ${label}`);
+    }
+    const control = document.getElementById(match.htmlFor) as HTMLInputElement | HTMLTextAreaElement;
+    if (!control) {
+      throw new Error(`no control for label ${label}`);
+    }
+    return control;
+  };
+
+  const setValue = async (control: HTMLInputElement | HTMLTextAreaElement, value: string) => {
+    const proto = control instanceof HTMLTextAreaElement ? HTMLTextAreaElement.prototype : HTMLInputElement.prototype;
+    const setter = Object.getOwnPropertyDescriptor(proto, 'value')!.set!;
+    await act(async () => {
+      setter.call(control, value);
+      control.dispatchEvent(new Event('input', { bubbles: true }));
+    });
+  };
+
+  const clickButton = async (name: string) => {
+    const button = Array.from(document.body.querySelectorAll('button')).find(
+      (candidate) => candidate.textContent === name
+    )!;
+    await act(async () => {
+      button.dispatchEvent(new MouseEvent('click', { bubbles: true }));
+    });
+    await act(async () => {
+      await new Promise((resolve) => setTimeout(resolve, 0));
+    });
+  };
+
+  it('long-text columns render as multiline textareas; short ones stay single-line inputs', async () => {
+    await mount(loadedRecord());
+    expect(controlByLabel('Title').tagName).toBe('INPUT');
+    expect(controlByLabel('Description').tagName).toBe('TEXTAREA');
+  });
+
+  it('object columns present pretty JSON and save the parsed object (round trip)', async () => {
+    await mount(loadedRecord());
+    const payloadControl = controlByLabel('Payload');
+    expect(payloadControl.tagName).toBe('TEXTAREA');
+    expect(payloadControl.value).toBe(JSON.stringify({ retries: 3 }, null, 2));
+
+    await setValue(payloadControl, '{\n  "retries": 5\n}');
+    await clickButton('Save');
+
+    expect(mockDbService.update).toHaveBeenCalledTimes(1);
+    const payloadSent = mockDbService.update.mock.calls[0][1].payload;
+    expect(payloadSent).toEqual({ retries: 5 });
+  });
+
+  it('invalid JSON refuses the save with a message naming the field; the update never runs', async () => {
+    await mount(loadedRecord());
+    await setValue(controlByLabel('Payload'), '{not json');
+    await clickButton('Save');
+
+    expect(mockDbService.update).not.toHaveBeenCalled();
+    expect(document.body.textContent).toContain('Payload must be valid JSON');
+  });
+
+  it('readonly timestamps display compact with the relative read as the helper line', async () => {
+    await mount(loadedRecord());
+    const createdControl = controlByLabel('Created') as HTMLInputElement;
+    expect(createdControl.value).toBe(created.format('MMM D, YYYY, h:mm A'));
+    expect(document.body.textContent).toContain(created.fromNow());
+  });
+});