@blokkli/editor 2.0.0-alpha.24 → 2.0.0-alpha.26

package/dist/runtime/helpers/providers/debug.d.ts

@@ -0,0 +1,125 @@
+import type { StorageProvider } from './storage.js';
+import { type ComputedRef } from '#imports';
+export type DebugLogger = {
+    /**
+     * Log a debug message.
+     *
+     * The message is always stored in the message history.
+     * It's only output to console if debug mode is enabled and this logger is active.
+     *
+     * @param message - The log message
+     * @param v - Additional context values to log
+     */
+    log: (message: string, ...v: any) => void;
+    /**
+     * Log an error message.
+     *
+     * The message is always stored in the message history.
+     * It's only output to console if debug mode is enabled and this logger is active.
+     *
+     * @param message - The error message
+     * @param v - Additional context values to log
+     */
+    error: (message: string, ...v: any) => void;
+};
+export type LogMessage = {
+    type: 'log' | 'error' | 'event';
+    name: string;
+    date: string;
+    message: string;
+    context?: string;
+};
+type RegisteredDebugOverlay = {
+    id: string;
+    label: string;
+    active: boolean;
+};
+export type DebugProvider = {
+    /**
+     * Whether debug mode is currently enabled.
+     *
+     * Persisted in storage and controls console output for all loggers.
+     */
+    isEnabled: ComputedRef<boolean>;
+    /**
+     * Toggle debug mode on/off.
+     *
+     * When disabled, debug messages are still collected but not output to console.
+     */
+    toggle: () => void;
+    /**
+     * Create a named debug logger.
+     *
+     * Each logger has a unique name that appears in console output and can be
+     * individually enabled/disabled. The logger is automatically registered.
+     *
+     * @param name - Unique name for this logger (e.g., 'DomProvider', 'Animation')
+     * @returns Logger instance with log and error methods
+     */
+    createLogger: (name: string) => DebugLogger;
+    /**
+     * Register a debug overlay.
+     *
+     * Debug overlays are visual debugging tools that can be toggled on/off.
+     * Examples include viewport visualization, rect debugging, etc.
+     *
+     * @param id - Unique identifier for the overlay
+     * @param label - Human-readable label for the overlay
+     */
+    registerOverlay: (id: string, label: string) => void;
+    /**
+     * Unregister a debug overlay.
+     *
+     * Removes an overlay from the available overlays list.
+     *
+     * @param id - Identifier of the overlay to remove
+     */
+    unregisterOverlay: (id: string) => void;
+    /**
+     * List of all registered debug overlays with their active state.
+     *
+     * Each overlay includes whether it's currently visible.
+     */
+    overlays: ComputedRef<RegisteredDebugOverlay[]>;
+    /**
+     * Toggle a debug overlay on/off.
+     *
+     * Active state is persisted in storage.
+     *
+     * @param id - Identifier of the overlay to toggle
+     */
+    toggleOverlay: (id: string) => void;
+    /**
+     * List of all registered logger names.
+     *
+     * Includes all loggers created via createLogger().
+     */
+    registeredLoggers: ComputedRef<string[]>;
+    /**
+     * List of currently enabled logger names.
+     *
+     * When empty, all loggers are active.
+     * When non-empty, only listed loggers output to console.
+     */
+    enabledLoggers: ComputedRef<string[]>;
+    /**
+     * Toggle a logger's enabled state.
+     *
+     * Adds or removes the logger from the enabled list.
+     * State is persisted in storage.
+     *
+     * @param name - Name of the logger to toggle
+     */
+    toggleLogger: (name: string) => void;
+    /**
+     * Get all collected debug messages.
+     *
+     * Returns messages from all loggers and events, regardless of enabled state.
+     * Useful for debugging issues after they occur.
+     *
+     * @returns Array of all log messages with timestamps
+     */
+    getMessages: () => LogMessage[];
+};
+export default function (storage: StorageProvider): DebugProvider;
+export {};

package/dist/runtime/helpers/{debugProvider.js → providers/debug.js}

@@ -4,8 +4,8 @@ import {
   onMounted,
   ref
 } from "#imports";
-import { eventBus } from "./eventBus.js";
-import { useGlobalBlokkliObject } from "./composables/useGlobalBlokkliObject.js";
+import { eventBus } from "./../eventBus.js";
+import { useGlobalBlokkliObject } from "./../composables/useGlobalBlokkliObject.js";
 export default function(storage) {
   const showDebug = storage.use("showDebug", false);
   const visible = storage.use("visibleDebugOverlays", []);

package/dist/runtime/helpers/providers/definition.d.ts

@@ -0,0 +1,87 @@
+import { type Ref, type ComputedRef } from '#imports';
+import type { BlockDefinition, FragmentDefinition, ProviderDefinition } from '#blokkli-build/definitions';
+import type { ValidFieldListTypes, BlockBundleWithNested } from '#blokkli-build/generated-types';
+import type { DeepReadonly } from 'vue';
+import type { BlockDefinitionOptionsInput } from '../../types/index.js';
+import { type RuntimeBlockOptionArray } from '#blokkli-build/runtime-options';
+export type DefinitionProvider = {
+    /**
+     * Get the block definition for a specific context.
+     *
+     * Checks for context-specific definitions in this order:
+     * 1. Field list type specific (e.g., bundle__field:canvas)
+     * 2. Parent bundle specific (e.g., bundle__parent:accordion)
+     * 3. Default bundle definition
+     *
+     * @param bundle - The block bundle name
+     * @param fieldListType - The field list type context
+     * @param parentBundle - Optional parent block bundle for nested blocks
+     * @returns The block definition, or undefined if not found
+     */
+    getBlockDefinition: (bundle: string, fieldListType: ValidFieldListTypes, parentBundle?: BlockBundleWithNested | null) => BlockDefinition | undefined;
+    /**
+     * Get the default block definition for a bundle.
+     *
+     * Returns the base definition without considering context (field list type or parent).
+     *
+     * @param bundle - The block bundle name
+     * @returns The default block definition, or undefined if not found
+     */
+    getDefaultDefinition: (bundle: string) => BlockDefinition | undefined;
+    /**
+     * Get a fragment definition by name.
+     *
+     * @param name - The fragment name
+     * @returns The fragment definition, or undefined if not found
+     */
+    getFragmentDefinition: (name: string) => FragmentDefinition | undefined;
+    /**
+     * Get a provider definition for an entity type and bundle.
+     *
+     * @param entityType - The entity type (e.g., 'node', 'block_content')
+     * @param entityBundle - The entity bundle (e.g., 'article', 'page')
+     * @returns The provider definition, or undefined if not found
+     */
+    getProviderDefinition: (entityType: string, entityBundle: string) => ProviderDefinition | undefined;
+    /**
+     * Get the icon name for a block bundle.
+     *
+     * @param bundle - The block bundle name
+     * @returns The icon name, or undefined if no icon is defined
+     */
+    getBlockIcon: (bundle: string) => string | undefined;
+    /**
+     * List of all registered fragment definitions.
+     *
+     * Updates automatically via HMR during development.
+     */
+    fragmentDefinitions: ComputedRef<FragmentDefinition[]>;
+    /**
+     * List of all registered block definitions.
+     *
+     * Updates automatically via HMR during development.
+     */
+    blockDefinitions: ComputedRef<BlockDefinition[]>;
+    /**
+     * Global options that apply to all blocks.
+     */
+    globalOptions: DeepReadonly<Ref<BlockDefinitionOptionsInput>>;
+    /**
+     * Runtime option values for all blocks.
+     *
+     * Maps block UUIDs to their option values. Structure:
+     * - First level: block UUID
+     * - Second level: option key → option value array
+     *
+     * Updates automatically via HMR during development.
+     */
+    runtimeOptions: DeepReadonly<Ref<Record<string, Record<string, RuntimeBlockOptionArray>>>>;
+    /**
+     * Render key that changes when definitions are updated.
+     *
+     * Use as a component key to force remounting when definitions change.
+     * Automatically increments via HMR during development.
+     */
+    renderKey: DeepReadonly<Ref<string>>;
+};
+export default function (): DefinitionProvider;

package/dist/runtime/helpers/providers/directive.d.ts

@@ -1,7 +1,7 @@
 import type { BlokkliDirectiveType, EntityContext, Rectangle } from '#blokkli/types';
-import type { UiProvider } from './../uiProvider.js';
+import type { UiProvider } from './ui.js';
 import { type ComputedRef } from '#imports';
-import type { DebugProvider } from '../debugProvider.js';
+import type { DebugProvider } from './debug.js';
 type EditableFieldData = EntityContext & {
     key: string;
     fieldName: string;
@@ -13,16 +13,102 @@ type DroppableFieldElementData = EditableFieldData & {
     element: HTMLElement;
 };
 export type DirectiveProvider = {
+    /**
+     * Initialize the directive provider.
+     *
+     * Starts the IntersectionObserver to track directive element visibility and positions.
+     */
     init: () => void;
+    /**
+     * Register a directive element for tracking.
+     *
+     * Starts observing the element with IntersectionObserver to track visibility and position.
+     * For 'editable' directives on blocks, also indexes by UUID for quick lookup.
+     *
+     * @param el - The HTML element with the directive
+     * @param fieldName - The field name
+     * @param entity - The entity context (type, bundle, UUID)
+     * @param type - The directive type ('editable' or 'droppable')
+     * @param isComponent - Whether this is a component-based field
+     * @param getValue - Optional function to get the current field value
+     */
     registerDirectiveElement: (el: HTMLElement, fieldName: string, entity: EntityContext, type: BlokkliDirectiveType, isComponent: boolean, getValue?: () => string) => void;
+    /**
+     * Unregister a directive element from tracking.
+     *
+     * Stops observing the element and removes it from all tracking maps.
+     *
+     * @param el - The HTML element to unregister
+     * @param fieldName - The field name
+     * @param entity - The entity context
+     * @param type - The directive type
+     */
     unregisterDirectiveElement: (el: HTMLElement, fieldName: string, entity: EntityContext, type: BlokkliDirectiveType) => void;
+    /**
+     * Get rectangles for all visible directives of a specific type.
+     *
+     * Only includes directives currently in the viewport.
+     *
+     * @param directiveType - The directive type to filter by
+     * @returns Array of rectangles for visible directives
+     */
     getVisible: (directiveType: BlokkliDirectiveType) => Rectangle[];
+    /**
+     * Find the editable field at a specific screen coordinate.
+     *
+     * Converts screen coordinates to artboard space and checks if any visible
+     * editable field contains the point.
+     *
+     * @param x - Screen X coordinate
+     * @param y - Screen Y coordinate
+     * @returns The editable field data at that point, or undefined
+     */
     getEditableAtPoint: (x: number, y: number) => EditableFieldData | undefined;
+    /**
+     * Get all editable fields for a specific block.
+     *
+     * Only returns 'editable' type directives on block entities.
+     *
+     * @param uuid - The block UUID
+     * @returns Array of editable fields for the block
+     */
     getEditablesForBlock: (uuid: string) => EditableFieldData[];
+    /**
+     * Get all droppable field elements.
+     *
+     * Returns fields with the 'droppable' directive type along with their HTML elements.
+     *
+     * @returns Array of droppable field data with elements
+     */
     getDroppableElements: () => DroppableFieldElementData[];
+    /**
+     * Find the HTML element for an editable field.
+     *
+     * @param fieldName - The field name
+     * @param host - The host entity context
+     * @returns The field's HTML element, or undefined if not found
+     */
     findEditableElement: (fieldName: string, host: EntityContext) => HTMLElement | undefined;
+    /**
+     * Find the editable field data.
+     *
+     * @param fieldName - The field name
+     * @param host - The host entity context
+     * @returns The editable field data, or undefined if not found
+     */
     findEditable: (fieldName: string, host: EntityContext) => EditableFieldData | undefined;
+    /**
+     * Whether the directive provider is ready.
+     *
+     * Ready when IntersectionObserver is initialized and initial measurements are complete.
+     */
     isReady: ComputedRef<boolean>;
+    /**
+     * Settlement key that increments after directive changes settle.
+     *
+     * Useful for triggering reactivity after directives are registered/unregistered.
+     */
+    settleKey: ComputedRef<number>;
 };
 export default function (debug: DebugProvider, ui: UiProvider): DirectiveProvider;
 export {};

package/dist/runtime/helpers/providers/directive.js

@@ -1,6 +1,11 @@
 import { falsy } from "#blokkli/helpers";
 import useDelayedIntersectionObserver from "./../composables/useDelayedIntersectionObserver.js";
-import { computed, onBeforeUnmount, ref } from "#imports";
+import {
+  computed,
+  onBeforeUnmount,
+  onMounted,
+  ref
+} from "#imports";
 import onBlokkliEvent from "./../composables/onBlokkliEvent.js";
 import { itemEntityType } from "#blokkli-build/config";
 export default function(debug, ui) {
@@ -14,6 +19,8 @@ export default function(debug, ui) {
   const rects = {};
   const visible = /* @__PURE__ */ new Set();
   const editablesByUuid = {};
+  let settleTimeout = null;
+  const settleKey = ref(0);
   function doInitTimeout() {
     if (initTimeout) {
       window.clearTimeout(initTimeout);
@@ -24,6 +31,14 @@ export default function(debug, ui) {
       }, 500);
     }
   }
+  function doSettleTimeout() {
+    if (settleTimeout) {
+      window.clearTimeout(settleTimeout);
+    }
+    settleTimeout = window.setTimeout(() => {
+      settleKey.value++;
+    }, 50);
+  }
   function getVisible(directiveType) {
     return [...visible.keys()].map((key) => {
       if (key.startsWith(directiveType)) {
@@ -91,6 +106,7 @@ export default function(debug, ui) {
     }
     logger.log("Registered directive element", data);
     doInitTimeout();
+    doSettleTimeout();
   }
   function unregisterDirectiveElement(el, fieldName, entity, directiveType) {
     const key = getEditableKey(fieldName, entity, directiveType);
@@ -106,6 +122,7 @@ export default function(debug, ui) {
         editablesByUuid[entity.uuid][fieldName] = void 0;
       }
     }
+    doSettleTimeout();
   }
   function init() {
     intersectionObserver.init();
@@ -192,9 +209,15 @@ export default function(debug, ui) {
     const key = getEditableKey(fieldName, host, "editable");
     return fieldData.get(key);
   }
-  onBlokkliEvent("state:reloaded", handleRefresh);
+  onBlokkliEvent("state:reloaded", () => {
+    handleRefresh();
+    doSettleTimeout();
+  });
   onBlokkliEvent("ui:resized", handleRefresh);
   onBlokkliEvent("option:finish-change", handleRefresh);
+  onMounted(() => {
+    doInitTimeout();
+  });
   onBeforeUnmount(() => {
     if (stateReloadTimeout) {
       window.clearTimeout(stateReloadTimeout);
@@ -210,6 +233,7 @@ export default function(debug, ui) {
     getEditablesForBlock,
     findEditableElement,
     getDroppableElements,
-    isReady: computed(() => !isInitalizing.value)
+    isReady: computed(() => !isInitalizing.value),
+    settleKey: computed(() => settleKey.value)
   };
 }

package/dist/runtime/helpers/providers/dom.d.ts

@@ -0,0 +1,225 @@
+import { type ComputedRef } from '#imports';
+import type { DraggableExistingBlock, DraggableItem, EntityContext, Rectangle, RenderedFieldListItem, RegisteredField, RegisterFieldData } from '#blokkli/types';
+import type { UiProvider } from './ui.js';
+import type { DebugProvider } from './debug.js';
+import type { StateProvider } from './state.js';
+import type { ElementProvider } from './element.js';
+type RegisteredFieldType = {
+    entityType: string;
+    entityBundle: string;
+    fieldName: string;
+};
+type MeasuredBlockRect = Rectangle & {
+    time: number;
+};
+export type DomProvider = {
+    /**
+     * Get the bounding client rect for an element.
+     *
+     * Wrapper around `getBoundingClientRect()` with debug logging.
+     */
+    getBoundingClientRect: (element: HTMLElement) => DOMRect;
+    /**
+     * Return the droppable markup for a draggable item.
+     */
+    getDropElementMarkup(item: DraggableItem | RenderedFieldListItem, checkSize?: boolean): string;
+    /**
+     * Register a block element for observation and tracking.
+     *
+     * Starts observing the element with IntersectionObserver and ResizeObserver
+     * to track visibility and dimensions.
+     *
+     * @param key - Unique key identifying the block's location (field + index)
+     * @param uuid - The block's UUID
+     * @param el - The block's root HTML element
+     */
+    registerBlock: (key: string, uuid: string, el: HTMLElement | null) => void;
+    /**
+     * Unregister a block element from observation.
+     *
+     * Stops observing the element and removes it from tracking.
+     *
+     * @param key - Unique key identifying the block's location
+     * @param uuid - The block's UUID
+     */
+    unregisterBlock: (key: string, uuid: string) => void;
+    /**
+     * Register a field element for observation.
+     *
+     * Starts observing the field element with IntersectionObserver to track
+     * visibility and position.
+     *
+     * @param entity - The entity context (UUID, type, bundle)
+     * @param fieldName - The field's machine name
+     * @param instance - The field's HTML element
+     * @param data - Additional field registration data
+     */
+    registerField: (entity: EntityContext, fieldName: string, instance: HTMLElement, data: RegisterFieldData) => void;
+    /**
+     * Update the element reference for an already registered field.
+     *
+     * Stops observing the old element and starts observing the new one.
+     *
+     * @param entity - The entity context
+     * @param fieldName - The field's machine name
+     * @param element - The new field HTML element
+     * @param data - Additional field registration data
+     */
+    updateFieldElement: (entity: EntityContext, fieldName: string, element: HTMLElement, data: RegisterFieldData) => void;
+    /**
+     * Unregister a field element from observation.
+     *
+     * @param entity - The entity context
+     * @param fieldName - The field's machine name
+     */
+    unregisterField: (entity: EntityContext, fieldName: string) => void;
+    /**
+     * Get a registered field by entity UUID and field name.
+     *
+     * @param uuid - The entity UUID
+     * @param fieldName - The field's machine name
+     * @returns The registered field data, or undefined if not found
+     */
+    getRegisteredField: (uuid: string, fieldName: string) => RegisteredField | undefined;
+    /**
+     * List of unique field types currently registered.
+     *
+     * Returns unique combinations of entity type, bundle, and field name.
+     */
+    registeredFieldTypes: ComputedRef<RegisteredFieldType[]>;
+    /**
+     * List of UUIDs for all blocks with registered elements.
+     *
+     * Only includes blocks that have a valid HTML element reference.
+     */
+    registeredBlockUuids: ComputedRef<string[]>;
+    /**
+     * Get UUIDs of all currently visible blocks.
+     *
+     * @returns Array of block UUIDs that are currently in the viewport
+     */
+    getVisibleBlocks(): string[];
+    /**
+     * Get keys of all currently visible fields.
+     *
+     * @returns Array of field keys (uuid:fieldName) that are currently in the viewport
+     */
+    getVisibleFields(): string[];
+    /**
+     * Check if a block is currently visible in the viewport.
+     *
+     * @param uuid - The block's UUID
+     * @returns True if the block is visible
+     */
+    isBlockVisible(uuid: string): boolean;
+    /**
+     * Get rectangles for all registered blocks.
+     *
+     * @returns Record mapping UUIDs to their measured rectangles with timestamps
+     */
+    getBlockRects: () => Record<string, MeasuredBlockRect>;
+    /**
+     * Get the rectangle for a specific block.
+     *
+     * @param uuid - The block's UUID
+     * @param refresh - Whether to refresh the rect before returning
+     * @returns The block's rectangle, or undefined if not found
+     */
+    getBlockRect: (uuid: string, refresh?: boolean) => MeasuredBlockRect | undefined;
+    /**
+     * Refresh the cached rectangle for a specific block.
+     *
+     * Recalculates the block's position and dimensions immediately.
+     *
+     * @param uuid - The block's UUID
+     */
+    refreshBlockRect: (uuid: string) => void;
+    /**
+     * Get the rectangle for a specific field.
+     *
+     * @param key - The field key (uuid:fieldName)
+     * @returns The field's rectangle, or undefined if not found
+     */
+    getFieldRect: (key: string) => Rectangle | undefined;
+    /**
+     * Record of all registered block elements.
+     *
+     * Maps UUIDs to their corresponding HTML elements.
+     */
+    registeredBlocks: ComputedRef<Record<string, HTMLElement | undefined>>;
+    /**
+     * Update rectangles for all visible blocks and fields.
+     *
+     * Recalculates positions and dimensions for currently visible items.
+     * For performance, only updates visible items when there are many blocks.
+     */
+    updateVisibleRects: () => void;
+    /**
+     * Whether the DOM provider is ready.
+     *
+     * Ready when IntersectionObserver is initialized and initial measurements are complete.
+     */
+    isReady: ComputedRef<boolean>;
+    /**
+     * Settlement key that increments after DOM changes settle.
+     *
+     * Useful for triggering reactivity after blocks/fields are registered/unregistered.
+     */
+    settleKey: ComputedRef<number>;
+    /**
+     * Initialize the DOM provider.
+     *
+     * Starts the IntersectionObserver and marks the provider as ready.
+     */
+    init: () => void;
+    /**
+     * Get the drag element for a block.
+     */
+    getDragElement: (block: DraggableExistingBlock | RenderedFieldListItem) => HTMLElement | undefined;
+    /**
+     * Get debug data for troubleshooting.
+     */
+    getDebugData: () => {
+        registeredBlocks: Array<{
+            uuid: string;
+            hasElement: boolean;
+            hasObservedElement: boolean;
+            hasRect: boolean;
+            hasCurrentKey: boolean;
+            isVisible: boolean;
+            elementInfo?: {
+                tagName: string;
+                bundle?: string;
+                hostBundle?: string;
+                fieldListType?: string;
+            };
+        }>;
+        fields: Array<{
+            key: string;
+            isVisible: boolean;
+            hasRect: boolean;
+            entityType: string;
+            entityBundle: string;
+            fieldName: string;
+        }>;
+        summary: {
+            totalRegisteredBlocks: number;
+            totalBlocksWithElements: number;
+            totalObservedElements: number;
+            totalBlockRects: number;
+            totalVisibleBlocks: number;
+            totalRegisteredFields: number;
+            totalVisibleFields: number;
+            totalFieldRects: number;
+            isInitializing: boolean;
+            isReady: boolean;
+        };
+        orphanedData: {
+            rectsWithoutRegistration: string[];
+            observedElementsWithoutRegistration: string[];
+            keysWithoutRegistration: string[];
+        };
+    };
+};
+export default function (ui: UiProvider, debug: DebugProvider, state: StateProvider, element: ElementProvider): DomProvider;
+export {};