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

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

@@ -1,7 +1,10 @@
 import { itemEntityType } from "#blokkli-build/config";
 import onBlokkliEvent from "../composables/onBlokkliEvent.js";
+import { ref } from "#imports";
+import { BUNDLE_BLOKKLI_FRAGMENT } from "#blokkli/constants";
 export default function(state, dom, context) {
   const renderedFieldListItemCache = /* @__PURE__ */ new Map();
+  const refreshKey = ref(1);
   function getParentBlockBundle(field) {
     if (field.entityType !== itemEntityType) {
       return null;
@@ -26,7 +29,18 @@ export default function(state, dom, context) {
     }
     return null;
   }
+  function getFragmentData(item) {
+    if (item.bundle === BUNDLE_BLOKKLI_FRAGMENT && item.props.name) {
+      return {
+        name: item.props.name
+      };
+    }
+    return null;
+  }
   function getBlock(uuid) {
+    if (refreshKey.value === 0) {
+      return;
+    }
     const cached = renderedFieldListItemCache.get(uuid);
     if (cached) {
       return cached;
@@ -54,6 +68,7 @@ export default function(state, dom, context) {
       isNested: fieldList.entityType === itemEntityType,
       fieldListType: field?.fieldListType ?? "default",
       library: getLibraryData(item),
+      fragment: getFragmentData(item),
       parentBlockBundle,
       host: {
         type: fieldList.entityType,
@@ -66,6 +81,9 @@ export default function(state, dom, context) {
     return renderedItem;
   }
   function getAllBlocks() {
+    if (refreshKey.value === 0) {
+      return [];
+    }
     const blocks = [];
     const uuids = state.getAllUuids();
     for (let i = 0; i < uuids.length; i++) {
@@ -83,6 +101,7 @@ export default function(state, dom, context) {
   }
   onBlokkliEvent("state:reloaded", () => {
     renderedFieldListItemCache.clear();
+    refreshKey.value++;
   });
   return {
     getBlock,

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

@@ -0,0 +1,41 @@
+import type { Command } from '#blokkli/types';
+type CommandsProviderFunction = () => Command[] | Command | undefined;
+export type CommandsProvider = {
+    /**
+     * Register a command provider function.
+     *
+     * The function will be called when commands are requested.
+     * It can return a single command, an array of commands, or undefined.
+     *
+     * @param fn - Function that returns commands
+     *
+     * @example
+     * ```ts
+     * commands.add(() => ({
+     *   id: 'my-command',
+     *   label: 'My Command',
+     *   callback: () => console.log('executed'),
+     * }))
+     * ```
+     */
+    add: (fn: CommandsProviderFunction) => void;
+    /**
+     * Unregister a command provider function.
+     *
+     * Removes a previously registered function so it no longer provides commands.
+     *
+     * @param fn - The function to remove (must be the same reference used in add)
+     */
+    remove: (fn: CommandsProviderFunction) => void;
+    /**
+     * Get all commands from all registered providers.
+     *
+     * Calls all registered provider functions, flattens the results,
+     * and filters out undefined values.
+     *
+     * @returns Array of all available commands
+     */
+    getCommands: () => Command[];
+};
+export default function (): CommandsProvider;
+export {};

package/dist/runtime/helpers/{commandsProvider.js → providers/commands.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/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

@@ -14,6 +14,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 +26,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 +101,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 +117,7 @@ export default function(debug, ui) {
         editablesByUuid[entity.uuid][fieldName] = void 0;
       }
     }
+    doSettleTimeout();
   }
   function init() {
     intersectionObserver.init();
@@ -192,7 +204,10 @@ 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);
   onBeforeUnmount(() => {
@@ -210,6 +225,7 @@ export default function(debug, ui) {
     getEditablesForBlock,
     findEditableElement,
     getDroppableElements,
-    isReady: computed(() => !isInitalizing.value)
+    isReady: computed(() => !isInitalizing.value),
+    settleKey: computed(() => settleKey.value)
   };
 }