@cratis/scene.blueprint.default 4.38.0 → 4.40.0

package/foundation/foundationDescriptors.ts

@@ -7,6 +7,8 @@ import { ComponentName } from '../ComponentName';
 import { defaultBlueprintName } from '../packageName';
 import { ActivityKind } from './activityModel';
 import { ApprovalState } from './approvalModel';
+import { CellKind, ListVariant } from './listModel';
+import { FormFieldType, FormMode } from './formModel';
 import { ChartKind } from './chartGeometry';
 import { ComponentState } from './ComponentState';
 import { FilterFieldType } from './filterModel';
@@ -353,5 +355,198 @@ export const foundationDescriptors: ComponentDescriptor[] = [
             ...standardStateProperties,
         ],
     },
+    {
+        component: key(ComponentName.DataList),
+        displayName: 'Data list',
+        description: 'The records of a collection as a table, as cards or grouped with subtotals, with search, sort, paging and selection that live in the address. On a phone a table becomes cards.',
+        properties: [
+            { path: 'rows', label: 'Rows', group: 'Data', valueType: PropertyValueType.Json, acceptedBindingKinds: bindable, default: [], description: 'The records; bind to a query result.' },
+            {
+                ...list('columns', 'Columns', 'Data', 'Column', [
+                    text('field', 'Field', 'Data', 'The result field the column shows.', { constraints: { required: true }, editorKind: PropertyEditorKind.Field }),
+                    text('header', 'Header', 'Content'),
+                    choice('kind', 'Kind', 'Appearance', { [CellKind.Text]: 'Text', [CellKind.Number]: 'Number', [CellKind.Currency]: 'Currency', [CellKind.Date]: 'Date', [CellKind.Status]: 'Status' }, CellKind.Text),
+                    flag('sortable', 'Sortable', 'Behavior', undefined, { default: true }),
+                    text('currency', 'Currency', 'Appearance'),
+                    { path: 'tones', label: 'Status tones', group: 'Appearance', valueType: PropertyValueType.Object, editorKind: PropertyEditorKind.StringMap, description: 'The tone (success, warning, danger, info, neutral) of each status value.' },
+                ], 'What is shown.'),
+                acceptedBindingKinds: bindable,
+            },
+            choice('variant', 'Layout', 'Appearance', { [ListVariant.Table]: 'Table', [ListVariant.Cards]: 'Cards', [ListVariant.Grouped]: 'Grouped' }, ListVariant.Table),
+            flag('collapse', 'Cards on a phone', 'Appearance', 'A table becomes cards on a phone-wide screen; nothing is hidden.', { default: true }),
+            text('idField', 'Id field', 'Data', undefined, { default: 'id', editorKind: PropertyEditorKind.Field }),
+            text('titleField', 'Title field', 'Data', 'The field that names a row for assistive technology and a card.', { editorKind: PropertyEditorKind.Field }),
+            text('groupBy', 'Group by', 'Data', undefined, { editorKind: PropertyEditorKind.Field }),
+            text('totalField', 'Subtotal field', 'Data', undefined, { editorKind: PropertyEditorKind.Field }),
+            number('pageSize', 'Rows per page', 'Behavior', '0 shows every row.', { default: 0, constraints: { minimum: 0, integer: true } }),
+            choice('selectionMode', 'Selection', 'Behavior', { none: 'None', single: 'One row', multiple: 'Many rows' }, 'none'),
+            { path: 'rowActions', label: 'Row actions', group: 'Behavior', valueType: PropertyValueType.Json, editorKind: PropertyEditorKind.StringList, default: [], description: 'The actions in each row\'s menu; each is the action output.' },
+            rule('actionPermission', 'Row action permission', 'Whether row actions work, refuse with a reason or are not shown.'),
+            text('search', 'Search', 'Data', 'The search text; bind to the search box output.', { acceptedBindingKinds: bindable }),
+            { path: 'filter', label: 'Filter', group: 'Data', valueType: PropertyValueType.Object, acceptedBindingKinds: bindable, description: 'The filter builder\'s value.' },
+            text('sort', 'Sort', 'Data', 'The sorted field; a leading - is descending.'),
+            text('urlKey', 'Address prefix', 'Behavior', 'Keeps search, sort, page and selection in the address under this prefix.'),
+            valueOutputProperty(PropertyValueType.Json, 'The selected row id (single) or ids (many).'),
+            { path: 'action', label: 'Requested action', group: 'Outputs', valueType: PropertyValueType.Json, readOnly: true, output: true, description: 'The row action the user chose, with its row id.' },
+            ...standardStateProperties.filter(property => property.path !== 'actionPermission'),
+        ],
+    },
+    {
+        component: key(ComponentName.TabSet),
+        displayName: 'Tab set',
+        description: 'Tabs with a panel for each: the content of tab `overview` is the slot `overview`. The active tab is kept in the address.',
+        properties: [
+            {
+                ...list('tabs', 'Tabs', 'Data', 'Tab', [
+                    text('id', 'Id', 'Data', 'Also the name of the slot that holds the tab\'s content.', { constraints: { required: true } }),
+                    text('label', 'Label', 'Content'),
+                    text('badge', 'Count', 'Content'),
+                    flag('disabled', 'Disabled', 'Behavior'),
+                ], 'The tabs a record page offers.'),
+                acceptedBindingKinds: bindable,
+            },
+            text('activeTab', 'Active tab', 'Behavior'),
+            text('urlKey', 'Address parameter', 'Behavior', 'Keeps the active tab in the address under this name.'),
+            text('label', 'Label', 'Accessibility'),
+            valueOutputProperty(PropertyValueType.String, 'The id of the active tab.'),
+            ...standardStateProperties.filter(property => property.path !== 'label'),
+        ],
+    },
+    {
+        component: key(ComponentName.SubNavigation),
+        displayName: 'Sub-navigation',
+        description: 'A module\'s own sections as a tab bar or a left rail. Choosing one changes only the section.',
+        properties: [
+            {
+                ...list('items', 'Sections', 'Data', 'Section', [
+                    text('id', 'Id', 'Data', undefined, { constraints: { required: true } }),
+                    text('label', 'Label', 'Content'),
+                    text('badge', 'Count', 'Content'),
+                    flag('disabled', 'Disabled', 'Behavior'),
+                ], 'The sections.'),
+                acceptedBindingKinds: bindable,
+            },
+            choice('orientation', 'Orientation', 'Appearance', { horizontal: 'Tabs', vertical: 'Left rail' }, 'horizontal'),
+            text('activeItem', 'Active section', 'Behavior'),
+            text('urlKey', 'Address parameter', 'Behavior'),
+            text('label', 'Label', 'Accessibility'),
+            valueOutputProperty(PropertyValueType.String, 'The id of the active section.'),
+            ...standardStateProperties.filter(property => property.path !== 'label'),
+        ],
+    },
+    {
+        component: key(ComponentName.BulkBar),
+        displayName: 'Bulk bar',
+        description: 'Appears when records are selected, says how many, offers the bulk actions and clears the selection.',
+        properties: [
+            { path: 'selection', label: 'Selection', group: 'Data', valueType: PropertyValueType.Json, acceptedBindingKinds: bindable, description: 'The selected records or their count; bind to the list\'s value.' },
+            { path: 'actions', label: 'Actions', group: 'Behavior', valueType: PropertyValueType.Json, editorKind: PropertyEditorKind.StringList, default: [] },
+            rule('actionPermission', 'Action permission', 'Whether the bulk actions work, refuse with a reason or are not shown.'),
+            text('locale', 'Locale', 'Content'),
+            { path: 'strings', label: 'Text overrides', group: 'Content', valueType: PropertyValueType.Object, editorKind: PropertyEditorKind.StringMap },
+        ],
+    },
+    {
+        component: key(ComponentName.GlobalSearch),
+        displayName: 'Search',
+        description: 'A search box for the topbar or a list\'s toolbar. The text is the value output and can live in the address.',
+        properties: [
+            text('text', 'Initial text', 'Data'),
+            text('placeholder', 'Placeholder', 'Content'),
+            text('label', 'Label', 'Accessibility'),
+            text('urlKey', 'Address parameter', 'Behavior'),
+            valueOutputProperty(PropertyValueType.String, 'The search text.'),
+            { path: 'strings', label: 'Text overrides', group: 'Content', valueType: PropertyValueType.Object, editorKind: PropertyEditorKind.StringMap },
+        ],
+    },
+    {
+        component: key(ComponentName.NotificationsButton),
+        displayName: 'Notifications button',
+        description: 'The bell of the topbar with the unread count, said in words as well as in the badge.',
+        properties: [
+            number('count', 'Unread', 'Data', 'Bind to a query result.', { constraints: { minimum: 0, integer: true } }),
+            text('locale', 'Locale', 'Content'),
+            { path: 'strings', label: 'Text overrides', group: 'Content', valueType: PropertyValueType.Object, editorKind: PropertyEditorKind.StringMap },
+        ],
+    },
+    {
+        component: key(ComponentName.KanbanBoard),
+        displayName: 'Kanban board',
+        description: 'Columns mapped to a status, with cards that move by dragging or by their own Move-to menu. The new arrangement is the value output.',
+        properties: [
+            {
+                ...list('columns', 'Columns', 'Data', 'Column', [
+                    text('id', 'Id', 'Data', 'The status or stage value.', { constraints: { required: true } }),
+                    text('label', 'Label', 'Content'),
+                    number('limit', 'Limit', 'Behavior', 'The most cards the stage should hold; 0 is no limit.', { constraints: { minimum: 0, integer: true } }),
+                ], 'The stages.'),
+                acceptedBindingKinds: bindable,
+            },
+            {
+                ...list('cards', 'Cards', 'Data', 'Card', [
+                    text('id', 'Id', 'Data', undefined, { constraints: { required: true } }),
+                    text('title', 'Title', 'Data', undefined, { constraints: { required: true } }),
+                    text('column', 'Column', 'Data', 'The id of the column the card is in.'),
+                    text('assignee', 'Assignee', 'Data'),
+                    { path: 'badges', label: 'Badges', group: 'Data', valueType: PropertyValueType.Json, editorKind: PropertyEditorKind.StringList, default: [] },
+                ], 'The cards, from a query.'),
+                acceptedBindingKinds: bindable,
+            },
+            rule('editPermission', 'Move permission', 'Enabled lets cards move; otherwise the board is read-only.'),
+            valueOutputProperty(PropertyValueType.Json, 'Each card\'s id and column, published as cards move.'),
+            ...standardStateProperties,
+        ],
+    },
+    {
+        component: key(ComponentName.WizardProgress),
+        displayName: 'Wizard',
+        description: 'A linear wizard: the steps, back/next/finish and the draft save. The content of step `details` is the slot `details`; the last step is the review.',
+        properties: [
+            {
+                ...list('steps', 'Steps', 'Data', 'Step', [
+                    text('id', 'Id', 'Data', 'Also the name of the slot that holds the step\'s content.', { constraints: { required: true } }),
+                    text('label', 'Label', 'Content'),
+                    flag('valid', 'Valid', 'Data', 'Whether the step\'s fields are valid; an invalid step blocks Next.', { default: true, acceptedBindingKinds: bindable }),
+                ], 'The steps in order.'),
+                acceptedBindingKinds: bindable,
+            },
+            text('currentStep', 'Current step', 'Behavior'),
+            text('urlKey', 'Address parameter', 'Behavior', 'Keeps the current step in the address so a refresh resumes.'),
+            valueOutputProperty(PropertyValueType.String, 'The id of the current step.'),
+            ...standardStateProperties,
+        ],
+    },
+    {
+        component: key(ComponentName.FormScreenBody),
+        displayName: 'Form',
+        description: 'Titled sections of fields in a one-to-three column grid, with inline validation, a save bar, the unsaved-changes guard and four modes.',
+        properties: [
+            {
+                ...list('sections', 'Sections', 'Data', 'Section', [
+                    text('id', 'Id', 'Data'),
+                    text('title', 'Title', 'Content'),
+                    number('columns', 'Columns', 'Appearance', undefined, { default: 1, constraints: { minimum: 1, maximum: 3, integer: true } }),
+                    list('fields', 'Fields', 'Data', 'Field', [
+                        text('name', 'Name', 'Data', undefined, { constraints: { required: true }, editorKind: PropertyEditorKind.Field }),
+                        text('label', 'Label', 'Content'),
+                        choice('type', 'Type', 'Data', Object.fromEntries(Object.values(FormFieldType).map(type => [type, type])), FormFieldType.Text),
+                        flag('required', 'Required', 'Data'),
+                        { path: 'options', label: 'Options', group: 'Data', valueType: PropertyValueType.Json, editorKind: PropertyEditorKind.StringList, default: [] },
+                        number('span', 'Columns spanned', 'Appearance', undefined, { default: 1, constraints: { minimum: 1, maximum: 3, integer: true } }),
+                        text('placeholder', 'Placeholder', 'Content'),
+                        text('help', 'Help text', 'Content'),
+                    ]),
+                ], 'The groups of fields.'),
+                acceptedBindingKinds: bindable,
+            },
+            { path: 'values', label: 'Values', group: 'Data', valueType: PropertyValueType.Object, acceptedBindingKinds: bindable, description: 'The record being edited; empty when creating.' },
+            { path: 'errors', label: 'Server errors', group: 'Data', valueType: PropertyValueType.Json, acceptedBindingKinds: bindable, description: 'Field errors from the server, as { field: message }; one for an unknown field is shown as a general error.' },
+            choice('mode', 'Mode', 'Behavior', { [FormMode.Create]: 'Create', [FormMode.Edit]: 'Edit', [FormMode.ReadOnly]: 'Read-only', [FormMode.Settings]: 'Settings (a save for each section)' }, FormMode.Create),
+            rule('editPermission', 'Edit permission', 'Enabled lets the user change fields; otherwise the form is read-only.'),
+            rule('savePermission', 'Save permission', 'Whether Save works, refuses with a reason or is not shown.'),
+            valueOutputProperty(PropertyValueType.Object, 'The values as the user has edited them.'),
+            ...standardStateProperties,
+        ],
+    },
 ];
 

package/foundation/foundationSamples.ts

@@ -108,6 +108,62 @@ export const foundationSamples: Record<string, FoundationSample> = {
         },
         data: ['Edit deals', 'Manage users'], stateful: true,
     },
+    [ComponentName.DataList]: {
+        properties: {
+            locale: 'en-US', idField: 'id', titleField: 'name', selectionMode: 'multiple', pageSize: 5, rowActions: ['Open', 'Archive'],
+            columns: [
+                { field: 'name', header: 'Account' }, { field: 'owner', header: 'Owner' }, { field: 'value', header: 'Value', kind: 'currency', currency: 'USD' },
+                { field: 'status', header: 'Status', kind: 'status', tones: { Open: 'info', Won: 'success', Lost: 'danger' } }, { field: 'closes', header: 'Closes', kind: 'date' },
+            ],
+            rows: [
+                { id: '1', name: 'Northgate Ltd', owner: 'Ada', value: 12000, status: 'Open', closes: '2026-04-01' },
+                { id: '2', name: 'Harbour & Sons', owner: 'Grace', value: 8400.5, status: 'Won', closes: '2026-03-12' },
+                { id: '3', name: 'Fjord Supply', owner: 'Linus', value: 560, status: 'Lost', closes: '2026-02-20' },
+            ],
+        },
+        data: ['Northgate Ltd', '3 items'], stateful: true,
+    },
+    [ComponentName.TabSet]: {
+        properties: { tabs: [{ id: 'overview', label: 'Overview' }, { id: 'related', label: 'Related', badge: '4' }, { id: 'files', label: 'Files' }, { id: 'history', label: 'History', disabled: true }] },
+        data: ['Overview', 'Related'], stateful: true,
+    },
+    [ComponentName.SubNavigation]: {
+        properties: { items: [{ id: 'accounts', label: 'Accounts' }, { id: 'contacts', label: 'Contacts', badge: '12' }, { id: 'deals', label: 'Deals' }] },
+        data: ['Accounts', 'Contacts'], stateful: true,
+    },
+    [ComponentName.BulkBar]: { properties: { selection: ['1', '2'], actions: ['Assign', 'Archive'] }, data: [], stateful: false },
+    [ComponentName.GlobalSearch]: { properties: { placeholder: 'Search accounts', label: 'Search accounts' }, data: [], stateful: false },
+    [ComponentName.NotificationsButton]: { properties: { count: 3 }, data: [], stateful: false },
+    [ComponentName.KanbanBoard]: {
+        properties: {
+            columns: [{ id: 'new', label: 'New', limit: 2 }, { id: 'qualified', label: 'Qualified' }, { id: 'won', label: 'Won' }],
+            cards: [
+                { id: 'c1', title: 'Acme renewal', column: 'new', assignee: 'Ada', fields: [{ label: 'Value', value: '$12,000' }], badges: ['Hot'] },
+                { id: 'c2', title: 'Globex rollout', column: 'new', assignee: 'Grace' },
+                { id: 'c3', title: 'Initech pilot', column: 'new' },
+                { id: 'c4', title: 'Umbrella upgrade', column: 'qualified' },
+            ],
+        },
+        data: ['Acme renewal'], stateful: true,
+    },
+    [ComponentName.WizardProgress]: {
+        properties: { steps: [{ id: 'details', label: 'Details' }, { id: 'people', label: 'People' }, { id: 'review', label: 'Review' }] },
+        data: ['Details', 'People'], stateful: true,
+    },
+    [ComponentName.FormScreenBody]: {
+        properties: {
+            mode: 'create', locale: 'en-US',
+            sections: [
+                { title: 'Account details', columns: 2, fields: [
+                    { name: 'name', label: 'Name', required: true }, { name: 'industry', label: 'Industry', type: 'select', options: ['Software', 'Retail'] },
+                    { name: 'revenue', label: 'Revenue', type: 'currency' }, { name: 'since', label: 'Customer since', type: 'date' },
+                    { name: 'notes', label: 'Notes', type: 'richText', span: 2 },
+                ] },
+                { title: 'Preferences', fields: [{ name: 'tags', label: 'Tags', type: 'multiSelect', options: ['VIP', 'Partner'] }, { name: 'active', label: 'Active', type: 'toggle' }] },
+            ],
+        },
+        data: ['Account details'], stateful: true,
+    },
 };
 
 /** A scene element for a foundation component, populated with its sample unless properties are given, with the state forced when asked. */

package/foundation/foundationStrings.ts

@@ -124,6 +124,78 @@ export const foundationStrings = {
     orgReports: '{count} reports',
     orgTree: 'Organization',
     orgNone: 'There is nobody in the organization yet',
+    listCount: '{count} items',
+    listCountFiltered: '{shown} of {total} items',
+    listSelectAll: 'Select all rows on this page',
+    listSelectRow: 'Select {name}',
+    listRowActions: 'Actions for {name}',
+    listActions: 'Actions',
+    listSortBy: 'Sort by {column}',
+    listSortedAscending: 'sorted ascending',
+    listSortedDescending: 'sorted descending',
+    listPage: 'Page {page} of {pages}',
+    listPrevious: 'Previous page',
+    listNext: 'Next page',
+    listNoMatches: 'Nothing matches your search or filters',
+    listClearSearch: 'Clear search and filters',
+    listGroupCollapse: 'Collapse {group}',
+    listGroupExpand: 'Expand {group}',
+    listGroupSubtotal: '{count} items, {total}',
+    listCards: 'Items as cards',
+    listTable: 'Items as a table',
+    listBack: 'Back to the list',
+    viewTable: 'Table',
+    viewCards: 'Cards',
+    viewGrouped: 'Grouped',
+    densityComfortable: 'Comfortable',
+    densityCompact: 'Compact',
+    formRequired: 'required',
+    formRequiredField: '{label} is required',
+    formInvalidField: '{label} is not valid',
+    formSummary: 'Fix {count} fields before saving',
+    formSummaryOne: 'Fix 1 field before saving',
+    formSave: 'Save',
+    formSaveAndNew: 'Save and new',
+    formCancel: 'Cancel',
+    formEdit: 'Edit',
+    formUnsaved: 'You have unsaved changes',
+    formDiscard: 'Discard changes',
+    formSaved: 'Saved',
+    formSectionSave: 'Save {section}',
+    formReadOnly: 'This form is read-only',
+    formChoose: 'Choose…',
+    summaryLabel: 'Key facts',
+    tabsLabel: 'Sections',
+    subNavLabel: 'Module sections',
+    bulkSelected: '{count} selected',
+    bulkClear: 'Clear selection',
+    bulkActions: 'Actions for the selection',
+    searchLabel: 'Search',
+    searchPlaceholder: 'Search',
+    searchClear: 'Clear search',
+    notificationsLabel: 'Notifications',
+    notificationsCount: '{count} unread',
+    notificationsNone: 'No new notifications',
+    boardMoveTo: 'Move to…',
+    boardMoveCard: 'Move {title}',
+    boardMoved: '{title} moved to {column}',
+    boardColumn: '{column}, {count} cards',
+    boardCollapse: 'Collapse {column}',
+    boardExpand: 'Expand {column}',
+    boardWip: 'Limit {limit}',
+    boardWipExceeded: 'Over the limit of {limit}',
+    boardNoCards: 'No cards',
+    wizardStep: 'Step {n} of {total}',
+    wizardBack: 'Back',
+    wizardNext: 'Next',
+    wizardFinish: 'Finish',
+    wizardSaveDraft: 'Save draft',
+    wizardDraftSaved: 'Draft saved',
+    wizardReview: 'Review',
+    wizardComplete: 'Completed',
+    wizardCurrent: 'Current step',
+    wizardUpcoming: 'Not started',
+    wizardProgress: 'Wizard progress',
     matrixAllowed: 'Allowed',
     matrixDenied: 'Not allowed',
     matrixGrant: 'Grant {permission} to {role}',

package/foundation/index.ts

@@ -36,6 +36,22 @@ export * from './orgModel';
 export * from './OrgTree';
 export * from './permissionModel';
 export * from './PermissionMatrix';
+export * from './urlState';
+export * from './useCompactWidth';
+export * from './listModel';
+export * from './DataList';
+export * from './tabModel';
+export * from './TabSet';
+export * from './SubNavigation';
+export * from './BulkBar';
+export * from './GlobalSearch';
+export * from './NotificationsButton';
+export * from './boardModel';
+export * from './KanbanBoard';
+export * from './wizardModel';
+export * from './WizardProgress';
+export * from './formModel';
+export * from './FormScreenBody';
 export * from './foundationDescriptors';
 export * from './foundationComponentMetadata';
 export * from './foundationSamples';

package/foundation/listModel.ts

@@ -0,0 +1,190 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/** How a column's cell is drawn. */
+export enum CellKind {
+    Text = 'text',
+    Number = 'number',
+    Currency = 'currency',
+    Date = 'date',
+    Status = 'status',
+}
+
+/** One column of a list. */
+export interface ListColumn {
+    field: string;
+    header: string;
+    kind: CellKind;
+    sortable: boolean;
+    /** For a status column: the tone of each value (`success`, `warning`, `danger`, `info`, `neutral`). */
+    tones: Record<string, string>;
+    /** For a currency column: the ISO 4217 code. */
+    currency?: string;
+}
+
+/** One record of a list, with the field values as the query returned them. */
+export type ListRow = Record<string, unknown>;
+
+/** How the list is sorted. */
+export interface ListSort {
+    field: string;
+    descending: boolean;
+}
+
+/** The ways the same records can be laid out. */
+export enum ListVariant {
+    Table = 'table',
+    Cards = 'cards',
+    Grouped = 'grouped',
+}
+
+const records = (value: unknown): Record<string, unknown>[] =>
+    Array.isArray(value) ? value.filter((entry): entry is Record<string, unknown> => typeof entry === 'object' && entry !== null && !Array.isArray(entry)) : [];
+
+/** Reads columns, dropping those without a field and repeated fields. */
+export function readListColumns(value: unknown): ListColumn[] {
+    const seen = new Set<string>();
+    return records(value).flatMap(entry => {
+        if (typeof entry.field !== 'string' || entry.field.length === 0 || seen.has(entry.field)) return [];
+        seen.add(entry.field);
+        const tones = typeof entry.tones === 'object' && entry.tones !== null && !Array.isArray(entry.tones)
+            ? Object.fromEntries(Object.entries(entry.tones as Record<string, unknown>).filter((pair): pair is [string, string] => typeof pair[1] === 'string')) : {};
+        return [{
+            field: entry.field,
+            header: typeof entry.header === 'string' && entry.header.length > 0 ? entry.header : entry.field,
+            kind: (Object.values(CellKind) as string[]).includes(entry.kind as string) ? (entry.kind as CellKind) : CellKind.Text,
+            sortable: entry.sortable !== false,
+            tones,
+            ...(typeof entry.currency === 'string' ? { currency: entry.currency } : {}),
+        }];
+    });
+}
+
+/** Reads the variant, defaulting to the table. */
+export const readListVariant = (value: unknown): ListVariant => ((Object.values(ListVariant) as string[]).includes(value as string) ? (value as ListVariant) : ListVariant.Table);
+
+/** The value of a row's field as text for searching and display: a primitive as itself, anything else empty. */
+export const textOf = (row: ListRow, field: string): string => {
+    const value = row[field];
+    return typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean' ? String(value) : '';
+};
+
+/** The id of a row: its `idField`, else its position, so a list without ids still selects and keys sensibly. */
+export const rowId = (row: ListRow, index: number, idField: string): string => {
+    const value = row[idField];
+    return typeof value === 'string' || typeof value === 'number' ? String(value) : `row-${index}`;
+};
+
+/** Rows that contain the search text in any shown column, without regard to case or accents; empty search keeps every row. */
+export function searchRows(rows: ListRow[], columns: ListColumn[], search: string): ListRow[] {
+    const needle = normalize(search);
+    if (needle.length === 0) return rows;
+    return rows.filter(row => columns.some(column => normalize(textOf(row, column.field)).includes(needle)));
+}
+
+/** Rows that satisfy a filter of conditions joined by AND or OR, in nested groups - the value the filter builder publishes. */
+export function filterRows(rows: ListRow[], filter: unknown): ListRow[] {
+    if (typeof filter !== 'object' || filter === null) return rows;
+    const group = filter as { operator?: string; conditions?: { field: string; operator: string; value: string }[]; groups?: unknown[] };
+    const tests = [
+        ...(group.conditions ?? []).filter(condition => typeof condition?.field === 'string').filter(active).map(condition => (row: ListRow) => satisfies(row, condition)),
+        ...(group.groups ?? []).filter(nested => hasConditions(nested)).map(nested => (row: ListRow) => filterRows([row], nested).length === 1),
+    ];
+    if (tests.length === 0) return rows;
+    return rows.filter(row => (group.operator === 'or' ? tests.some(test => test(row)) : tests.every(test => test(row))));
+}
+
+const active = (condition: { operator: string; value: string }) => ['isEmpty', 'true', 'false'].includes(condition.operator) || (condition.value ?? '').trim().length > 0;
+const hasConditions = (group: unknown): boolean => {
+    const candidate = group as { conditions?: { operator: string; value: string }[]; groups?: unknown[] } | null;
+    return (candidate?.conditions ?? []).some(active) || (candidate?.groups ?? []).some(hasConditions);
+};
+
+function satisfies(row: ListRow, condition: { field: string; operator: string; value: string }): boolean {
+    const raw = row[condition.field];
+    const text = normalize(typeof raw === 'string' || typeof raw === 'number' || typeof raw === 'boolean' ? String(raw) : '');
+    const value = normalize(condition.value ?? '');
+    const number = Number(raw);
+    const wanted = Number(condition.value);
+    switch (condition.operator) {
+        case 'contains': return text.includes(value);
+        case 'equals': case 'is': case 'on': return typeof raw === 'number' ? number === wanted : text === value;
+        case 'notEquals': case 'isNot': return typeof raw === 'number' ? number !== wanted : text !== value;
+        case 'startsWith': return text.startsWith(value);
+        case 'isEmpty': return text.length === 0;
+        case 'greater': return number > wanted;
+        case 'greaterOrEqual': return number >= wanted;
+        case 'less': return number < wanted;
+        case 'lessOrEqual': return number <= wanted;
+        case 'before': return text < value;
+        case 'after': return text > value;
+        case 'true': return raw === true || text === 'true';
+        case 'false': return raw === false || text === 'false';
+        default: return true;
+    }
+}
+
+function normalize(text: string): string {
+    return text.normalize('NFD').replace(/\p{Diacritic}/gu, '').toLocaleLowerCase();
+}
+
+/** Reads a sort from its address form, `field` or `-field` for descending; a field that is not a sortable column is no sort at all. */
+export function parseSort(text: string | undefined, columns: ListColumn[]): ListSort | undefined {
+    if (!text) return undefined;
+    const descending = text.startsWith('-');
+    const field = descending ? text.slice(1) : text;
+    return columns.some(column => column.field === field && column.sortable) ? { field, descending } : undefined;
+}
+
+/** A sort in its address form. */
+export const formatSort = (sort: ListSort | undefined): string | undefined => (sort === undefined ? undefined : `${sort.descending ? '-' : ''}${sort.field}`);
+
+/** The next sort when a header is pressed: ascending, then descending, then none. */
+export const nextSort = (current: ListSort | undefined, field: string): ListSort | undefined =>
+    current?.field !== field ? { field, descending: false } : current.descending ? undefined : { field, descending: true };
+
+/** Rows in order of a column, numbers as numbers and text by the locale, with ties kept in their original order. */
+export function sortRows(rows: ListRow[], sort: ListSort | undefined, locale: string): ListRow[] {
+    if (!sort) return rows;
+    const collator = new Intl.Collator(locale, { numeric: true, sensitivity: 'base' });
+    return rows.map((row, index) => ({ row, index })).sort((left, right) => {
+        const a = left.row[sort.field];
+        const b = right.row[sort.field];
+        const order = typeof a === 'number' && typeof b === 'number' ? a - b : collator.compare(textOf(left.row, sort.field), textOf(right.row, sort.field));
+        return (order === 0 ? left.index - right.index : sort.descending ? -order : order);
+    }).map(entry => entry.row);
+}
+
+/** The slice of rows on a page (1-based), and how many pages there are; a page out of range is clamped rather than empty. */
+export function paginate<T>(rows: T[], page: number, pageSize: number): { rows: T[]; page: number; pages: number } {
+    const size = pageSize > 0 ? Math.floor(pageSize) : rows.length || 1;
+    const pages = Math.max(1, Math.ceil(rows.length / size));
+    const clamped = Math.min(Math.max(1, Math.floor(Number.isFinite(page) ? page : 1)), pages);
+    return { rows: rows.slice((clamped - 1) * size, clamped * size), page: clamped, pages };
+}
+
+/** A group of rows with a subtotal, for the grouped variant. */
+export interface ListGroup {
+    key: string;
+    rows: ListRow[];
+    subtotal?: number;
+}
+
+/** Groups rows by a field in the order the groups are first seen, with the sum of a numeric field as the subtotal when one is named. */
+export function groupRows(rows: ListRow[], groupBy: string, totalField?: string): ListGroup[] {
+    const groups: ListGroup[] = [];
+    for (const row of rows) {
+        const key = textOf(row, groupBy);
+        const group = groups.find(candidate => candidate.key === key) ?? (groups.push({ key, rows: [] }), groups[groups.length - 1]);
+        group.rows.push(row);
+    }
+
+    return totalField === undefined ? groups : groups.map(group => ({ ...group, subtotal: group.rows.reduce((sum, row) => sum + (typeof row[totalField] === 'number' ? (row[totalField] as number) : 0), 0) }));
+}
+
+/** Toggles an id in a selection that allows one or many. */
+export const toggleSelection = (selected: string[], id: string, multiple: boolean): string[] =>
+    selected.includes(id) ? selected.filter(candidate => candidate !== id) : multiple ? [...selected, id] : [id];
+
+/** Reads a selection from its address form: ids separated by commas. */
+export const parseSelection = (text: string | undefined): string[] => (text ? text.split(',').filter(id => id.length > 0) : []);

package/foundation/tabModel.ts

@@ -0,0 +1,41 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/** One tab or sub-section: an id the address and the slot content use, a label, and an optional count badge. */
+export interface TabItem {
+    id: string;
+    label: string;
+    badge?: string;
+    disabled: boolean;
+}
+
+/** Reads tabs out of a property value; entries without an id are dropped and a repeated id keeps its first. */
+export function readTabs(value: unknown): TabItem[] {
+    if (!Array.isArray(value)) return [];
+
+    const seen = new Set<string>();
+    return value.flatMap((entry): TabItem[] => {
+        if (typeof entry !== 'object' || entry === null || Array.isArray(entry)) return [];
+        const { id, label, badge, disabled } = entry as Record<string, unknown>;
+        if (typeof id !== 'string' || id.length === 0 || seen.has(id)) return [];
+        seen.add(id);
+        return [{ id, label: typeof label === 'string' && label.length > 0 ? label : id, disabled: disabled === true, ...(typeof badge === 'string' || typeof badge === 'number' ? { badge: String(badge) } : {}) }];
+    });
+}
+
+/** The active tab: the requested one when it exists and is enabled, else the first enabled one. Deep links to a tab that was removed fall back instead of showing nothing. */
+export function activeTab(tabs: TabItem[], requested: string | undefined): string | undefined {
+    const wanted = tabs.find(tab => tab.id === requested && !tab.disabled);
+    return (wanted ?? tabs.find(tab => !tab.disabled))?.id;
+}
+
+/** The enabled tab one step from the current one, wrapping, or the first/last for Home and End. */
+export function stepTab(tabs: TabItem[], current: string | undefined, direction: 'next' | 'previous' | 'first' | 'last'): string | undefined {
+    const enabled = tabs.filter(tab => !tab.disabled);
+    if (enabled.length === 0) return undefined;
+    if (direction === 'first') return enabled[0].id;
+    if (direction === 'last') return enabled[enabled.length - 1].id;
+
+    const index = Math.max(0, enabled.findIndex(tab => tab.id === current));
+    return enabled[(index + (direction === 'next' ? 1 : -1) + enabled.length) % enabled.length].id;
+}