ng-hub-ui-spreadsheet 22.0.0

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "ng-hub-ui-spreadsheet",
+  "version": "22.0.0",
+  "license": "MIT",
+  "description": "Excel-like editable spreadsheet for Angular: in-cell editing, full keyboard navigation, rectangular range selection and a clipboard that round-trips with Excel. Accessible, themable through CSS variables and free of paid tiers. Part of the ng-hub-ui family.",
+  "author": "Carlos Morcillo Fernández <carlos.morcillo@me.com> (https://www.carlosmorcillo.com)",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hub-env/ng-hub-ui-spreadsheet.git"
+  },
+  "bugs": {
+    "url": "https://github.com/hub-env/hub-ui/issues"
+  },
+  "homepage": "https://hubui.dev/en/spreadsheet/overview/",
+  "keywords": [
+    "angular",
+    "spreadsheet",
+    "data-grid",
+    "editable-table",
+    "excel",
+    "clipboard",
+    "cell-editing",
+    "range-selection",
+    "accessibility",
+    "ng-hub-ui",
+    "standalone",
+    "signals"
+  ],
+  "peerDependencies": {
+    "@angular/common": ">=22.0.0",
+    "@angular/core": ">=22.0.0",
+    "ng-hub-ui-ds": ">=22.0.0",
+    "ng-hub-ui-utils": ">=22.18.0",
+    "@angular/forms": ">=22.0.0"
+  },
+  "peerDependenciesMeta": {
+    "ng-hub-ui-ds": {
+      "optional": true
+    },
+    "@angular/forms": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "tslib": "^2.3.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": false,
+  "module": "fesm2022/ng-hub-ui-spreadsheet.mjs",
+  "typings": "types/ng-hub-ui-spreadsheet.d.ts",
+  "exports": {
+    "./package.json": {
+      "default": "./package.json"
+    },
+    ".": {
+      "types": "./types/ng-hub-ui-spreadsheet.d.ts",
+      "default": "./fesm2022/ng-hub-ui-spreadsheet.mjs"
+    },
+    "./signals": {
+      "types": "./types/ng-hub-ui-spreadsheet-signals.d.ts",
+      "default": "./fesm2022/ng-hub-ui-spreadsheet-signals.mjs"
+    }
+  },
+  "type": "module"
+}

package/types/ng-hub-ui-spreadsheet-signals.d.ts

@@ -0,0 +1,125 @@
+import * as _angular_core from '@angular/core';
+import { FormValueControl, ValidationError, FieldTree } from '@angular/forms/signals';
+import { HubGridSpan, HubGridRange } from 'ng-hub-ui-utils';
+import { HubSpreadsheetColumn, HubSpreadsheetCellState, HubSpreadsheetCommit, HubSpreadsheetPaste, HubSpreadsheetCellRef } from 'ng-hub-ui-spreadsheet';
+
+/**
+ * A sheet that is a form control: its value is the rows.
+ *
+ * Bind it with the `FormField` directive and the rows become the field's value, written back on
+ * every edit, paste and clearing. Because the contract is Angular's own
+ * {@link FormValueControl}, the same component also works inside reactive and template-driven
+ * forms — Angular's migration guide says as much, and forbids implementing the old
+ * `ControlValueAccessor` alongside it.
+ *
+ * **What this shape cannot do, and why it is not the only one.** A control bound to a collection
+ * receives that field's own errors and never its descendants'. A rule declared with `applyEach`
+ * on the rows therefore produces errors this component will not see, and per-cell validation is
+ * the whole point of an editable sheet. When you need it, keep `<hub-spreadsheet>` bound to your
+ * own rows and feed its `errors` input — `spreadsheetFieldErrors()` maps a field tree onto the
+ * map it expects.
+ */
+declare class HubSpreadsheetFieldComponent<TRow extends object> implements FormValueControl<TRow[]> {
+    /** The rows, as the field's value. Written back whenever the reader changes a cell. */
+    readonly value: _angular_core.ModelSignal<TRow[]>;
+    /** What each column shows and allows. */
+    readonly columns: _angular_core.InputSignal<readonly HubSpreadsheetColumn<TRow>[]>;
+    /** A stable name per row. */
+    readonly rowKey: _angular_core.InputSignal<(row: TRow) => string>;
+    /** The save state of each cell. */
+    readonly states: _angular_core.InputSignal<Record<string, HubSpreadsheetCellState>>;
+    /** The character this reader types decimals with. */
+    readonly decimalMark: _angular_core.InputSignal<"," | ".">;
+    /** What an empty sheet says. */
+    readonly emptyText: _angular_core.InputSignal<string>;
+    /** How many rows Page Up and Page Down travel. */
+    readonly pageSize: _angular_core.InputSignal<number>;
+    /** Turns off every editor, whatever the cells say. */
+    readonly readonly: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** How many columns stay pinned to the leading edge. */
+    readonly frozenColumns: _angular_core.InputSignal<number>;
+    /** How many rows stay pinned below the header. */
+    readonly frozenRows: _angular_core.InputSignal<number>;
+    /** Merged blocks. */
+    readonly spans: _angular_core.InputSignal<readonly HubGridSpan[]>;
+    /**
+     * Bound by the `FormField` directive. Only the array field's own errors arrive here, which is
+     * why they are shown as a whole rather than attributed to a cell.
+     */
+    readonly errors: _angular_core.InputSignal<readonly ValidationError.WithOptionalFieldTree[]>;
+    /** Bound by the `FormField` directive; disables every editor. */
+    readonly disabled: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** The selected rectangle changed. */
+    readonly selectionChange: _angular_core.OutputEmitterRef<HubGridRange | null>;
+    /**
+     * The sheet's own per-cell error map.
+     *
+     * Empty here on purpose: this shape has no per-cell errors to give. It exists so the inner
+     * component's input is always bound to something, and so a future release can fill it without
+     * changing the template.
+     */
+    protected readonly cellErrors: _angular_core.Signal<Record<string, string>>;
+    protected onCommit(change: HubSpreadsheetCommit<TRow>): void;
+    protected onPaste(paste: HubSpreadsheetPaste<TRow>): void;
+    protected onCleared(cells: readonly HubSpreadsheetCellRef<TRow>[]): void;
+    private write;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<HubSpreadsheetFieldComponent<any>, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<HubSpreadsheetFieldComponent<any>, "hub-spreadsheet-field", never, { "value": { "alias": "value"; "required": false; "isSignal": true; }; "columns": { "alias": "columns"; "required": true; "isSignal": true; }; "rowKey": { "alias": "rowKey"; "required": true; "isSignal": true; }; "states": { "alias": "states"; "required": false; "isSignal": true; }; "decimalMark": { "alias": "decimalMark"; "required": false; "isSignal": true; }; "emptyText": { "alias": "emptyText"; "required": false; "isSignal": true; }; "pageSize": { "alias": "pageSize"; "required": false; "isSignal": true; }; "readonly": { "alias": "readonly"; "required": false; "isSignal": true; }; "frozenColumns": { "alias": "frozenColumns"; "required": false; "isSignal": true; }; "frozenRows": { "alias": "frozenRows"; "required": false; "isSignal": true; }; "spans": { "alias": "spans"; "required": false; "isSignal": true; }; "errors": { "alias": "errors"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; }, { "value": "valueChange"; "selectionChange": "selectionChange"; }, never, never, true, never>;
+}
+
+/**
+ * Turns a field tree over rows into the per-cell error map `<hub-spreadsheet>` reads.
+ *
+ * This is the piece that makes per-cell validation work, and it exists because of a limit in the
+ * framework rather than a preference: a control bound to a collection is handed that field's own
+ * errors and never its descendants'. Rules declared with `applyEach` therefore land on the row
+ * fields, one level below anything the sheet could see for itself.
+ *
+ * So the host keeps the field tree, and this walks it: for each row and each column, it reads
+ * that field's errors and writes the first message under the key the sheet addresses cells by.
+ *
+ * ```ts
+ * readonly form = form(this.lines, (path) => {
+ *   applyEach(path, (line) => {
+ *     min(line.units, 1, { message: 'At least one unit' });
+ *   });
+ * });
+ *
+ * protected readonly cellErrors = computed(() =>
+ *   spreadsheetFieldErrors(this.form, this.lines(), this.columns, (row) => row.id)
+ * );
+ * ```
+ *
+ * @param form The field tree over the rows.
+ * @param rows The rows themselves, in the same order.
+ * @param columns The sheet's columns; only aliases that name a field are looked up.
+ * @param rowKey How the sheet names a row, so the keys line up with `states`.
+ * @param touchedOnly Whether to report only fields the reader has visited. True by default: an
+ *   untouched form that paints itself red the moment it renders is a form nobody trusts.
+ */
+declare function spreadsheetFieldErrors<TRow extends object>(form: FieldTree<TRow[]>, rows: readonly TRow[], columns: readonly HubSpreadsheetColumn<TRow>[], rowKey: (row: TRow) => string, touchedOnly?: boolean): Record<string, string>;
+/**
+ * Marks the field behind a cell as visited.
+ *
+ * Errors are held back until a cell has been touched, and a sheet has no way to report that on
+ * its own: the `FormField` directive learns it from a control's `touch` output, and a sheet
+ * driven through `errors` is not bound to a field at all. So the host says it, from the
+ * `commit`, `pasted` and `cleared` handlers it already writes.
+ *
+ * Without this call, `spreadsheetFieldErrors()` in its default mode reports nothing and no cell
+ * is ever marked — which looks exactly like validation that does not work.
+ *
+ * ```ts
+ * protected onCommit(change: HubSpreadsheetCommit<Line>): void {
+ *   this.lines.update(...);
+ *   touchSpreadsheetField(this.orderForm, change.coords.row, change.column.key);
+ * }
+ * ```
+ *
+ * @param form The field tree over the rows.
+ * @param row The row index of the cell.
+ * @param columnKey The column's alias.
+ */
+declare function touchSpreadsheetField<TRow extends object>(form: FieldTree<TRow[]>, row: number, columnKey: string): void;
+
+export { HubSpreadsheetFieldComponent, spreadsheetFieldErrors, touchSpreadsheetField };