@lavalogic/scoria 0.37.44 → 0.37.46

package/dist/Components/Table/Types/DataRepository/TableDataRepository.svelte.js

@@ -1,4 +1,4 @@
-import { browser } from '$app/environment';
+import { browser, dev } from '$app/environment';
 import { SvelteMap, SvelteSet } from 'svelte/reactivity';
 import { PaginationType } from '../Pagination/PaginationType.js';
 /**
@@ -6,12 +6,6 @@ import { PaginationType } from '../Pagination/PaginationType.js';
  * Owns pagination state with localStorage write-through on `pageSize`,
  * the reactive filter-mode map, the force-refresh hook, and shared
  * static helpers for parsing comma-separated filter input.
- *
- * The `out FilterValueType` variance annotation is currently advisory:
- * `filtering` reads the parameter (contravariant) but `__queryValues`
- * does not currently use it. A proper variance audit is deferred to a
- * future workorder; the existing annotation does not break type
- * checking.
  */
 export class TableDataRepository {
     tableName;
@@ -20,14 +14,6 @@ export class TableDataRepository {
         this.tableName = tableName;
         this.getUserId = getUserId;
     }
-    /**
-     * Reactive bag of consumer-defined query values keyed by column id.
-     * Stored as `unknown` because the shape depends on the column type;
-     * narrowing to `FilterValueType` is deferred (would force consumers
-     * to choose a single value type at construction time, which is too
-     * restrictive for tables mixing several filter modes).
-     */
-    __queryValues = new SvelteMap();
     _paginationState = $state({
         pageIndex: 0,
         pageSize: 20,
@@ -37,10 +23,10 @@ export class TableDataRepository {
         return this._paginationState;
     }
     /**
-     * Replaces pagination state and writes the new `pageSize` through to
+     * Replace pagination state and write the new `pageSize` through to
      * localStorage. Idempotent: identical states are dropped so the
-     * previously-viewed-page tracker does not lose its value when the
-     * same state is reassigned (e.g. from a `$derived` re-evaluation).
+     * previously-viewed-page tracker keeps its value when the same state
+     * is reassigned (e.g. from a `$derived` re-evaluation).
      */
     set paginationState(v) {
         if (v.pageIndex === this._paginationState.pageIndex &&
@@ -83,24 +69,26 @@ export class TableDataRepository {
         return this._forceRefresh;
     }
     /**
-     * Replaces the force-refresh callback. Also invokes the new callback
-     * immediately so callers wiring up a remote repo can request a fresh
-     * payload as a single assignment.
+     * @deprecated Assigning the setter both replaces the callback AND
+     * invokes it immediately, which is a footgun for callers wiring it up
+     * inside a constructor or `$effect.pre`. Use `registerRefreshMethod`
+     * to assign without the implicit invoke; call `repo.forceRefresh()`
+     * via the getter when an explicit refresh is wanted.
      *
-     * The implicit invocation on set is a known footgun (TableDataRepository
-     * P1 finding): a future workorder will introduce a dedicated
-     * `triggerRefresh()` method and remove the side effect from the
-     * setter. Behaviour preserved here to avoid breaking existing
-     * consumers.
+     * Behaviour is preserved for backwards compatibility; the setter logs
+     * a dev-only warning so existing call sites surface in development.
      */
     set forceRefresh(v) {
+        if (dev) {
+            console.warn('[scoria] `forceRefresh =` setter is deprecated: it invokes the callback on assignment. Use `registerRefreshMethod(fn)` then call `repo.forceRefresh()` when a refresh is wanted.');
+        }
         this._forceRefresh = v;
         this._forceRefresh();
     }
     /**
      * Registers a refresh callback without invoking it. Preferred over
-     * the `forceRefresh` setter when the caller does not want the
-     * implicit immediate refresh.
+     * the deprecated `forceRefresh` setter; call `repo.forceRefresh()`
+     * separately when an explicit refresh is wanted.
      */
     registerRefreshMethod = (method) => {
         this._forceRefresh = method;

package/dist/Components/Table/Types/Header.d.ts

@@ -4,14 +4,14 @@ import type { Column } from './Columns/Column.js';
  * consumed by `TableHead.svelte`. Holds the underlying `Column` plus
  * header-only affordances: column-span, header size, and the resize handler.
  *
- * Variance markers (`in FilterValueType`, `out FilterOptionsType`) mirror
- * the inner `Column<T, F, O>` so headers compose with column assignability.
+ * The variance marker `in FilterValueType` mirrors the inner
+ * `Column<T, F>` so headers compose with column assignability.
  */
-export interface Header<T extends object, in FilterValueType, out FilterOptionsType> {
+export interface Header<T extends object, in FilterValueType> {
     id: string;
     colSpan: number;
     getSize: () => number;
-    column: Column<T, FilterValueType, FilterOptionsType>;
+    column: Column<T, FilterValueType>;
     isPlaceholder: boolean;
     getResizeHandler: () => (e: MouseEvent) => void;
 }

package/dist/Components/Table/Types/HeaderGroup.d.ts

@@ -1,12 +1,12 @@
 import type { Header } from './Header.js';
 /**
  * One row of headers (left / centre / right group). `headers` is typed with
- * the conservative placeholder element type `Header<T, never, unknown>`
- * because the group holds heterogeneous columns whose per-column filter
- * value type cannot be expressed in the array element type. Tightening to
- * `Header<T, unknown, unknown>` is deferred (workorder Types-Root finding 1).
+ * the conservative placeholder element type `Header<T, never>` because
+ * the group holds heterogeneous columns whose per-column filter value
+ * type cannot be expressed in the array element type. Tightening to
+ * `Header<T, unknown>` is deferred (workorder Types-Root finding 1).
  */
 export interface HeaderGroup<T extends object> {
     id: string;
-    headers: Array<Header<T, never, unknown>>;
+    headers: Array<Header<T, never>>;
 }

package/dist/Components/Table/Types/Public/index.d.ts

@@ -1,9 +1,7 @@
 /**
  * Barrel re-export of every public Table API type. Imported by
- * `src/lib/index.ts` and by sub-deliverable 1.2's `ColumnFactory`
- * runtime module.
- *
- * Phase 1 is type-only; no runtime symbols flow through this barrel.
+ * `src/lib/index.ts` and by the `ColumnFactory` runtime module. This
+ * barrel is type-only; no runtime symbols flow through it.
  */
 export type { AnyEditEvent } from './AnyEditEvent.js';
 export type { BaseColumnOptions } from './BaseColumnOptions.js';

package/dist/Components/Table/Types/Public/index.js

@@ -1,8 +1,6 @@
 /**
  * Barrel re-export of every public Table API type. Imported by
- * `src/lib/index.ts` and by sub-deliverable 1.2's `ColumnFactory`
- * runtime module.
- *
- * Phase 1 is type-only; no runtime symbols flow through this barrel.
+ * `src/lib/index.ts` and by the `ColumnFactory` runtime module. This
+ * barrel is type-only; no runtime symbols flow through it.
  */
 export {};

package/dist/Components/Table/clipboardEscape.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Clipboard escape helpers for the Table copy path.
+ *
+ * Every value written to `navigator.clipboard.writeText` from `<Table>`
+ * passes through these helpers so that pasted payloads cannot evaluate
+ * as spreadsheet formulas in the receiving application.
+ */
+/**
+ * Neutralises CSV / TSV formula-injection prefixes recognised by Excel,
+ * LibreOffice Calc, Google Sheets, and Apple Numbers.
+ *
+ * When a clipboard payload reaches a spreadsheet, any cell whose first
+ * character is one of `=`, `+`, `-`, `@`, `\t`, `\r` is treated as a
+ * formula and evaluated in the user's context. Untrusted row data
+ * containing `=cmd|'/c calc'!A1` (or DDE / web-query equivalents) is the
+ * canonical attack vector. Prefixing such a value with a single quote
+ * (`'`) makes the spreadsheet interpret the cell as a literal string.
+ *
+ * Trade-off: the leading apostrophe is invisible in the rendered cell of
+ * every major spreadsheet, but the underlying cell value differs from
+ * the source when read back by another formula referencing the cell.
+ * This is the accepted industry mitigation (OWASP CSV Injection
+ * cheat sheet).
+ */
+export declare function escapeForSpreadsheet(value: string): string;
+/**
+ * Wraps a single TSV / CSV cell value in double quotes, escaping any
+ * embedded quotes and replacing newlines with spaces so each cell stays
+ * on a single line. Runs `escapeForSpreadsheet` on the value first so
+ * the final string is also formula-injection safe.
+ */
+export declare function encapsulate(value: string): string;

package/dist/Components/Table/clipboardEscape.js

@@ -0,0 +1,45 @@
+/**
+ * Clipboard escape helpers for the Table copy path.
+ *
+ * Every value written to `navigator.clipboard.writeText` from `<Table>`
+ * passes through these helpers so that pasted payloads cannot evaluate
+ * as spreadsheet formulas in the receiving application.
+ */
+/**
+ * Neutralises CSV / TSV formula-injection prefixes recognised by Excel,
+ * LibreOffice Calc, Google Sheets, and Apple Numbers.
+ *
+ * When a clipboard payload reaches a spreadsheet, any cell whose first
+ * character is one of `=`, `+`, `-`, `@`, `\t`, `\r` is treated as a
+ * formula and evaluated in the user's context. Untrusted row data
+ * containing `=cmd|'/c calc'!A1` (or DDE / web-query equivalents) is the
+ * canonical attack vector. Prefixing such a value with a single quote
+ * (`'`) makes the spreadsheet interpret the cell as a literal string.
+ *
+ * Trade-off: the leading apostrophe is invisible in the rendered cell of
+ * every major spreadsheet, but the underlying cell value differs from
+ * the source when read back by another formula referencing the cell.
+ * This is the accepted industry mitigation (OWASP CSV Injection
+ * cheat sheet).
+ */
+export function escapeForSpreadsheet(value) {
+    if (value.length === 0) {
+        return value;
+    }
+    const first = value.charCodeAt(0);
+    // '=' 61, '+' 43, '-' 45, '@' 64, '\t' 9, '\r' 13
+    if (first === 61 || first === 43 || first === 45 || first === 64 || first === 9 || first === 13) {
+        return `'${value}`;
+    }
+    return value;
+}
+/**
+ * Wraps a single TSV / CSV cell value in double quotes, escaping any
+ * embedded quotes and replacing newlines with spaces so each cell stays
+ * on a single line. Runs `escapeForSpreadsheet` on the value first so
+ * the final string is also formula-injection safe.
+ */
+export function encapsulate(value) {
+    const safe = escapeForSpreadsheet(value);
+    return `"${safe.replace(/[\n]/gm, ' ').replace(/["]/g, '""')}"`;
+}

package/dist/Components/Table/createTable.svelte.d.ts

@@ -1,21 +1,11 @@
 /**
- * `createTable` is the entry point for the new public Table API. It accepts
- * a single options object and returns a structured `Table<TRow, TRowId>`
- * instance.
+ * `createTable` is the entry point for the public Table API. It accepts a
+ * single options object and returns a structured `Table<TRow, TRowId>`
+ * instance whose sub-APIs are facades over the internal sub-contexts.
  *
- * Phase 1 implementation strategy: this function is a thin facade. It
- * unwraps the column specs, constructs the existing internal repository
- * (`LocalTableDataRepository` for `kind: 'local'`, the new
- * `BuiltInRemoteRepository` for `kind: 'remote'`, an adapter for
- * `kind: 'custom'`), invokes `TableContext.init`, wires the per-column
- * edit handlers and the optional `onAnyEdit` observer, then returns a
- * structured `Table` instance whose sub-APIs are facades over the Phase 6
- * sub-contexts. Phase 2 will inline the internals.
- *
- * The structured `Table` instance is also exposed as the `_context` field
- * for the Phase 1 `<Table>` component which still reads from a
- * `TableContext` via `setContext`. Phase 2 reshapes `<Table>` to consume
- * the structured instance directly.
+ * The structured `Table` instance also exposes a `_context` field so the
+ * `<Table>` component can read from the underlying `TableContext` via
+ * `setContext`.
  */
 import { TableContext } from './Types/Context/TableContext.svelte.js';
 import type { Primitive } from './Types/Context/TableInitOptions.js';
@@ -25,8 +15,8 @@ import type { Table } from './Types/Public/Table.js';
 /**
  * Construct a new Table from the supplied options. Returns the structured
  * `Table<TRow, TRowId>` instance. Mount the rendering component via
- * `<Table {table} />` (Phase 1 also accepts the legacy
- * `<Table tableContext={table._context} />` form).
+ * `<Table {table} />` (the legacy `<Table tableContext={table._context} />`
+ * form is also accepted).
  *
  * @example
  * ```ts

package/dist/Components/Table/createTable.svelte.js

@@ -1,21 +1,11 @@
 /**
- * `createTable` is the entry point for the new public Table API. It accepts
- * a single options object and returns a structured `Table<TRow, TRowId>`
- * instance.
+ * `createTable` is the entry point for the public Table API. It accepts a
+ * single options object and returns a structured `Table<TRow, TRowId>`
+ * instance whose sub-APIs are facades over the internal sub-contexts.
  *
- * Phase 1 implementation strategy: this function is a thin facade. It
- * unwraps the column specs, constructs the existing internal repository
- * (`LocalTableDataRepository` for `kind: 'local'`, the new
- * `BuiltInRemoteRepository` for `kind: 'remote'`, an adapter for
- * `kind: 'custom'`), invokes `TableContext.init`, wires the per-column
- * edit handlers and the optional `onAnyEdit` observer, then returns a
- * structured `Table` instance whose sub-APIs are facades over the Phase 6
- * sub-contexts. Phase 2 will inline the internals.
- *
- * The structured `Table` instance is also exposed as the `_context` field
- * for the Phase 1 `<Table>` component which still reads from a
- * `TableContext` via `setContext`. Phase 2 reshapes `<Table>` to consume
- * the structured instance directly.
+ * The structured `Table` instance also exposes a `_context` field so the
+ * `<Table>` component can read from the underlying `TableContext` via
+ * `setContext`.
  */
 import { devCatch, refWrapper } from '../../Helpers/Helpers.svelte.js';
 import { BuiltInRemoteRepository, CustomRemoteRepository, } from './Types/DataRepository/BuiltInRemoteRepository.svelte.js';
@@ -30,8 +20,8 @@ import { makeClipboardApi, makeColumnsApi, makeFilteringApi, makeFocusApi, makeM
 /**
  * Construct a new Table from the supplied options. Returns the structured
  * `Table<TRow, TRowId>` instance. Mount the rendering component via
- * `<Table {table} />` (Phase 1 also accepts the legacy
- * `<Table tableContext={table._context} />` form).
+ * `<Table {table} />` (the legacy `<Table tableContext={table._context} />`
+ * form is also accepted).
  *
  * @example
  * ```ts
@@ -48,15 +38,11 @@ import { makeClipboardApi, makeColumnsApi, makeFilteringApi, makeFocusApi, makeM
  * ```
  */
 export function createTable(options) {
-    // ── 1. Resolve rowId ────────────────────────────────────────────
     const rowIdFn = resolveRowId(options.rowId);
-    // ── 2. Run the column-builder closure ───────────────────────────
     const factory = createColumnFactory();
     const specs = options.columns(factory);
-    // Build a Map<columnId, ColumnSpec> for the ColumnsApi, plus a
-    // Map<columnId, perColumnOnEdit> for the onEditCell dispatcher.
-    // These are constructed once during init and never reassigned reactively,
-    // so a plain Map is correct here.
+    // These maps are constructed once during init and never reassigned
+    // reactively, so a plain Map is correct here (no SvelteMap needed).
     // eslint-disable-next-line svelte/prefer-svelte-reactivity
     const specsById = new Map();
     // eslint-disable-next-line svelte/prefer-svelte-reactivity
@@ -71,18 +57,14 @@ export function createTable(options) {
     });
     // remoteFilters resolution order:
     //   1. Explicit `options.remoteFilters` thunk on createTable.
-    //   2. `kind: 'custom'` row source's `remoteFilters` field (set by
-    //      `createRemoteRowSource` from its own option of the same name).
-    // This means a caller can hand the same `SvelteMap` to the custom
-    // row-source factory once and the filter panel picks it up for free.
+    //   2. `kind: 'custom'` row source's `remoteFilters` field.
+    // A caller can hand the same `SvelteMap` to the custom row-source
+    // factory once and the filter panel picks it up for free.
     const remoteFilters = options.remoteFilters?.() ??
         (options.rows.kind === 'custom' ? options.rows.remoteFilters : undefined);
     const defsWrapper = remoteFilters ? { defs, remoteFilters } : { defs };
-    // ── 3. Construct the repository for the chosen row source ──────
     const repository = makeRepository(options.name, options.rows, options.getUserId);
-    // ── 4. Build the `onEditCell` wrapper ──────────────────────────
     const onEditCell = makeOnEditCell(editHandlers, options.onAnyEdit);
-    // ── 5. Translate the new options to TableInitOptions ───────────
     const initOptions = {
         selectionExtractor: rowIdFn,
         getUserId: options.getUserId ?? (() => undefined),
@@ -97,23 +79,17 @@ export function createTable(options) {
         onEditCell,
         debug: options.debug,
     };
-    // ── 6. Build the TableContext ──────────────────────────────────
     const ctx = TableContext.init(defsWrapper, options.name, repository, initOptions);
-    // ── 7. Wire selection.bindTo (Phase 1 uses the existing setter) ─
     if (options.selection && options.selection.mode !== 'none' && options.selection.bindTo) {
         ctx.setSelectionMap(options.selection.bindTo);
     }
-    // ── 8. Apply initialState ───────────────────────────────────────
     if (options.initialState) {
         applyInitialState(ctx, options.initialState);
     }
-    // ── 9. Auto-pin structural columns ──────────────────────────────
-    // `col.actions` (the ellipsis menu) and `col.rowSelection` (the
-    // select-row checkbox) are conventionally pinned to the right and
-    // left respectively across every table in the app, so apply that
-    // pin automatically here. The caller can override either pin via
-    // `initialState.columnPinning` (which runs first above), or via
-    // the live `setColumnPinning` updater on the table context.
+    // Auto-pin structural columns. `col.actions` (ellipsis menu) pins right
+    // and `col.rowSelection` (select-row checkbox) pins left by convention.
+    // Callers can override either pin via `initialState.columnPinning` (which
+    // runs above) or via the live `setColumnPinning` updater.
     const autoPinLeft = new Map();
     const autoPinRight = new Map();
     for (const spec of specs) {
@@ -145,7 +121,6 @@ export function createTable(options) {
         }
         ctx.columnPinning = { left: nextLeft, right: nextRight };
     }
-    // ── 9. Build the structured Table instance ─────────────────────
     const table = Object.freeze({
         get name() {
             return ctx.tableName;
@@ -172,8 +147,7 @@ export function createTable(options) {
             return ctx.dataRepo.reload?.() ?? Promise.resolve();
         },
         destroy() {
-            // Phase 1: no teardown hook exists on TableContext. Phase 2 will
-            // introduce one when <Table> consumes the structured instance.
+            // No teardown hook on TableContext yet.
         },
         _context: ctx,
     });
@@ -292,9 +266,7 @@ function translateToolbar(toolbar) {
             return ToolbarPosition.None;
     }
 }
-/** Apply the `initialState` options to a freshly-constructed TableContext.
- *  Phase 1 wires the subset of fields the existing sub-contexts already
- *  support; Phase 2 may extend the surface. */
+/** Apply the `initialState` options to a freshly-constructed TableContext. */
 function applyInitialState(ctx, state) {
     if (state.sortBy && state.sortBy.length > 0) {
         ctx.dataRepo.updateSorting?.(state.sortBy.map((s) => ({ id: s.id, desc: s.desc ?? false })));

package/dist/Components/Test/TestContextConsumer.svelte

@@ -1,13 +1,13 @@
-<svelte:options runes />
-
-<script lang="ts">
-	import { TestContext } from '../../Contexts/TestContext.svelte.js';
-	import { getContext } from 'svelte';
-
-	const testContext = getContext<TestContext>(TestContext.identifier);
-</script>
-
-<h1>counter 1: {testContext.value1.value}</h1>
-<p>Ref wrapper 1 is incremented every time you click the button</p>
-<h2>counter 2: {testContext.value2.value}</h2>
-<p>ref wrapper 2 adds ref wrapper 1's value every time ref wrapper 1's value is divisible by 3</p>
+<svelte:options runes />
+
+<script lang="ts">
+	import { TestContext } from '../../Contexts/TestContext.svelte.js';
+	import { getContext } from 'svelte';
+
+	const testContext = getContext<TestContext>(TestContext.identifier);
+</script>
+
+<h1>counter 1: {testContext.value1.value}</h1>
+<p>Ref wrapper 1 is incremented every time you click the button</p>
+<h2>counter 2: {testContext.value2.value}</h2>
+<p>ref wrapper 2 adds ref wrapper 1's value every time ref wrapper 1's value is divisible by 3</p>