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

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

@@ -0,0 +1,227 @@
+import { type Ref, type ComputedRef } from 'vue';
+import type { BlokkliAdapter, AdapterContext } from '../../adapter/index.js';
+import type { MutatedField, EditEntity, MutatedOptions, TranslationState, MappedState, MutationItem, Validation, MutateWithLoadingStateFunction, EditMode, FieldListItem, PublishOptions, EditPermission } from '#blokkli/types';
+import type { TextProvider } from './texts.js';
+export type BlokkliOwner = {
+    name: string | undefined;
+    currentUserIsOwner: boolean;
+};
+export type RenderedBlock = {
+    item: FieldListItem;
+    parentEntityType: string;
+    parentEntityBundle: string;
+    parentEntityUuid: string;
+};
+export type StateProvider = {
+    /**
+     * Information about the editing session owner.
+     *
+     * Includes owner name and whether the current user is the owner.
+     */
+    owner: Readonly<Ref<BlokkliOwner | null>>;
+    /**
+     * Refresh key that changes when state is reloaded.
+     *
+     * Use as a component key to force remounting when state updates.
+     */
+    refreshKey: Readonly<Ref<string>>;
+    /**
+     * All mutated fields in the current editing session.
+     *
+     * Each field contains its entity context, field name, and list of blocks.
+     */
+    mutatedFields: Readonly<Ref<MutatedField[]>>;
+    /**
+     * The host entity being edited.
+     *
+     * Contains label, status, and bundle information.
+     */
+    entity: Readonly<Ref<EditEntity>>;
+    /**
+     * Mutated options for all blocks and the host entity.
+     *
+     * Maps block UUIDs (or 'HOST' for host options) to their option values.
+     */
+    mutatedOptions: MutatedOptions;
+    /**
+     * Translation state for the edited entity.
+     *
+     * Includes source language, available languages, and existing translations.
+     */
+    translation: Readonly<Ref<TranslationState>>;
+    /**
+     * Publishing options and capabilities.
+     *
+     * Indicates whether publishing, scheduling, and revisions are available.
+     */
+    publishOptions: Readonly<Ref<PublishOptions>>;
+    /**
+     * History of all mutations in the editing session.
+     *
+     * Used for undo/redo functionality and tracking changes.
+     */
+    mutations: Readonly<Ref<MutationItem[]>>;
+    /**
+     * Current position in the mutation history.
+     *
+     * -1 indicates no mutations, 0+ indicates active mutation index.
+     */
+    currentMutationIndex: Readonly<Ref<number>>;
+    /**
+     * Validation violations for the current state.
+     *
+     * Contains errors and warnings about invalid field values or configurations.
+     */
+    violations: Readonly<Ref<Validation[]>>;
+    /**
+     * Execute a mutation with loading state and error handling.
+     *
+     * Shows loading indicator, handles errors, updates state, and shows messages.
+     *
+     * @param callback - Function that performs the mutation
+     * @param errorMessage - Error message to show on failure (false to suppress)
+     * @param successMessage - Optional success message to show
+     * @returns True if successful, false if failed
+     */
+    mutateWithLoadingState: MutateWithLoadingStateFunction;
+    /**
+     * Current edit mode.
+     *
+     * - 'readonly': User cannot edit (no permission or not owner)
+     * - 'editing': User can edit
+     * - 'translating': User is editing a translation
+     */
+    editMode: Readonly<Ref<EditMode>>;
+    /**
+     * The raw mutated entity data from the adapter.
+     *
+     * Contains adapter-specific entity data (e.g., Drupal entity fields).
+     */
+    mutatedEntity: Readonly<Ref<any>>;
+    /**
+     * Whether the current user can edit.
+     *
+     * True when state is loaded, user is owner, no load errors, and has edit permission.
+     */
+    canEdit: ComputedRef<boolean>;
+    /**
+     * List of permissions for the current user.
+     *
+     * Includes 'edit', 'view', and other adapter-specific permissions.
+     */
+    permissions: ComputedRef<EditPermission[]>;
+    /**
+     * Whether state has been successfully loaded.
+     *
+     * True when state loaded without errors.
+     */
+    stateAvailable: ComputedRef<boolean>;
+    /**
+     * Whether a loading operation is in progress.
+     *
+     * Automatically adds 'bk-body-loading' class to document.body when true.
+     */
+    isLoading: Readonly<Ref<boolean>>;
+    /**
+     * UUIDs of all blocks loaded from the library.
+     *
+     * Blocks with bundle 'from_library'.
+     */
+    fromLibraryUuids: Readonly<Ref<Readonly<string[]>>>;
+    /**
+     * Get the number of blocks in a field.
+     *
+     * Results are cached for performance.
+     *
+     * @param key - The field key (entityUuid:fieldName)
+     * @returns Number of blocks in the field
+     */
+    getFieldBlockCount: (key: string) => number;
+    /**
+     * Get the total count of blocks with a specific bundle.
+     *
+     * @param bundle - The block bundle
+     * @returns Total number of blocks with this bundle
+     */
+    getBlockBundleCount: (bundle: string) => number;
+    /**
+     * Get a field list item by UUID.
+     *
+     * @param uuid - The block UUID
+     * @returns The field list item, or undefined if not found
+     */
+    getFieldListItem: (uuid: string) => FieldListItem | undefined;
+    /**
+     * Get the mutated field that contains a block.
+     *
+     * @param uuid - The block UUID
+     * @returns The field containing this block, or undefined if not found
+     */
+    getFieldListForBlock: (uuid: string) => MutatedField | undefined;
+    /**
+     * Get a mutated field by entity UUID and field name.
+     *
+     * @param uuid - The entity UUID
+     * @param fieldName - The field name
+     * @returns The mutated field, or undefined if not found
+     */
+    getMutatedField: (uuid: string, fieldName: string) => MutatedField | undefined;
+    /**
+     * Get all block UUIDs, optionally filtered by bundle.
+     *
+     * @param bundle - Optional bundle to filter by
+     * @returns Array of block UUIDs
+     */
+    getAllUuids: (bundle?: string) => string[];
+    /**
+     * Get the nesting level of a block.
+     *
+     * Level 0 = block in host entity field
+     * Level 1 = block in another block's field
+     * Level 2+ = deeper nesting
+     *
+     * @param uuid - The block UUID
+     * @returns The nesting level (0+)
+     */
+    getNestingLevel: (uuid: string) => number;
+    /**
+     * Check if a block is a child (direct or nested) of another block.
+     *
+     * Recursively checks parent relationships.
+     *
+     * @param childUuid - The potential child block UUID
+     * @param parentUuid - The potential parent block UUID
+     * @returns True if childUuid is a descendant of parentUuid
+     */
+    isChildOf: (childUuid: string, parentUuid: string) => boolean;
+    /**
+     * Get the current mapped state.
+     *
+     * Throws error if called before state is available.
+     *
+     * @returns The current mapped state
+     */
+    getMappedState: () => MappedState;
+    /**
+     * Temporarily override the state.
+     *
+     * Used for previewing changes without committing them.
+     *
+     * @param state - The temporary state to use
+     */
+    setOverrideState: (state: MappedState) => void;
+    /**
+     * Clear the temporary override and restore previous state.
+     *
+     * Throws error if no override is active.
+     */
+    clearOverrideState: () => void;
+    /**
+     * Get the field key for a block UUID.
+     *
+     * @param uuid - The block UUID
+     * @returns The field key (entityUuid:fieldName), or null if not found
+     */
+    getFieldKeyForUuid: (uuid: string) => string | null;
+};
+export default function (adapter: BlokkliAdapter<any>, context: ComputedRef<AdapterContext>, $t: TextProvider, providerKey: string, permissions: EditPermission[]): Promise<StateProvider>;

package/dist/runtime/helpers/{stateProvider.js → providers/state.js}

@@ -6,12 +6,12 @@ import {
   provide
 } from "vue";
 import { refreshNuxtData, useState } from "nuxt/app";
-import { INJECT_MUTATED_FIELDS_MAP } from "./symbols.js";
-import onBlokkliEvent from "./composables/onBlokkliEvent.js";
+import { INJECT_MUTATED_FIELDS_MAP } from "../symbols.js";
+import onBlokkliEvent from "../composables/onBlokkliEvent.js";
 import { falsy, getFieldKey } from "#blokkli/helpers";
 import { eventBus, emitMessage } from "#blokkli/helpers/eventBus";
 import { nextTick } from "#imports";
-import { addElementClasses } from "./addElementClasses.js";
+import { addElementClasses } from "../composables/addElementClasses.js";
 import { BUNDLE_FROM_LIBRARY } from "#blokkli/constants";
 const HOST_OPTION_KEY = "HOST";
 function mapPublishOptions(context) {

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

@@ -0,0 +1,64 @@
+import { type ComputedRef, type WritableComputedRef } from '#imports';
+import type { AdapterContext, BlokkliAdapter } from '#blokkli/adapter';
+export type StorageProvider = {
+    /**
+     * Create a reactive storage value synced to localStorage.
+     *
+     * The value is automatically persisted to localStorage on change.
+     * Can optionally be synced to user settings on the server.
+     *
+     * @param key - Storage key (will be prefixed with 'blokkli:')
+     * @param defaultValue - Default value if no stored value exists
+     * @param persist - Whether to sync to server user settings (default: false)
+     * @returns Reactive writable computed ref synced to storage
+     *
+     * @example
+     * ```ts
+     * const showGrid = storage.use('showGrid', false)
+     * showGrid.value = true // Automatically saved to localStorage
+     * ```
+     */
+    use: <T>(key: string | ComputedRef<string>, defaultValue: T, persist?: boolean) => WritableComputedRef<T>;
+    /**
+     * Create a reactive storage value with entity context prefix.
+     *
+     * Same as `use()` but automatically prefixes the key with entity type and UUID.
+     * Useful for entity-specific settings (e.g., sidebar state per page).
+     *
+     * @param key - Storage key (will be prefixed with context)
+     * @param defaultValue - Default value if no stored value exists
+     * @param persist - Whether to sync to server user settings (default: false)
+     * @returns Reactive writable computed ref synced to storage
+     *
+     * @example
+     * ```ts
+     * // If context is node:abc123, key becomes 'sidebarOpen:node:abc123'
+     * const sidebarOpen = storage.useWithContextPrefix('sidebarOpen', false)
+     * ```
+     */
+    useWithContextPrefix: <T>(key: string, defaultValue: T, persist?: boolean) => WritableComputedRef<T>;
+    /**
+     * Clear all blokkli storage values.
+     *
+     * Removes all localStorage entries starting with 'blokkli:' prefix.
+     * Does not affect server user settings.
+     */
+    clearAll: () => void;
+    /**
+     * Clear a specific storage value.
+     *
+     * Removes the value from localStorage (without prefix).
+     *
+     * @param key - The storage key to clear (without 'blokkli:' prefix)
+     */
+    clear: (key: string) => void;
+};
+/**
+ * Create a reactive variable that is synced to local storage using the
+ * given key. The sync only happens client side and after the component
+ * has been mounted.
+ *
+ * This composable can be used to keep state across page navigations and
+ * even after a refresh.
+ */
+export default function (adapter: BlokkliAdapter<any>, context: ComputedRef<AdapterContext>): Promise<StorageProvider>;

package/dist/runtime/helpers/{textProvider.d.ts → providers/texts.d.ts}

@@ -1,4 +1,4 @@
 import { type ComputedRef } from 'vue';
-import type { AdapterContext } from '../adapter/index.js';
+import type { AdapterContext } from '../../adapter/index.js';
 export type TextProvider = (key: string, defaultValue?: string) => string;
 export default function (context?: ComputedRef<AdapterContext>): TextProvider;

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

@@ -0,0 +1,119 @@
+import type { DraggableStyle } from '#blokkli/types';
+import type { RGB, ThemeColorGroup, ThemeColorShade, ThemeColors, ThemeContextColorGroup, ThemeContextColorShade, ThemeContextColors, ThemeName } from '#blokkli/types/theme';
+import { type Ref } from '#imports';
+import type { ElementProvider } from './element.js';
+type ThemeMap = {
+    accent: Ref<ThemeColors>;
+    mono: Ref<ThemeColors>;
+    teal: Ref<ThemeContextColors>;
+    yellow: Ref<ThemeContextColors>;
+    red: Ref<ThemeContextColors>;
+    lime: Ref<ThemeContextColors>;
+    orange: Ref<ThemeContextColors>;
+};
+export type ThemeProvider = {
+    /**
+     * Accent color palette (primary brand color).
+     *
+     * Available shades: 50-950
+     */
+    accent: Ref<ThemeColors>;
+    /**
+     * Monochrome color palette (grays).
+     *
+     * Available shades: 50-950
+     */
+    mono: Ref<ThemeColors>;
+    /**
+     * Teal context color palette.
+     *
+     * Available shades: bg, fg, fgHover, bgHover
+     */
+    teal: Ref<ThemeContextColors>;
+    /**
+     * Yellow context color palette.
+     *
+     * Available shades: bg, fg, fgHover, bgHover
+     */
+    yellow: Ref<ThemeContextColors>;
+    /**
+     * Red context color palette.
+     *
+     * Available shades: bg, fg, fgHover, bgHover
+     */
+    red: Ref<ThemeContextColors>;
+    /**
+     * Lime context color palette.
+     *
+     * Available shades: bg, fg, fgHover, bgHover
+     */
+    lime: Ref<ThemeContextColors>;
+    /**
+     * Orange context color palette.
+     *
+     * Available shades: bg, fg, fgHover, bgHover
+     */
+    orange: Ref<ThemeContextColors>;
+    /**
+     * Get the draggable style for an element.
+     *
+     * Computes and caches the visual style to use when dragging this element.
+     * Includes background color, text color, and border radius.
+     *
+     * @param el - The element to get style for
+     * @returns The draggable style configuration
+     */
+    getDraggableStyle: (el: HTMLElement | SVGElement) => DraggableStyle;
+    /**
+     * Set a theme color value.
+     *
+     * Updates both the reactive ref and the CSS custom property on :root.
+     *
+     * @param group - The color group (accent, mono, teal, etc.)
+     * @param shade - The shade (50-950 for accent/mono, bg/fg/etc for context colors)
+     * @param value - RGB color as [r, g, b] array
+     */
+    setColor: <Group extends ThemeColorGroup | ThemeContextColorGroup>(group: Group, shade: Group extends ThemeColorGroup ? ThemeColorShade : ThemeContextColorShade, value: RGB) => void;
+    /**
+     * Apply a theme by name.
+     *
+     * Replaces all theme colors with the selected theme.
+     * Use 'custom' to restore previously customized colors.
+     *
+     * @param name - Theme name or 'custom' for customized theme
+     */
+    applyTheme: (name: ThemeName | 'custom') => void;
+    /**
+     * Invalidate cached style for an element.
+     *
+     * Forces recalculation of draggable style next time it's requested.
+     * Useful when element styling changes dynamically.
+     *
+     * @param el - The element to invalidate
+     */
+    invalidateCachedStyle: (el: HTMLElement | SVGElement) => void;
+    /**
+     * Get an RGB color value from the theme.
+     *
+     * @param color - The color group
+     * @param key - The shade key
+     * @returns RGB color as [r, g, b] array
+     */
+    getColor<K extends keyof ThemeMap, T extends ThemeMap[K]['value']>(color: K, key: keyof T): RGB;
+    /**
+     * Get a color as an rgba() CSS string.
+     *
+     * @param color - The color group
+     * @param key - The shade key
+     * @param alpha - Optional alpha value (0-1, default: 1)
+     * @returns CSS rgba() string
+     *
+     * @example
+     * ```ts
+     * theme.getColorString('accent', 700, 0.5) // 'rgba(59, 130, 246, 0.5)'
+     * ```
+     */
+    getColorString<K extends keyof ThemeMap, T extends ThemeMap[K]['value']>(color: K, key: keyof T, alpha?: number): string;
+};
+export default function (element: ElementProvider): ThemeProvider;
+export {};

package/dist/runtime/helpers/{themeProvider.js → providers/theme.js}

@@ -1,8 +1,8 @@
 import { theme, themes } from "#blokkli-build/config";
 import { ref, onMounted, onBeforeUnmount } from "#imports";
-import { rgbaToString } from "./index.js";
-import { DragStyle } from "./DragStyle/index.js";
-import onBlokkliEvent from "./composables/onBlokkliEvent.js";
+import { rgbaToString } from "../index.js";
+import { DragStyle } from "../DragStyle/index.js";
+import onBlokkliEvent from "../composables/onBlokkliEvent.js";
 export default function(element) {
   const rootElement = element.query(
     document,

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

@@ -0,0 +1,49 @@
+import type { TourItem } from '#blokkli/types';
+import { type Ref } from '#imports';
+type TourProviderFunction = () => TourItem[] | TourItem | undefined;
+export type TourProvider = {
+    /**
+     * Register a tour provider function.
+     *
+     * The function will be called when tour items are requested.
+     * It can return a single tour item, an array of tour items, or undefined.
+     *
+     * @param fn - Function that returns tour item(s)
+     *
+     * @example
+     * ```ts
+     * tour.add(() => ({
+     *   id: 'welcome',
+     *   title: 'Welcome',
+     *   text: 'Welcome to the editor!',
+     *   element: '.bk-main-canvas',
+     * }))
+     * ```
+     */
+    add: (fn: TourProviderFunction) => void;
+    /**
+     * Unregister a tour provider function.
+     *
+     * Removes a previously registered function so it no longer provides tour items.
+     *
+     * @param fn - The function to remove (must be the same reference used in add)
+     */
+    remove: (fn: TourProviderFunction) => void;
+    /**
+     * Get all tour items from all registered providers.
+     *
+     * Calls all registered provider functions, flattens the results,
+     * and filters out undefined values.
+     *
+     * @returns Array of all available tour items
+     */
+    getTourItems: () => TourItem[];
+    /**
+     * Whether a tour is currently active.
+     *
+     * Set to true when a tour starts, false when it ends.
+     */
+    isTouring: Ref<boolean>;
+};
+export default function (): TourProvider;
+export {};

package/dist/runtime/helpers/{tourProvider.js → providers/tour.js}

@@ -1,4 +1,4 @@
-import { falsy } from "./index.js";
+import { falsy } from "../index.js";
 import { ref } from "#imports";
 export default function() {
   let functions = [];

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

@@ -0,0 +1,170 @@
+import type { ComputedRef } from 'vue';
+import type { FieldConfig, BlockBundleDefinition, EditableFieldConfig, BlockDefinitionInput, BlockDefinitionOptionsInput, DroppableFieldConfig, DraggableExistingBlock, EntityContext } from '../../types/index.js';
+import type { AdapterContext, BlokkliAdapter } from '../../adapter/index.js';
+import type { SelectionProvider } from './selection.js';
+export type BlokkliBlockType = BlockBundleDefinition & {
+    definition: BlockDefinitionInput<BlockDefinitionOptionsInput, never[]> | undefined;
+};
+/**
+ * Base interface for configuration objects that can be mapped by entity context.
+ *
+ * Used by ConfigMap to organize configuration data by entity type, bundle, and name
+ * for efficient lookup.
+ */
+interface MappableConfig {
+    /**
+     * The entity type (e.g., 'paragraph', 'node', 'block_content').
+     */
+    entityType: string;
+    /**
+     * The entity bundle (e.g., 'text', 'image', 'article').
+     */
+    entityBundle: string;
+    /**
+     * The configuration name (typically a field name like 'field_paragraphs').
+     */
+    name: string;
+}
+/**
+ * Efficient lookup map for configuration objects organized by entity context.
+ *
+ * Provides O(1) lookups by entity type, entity type + bundle, and
+ * entity type + bundle + name combinations. Used for field configurations,
+ * editable field configurations, and droppable field configurations.
+ *
+ * @template T - Configuration type extending MappableConfig
+ */
+declare class ConfigMap<T extends MappableConfig> {
+    private configs;
+    private mapEntityType;
+    private mapEntityTypeBundle;
+    private mapEntityTypeBundleName;
+    constructor(items: T[]);
+    /**
+     * Get all configurations for a specific entity type.
+     *
+     * @param entityType - The entity type to filter by
+     * @returns Array of matching configurations
+     *
+     * @example
+     * ```ts
+     * // Get all field configs for paragraph entities
+     * const paragraphFields = fieldConfig.forEntityType('paragraph')
+     * ```
+     */
+    forEntityType(entityType: string): T[];
+    /**
+     * Get all configurations for a specific entity type and bundle combination.
+     *
+     * @param entityType - The entity type
+     * @param entityBundle - The entity bundle
+     * @returns Array of matching configurations
+     *
+     * @example
+     * ```ts
+     * // Get all field configs for text paragraph bundle
+     * const textFields = fieldConfig.forEntityTypeAndBundle('paragraph', 'text')
+     * ```
+     */
+    forEntityTypeAndBundle(entityType: string, entityBundle: string): T[];
+    /**
+     * Get a specific configuration by entity type, bundle, and name.
+     *
+     * @param entityType - The entity type
+     * @param entityBundle - The entity bundle
+     * @param name - The configuration name (typically field name)
+     * @returns The matching configuration, or undefined if not found
+     *
+     * @example
+     * ```ts
+     * // Get field config for specific field on text paragraph
+     * const config = fieldConfig.forName('paragraph', 'text', 'field_items')
+     * ```
+     */
+    forName(entityType: string, entityBundle: string, name: string): T | undefined;
+    /**
+     * Get all configurations.
+     *
+     * @returns Array of all configurations in the map
+     */
+    all(): T[];
+}
+export type BlockDefinitionProvider = {
+    /**
+     * List of block bundles that contain nested blocks.
+     *
+     * A bundle is included if it has any field configurations
+     * where it can contain other blocks.
+     */
+    itemBundlesWithNested: string[];
+    /**
+     * Allowed block types in the currently selected list.
+     *
+     * Computed based on the parent field of selected blocks.
+     * Returns empty array if:
+     * - No blocks are selected
+     * - Selected blocks are in different fields
+     */
+    allowedTypesInList: ComputedRef<string[]>;
+    /**
+     * Block bundles that can be used somewhere in the current context.
+     *
+     * Includes bundles allowed:
+     * - Directly on the current entity
+     * - In nested blocks allowed on the current entity
+     *
+     * Used for add dialogs, library, and other "available blocks" UIs.
+     */
+    generallyAvailableBundles: BlockBundleDefinition[];
+    /**
+     * Get the bundle definition for a specific block type.
+     *
+     * @param bundle - The block bundle ID (e.g., 'text', 'image')
+     * @returns The bundle definition, or undefined if not found
+     */
+    getBlockBundleDefinition: (bundle: string) => BlockBundleDefinition | undefined;
+    /**
+     * Get the field configuration for a specific field on an entity.
+     *
+     * Field configurations define allowed bundles, cardinality, and other
+     * field-level settings.
+     *
+     * @param entityType - The entity type
+     * @param entityBundle - The entity bundle
+     * @param fieldName - The field name
+     * @returns The field configuration, or undefined if not found
+     */
+    getFieldConfig: (entityType: string, entityBundle: string, fieldName: string) => FieldConfig | undefined;
+    /**
+     * Map of all field configurations.
+     *
+     * Provides efficient lookups by entity type, bundle, and field name.
+     */
+    fieldConfig: ConfigMap<FieldConfig>;
+    /**
+     * Map of editable field configurations.
+     *
+     * Defines which fields support inline editing and their configuration.
+     */
+    editableFieldConfig: ConfigMap<EditableFieldConfig>;
+    /**
+     * Map of droppable field configurations.
+     *
+     * Defines which fields can accept dropped blocks and their behavior.
+     */
+    droppableFieldConfig: ConfigMap<DroppableFieldConfig>;
+    /**
+     * Get droppable field configuration for a field on a host.
+     *
+     * Throws an error if configuration is not found, as droppable fields
+     * should always have configuration when accessed.
+     *
+     * @param fieldName - The field name
+     * @param host - The host block or entity context
+     * @returns The droppable field configuration
+     * @throws Error if configuration not found
+     */
+    getDroppableFieldConfig: (fieldName: string, host: DraggableExistingBlock | EntityContext) => DroppableFieldConfig;
+};
+export default function (adapter: BlokkliAdapter<any>, selection: SelectionProvider, context: ComputedRef<AdapterContext>): Promise<BlockDefinitionProvider>;
+export {};