@lavalogic/scoria 0.36.0 → 0.37.0

package/dist/Components/Table/Types/Context/SortingState.svelte.d.ts

@@ -0,0 +1,112 @@
+import type { ColumnDef } from '../Columns/Definitions/ColumnDef.svelte.js';
+import { PaginationType } from '../Pagination/PaginationType.js';
+import type { SortingState as SortingStateArray } from '../DataRepository/SortingState.js';
+/**
+ * Comparator factory for any column whose stored row values implement the
+ * `<` / `>` operators natively (strings, numbers, Dates). Used by
+ * `DisplayDef`, `TextInputDef`, `NumberInputDef`, `DateInputDef`, and
+ * `SelectDef`. The desc flag is captured at builder time so the inner
+ * comparator pays no extra branching per comparison.
+ *
+ * Lifted out of `TableContext.svelte.ts` during Phase 6.1 god-object
+ * decomposition; the closure shape and return values are unchanged.
+ */
+export declare function comparableSortingFn<T>(id: keyof T, desc: boolean): (a: T, b: T) => -1 | 0 | 1;
+/**
+ * Comparator factory for `CheckboxDef` columns. Boolean-coercion compares
+ * truthy-vs-falsy so undefined / null / 0 collapse to "unchecked".
+ *
+ * Lifted from `TableContext.svelte.ts` during Phase 6.1.
+ */
+export declare function checkboxSortingFn<T>(id: keyof T, desc: boolean): (a: T, b: T) => -1 | 0 | 1;
+/**
+ * Comparator factory for `ProgressBarDef` columns. The stored value is a
+ * `[min, max]` tuple and the comparison is performed on `min / max` (the
+ * fractional completion). Zero-`max` and undefined endpoints sort to the
+ * bottom in ascending order (and to the top in descending order) so empty
+ * progress bars cluster together.
+ *
+ * Lifted from `TableContext.svelte.ts` during Phase 6.1.
+ */
+export declare function progressSortingFn<T>(id: keyof T, desc: boolean): (a: T, b: T) => -1 | 0 | 1;
+/**
+ * Dependency surface that `SortingState` reads from the surrounding
+ * `TableContext`. All dependencies are passed as thunks so the sub-context
+ * does not hold a reference to the parent and the reactivity graph
+ * remains thread through `$derived` rather than through method calls on a
+ * shared object.
+ */
+export interface SortingStateDeps<T extends object> {
+    /** Snapshot of the column-defs map keyed by `def.id`. */
+    getColumnDefsById: () => ReadonlyMap<string, ColumnDef<T>>;
+    /** Filtered (but not yet sorted) row array. */
+    getFilteredData: () => Array<T>;
+    /** Current sort instruction list, ordered by precedence. */
+    getSortingArray: () => SortingStateArray;
+    /** Pagination mode; only `Local` triggers in-process sorting. */
+    getPaginationType: () => PaginationType | undefined;
+    /** Row-data length; used to short-circuit comparator construction when
+     *  the repository is empty. */
+    getDataLength: () => number;
+    /** Logger gate; mirrors the parent `TableContext.debug` field. */
+    getDebug: () => boolean;
+}
+/**
+ * Phase 6.1 god-object decomposition - sub-context that owns the
+ * sort-related derived chain (`sortedData`), the per-`ColumnDef`
+ * comparator dispatch (`getSortingFn`), and the comparator-hoist
+ * optimisation that lifts the `instanceof` cascade out of the
+ * `.sort()` callback.
+ *
+ * `TableContext` retains delegating getters / methods for backwards
+ * compatibility; future consumers can read `tableContext._sorting`
+ * directly once the migration is complete (see
+ * `src/stories/Concepts/TableContext-decomposition.mdx`).
+ */
+export declare class SortingState<T extends object> {
+    private readonly _deps;
+    private _sortedDataAbortController;
+    /**
+     * @param deps thunks the sub-context reads from the parent.
+     *             Constructor-only - no implicit setup so the parent
+     *             remains in control of effect ownership.
+     */
+    constructor(deps: SortingStateDeps<T>);
+    /**
+     * Resolve the comparator for a single column. Order of resolution:
+     *
+     * 1. `def.getSortingFn(desc)` if the column declares one.
+     * 2. `comparableSortingFn` for `DisplayDef` / `TextInputDef` /
+     *    `NumberInputDef` / `DateInputDef` / `SelectDef`.
+     * 3. `checkboxSortingFn` for `CheckboxDef`.
+     * 4. `progressSortingFn` for `ProgressBarDef`.
+     * 5. Fallback: `comparableSortingFn`.
+     *
+     * Returns `undefined` only when the data repository is empty (so the
+     * `.sort()` caller can skip without warning) or when the column id is
+     * not in the current `columnDefsById` map.
+     *
+     * Public so the comparator dispatch can be unit-tested independently
+     * of the `sortedData` derived chain.
+     */
+    getSortingFn(id: string & keyof T, desc: boolean): ((a: T, b: T) => number) | undefined;
+    /**
+     * Sorted view of the filtered data. When `paginationType` is `Local`
+     * the array is `filteredData.concat().sort(...)` with comparators
+     * resolved through `getSortingFn`. For all other modes the upstream
+     * `filteredData` is returned untouched (remote sort applies on the
+     * server).
+     *
+     * Performance: the per-column `instanceof` cascade inside
+     * `getSortingFn` is paid O(columns) times per re-sort instead of
+     * O(n log n) - the comparator array is materialised once before the
+     * `.sort()` callback. Lifted from `TableContext.sortedData` in
+     * Phase-5 Group 2 (workorder P0); preserved verbatim here.
+     *
+     * Abort semantics: when `filteredData` or `sortingState` changes
+     * mid-sort the previous controller is aborted and the in-flight
+     * comparator returns `0` to short-circuit. The `$derived` re-runs
+     * immediately afterwards and produces the up-to-date array.
+     */
+    readonly sortedData: T[];
+}

package/dist/Components/Table/Types/Context/SortingState.svelte.js

@@ -0,0 +1,272 @@
+import { dev } from '$app/environment';
+import { CheckboxDef } from '../Columns/Definitions/Accessors/CheckboxDef.svelte.js';
+import { DateInputDef } from '../Columns/Definitions/Accessors/DateInputDef.svelte.js';
+import { NumberInputDef } from '../Columns/Definitions/Accessors/NumberInputDef.svelte.js';
+import { SelectDef } from '../Columns/Definitions/Accessors/SelectDef.svelte.js';
+import { TextInputDef } from '../Columns/Definitions/Accessors/TextInputDef.svelte.js';
+import { DisplayDef } from '../Columns/Definitions/Display/DisplayDef.svelte.js';
+import { ProgressBarDef } from '../Columns/Definitions/Display/ProgressBarDef.svelte.js';
+import { PaginationType } from '../Pagination/PaginationType.js';
+/**
+ * Comparator factory for any column whose stored row values implement the
+ * `<` / `>` operators natively (strings, numbers, Dates). Used by
+ * `DisplayDef`, `TextInputDef`, `NumberInputDef`, `DateInputDef`, and
+ * `SelectDef`. The desc flag is captured at builder time so the inner
+ * comparator pays no extra branching per comparison.
+ *
+ * Lifted out of `TableContext.svelte.ts` during Phase 6.1 god-object
+ * decomposition; the closure shape and return values are unchanged.
+ */
+export function comparableSortingFn(id, desc) {
+    return desc
+        ? (a, b) => {
+            if (a[id] == undefined && b[id] != undefined) {
+                return 1;
+            }
+            if (b[id] == undefined && a[id] != undefined) {
+                return -1;
+            }
+            if (a[id] < b[id]) {
+                return 1;
+            }
+            if (a[id] > b[id]) {
+                return -1;
+            }
+            return 0;
+        }
+        : (a, b) => {
+            if (a[id] == undefined && b[id] != undefined) {
+                return 1;
+            }
+            if (b[id] == undefined && a[id] != undefined) {
+                return -1;
+            }
+            if (a[id] < b[id]) {
+                return -1;
+            }
+            if (a[id] > b[id]) {
+                return 1;
+            }
+            return 0;
+        };
+}
+/**
+ * Comparator factory for `CheckboxDef` columns. Boolean-coercion compares
+ * truthy-vs-falsy so undefined / null / 0 collapse to "unchecked".
+ *
+ * Lifted from `TableContext.svelte.ts` during Phase 6.1.
+ */
+export function checkboxSortingFn(id, desc) {
+    return desc
+        ? (a, b) => {
+            if (a[id] && !b[id]) {
+                return 1;
+            }
+            if (!a[id] && b[id]) {
+                return -1;
+            }
+            return 0;
+        }
+        : (a, b) => {
+            if (a[id] && !b[id]) {
+                return -1;
+            }
+            if (!a[id] && b[id]) {
+                return 1;
+            }
+            return 0;
+        };
+}
+/**
+ * Comparator factory for `ProgressBarDef` columns. The stored value is a
+ * `[min, max]` tuple and the comparison is performed on `min / max` (the
+ * fractional completion). Zero-`max` and undefined endpoints sort to the
+ * bottom in ascending order (and to the top in descending order) so empty
+ * progress bars cluster together.
+ *
+ * Lifted from `TableContext.svelte.ts` during Phase 6.1.
+ */
+export function progressSortingFn(id, desc) {
+    return desc
+        ? (a, b) => {
+            const [minA, maxA] = a[id];
+            const [minB, maxB] = b[id];
+            if (minA == undefined || maxA == undefined || maxA == 0) {
+                if (maxB != undefined && maxB != 0) {
+                    return 1;
+                }
+                else {
+                    return 0;
+                }
+            }
+            if (minB == undefined || maxB == undefined || maxB == 0) {
+                return -1;
+            }
+            const valueA = minA / maxA;
+            const valueB = minB / maxB;
+            if (valueA < valueB) {
+                return 1;
+            }
+            if (valueB < valueA) {
+                return -1;
+            }
+            return 0;
+        }
+        : (a, b) => {
+            const [minA, maxA] = a[id];
+            const [minB, maxB] = b[id];
+            if (minA == undefined || maxA == undefined || maxA == 0) {
+                if (maxB != undefined && maxB != 0) {
+                    return -1;
+                }
+                else {
+                    return 0;
+                }
+            }
+            if (minB == undefined || maxB == undefined || maxB == 0) {
+                return 1;
+            }
+            const valueA = minA / maxA;
+            const valueB = minB / maxB;
+            if (valueA < valueB) {
+                return -1;
+            }
+            if (valueB < valueA) {
+                return 1;
+            }
+            return 0;
+        };
+}
+/**
+ * Phase 6.1 god-object decomposition - sub-context that owns the
+ * sort-related derived chain (`sortedData`), the per-`ColumnDef`
+ * comparator dispatch (`getSortingFn`), and the comparator-hoist
+ * optimisation that lifts the `instanceof` cascade out of the
+ * `.sort()` callback.
+ *
+ * `TableContext` retains delegating getters / methods for backwards
+ * compatibility; future consumers can read `tableContext._sorting`
+ * directly once the migration is complete (see
+ * `src/stories/Concepts/TableContext-decomposition.mdx`).
+ */
+export class SortingState {
+    _deps;
+    _sortedDataAbortController = null;
+    /**
+     * @param deps thunks the sub-context reads from the parent.
+     *             Constructor-only - no implicit setup so the parent
+     *             remains in control of effect ownership.
+     */
+    constructor(deps) {
+        this._deps = deps;
+    }
+    /**
+     * Resolve the comparator for a single column. Order of resolution:
+     *
+     * 1. `def.getSortingFn(desc)` if the column declares one.
+     * 2. `comparableSortingFn` for `DisplayDef` / `TextInputDef` /
+     *    `NumberInputDef` / `DateInputDef` / `SelectDef`.
+     * 3. `checkboxSortingFn` for `CheckboxDef`.
+     * 4. `progressSortingFn` for `ProgressBarDef`.
+     * 5. Fallback: `comparableSortingFn`.
+     *
+     * Returns `undefined` only when the data repository is empty (so the
+     * `.sort()` caller can skip without warning) or when the column id is
+     * not in the current `columnDefsById` map.
+     *
+     * Public so the comparator dispatch can be unit-tested independently
+     * of the `sortedData` derived chain.
+     */
+    getSortingFn(id, desc) {
+        if (this._deps.getDataLength() == 0) {
+            return undefined;
+        }
+        const def = this._deps.getColumnDefsById().get(id);
+        if (!def) {
+            return undefined;
+        }
+        if (def.getSortingFn != undefined) {
+            return def.getSortingFn(desc);
+        }
+        if (def instanceof DisplayDef ||
+            def instanceof TextInputDef ||
+            def instanceof NumberInputDef ||
+            def instanceof DateInputDef) {
+            return comparableSortingFn(id, desc);
+        }
+        if (def instanceof CheckboxDef) {
+            return checkboxSortingFn(id, desc);
+        }
+        if (def instanceof SelectDef) {
+            return comparableSortingFn(id, desc);
+        }
+        if (def instanceof ProgressBarDef) {
+            return progressSortingFn(id, desc);
+        }
+        return comparableSortingFn(id, desc);
+    }
+    /**
+     * Sorted view of the filtered data. When `paginationType` is `Local`
+     * the array is `filteredData.concat().sort(...)` with comparators
+     * resolved through `getSortingFn`. For all other modes the upstream
+     * `filteredData` is returned untouched (remote sort applies on the
+     * server).
+     *
+     * Performance: the per-column `instanceof` cascade inside
+     * `getSortingFn` is paid O(columns) times per re-sort instead of
+     * O(n log n) - the comparator array is materialised once before the
+     * `.sort()` callback. Lifted from `TableContext.sortedData` in
+     * Phase-5 Group 2 (workorder P0); preserved verbatim here.
+     *
+     * Abort semantics: when `filteredData` or `sortingState` changes
+     * mid-sort the previous controller is aborted and the in-flight
+     * comparator returns `0` to short-circuit. The `$derived` re-runs
+     * immediately afterwards and produces the up-to-date array.
+     */
+    sortedData = $derived.by(() => {
+        const filteredData = this._deps.getFilteredData();
+        const sortingArray = this._deps.getSortingArray();
+        const paginationType = this._deps.getPaginationType();
+        const debug = this._deps.getDebug();
+        this._sortedDataAbortController?.abort();
+        const currentController = (this._sortedDataAbortController = new AbortController());
+        if (debug) {
+            console.log('sorted data');
+        }
+        if (paginationType == PaginationType.Local) {
+            if (currentController.signal.aborted) {
+                return [];
+            }
+            const dataToSort = filteredData.concat();
+            // Hoist comparators out of the .sort() callback so the
+            // per-column instanceof cascade inside getSortingFn is paid
+            // O(columns) times instead of O(n log n) (workorder P0).
+            const sortingFns = [];
+            for (let i = 0; i < sortingArray.length; i++) {
+                const { id, desc } = sortingArray[i];
+                const fn = this.getSortingFn(id, desc);
+                if (fn) {
+                    sortingFns.push(fn);
+                }
+                else if (dev) {
+                    console.warn('no sorting fn found for ' + id);
+                }
+            }
+            const end = sortingFns.length;
+            dataToSort.sort((a, b) => {
+                if (currentController.signal.aborted) {
+                    return 0;
+                }
+                for (let i = 0; i < end; i++) {
+                    const result = sortingFns[i](a, b);
+                    if (result != 0) {
+                        return result;
+                    }
+                }
+                return 0;
+            });
+            return dataToSort;
+        }
+        return filteredData;
+    });
+}