svelte-flexiboards 0.3.2 → 0.4.1

package/dist/system/target/controller.svelte.js

@@ -1,11 +1,11 @@
 import { tick, untrack } from 'svelte';
-import { FreeFormFlexiGrid } from '../grid/free-grid.svelte.js';
 import { FlexiGrid, FlowFlexiGrid } from '../grid/index.js';
 import { FlexiWidgetController } from '../widget/base.svelte.js';
 import { InternalFlexiWidgetController } from '../widget/controller.svelte.js';
 import { getFlexiEventBus } from '../shared/event-bus.js';
 import { SvelteSet } from 'svelte/reactivity';
 import { getPointerService } from '../shared/utils.svelte.js';
+import { FreeFormFlexiGrid } from '../grid/free-grid.svelte.js';
 export class InternalFlexiTargetController {
     #widgets = $state(new SvelteSet());
     #orderedWidgets = $state([]);
@@ -32,10 +32,16 @@ export class InternalFlexiTargetController {
         x: 0,
         y: 0
     });
+    // Raw (fractional) cell position - used for resize snapping (rounds instead of floors)
+    #rawMouseCellPosition = $state({
+        x: 0,
+        y: 0
+    });
     key;
     #grid = null;
     #preGrabSnapshot = null;
     #gridSnapshot = null;
+    registry = $derived(this.provider?.registry);
     #targetConfig = $state(undefined);
     #pointerService = getPointerService();
     config = $derived({
@@ -122,10 +128,20 @@ export class InternalFlexiTargetController {
     }
     createWidget(config) {
         const [x, y, width, height] = [config.x, config.y, config.width, config.height];
+        let widgetConfig = {};
+        if (config.type) {
+            if (!this.registry?.[config.type]) {
+                console.warn('createWidget(): widget with type ', config.type, ' not found in registry, it will be missing settings.');
+            }
+            else {
+                widgetConfig = { ...this.registry[config.type] };
+            }
+        }
         const widget = new InternalFlexiWidgetController({
-            config,
+            config: { ...widgetConfig, ...config },
             provider: this.provider,
-            target: this
+            target: this,
+            type: config.type
         });
         // If the widget can't be added, it's probably a collision.
         if (!this.#tryAddWidget(widget, x, y, width, height)) {
@@ -160,19 +176,46 @@ export class InternalFlexiTargetController {
         if (deleted && 'destroy' in widget) {
             widget.destroy();
         }
+        // Clear the pre-grab snapshot only if the deleted widget is the one being grabbed/resized
+        // (prevents the board's safety net from restoring a widget that was intentionally removed)
+        // Note: We don't clear if a different widget is deleted during a grab operation
+        if (this.actionWidget?.widget === widget) {
+            this.forgetPreGrabSnapshot();
+        }
         // Apply any deferred operations like row collapsing now that the operation is complete
         this.applyGridPostCompletionOperations();
         return deleted;
     }
     /**
      * Imports a layout of widgets into this target, replacing any existing widgets.
+     * Widgets with types not found in the registry will be skipped with a warning.
      * @param layout The layout to import.
      */
     importLayout(layout) {
+        if (!this.registry) {
+            console.warn('importLayout(): no registry provided, cannot import layout. Provide a registry to the FlexiBoard component.');
+            return;
+        }
         this.widgets.clear();
         this.grid.clear();
-        for (const config of layout) {
-            this.createWidget(config);
+        for (const entry of layout) {
+            if (!entry.type) {
+                console.warn('importLayout(): skipping widget entry with no type:', entry);
+                continue;
+            }
+            if (!this.registry[entry.type]) {
+                console.warn(`importLayout(): widget type "${entry.type}" not found in registry, skipping widget.`);
+                continue;
+            }
+            this.createWidget({
+                id: entry.id,
+                type: entry.type,
+                x: entry.x,
+                y: entry.y,
+                width: entry.width,
+                height: entry.height,
+                metadata: entry.metadata
+            });
         }
     }
     /**
@@ -180,41 +223,51 @@ export class InternalFlexiTargetController {
      * @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;
+        // Prevent reactive subscriptions onto exportLayout directly - they should use onLayoutChange.
+        return untrack(() => {
+            const result = [];
+            // Likely much more information than needed, but we've got it.
+            for (const widget of this.internalWidgets) {
+                if (!widget.type) {
+                    console.warn('exportLayout(): widget has no type, it will be skipped.');
+                    continue;
+                }
+                const entry = {
+                    type: widget.type,
+                    width: widget.width,
+                    height: widget.height,
+                    x: widget.x,
+                    y: widget.y,
+                    metadata: widget.metadata
+                };
+                // Only include id if user provided one
+                if (widget.userProvidedId) {
+                    entry.id = widget.userProvidedId;
+                }
+                result.push(entry);
+            }
+            return result;
+        });
     }
-    #createShadow(of) {
+    #createShadow(of, action) {
         const shadow = new InternalFlexiWidgetController({
             config: {
                 width: of.width,
                 height: of.height,
                 component: of.component,
                 draggable: of.draggable,
+                draggability: of.draggability,
                 resizability: of.resizability,
                 snippet: of.snippet,
                 className: of.className,
-                componentProps: of.componentProps
+                componentProps: of.componentProps,
+                metadata: of.metadata
             },
             provider: this.provider,
             target: this,
             isShadow: true
         });
+        shadow.interpolationAnimationHint = action === 'resize' ? 'resize' : 'move';
         return shadow;
     }
     // Events
@@ -240,6 +293,9 @@ export class InternalFlexiTargetController {
     forgetPreGrabSnapshot() {
         this.#preGrabSnapshot = null;
     }
+    hasPreGrabSnapshot() {
+        return this.#preGrabSnapshot !== null;
+    }
     applyGridPostCompletionOperations() {
         this.grid.applyPostCompletionOperations();
     }
@@ -259,6 +315,9 @@ export class InternalFlexiTargetController {
         // Try to formally place the widget in the grid, which will also serve as a final check that
         // the drop is possible.
         const result = this.#tryAddWidget(widget, x, y, width, height);
+        if (!result) {
+            widget.isBeingDropped = false;
+        }
         // Apply any deferred operations like row collapsing now that the operation is complete
         if (result) {
             this.applyGridPostCompletionOperations();
@@ -269,6 +328,8 @@ export class InternalFlexiTargetController {
     }
     onmousegridcellmove(event) {
         this.#updateMouseCellPosition(event.cellX, event.cellY);
+        this.#rawMouseCellPosition.x = event.rawCellX;
+        this.#rawMouseCellPosition.y = event.rawCellY;
         this.#updateDropzoneWidget();
     }
     onWidgetGrabbed(event) {
@@ -394,9 +455,10 @@ export class InternalFlexiTargetController {
         const grid = this.grid;
         // Take a snapshot of the grid so we can restore its state if the hover stops.
         this.#gridSnapshot = grid.takeSnapshot();
+        grid.setDragSnapshot(this.#gridSnapshot);
         // TODO: Not sure why the $effect.root is needed, but it is.
         this.#dropzoneWidgetDestroy = $effect.root(() => {
-            this.dropzoneWidget = this.#createShadow(this.actionWidget.widget);
+            this.dropzoneWidget = this.#createShadow(this.actionWidget.widget, this.actionWidget.action);
         });
         let [x, y, width, height] = this.#getDropzoneLocation(this.actionWidget);
         const added = this.grid.tryPlaceWidget(this.dropzoneWidget, x, y, width, height, true);
@@ -455,8 +517,12 @@ export class InternalFlexiTargetController {
     }
     #getNewWidgetHeightAndWidth(widget, mouseCellPosition) {
         const grid = this.grid;
-        let newWidth = Math.max(1, mouseCellPosition.x - widget.x);
-        let newHeight = Math.max(1, mouseCellPosition.y - widget.y);
+        // Use raw (fractional) position with rounding for smoother resize snapping
+        // This makes the widget snap to the next cell when more than halfway through
+        const roundedX = Math.round(this.#rawMouseCellPosition.x);
+        const roundedY = Math.round(this.#rawMouseCellPosition.y);
+        let newWidth = Math.max(1, Math.min(widget.maxWidth, Math.max(roundedX - widget.x, widget.minWidth)));
+        let newHeight = Math.max(1, Math.min(widget.maxHeight, Math.max(roundedY - widget.y, widget.minHeight)));
         // 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') {
@@ -479,17 +545,21 @@ export class InternalFlexiTargetController {
         if (!this.dropzoneWidget) {
             return;
         }
+        const dropzoneWidget = this.dropzoneWidget;
         const grid = this.grid;
-        grid.removeWidget(this.dropzoneWidget);
+        grid.removeWidget(dropzoneWidget);
         if (this.#isDropzoneWidgetAdded) {
-            this.widgets.delete(this.dropzoneWidget);
+            this.widgets.delete(dropzoneWidget);
             this.#isDropzoneWidgetAdded = false;
         }
         grid.restoreFromSnapshot(this.#gridSnapshot);
+        grid.clearDragSnapshot();
         this.#gridSnapshot = null;
         this.dropzoneWidget = null;
         this.#dropzoneWidgetDestroy?.();
         this.#dropzoneWidgetDestroy = null;
+        // Clean up the shadow widget's event subscriptions and reset counters
+        dropzoneWidget.destroy();
     }
     // State-related getters and setters
     /**
@@ -543,6 +613,9 @@ export class InternalFlexiTargetController {
     set dropzoneWidget(value) {
         this.#dropzoneWidget.value = value;
     }
+    get shouldRenderDropzoneWidget() {
+        return this.#isDropzoneWidgetAdded && !!this.dropzoneWidget;
+    }
     get widgets() {
         return this.#widgets;
     }

package/dist/system/types.d.ts

@@ -1,9 +1,10 @@
 import type { InternalFlexiTargetController } from './target/controller.svelte.js';
 import type { FlexiAddController, InternalFlexiAddController } from './misc/adder.svelte.js';
 import type { FlexiWidgetController } from './widget/base.svelte.js';
-import type { FlexiWidgetConfiguration } from './widget/types.js';
 import type { InternalFlexiBoardController } from './board/controller.svelte.js';
 import type { InternalFlexiWidgetController } from './widget/controller.svelte.js';
+import type { FlexiLayout } from './board/types.js';
+import type { InternalResponsiveFlexiBoardController } from './responsive/controller.svelte.js';
 export type ProxiedValue<T> = {
     value: T;
 };
@@ -16,6 +17,7 @@ export type FlexiCommonProps<T> = {
     onfirstcreate?: (instance: T) => void;
 };
 export type WidgetResizability = 'none' | 'horizontal' | 'vertical' | 'both';
+export type WidgetDraggability = 'none' | 'movable' | 'full';
 export type WidgetGrabAction = {
     action: 'grab';
     widget: InternalFlexiWidgetController;
@@ -112,6 +114,8 @@ export type TargetEvent = {
 export type MouseGridCellMoveEvent = {
     cellX: number;
     cellY: number;
+    rawCellX: number;
+    rawCellY: number;
 };
 export type GrabbedWidgetMouseEvent = {
     widget: FlexiWidgetController;
@@ -119,7 +123,6 @@ export type GrabbedWidgetMouseEvent = {
 export type HoveredTargetEvent = {
     target: InternalFlexiTargetController;
 };
-export type FlexiSavedLayout = Record<string, FlexiWidgetConfiguration[]>;
 export type WidgetActionEvent = (PointerEvent & {
     isKeyboard?: undefined;
 }) | (KeyboardEvent & {
@@ -127,3 +130,11 @@ export type WidgetActionEvent = (PointerEvent & {
     clientX: number;
     clientY: number;
 });
+export type BoardLayoutChangeEvent = {
+    board: InternalFlexiBoardController;
+    layout: FlexiLayout;
+    breakpoint?: string;
+};
+export type ResponsiveLayoutImportEvent = {
+    responsiveController: InternalResponsiveFlexiBoardController;
+};

package/dist/system/widget/base.svelte.d.ts

@@ -1,6 +1,6 @@
 import type { Component } from 'svelte';
 import type { FlexiTargetController } from '../target/index.js';
-import type { WidgetAction, WidgetResizability } from '../types.js';
+import type { WidgetAction, WidgetDraggability, WidgetResizability } from '../types.js';
 import { type FlexiWidgetChildrenSnippet, type FlexiWidgetClasses, type FlexiWidgetConstructorParams } from './types.js';
 export declare class FlexiWidgetController {
     #private;
@@ -43,9 +43,23 @@ export declare class FlexiWidgetController {
     set currentAction(value: WidgetAction | null);
     /**
      * Whether the widget is draggable.
+     * @deprecated Prefer the use of `draggability` instead for finer control. When `true`, `draggability = 'full'`, when `false`, `draggability = 'none'`.
      */
     get draggable(): boolean;
     set draggable(value: boolean);
+    /**
+     * The draggability of the widget.
+     */
+    get draggability(): WidgetDraggability;
+    set draggability(value: WidgetDraggability);
+    /**
+     * Whether the widget can be grabbed.
+     */
+    get isGrabbable(): boolean;
+    /**
+     * Whether the widget can be moved.
+     */
+    get isMovable(): boolean;
     /**
      * The resizability of the widget.
      */
@@ -122,6 +136,31 @@ export declare class FlexiWidgetController {
      */
     get isBeingDropped(): boolean;
     set isBeingDropped(value: boolean);
+    /**
+     * The minimum width of the widget in units.
+     */
+    get minWidth(): number;
+    /**
+     * The minimum height of the widget in units.
+     */
+    get minHeight(): number;
+    /**
+     * The maximum width of the widget in units.
+     */
+    get maxWidth(): number;
+    /**
+     * The maximum height of the widget in units.
+     */
+    get maxHeight(): number;
+    /**
+     * The user-provided stable identifier for this widget, if any.
+     * This is used for persistence and layout import/export.
+     */
+    get userProvidedId(): string | undefined;
+    /**
+     * The type of this widget (registry key for looking up configuration).
+     */
+    get type(): string | undefined;
 }
 export type WidgetStateData = {
     currentAction: WidgetAction | null;

package/dist/system/widget/base.svelte.js

@@ -1,6 +1,5 @@
 import { FlexiControllerBase } from '../base.svelte.js';
 import { defaultTriggerConfig } from './types.js';
-import { WidgetMoveInterpolator } from './interpolator.svelte.js';
 export class FlexiWidgetController {
     /**
      * The target this widget is under. This is not defined if the widget has not yet been dropped in the board.
@@ -47,6 +46,14 @@ export class FlexiWidgetController {
             this.#targetWidgetDefaults?.draggable ??
             this.#providerWidgetDefaults?.draggable ??
             true,
+        draggability: this.#rawConfig.draggability ??
+            this.#targetWidgetDefaults?.draggability ??
+            this.#providerWidgetDefaults?.draggability ??
+            // This is not pretty but will ensure backwards compatibility with the old `draggable` property.
+            (this.#rawConfig.draggable !== undefined ? (this.#rawConfig.draggable ? 'full' : 'none') : undefined) ??
+            (this.#targetWidgetDefaults?.draggable !== undefined ? (this.#targetWidgetDefaults?.draggable ? 'full' : 'none') : undefined) ??
+            (this.#providerWidgetDefaults?.draggable !== undefined ? (this.#providerWidgetDefaults?.draggable ? 'full' : 'none') : undefined) ??
+            'full',
         className: this.#rawConfig.className ??
             this.#targetWidgetDefaults?.className ??
             this.#providerWidgetDefaults?.className,
@@ -62,7 +69,23 @@ export class FlexiWidgetController {
         resizeTrigger: this.#rawConfig.resizeTrigger ??
             this.#targetWidgetDefaults?.resizeTrigger ??
             this.#providerWidgetDefaults?.resizeTrigger ??
-            defaultTriggerConfig
+            defaultTriggerConfig,
+        minWidth: this.#rawConfig.minWidth ??
+            this.#targetWidgetDefaults?.minWidth ??
+            this.#providerWidgetDefaults?.minWidth ??
+            1,
+        minHeight: this.#rawConfig.minHeight ??
+            this.#targetWidgetDefaults?.minHeight ??
+            this.#providerWidgetDefaults?.minHeight ??
+            1,
+        maxWidth: this.#rawConfig.maxWidth ??
+            this.#targetWidgetDefaults?.maxWidth ??
+            this.#providerWidgetDefaults?.maxWidth ??
+            Infinity,
+        maxHeight: this.#rawConfig.maxHeight ??
+            this.#targetWidgetDefaults?.maxHeight ??
+            this.#providerWidgetDefaults?.maxHeight ??
+            Infinity,
     });
     // Reactive state properties - single source of truth
     backingState = $state();
@@ -97,6 +120,7 @@ export class FlexiWidgetController {
     }
     /**
      * Whether the widget is draggable.
+     * @deprecated Prefer the use of `draggability` instead for finer control. When `true`, `draggability = 'full'`, when `false`, `draggability = 'none'`.
      */
     get draggable() {
         return this.#config.draggable;
@@ -104,6 +128,27 @@ export class FlexiWidgetController {
     set draggable(value) {
         this.#rawConfig.draggable = value;
     }
+    /**
+     * The draggability of the widget.
+     */
+    get draggability() {
+        return this.#config.draggability;
+    }
+    set draggability(value) {
+        this.#rawConfig.draggability = value;
+    }
+    /**
+     * Whether the widget can be grabbed.
+     */
+    get isGrabbable() {
+        return this.#config.draggability == 'full';
+    }
+    /**
+     * Whether the widget can be moved.
+     */
+    get isMovable() {
+        return this.#config.draggability == 'movable' || this.#config.draggability == 'full';
+    }
     /**
      * The resizability of the widget.
      */
@@ -228,4 +273,41 @@ export class FlexiWidgetController {
     set isBeingDropped(value) {
         this.backingState.isBeingDropped = value;
     }
+    /**
+     * The minimum width of the widget in units.
+     */
+    get minWidth() {
+        return this.#config.minWidth;
+    }
+    /**
+     * The minimum height of the widget in units.
+     */
+    get minHeight() {
+        return this.#config.minHeight;
+    }
+    /**
+     * The maximum width of the widget in units.
+     */
+    get maxWidth() {
+        return this.#config.maxWidth;
+    }
+    /**
+     * The maximum height of the widget in units.
+     */
+    get maxHeight() {
+        return this.#config.maxHeight;
+    }
+    /**
+     * The user-provided stable identifier for this widget, if any.
+     * This is used for persistence and layout import/export.
+     */
+    get userProvidedId() {
+        return undefined; // Overridden in InternalFlexiWidgetController
+    }
+    /**
+     * The type of this widget (registry key for looking up configuration).
+     */
+    get type() {
+        return undefined; // Overridden in InternalFlexiWidgetController
+    }
 }

package/dist/system/widget/controller.svelte.d.ts

@@ -1,7 +1,7 @@
 import type { WidgetDroppedEvent, WidgetEvent, WidgetGrabbedEvent, WidgetResizingEvent } from '../types.js';
 import { FlexiWidgetController } from './base.svelte.js';
 import type { InternalFlexiTargetController } from '../target/controller.svelte.js';
-import { WidgetMoveInterpolator } from './interpolator.svelte.js';
+import { WidgetMoveInterpolator, type WidgetMovementAnimation } from './interpolator.svelte.js';
 import type { FlexiWidgetConstructorParams } from './types.js';
 import type { InternalFlexiBoardController } from '../board/controller.svelte.js';
 export declare class InternalFlexiWidgetController extends FlexiWidgetController {
@@ -10,6 +10,8 @@ export declare class InternalFlexiWidgetController extends FlexiWidgetController
     internalTarget?: InternalFlexiTargetController;
     provider: InternalFlexiBoardController;
     mounted: boolean;
+    get type(): string | undefined;
+    get userProvidedId(): string | undefined;
     /**
      * The styling to apply to the widget.
      */
@@ -57,4 +59,5 @@ export declare class InternalFlexiWidgetController extends FlexiWidgetController
      * Whether the widget should draw a placeholder widget in the DOM.
      */
     get shouldDrawPlaceholder(): boolean;
+    set interpolationAnimationHint(value: WidgetMovementAnimation | null);
 }