@lavalogic/scoria 0.36.0 → 0.37.0

package/dist/Components/Table/Body/Rows/Columns/_helpers/useAsyncEditable.svelte.d.ts

@@ -0,0 +1,104 @@
+import { type Primitive } from '../../../../Types/Context/TableInitOptions.js';
+import type { TableCell } from '../../../../Types/Columns/TableCell.js';
+import type { TableFocusDetails } from '../../../../Types/Focus/TableFocusDetails.svelte.js';
+import { Validity } from '../../../../../../Types/Internal/Validity.js';
+/**
+ * Options for {@link useAsyncEditable}. All reactive inputs are exposed as
+ * thunks so the helper can establish its own `$effect` / `$derived` chain
+ * on whatever reactive state the caller wraps inside.
+ */
+export interface UseAsyncEditableOptions<T extends object> {
+    /** The cell to coordinate focus / edit state for. */
+    cell: () => TableCell<T>;
+    /**
+     * Optional callback fired once a row first qualifies as `wantsToBeEdited`
+     * AND the async `editable` check has resolved true. Use this to seed a
+     * cell-local `tempValue` buffer before the inner input renders. The
+     * helper guarantees `wantsToBeEdited && editable` are both true at the
+     * time of the call.
+     */
+    onEnterEdit?: () => void;
+    /**
+     * Optional callback fired immediately after the cell leaves edit mode
+     * (either because `wantsToBeEdited` flipped false, or because the
+     * cell-specific input dispatched a commit / cancel). Cells that need
+     * "save on blur" semantics should fire `tableContext.onEditCell` here.
+     */
+    onLeaveEdit?: () => void;
+    /**
+     * Optional callback fired immediately after `isBeingEdited` becomes
+     * true, with `isMousingDown` already reset. Use to focus / select the
+     * inner input on the next tick.
+     */
+    onAfterEnterEdit?: () => void;
+}
+/**
+ * Public surface returned by {@link useAsyncEditable}. All reactive
+ * properties must be read inside a Svelte reactive scope to participate in
+ * dependency tracking.
+ */
+export interface AsyncEditable<T extends object, RowIdType extends Primitive> {
+    /** Resolved synchronous boolean from the async `isEditable` predicate. */
+    readonly editable: boolean;
+    /** True while the cell is rendering its inline edit input. */
+    readonly isBeingEdited: boolean;
+    /** The per-cell focus-details handle from `FocusState`. */
+    readonly focusDetails: TableFocusDetails<T, RowIdType>;
+    /** The latest unwrapped `Validity` for the cell. */
+    readonly validity: Validity;
+    /**
+     * Wire onto `<td onmouseup={...}>`. Returns `true` if a single-click
+     * focus was handled (and the caller should NOT also call
+     * `tableContext.endFocus`).
+     */
+    handleSingleClickFocus(): boolean;
+    /**
+     * Wire onto `<td ondblclick={...}>`. Returns `true` if a double-click
+     * focus was handled.
+     */
+    handleDoubleClickFocus(): boolean;
+    /**
+     * Pass to `$effect(() => editable.attachEditListener(tdref))`. Returns
+     * the cleanup unsubscriber for the `edit` custom event listener.
+     */
+    attachEditListener(node: HTMLElement | undefined): (() => void) | undefined;
+    /**
+     * Helper for Escape / Enter keydown handlers: clears
+     * `focusStartIsBeingEdited` and refocuses the `<td>` element on the
+     * next tick.
+     */
+    leaveEditingViaKeyboard(tdEl: HTMLElement | undefined): void;
+}
+/**
+ * Reactive editable-cell focus coordinator. Centralises the bookkeeping
+ * that all inline-editable Table cells (`TableTextInput`, `TableNumberInput`,
+ * `TableSelect`, `TableQuerySelect`) share:
+ *
+ * - resolving the async `cell.column.columnDef.isEditable(row, index)`
+ *   predicate (sync boolean or Promise of boolean) with a sequence counter
+ *   that discards stale resolutions;
+ * - deriving `wantsToBeEdited` from {@link TableContext.focusStart} /
+ *   {@link TableContext.focusEnd} / {@link TableContext.focusStartIsBeingEdited}
+ *   / {@link TableContext.isMousingDown};
+ * - mirroring the resolved `wantsToBeEdited && editable` into an
+ *   `isBeingEdited` `$state` flag, with cell-specific seed / commit hooks;
+ * - tracking the `Validity` for the cell from
+ *   {@link TableFocusDetails.validity} and unwrapping validity tuples;
+ * - wiring the `edit` custom event on the cell's `<td>` element with proper
+ *   `$effect` cleanup;
+ * - exposing `handleSingleClickFocus` / `handleDoubleClickFocus` so the
+ *   consumer can spread the standard mouseup / dblclick wiring onto its
+ *   `<td>`.
+ *
+ * Per-cell concerns the helper does NOT take over:
+ * - rendering the editing input (different per cell);
+ * - value-to-display coercion (parseFloat, Date parsing, option lookup);
+ * - keydown re-dispatch on the inner Svelecte input (Select / QuerySelect
+ *   only);
+ * - the inline-modal lifecycle of `TableDatePicker` (deferred separately).
+ *
+ * @param options Reactive inputs and lifecycle callbacks.
+ * @returns A reactive {@link AsyncEditable} bundle. Read its getters inside
+ *          a reactive scope; the helper updates them as state changes.
+ */
+export declare function useAsyncEditable<T extends object, RowIdType extends Primitive>(options: UseAsyncEditableOptions<T>): AsyncEditable<T, RowIdType>;

package/dist/Components/Table/Body/Rows/Columns/_helpers/useAsyncEditable.svelte.js

@@ -0,0 +1,215 @@
+import { TableContext } from '../../../../Types/Context/TableContext.svelte.js';
+import {} from '../../../../Types/Context/TableInitOptions.js';
+import { devCatch, isValidityTuple } from '../../../../../../Helpers/Helpers.svelte.js';
+import { Validity } from '../../../../../../Types/Internal/Validity.js';
+import { getContext, tick, untrack } from 'svelte';
+/**
+ * Reactive editable-cell focus coordinator. Centralises the bookkeeping
+ * that all inline-editable Table cells (`TableTextInput`, `TableNumberInput`,
+ * `TableSelect`, `TableQuerySelect`) share:
+ *
+ * - resolving the async `cell.column.columnDef.isEditable(row, index)`
+ *   predicate (sync boolean or Promise of boolean) with a sequence counter
+ *   that discards stale resolutions;
+ * - deriving `wantsToBeEdited` from {@link TableContext.focusStart} /
+ *   {@link TableContext.focusEnd} / {@link TableContext.focusStartIsBeingEdited}
+ *   / {@link TableContext.isMousingDown};
+ * - mirroring the resolved `wantsToBeEdited && editable` into an
+ *   `isBeingEdited` `$state` flag, with cell-specific seed / commit hooks;
+ * - tracking the `Validity` for the cell from
+ *   {@link TableFocusDetails.validity} and unwrapping validity tuples;
+ * - wiring the `edit` custom event on the cell's `<td>` element with proper
+ *   `$effect` cleanup;
+ * - exposing `handleSingleClickFocus` / `handleDoubleClickFocus` so the
+ *   consumer can spread the standard mouseup / dblclick wiring onto its
+ *   `<td>`.
+ *
+ * Per-cell concerns the helper does NOT take over:
+ * - rendering the editing input (different per cell);
+ * - value-to-display coercion (parseFloat, Date parsing, option lookup);
+ * - keydown re-dispatch on the inner Svelecte input (Select / QuerySelect
+ *   only);
+ * - the inline-modal lifecycle of `TableDatePicker` (deferred separately).
+ *
+ * @param options Reactive inputs and lifecycle callbacks.
+ * @returns A reactive {@link AsyncEditable} bundle. Read its getters inside
+ *          a reactive scope; the helper updates them as state changes.
+ */
+export function useAsyncEditable(options) {
+    const tableContext = getContext(TableContext.identifier);
+    // Runtime guard: getContext is typed as non-undefined for ergonomics
+    // downstream (TS narrowing-by-throw does not propagate into nested
+    // function declarations), but the context can still be absent at
+    // runtime if a consumer forgets to wrap with a Table.
+    if (tableContext == null) {
+        throw new Error('useAsyncEditable requires a TableContext to be in scope');
+    }
+    const editableAsync = $derived(options
+        .cell()
+        .column.columnDef.isEditable(options.cell().row.original, options.cell().row.originalIndex));
+    let editable = $state(false);
+    let asyncCounter = 0;
+    $effect(() => {
+        void editableAsync;
+        const localCounter = (asyncCounter = asyncCounter + 1);
+        const debug = options.cell().column.columnDef.debug;
+        (async () => {
+            try {
+                const isEditable = await editableAsync;
+                if (asyncCounter === localCounter) {
+                    editable = isEditable;
+                }
+                else if (debug) {
+                    console.log('skipping async editable because it is stale');
+                }
+            }
+            catch (e) {
+                if (debug) {
+                    console.error(e);
+                }
+                if (asyncCounter === localCounter) {
+                    editable = false;
+                }
+                else if (debug) {
+                    console.log('skipping async editable because it is stale');
+                }
+            }
+        })().catch(devCatch);
+    });
+    const focusDetails = $derived(tableContext._focus.getFocusDetailsFor(options.cell()));
+    const wantsToBeEdited = $derived(tableContext.focusStart?.column === focusDetails.coordinates.column &&
+        tableContext.focusEnd?.column === focusDetails.coordinates.column &&
+        tableContext.focusStart.row === focusDetails.coordinates.row &&
+        tableContext.focusEnd.row === focusDetails.coordinates.row &&
+        !tableContext.isMousingDown &&
+        tableContext.focusStartIsBeingEdited);
+    let isBeingEdited = $state(false);
+    $effect(() => {
+        if (wantsToBeEdited) {
+            if (editable) {
+                tick()
+                    .then(() => {
+                    untrack(() => {
+                        options.onEnterEdit?.();
+                        isBeingEdited = true;
+                    });
+                })
+                    .catch(devCatch);
+            }
+            else {
+                tick()
+                    .then(() => {
+                    untrack(() => {
+                        tableContext.focusStartIsBeingEdited = false;
+                    });
+                })
+                    .catch(devCatch);
+            }
+        }
+        else if (isBeingEdited) {
+            untrack(() => {
+                isBeingEdited = false;
+                tick()
+                    .then(() => {
+                    options.onLeaveEdit?.();
+                })
+                    .catch(devCatch);
+            });
+        }
+    });
+    let overrideEdit = $state(false);
+    $effect(() => {
+        if (isBeingEdited) {
+            if (overrideEdit) {
+                overrideEdit = false;
+            }
+            else {
+                tableContext.isMousingDown = false;
+                tick()
+                    .then(() => {
+                    options.onAfterEnterEdit?.();
+                })
+                    .catch(devCatch);
+            }
+        }
+    });
+    let validity = $state(Validity.Valid);
+    $effect(() => {
+        const validityPromise = focusDetails.validity;
+        validityPromise
+            .then((v) => {
+            if (!v) {
+                validity = Validity.Neutral;
+            }
+            else if (isValidityTuple(v)) {
+                validity = v.value;
+            }
+            else {
+                validity = v;
+            }
+        })
+            .catch(devCatch);
+    });
+    function handleTDFocus(selectAll = false) {
+        if (tableContext.focusStart?.column === focusDetails.coordinates.column &&
+            tableContext.focusStart.row === focusDetails.coordinates.row &&
+            editable) {
+            if (tableContext.focusEnd?.column !== focusDetails.coordinates.column ||
+                tableContext.focusEnd.row !== focusDetails.coordinates.row) {
+                tableContext.setFocusEnd(focusDetails.coordinates);
+            }
+            tableContext.isMousingDown = false;
+            if (!selectAll) {
+                overrideEdit = true;
+            }
+            tableContext.focusStartIsBeingEdited = true;
+            return true;
+        }
+        return false;
+    }
+    function handleSingleClickFocus() {
+        return tableContext.singleClickEditing && handleTDFocus();
+    }
+    function handleDoubleClickFocus() {
+        return !tableContext.singleClickEditing && handleTDFocus();
+    }
+    const onEdit = (e) => {
+        const detail = e.detail;
+        handleTDFocus(detail.selectAll);
+    };
+    function attachEditListener(node) {
+        if (!node) {
+            return undefined;
+        }
+        node.addEventListener('edit', onEdit);
+        return () => {
+            node.removeEventListener('edit', onEdit);
+        };
+    }
+    function leaveEditingViaKeyboard(tdEl) {
+        tableContext.focusStartIsBeingEdited = false;
+        tick()
+            .then(() => {
+            tdEl?.focus();
+        })
+            .catch(devCatch);
+    }
+    return {
+        get editable() {
+            return editable;
+        },
+        get isBeingEdited() {
+            return isBeingEdited;
+        },
+        get focusDetails() {
+            return focusDetails;
+        },
+        get validity() {
+            return validity;
+        },
+        handleSingleClickFocus,
+        handleDoubleClickFocus,
+        attachEditListener,
+        leaveEditingViaKeyboard,
+    };
+}