@siliconst/metaui 1.4.44 → 2.0.0

package/src/nz/co/siliconst/ui5/metaui/layouts/TableLayout.ts

@@ -1,240 +1,294 @@
-/**
- * @file TableLayout.ts
- * @description Generates a responsive SAP Fiori Table layout for v2 schema.
- */
-
-import Table from "sap/m/Table";
-import Column from "sap/m/Column";
-import Text from "sap/m/Text";
-import ColumnListItem from "sap/m/ColumnListItem";
-import Toolbar from "sap/m/Toolbar";
-import Title from "sap/m/Title";
-import ToolbarSpacer from "sap/m/ToolbarSpacer";
-import Button from "sap/m/Button";
-import JSONModel from "sap/ui/model/json/JSONModel";
-import Control from "sap/ui/core/Control";
-import { IPropertyMetadata, ISchema, ILayoutElement } from "../interfaces/ISchema";
-import { ILayoutManager } from "../interfaces/ILayoutManager";
-import { Engine } from "../core/Engine";
-import GeneratorHost from "../controls/host/GeneratorHost";
-import { SchemaNormalizer } from "../core/SchemaNormalizer";
-import { Logger } from "../utils/Logger";
-import { WIDGET_TYPE, SCHEMA_TYPE } from "../constants/MetaUIConstants";
-
-/**
- * Layout Manager responsible for generating a responsive SAP Fiori Table.
- * It is automatically utilized by the Engine when the schema root or property is of type 'array'.
- * Includes built-in support for adding and deleting rows via dynamic data binding manipulation.
- * 
- * @namespace nz.co.siliconst.ui5.metaui.layouts
- * @public
- */
-export class TableLayout implements ILayoutManager {
-    /**
-     * Renders the JSON Schema array properties into a UI5 Table.
-     * 
-     * @param schema The active JSON schema array definition.
-     * @param modelName The UI5 JSONModel name used for data binding.
-     * @param engine The central orchestrator for delegating column plugin generation.
-     * @param onSubmit Optional submit hook.
-     * @param bindingPath The JSON path representing the array within the payload.
-     * @returns {Control} The generated sap.m.Table control.
-     * @throws {Error} If the provided schema is not of type 'array'.
-     */
-    public render(schema: ISchema, modelName: string, engine: Engine, onSubmit?: () => void, bindingPath: string = "/"): Control {
-        let itemsSchema = schema.items;
-        if (itemsSchema && !itemsSchema.properties && itemsSchema.ui?.widget === WIDGET_TYPE.REFERENCE && itemsSchema.$ref) {
-            Logger.debug(`[MetaUI] TableLayout detecting reference widget for ${bindingPath}. Resolving ${itemsSchema.$ref}`, "", "TableLayout");
-            
-            const host = engine.host as unknown as GeneratorHost;
-            if (host && typeof host.getSchemaDefinition === "function") {
-                const resolved = host.getSchemaDefinition(itemsSchema.$ref);
-                Logger.debug(`[MetaUI] Resolved schema for ${itemsSchema.$ref}: ${!!resolved} ${resolved ? Object.keys(resolved) : ""}`, "", "TableLayout");
-                if (resolved && resolved.properties) {
-                    itemsSchema = resolved;
-                } else {
-                    Logger.error(`[MetaUI] TableLayout resolved schema but it has no properties!`, "", "TableLayout");
-                }
-            } else {
-                Logger.error(`[MetaUI] TableLayout cannot resolve ${itemsSchema.$ref} because engine.host.getSchemaDefinition is missing! host: ${host?.getMetadata().getName()}`, "", "TableLayout");
-            }
-        }
-
-        const isPrimitive = itemsSchema && !itemsSchema.properties && ["string", "number", "boolean"].includes(itemsSchema.type as string);
-        if (schema.type !== SCHEMA_TYPE.ARRAY || !itemsSchema || (!itemsSchema.properties && !isPrimitive)) {
-            Logger.error(`[MetaUI] TableLayout fatal error! schema.type: ${schema.type}, itemsSchema: ${!!itemsSchema}, properties: ${itemsSchema ? !!itemsSchema.properties : false}`, "", "TableLayout");
-            throw new Error("[MetaUI] TableLayout requires an array schema with items.properties or primitive items.");
-        }
-
-        const createSkeleton = (meta: ISchema | IPropertyMetadata): any => {
-            if (meta.type === "object" && meta.properties) {
-                const obj: any = {};
-                for (const key of Object.keys(meta.properties)) {
-                    obj[key] = createSkeleton(meta.properties[key] as ISchema | IPropertyMetadata);
-                }
-                return obj;
-            } else if (meta.type === "array") {
-                return [];
-            } else if (meta.type === "string") {
-                return (meta as any).default !== undefined ? (meta as any).default : ((meta as any).enum ? (meta as any).enum[0] : "");
-            } else if (meta.type === "number") {
-                return (meta as any).default !== undefined ? (meta as any).default : 0;
-            } else if (meta.type === "boolean") {
-                return (meta as any).default !== undefined ? (meta as any).default : false;
-            }
-            return "";
-        };
-
-        const tableTitle = schema.title || "Table";
-        const actualModelName = modelName;
-        const actualPath = bindingPath;
-
-        const table = new Table({
-            headerToolbar: new Toolbar({
-                content: [
-                    new Title({ text: tableTitle }),
-                    new ToolbarSpacer(),
-                    ...(!engine.isEditable ? [] : [
-                        new Button({
-                            text: "Add Row",
-                            icon: "sap-icon://add",
-                            press: (oEvent: sap.ui.base.Event) => {
-                                const btn = oEvent.getSource() as Button;
-                                const tbl = btn.getParent()?.getParent() as Table;
-                                const model = tbl.getModel(actualModelName) as JSONModel;
-                                const info = tbl.getBindingInfo("items");
-                                if (!info || !info.path) return;
-
-                                const rawData = model.getProperty(info.path);
-                                const data = Array.isArray(rawData) ? rawData : [];
-                                const newData = [...data, createSkeleton(itemsSchema)];
-                                model.setProperty(info.path, newData);
-
-                                // CRITICAL: Notify the engine so it extracts payload and triggers liveUpdate
-                                if (engine.onChange) {
-                                    engine.onChange(true, actualPath.replace(/^\//, ""));
-                                }
-                            }
-                        })
-                    ])
-                ]
-            }),
-            fixedLayout: false,
-            mode: !engine.isEditable ? "None" : "Delete",
-            delete: (oEvent: sap.ui.base.Event) => {
-                const item = oEvent.getParameter("listItem") as ColumnListItem;
-                const path = item.getBindingContext(actualModelName)?.getPath();
-                if (!path) return;
-                const model = item.getModel(actualModelName) as JSONModel;
-
-                const splitPaths = path.split("/");
-                const index = parseInt(splitPaths.pop() || "0", 10);
-                let arrayPath = splitPaths.join("/");
-                if (arrayPath === "") arrayPath = "/";
-
-                const rawData = model.getProperty(arrayPath);
-                const data = Array.isArray(rawData) ? rawData : [];
-                const newData = [...data];
-                newData.splice(index, 1);
-                model.setProperty(arrayPath, newData);
-
-                // CRITICAL: Notify the engine so it extracts payload and triggers liveUpdate
-                if (engine.onChange) {
-                    engine.onChange(true, actualPath.replace(/^\//, ""));
-                }
-
-                // CRITICAL: Clear ghost errors that shifted due to array mutation
-                if (typeof (engine as any).onArrayMutated === "function") {
-                    (engine as any).onArrayMutated(arrayPath);
-                }
-            }
-        });
-
-        const templateCells: Control[] = [];
-        const props = itemsSchema.properties;
-        const layoutElements = schema.uiLayout;
-
-        if (isPrimitive) {
-            table.addColumn(new Column({
-                header: new Text({ text: "Value" })
-            }));
-            const control = engine.generateField(itemsSchema as IPropertyMetadata, "", actualModelName || "meta", true);
-            templateCells.push(control);
-        } else if (layoutElements && Array.isArray(layoutElements)) {
-            // Only render columns defined in uiLayout
-            layoutElements.forEach((element: ILayoutElement) => {
-                if (element.type === "Control" && element.scope) {
-                    const { meta: fieldMeta, bindingPath, propKey } = SchemaNormalizer.resolveScope(
-                        { type: "object", properties: props } as ISchema, 
-                        element.scope
-                    );
-                    
-                    if (!fieldMeta) {
-                        Logger.error(`[MetaUI] Property '${propKey}' not found in schema definitions for Table.`, "", "TableLayout");
-                    } else {
-                        // The architectural boundary: Table Layout orchestrates the columns and aggregation binding,
-                        // but delegates the actual cell rendering to the Engine's Field Plugins.
-                        table.addColumn(new Column({
-                            header: new Text({ text: element.label || fieldMeta.ui?.label || propKey }),
-                            demandPopin: !fieldMeta.ui?.isKey,
-                            minScreenWidth: fieldMeta.ui?.isKey ? "" : "Tablet",
-                            popinDisplay: "Inline"
-                        }));
-
-                        const effectiveMeta = { ...fieldMeta };
-                        if (element.widget) {
-                            effectiveMeta.ui = { ...fieldMeta.ui, widget: element.widget };
-                        }
-
-                        // We pass the activeModel as actualModelName down. But the path must be relative to the 
-                        // table row binding context, so we just use the bindingPath (e.g. "id" or "header/id")
-                        const control = engine.generateField(effectiveMeta, bindingPath, actualModelName || "meta", true);
-                        templateCells.push(control);
-                    }
-                } else {
-                    Logger.warn(`[MetaUI] Unsupported layout element type '${element.type}' in Table.`, "", "TableLayout");
-                }
-            });
-        } else {
-            Logger.debug("[MetaUI TableLayout]", "No uiLayout provided. Falling back to rendering all properties as columns.", "TableLayout");
-            // Fallback: If no uiLayout is provided, render all properties as columns
-            Object.keys(props).forEach((key) => {
-                try {
-                    const fieldMeta = props[key];
-                    const isKey = !!fieldMeta.ui?.isKey;
-
-                    const column = new Column({
-                        header: new Text({ text: fieldMeta.ui?.label || key }),
-                        demandPopin: !isKey,
-                        minScreenWidth: isKey ? "" : "Tablet",
-                        popinDisplay: "Inline"
-                    });
-                    table.addColumn(column);
-
-                    const control = engine.generateField(fieldMeta, key, actualModelName || "meta", true);
-                    templateCells.push(control);
-                } catch (error) {
-                    const msg = (error as Error).message;
-                    Logger.error(`[MetaUI] Failed to render fallback column ${key}`, msg, "TableLayout");
-                    Logger.showErrorPopup(`Failed to render fallback table column '${key}'.\n\nDetails: ${msg}`);
-                    templateCells.push(new Text({ text: "Error" }));
-                }
-            });
-        }
-
-
-
-        const rowTemplate = new ColumnListItem({
-            cells: templateCells
-        });
-
-        table.bindItems({
-            path: actualPath,
-            model: actualModelName,
-            template: rowTemplate,
-            templateShareable: false
-        });
-
-        return table;
-    }
-}
+/**
+ * @file TableLayout.ts
+ * @description Generates a responsive SAP Fiori Table layout for v2 array schemas.
+ */
+
+import Table from "sap/m/Table";
+import Column from "sap/m/Column";
+import Label from "sap/m/Label";
+import Text from "sap/m/Text";
+import ColumnListItem from "sap/m/ColumnListItem";
+import Toolbar from "sap/m/Toolbar";
+import Title from "sap/m/Title";
+import ToolbarSpacer from "sap/m/ToolbarSpacer";
+import Button from "sap/m/Button";
+import Control from "sap/ui/core/Control";
+import Event from "sap/ui/base/Event";
+import { ListMode, PopinDisplay } from "sap/m/library";
+import { IPropertyMetadata, ISchema, ILayoutElement } from "../interfaces/ISchema";
+import { ILayoutManager } from "../interfaces/ILayoutManager";
+import { Engine } from "../core/Engine";
+import { TableRowHelper } from "./TableRowHelper";
+import { ControlDirectiveUtil } from "../utils/ControlDirectiveUtil";
+import { AccessibilityUtil } from "../utils/AccessibilityUtil";
+import { Logger } from "../utils/Logger";
+import { I18n, TEXT_KEY } from "../utils/I18n";
+import { SCHEMA_TYPE } from "../constants/MetaUIConstants";
+import { isRecord } from "../utils/TypeGuards";
+import { LayoutElementWalker, LayoutFieldFactory } from "./LayoutElementWalker";
+
+/**
+ * Layout Manager responsible for generating a responsive SAP Fiori Table.
+ * Automatically utilized by the Engine when the schema root or property is of type `'array'`.
+ * Includes built-in support for adding and deleting rows via dynamic data binding manipulation.
+ *
+ * @namespace nz.co.siliconst.ui5.metaui.layouts
+ * @internal
+ */
+export class TableLayout implements ILayoutManager {
+    /**
+     * Rows drawn per page by the generated table's `growing` feature.
+     *
+     * The sandbox model no longer caps a list binding at UI5's default of 100 contexts, so every row a
+     * consumer passes is now reachable. Drawing all of them at once is what that costs: measured with
+     * `benchmark/run-benchmarks.js --only=table` on an uncapped model, a 1000-row table takes 754 ms at
+     * 3 columns and **3782 ms at 15 columns** — a multi-second main-thread freeze on load, which is a
+     * worse defect than the truncation it replaced because the user can see it happen.
+     *
+     * Paging at 100 brings first paint back to the cost of a 100-row table (55 ms / 182 ms / 332 ms at
+     * 3 / 8 / 15 columns, measured) while the remaining rows stay reachable behind the growing trigger.
+     * 100 specifically, because it is the window the consumer's users already see today: it was UI5's
+     * silent cap, so the first screenful is unchanged and only the previously-discarded remainder moves.
+     */
+    public static readonly GROWING_PAGE_SIZE = 100;
+
+    /**
+     * Renders the JSON Schema array properties into a UI5 Table.
+     *
+     * @param schema The active JSON schema array definition.
+     * @param modelName The UI5 JSONModel name used for data binding.
+     * @param engine The central orchestrator for delegating column plugin generation.
+     * @param _onSubmit Optional submit hook.
+     * @param bindingPath The JSON path representing the array within the payload.
+     * @returns {Control} The generated `sap.m.Table` control.
+     * @throws {Error} If the provided schema is not of type `'array'`.
+     */
+    public render(
+        schema: ISchema,
+        modelName: string,
+        engine: Engine,
+        _onSubmit?: () => void,
+        bindingPath: string = "/"
+    ): Control {
+        const itemsSchema = TableRowHelper.resolveItemsSchema(schema, engine, bindingPath);
+        const isPrimitive = Boolean(
+            itemsSchema &&
+                !itemsSchema.properties &&
+                ["string", "number", "integer", "boolean"].includes(itemsSchema.type as string)
+        );
+
+        if (schema.type !== SCHEMA_TYPE.ARRAY || !itemsSchema || (!itemsSchema.properties && !isPrimitive)) {
+            Logger.error(
+                `[MetaUI] TableLayout fatal error! schema.type: ${schema.type}, itemsSchema: ${!!itemsSchema}`,
+                "",
+                "TableLayout"
+            );
+            throw new Error("[MetaUI] TableLayout requires an array schema with items.properties or primitive items.");
+        }
+
+        const resolvedItemsSchema: IPropertyMetadata = itemsSchema;
+        const tableTitle = schema.title || schema.ui?.label || I18n.getText(TEXT_KEY.tableDefaultTitle);
+        const canEditTable =
+            engine.isEditable && !schema.readOnly && !schema.ui?.readOnly && schema.ui?.enabled !== false;
+
+        let effectiveBindingPath = bindingPath;
+        if (bindingPath === "/") {
+            const activeModel = engine.getModel() as { getData?: () => unknown } | undefined;
+            const rootData = typeof activeModel?.getData === "function" ? activeModel.getData() : undefined;
+            if (!Array.isArray(rootData) && isRecord(rootData) && Array.isArray(rootData.items)) {
+                effectiveBindingPath = "/items";
+            }
+        }
+
+        const addRowBtn = new Button({
+            text: I18n.getText(TEXT_KEY.tableAddRow),
+            icon: "sap-icon://add",
+            visible: canEditTable,
+            press: (oEvent: Event) => {
+                const btn = oEvent.getSource() as Button;
+                const tbl = btn.getParent()?.getParent() as Table | undefined;
+                TableRowHelper.addRow(tbl, modelName, resolvedItemsSchema, engine, effectiveBindingPath, schema);
+            }
+        });
+        addRowBtn.data("metauiTableAddBtn", true);
+
+        const titleControl = new Title({ text: tableTitle });
+        const table = new Table({
+            headerToolbar: new Toolbar({
+                content: [titleControl, new ToolbarSpacer(), addRowBtn]
+            }),
+            fixedLayout: false,
+            growing: true,
+            growingThreshold: TableLayout.GROWING_PAGE_SIZE,
+            // Deliberately false. With `true` the remaining rows load on scroll, which inside a
+            // non-scrolling container means they never load and nothing says so - the shape of the
+            // original defect. With `false` UI5 renders an explicit trigger whose counter reads
+            // "[ 100 / 1000 ]", and that counter is the disclosure: it is what tells the user rows
+            // exist beyond the ones drawn, and how many. `growingTriggerText` is left unset so the
+            // button keeps sap.m's own translated "More" rather than an English literal.
+            growingScrollToLoad: false,
+            mode: !canEditTable ? ListMode.None : ListMode.Delete,
+            delete: (oEvent: Event) => {
+                const params = oEvent.getParameters() as { listItem?: ColumnListItem };
+                TableRowHelper.deleteRow(params.listItem, modelName, engine, effectiveBindingPath, schema);
+            }
+        });
+        table.data("metauiBindingPath", effectiveBindingPath);
+        // The toolbar title names the table visually; the grid itself has no accessible name until the
+        // application supplies one, which for a generated table is MetaUI's job and nobody else's.
+        AccessibilityUtil.associateAriaLabel(table, titleControl);
+        if (schema.ui?.visible === false || schema.ui?.visibleOn) {
+            ControlDirectiveUtil.applyCommonDirectives(
+                table,
+                table,
+                { type: "array", ui: { visible: schema.ui.visible, visibleOn: schema.ui.visibleOn } },
+                effectiveBindingPath,
+                canEditTable,
+                modelName
+            );
+        }
+
+        const templateCells = this.buildColumnsAndCells(
+            table,
+            schema,
+            resolvedItemsSchema,
+            isPrimitive,
+            modelName,
+            engine,
+            canEditTable
+        );
+
+        table.bindItems({
+            path: effectiveBindingPath,
+            model: modelName,
+            template: new ColumnListItem({ cells: templateCells }),
+            templateShareable: false
+        });
+
+        return table;
+    }
+
+    /**
+     * Populates the `sap.m.Table` columns (with accessible `sap.m.Label` headers and `required` indicators)
+     * and generates the corresponding cell template controls.
+     *
+     * @param table The target `sap.m.Table` control.
+     * @param schema The array schema.
+     * @param resolvedItemsSchema The resolved `items` metadata.
+     * @param isPrimitive True if the array items are primitives rather than objects.
+     * @param modelName The UI5 JSONModel alias.
+     * @param engine The owning `Engine` instance.
+     * @param canEditTable True if the table allows editing.
+     * @returns {Control[]} The array of template cell controls for `ColumnListItem`.
+     */
+    private buildColumnsAndCells(
+        table: Table,
+        schema: ISchema,
+        resolvedItemsSchema: IPropertyMetadata,
+        isPrimitive: boolean,
+        modelName: string,
+        engine: Engine,
+        canEditTable: boolean = true
+    ): Control[] {
+        const templateCells: Control[] = [];
+        const props = resolvedItemsSchema.properties;
+        const layoutElements = schema.uiLayout || resolvedItemsSchema.uiLayout;
+        const effectiveModel = modelName || "meta";
+
+        const withTableReadOnly = (meta: IPropertyMetadata, widgetOverride?: string): IPropertyMetadata => {
+            return LayoutFieldFactory.cloneFieldMetadata(meta, widgetOverride, !canEditTable);
+        };
+
+        if (isPrimitive) {
+            const valueHeader = I18n.getText(TEXT_KEY.tableValueColumn);
+            table.addColumn(
+                new Column({
+                    header: new Label({ text: valueHeader, required: resolvedItemsSchema.required === true && canEditTable })
+                })
+            );
+            const primitiveCell = engine.generateField(withTableReadOnly(resolvedItemsSchema), "", effectiveModel, true);
+            AccessibilityUtil.nameCellByColumnHeader(primitiveCell, valueHeader);
+            templateCells.push(primitiveCell);
+            return templateCells;
+        }
+
+        const hasExplicitKey = props
+            ? Object.values(props).some((p) => Boolean(p.ui?.isKey))
+            : false;
+
+        if (layoutElements && Array.isArray(layoutElements)) {
+            let renderedColIndex = 0;
+            const itemObjectSchema: ISchema = { type: "object", properties: props };
+            const controlCount = LayoutElementWalker.walk(
+                layoutElements,
+                itemObjectSchema,
+                engine,
+                {
+                    onScalarField: (element: ILayoutElement, colBindingPath: string, fieldMeta: IPropertyMetadata) => {
+                        const isAnchor = Boolean(fieldMeta.ui?.isKey) || (!hasExplicitKey && renderedColIndex === 0);
+                        renderedColIndex++;
+                        const headerText = element.label || fieldMeta.ui?.label || colBindingPath;
+                        table.addColumn(
+                            new Column({
+                                header: new Label({
+                                    text: headerText,
+                                    required: fieldMeta.required === true && canEditTable
+                                }),
+                                demandPopin: !isAnchor,
+                                minScreenWidth: isAnchor ? "" : "Tablet",
+                                popinDisplay: PopinDisplay.Inline
+                            })
+                        );
+                        const effectiveMeta = withTableReadOnly(fieldMeta, element.widget);
+                        const cell = engine.generateField(effectiveMeta, colBindingPath, effectiveModel, true);
+                        AccessibilityUtil.nameCellByColumnHeader(cell, headerText);
+                        templateCells.push(cell);
+                    }
+                },
+                "TableLayout"
+            );
+            if (controlCount > 0) {
+                return templateCells;
+            }
+            Logger.warn(
+                "[MetaUI] Table uiLayout contains no Control elements; falling back to item properties.",
+                "",
+                "TableLayout"
+            );
+        }
+
+        if (props) {
+            Object.keys(props).forEach((key, colIdx) => {
+                try {
+                    const fieldMeta = withTableReadOnly(props[key]);
+                    const isAnchor = Boolean(fieldMeta.ui?.isKey) || (!hasExplicitKey && colIdx === 0);
+                    const headerText = fieldMeta.ui?.label || key;
+                    table.addColumn(
+                        new Column({
+                            header: new Label({
+                                text: headerText,
+                                required: fieldMeta.required === true && canEditTable
+                            }),
+                            demandPopin: !isAnchor,
+                            minScreenWidth: isAnchor ? "" : "Tablet",
+                            popinDisplay: PopinDisplay.Inline
+                        })
+                    );
+                    const cell = engine.generateField(fieldMeta, key, effectiveModel, true);
+                    // A row cell has no label of its own. UI5 associates the column header with a plain
+                    // cell control; a composite cell is the case it cannot reach.
+                    AccessibilityUtil.nameCellByColumnHeader(cell, headerText);
+                    templateCells.push(cell);
+                } catch (error) {
+                    engine.hasPartialRenderingErrors = true;
+                    const msg = (error as Error).message;
+                    Logger.error(`[MetaUI] Failed to render fallback column ${key}`, msg, "TableLayout");
+                    Logger.showErrorPopup(`Failed to render fallback table column '${key}'.\n\nDetails: ${msg}`);
+                    templateCells.push(new Text({ text: "Error" }));
+                }
+            });
+        }
+
+        return templateCells;
+    }
+}