svelte-flexiboards 0.1.0

package/dist/system/target.svelte.js

@@ -0,0 +1,397 @@
+import { getContext, setContext, untrack } from "svelte";
+import { getFlexiboardCtx, getInternalFlexiboardCtx, InternalFlexiBoardController } from "./provider.svelte.js";
+import { FlexiWidgetController } from "./widget.svelte.js";
+import { SvelteSet } from "svelte/reactivity";
+import { FlowFlexiGrid, FlexiGrid, FreeFormFlexiGrid } from "./grid.svelte.js";
+export class InternalFlexiTargetController {
+    widgets = $state(new SvelteSet());
+    provider = $state();
+    #providerTargetDefaults = $derived(this.provider?.config?.targetDefaults);
+    providerWidgetDefaults = $derived(this.provider?.config?.widgetDefaults);
+    /**
+     * Stores the underlying state of the target.
+     */
+    #state = $state({
+        hovered: false,
+        actionWidget: null,
+        prepared: false
+    });
+    #dropzoneWidget = $state({
+        value: null
+    });
+    #mouseCellPosition = $state({
+        x: 0,
+        y: 0
+    });
+    key;
+    #grid = null;
+    #preGrabSnapshot = null;
+    #gridSnapshot = null;
+    #targetConfig = $state(undefined);
+    config = $derived({
+        baseColumns: untrack(() => this.#targetConfig?.baseColumns ?? this.#providerTargetDefaults?.baseColumns ?? null),
+        baseRows: untrack(() => this.#targetConfig?.baseRows ?? this.#providerTargetDefaults?.baseRows ?? null),
+        layout: this.#targetConfig?.layout ?? this.#providerTargetDefaults?.layout ?? {
+            type: "flow",
+            flowAxis: "row",
+            placementStrategy: "append"
+        },
+        rowSizing: this.#targetConfig?.rowSizing ?? this.#providerTargetDefaults?.rowSizing ?? "minmax(1rem, auto)",
+        columnSizing: this.#targetConfig?.columnSizing ?? this.#providerTargetDefaults?.columnSizing ?? "minmax(0, 1fr)",
+        widgetDefaults: this.#targetConfig?.widgetDefaults
+    });
+    constructor(provider, config, key) {
+        this.provider = provider;
+        // If we weren't provided a key, the provider will generate one for us.
+        this.key = provider.addTarget(this, key);
+        this.#targetConfig = config;
+    }
+    #tryAddWidget(widget, x, y, width, height) {
+        const added = this.grid.tryPlaceWidget(widget, x, y, width, height);
+        if (added) {
+            this.widgets.add(widget);
+            widget.target = this;
+        }
+        return added;
+    }
+    createGrid() {
+        if (this.#grid) {
+            console.warn("A grid already exists but is being replaced. If this is due to a hot reload, this is no cause for alarm.");
+        }
+        const layout = this.config.layout;
+        switch (layout.type) {
+            case "free":
+                this.#grid = new FreeFormFlexiGrid(this, this.config);
+                break;
+            case "flow":
+                this.#grid = new FlowFlexiGrid(this, this.config);
+                break;
+        }
+        return this.#grid;
+    }
+    createWidget(config) {
+        const [x, y, width, height] = [config.x, config.y, config.width, config.height];
+        const widget = new FlexiWidgetController({
+            type: "target",
+            target: this,
+            config
+        });
+        // If the widget can't be added, it's probably a collision.
+        if (!this.#tryAddWidget(widget, x, y, width, height)) {
+            console.warn("Failed to add widget to target. Check that the widget's x and y coordinates do not lead to an unresolvable collision.");
+            return undefined;
+        }
+        return widget;
+    }
+    /**
+     * Deletes the given widget from this target, if it exists.
+     * @returns Whether the widget was deleted.
+     */
+    deleteWidget(widget) {
+        const deleted = this.widgets.delete(widget);
+        this.grid.removeWidget(widget);
+        return deleted;
+    }
+    /**
+     * Imports a layout of widgets into this target, replacing any existing widgets.
+     * @param layout The layout to import.
+     */
+    importLayout(layout) {
+        this.widgets.clear();
+        this.grid.clear();
+        for (const config of layout) {
+            this.createWidget(config);
+        }
+    }
+    /**
+     * Exports the current layout of widgets from this target.
+     * @returns The layout of widgets.
+     */
+    exportLayout() {
+        const result = [];
+        // Likely much more information than needed, but we've got it.
+        for (const widget of this.widgets) {
+            result.push({
+                component: widget.component,
+                componentProps: widget.componentProps,
+                snippet: widget.snippet,
+                width: widget.width,
+                height: widget.height,
+                x: widget.x,
+                y: widget.y,
+                draggable: widget.draggable,
+                resizability: widget.resizability,
+                className: widget.className,
+                metadata: widget.metadata
+            });
+        }
+        return result;
+    }
+    #createShadow(of) {
+        const shadow = new FlexiWidgetController({
+            type: "target",
+            target: this,
+            config: {
+                width: of.width,
+                height: of.height,
+                component: of.component,
+                draggable: of.draggable,
+                resizability: of.resizability,
+                snippet: of.snippet,
+                className: of.className,
+                componentProps: of.componentProps
+            },
+            isShadow: true
+        });
+        this.widgets.add(shadow);
+        return shadow;
+    }
+    // Events
+    onpointerenter() {
+        this.hovered = true;
+        this.provider.onpointerentertarget({
+            target: this
+        });
+    }
+    onpointerleave() {
+        this.hovered = false;
+        this.provider.onpointerleavetarget({
+            target: this
+        });
+    }
+    grabWidget(params) {
+        // Take a snapshot of the grid before the widget is removed, so if the widget is not successfully placed
+        // we can restore the grid to its original state.
+        this.#preGrabSnapshot = this.grid.takeSnapshot();
+        // Remove the widget from the grid as it's now in a floating state.
+        this.grid.removeWidget(params.widget);
+        return this.provider.onwidgetgrabbed({
+            ...params,
+            target: this
+        });
+    }
+    restorePreGrabSnapshot() {
+        if (!this.#preGrabSnapshot) {
+            return;
+        }
+        this.grid.restoreFromSnapshot(this.#preGrabSnapshot);
+        this.forgetPreGrabSnapshot();
+    }
+    forgetPreGrabSnapshot() {
+        this.#preGrabSnapshot = null;
+    }
+    startResizeWidget(params) {
+        // Remove the widget as it's now in a pseudo-floating state.
+        this.grid.removeWidget(params.widget);
+        const result = this.provider.onwidgetstartresize({
+            ...params,
+            target: this
+        });
+        if (result) {
+            this.actionWidget = {
+                action: "resize",
+                widget: params.widget
+            };
+            this.#createDropzoneWidget();
+        }
+        return result;
+    }
+    tryDropWidget(widget) {
+        const actionWidget = this.actionWidget;
+        if (!actionWidget) {
+            return false;
+        }
+        const [x, y, width, height] = this.#getDropzoneLocation(actionWidget);
+        this.actionWidget = null;
+        this.#removeDropzoneWidget();
+        // Try to formally place the widget in the grid, which will also serve as a final check that
+        // the drop is possible.
+        return this.#tryAddWidget(widget, x, y, width, height);
+    }
+    onmousegridcellmove(event) {
+        this.#updateMouseCellPosition(event.cellX, event.cellY);
+        this.#updateDropzoneWidget();
+    }
+    ongrabbedwidgetover(event) {
+        this.actionWidget = {
+            action: "grab",
+            widget: event.widget
+        };
+        this.#createDropzoneWidget();
+    }
+    ongrabbedwidgetleave() {
+        this.actionWidget = null;
+        this.#removeDropzoneWidget();
+    }
+    oninitialloadcomplete() {
+        this.#state.prepared = true;
+    }
+    #updateMouseCellPosition(x, y) {
+        this.#mouseCellPosition.x = x;
+        this.#mouseCellPosition.y = y;
+    }
+    #createDropzoneWidget() {
+        if (this.dropzoneWidget || !this.actionWidget) {
+            return;
+        }
+        const grid = this.grid;
+        // Take a snapshot of the grid so we can restore its state if the hover stops.
+        this.#gridSnapshot = grid.takeSnapshot();
+        const dropzoneWidget = this.#createShadow(this.actionWidget.widget);
+        this.dropzoneWidget = dropzoneWidget;
+        let [x, y, width, height] = this.#getDropzoneLocation(this.actionWidget);
+        grid.tryPlaceWidget(this.dropzoneWidget, x, y, width, height);
+    }
+    #updateDropzoneWidget() {
+        const dropzoneWidget = this.dropzoneWidget;
+        const actionWidget = this.actionWidget;
+        if (!dropzoneWidget || !actionWidget) {
+            return;
+        }
+        let [x, y, width, height] = this.#getDropzoneLocation(actionWidget);
+        const grid = this.grid;
+        // No change, no need to update.
+        if (x === dropzoneWidget.x && y === dropzoneWidget.y && width === dropzoneWidget.width && height === dropzoneWidget.height) {
+            return;
+        }
+        grid.removeWidget(dropzoneWidget);
+        grid.restoreFromSnapshot(this.#gridSnapshot);
+        grid.tryPlaceWidget(dropzoneWidget, x, y, width, height);
+    }
+    #getDropzoneLocation(actionWidget) {
+        const mouseCellPosition = this.#mouseCellPosition;
+        switch (actionWidget.action) {
+            case "grab":
+                return this.#getGrabbedDropzoneLocation(actionWidget.widget, mouseCellPosition);
+            case "resize":
+                return this.#getResizingDropzoneLocation(actionWidget.widget, mouseCellPosition);
+        }
+    }
+    #getGrabbedDropzoneLocation(grabbedWidget, mouseCellPosition) {
+        return [mouseCellPosition.x, mouseCellPosition.y, grabbedWidget.width, grabbedWidget.height];
+    }
+    #getResizingDropzoneLocation(resizingWidget, mouseCellPosition) {
+        const { width, height } = this.#getNewWidgetHeightAndWidth(resizingWidget, mouseCellPosition);
+        return [resizingWidget.x, resizingWidget.y, width, height];
+    }
+    #getNewWidgetHeightAndWidth(widget, mouseCellPosition) {
+        const grid = this.grid;
+        let newWidth = mouseCellPosition.x - widget.x;
+        let newHeight = mouseCellPosition.y - widget.y;
+        // If the widget is in a flow layout, then they can't change their flow axis dimensions.
+        // NEXT: show this visually to the user by faking the "horizontal"/"vertical" resizable modes.
+        if (this.config.layout.type == "flow" && this.config.layout.flowAxis == "row") {
+            newHeight = widget.height;
+        }
+        else if (this.config.layout.type == "flow" && this.config.layout.flowAxis == "column") {
+            newWidth = widget.width;
+        }
+        switch (widget.resizability) {
+            case "horizontal":
+                return { width: newWidth, height: widget.height };
+            case "vertical":
+                return { width: widget.width, height: newHeight };
+            case "both":
+                return { width: newWidth, height: newHeight };
+        }
+        return { width: widget.width, height: widget.height };
+    }
+    #removeDropzoneWidget() {
+        if (!this.dropzoneWidget) {
+            return;
+        }
+        const grid = this.grid;
+        grid.removeWidget(this.dropzoneWidget);
+        this.widgets.delete(this.dropzoneWidget);
+        grid.restoreFromSnapshot(this.#gridSnapshot);
+        this.#gridSnapshot = null;
+        this.dropzoneWidget = null;
+    }
+    // State-related getters and setters
+    /**
+     * Whether the target is currently being hovered over by the mouse.
+     */
+    get hovered() {
+        return this.#state.hovered;
+    }
+    set hovered(value) {
+        this.#state.hovered = value;
+    }
+    /**
+     * When set, this indicates that a widget is currently being hovered over this target.
+     */
+    get actionWidget() {
+        return this.#state.actionWidget;
+    }
+    set actionWidget(value) {
+        this.#state.actionWidget = value;
+    }
+    /**
+     * Whether the target is prepared and ready to render widgets.
+     */
+    get prepared() {
+        return this.#state.prepared;
+    }
+    /**
+     * The number of columns currently being used in the target grid.
+     * This value is readonly.
+     */
+    get columns() {
+        return this.#grid?.columns;
+    }
+    /**
+     * The number of rows currently being used in the target grid.
+     * This value is readonly.
+     */
+    get rows() {
+        return this.#grid?.rows;
+    }
+    get grid() {
+        const grid = this.#grid;
+        if (!grid) {
+            throw new Error("Grid is not initialised. Ensure that a FlexiGrid has been created before accessing it.");
+        }
+        return grid;
+    }
+    get dropzoneWidget() {
+        return this.#dropzoneWidget.value;
+    }
+    set dropzoneWidget(value) {
+        this.#dropzoneWidget.value = value;
+    }
+}
+const contextKey = Symbol('flexitarget');
+/**
+ * Creates a new {@link FlexiTargetController} instance in the context of the current FlexiBoard.
+ * @returns A {@link FlexiTargetController} instance.
+ */
+export function flexitarget(config, key) {
+    const provider = getInternalFlexiboardCtx();
+    const target = new InternalFlexiTargetController(provider, config, key);
+    setContext(contextKey, target);
+    return {
+        onpointerenter: () => target.onpointerenter(),
+        onpointerleave: () => target.onpointerleave(),
+        target: target
+    };
+}
+/**
+ * Gets the current {@link InternalFlexiTargetController} instance, if any. Throws an error if no target is found.
+ * @internal
+ * @returns An {@link InternalFlexiTargetController} instance.
+ */
+export function getInternalFlexitargetCtx() {
+    const target = getContext(contextKey);
+    // No provider to attach to.
+    if (!target) {
+        throw new Error("Cannot get FlexiTarget context outside of a registered target. Ensure that flexitarget() (or <FlexiTarget>) is called within a <FlexiBoard> component.");
+    }
+    return target;
+}
+/**
+ * Gets the current {@link FlexiTargetController} instance, if any. Throws an error if no target is found.
+ * @returns A {@link FlexiTargetController} instance.
+ */
+export function getFlexitargetCtx() {
+    return getInternalFlexitargetCtx();
+}

package/dist/system/types.d.ts

@@ -0,0 +1,91 @@
+import type { FlexiWidgetController, FlexiWidgetConfiguration } from "./widget.svelte.js";
+import type { FlexiTargetController, InternalFlexiTargetController } from "./target.svelte.js";
+import type { PointerPositionWatcher } from "./utils.svelte.js";
+import type { FlexiAddController } from "./manage.svelte.js";
+export type ProxiedValue<T> = {
+    value: T;
+};
+export type SvelteClassValue = string | import('clsx').ClassArray | import('clsx').ClassDictionary | undefined | null;
+export type Position = {
+    x: number;
+    y: number;
+};
+export type FlexiCommonProps<T> = {
+    controller?: T;
+    onfirstcreate?: (instance: T) => void;
+};
+export type WidgetResizability = "none" | "horizontal" | "vertical" | "both";
+export type WidgetGrabAction = {
+    action: 'grab';
+    widget: FlexiWidgetController;
+    target?: FlexiTargetController;
+    adder?: FlexiAddController;
+    offsetX: number;
+    offsetY: number;
+    positionWatcher: PointerPositionWatcher;
+    capturedHeightPx: number;
+    capturedWidthPx: number;
+};
+export type WidgetResizeAction = {
+    action: 'resize';
+    widget: FlexiWidgetController;
+    target: FlexiTargetController;
+    offsetX: number;
+    offsetY: number;
+    left: number;
+    top: number;
+    heightPx: number;
+    widthPx: number;
+    initialHeightUnits: number;
+    initialWidthUnits: number;
+    positionWatcher: PointerPositionWatcher;
+};
+export type WidgetAction = WidgetGrabAction | WidgetResizeAction;
+export type WidgetGrabbedParams = {
+    widget: FlexiWidgetController;
+    xOffset: number;
+    yOffset: number;
+    capturedHeight: number;
+    capturedWidth: number;
+};
+export type WidgetStartResizeParams = {
+    widget: FlexiWidgetController;
+    xOffset: number;
+    yOffset: number;
+    left: number;
+    top: number;
+    heightPx: number;
+    widthPx: number;
+};
+export type WidgetGrabbedEvent = WidgetGrabbedParams & {
+    target?: InternalFlexiTargetController;
+    adder?: FlexiAddController;
+};
+export type WidgetStartResizeEvent = WidgetStartResizeParams & {
+    target: InternalFlexiTargetController;
+};
+/**
+ * Event object that captures widget grabbed event data.
+ */
+export type WidgetDroppedEvent = {
+    widget: FlexiWidgetController;
+    preventDefault: () => void;
+};
+export type WidgetOverEvent = {
+    widget: FlexiWidgetController;
+    mousePosition: Position;
+};
+export type WidgetOutEvent = {
+    widget: FlexiWidgetController;
+};
+export type MouseGridCellMoveEvent = {
+    cellX: number;
+    cellY: number;
+};
+export type GrabbedWidgetMouseEvent = {
+    widget: FlexiWidgetController;
+};
+export type HoveredTargetEvent = {
+    target: InternalFlexiTargetController;
+};
+export type FlexiSavedLayout = Record<string, FlexiWidgetConfiguration[]>;

package/dist/system/types.js

@@ -0,0 +1 @@
+export {};

package/dist/system/utils.svelte.d.ts

@@ -0,0 +1,21 @@
+import type { Position, ProxiedValue } from "./types.js";
+import type { FlexiGrid } from "./grid.svelte.js";
+import type { FlexiTargetConfiguration } from "./target.svelte.js";
+export declare class PointerPositionWatcher {
+    #private;
+    constructor(ref: ProxiedValue<HTMLElement | null>);
+    get position(): Position;
+    get ref(): HTMLElement | null;
+}
+type CellPosition = {
+    row: number;
+    column: number;
+};
+export declare class GridDimensionTracker {
+    #private;
+    constructor(grid: FlexiGrid, targetConfig: FlexiTargetConfiguration);
+    watchGrid(): void;
+    updateGridDimensions(): void;
+    getCellFromPointerPosition(clientX: number, clientY: number): CellPosition | null;
+}
+export {};

package/dist/system/utils.svelte.js

@@ -0,0 +1,156 @@
+/*
+    This MousePosition utility class is inspired by the MousePositionState class from Joy of Code's
+    'Creating Reactive Browser APIs In Svelte' video, found at https://youtu.be/BKyENJQ6KdQ.
+*/
+export class PointerPositionWatcher {
+    #position = $state({
+        x: 0,
+        y: 0
+    });
+    #ref = $state();
+    constructor(ref) {
+        this.#ref = ref;
+        const onPointerMove = (event) => {
+            if (!this.ref) {
+                return;
+            }
+            const rect = this.ref.getBoundingClientRect();
+            this.#position.x = event.clientX - rect.left;
+            this.#position.y = event.clientY - rect.top;
+            event.preventDefault();
+        };
+        $effect(() => {
+            window.addEventListener('pointermove', onPointerMove);
+            return () => {
+                window.removeEventListener('pointermove', onPointerMove);
+            };
+        });
+    }
+    get position() {
+        return this.#position;
+    }
+    get ref() {
+        return this.#ref.value;
+    }
+}
+export class GridDimensionTracker {
+    #dimensions = $state({
+        left: 0,
+        width: 0,
+        columns: [],
+        columnString: '',
+        columnGap: 0,
+        top: 0,
+        height: 0,
+        rows: [],
+        rowString: '',
+        rowGap: 0
+    });
+    #grid = $state(null);
+    #rows = $derived(this.#grid?.rows ?? 0);
+    #columns = $derived(this.#grid?.columns ?? 0);
+    #pointerPosition = $state({
+        x: 0,
+        y: 0
+    });
+    #targetConfig = $state({});
+    constructor(grid, targetConfig) {
+        this.#grid = grid;
+        this.#targetConfig = targetConfig;
+    }
+    watchGrid() {
+        // Whenever a change occurs to the grid's dimensions or the underlying widgets, update the sizes.
+        $effect(() => {
+            const grid = this.#grid;
+            const columns = grid.columns ?? 0;
+            const rows = grid.rows ?? 0;
+            this.updateGridDimensions();
+        });
+        // Whenever the grid is resized, update the sizes.
+        $effect(() => {
+            const grid = this.#grid.ref;
+            if (!grid) {
+                return;
+            }
+            const observer = new ResizeObserver((entries) => {
+                const entry = entries[0];
+                if (!entry || !grid) {
+                    return;
+                }
+                this.updateGridDimensions();
+            });
+            observer.observe(grid);
+            return () => {
+                observer.disconnect();
+            };
+        });
+    }
+    updateGridDimensions() {
+        const grid = this.#grid;
+        const gridElement = grid?.ref;
+        if (!gridElement || !window) {
+            return;
+        }
+        const rect = gridElement.getBoundingClientRect();
+        const style = window.getComputedStyle(gridElement);
+        // Computed style gives us pixel values for each column and row of the grid.
+        const templateColumns = style.getPropertyValue('grid-template-columns');
+        const templateRows = style.getPropertyValue('grid-template-rows');
+        const gapX = style.getPropertyValue('grid-column-gap');
+        const gapY = style.getPropertyValue('grid-row-gap');
+        // If the dimensions are unchanged, we don't need to update them.
+        if (templateColumns == this.#dimensions.columnString
+            && templateRows == this.#dimensions.rowString
+            && this.#dimensions.left == rect.left
+            && this.#dimensions.top == rect.top
+            && this.#dimensions.width == rect.width
+            && this.#dimensions.height == rect.height
+            && grid.rows == this.#dimensions.rows.length
+            && grid.columns == this.#dimensions.columns.length) {
+            return;
+        }
+        const columns = templateColumns.split(' ').map(column => parseFloat(column.match(/(\d+\.?\d*)px/)?.[1] ?? '0'));
+        const rows = templateRows.split(' ').map(row => parseFloat(row.match(/(\d+\.?\d*)px/)?.[1] ?? '0'));
+        // Update in-place to avoid replacing the proxy object.
+        this.#dimensions.left = rect.left;
+        this.#dimensions.width = rect.width;
+        this.#dimensions.columns = columns;
+        this.#dimensions.top = rect.top;
+        this.#dimensions.height = rect.height;
+        this.#dimensions.rows = rows;
+        this.#dimensions.columnGap = parseFloat(gapX.match(/(\d+\.?\d*)px/)?.[1] ?? '0');
+        this.#dimensions.rowGap = parseFloat(gapY.match(/(\d+\.?\d*)px/)?.[1] ?? '0');
+    }
+    getCellFromPointerPosition(clientX, clientY) {
+        if (!this.#grid?.ref) {
+            return null;
+        }
+        this.#pointerPosition.x = clientX;
+        this.#pointerPosition.y = clientY;
+        let xCell = this.#findCell(clientX, this.#dimensions.left, this.#dimensions.width, this.#dimensions.columnGap, this.#dimensions.columns);
+        let yCell = this.#findCell(clientY, this.#dimensions.top, this.#dimensions.height, this.#dimensions.rowGap, this.#dimensions.rows);
+        return {
+            row: yCell,
+            column: xCell
+        };
+    }
+    #findCell(pointerLocation, start, size, gap, axisCoordinates) {
+        // If outside the axis, then return the ends.
+        if (pointerLocation < start) {
+            return 0;
+        }
+        if (pointerLocation >= start + size) {
+            return axisCoordinates.length;
+        }
+        let subtotal = start;
+        for (let i = 0; i < axisCoordinates.length; i++) {
+            const base = subtotal;
+            subtotal += axisCoordinates[i] + gap;
+            const proportionAlong = (pointerLocation - base) / (subtotal - base);
+            if (pointerLocation < subtotal) {
+                return i + proportionAlong;
+            }
+        }
+        return axisCoordinates.length;
+    }
+}