@jackuait/blok 0.4.1-beta.1 → 0.4.1-beta.12

package/src/variants/all-locales.ts

@@ -0,0 +1,155 @@
+/**
+ * Static imports for all 68 locales.
+ *
+ * This file forces Vite to bundle all locale JSON files instead of code-splitting them.
+ * It's only used for the "maximum" bundle size measurement variant.
+ *
+ * This file is NOT part of the public API.
+ */
+
+// Static imports for all locale message files
+import am from '../components/i18n/locales/am/messages.json';
+import ar from '../components/i18n/locales/ar/messages.json';
+import az from '../components/i18n/locales/az/messages.json';
+import bg from '../components/i18n/locales/bg/messages.json';
+import bn from '../components/i18n/locales/bn/messages.json';
+import bs from '../components/i18n/locales/bs/messages.json';
+import cs from '../components/i18n/locales/cs/messages.json';
+import da from '../components/i18n/locales/da/messages.json';
+import de from '../components/i18n/locales/de/messages.json';
+import dv from '../components/i18n/locales/dv/messages.json';
+import el from '../components/i18n/locales/el/messages.json';
+import en from '../components/i18n/locales/en/messages.json';
+import es from '../components/i18n/locales/es/messages.json';
+import et from '../components/i18n/locales/et/messages.json';
+import fa from '../components/i18n/locales/fa/messages.json';
+import fi from '../components/i18n/locales/fi/messages.json';
+import fil from '../components/i18n/locales/fil/messages.json';
+import fr from '../components/i18n/locales/fr/messages.json';
+import gu from '../components/i18n/locales/gu/messages.json';
+import he from '../components/i18n/locales/he/messages.json';
+import hi from '../components/i18n/locales/hi/messages.json';
+import hr from '../components/i18n/locales/hr/messages.json';
+import hu from '../components/i18n/locales/hu/messages.json';
+import hy from '../components/i18n/locales/hy/messages.json';
+import id from '../components/i18n/locales/id/messages.json';
+import it from '../components/i18n/locales/it/messages.json';
+import ja from '../components/i18n/locales/ja/messages.json';
+import ka from '../components/i18n/locales/ka/messages.json';
+import km from '../components/i18n/locales/km/messages.json';
+import kn from '../components/i18n/locales/kn/messages.json';
+import ko from '../components/i18n/locales/ko/messages.json';
+import ku from '../components/i18n/locales/ku/messages.json';
+import lo from '../components/i18n/locales/lo/messages.json';
+import lt from '../components/i18n/locales/lt/messages.json';
+import lv from '../components/i18n/locales/lv/messages.json';
+import mk from '../components/i18n/locales/mk/messages.json';
+import ml from '../components/i18n/locales/ml/messages.json';
+import mn from '../components/i18n/locales/mn/messages.json';
+import mr from '../components/i18n/locales/mr/messages.json';
+import ms from '../components/i18n/locales/ms/messages.json';
+import my from '../components/i18n/locales/my/messages.json';
+import ne from '../components/i18n/locales/ne/messages.json';
+import nl from '../components/i18n/locales/nl/messages.json';
+import no from '../components/i18n/locales/no/messages.json';
+import pa from '../components/i18n/locales/pa/messages.json';
+import pl from '../components/i18n/locales/pl/messages.json';
+import ps from '../components/i18n/locales/ps/messages.json';
+import pt from '../components/i18n/locales/pt/messages.json';
+import ro from '../components/i18n/locales/ro/messages.json';
+import ru from '../components/i18n/locales/ru/messages.json';
+import sd from '../components/i18n/locales/sd/messages.json';
+import si from '../components/i18n/locales/si/messages.json';
+import sk from '../components/i18n/locales/sk/messages.json';
+import sl from '../components/i18n/locales/sl/messages.json';
+import sq from '../components/i18n/locales/sq/messages.json';
+import sr from '../components/i18n/locales/sr/messages.json';
+import sv from '../components/i18n/locales/sv/messages.json';
+import sw from '../components/i18n/locales/sw/messages.json';
+import ta from '../components/i18n/locales/ta/messages.json';
+import te from '../components/i18n/locales/te/messages.json';
+import th from '../components/i18n/locales/th/messages.json';
+import tr from '../components/i18n/locales/tr/messages.json';
+import ug from '../components/i18n/locales/ug/messages.json';
+import uk from '../components/i18n/locales/uk/messages.json';
+import ur from '../components/i18n/locales/ur/messages.json';
+import vi from '../components/i18n/locales/vi/messages.json';
+import yi from '../components/i18n/locales/yi/messages.json';
+import zh from '../components/i18n/locales/zh/messages.json';
+
+/**
+ * All locale dictionaries as a record.
+ * Exporting this ensures the imports are not tree-shaken.
+ */
+export const allLocales = {
+  am,
+  ar,
+  az,
+  bg,
+  bn,
+  bs,
+  cs,
+  da,
+  de,
+  dv,
+  el,
+  en,
+  es,
+  et,
+  fa,
+  fi,
+  fil,
+  fr,
+  gu,
+  he,
+  hi,
+  hr,
+  hu,
+  hy,
+  id,
+  it,
+  ja,
+  ka,
+  km,
+  kn,
+  ko,
+  ku,
+  lo,
+  lt,
+  lv,
+  mk,
+  ml,
+  mn,
+  mr,
+  ms,
+  my,
+  ne,
+  nl,
+  no,
+  pa,
+  pl,
+  ps,
+  pt,
+  ro,
+  ru,
+  sd,
+  si,
+  sk,
+  sl,
+  sq,
+  sr,
+  sv,
+  sw,
+  ta,
+  te,
+  th,
+  tr,
+  ug,
+  uk,
+  ur,
+  vi,
+  yi,
+  zh,
+};
+
+export const localeCount = Object.keys(allLocales).length;

package/src/variants/blok-maximum.ts

@@ -0,0 +1,20 @@
+/**
+ * Maximum bundle variant - All tools + all 68 locales
+ *
+ * This entry point bundles everything: the Blok class, all bundled tools,
+ * and all 68 locale dictionaries (statically imported, not code-split).
+ *
+ * Use this to measure the maximum bundle size when everything is included.
+ *
+ * This file is NOT part of the public API - it's only used for bundle size measurement.
+ */
+
+// Re-export everything from the main blok entry
+export * from '../blok';
+
+// Import all locales to force them into the bundle
+// The allLocales export ensures these aren't tree-shaken
+import { allLocales, localeCount } from './all-locales';
+
+// Export to prevent tree-shaking
+export { allLocales, localeCount };

package/src/variants/blok-minimum.ts

@@ -0,0 +1,243 @@
+'use strict';
+
+/**
+ * Minimum bundle variant - Core editor only
+ *
+ * This entry point exports the Blok class WITHOUT bundled tools (Header, Paragraph, List).
+ * Use this to measure the minimum bundle size when users provide all tools externally.
+ *
+ * This file is NOT part of the public API - it's only used for bundle size measurement.
+ */
+
+import type { BlokConfig } from '../../types';
+import type { BlokModules } from '../types-internal/blok-modules';
+
+import '@babel/register';
+import '../components/polyfills';
+import { Core } from '../components/core';
+import { getBlokVersion, isObject, isFunction } from '../components/utils';
+import { destroy as destroyTooltip } from '../components/utils/tooltip';
+import { DATA_ATTR } from '../components/constants/data-attributes';
+
+export const version = getBlokVersion();
+export { DATA_ATTR };
+
+/**
+ * Blok - Minimum bundle (no bundled tools)
+ */
+class Blok {
+  private readonly initialConfiguration: BlokConfig | string | undefined;
+  public isReady: Promise<void>;
+  public destroy: () => void;
+
+  public static get version(): string {
+    return getBlokVersion();
+  }
+
+  public static DATA_ATTR = DATA_ATTR;
+
+  constructor(configuration?: BlokConfig | string) {
+    this.initialConfiguration = isObject(configuration)
+      ? { ...configuration }
+      : configuration;
+
+    const onReady =
+      isObject(configuration) && isFunction(configuration.onReady)
+        ? configuration.onReady
+        : () => {};
+
+    const blok = new Core(configuration);
+
+    this.destroy = (): void => {};
+
+    this.isReady = blok.isReady.then(() => {
+      this.exportAPI(blok);
+      onReady();
+    });
+  }
+
+  public exportAPI(blok: Core): void {
+    const fieldsToExport = ['configuration'];
+    const destroy = (): void => {
+      Object.values(blok.moduleInstances).forEach((moduleInstance) => {
+        if (moduleInstance === undefined || moduleInstance === null) {
+          return;
+        }
+
+        if (
+          isFunction((moduleInstance as { destroy?: () => void }).destroy)
+        ) {
+          (moduleInstance as { destroy: () => void }).destroy();
+        }
+
+        const listeners = (
+          moduleInstance as { listeners?: { removeAll?: () => void } }
+        ).listeners;
+
+        if (listeners && isFunction(listeners.removeAll)) {
+          listeners.removeAll();
+        }
+      });
+
+      destroyTooltip();
+
+      for (const field in this) {
+        if (Object.prototype.hasOwnProperty.call(this, field)) {
+          delete (this as Record<string, unknown>)[field];
+        }
+      }
+
+      Object.setPrototypeOf(this, null);
+    };
+
+    fieldsToExport.forEach((field) => {
+      if (field !== 'configuration') {
+        (this as Record<string, unknown>)[field] = (
+          blok as unknown as Record<string, unknown>
+        )[field];
+
+        return;
+      }
+
+      const coreConfiguration = (
+        blok as unknown as { configuration?: BlokConfig | string | undefined }
+      ).configuration;
+      const configurationToExport = isObject(this.initialConfiguration)
+        ? this.initialConfiguration
+        : (coreConfiguration ?? this.initialConfiguration);
+
+      if (configurationToExport === undefined) {
+        return;
+      }
+
+      (this as Record<string, unknown>)[field] = configurationToExport as
+        | BlokConfig
+        | string;
+    });
+
+    this.destroy = destroy;
+
+    const apiMethods = blok.moduleInstances.API.methods;
+    const eventsDispatcherApi =
+      blok.moduleInstances.EventsAPI?.methods ?? apiMethods.events;
+
+    if (eventsDispatcherApi !== undefined) {
+      const defineDispatcher = (target: object): void => {
+        if (!Object.prototype.hasOwnProperty.call(target, 'eventsDispatcher')) {
+          Object.defineProperty(target, 'eventsDispatcher', {
+            value: eventsDispatcherApi,
+            configurable: true,
+            enumerable: true,
+            writable: false,
+          });
+        }
+      };
+
+      defineDispatcher(apiMethods);
+      defineDispatcher(this as Record<string, unknown>);
+    }
+
+    if (Object.getPrototypeOf(apiMethods) !== Blok.prototype) {
+      Object.setPrototypeOf(apiMethods, Blok.prototype);
+    }
+
+    Object.setPrototypeOf(this, apiMethods);
+
+    const moduleAliases = Object.create(null) as Record<string, unknown>;
+    const moduleInstances = blok.moduleInstances as Partial<BlokModules>;
+    const moduleInstancesRecord = moduleInstances as unknown as Record<
+      string,
+      unknown
+    >;
+
+    const getAliasName = (name: string): string =>
+      /^[A-Z]+$/.test(name)
+        ? name.toLowerCase()
+        : name.charAt(0).toLowerCase() + name.slice(1);
+
+    Object.keys(moduleInstancesRecord).forEach((name) => {
+      const alias = getAliasName(name);
+
+      Object.defineProperty(moduleAliases, alias, {
+        configurable: true,
+        enumerable: true,
+        get: () => moduleInstancesRecord[name],
+      });
+    });
+
+    type ToolbarModuleWithSettings = {
+      blockSettings?: unknown;
+      inlineToolbar?: unknown;
+    };
+
+    const toolbarModule = moduleInstances.Toolbar as unknown as
+      | ToolbarModuleWithSettings
+      | undefined;
+    const blockSettingsModule = moduleInstances.BlockSettings;
+
+    if (
+      toolbarModule !== undefined &&
+      blockSettingsModule !== undefined &&
+      toolbarModule.blockSettings === undefined
+    ) {
+      toolbarModule.blockSettings = blockSettingsModule;
+    }
+
+    const inlineToolbarModule = moduleInstances.InlineToolbar;
+
+    if (
+      toolbarModule !== undefined &&
+      inlineToolbarModule !== undefined &&
+      toolbarModule.inlineToolbar === undefined
+    ) {
+      toolbarModule.inlineToolbar = inlineToolbarModule;
+    }
+
+    Object.defineProperty(this, 'module', {
+      value: moduleAliases,
+      configurable: true,
+      enumerable: false,
+      writable: false,
+    });
+
+    delete (this as Partial<Blok>).exportAPI;
+
+    const shorthands = {
+      blocks: {
+        clear: 'clear',
+        render: 'render',
+      },
+      caret: {
+        focus: 'focus',
+      },
+      events: {
+        on: 'on',
+        off: 'off',
+        emit: 'emit',
+      },
+      saver: {
+        save: 'save',
+      },
+    };
+
+    type API = {
+      blocks: Record<string, unknown>;
+      caret: Record<string, unknown>;
+      events: Record<string, unknown>;
+      saver: Record<string, unknown>;
+    };
+
+    Object.entries(shorthands).forEach(([key, methods]) => {
+      Object.entries(methods).forEach(([name, alias]) => {
+        const apiKey = key as keyof API;
+        const apiMethodGroup = blok.moduleInstances.API.methods[
+          apiKey
+        ] as unknown as Record<string, unknown>;
+
+        (this as Record<string, unknown>)[alias] = apiMethodGroup[name];
+      });
+    });
+  }
+}
+
+export { Blok };

package/types/api/blocks.d.ts

@@ -32,7 +32,7 @@ export interface Blocks {
    * Removes current Block
    * @param {number} index - index of a block to delete
    */
-  delete(index?: number): void;
+  delete(index?: number): Promise<void>;
 
   /**
    * Moves a block to a new index
@@ -133,4 +133,12 @@ export interface Blocks {
    * @throws Error if conversion is not possible
    */
   convert(id: string, newType: string, dataOverrides?: BlockToolData): Promise<BlockAPI>;
+
+  /**
+   * Stops mutation watching on a block at the specified index.
+   * This is used to prevent spurious block-changed events during block replacement.
+   *
+   * @param index - index of the block to stop watching
+   */
+  stopBlockMutationWatching(index: number): void;
 }

package/types/api/history.d.ts

@@ -30,4 +30,11 @@ export interface History {
    * Clears the history stacks, removing all undo/redo history
    */
   clear(): void;
+
+  /**
+   * Captures the initial document state for undo/redo
+   * Typically called after the editor is fully initialized
+   * @returns Promise that resolves when the initial state is captured
+   */
+  captureInitialState(): Promise<void>;
 }

package/types/api/i18n.d.ts

@@ -1,11 +1,30 @@
 /**
- * Describes Blok`s I18n API
+ * Describes Blok's I18n API for tools
  */
 export interface I18n {
   /**
-   * Perform translation with automatically added namespace like `tools.${toolName}` or `blockTunes.${tuneName}`
+   * Translate a key from the global dictionary.
+   * Keys should be fully qualified (e.g., 'tools.link.addLink', 'blockSettings.delete').
    *
-   * @param dictKey - what to translate
+   * @param dictKey - Full translation key to look up
+   * @returns Translated string, or the key itself if translation is missing
    */
   t(dictKey: string): string;
+
+  /**
+   * Check if a translation exists for the given key.
+   *
+   * @param dictKey - Full translation key to check
+   * @returns True if translation exists, false otherwise
+   */
+  has(dictKey: string): boolean;
+
+  /**
+   * Get the English translation for a key.
+   * Used for multilingual search - always searches against English terms.
+   *
+   * @param key - Translation key (e.g., 'toolNames.heading')
+   * @returns English translation string, or empty string if not found
+   */
+  getEnglishTranslation(key: string): string;
 }

package/types/api/selection.d.ts

@@ -27,6 +27,12 @@ export interface Selection {
    */
   removeFakeBackground(): void;
 
+  /**
+   * Clears all fake background state - both DOM elements and internal flags
+   * This is useful for cleanup after undo/redo operations or when the selection context has been lost
+   */
+  clearFakeBackground(): void;
+
   /**
    * Save selection range.
    * Allows to save selection to be able to temporally move focus away.

package/types/api/styles.d.ts

@@ -1,10 +1,23 @@
+/**
+ * Style class names for tool styling.
+ * These are single CSS class names that can be safely used with element.classList.add().
+ * The actual styles are defined using Tailwind's @apply directive in the CSS.
+ *
+ * @example
+ * // Add styles to an element
+ * element.classList.add(api.styles.block);
+ *
+ * // Combine with other classes using tailwind-merge
+ * import { twMerge } from '@jackuait/blok/utils/tw';
+ * element.className = twMerge(api.styles.block, 'my-4 bg-gray-100');
+ */
 export interface Styles {
   /**
    * Base block styles - applied to block tool wrappers.
    * Provides vertical padding for consistent block spacing.
    * Includes placeholder styling via pseudo-element.
    *
-   * @example 'py-[theme(spacing.block-padding-vertical)] px-0 [&::-webkit-input-placeholder]:!leading-normal'
+   * @example 'blok-block'
    */
   block: string;
 
@@ -12,7 +25,7 @@ export interface Styles {
    * Styles for Inline Toolbar button.
    * Provides flexbox centering, transparent background, and proper sizing.
    *
-   * @example 'flex justify-center items-center border-0 rounded h-full p-0 w-7 bg-transparent cursor-pointer'
+   * @example 'blok-inline-tool-button'
    */
   inlineToolButton: string;
 
@@ -20,7 +33,7 @@ export interface Styles {
    * Styles for active Inline Toolbar button.
    * Apply alongside inlineToolButton when the tool is active.
    *
-   * @example 'bg-icon-active-bg text-icon-active-text'
+   * @example 'blok-inline-tool-button--active'
    */
   inlineToolButtonActive: string;
 
@@ -28,7 +41,7 @@ export interface Styles {
    * Styles for input elements.
    * Provides full width, border, padding, shadow, and Firefox placeholder workaround.
    *
-   * @example 'w-full rounded-[3px] border border-line-gray px-3 py-2.5 outline-none shadow-input'
+   * @example 'blok-input'
    */
   input: string;
 
@@ -36,7 +49,7 @@ export interface Styles {
    * Loader styles for loading states.
    * Provides relative positioning, border, and spinning animation.
    *
-   * @example 'relative border border-line-gray before:animate-rotation'
+   * @example 'blok-loader'
    */
   loader: string;
 
@@ -45,7 +58,7 @@ export interface Styles {
    * Provides flexbox centering, transparent background, minimum sizing,
    * mobile responsive sizing, and hover states.
    *
-   * @example 'inline-flex items-center justify-center rounded-[3px] cursor-pointer'
+   * @example 'blok-settings-button'
    */
   settingsButton: string;
 
@@ -53,7 +66,7 @@ export interface Styles {
    * Styles for active Settings box buttons.
    * Apply alongside settingsButton when the button is active.
    *
-   * @example 'text-active-icon'
+   * @example 'blok-settings-button--active'
    */
   settingsButtonActive: string;
 
@@ -61,7 +74,7 @@ export interface Styles {
    * Styles for focused Settings box buttons.
    * Apply alongside settingsButton when the button has focus.
    *
-   * @example 'shadow-button-focused bg-item-focus-bg'
+   * @example 'blok-settings-button--focused'
    */
   settingsButtonFocused: string;
 
@@ -69,7 +82,7 @@ export interface Styles {
    * Styles for focused Settings box buttons with animation.
    * Apply alongside settingsButton and settingsButtonFocused for click animation.
    *
-   * @example 'animate-button-clicked'
+   * @example 'blok-settings-button--focused-animated'
    */
   settingsButtonFocusedAnimated: string;
 
@@ -77,7 +90,7 @@ export interface Styles {
    * Styles for general buttons.
    * Provides padding, border, background, shadow, hover states, and SVG styling.
    *
-   * @example 'p-[13px] rounded-[3px] border border-line-gray text-[14.9px] bg-white'
+   * @example 'blok-button'
    */
   button: string;
 }

package/types/configs/blok-config.d.ts

@@ -4,6 +4,14 @@ import {SanitizerConfig} from './sanitizer-config';
 import {I18nConfig} from './i18n-config';
 import { BlockMutationEvent } from '../events/block';
 
+/**
+ * Data model format for input/output
+ * - 'legacy': Use nested items structure (e.g., List items[] with nested items[])
+ * - 'hierarchical': Use flat blocks with parent/content references (Notion-like)
+ * - 'auto': Auto-detect input format and preserve it on output (default)
+ */
+export type DataModelFormat = 'legacy' | 'hierarchical' | 'auto';
+
 export interface BlokConfig {
   /**
    * Element where Blok will be appended
@@ -22,6 +30,19 @@ export interface BlokConfig {
    */
   defaultBlock?: string;
 
+  /**
+   * Data model format for input/output.
+   * - 'legacy': Always use nested items structure (e.g., List items[] with nested items[])
+   * - 'hierarchical': Always use flat blocks with parent/content references (Notion-like)
+   * - 'auto': Auto-detect input format and preserve it on output (default)
+   *
+   * With 'auto', existing articles using legacy format will continue to work unchanged,
+   * while new hierarchical data will be preserved as-is.
+   *
+   * @default 'auto'
+   */
+  dataModel?: DataModelFormat;
+
 
 
   /**
@@ -52,6 +73,14 @@ export interface BlokConfig {
    */
   historyDebounceTime?: number;
 
+  /**
+   * Enable document-level undo/redo shortcuts.
+   * When true, Cmd+Z / Ctrl+Z and Cmd+Shift+Z / Ctrl+Shift+Z work even when
+   * the editor is not focused (e.g., after dragging a block).
+   * @default true
+   */
+  globalUndoRedo?: boolean;
+
   /**
    * Map of Tools to use
    */