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

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

@@ -1,16 +1,15 @@
-import { reactive, ref, computed } from "#imports";
+import { reactive, ref, computed, onMounted } 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,11 @@ 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();
@@ -154,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}`;
@@ -179,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) {
@@ -265,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) {
@@ -322,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);
     }
@@ -335,6 +295,7 @@ export default function(ui, debug, definitions, state, element) {
       updateVisibleRects();
     }
     stateReloadTimeout = window.setTimeout(updateVisibleRects, 300);
+    doSettleTimeout();
   });
   function forceRefresh() {
     updateVisibleRects();
@@ -355,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);
@@ -393,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);
@@ -423,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];
@@ -531,6 +483,9 @@ export default function(ui, debug, definitions, state, element) {
       }
     };
   }
+  onMounted(() => {
+    doInitTimeout();
+  });
   return {
     getDropElementMarkup,
     getVisibleBlocks,
@@ -546,6 +501,7 @@ export default function(ui, debug, definitions, state, element) {
     isReady: computed(
       () => mutationsReady.value && intersectionReady.value && !isInitalizing.value
     ),
+    settleKey: computed(() => settleKey.value),
     init,
     getDragElement,
     updateVisibleRects,

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,16 +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: (
     /**
-     * The host entity UUID.
+     * 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
      */
-    uuid: string, 
-    /**
-     * The name of the field.
-     */
-    fieldName: string) => BlokkliFieldElement | undefined;
+    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;

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

@@ -0,0 +1,44 @@
+import { type Ref } from 'vue';
+import type { BlockIndicator } from '../../types/index.js';
+export type IndicatorsProvider = {
+    /**
+     * List of all active block indicators.
+     *
+     * Indicators are visual badges/icons that appear on blocks
+     * (e.g., anchor icons, schedule indicators, etc.).
+     */
+    indicators: Ref<BlockIndicator[]>;
+    /**
+     * UUID of the currently hovered block.
+     *
+     * Used to show/hide hover-specific indicators.
+     */
+    hovered: Ref<string>;
+    /**
+     * Add a block indicator.
+     *
+     * Registers a new indicator to be displayed on a block.
+     *
+     * @param indicator - The indicator configuration
+     */
+    addIndicator: (indicator: BlockIndicator) => void;
+    /**
+     * Remove a block indicator.
+     *
+     * Removes an indicator based on its ID and the block UUID.
+     * Both must match to remove the indicator.
+     *
+     * @param id - The indicator ID
+     * @param uuid - The block UUID
+     */
+    removeIndicator: (id: string, uuid: string) => void;
+    /**
+     * Set the currently hovered block.
+     *
+     * Updates the hovered state used to show hover-specific indicators.
+     *
+     * @param uuid - The block UUID, or null/undefined to clear
+     */
+    setHovered: (uuid?: string | null) => void;
+};
+export default function (): IndicatorsProvider;

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

@@ -0,0 +1,76 @@
+import { type Ref, type ComputedRef } from 'vue';
+import type { KeyboardShortcut } from '#blokkli/types';
+type RegisteredShortcut = {
+    key: string;
+    shortcut: KeyboardShortcut;
+};
+export type KeyboardProvider = {
+    /**
+     * Whether the Space key is currently pressed.
+     *
+     * Commonly used to enable panning mode in the artboard.
+     */
+    isPressingSpace: Readonly<Ref<boolean>>;
+    /**
+     * Whether Control/Meta key is currently pressed.
+     *
+     * Meta is Cmd on macOS, Ctrl on Windows/Linux.
+     * Also true when CapsLock is active.
+     */
+    isPressingControl: Readonly<Ref<boolean>>;
+    /**
+     * Whether the Shift key is currently pressed.
+     */
+    isPressingShift: Readonly<Ref<boolean>>;
+    /**
+     * Update keyboard modifier state from a mouse/pointer event.
+     *
+     * Useful for updating modifier state during drag operations where
+     * keyboard events might not fire.
+     *
+     * @param e - The mouse or pointer event
+     */
+    setShortcutStateFromEvent: (e: MouseEvent | PointerEvent) => void;
+    /**
+     * List of all registered keyboard shortcuts.
+     *
+     * Shortcuts are registered by features, buttons, and actions to enable
+     * keyboard navigation and commands.
+     */
+    shortcuts: ComputedRef<RegisteredShortcut[]>;
+    /**
+     * Register a keyboard shortcut.
+     *
+     * Adds the shortcut to the global shortcuts list for display in help UI.
+     *
+     * @param shortcut - The keyboard shortcut configuration
+     */
+    registerShortcut: (shortcut: KeyboardShortcut) => void;
+    /**
+     * Unregister a keyboard shortcut.
+     *
+     * Removes the shortcut from the global shortcuts list.
+     *
+     * @param shortcut - The keyboard shortcut to remove
+     */
+    unregisterShortcut: (shortcut: KeyboardShortcut) => void;
+    /**
+     * Lock keyboard events.
+     *
+     * Prevents keyboard shortcuts from firing. Used when text input is focused
+     * or dialogs are open to avoid unintended actions.
+     *
+     * @param id - Unique identifier for this lock
+     */
+    lockKeyboardEvents: (id: string) => void;
+    /**
+     * Unlock keyboard events.
+     *
+     * Removes a keyboard lock, re-enabling shortcuts when all locks are removed.
+     *
+     * @param id - The lock identifier to remove
+     */
+    unlockKeyboardEvents: (id: string) => void;
+};
+export default function (): KeyboardProvider;
+export {};

package/dist/runtime/helpers/{keyboardProvider.js → providers/keyboard.js}

@@ -3,7 +3,6 @@ import {
   readonly,
   onMounted,
   onBeforeUnmount,
-  watch,
   computed
 } from "vue";
 import { eventBus } from "#blokkli/helpers/eventBus";
@@ -13,7 +12,7 @@ function getControlState(e) {
   }
   return e.getModifierState("Control") || e.getModifierState("Meta");
 }
-export default function(animationProvider) {
+export default function() {
   const isPressingControl = ref(false);
   const isPressingSpace = ref(false);
   const isPressingShift = ref(false);
@@ -62,12 +61,6 @@ export default function(animationProvider) {
     document.removeEventListener("keyup", onKeyUp);
     document.removeEventListener("visibilitychange", onVisibilityChange);
   });
-  watch(isPressingSpace, () => {
-    animationProvider.requestDraw();
-  });
-  watch(isPressingControl, () => {
-    animationProvider.requestDraw();
-  });
   const getShortcutKey = (shortcut) => [!!shortcut.meta, !!shortcut.shift, shortcut.code].join("-");
   const registerShortcut = (shortcut) => {
     registeredShortcuts.value.push({ key: getShortcutKey(shortcut), shortcut });

package/dist/runtime/helpers/{pluginProvider.d.ts → providers/plugin.d.ts}

@@ -37,8 +37,44 @@ type PluginDataMap = {
     menuButton: MenuButtonPlugin;
 };
 export type PluginProvider = {
+    /**
+     * Register a plugin provider function.
+     *
+     * The function will be called when plugins of this type are requested.
+     * It can return a single plugin, an array of plugins, or undefined.
+     *
+     * @param type - The plugin type ('addAction', 'itemDropdownAction', 'menuButton')
+     * @param fn - Function that returns plugin(s)
+     *
+     * @example
+     * ```ts
+     * plugin.add('addAction', () => ({
+     *   id: 'custom-add',
+     *   label: 'Add Custom',
+     *   bundles: ['text'],
+     *   callback: () => console.log('add'),
+     * }))
+     * ```
+     */
     add<T extends keyof PluginFunctionMap>(type: T, fn: PluginFunctionMap[T]): void;
+    /**
+     * Unregister a plugin provider function.
+     *
+     * Removes a previously registered function so it no longer provides plugins.
+     *
+     * @param type - The plugin type
+     * @param fn - The function to remove (must be the same reference used in add)
+     */
     remove<T extends keyof PluginFunctionMap>(type: T, fn: PluginFunctionMap[T]): void;
+    /**
+     * Get all plugins from all registered providers.
+     *
+     * Calls all registered provider functions for this type, flattens the results,
+     * and filters out undefined values.
+     *
+     * @param type - The plugin type to retrieve
+     * @returns Array of all available plugins of this type
+     */
     get<T extends keyof PluginDataMap>(type: T): PluginDataMap[T][];
 };
 export default function (): PluginProvider;

package/dist/runtime/helpers/{selectionProvider.d.ts → providers/selection.d.ts}

@@ -1,6 +1,6 @@
 import { type Ref, type ComputedRef } from '#imports';
 import type { DraggableItem, InteractionMode, RenderedFieldListItem } from '#blokkli/types';
-import type { BlocksProvider } from './providers/blocks.js';
+import type { BlocksProvider } from './blocks.js';
 export type SelectionProvider = {
     /**
      * The currently selected UUIDs.
@@ -66,6 +66,9 @@ export type SelectionProvider = {
      * The block bundles of the items being dragged.
      */
     dragItemsBundles: ComputedRef<string[]>;
+    /**
+     * Determine if the given block UUID is currently selected.
+     */
     isBlockSelected(uuid: string): boolean;
     /**
      * Lock selection.

package/dist/runtime/helpers/{selectionProvider.js → providers/selection.js}

@@ -1,4 +1,4 @@
-import onBlokkliEvent from "./composables/onBlokkliEvent.js";
+import onBlokkliEvent from "../composables/onBlokkliEvent.js";
 import { computed, ref } from "#imports";
 import { falsy, onlyUnique } from "#blokkli/helpers";
 export default function(blocks) {