dynamic-mui 2.5.0 → 2.5.1

package/dist/types.d.ts

@@ -81,6 +81,194 @@ export interface FormField {
     optionsMap?: Record<string, any[]>;
     [key: string]: any;
 }
+/**
+ * Text shown on a `collection` item card: a field id (`'customerName'`), a
+ * template (`'{city}, {state} {zip}'`), a list of ids joined with " · ", or a
+ * function of the item.
+ */
+export type CollectionTextSpec = string | string[] | ((item: Record<string, any>) => string);
+/** A theme palette name, or any CSS colour (`'#0ea5e9'`). */
+export type CollectionColor = 'primary' | 'secondary' | 'success' | 'info' | 'warning' | 'error' | (string & {});
+/** One labelled fact on an item card: icon in front, then label and value. */
+export interface CollectionDetailSpec {
+    /** Field id whose value is shown. */
+    field: string;
+    /** Label override (defaults to the field's own label). */
+    label?: string;
+    /** Material icon name shown in front (defaults to one based on the field type). */
+    icon?: string;
+    /** Grid columns this detail spans (grid layout). */
+    span?: number;
+}
+/** Responsive column count, e.g. `{ xs: 1, sm: 2, md: 4 }`. */
+export type CollectionColumns = number | Partial<Record<'xs' | 'sm' | 'md' | 'lg' | 'xl', number>>;
+/** How a `collection` item is summarised on its card / row. */
+export interface CollectionDisplay {
+    /** Card heading / first table column. Defaults to the first field. */
+    title?: CollectionTextSpec;
+    /** Heading of the title column in the table layout (defaults to `itemLabel`). */
+    titleLabel?: string;
+    /** Optional secondary line under the title. */
+    subtitle?: CollectionTextSpec;
+    /** Material icon in front of the subtitle (e.g. `'place'` for an address). */
+    subtitleIcon?: string;
+    /** A status pill. `colors` maps a raw value (or its label) to a colour;
+     *  `label` heads its column in the table layout. */
+    badge?: string | {
+        field: string;
+        label?: string;
+        colors?: Record<string, CollectionColor | 'default'>;
+    };
+    /** Leading avatar on cards: initials of the title, the collection icon, the item number, or none (default). */
+    avatar?: 'initials' | 'icon' | 'index' | 'none';
+    /**
+     * The labelled facts under the title. Defaults to every filled field not
+     * already in the title/subtitle/badge. List ids or `{ field, label, icon, span }`
+     * to choose and order them, or `false` to hide them.
+     */
+    details?: (string | CollectionDetailSpec)[] | false;
+    /** `grid` (icon tiles), `list` (one row per fact) or `inline` (a wrapping line). */
+    detailsLayout?: 'grid' | 'list' | 'inline';
+    /** Grid columns. Defaults to as many as fit `minColumnWidth`. */
+    columns?: CollectionColumns;
+    /** Narrowest grid column in px when `columns` is not set (default 180). */
+    minColumnWidth?: number;
+    /** Show the icon in front of each detail (default true). */
+    showIcons?: boolean;
+}
+/** The add button of a collection level. */
+export interface CollectionAddButton {
+    /** `header` (beside the title, default), `footer` (below the list), `both`, or `none`. */
+    position?: 'header' | 'footer' | 'both' | 'none';
+    /** `contained` (top-level default), `outlined` (nested default), `text`, `soft` (tinted) or `dashed` (full-width tile). */
+    variant?: 'dashed' | 'soft' | 'contained' | 'outlined' | 'text';
+    /** Material icon name (default `'add'`). */
+    icon?: string;
+    size?: 'small' | 'medium' | 'large';
+    fullWidth?: boolean;
+}
+/** Which item actions are offered. Edit and delete are on by default;
+ *  duplicate, move (up/down) and collapse are opt-in. */
+export interface CollectionActions {
+    edit?: boolean;
+    delete?: boolean;
+    duplicate?: boolean;
+    move?: boolean;
+    /** Collapse/expand toggle on items that own nested collections. */
+    collapse?: boolean;
+}
+/**
+ * Every user-facing string, so labels can be reworded or translated from JSON.
+ * Placeholders: `{label}` item label, `{labelLower}`, `{plural}`, `{pluralLower}`,
+ * `{title}` item title, `{max}`, `{detail}`. Nested levels inherit their parent's texts.
+ */
+export interface CollectionTexts {
+    add?: string;
+    addMore?: string;
+    emptyTitle?: string;
+    emptyText?: string;
+    edit?: string;
+    duplicate?: string;
+    moveUp?: string;
+    moveDown?: string;
+    delete?: string;
+    more?: string;
+    collapse?: string;
+    expand?: string;
+    editAria?: string;
+    deleteAria?: string;
+    viewAria?: string;
+    moreAria?: string;
+    collapseAria?: string;
+    expandAria?: string;
+    maxReached?: string;
+    dialogAddTitle?: string;
+    dialogEditTitle?: string;
+    dialogViewTitle?: string;
+    /** Line under a nested dialog title naming the parent, e.g. "For {parent}". */
+    dialogContext?: string;
+    save?: string;
+    saveChanges?: string;
+    saveAndAddAnother?: string;
+    cancel?: string;
+    close?: string;
+    closeAria?: string;
+    shortcut?: string;
+    deleteTitle?: string;
+    deleteMessage?: string;
+    deleteDetail?: string;
+    deleteConfirm?: string;
+}
+/**
+ * Named parts of a collection level that take an MUI `sx` override from JSON.
+ * The override is merged over the built-in style, so any look can be changed.
+ */
+export type CollectionSlot = 'root' | 'header' | 'headerIcon' | 'headerTitle' | 'headerCount' | 'headerDescription' | 'error' | 'list' | 'addButton' | 'empty' | 'emptyTitle' | 'emptyText' | 'item' | 'itemHeader' | 'avatar' | 'itemTitle' | 'badge' | 'subtitle' | 'actions' | 'actionButton' | 'counts' | 'details' | 'detail' | 'detailIcon' | 'detailLabel' | 'detailValue' | 'sections' | 'section' | 'table' | 'tableHead' | 'tableHeadCell' | 'tableRow' | 'tableCell' | 'rowActions' | 'mobileRow' | 'dialog' | 'dialogHeader' | 'dialogTitle' | 'dialogDescription' | 'dialogContext' | 'dialogContent' | 'dialogActions' | 'dialogCancel' | 'dialogSaveAnother' | 'dialogSave' | 'menu' | 'menuItem' | 'confirm' | 'confirmTitle' | 'confirmText' | 'confirmCancel' | 'confirmDelete';
+export type CollectionStyles = Partial<Record<CollectionSlot, Record<string, any>>>;
+/**
+ * One level of a `collection` field: a list of items added/edited through a
+ * dialog, rendered as cards. Each item can own nested `collections` (e.g. a
+ * Customer Location with Services and Backflow devices), to any depth.
+ * Everything — content, layout, wording and styling — is set from JSON.
+ * Output: `[{ ...itemFields, [child.id]: [{ ...childFields }] }]`.
+ */
+export interface CollectionConfig {
+    /** Key of this list in its parent item (the field id at the root). */
+    id: string;
+    /** Singular name, e.g. "Customer Location" → "Add Customer Location". */
+    itemLabel?: string;
+    /** Section heading. Defaults to the plural of `itemLabel`. */
+    title?: string;
+    /** Helper text under the heading. */
+    description?: string;
+    /** Material icon name for the section, dialog and item avatars. */
+    icon?: string;
+    /** Accent colour for this level (palette name or any CSS colour). */
+    color?: CollectionColor;
+    /** The fields of the add/edit dialog (any FormGenerator schema). */
+    fields: FormField[];
+    /** Card summary configuration. */
+    display?: CollectionDisplay;
+    /** Nested lists owned by each item. */
+    collections?: CollectionConfig[];
+    /** Columns for this level's nested sections inside an item (default 1 = stacked rows). */
+    sectionColumns?: CollectionColumns;
+    /** How items are shown: `cards` (top-level default) or `table` (nested
+     *  default — one row per item, one column per detail; stacked rows on phones). */
+    layout?: 'cards' | 'table';
+    /** Card look: `outlined` (default, thin border), `card` (soft shadow) or `flat`. */
+    variant?: 'card' | 'outlined' | 'flat';
+    /** Add button placement and look. */
+    addButton?: CollectionAddButton;
+    /** Which item actions are offered. */
+    actions?: CollectionActions;
+    /** Minimum / maximum number of items at this level (validated on submit). */
+    min?: number;
+    max?: number;
+    minMessage?: string;
+    maxMessage?: string;
+    /** Dialog options. `addAnother` shows "Save & add another" (default true);
+     *  `fullScreen` is `'mobile'` (default), `true` or `false`. */
+    dialog?: {
+        maxWidth?: 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+        description?: string;
+        addAnother?: boolean;
+        fullScreen?: boolean | 'mobile';
+        /** Grid spacing of the dialog form. */
+        spacing?: number;
+    };
+    /** Ask before deleting an item (default true). */
+    confirmDelete?: boolean;
+    /** Start items collapsed (default false). */
+    defaultCollapsed?: boolean;
+    /** Show a message when the list is empty. Defaults: true at the top level,
+     *  false when nested (an empty nested section is just its title + add button). */
+    showEmpty?: boolean;
+    /** Reword / translate any text (inherited by nested levels). */
+    texts?: CollectionTexts;
+    /** Per-part `sx` overrides — see `CollectionSlot`. */
+    styles?: CollectionStyles;
+}
 /** An unmet validation rule reported back through `onSubmit`. */
 export interface FormError extends ValidationRule {
     id?: string;

package/dist/util/collection.d.ts

@@ -0,0 +1,82 @@
+import { CollectionConfig, CollectionTextSpec, FormField } from '../types';
+/**
+ * Pure helpers for the `collection` control (nested, dialog-edited lists such as
+ * Customer Locations → Services / Backflow devices). Kept free of React/MUI so
+ * FormGenerator can use them for validation and the review summary without
+ * pulling the (lazy) collection UI into the main bundle.
+ */
+/** A structural problem in a collection tree. `path` locates the offending
+ *  LIST: `[]` is the root list, `[0, 'services']` is item 0's services list. */
+export interface CollectionIssue {
+    path: (string | number)[];
+    message: string;
+}
+/** Naive English plural for default headings/labels ("Service" → "Services",
+ *  "Address" → "Addresses", "Facility" → "Facilities"). */
+export declare const pluralize: (word: string, count?: number) => string;
+/** Singular item label for a collection level ("Customer Location"). */
+export declare const itemLabelOf: (config: Partial<CollectionConfig>) => string;
+/** Section heading for a collection level ("Customer Locations"). */
+export declare const titleOf: (config: Partial<CollectionConfig>) => string;
+export declare const toItems: (value: any) => Record<string, any>[];
+/** Find a field definition by id, following `subforms` branches. */
+export declare const findField: (fields: FormField[] | undefined, id: string) => FormField | undefined;
+/** Human-readable label of a field definition. */
+export declare const fieldLabel: (field: FormField | undefined) => string;
+/** Human-readable text for one stored value: option labels for selects/radios,
+ *  Yes/No for booleans, formatted dates, joined arrays. */
+export declare const formatValue: (field: FormField | undefined, value: any) => string;
+/** Resolve a display spec against an item. A spec is a field id (`'name'`), a
+ *  template (`'{city}, {state} {zip}'`), a list of ids joined with " · ", or a
+ *  function `(item) => string`. */
+export declare const resolveText: (spec: CollectionTextSpec | undefined, item: Record<string, any>, fields?: FormField[]) => string;
+export interface ItemDetail {
+    id: string;
+    label: string;
+    value: string;
+    icon: string;
+    span?: number;
+}
+export declare const defaultIconFor: (field: FormField | undefined) => string;
+/**
+ * Everything an item card shows: its title, optional subtitle, and the
+ * labelled `details` (icon + label + value) of its other filled fields — so
+ * every record is readable at a glance. Fields already in the title, subtitle
+ * or badge are not repeated. `display.details` lists ids or
+ * `{ field, label, icon, span }` to choose and order them, or is `false`.
+ */
+export declare const describeItem: (item: Record<string, any>, config: Partial<CollectionConfig>, index: number) => {
+    title: string;
+    subtitle: string;
+    details: ItemDetail[];
+};
+/** The field ids the title shows: from `display.title`, else the first field. */
+export declare const titleFieldIds: (config: Partial<CollectionConfig>) => string[];
+/**
+ * The facts a level shows for each item (and the columns of its table view),
+ * in order: `display.details` when given, else every field not already in the
+ * title, subtitle or badge. Labels/icons default from the field definitions.
+ */
+export declare const detailSpecs: (config: Partial<CollectionConfig>) => Omit<ItemDetail, "value">[];
+/** Title + subtitle only (see `describeItem`). */
+export declare const summarize: (item: Record<string, any>, config: Partial<CollectionConfig>, index: number) => {
+    title: string;
+    subtitle: string;
+};
+/** Count every nested item under `item`, per child collection (for delete
+ *  confirmations: "also removes 2 services and 1 backflow"). */
+export declare const describeDescendants: (item: Record<string, any>, config: Partial<CollectionConfig>) => string;
+/**
+ * Walk a collection tree and report every level that breaks its `min`/`max`.
+ * `required` (from a mandatory rule) enforces at least one root item.
+ */
+export declare const collectionIssues: (value: any, config: Partial<CollectionConfig>, opts?: {
+    required?: boolean;
+    requiredMessage?: string;
+}, path?: (string | number)[]) => CollectionIssue[];
+/** Label/value rows for the review summary, print view and PDF export.
+ *  Nested items are prefixed with their parent ("Customer Location 1 › Service 2"). */
+export declare const collectionReviewRows: (value: any, config: Partial<CollectionConfig>, prefix?: string) => {
+    label: string;
+    value: string;
+}[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dynamic-mui",
-  "version": "2.5.0",
+  "version": "2.5.1",
   "author": "Dinakaran S",
   "user": "dinakarans",
   "repository": {