svelte-flexiboards 0.1.0

package/dist/system/index.d.ts

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

package/dist/system/index.js

@@ -0,0 +1 @@
+"use strict";

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

@@ -0,0 +1,25 @@
+import { type InternalFlexiBoardController } from "./provider.svelte.js";
+import type { WidgetGrabbedParams } from "./types.js";
+import { FlexiWidgetController, type FlexiWidgetConfiguration } from "./widget.svelte.js";
+export type FlexiAddWidgetFn = () => AdderWidgetConfiguration | null;
+export type AdderWidgetConfiguration = {
+    widget: FlexiWidgetConfiguration;
+    widthPx?: number;
+    heightPx?: number;
+};
+export declare class FlexiAddController {
+    #private;
+    newWidget?: FlexiWidgetController;
+    constructor(provider: InternalFlexiBoardController, addWidgetFn: FlexiAddWidgetFn);
+    onpointerdown(event: PointerEvent): void;
+    onstartwidgetdragin(event: WidgetGrabbedParams): import("./types.js").WidgetGrabAction | null;
+    onstopwidgetdragin(): void;
+}
+export declare function flexiadd(addWidgetFn: FlexiAddWidgetFn): {
+    adder: FlexiAddController;
+    onpointerdown: (event: PointerEvent) => void;
+};
+export declare function flexidelete(): {
+    onpointerenter: () => void;
+    onpointerleave: () => void;
+};

package/dist/system/manage.svelte.js

@@ -0,0 +1,54 @@
+import { getFlexiboardCtx, getInternalFlexiboardCtx } from "./provider.svelte.js";
+import { FlexiWidgetController } from "./widget.svelte.js";
+export class FlexiAddController {
+    #provider;
+    #addWidget;
+    newWidget = $state(undefined);
+    constructor(provider, addWidgetFn) {
+        this.#provider = provider;
+        this.#addWidget = addWidgetFn;
+        this.onpointerdown = this.onpointerdown.bind(this);
+    }
+    onpointerdown(event) {
+        const config = this.#addWidget();
+        if (!config || !config.widget) {
+            return;
+        }
+        // Create a widget under this FlexiAdd, which will automatically place it into a grabbed state.
+        this.newWidget = new FlexiWidgetController({
+            type: "adder",
+            adder: this,
+            config: config.widget,
+            widthPx: config.widthPx ?? 100,
+            heightPx: config.heightPx ?? 100
+        });
+        // Don't implicitly keep the pointer capture, as then mobile can't move the widget in and out of targets.
+        event.target.releasePointerCapture(event.pointerId);
+        event.preventDefault();
+    }
+    onstartwidgetdragin(event) {
+        return this.#provider.onwidgetgrabbed({
+            ...event,
+            adder: this
+        });
+    }
+    onstopwidgetdragin() {
+        // Whether it got placed into a target or not, the FlexiAdd's work is done.
+        this.newWidget = undefined;
+    }
+}
+export function flexiadd(addWidgetFn) {
+    const provider = getInternalFlexiboardCtx();
+    const adder = new FlexiAddController(provider, addWidgetFn);
+    return {
+        adder,
+        onpointerdown: (event) => adder.onpointerdown(event)
+    };
+}
+export function flexidelete() {
+    const provider = getInternalFlexiboardCtx();
+    return {
+        onpointerenter: () => provider.onenterdeleter(),
+        onpointerleave: () => provider.onleavedeleter()
+    };
+}

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

@@ -0,0 +1,51 @@
+import type { HoveredTargetEvent, WidgetGrabAction, WidgetResizeAction, WidgetGrabbedEvent, WidgetStartResizeEvent } from "./types.js";
+import type { InternalFlexiTargetController, FlexiTargetDefaults, FlexiTargetController } from "./target.svelte.js";
+import type { FlexiWidgetController, FlexiWidgetDefaults } from "./widget.svelte.js";
+import type { FlexiBoardProps } from "../components/flexi-board.svelte";
+export type FlexiBoardConfiguration = {
+    widgetDefaults?: FlexiWidgetDefaults;
+    targetDefaults?: FlexiTargetDefaults;
+};
+export interface FlexiBoardController {
+    /**
+     * The reactive styling to apply to the board's root element.
+     */
+    style: string;
+    /**
+     * The reactive DOM reference to the board's root element.
+     */
+    ref: HTMLElement | null;
+    /**
+     * Moves an existing widget from one target to another.
+     * @param widget The widget to move.
+     * @param from The target to move the widget from.
+     * @param to The target to move the widget to.
+     */
+    moveWidget(widget: FlexiWidgetController, from: FlexiTargetController | undefined, to: FlexiTargetController): void;
+}
+export declare class InternalFlexiBoardController implements FlexiBoardController {
+    #private;
+    config?: FlexiBoardConfiguration;
+    constructor(props: FlexiBoardProps);
+    style: string;
+    get ref(): HTMLElement | null;
+    set ref(ref: HTMLElement | null);
+    addTarget(target: InternalFlexiTargetController, key?: string): string;
+    onpointerentertarget(event: HoveredTargetEvent): void;
+    onpointerleavetarget(event: HoveredTargetEvent): void;
+    onenterdeleter(): void;
+    onleavedeleter(): void;
+    onwidgetgrabbed(event: WidgetGrabbedEvent): WidgetGrabAction | null;
+    onwidgetstartresize(event: WidgetStartResizeEvent): WidgetResizeAction | null;
+    stopScroll(event: TouchEvent): void;
+    handleWidgetRelease(): void;
+    oninitialloadcomplete(): void;
+    /**
+     * Moves a widget from one target to another.
+     * @param widget The widget to move.
+     * @param from The target to move the widget from.
+     * @param to The target to move the widget to.
+     */
+    moveWidget(widget: FlexiWidgetController, from: FlexiTargetController | undefined, to: FlexiTargetController): boolean;
+}
+export declare function flexiboard(props: FlexiBoardProps): FlexiBoardController;

package/dist/system/provider.svelte.js

@@ -0,0 +1,290 @@
+import { getContext, setContext } from "svelte";
+import { PointerPositionWatcher } from "./utils.svelte.js";
+export class InternalFlexiBoardController {
+    #currentWidgetAction = $state(null);
+    #targets = new Map();
+    #hoveredTarget = $state(null);
+    #hoveredOverDeleter = $state(false);
+    #ref = $state({ value: null });
+    #positionWatcher = new PointerPositionWatcher(this.#ref);
+    #rawProps = $state(undefined);
+    config = $derived(this.#rawProps?.config);
+    #nextTargetIndex = 0;
+    #storedLoadLayout = null;
+    #ready = false;
+    constructor(props) {
+        // Track the props proxy so our config reactively updates.
+        this.#rawProps = props;
+        const onpointerup = this.#onpointerup.bind(this);
+        $effect(() => {
+            window.addEventListener('pointerup', onpointerup);
+            return () => {
+                window.removeEventListener('pointerup', onpointerup);
+            };
+        });
+    }
+    style = $derived.by(() => {
+        if (!this.#currentWidgetAction) {
+            return 'position: relative;';
+        }
+        return `position: relative; overflow: hidden;`;
+    });
+    get ref() {
+        return this.#ref.value;
+    }
+    set ref(ref) {
+        this.#ref.value = ref;
+    }
+    addTarget(target, key) {
+        // If they didn't bring their own key, assign one.
+        key ??= this.#nextTargetKey();
+        if (this.#targets.has(key)) {
+            throw new Error(`A duplicate key, '${target.key}' was used during the instantiation of a FlexiTarget. Ensure that all FlexiTarget keys are unique.`);
+        }
+        this.#targets.set(key, target);
+        return key;
+    }
+    onpointerentertarget(event) {
+        this.#hoveredTarget = event.target;
+        // If a widget is currently being grabbed, propagate a grabbed widget over event to this target.
+        const currentAction = this.#currentWidgetAction;
+        if (currentAction?.action === 'grab') {
+            event.target.ongrabbedwidgetover({
+                widget: currentAction.widget
+            });
+        }
+    }
+    onpointerleavetarget(event) {
+        // Failsafe in case another target is already registered as hovered.
+        if (this.#hoveredTarget === event.target) {
+            this.#hoveredTarget = null;
+        }
+        // If a widget is currently being grabbed, propagate a grabbed widget over event to this target.
+        const currentAction = this.#currentWidgetAction;
+        if (currentAction?.action === 'grab') {
+            event.target.ongrabbedwidgetleave();
+        }
+        // If it's resize, then we don't care that the pointer has left the target.
+    }
+    onenterdeleter() {
+        this.#hoveredOverDeleter = true;
+    }
+    onleavedeleter() {
+        this.#hoveredOverDeleter = false;
+    }
+    onwidgetgrabbed(event) {
+        if (this.#currentWidgetAction) {
+            return null;
+        }
+        const action = {
+            action: 'grab',
+            target: event.target,
+            widget: event.widget,
+            adder: event.adder,
+            offsetX: event.xOffset,
+            offsetY: event.yOffset,
+            capturedHeightPx: event.capturedHeight,
+            capturedWidthPx: event.capturedWidth,
+            positionWatcher: this.#positionWatcher
+        };
+        this.#currentWidgetAction = action;
+        this.#lockViewport();
+        // Only matters if the event source is a target, which isn't the case when the widget is being dragged into the board.
+        if (event.target) {
+            event.target.ongrabbedwidgetover({
+                widget: event.widget
+            });
+        }
+        return action;
+    }
+    onwidgetstartresize(event) {
+        if (this.#currentWidgetAction) {
+            return null;
+        }
+        const providerRef = this.ref;
+        if (!providerRef) {
+            throw new Error("Provider ref is not set");
+        }
+        const providerRect = providerRef.getBoundingClientRect();
+        const action = {
+            action: 'resize',
+            target: event.target,
+            widget: event.widget,
+            offsetX: event.xOffset - providerRect.left,
+            offsetY: event.yOffset - providerRect.top,
+            left: event.left - providerRect.left,
+            top: event.top - providerRect.top,
+            heightPx: event.heightPx,
+            widthPx: event.widthPx,
+            initialHeightUnits: event.widget.height,
+            initialWidthUnits: event.widget.width,
+            positionWatcher: this.#positionWatcher
+        };
+        this.#currentWidgetAction = action;
+        this.#lockViewport();
+        return action;
+    }
+    #lockViewport() {
+        document.documentElement.style.overscrollBehaviorY = 'contain';
+        document.documentElement.style.overflow = 'hidden';
+        document.documentElement.style.touchAction = 'none';
+        this.stopScroll = this.stopScroll.bind(this);
+        document.addEventListener('touchmove', this.stopScroll, { passive: false });
+    }
+    #unlockViewport() {
+        document.documentElement.style.overscrollBehaviorY = 'auto';
+        document.documentElement.style.overflow = 'auto';
+        document.documentElement.style.touchAction = 'auto';
+        document.removeEventListener('touchmove', this.stopScroll);
+    }
+    stopScroll(event) {
+        // If a scroll is in progress, there's nothing we can do to stop it and so we'll just release the widget.
+        if (!event.cancelable) {
+            this.handleWidgetRelease();
+            return;
+        }
+        event.preventDefault();
+    }
+    #onpointerup(event) {
+        if (!this.#currentWidgetAction) {
+            return;
+        }
+        this.handleWidgetRelease();
+    }
+    handleWidgetRelease() {
+        this.#unlockViewport();
+        const currentAction = this.#currentWidgetAction;
+        switch (currentAction.action) {
+            case 'grab':
+                this.#handleGrabbedWidgetRelease(currentAction);
+                break;
+            case 'resize':
+                this.#handleResizingWidgetRelease(currentAction);
+                break;
+        }
+    }
+    oninitialloadcomplete() {
+        this.#ready = true;
+        // if(this.#storedLoadLayout) {
+        // 	this.importLayout(this.#storedLoadLayout);
+        // }
+    }
+    // NEXT: Add import/export layout.
+    // importLayout(layout: FlexiSavedLayout) {
+    // 	// The board isn't ready to import widgets yet, so we'll store the layout and import it later.
+    // 	if(!this.#ready) {
+    // 		this.#storedLoadLayout = layout;
+    // 		return;
+    // 	}
+    // 	// Good to go - import the widgets into their respective targets.
+    // 	this.#targets.forEach(target => {
+    // 		target.importLayout(layout[target.key]);
+    // 	});
+    // }
+    // exportLayout(): FlexiSavedLayout {
+    // 	const result: FlexiSavedLayout = {};
+    // 	// Grab the current layout of each target.
+    // 	this.#targets.forEach(target => {
+    // 		result[target.key] = target.exportLayout();
+    // 	});
+    // 	return result;
+    // }
+    #handleGrabbedWidgetRelease(action) {
+        // If a deleter is hovered, then we'll delete the widget.
+        if (this.#hoveredOverDeleter) {
+            action.widget.delete();
+            this.#currentWidgetAction = null;
+            return;
+        }
+        // If no target is hovered, then just release the widget.
+        if (!this.#hoveredTarget) {
+            this.#releaseCurrentWidgetAction();
+            return;
+        }
+        if (action.adder) {
+            action.adder.onstopwidgetdragin();
+        }
+        const shouldDrop = this.moveWidget(action.widget, action.target, this.#hoveredTarget);
+        if (!shouldDrop) {
+            this.#releaseCurrentWidgetAction();
+            return;
+        }
+        this.#releaseCurrentWidgetAction(true);
+    }
+    #handleResizingWidgetRelease(action) {
+        action.target.tryDropWidget(action.widget);
+        this.#releaseCurrentWidgetAction();
+    }
+    #releaseCurrentWidgetAction(actionSucceeded = false) {
+        const currentWidgetAction = this.#currentWidgetAction;
+        if (!currentWidgetAction) {
+            return;
+        }
+        const widget = currentWidgetAction.widget;
+        // If the widget is still being grabbed, we'll need to release it.
+        if (widget.currentAction) {
+            widget.currentAction = null;
+        }
+        // If this widget is new from an adder, then it needs to remove it regardless of the outcome.
+        if (currentWidgetAction.action == "grab" && currentWidgetAction.adder) {
+            currentWidgetAction.widget.adder = undefined;
+            currentWidgetAction.adder.onstopwidgetdragin();
+        }
+        // The widget wasn't placed successfully, so go back to the pre-grab state on the target.
+        if (!actionSucceeded && currentWidgetAction.target) {
+            currentWidgetAction.target.restorePreGrabSnapshot();
+        }
+        this.#currentWidgetAction = null;
+    }
+    /**
+     * Moves a widget from one target to another.
+     * @param widget The widget to move.
+     * @param from The target to move the widget from.
+     * @param to The target to move the widget to.
+     */
+    moveWidget(widget, from, to) {
+        let defaultPrevented = false;
+        const dropSuccessful = to.tryDropWidget(widget);
+        if (defaultPrevented) {
+            return false;
+        }
+        // If the widget is new, it has no from target.
+        if (from) {
+            from.widgets.delete(widget);
+            from.forgetPreGrabSnapshot();
+        }
+        widget.target = to;
+        to.widgets.add(widget);
+        return true;
+    }
+    #nextTargetKey() {
+        return `target-${this.#nextTargetIndex++}`;
+    }
+}
+const contextKey = Symbol('flexiboard');
+export function flexiboard(props) {
+    const board = new InternalFlexiBoardController(props);
+    setContext(contextKey, board);
+    return board;
+}
+/**
+ * Gets the current {@link InternalFlexiBoardController} instance, if any. Throws an error if no board is found.
+ * @internal
+ * @returns An {@link InternalFlexiBoardController} instance.
+ */
+export function getInternalFlexiboardCtx() {
+    const board = getContext(contextKey);
+    // No provider to attach to.
+    if (!board) {
+        throw new Error("Cannot get FlexiBoard context outside of a registered board. Ensure that flexiboard() (or <FlexiProvider>) is called.");
+    }
+    return board;
+}
+/**
+ * Gets the current {@link FlexiBoard} instance, if any. Throws an error if no board is found.
+ * @internal
+ * @returns A {@link FlexiBoard} instance.
+ */
+export function getFlexiboardCtx() {
+    return getInternalFlexiboardCtx();
+}

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

@@ -0,0 +1,179 @@
+import { InternalFlexiBoardController } from "./provider.svelte.js";
+import { type FlexiWidgetConfiguration, type FlexiWidgetDefaults, FlexiWidgetController } from "./widget.svelte.js";
+import type { GrabbedWidgetMouseEvent, MouseGridCellMoveEvent, WidgetAction, WidgetGrabAction, WidgetGrabbedParams, WidgetStartResizeParams } from "./types.js";
+import { SvelteSet } from "svelte/reactivity";
+import { FlexiGrid, type FlowTargetLayout, type FreeFormTargetLayout } from "./grid.svelte.js";
+type TargetSizingFn = ({ target, grid }: {
+    target: FlexiTargetController;
+    grid: FlexiGrid;
+}) => string;
+export type TargetSizing = TargetSizingFn | string;
+export type FlexiTargetDefaults = {
+    /**
+     * The base number of columns for the target's grid. Defaults to 1.
+     */
+    baseColumns?: number | null;
+    /**
+     * The base number of rows for the target's grid. Defaults to 1.
+     */
+    baseRows?: number | null;
+    /**
+     * Allows the specifying of the value inside the `repeat()` function of the `grid-template-rows` CSS property for the target.
+     */
+    rowSizing?: TargetSizing;
+    /**
+     * Allows the specifying of the value inside the `repeat()` function of the `grid-template-columns` CSS property for the target.
+     */
+    columnSizing?: TargetSizing;
+    /**
+     * The layout algorithm and parameters to use for the target grid.
+     */
+    layout?: TargetLayout;
+};
+export type FlexiTargetPartialConfiguration = FlexiTargetDefaults & {
+    widgetDefaults?: FlexiWidgetDefaults;
+};
+export type FlexiTargetConfiguration = Required<FlexiTargetDefaults> & {
+    widgetDefaults?: FlexiWidgetDefaults;
+};
+export type TargetLayout = FlowTargetLayout | FreeFormTargetLayout;
+export interface FlexiTargetController {
+    /**
+     * The widgets currently in this target.
+     */
+    widgets: SvelteSet<FlexiWidgetController>;
+    /**
+     * The reactive configuration of the target.
+     */
+    config: FlexiTargetConfiguration;
+    /**
+     * The reactive default widget configuration passed through from the provider, if it exists.
+     */
+    providerWidgetDefaults?: FlexiWidgetDefaults;
+    /**
+     * Whether the target is prepared and ready to render widgets.
+     */
+    get prepared(): boolean;
+    /**
+     * Creates a new widget under this target.
+     * @param config The configuration of the widget to create.
+     * @returns The newly created widget if it could be placed, or undefined if not.
+     */
+    createWidget(config: FlexiWidgetConfiguration): FlexiWidgetController | undefined;
+    /**
+     * Deletes the given widget from this target, if it exists.
+     * @returns Whether the widget was deleted.
+     */
+    deleteWidget(widget: FlexiWidgetController): boolean;
+    /**
+     * Restores the target to its pre-grab state.
+     * @remarks This is not intended for external use.
+     */
+    restorePreGrabSnapshot(): void;
+    /**
+     * Forgets the pre-grab state of the target.
+     * @remarks This is not intended for external use.
+     */
+    forgetPreGrabSnapshot(): void;
+    /**
+     * Attempts to drop a widget into this target.
+     * @param widget The widget to drop.
+     * @returns Whether the widget was dropped.
+     */
+    tryDropWidget(widget: FlexiWidgetController): boolean;
+    /**
+     * Grabs a widget.
+     * @param params The parameters for the grab action.
+     * @returns The action that was started, or null if the action couldn't be started.
+     */
+    grabWidget(params: WidgetGrabbedParams): WidgetAction | null;
+    /**
+     * Starts resizing a widget.
+     * @param params The parameters for the resize action.
+     * @returns The action that was started, or null if the action couldn't be started.
+     */
+    startResizeWidget(params: WidgetStartResizeParams): WidgetAction | null;
+}
+export declare class InternalFlexiTargetController implements FlexiTargetController {
+    #private;
+    widgets: SvelteSet<FlexiWidgetController>;
+    provider: InternalFlexiBoardController;
+    providerWidgetDefaults?: FlexiWidgetDefaults;
+    key: string;
+    config: FlexiTargetConfiguration;
+    constructor(provider: InternalFlexiBoardController, config?: FlexiTargetPartialConfiguration, key?: string);
+    createGrid(): FlexiGrid;
+    createWidget(config: FlexiWidgetConfiguration): FlexiWidgetController | undefined;
+    /**
+     * Deletes the given widget from this target, if it exists.
+     * @returns Whether the widget was deleted.
+     */
+    deleteWidget(widget: FlexiWidgetController): boolean;
+    /**
+     * Imports a layout of widgets into this target, replacing any existing widgets.
+     * @param layout The layout to import.
+     */
+    importLayout(layout: FlexiWidgetConfiguration[]): void;
+    /**
+     * Exports the current layout of widgets from this target.
+     * @returns The layout of widgets.
+     */
+    exportLayout(): FlexiWidgetConfiguration[];
+    onpointerenter(): void;
+    onpointerleave(): void;
+    grabWidget(params: WidgetGrabbedParams): WidgetGrabAction | null;
+    restorePreGrabSnapshot(): void;
+    forgetPreGrabSnapshot(): void;
+    startResizeWidget(params: WidgetStartResizeParams): import("./types.js").WidgetResizeAction | null;
+    tryDropWidget(widget: FlexiWidgetController): boolean;
+    onmousegridcellmove(event: MouseGridCellMoveEvent): void;
+    ongrabbedwidgetover(event: GrabbedWidgetMouseEvent): void;
+    ongrabbedwidgetleave(): void;
+    oninitialloadcomplete(): void;
+    /**
+     * Whether the target is currently being hovered over by the mouse.
+     */
+    get hovered(): boolean;
+    set hovered(value: boolean);
+    /**
+     * When set, this indicates that a widget is currently being hovered over this target.
+     */
+    get actionWidget(): FlexiTargetActionWidget | null;
+    set actionWidget(value: FlexiTargetActionWidget | null);
+    /**
+     * Whether the target is prepared and ready to render widgets.
+     */
+    get prepared(): boolean;
+    /**
+     * The number of columns currently being used in the target grid.
+     * This value is readonly.
+     */
+    get columns(): number | undefined;
+    /**
+     * The number of rows currently being used in the target grid.
+     * This value is readonly.
+     */
+    get rows(): number | undefined;
+    get grid(): FlexiGrid;
+    get dropzoneWidget(): FlexiWidgetController | null;
+    set dropzoneWidget(value: FlexiWidgetController | null);
+}
+type FlexiTargetActionWidget = {
+    action: WidgetAction["action"];
+    widget: FlexiWidgetController;
+};
+/**
+ * Creates a new {@link FlexiTargetController} instance in the context of the current FlexiBoard.
+ * @returns A {@link FlexiTargetController} instance.
+ */
+export declare function flexitarget(config?: FlexiTargetPartialConfiguration, key?: string): {
+    onpointerenter: () => void;
+    onpointerleave: () => void;
+    target: FlexiTargetController;
+};
+/**
+ * Gets the current {@link FlexiTargetController} instance, if any. Throws an error if no target is found.
+ * @returns A {@link FlexiTargetController} instance.
+ */
+export declare function getFlexitargetCtx(): FlexiTargetController;
+export {};