@proteinjs/db-ui 1.9.4 → 1.10.1

package/src/form/RecordForm.tsx

@@ -2,12 +2,13 @@ import React from 'react';
 import S from 'string';
 import moment from 'moment';
 import { StringUtil, isInstanceOf } from '@proteinjs/util';
-import { Form, Fields, textField, FormButtons } from '@proteinjs/ui';
+import { Form, Fields, textField, checkboxField, dateField, FormButtons } from '@proteinjs/ui';
 import {
   Table,
   Record,
   Column,
   getDbService,
+  DateColumn,
   DateTimeColumn,
   BooleanColumn,
   Reference,
@@ -77,6 +78,15 @@ function parseReferenceIds(value: unknown): string[] {
     .filter(Boolean);
 }
 
+/** Parse a native date/datetime-local input value ('YYYY-MM-DD' / 'YYYY-MM-DDTHH:mm'). */
+function parseDateInputValue(value: unknown): moment.Moment | null {
+  if (typeof value !== 'string' || !value.trim()) {
+    return null;
+  }
+
+  return moment(value);
+}
+
 function parseBooleanValue(value: unknown): boolean | null {
   if (typeof value === 'boolean') {
     return value;
@@ -157,17 +167,81 @@ export function RecordForm<T extends Record>({ table, record }: RecordFormProps<
   function createFields(): () => Fields {
     return () => {
       const fields: Fields = {};
-      for (const columnPropertyName in getColumns()) {
-        fields[columnPropertyName] = textField({
-          name: columnPropertyName,
-          label: StringUtil.humanizeCamel(columnPropertyName),
-        });
+      const columns = getColumns();
+      for (const columnPropertyName in columns) {
+        fields[columnPropertyName] = createField(columnPropertyName, columns[columnPropertyName]);
       }
 
       return fields;
     };
   }
 
+  /**
+   * Server-managed columns (`id`/`created`/`updated`) and stored timestamps (`DateTimeColumn`)
+   * are readonly on existing records; readonly was previously applied in `onLoad`, which made
+   * field-control selection impossible at creation time — it lives here now so each column type
+   * can pick its control up front.
+   */
+  function isReadonlyField(columnPropertyName: string, column: Column<T, any>) {
+    return (
+      !isNewRecord &&
+      (columnPropertyName == 'id' ||
+        columnPropertyName == 'created' ||
+        columnPropertyName == 'updated' ||
+        isInstanceOf(column, DateTimeColumn))
+    );
+  }
+
+  /** Pick the field control that tells the truth about the column's type. */
+  function createField(columnPropertyName: string, column: Column<T, any>) {
+    const name = columnPropertyName;
+    const label = StringUtil.humanizeCamel(columnPropertyName);
+
+    // Readonly values render as text (a native date input isn't text-selectable): copyable
+    // ids/timestamps beat a type-specific control the user can't interact with anyway.
+    if (isReadonlyField(columnPropertyName, column)) {
+      return textField({ name, label, accessibility: { readonly: true } });
+    }
+
+    if (isInstanceOf(column, BooleanColumn)) {
+      return checkboxField({ name, label });
+    }
+
+    if (isInstanceOf(column, DateColumn)) {
+      return dateField({ name, label });
+    }
+
+    // Only reachable on new-record forms; on existing records DateTimeColumns are readonly.
+    if (isInstanceOf(column, DateTimeColumn)) {
+      return dateField({ name, label, includeTime: true });
+    }
+
+    if (isInstanceOf(column, ReferenceColumn)) {
+      const { referenceTable } = column as unknown as ReferenceColumn<any>;
+      return textField({
+        name,
+        label,
+        description: `${referenceTable} record id`,
+        onChange: async (value, fields, setFieldStatus) => {
+          if (typeof value === 'string' && value.includes(',')) {
+            setFieldStatus(`Enter a single ${referenceTable} record id`, true);
+          }
+        },
+      });
+    }
+
+    if (isInstanceOf(column, ReferenceArrayColumn)) {
+      const { referenceTable } = column as unknown as ReferenceArrayColumn<any>;
+      return textField({
+        name,
+        label,
+        description: `Comma-separated ${referenceTable} record ids`,
+      });
+    }
+
+    return textField({ name, label });
+  }
+
   function fieldLayout(): any {
     const columns = getColumns();
     const layoutColumns = Object.entries(columns).length > 6 ? 2 : 1;
@@ -213,6 +287,14 @@ export function RecordForm<T extends Record>({ table, record }: RecordFormProps<
       return parseBooleanValue(fieldValue);
     }
 
+    if (isInstanceOf(column, DateColumn)) {
+      return parseDateInputValue(fieldValue)?.toDate() ?? null;
+    }
+
+    if (isInstanceOf(column, DateTimeColumn)) {
+      return parseDateInputValue(fieldValue);
+    }
+
     return fieldValue;
   }
 
@@ -228,6 +310,11 @@ export function RecordForm<T extends Record>({ table, record }: RecordFormProps<
           color: 'primary',
           variant: 'text',
         },
+        confirm: (fields: Fields) => ({
+          title: `Delete ${S(table.name).humanize().s}?`,
+          message: 'This permanently deletes the record.',
+          confirmButtonText: 'Delete',
+        }),
         redirect: async (fields: Fields, buttons: FormButtons<Fields>) => {
           return { path: recordTableLink(table) };
         },
@@ -258,6 +345,13 @@ export function RecordForm<T extends Record>({ table, record }: RecordFormProps<
           }
 
           for (const columnPropertyName in fields) {
+            // Readonly fields are display-only; their values are formatted strings. The loaded
+            // record already holds the real values (id keys the update; created/updated stay
+            // moments — writing the display string back serialized `created` to null on save).
+            if (isReadonlyField(columnPropertyName, getColumn(columnPropertyName))) {
+              continue;
+            }
+
             const field = fields[columnPropertyName];
             (record as any)[columnPropertyName] = getFieldValue(columnPropertyName, field.field.value);
           }
@@ -308,29 +402,22 @@ export function RecordForm<T extends Record>({ table, record }: RecordFormProps<
       const field = fields[columnPropertyName].field;
       let fieldValue = (record as any)[columnPropertyName];
 
-      if (moment.isMoment(fieldValue)) {
-        fieldValue = fieldValue.format('ddd, MMM Do YY, h:mm:ss a');
-      } else if (isReferenceValue(fieldValue)) {
+      if (isReferenceValue(fieldValue)) {
         fieldValue = fieldValue._id || '';
       } else if (isReferenceArrayValue(fieldValue)) {
         fieldValue = fieldValue._ids.join(', ');
       } else if (isInstanceOf(column, BooleanColumn)) {
-        fieldValue = fieldValue == true ? 'True' : 'False';
+        // The checkbox control takes a real boolean, not a 'True'/'False' display string
+        fieldValue = fieldValue == true;
+      } else if (isInstanceOf(column, DateColumn) && fieldValue) {
+        // The native date input takes its own value format
+        fieldValue = moment(fieldValue).format('YYYY-MM-DD');
+      } else if (moment.isMoment(fieldValue)) {
+        // Readonly timestamps (created/updated/DateTimeColumn) display human-formatted, copyable
+        fieldValue = fieldValue.format('ddd, MMM Do YY, h:mm:ss a');
       }
 
       field.value = fieldValue;
-      if (
-        columnPropertyName == 'created' ||
-        columnPropertyName == 'updated' ||
-        columnPropertyName == 'id' ||
-        isInstanceOf(column, DateTimeColumn)
-      ) {
-        if (!field.accessibility) {
-          field.accessibility = {};
-        }
-
-        field.accessibility.readonly = true;
-      }
     }
   }
 }

package/src/form/customizations/MigrationRecordFormCustomization.tsx

@@ -1,5 +1,5 @@
 import { Fields, FormButtons } from '@proteinjs/ui';
-import { Migration, getMigrationRunnerService, tables } from '@proteinjs/db';
+import { Migration, getDbService, getMigrationRunnerService, tables } from '@proteinjs/db';
 import { RecordFormCustomization } from '../RecordFormCustomization';
 
 export class MigrationRecordFormCustomization extends RecordFormCustomization {
@@ -26,6 +26,58 @@ export class MigrationRecordFormCustomization extends RecordFormCustomization {
         return `Starting migration`;
       },
     };
+    // Retire/Un-retire: the deploy-gated series stamps `retired` on rows whose source class no
+    // longer ships, and a retired row is never auto-run again until un-retired here. The Form
+    // renders button labels statically, so the toggle is a mutually-exclusive button pair whose
+    // visibility flips in place after each write.
+    formButtons['retire'] = {
+      name: 'Retire',
+      accessibility: {
+        hidden: !migration || migration.retired === true,
+      },
+      style: {
+        color: 'primary',
+        variant: 'text',
+      },
+      onClick: async (fields: Fields, buttons: FormButtons<Fields>) => {
+        await this.setRetired(migration, true, fields, formButtons);
+        return `Migration retired — the deploy series will not auto-run it`;
+      },
+      progressMessage: (fields: Fields) => {
+        return `Retiring migration`;
+      },
+    };
+    formButtons['unretire'] = {
+      name: 'Un-retire',
+      accessibility: {
+        hidden: !migration || migration.retired !== true,
+      },
+      style: {
+        color: 'primary',
+        variant: 'text',
+      },
+      onClick: async (fields: Fields, buttons: FormButtons<Fields>) => {
+        await this.setRetired(migration, false, fields, formButtons);
+        return `Migration un-retired — the deploy series can auto-run it again`;
+      },
+      progressMessage: (fields: Fields) => {
+        return `Un-retiring migration`;
+      },
+    };
     return formButtons;
   }
+
+  /**
+   * Partial write + in-place view reconcile: the flag flips on the row, the loaded record, the
+   * rendered field, and the button pair — no whole-record save, no stale intermediate state.
+   */
+  private async setRetired(migration: Migration, retired: boolean, fields: Fields, formButtons: FormButtons<any>) {
+    await getDbService().update(this.table, { id: migration.id, retired } as Partial<Migration>);
+    migration.retired = retired;
+    if (fields['retired']) {
+      fields['retired'].field.value = retired ? 'True' : 'False';
+    }
+    formButtons['retire'].accessibility = { hidden: retired };
+    formButtons['unretire'].accessibility = { hidden: !retired };
+  }
 }

package/src/table/RecordTable.tsx

@@ -14,6 +14,7 @@ import {
 import { QueryTableLoader } from './QueryTableLoader';
 import { newRecordFormLink, recordFormLink } from '../pages/RecordFormPage';
 import { recordTableLink } from '../pages/RecordTablePage';
+import { tableDisplayName } from '../tableDisplayName';
 import { isInstanceOf } from '@proteinjs/util';
 import {
   IntegerColumn,
@@ -46,6 +47,13 @@ function deleteButton<T extends Record>(table: Table<T>): TableButton<T> {
       showWhenRowsSelected: true,
       showWhenNoRowsSelected: false,
     },
+    confirm: (selectedRows) => ({
+      title: `Delete ${selectedRows.length} ${selectedRows.length == 1 ? 'row' : 'rows'}?`,
+      message: `This permanently deletes ${
+        selectedRows.length == 1 ? 'the selected row' : 'the selected rows'
+      } from ${tableDisplayName(table)}.`,
+      confirmButtonText: 'Delete',
+    }),
     onClick: async (selectedRows, navigate) => {
       const qb = new QueryBuilderFactory()
         .getQueryBuilder(table)
@@ -191,7 +199,7 @@ export function RecordTable<T extends Record>(props: RecordTableProps<T>) {
 
   return (
     <TableComponent
-      title={props.title ? props.title : `${S(props.table.name).humanize().toString()} Table`}
+      title={props.title ? props.title : tableDisplayName(props.table)}
       columns={props.columns ? props.columns : defaultColumns()}
       columnConfig={mergeColumnConfigs()}
       tableLoader={props.tableLoader ? props.tableLoader : defaultTableLoader()}

package/src/tableDisplayName.ts

@@ -0,0 +1,28 @@
+import S from 'string';
+import { Table } from '@proteinjs/db';
+
+/**
+ * Human title for a table's record collection: the humanized table name with its last word
+ * pluralized — 'user' → 'Users', 'access_grant' → 'Access grants'. `Table` carries no display
+ * metadata, so the name is derived; the pluralization is deliberately boring (s/es/ies) and
+ * predictable rather than a full inflection library.
+ */
+export function tableDisplayName(table: Table<any>): string {
+  const humanized = S(table.name).humanize().s;
+  const words = humanized.split(' ');
+  words[words.length - 1] = pluralize(words[words.length - 1]);
+  return words.join(' ');
+}
+
+function pluralize(word: string): string {
+  const lower = word.toLowerCase();
+  if (/(s|x|z|ch|sh)$/.test(lower)) {
+    return `${word}es`;
+  }
+
+  if (/[^aeiou]y$/.test(lower)) {
+    return `${word.slice(0, -1)}ies`;
+  }
+
+  return `${word}s`;
+}

package/test/recordFormInteractions.test.tsx

@@ -0,0 +1,259 @@
+/**
+ * @jest-environment jsdom
+ *
+ * RecordForm functional gaps (task #53 part 2):
+ *  - item 2: Delete routes through the confirmation dialog — the service delete only runs after
+ *    the user confirms (the immediate-delete repro), and cancel is a no-op.
+ *  - item 3: readonly fields (id/created/updated) are readOnly, not disabled — copyable.
+ *  - item 7: field controls tell the truth about column types — booleans render as checkboxes,
+ *    dates as native date inputs, reference columns say what they expect ('comma-separated ids').
+ *  - save-path truth: the update payload carries real values — a boolean stays a boolean, a
+ *    DateColumn becomes a Date — and readonly display strings are never written back into the
+ *    record (pre-fix, `created` round-tripped through its display string, which
+ *    DateTimeColumn.serialize turns into null on every save).
+ */
+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 {
+  BooleanColumn,
+  DateColumn,
+  DateTimeColumn,
+  Record,
+  Reference,
+  ReferenceArray,
+  ReferenceArrayColumn,
+  ReferenceColumn,
+  StringColumn,
+  Table,
+  withRecordColumns,
+} from '@proteinjs/db';
+// Load the package's reflection source graph: RecordForm resolves RecordFormCustomizations
+// through SourceRepository, which only knows the type once the generated index has merged it.
+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 Task extends Record {
+  title: string;
+  active: boolean | null;
+  dueDate: Date;
+  archivedAt: moment.Moment | null;
+  owner: Reference<any>;
+  tags: ReferenceArray<any>;
+}
+
+class TaskTable extends Table<Task> {
+  public name = 'admin_test_task';
+  public columns = withRecordColumns<Task>({
+    title: new StringColumn('title'),
+    active: new BooleanColumn('active'),
+    dueDate: new DateColumn('due_date'),
+    archivedAt: new DateTimeColumn('archived_at'),
+    owner: new ReferenceColumn('owner', 'user', false),
+    // ObjectColumn descendants (incl. ReferenceArrayColumn) are ui.hidden by default; surface it
+    tags: new ReferenceArrayColumn('tags', 'tag', false, { ui: { hidden: false } }),
+  });
+}
+
+const created = moment('2026-01-02T03:04:05.000Z');
+const updated = moment('2026-02-03T04:05:06.000Z');
+const archivedAt = moment('2026-03-04T05:06:07.000Z');
+
+function loadedRecord(): Task {
+  return {
+    id: 'task-1',
+    title: 'Write tests',
+    active: true,
+    dueDate: moment('2026-08-10', 'YYYY-MM-DD').toDate(),
+    archivedAt,
+    owner: new Reference('user', 'user-9'),
+    tags: new ReferenceArray('tag', ['tag-1', 'tag-2']),
+    created,
+    updated,
+  } as Task;
+}
+
+describe('RecordForm', () => {
+  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?: Task) => {
+    await act(async () => {
+      root.render(
+        <MemoryRouter>
+          <RecordForm table={new TaskTable()} record={record} />
+        </MemoryRouter>
+      );
+    });
+    // Let Form.onLoad (async componentDidMount work) settle
+    await act(async () => {
+      await Promise.resolve();
+    });
+  };
+
+  const findButton = (name: string) => {
+    const button = Array.from(document.querySelectorAll('button')).find((b) => b.textContent === name);
+    if (!button) {
+      throw new Error(`Button not rendered: ${name}`);
+    }
+
+    return button;
+  };
+
+  const click = async (element: Element) => {
+    await act(async () => {
+      element.dispatchEvent(new MouseEvent('click', { bubbles: true }));
+    });
+  };
+
+  const inputByLabel = (labelText: string) => {
+    const label = Array.from(document.querySelectorAll('label')).find((l) => l.textContent?.startsWith(labelText));
+    if (!label) {
+      throw new Error(`No field labeled: ${labelText}`);
+    }
+
+    const control = label.getAttribute('for')
+      ? document.getElementById(label.getAttribute('for')!)
+      : label.parentElement?.querySelector('input');
+    if (!control) {
+      throw new Error(`No input for label: ${labelText}`);
+    }
+
+    return control as HTMLInputElement;
+  };
+
+  const dialog = () => document.querySelector('[role="dialog"]');
+
+  describe('type-truthful field controls (item 7)', () => {
+    it('renders booleans as a checked checkbox, dates as a native date input, and readonly timestamps as copyable text', async () => {
+      await mount(loadedRecord());
+
+      const active = inputByLabel('Active');
+      expect(active.type).toBe('checkbox');
+      expect(active.checked).toBe(true);
+
+      const dueDate = inputByLabel('Due date');
+      expect(dueDate.type).toBe('date');
+      expect(dueDate.value).toBe('2026-08-10');
+
+      // Readonly fields render as text, readOnly-not-disabled (item 3): copyable
+      // (`id` itself is ui.hidden at the column layer and never renders)
+      for (const labelText of ['Created', 'Updated', 'Archived at']) {
+        const input = inputByLabel(labelText);
+        expect(input.type).toBe('text');
+        expect(input.readOnly).toBe(true);
+        expect(input.disabled).toBe(false);
+      }
+    });
+
+    it('stops pretending on reference columns: helper text names the expected ids', async () => {
+      await mount(loadedRecord());
+
+      expect(document.body.textContent).toContain('user record id');
+      expect(document.body.textContent).toContain('Comma-separated tag record ids');
+      expect(inputByLabel('Owner').value).toBe('user-9');
+      expect(inputByLabel('Tags').value).toBe('tag-1, tag-2');
+    });
+
+    it('renders a datetime-local input for editable DateTimeColumns on new records', async () => {
+      await mount(undefined);
+
+      expect(inputByLabel('Archived at').type).toBe('datetime-local');
+      expect(inputByLabel('Active').type).toBe('checkbox');
+      expect(inputByLabel('Active').checked).toBe(false);
+    });
+  });
+
+  describe('delete confirmation (item 2)', () => {
+    it('does not delete on click; the service call runs only after the dialog confirms', async () => {
+      await mount(loadedRecord());
+
+      await click(findButton('Delete'));
+      expect(mockDbService.delete).not.toHaveBeenCalled();
+      expect(dialog()).not.toBeNull();
+      expect(dialog()!.textContent).toContain('Delete Admin test task?');
+
+      const confirm = Array.from(dialog()!.querySelectorAll('button')).find((b) => b.textContent === 'Delete')!;
+      await click(confirm);
+
+      expect(mockDbService.delete).toHaveBeenCalledTimes(1);
+      expect(mockDbService.delete.mock.calls[0][1]).toEqual({ id: 'task-1' });
+    });
+
+    it('cancel is a no-op', async () => {
+      await mount(loadedRecord());
+
+      await click(findButton('Delete'));
+      const cancel = Array.from(dialog()!.querySelectorAll('button')).find((b) => b.textContent === 'Cancel')!;
+      await click(cancel);
+
+      expect(mockDbService.delete).not.toHaveBeenCalled();
+      expect(dialog()).toBeNull();
+    });
+  });
+
+  describe('save-path truth', () => {
+    it('sends real values: booleans stay booleans, dates become Dates, and readonly fields never round-trip through display strings', async () => {
+      await mount(loadedRecord());
+
+      await click(findButton('Save'));
+
+      expect(mockDbService.update).toHaveBeenCalledTimes(1);
+      const payload = mockDbService.update.mock.calls[0][1];
+      expect(payload.active).toBe(true);
+      expect(payload.dueDate).toBeInstanceOf(Date);
+      expect(moment(payload.dueDate).format('YYYY-MM-DD')).toBe('2026-08-10');
+      // Pre-fix, these were the human display strings ('Fri, Jan 2nd 26, ...'); `created` then
+      // serialized to null on every save. They must remain the loaded moments.
+      expect(moment.isMoment(payload.created)).toBe(true);
+      expect(payload.created.valueOf()).toBe(created.valueOf());
+      expect(moment.isMoment(payload.archivedAt)).toBe(true);
+      expect(payload.archivedAt.valueOf()).toBe(archivedAt.valueOf());
+      expect(payload.id).toBe('task-1');
+    });
+
+    it('an unchecked checkbox saves boolean false, not a string', async () => {
+      await mount(loadedRecord());
+
+      await click(inputByLabel('Active'));
+      await click(findButton('Save'));
+
+      const payload = mockDbService.update.mock.calls[0][1];
+      expect(payload.active).toBe(false);
+    });
+  });
+});