@vuu-ui/grid-layout 4.0.0-alpha.1

package/src/GridController.js

@@ -0,0 +1,359 @@
+import { LegacyGridCommandExecutor } from "./GridCommand.js";
+import { gridLayoutDescriptorToSnapshot, normalizeGridSnapshot } from "./grid-snapshot-adapters.js";
+import { toGridStackSnapshot } from "./GridStack.js";
+const semanticSnapshot = ({ revision: _revision, ...snapshot })=>JSON.stringify(snapshot);
+const transactionError = (code, message)=>({
+        code,
+        message
+    });
+class GridController {
+    gridModel;
+    #executor;
+    #listeners = new Set();
+    #commitListeners = new Set();
+    #activeTransaction;
+    #snapshot;
+    constructor(gridModel, revision = 0, executor = new LegacyGridCommandExecutor(gridModel)){
+        this.gridModel = gridModel;
+        this.#executor = executor;
+        this.#snapshot = this.#readSnapshot(revision);
+    }
+    getSnapshot = ()=>this.#snapshot;
+    subscribe = (listener)=>{
+        this.#listeners.add(listener);
+        return ()=>{
+            this.#listeners.delete(listener);
+        };
+    };
+    subscribeCommitted = (listener)=>{
+        this.#commitListeners.add(listener);
+        return ()=>{
+            this.#commitListeners.delete(listener);
+        };
+    };
+    dispatch(command) {
+        if (this.#activeTransaction) return {
+            command: command.type,
+            error: transactionError("TRANSACTION_ACTIVE", `Cannot dispatch ${command.type} while a grid transaction is active`),
+            ok: false
+        };
+        const checkpoint = this.gridModel.createCheckpoint();
+        const previous = this.#snapshot;
+        const result = this.#executeAtomically(command, checkpoint);
+        if (!result.ok) return result;
+        const candidate = this.#readSnapshot(previous.revision);
+        if (semanticSnapshot(candidate) === semanticSnapshot(previous)) return result;
+        this.#snapshot = this.#readSnapshot(previous.revision + 1);
+        this.#notifyState();
+        this.#notifyCommitted({
+            commands: [
+                command
+            ],
+            kind: "dispatch",
+            previous,
+            snapshot: this.#snapshot
+        });
+        return result;
+    }
+    beginTransaction(kind) {
+        if (this.#activeTransaction) return {
+            error: transactionError("TRANSACTION_ACTIVE", `Cannot begin ${kind}; a grid transaction is already active`),
+            ok: false
+        };
+        let transaction;
+        transaction = new GridControllerTransaction(kind, this.gridModel.createCheckpoint(), this.#snapshot, (command)=>this.#executePreview(transaction, command), (commands)=>this.#establishWorkingBaseline(transaction, commands), (commands)=>this.#replacePreview(transaction, commands), (commands)=>this.#validateReplacement(transaction, commands), (commands)=>this.#commitTransaction(transaction, kind, transaction.baseline, commands), ()=>this.#rollbackTransaction(transaction, transaction.checkpoint, transaction.baseline));
+        this.#activeTransaction = transaction;
+        return {
+            ok: true,
+            transaction
+        };
+    }
+    #executePreview(transaction, command) {
+        if (this.#activeTransaction !== transaction) return {
+            command: command.type,
+            error: transactionError("TRANSACTION_CLOSED", `Cannot dispatch ${command.type}; the grid transaction is closed`),
+            ok: false
+        };
+        const checkpoint = this.gridModel.createCheckpoint();
+        const result = this.#executeAtomically(command, checkpoint);
+        if (!result.ok) return result;
+        const candidate = this.#readSnapshot(this.#snapshot.revision);
+        if (semanticSnapshot(candidate) !== semanticSnapshot(this.#snapshot)) {
+            this.#snapshot = semanticSnapshot(candidate) === semanticSnapshot(transaction.baseline) ? transaction.baseline : candidate;
+            this.#notifyState();
+        }
+        return result;
+    }
+    #replacePreview(transaction, commands) {
+        const representative = commands[0] ?? {
+            type: "regenerate-placeholders"
+        };
+        if (this.#activeTransaction !== transaction) return {
+            command: representative.type,
+            error: transactionError("TRANSACTION_CLOSED", "Cannot replace preview; the grid transaction is closed"),
+            ok: false
+        };
+        this.gridModel.restoreCheckpoint(transaction.workingCheckpoint);
+        this.#snapshot = transaction.workingBaseline;
+        try {
+            for (const command of commands){
+                const checkpoint = this.gridModel.createCheckpoint();
+                const result = this.#executeAtomically(command, checkpoint);
+                if (!result.ok) {
+                    this.gridModel.restoreCheckpoint(transaction.workingCheckpoint);
+                    this.#snapshot = transaction.workingBaseline;
+                    transaction.setReplacementCommands([]);
+                    this.#notifyState();
+                    return result;
+                }
+            }
+        } catch (error) {
+            this.gridModel.restoreCheckpoint(transaction.workingCheckpoint);
+            this.#snapshot = transaction.workingBaseline;
+            transaction.setReplacementCommands([]);
+            this.#notifyState();
+            throw error;
+        }
+        transaction.setReplacementCommands(commands);
+        const candidate = this.#readSnapshot(transaction.baseline.revision);
+        this.#snapshot = semanticSnapshot(candidate) === semanticSnapshot(transaction.baseline) ? transaction.baseline : candidate;
+        this.#notifyState();
+        return {
+            command: representative.type,
+            ok: true
+        };
+    }
+    #establishWorkingBaseline(transaction, commands) {
+        const representative = commands[0] ?? {
+            type: "regenerate-placeholders"
+        };
+        if (this.#activeTransaction !== transaction) return {
+            command: representative.type,
+            error: transactionError("TRANSACTION_CLOSED", "Cannot establish a working baseline; the grid transaction is closed"),
+            ok: false
+        };
+        this.gridModel.restoreCheckpoint(transaction.checkpoint);
+        this.#snapshot = transaction.baseline;
+        for (const command of commands){
+            const checkpoint = this.gridModel.createCheckpoint();
+            const result = this.#executeAtomically(command, checkpoint);
+            if (!result.ok) {
+                this.gridModel.restoreCheckpoint(transaction.checkpoint);
+                this.#snapshot = transaction.baseline;
+                transaction.resetWorkingBaseline();
+                return result;
+            }
+        }
+        const candidate = this.#readSnapshot(transaction.baseline.revision);
+        this.#snapshot = semanticSnapshot(candidate) === semanticSnapshot(transaction.baseline) ? transaction.baseline : candidate;
+        transaction.setWorkingBaseline(this.gridModel.createCheckpoint(), this.#snapshot, commands);
+        this.#notifyState();
+        return {
+            command: representative.type,
+            ok: true
+        };
+    }
+    #validateReplacement(transaction, commands) {
+        const representative = commands[0] ?? {
+            type: "regenerate-placeholders"
+        };
+        if (this.#activeTransaction !== transaction) return {
+            command: representative.type,
+            error: transactionError("TRANSACTION_CLOSED", "Cannot validate replacement; the grid transaction is closed"),
+            ok: false
+        };
+        this.gridModel.restoreCheckpoint(transaction.workingCheckpoint);
+        this.#snapshot = transaction.workingBaseline;
+        try {
+            for (const command of commands){
+                const checkpoint = this.gridModel.createCheckpoint();
+                const result = this.#executeAtomically(command, checkpoint);
+                if (!result.ok) return result;
+            }
+            return {
+                command: representative.type,
+                ok: true
+            };
+        } finally{
+            this.gridModel.restoreCheckpoint(transaction.workingCheckpoint);
+            this.#snapshot = transaction.workingBaseline;
+        }
+    }
+    #commitTransaction(transaction, kind, baseline, commands) {
+        if (this.#activeTransaction !== transaction) return this.#closedResult("commit");
+        const changed = semanticSnapshot(this.#snapshot) !== semanticSnapshot(baseline);
+        this.#activeTransaction = void 0;
+        if (!changed) {
+            this.#snapshot = baseline;
+            return {
+                ok: true,
+                snapshot: this.#snapshot
+            };
+        }
+        this.#snapshot = this.#readSnapshot(baseline.revision + 1);
+        this.#notifyState();
+        this.#notifyCommitted({
+            commands: [
+                ...commands
+            ],
+            kind,
+            previous: baseline,
+            snapshot: this.#snapshot
+        });
+        return {
+            ok: true,
+            snapshot: this.#snapshot
+        };
+    }
+    #rollbackTransaction(transaction, checkpoint, baseline) {
+        if (this.#activeTransaction !== transaction) return this.#closedResult("rollback");
+        const changed = semanticSnapshot(this.#snapshot) !== semanticSnapshot(baseline);
+        this.gridModel.restoreCheckpoint(checkpoint);
+        this.#snapshot = baseline;
+        this.#activeTransaction = void 0;
+        if (changed) this.#notifyState();
+        return {
+            ok: true,
+            snapshot: this.#snapshot
+        };
+    }
+    #closedResult(action) {
+        return {
+            error: transactionError("TRANSACTION_CLOSED", `Cannot ${action}; the grid transaction is closed`),
+            ok: false
+        };
+    }
+    #executeAtomically(command, checkpoint) {
+        try {
+            const result = this.#executor.execute(command);
+            if (!result.ok) this.gridModel.restoreCheckpoint(checkpoint);
+            return result;
+        } catch (error) {
+            this.gridModel.restoreCheckpoint(checkpoint);
+            throw error;
+        }
+    }
+    #readSnapshot(revision) {
+        const snapshot = gridLayoutDescriptorToSnapshot(this.gridModel.toGridLayoutDescriptor(), {
+            gridId: this.gridModel.id,
+            revision
+        });
+        return normalizeGridSnapshot({
+            ...snapshot,
+            stacks: snapshot.stacks.map(({ id })=>toGridStackSnapshot(this.gridModel.getStackState(id)))
+        });
+    }
+    #notifyState() {
+        for (const listener of [
+            ...this.#listeners
+        ])if (this.#listeners.has(listener)) listener();
+    }
+    #notifyCommitted(transition) {
+        for (const listener of [
+            ...this.#commitListeners
+        ])if (this.#commitListeners.has(listener)) listener(transition);
+    }
+}
+class GridControllerTransaction {
+    kind;
+    checkpoint;
+    baseline;
+    executePreview;
+    establishBaseline;
+    replacePreview;
+    validatePreviewReplacement;
+    commitTransaction;
+    rollbackTransaction;
+    #commands = [];
+    #workingCommands = [];
+    #closed = false;
+    #workingCheckpoint;
+    #workingBaseline;
+    constructor(kind, checkpoint, baseline, executePreview, establishBaseline, replacePreview, validatePreviewReplacement, commitTransaction, rollbackTransaction){
+        this.kind = kind;
+        this.checkpoint = checkpoint;
+        this.baseline = baseline;
+        this.executePreview = executePreview;
+        this.establishBaseline = establishBaseline;
+        this.replacePreview = replacePreview;
+        this.validatePreviewReplacement = validatePreviewReplacement;
+        this.commitTransaction = commitTransaction;
+        this.rollbackTransaction = rollbackTransaction;
+        this.#workingCheckpoint = checkpoint;
+        this.#workingBaseline = baseline;
+    }
+    get workingCheckpoint() {
+        return this.#workingCheckpoint;
+    }
+    get workingBaseline() {
+        return this.#workingBaseline;
+    }
+    dispatch(command) {
+        if (this.#closed) return {
+            command: command.type,
+            error: transactionError("TRANSACTION_CLOSED", `Cannot dispatch ${command.type}; the grid transaction is closed`),
+            ok: false
+        };
+        const result = this.executePreview(command);
+        if (result.ok) this.#commands.push(command);
+        return result;
+    }
+    replace(commands) {
+        if (this.#closed) return {
+            command: commands[0]?.type ?? "regenerate-placeholders",
+            error: transactionError("TRANSACTION_CLOSED", "Cannot replace preview; the grid transaction is closed"),
+            ok: false
+        };
+        return this.replacePreview(commands);
+    }
+    establishWorkingBaseline(commands) {
+        if (this.#closed) return {
+            command: commands[0]?.type ?? "regenerate-placeholders",
+            error: transactionError("TRANSACTION_CLOSED", "Cannot establish a working baseline; the grid transaction is closed"),
+            ok: false
+        };
+        return this.establishBaseline(commands);
+    }
+    validateReplacement(commands) {
+        if (this.#closed) return {
+            command: commands[0]?.type ?? "regenerate-placeholders",
+            error: transactionError("TRANSACTION_CLOSED", "Cannot validate replacement; the grid transaction is closed"),
+            ok: false
+        };
+        return this.validatePreviewReplacement(commands);
+    }
+    setWorkingBaseline(checkpoint, snapshot, commands) {
+        this.#workingCheckpoint = checkpoint;
+        this.#workingBaseline = snapshot;
+        this.#workingCommands.splice(0, this.#workingCommands.length, ...commands);
+        this.setReplacementCommands([]);
+    }
+    resetWorkingBaseline() {
+        this.#workingCheckpoint = this.checkpoint;
+        this.#workingBaseline = this.baseline;
+        this.#workingCommands.length = 0;
+        this.#commands.length = 0;
+    }
+    setReplacementCommands(commands) {
+        this.#commands.splice(0, this.#commands.length, ...this.#workingCommands, ...commands);
+    }
+    commit() {
+        if (this.#closed) return {
+            error: transactionError("TRANSACTION_CLOSED", "Cannot commit; the grid transaction is closed"),
+            ok: false
+        };
+        const result = this.commitTransaction(this.#commands);
+        if (result.ok) this.#closed = true;
+        return result;
+    }
+    rollback() {
+        if (this.#closed) return {
+            error: transactionError("TRANSACTION_CLOSED", "Cannot rollback; the grid transaction is closed"),
+            ok: false
+        };
+        const result = this.rollbackTransaction();
+        if (result.ok) this.#closed = true;
+        return result;
+    }
+}
+export { GridController };

package/src/GridDragCoordinator.js

@@ -0,0 +1,293 @@
+const failure = (code, message)=>({
+        error: {
+            code,
+            message
+        },
+        ok: false
+    });
+const stackPlacement = (intent)=>intent.position && intent.targetItemId ? {
+        position: intent.position,
+        targetItemId: intent.targetItemId
+    } : {};
+const createGridDropPlan = (source, target)=>{
+    if ("palette-template" !== source.kind && source.sourceGridId !== target.gridId) return {
+        code: "CROSS_GRID_DRAG",
+        message: `Grid item #${source.itemId} cannot move from #${source.sourceGridId} to #${target.gridId}`
+    };
+    const commands = [];
+    if ("palette-template" === source.kind) if ("stack" === target.intent.kind) {
+        commands.push({
+            item: source.item,
+            ...stackPlacement(target.intent),
+            stackId: target.targetId,
+            type: "add-stack-item"
+        });
+        commands.push({
+            itemId: source.item.id,
+            stackId: target.targetId,
+            type: "select-stack-item"
+        });
+    } else commands.push({
+        item: source.item,
+        type: "add-item"
+    });
+    const itemId = "palette-template" === source.kind ? source.item.id : source.itemId;
+    switch(target.intent.kind){
+        case "split":
+            if ("stack-member" === source.kind) commands.push({
+                itemId,
+                stackId: source.stackId,
+                targetId: target.targetId,
+                position: target.intent.position,
+                type: "move-stack-item-to-grid"
+            });
+            else commands.push({
+                itemId,
+                position: target.intent.position,
+                targetId: target.targetId,
+                type: "move-item"
+            });
+            break;
+        case "replace":
+            if ("stack-member" === source.kind) commands.push({
+                itemId,
+                stackId: source.stackId,
+                targetId: target.targetId,
+                type: "replace-stack-item"
+            });
+            else commands.push({
+                itemId,
+                targetId: target.targetId,
+                type: "replace-item"
+            });
+            break;
+        case "create-stack":
+            if ("stack-member" === source.kind) return {
+                code: "UNSUPPORTED_DROP",
+                message: "A stack member cannot create a stack without first becoming standalone"
+            };
+            commands.push({
+                itemId,
+                selectedItemId: itemId,
+                targetId: target.targetId,
+                type: "create-stack"
+            });
+            break;
+        case "stack":
+            if ("palette-template" === source.kind) break;
+            if ("stack-member" === source.kind && source.stackId === target.targetId) {
+                if (!target.intent.position || !target.intent.targetItemId) return {
+                    code: "UNSUPPORTED_DROP",
+                    message: "Reordering a stack member requires a target item and position"
+                };
+                commands.push({
+                    activate: source.selected,
+                    itemId,
+                    position: target.intent.position,
+                    stackId: source.stackId,
+                    targetItemId: target.intent.targetItemId,
+                    type: "reorder-stack-item"
+                });
+            } else commands.push({
+                ...stackPlacement(target.intent),
+                fromStackId: "stack-member" === source.kind ? source.stackId : void 0,
+                itemId,
+                stackId: target.targetId,
+                type: "move-item-to-stack"
+            });
+            break;
+    }
+    if (!commands.some(({ type })=>"reorder-stack-item" === type)) commands.push({
+        type: "regenerate-placeholders"
+    });
+    return {
+        commands,
+        source,
+        target
+    };
+};
+const isPlanError = (value)=>"code" in value;
+class GridDragCoordinator {
+    gridId;
+    controller;
+    #sourceRemovedBaseline = false;
+    #state = {
+        phase: "idle"
+    };
+    #transaction;
+    constructor(gridId, controller){
+        this.gridId = gridId;
+        this.controller = controller;
+    }
+    get state() {
+        return this.#state;
+    }
+    begin(source) {
+        if ("dragging" === this.#state.phase || "previewing" === this.#state.phase) return failure("INVALID_TRANSITION", `Cannot begin a drag while ${this.#state.phase}`);
+        if ("palette-template" !== source.kind && source.sourceGridId !== this.gridId) return failure("CROSS_GRID_DRAG", `Grid item #${source.itemId} cannot move from #${source.sourceGridId} to #${this.gridId}`);
+        this.#state = {
+            phase: "dragging",
+            source
+        };
+        if ("existing-item" === source.kind) {
+            const started = this.controller.beginTransaction("drag");
+            if (!started.ok) {
+                this.#state = {
+                    phase: "idle"
+                };
+                return {
+                    error: started.error,
+                    ok: false
+                };
+            }
+            this.#transaction = started.transaction;
+            const removed = this.#transaction.establishWorkingBaseline([
+                {
+                    itemId: source.itemId,
+                    reason: "drag",
+                    type: "remove-item"
+                }
+            ]);
+            if (!removed.ok) {
+                this.#transaction.rollback();
+                this.#transaction = void 0;
+                this.#state = {
+                    phase: "idle"
+                };
+                return this.#commandFailure(removed);
+            }
+            this.#sourceRemovedBaseline = true;
+        }
+        return {
+            ok: true,
+            state: this.#state
+        };
+    }
+    preview(target) {
+        if ("dragging" !== this.#state.phase && "previewing" !== this.#state.phase) return failure("INVALID_TRANSITION", `Cannot preview a drop while ${this.#state.phase}`);
+        if (target.gridId !== this.gridId) {
+            this.#clearTargetPreview();
+            return failure("CROSS_GRID_DRAG", `Coordinator #${this.gridId} cannot preview target grid #${target.gridId}`);
+        }
+        const source = this.#state.source;
+        const plan = createGridDropPlan(source, target);
+        if (isPlanError(plan)) {
+            this.#clearTargetPreview();
+            return {
+                error: plan,
+                ok: false
+            };
+        }
+        if (!this.#transaction) {
+            const result = this.controller.beginTransaction("drag");
+            if (!result.ok) return {
+                error: result.error,
+                ok: false
+            };
+            this.#transaction = result.transaction;
+        }
+        const result = "existing-item" === source.kind ? this.#transaction.validateReplacement(plan.commands) : this.#transaction.replace(plan.commands);
+        if (!result.ok) {
+            this.#clearTargetPreview();
+            return this.#commandFailure(result);
+        }
+        this.#state = {
+            phase: "previewing",
+            plan,
+            source,
+            target
+        };
+        return {
+            ok: true,
+            state: this.#state
+        };
+    }
+    commit() {
+        if ("previewing" !== this.#state.phase || !this.#transaction) return failure("INVALID_TRANSITION", `Cannot commit a drag while ${this.#state.phase}`);
+        const { plan, source } = this.#state;
+        if ("existing-item" === source.kind) {
+            const applied = this.#transaction.replace(plan.commands);
+            if (!applied.ok) return this.#commandFailure(applied);
+        }
+        const result = this.#transaction.commit();
+        if (!result.ok) return {
+            error: result.error,
+            ok: false
+        };
+        this.#transaction = void 0;
+        this.#sourceRemovedBaseline = false;
+        this.#state = {
+            phase: "committed",
+            source
+        };
+        return {
+            ok: true,
+            state: this.#state
+        };
+    }
+    clearPreview() {
+        if ("previewing" !== this.#state.phase) return failure("INVALID_TRANSITION", `Cannot clear a preview while ${this.#state.phase}`);
+        const result = this.#clearTargetPreview();
+        if (result && !result.ok) return "command" in result ? this.#commandFailure(result) : {
+            error: result.error,
+            ok: false
+        };
+        return {
+            ok: true,
+            state: this.#state
+        };
+    }
+    cancel() {
+        if ("dragging" !== this.#state.phase && "previewing" !== this.#state.phase) return failure("INVALID_TRANSITION", `Cannot cancel a drag while ${this.#state.phase}`);
+        const source = this.#state.source;
+        const result = this.#rollbackPreview();
+        if (result && !result.ok) return {
+            error: result.error,
+            ok: false
+        };
+        this.#state = {
+            phase: "cancelled",
+            source
+        };
+        return {
+            ok: true,
+            state: this.#state
+        };
+    }
+    dispose() {
+        if (this.#transaction) {
+            const result = this.#transaction.rollback();
+            this.#transaction = void 0;
+            if (!result.ok) throw Error(result.error.message);
+        }
+        this.#sourceRemovedBaseline = false;
+        this.#state = {
+            phase: "idle"
+        };
+    }
+    #clearTargetPreview() {
+        if (this.#sourceRemovedBaseline && this.#transaction) {
+            const result = this.#transaction.replace([]);
+            if ("previewing" === this.#state.phase) this.#state = {
+                phase: "dragging",
+                source: this.#state.source
+            };
+            return result;
+        }
+        return this.#rollbackPreview();
+    }
+    #rollbackPreview() {
+        const result = this.#transaction?.rollback();
+        this.#transaction = void 0;
+        this.#sourceRemovedBaseline = false;
+        if ("previewing" === this.#state.phase) this.#state = {
+            phase: "dragging",
+            source: this.#state.source
+        };
+        return result;
+    }
+    #commandFailure(result) {
+        return failure("TRANSACTION_FAILURE", `${result.error.code}: ${result.error.message}`);
+    }
+}
+export { GridDragCoordinator, createGridDropPlan };