@jackuait/blok 0.4.1 → 0.4.2

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

package/types/api/i18n.d.ts

@@ -1,11 +1,13 @@
 /**
- * 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;
 }

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

@@ -94,8 +94,3 @@ export interface Styles {
    */
   button: string;
 }
-
-/**
- * @deprecated Use Styles instead
- */
-export type StyleClasses = Styles;

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;
+
 
 
   /**

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

@@ -3,14 +3,64 @@
  */
 import { I18nDictionary } from './i18n-dictionary';
 
+/**
+ * Supported locale codes that have built-in translations.
+ *
+ * When adding a new locale:
+ * 1. Add the code to this union type
+ * 2. Add the code to ALL_LOCALE_CODES in src/components/i18n/locales/index.ts
+ * 3. Add the importer to localeImporters in the same file
+ * 4. Create the messages.json file in src/components/i18n/locales/{code}/
+ *
+ * TypeScript will error if localeImporters is missing any code from this type.
+ */
+export type SupportedLocale = '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';
+
+/**
+ * Configuration for a single locale including its dictionary and text direction.
+ * This is the single source of truth for locale configuration shape.
+ */
+export interface LocaleConfig {
+  /** Translation dictionary mapping keys to translated strings */
+  dictionary: I18nDictionary;
+  /** Text direction for the locale */
+  direction: 'ltr' | 'rtl';
+}
+
+/**
+ * Registry of locale configurations.
+ */
+export type LocaleRegistry = Partial<Record<SupportedLocale, LocaleConfig>>;
+
+/**
+ * I18n configuration options.
+ *
+ * All 68 supported locales are available for lazy loading by default.
+ *
+ * @see README.md#localization for usage examples
+ */
 export interface I18nConfig {
   /**
-   * Dictionary used for translation
+   * Active locale code ('en', 'ru', etc.) or 'auto' to detect from browser.
+   * All 68 locales are supported and will be loaded on-demand.
+   * @default 'auto'
+   */
+  locale?: SupportedLocale | 'auto';
+
+  /**
+   * Custom dictionary that overrides locale-based translations.
    */
   messages?: I18nDictionary;
 
   /**
-   * Text direction. If not set, uses ltr
+   * Text direction. Auto-determined by locale if not set.
+   * @default 'ltr'
    */
   direction?: 'ltr' | 'rtl';
+
+  /**
+   * Fallback locale when detection fails or requested locale unavailable.
+   * @default 'en'
+   */
+  defaultLocale?: SupportedLocale;
 }

package/types/configs/i18n-dictionary.d.ts

@@ -1,93 +1,19 @@
 /**
- * Structure of the i18n dictionary
+ * Structure of the i18n dictionary - flat key-value pairs
+ *
+ * Keys use dot notation to represent the translation path:
+ * - "toolNames.text" - Tool name translations
+ * - "tools.link.addLink" - Tool-specific translations
+ * - "blockSettings.delete" - Block settings translations
+ * - "popover.search" - Popover component translations
+ * - "a11y.dragHandle" - Accessibility translations
+ *
+ * Example:
+ * {
+ *   "toolNames.text": "Текст",
+ *   "tools.link.addLink": "Добавить ссылку",
+ *   "popover.search": "Поиск"
+ * }
  */
-export interface I18nDictionary {
-  /**
-   * Section for translation Tool Names: both block and inline tools
-   * Example:
-   *  "toolNames": {
-   *     "Text": "Параграф",
-   *     "Heading": "Заголовок",
-   *     "List": "Список",
-   *     ...
-   *  },
-   */
-  toolNames?: Dictionary;
-
-  /**
-   * Section for passing translations to the external tools classes
-   * The first-level keys of this object should be equal of keys ot the 'tools' property of BlokConfig
-   * Includes internal tools: "paragraph", "stub"
-   *
-   * Example:
-   *  "tools": {
-   *     "warning": {
-   *       "Title": "Название",
-   *       "Message": "Сообщение",
-   *     },
-   *     "link": {
-   *        "Add a link": "Вставьте ссылку"
-   *     },
-   *  },
-   */
-  tools?: Dictionary;
-
-  /**
-   * Section allows to translate Block Tunes
-   * The first-level keys of this object should be equal of 'name' ot the 'tools.<toolName>.tunes' property of BlokConfig
-   * Including some internal block-tunes: "delete", "moveUp", "moveDown
-   *
-   * Example:
-   * "blockTunes": {
-   *   "delete": {
-   *     "Delete": "Удалить"
-   *   },
-   *   "moveUp": {
-   *     "Move up": "Переместить вверх"
-   *   },
-   *   "moveDown": {
-   *     "Move down": "Переместить вниз"
-   *   }
-   * },
-   */
-  blockTunes?: Dictionary;
-
-  /**
-   * Translation of internal UI components of the blok.js core
-   */
-  ui?: Dictionary;
-}
-
-/**
- * Represent item of the I18nDictionary config
- */
-export interface Dictionary {
-  /**
-   * The keys of the object can represent two entities:
-   *  1. Dictionary key usually is an original string from default locale, like "Convert to"
-   *  2. Sub-namespace section, like "toolbar.converter.<...>"
-   *
-   *  Example of 1:
-   *  toolbox: {
-   *    "Add": "Добавить",
-   *  }
-   *
-   *  Example of 2:
-   *  ui: {
-   *    toolbar: {
-   *      toolbox: {    <-- Example of 1
-   *        "Add": "Добавить"
-   *      }
-   *    }
-   *  }
-   */
-  [key: string]: DictValue;
-}
-
-/**
- * The value of the dictionary can be:
- *  - other dictionary
- *  - result translate string
- */
-export type DictValue = {[key: string]: Dictionary | string} | string;
+export type I18nDictionary = Record<string, string>;