@blokkli/editor 2.0.0-alpha.23 → 2.0.0-alpha.25

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 {};

package/dist/runtime/helpers/{domProvider.js → providers/dom.js}

@@ -1,16 +1,15 @@
 import { reactive, ref, computed } from "#imports";
 import { falsy } from "#blokkli/helpers";
-import { cloneElementWithStyles } from "./dom/index.js";
-import onBlokkliEvent from "./composables/onBlokkliEvent.js";
-import useDelayedIntersectionObserver from "./composables/useDelayedIntersectionObserver.js";
-import { itemEntityType } from "#blokkli-build/config";
+import { cloneElementWithStyles } from "../dom/index.js";
+import onBlokkliEvent from "../composables/onBlokkliEvent.js";
+import useDelayedIntersectionObserver from "../composables/useDelayedIntersectionObserver.js";
 function rectWithTime(rect, time) {
   return {
     ...rect,
     time: time || performance.now()
   };
 }
-export default function(ui, debug, definitions, state, element) {
+export default function(ui, debug, state, element) {
   const logger = debug.createLogger("DomProvider");
   const mutationsReady = ref(true);
   const intersectionReady = ref(false);
@@ -23,10 +22,15 @@ export default function(ui, debug, definitions, state, element) {
   const blockRects = {};
   const fieldRects = {};
   const blockUuidCurrentKey = {};
-  const observedElements = {};
   let initTimeout = null;
   const isInitalizing = ref(true);
-  const observedElementCache = /* @__PURE__ */ new Map();
+  let settleTimeout = null;
+  const settleKey = ref(0);
+  const observedElements = {};
+  function getBoundingClientRect(element2) {
+    logger.log("getBoundingClientRect", element2);
+    return element2.getBoundingClientRect();
+  }
   const registeredBlockUuids = computed(() => {
     return Object.entries(registeredBlocks).map(([uuid, element2]) => {
       if (element2) {
@@ -150,6 +154,7 @@ export default function(ui, debug, definitions, state, element) {
     intersectionObserver.observe(element2);
     fieldElementToFieldKey.set(element2, key);
     doInitTimeout();
+    doSettleTimeout();
   };
   const updateFieldElement = (entity, fieldName, element2, data) => {
     const key = `${entity.uuid}:${fieldName}`;
@@ -175,36 +180,12 @@ export default function(ui, debug, definitions, state, element) {
     }
     visibleFields.delete(key);
     registeredFields[key] = void 0;
+    doSettleTimeout();
   };
   const getRegisteredField = (uuid, fieldName) => {
     const key = `${uuid}:${fieldName}`;
     return registeredFields[key];
   };
-  function getElementToObserve(uuid, el, bundle, fieldListType, parentBlockBundle) {
-    if (el.classList.contains("bk-block-proxy")) {
-      return el;
-    }
-    const key = `${uuid}${bundle}${fieldListType}${parentBlockBundle ?? "none"}`;
-    const cached = observedElementCache.get(key);
-    if (cached) {
-      return cached;
-    }
-    const definition = definitions.getBlockDefinition(
-      bundle,
-      fieldListType,
-      parentBlockBundle
-    );
-    if (!definition) {
-      throw new Error("Failed to load definition for bundle: " + bundle);
-    }
-    const observableElement = (definition.editor?.getDraggableElement ? definition.editor.getDraggableElement(el) : el) || el;
-    if (observableElement instanceof HTMLElement) {
-      observedElementCache.set(key, observableElement);
-      return observableElement;
-    }
-    observedElementCache.set(key, el);
-    return el;
-  }
   const getDropElementMarkup = (item, checkSize) => {
     const getElement = () => {
       if ("itemType" in item) {
@@ -219,7 +200,7 @@ export default function(ui, debug, definitions, state, element) {
     if (!el) {
       return "";
     }
-    if ("itemType" in item && item.itemType !== "new") {
+    if ("itemType" in item && item.itemType !== "existing_structure") {
       return el.outerHTML;
     }
     const childCount = element.queryAll(
@@ -261,21 +242,8 @@ export default function(ui, debug, definitions, state, element) {
     if (!fieldList) {
       return;
     }
-    const fieldListType = getRegisteredField(fieldList.entityUuid, fieldList.name)?.fieldListType ?? "default";
-    const parentBundle = fieldList.entityType === itemEntityType ? state.getFieldListItem(fieldList.entityUuid)?.bundle ?? null : null;
-    const observableElement = getElementToObserve(
-      uuid,
-      el,
-      item.bundle,
-      fieldListType,
-      parentBundle
-    );
     blockRects[uuid] = rectWithTime(
-      ui.getAbsoluteElementRect(
-        observableElement.getBoundingClientRect(),
-        scale,
-        offset
-      )
+      ui.getAbsoluteElementRect(el.getBoundingClientRect(), scale, offset)
     );
   }
   function refreshFieldRect(key) {
@@ -318,11 +286,7 @@ export default function(ui, debug, definitions, state, element) {
       );
     }
   }
-  onBlokkliEvent("state:reload:before", () => {
-    observedElementCache.clear();
-  });
   onBlokkliEvent("state:reloaded", () => {
-    observedElementCache.clear();
     if (stateReloadTimeout) {
       window.clearTimeout(stateReloadTimeout);
     }
@@ -331,6 +295,7 @@ export default function(ui, debug, definitions, state, element) {
       updateVisibleRects();
     }
     stateReloadTimeout = window.setTimeout(updateVisibleRects, 300);
+    doSettleTimeout();
   });
   function forceRefresh() {
     updateVisibleRects();
@@ -351,17 +316,7 @@ export default function(ui, debug, definitions, state, element) {
     if (!item) {
       return;
     }
-    const el = registeredBlocks[item.uuid];
-    if (!el) {
-      return;
-    }
-    return getElementToObserve(
-      item.uuid,
-      el,
-      item.bundle,
-      item.fieldListType,
-      item.parentBlockBundle
-    );
+    return registeredBlocks[item.uuid];
   }
   function isBlockVisible(uuid) {
     return visibleBlocks.has(uuid);
@@ -389,10 +344,19 @@ export default function(ui, debug, definitions, state, element) {
       }, 500);
     }
   }
+  function doSettleTimeout() {
+    if (settleTimeout) {
+      window.clearTimeout(settleTimeout);
+    }
+    settleTimeout = window.setTimeout(() => {
+      settleKey.value++;
+    }, 50);
+  }
   function registerBlock(key, uuid, el) {
     logger.log("registerBlock: " + uuid);
     blockUuidCurrentKey[uuid] = key;
     doInitTimeout();
+    doSettleTimeout();
     if (!(el instanceof HTMLElement)) {
       logger.log("registerBlock call unregisterBlock because no element", uuid);
       unregisterBlock(key, uuid);
@@ -419,26 +383,18 @@ export default function(ui, debug, definitions, state, element) {
         uuid
       );
     }
-    const fieldListType = getRegisteredField(fieldList.entityUuid, fieldList.name)?.fieldListType ?? "default";
-    const parentBundle = fieldList.entityType === itemEntityType ? state.getFieldListItem(fieldList.entityUuid)?.bundle ?? null : null;
-    const observableElement = getElementToObserve(
-      item.uuid,
-      el,
-      item.bundle,
-      fieldListType,
-      parentBundle
-    );
-    blockElementToUuid.set(observableElement, uuid);
+    blockElementToUuid.set(el, uuid);
     registeredBlocks[uuid] = el;
-    observedElements[uuid] = observableElement;
-    intersectionObserver.observe(observableElement);
-    resizeObserver.observe(observableElement);
+    observedElements[uuid] = el;
+    intersectionObserver.observe(el);
+    resizeObserver.observe(el);
   }
   function unregisterBlock(key, uuid) {
     const currentKey = blockUuidCurrentKey[uuid];
     if (currentKey && currentKey !== key) {
       return;
     }
+    doSettleTimeout();
     logger.log("unregisterBlock: " + uuid);
     const el = registeredBlocks[uuid];
     const observedElement = observedElements[uuid];
@@ -542,6 +498,7 @@ export default function(ui, debug, definitions, state, element) {
     isReady: computed(
       () => mutationsReady.value && intersectionReady.value && !isInitalizing.value
     ),
+    settleKey: computed(() => settleKey.value),
     init,
     getDragElement,
     updateVisibleRects,
@@ -551,6 +508,7 @@ export default function(ui, debug, definitions, state, element) {
     registeredBlockUuids,
     getDebugData,
     getRegisteredField,
-    registeredBlocks: computed(() => registeredBlocks)
+    registeredBlocks: computed(() => registeredBlocks),
+    getBoundingClientRect
   };
 }

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

@@ -0,0 +1,47 @@
+import type { DraggableItem, DropArea } from '#blokkli/types';
+type DropAreaProviderFunction = (items: DraggableItem[]) => DropArea[] | DropArea | undefined;
+export type DropAreaProvider = {
+    /**
+     * Register a drop area provider function.
+     *
+     * The function will be called when drop areas are requested during drag operations.
+     * It receives the currently dragged items and can return drop areas where those items can be dropped.
+     *
+     * @param fn - Function that returns drop areas based on dragged items
+     *
+     * @example
+     * ```ts
+     * dropArea.add((items) => {
+     *   // Only provide drop area for text blocks
+     *   if (items.every(item => item.bundle === 'text')) {
+     *     return {
+     *       id: 'custom-area',
+     *       label: 'Text Only Area',
+     *       accepts: (item) => item.bundle === 'text',
+     *     }
+     *   }
+     * })
+     * ```
+     */
+    add: (fn: DropAreaProviderFunction) => void;
+    /**
+     * Unregister a drop area provider function.
+     *
+     * Removes a previously registered function so it no longer provides drop areas.
+     *
+     * @param fn - The function to remove (must be the same reference used in add)
+     */
+    remove: (fn: DropAreaProviderFunction) => void;
+    /**
+     * Get all drop areas from all registered providers.
+     *
+     * Calls all registered provider functions with the dragged items,
+     * flattens the results, and filters out undefined values.
+     *
+     * @param items - The currently dragged items
+     * @returns Array of all available drop areas for these items
+     */
+    getDropAreas: (items: DraggableItem[]) => DropArea[];
+};
+export default function (): DropAreaProvider;
+export {};

package/dist/runtime/helpers/{dropAreaProvider.js → providers/dropArea.js}

@@ -1,4 +1,4 @@
-import { falsy } from "./index.js";
+import { falsy } from "../index.js";
 export default function() {
   let functions = [];
   const add = (fn) => {

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

@@ -1,6 +1,63 @@
-import type { DebugProvider } from '../debugProvider.js';
+import type { DebugProvider } from './debug.js';
 export type ElementProvider = {
+    /**
+     * Query all matching elements with debug logging.
+     *
+     * Wrapper around `querySelectorAll` that:
+     * - Logs the query and reason to debug console
+     * - Filters out non-HTMLElement results
+     * - Optionally maps/transforms results
+     * - Filters out null/undefined mapped results
+     *
+     * @param target - Element or document to query within
+     * @param query - CSS selector string
+     * @param reason - Human-readable reason for the query (for debugging)
+     * @param map - Optional function to transform each matched element
+     * @returns Array of matched (and optionally transformed) elements
+     *
+     * @example
+     * ```ts
+     * // Get all buttons
+     * const buttons = element.queryAll(document, 'button', 'Get all buttons')
+     *
+     * // Get all buttons with data attributes
+     * const buttonData = element.queryAll(
+     *   document,
+     *   'button[data-action]',
+     *   'Get action buttons',
+     *   (el) => el.dataset.action
+     * )
+     * ```
+     */
     queryAll: <T = HTMLElement>(target: HTMLElement | Document, query: string, reason: string, map?: (v: HTMLElement) => T | null | undefined) => T[];
+    /**
+     * Query the first matching element with debug logging.
+     *
+     * Wrapper around `querySelector` that:
+     * - Logs the query and reason to debug console
+     * - Returns null if no match or match is not HTMLElement
+     * - Optionally maps/transforms the result
+     *
+     * @param target - Element or document to query within
+     * @param query - CSS selector string
+     * @param reason - Human-readable reason for the query (for debugging)
+     * @param map - Optional function to transform the matched element
+     * @returns The first matched (and optionally transformed) element, or null
+     *
+     * @example
+     * ```ts
+     * // Get first button
+     * const button = element.query(document, 'button', 'Get first button')
+     *
+     * // Get button action
+     * const action = element.query(
+     *   document,
+     *   'button[data-action]',
+     *   'Get action button',
+     *   (el) => el.dataset.action
+     * )
+     * ```
+     */
     query: <T = HTMLElement>(target: HTMLElement | Document, query: string, reason: string, map?: (v: HTMLElement) => T | null | undefined) => T | null;
 };
 export default function (debug: DebugProvider): ElementProvider;

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

@@ -0,0 +1,56 @@
+import type { FeatureDefinition, AdapterMethods } from '#blokkli/types';
+import { type ValidFeatureKey } from '#blokkli-build/features';
+import { type ComputedRef } from '#imports';
+import type { StorageProvider } from './storage.js';
+export type FeaturesProvider = {
+    /**
+     * List of all registered feature definitions.
+     *
+     * Updates automatically via HMR during development.
+     */
+    features: ComputedRef<FeatureDefinition[]>;
+    /**
+     * List of currently mounted features.
+     *
+     * Features are mounted when their components are rendered in the editor.
+     * This list is used to track which features are active in the current session.
+     */
+    mountedFeatures: ComputedRef<FeatureDefinition<AdapterMethods[], ValidFeatureKey>[]>;
+    /**
+     * List of available beta features.
+     *
+     * Only includes features marked with `beta: true` in their definition.
+     * These features can be individually enabled/disabled by users.
+     */
+    betaFeatures: ComputedRef<{
+        id: ValidFeatureKey;
+        label: string;
+        description?: string;
+    }[]>;
+    /**
+     * List of beta features that are currently enabled.
+     *
+     * Derived from user settings stored in local storage.
+     * Users can toggle beta features on/off in the settings UI.
+     */
+    enabledBetaFeatures: ComputedRef<ValidFeatureKey[]>;
+    /**
+     * Mount a feature.
+     *
+     * Called when a feature component is mounted/rendered.
+     * Adds the feature to the mountedFeatures list.
+     *
+     * @param feature - The feature definition to mount
+     */
+    mount: (feature: FeatureDefinition<AdapterMethods[], ValidFeatureKey>) => void;
+    /**
+     * Unmount a feature.
+     *
+     * Called when a feature component is unmounted/destroyed.
+     * Removes the feature from the mountedFeatures list.
+     *
+     * @param id - The feature ID to unmount
+     */
+    unmount: (id: string) => void;
+};
+export default function (storage: StorageProvider): FeaturesProvider;

package/dist/runtime/helpers/{featuresProvider.js → providers/features.js}

@@ -2,7 +2,7 @@ import {
   featureDefinitions
 } from "#blokkli-build/features";
 import { computed, ref } from "#imports";
-import { falsy } from "./index.js";
+import { falsy } from "../index.js";
 export default function(storage) {
   const definitions = ref(featureDefinitions);
   const mountedFeatures = ref([]);

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

@@ -1,8 +1,23 @@
 import type { BlokkliFieldElement } from '#blokkli/types';
-import type { DomProvider } from '../domProvider.js';
-import type { StateProvider } from '../stateProvider.js';
-import type { BlockDefinitionProvider } from '../typesProvider.js';
+import type { DomProvider } from './dom.js';
+import type { BlockDefinitionProvider } from './types.js';
 export type FieldsProvider = {
+    /**
+     * Find a field element by host entity UUID and field name.
+     *
+     * Returns a BlokkliFieldElement with complete field metadata including:
+     * - Field configuration (label, cardinality, allowed bundles)
+     * - Host entity information
+     * - Nesting level and field list type
+     * - HTML element reference
+     * - Drop alignment settings
+     *
+     * Results are cached and invalidated on state reload.
+     *
+     * @param uuid - The host entity UUID
+     * @param fieldName - The name of the field
+     * @returns The field element with metadata, or undefined if not found
+     */
     find: (uuid: string, fieldName: string) => BlokkliFieldElement | undefined;
 };
-export default function (state: StateProvider, dom: DomProvider, types: BlockDefinitionProvider): FieldsProvider;
+export default function (dom: DomProvider, types: BlockDefinitionProvider): FieldsProvider;

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

@@ -1,5 +1,5 @@
 import onBlokkliEvent from "../composables/onBlokkliEvent.js";
-export default function(state, dom, types) {
+export default function(dom, types) {
   const fieldCache = /* @__PURE__ */ new Map();
   function find(uuid, fieldName) {
     const key = uuid + ":" + fieldName;