@jackuait/blok 0.4.1-beta.0 → 0.4.1-beta.11

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>;
 

package/types/data-attributes.d.ts

@@ -0,0 +1,170 @@
+/**
+ * Centralized data attributes used across the Blok editor.
+ * This is the single source of truth for all data-blok-* attributes.
+ *
+ * Access via Blok.DATA_ATTR
+ */
+export const DATA_ATTR: {
+  // Core Element Identifiers
+  readonly interface: 'data-blok-interface';
+  readonly element: 'data-blok-element';
+  readonly elementContent: 'data-blok-element-content';
+  readonly editor: 'data-blok-editor';
+  readonly redactor: 'data-blok-redactor';
+
+  // Block Identifiers
+  readonly id: 'data-blok-id';
+  readonly component: 'data-blok-component';
+  readonly tool: 'data-blok-tool';
+  readonly depth: 'data-blok-depth';
+
+  // Global States
+  readonly hidden: 'data-blok-hidden';
+  readonly disabled: 'data-blok-disabled';
+  readonly focused: 'data-blok-focused';
+  readonly selected: 'data-blok-selected';
+  readonly stretched: 'data-blok-stretched';
+  readonly empty: 'data-blok-empty';
+
+  // Editor Modes
+  readonly narrow: 'data-blok-narrow';
+  readonly rtl: 'data-blok-rtl';
+
+  // Drag and Drop
+  readonly dragging: 'data-blok-dragging';
+  readonly draggingMulti: 'data-blok-dragging-multi';
+  readonly duplicating: 'data-blok-duplicating';
+  readonly dragHandle: 'data-blok-drag-handle';
+
+  // Toolbar
+  readonly toolbar: 'data-blok-toolbar';
+  readonly settingsToggler: 'data-blok-settings-toggler';
+  readonly toolboxOpened: 'data-blok-toolbox-opened';
+  readonly blockSettingsOpened: 'data-blok-block-settings-opened';
+  readonly opened: 'data-blok-opened';
+
+  // Popover Container
+  readonly popover: 'data-blok-popover';
+  readonly popoverContainer: 'data-blok-popover-container';
+  readonly popoverItems: 'data-blok-popover-items';
+  readonly popoverOverlay: 'data-blok-popover-overlay';
+  readonly popoverCustomContent: 'data-blok-popover-custom-content';
+  readonly popoverCustomClass: 'data-blok-popover-custom-class';
+  readonly popoverInline: 'data-blok-popover-inline';
+  readonly popoverOpened: 'data-blok-popover-opened';
+  readonly popoverOpenTop: 'data-blok-popover-open-top';
+  readonly popoverOpenLeft: 'data-blok-popover-open-left';
+
+  // Popover Nesting
+  readonly nested: 'data-blok-nested';
+  readonly nestedLevel: 'data-blok-nested-level';
+
+  // Popover Header
+  readonly popoverHeader: 'data-blok-popover-header';
+  readonly popoverHeaderText: 'data-blok-popover-header-text';
+  readonly popoverHeaderBackButton: 'data-blok-popover-header-back-button';
+
+  // Popover Items
+  readonly popoverItem: 'data-blok-popover-item';
+  readonly popoverItemIcon: 'data-blok-popover-item-icon';
+  readonly popoverItemIconChevronRight: 'data-blok-popover-item-icon-chevron-right';
+  readonly popoverItemTitle: 'data-blok-popover-item-title';
+  readonly popoverItemSecondaryTitle: 'data-blok-popover-item-secondary-title';
+  readonly popoverItemActive: 'data-blok-popover-item-active';
+  readonly popoverItemConfirmation: 'data-blok-popover-item-confirmation';
+  readonly popoverItemNoHover: 'data-blok-popover-item-no-hover';
+  readonly popoverItemNoFocus: 'data-blok-popover-item-no-focus';
+  readonly popoverItemWobble: 'data-blok-popover-item-wobble';
+  readonly popoverItemSeparator: 'data-blok-popover-item-separator';
+  readonly popoverItemSeparatorLine: 'data-blok-popover-item-separator-line';
+  readonly popoverItemHtml: 'data-blok-popover-item-html';
+  readonly hasChildren: 'data-blok-has-children';
+  readonly itemName: 'data-blok-item-name';
+  readonly nothingFoundDisplayed: 'data-blok-nothing-found-displayed';
+
+  // Overlay / Selection
+  readonly overlay: 'data-blok-overlay';
+  readonly overlayContainer: 'data-blok-overlay-container';
+  readonly overlayRectangle: 'data-blok-overlay-rectangle';
+  readonly overlayHidden: 'data-blok-overlay-hidden';
+  readonly fakeCursor: 'data-blok-fake-cursor';
+  readonly fakeBackground: 'data-blok-fake-background';
+
+  // Scroll
+  readonly scrollZone: 'data-blok-scroll-zone';
+  readonly scrollLocked: 'data-blok-scroll-locked';
+  readonly scrollLockedHard: 'data-blok-scroll-locked-hard';
+
+  // Caret
+  readonly shadowCaret: 'data-blok-shadow-caret';
+
+  // Placeholders
+  readonly placeholder: 'data-blok-placeholder';
+  readonly placeholderActive: 'data-blok-placeholder-active';
+
+  // Mutation Tracking
+  readonly mutationFree: 'data-blok-mutation-free';
+
+  // Navigation
+  readonly navigationFocused: 'data-blok-navigation-focused';
+  readonly flipperNavigationTarget: 'data-blok-flipper-navigation-target';
+
+  // Inline Toolbar
+  readonly inlineToolbar: 'data-blok-inline-toolbar';
+
+  // Link Tool
+  readonly linkToolActive: 'data-blok-link-tool-active';
+  readonly linkToolUnlink: 'data-blok-link-tool-unlink';
+  readonly linkToolInputOpened: 'data-blok-link-tool-input-opened';
+
+  // Bold Tool
+  readonly boldCollapsedLength: 'data-blok-bold-collapsed-length';
+  readonly boldCollapsedActive: 'data-blok-bold-collapsed-active';
+  readonly boldPrevLength: 'data-blok-bold-prev-length';
+  readonly boldLeadingWs: 'data-blok-bold-leading-ws';
+  readonly boldMarker: 'data-blok-bold-marker';
+
+  // Tooltip
+  readonly shown: 'data-blok-shown';
+  readonly placement: 'data-blok-placement';
+
+  // Notifier
+  readonly bounceIn: 'data-blok-bounce-in';
+
+  // Announcer (Accessibility)
+  readonly announcer: 'data-blok-announcer';
+
+  // Stub Block
+  readonly stub: 'data-blok-stub';
+  readonly stubInfo: 'data-blok-stub-info';
+  readonly stubTitle: 'data-blok-stub-title';
+  readonly stubSubtitle: 'data-blok-stub-subtitle';
+
+  // Testing
+  readonly testid: 'data-blok-testid';
+  readonly forceHover: 'data-blok-force-hover';
+};
+
+/**
+ * Type for DATA_ATTR keys
+ */
+export type DataAttrKey = keyof typeof DATA_ATTR;
+
+/**
+ * Type for DATA_ATTR values
+ */
+export type DataAttrValue = (typeof DATA_ATTR)[DataAttrKey];
+
+/**
+ * Helper function to create a CSS selector from an attribute
+ *
+ * @param attr - The data attribute name from DATA_ATTR
+ * @param value - Optional value for the attribute (defaults to presence selector)
+ * @returns CSS selector string
+ *
+ * @example
+ * createSelector(DATA_ATTR.element) // '[data-blok-element]'
+ * createSelector(DATA_ATTR.selected, true) // '[data-blok-selected="true"]'
+ * createSelector(DATA_ATTR.tool, 'paragraph') // '[data-blok-tool="paragraph"]'
+ */
+export const createSelector: (attr: DataAttrValue, value?: string | boolean) => string;

package/types/data-formats/output-data.d.ts

@@ -26,6 +26,21 @@ export interface OutputBlockData<Type extends string = string, Data extends obje
    * Block Tunes data
    */
   tunes?: {[name: string]: BlockTuneData};
+
+  /**
+   * Parent block id for hierarchical/nested blocks (Notion-like flat-with-references model).
+   * When present, this block is a child of the block with the specified id.
+   * Omit for root-level blocks.
+   */
+  parent?: BlockId;
+
+  /**
+   * Array of child block ids (Notion-like flat-with-references model).
+   * References blocks that are children of this block.
+   * The referenced blocks should have their `parent` field set to this block's id.
+   * Omit if block has no children.
+   */
+  content?: BlockId[];
 }
 
 export interface OutputData {

package/types/full.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Type definitions for @jackuait/blok/full entry point
+ * Full bundle with Blok core + all built-in tools
+ */
+
+// Re-export everything from core
+export { Blok, version, DATA_ATTR } from './index';
+
+// Re-export all types from core
+export * from './index';
+
+// Re-export all tools
+export {
+  Paragraph,
+  Header,
+  List,
+  Bold,
+  Italic,
+  Link,
+  Convert,
+  Delete,
+  defaultBlockTools,
+  defaultInlineTools,
+  HeaderData,
+  HeaderConfig,
+  ParagraphData,
+  ParagraphConfig,
+  ListData,
+  ListConfig,
+  ListStyle,
+} from './tools';
+
+import { ParagraphConstructable } from './tools/paragraph';
+import { HeaderConstructable } from './tools/header';
+import { ListConstructable } from './tools/list';
+import { InlineToolConstructable } from './tools/inline-tool';
+
+/**
+ * Default tools configuration matching pre-modularization behavior.
+ * Includes Paragraph, Header, and List with inline toolbar enabled.
+ */
+export const defaultTools: {
+  readonly paragraph: {
+    readonly class: ParagraphConstructable;
+    readonly inlineToolbar: true;
+    readonly config: { readonly preserveBlank: true };
+  };
+  readonly header: {
+    readonly class: HeaderConstructable;
+    readonly inlineToolbar: true;
+  };
+  readonly list: {
+    readonly class: ListConstructable;
+    readonly inlineToolbar: true;
+  };
+};
+
+/**
+ * All built-in tools including inline tools.
+ * For users who want every tool available.
+ */
+export const allTools: {
+  readonly paragraph: {
+    readonly class: ParagraphConstructable;
+    readonly inlineToolbar: true;
+    readonly config: { readonly preserveBlank: true };
+  };
+  readonly header: {
+    readonly class: HeaderConstructable;
+    readonly inlineToolbar: true;
+  };
+  readonly list: {
+    readonly class: ListConstructable;
+    readonly inlineToolbar: true;
+  };
+  readonly bold: { readonly class: InlineToolConstructable };
+  readonly italic: { readonly class: InlineToolConstructable };
+  readonly link: { readonly class: InlineToolConstructable };
+  readonly convertTo: { readonly class: InlineToolConstructable };
+};

package/types/index.d.ts

@@ -85,7 +85,26 @@ export * from './utils/popover';
 
 export { OutputData, OutputBlockData} from './data-formats/output-data';
 export { BlockId } from './data-formats/block-id';
-export { BlockAPI } from './api'
+export {
+  BlockAPI,
+  Blocks,
+  Caret,
+  Events,
+  History,
+  InlineToolbar,
+  Listeners,
+  Notifier,
+  ReadOnly,
+  Sanitizer,
+  Saver,
+  Selection,
+  Styles,
+  Toolbar,
+  Tooltip,
+  I18n,
+  Ui,
+  Tools,
+} from './api';
 export {
   BlockMutationType,
   BlockMutationEvent,
@@ -124,23 +143,24 @@ export interface API {
   ui: Ui;
 }
 
-import { HeaderConstructable } from './tools/header';
+import { DATA_ATTR, DataAttrKey, DataAttrValue, createSelector } from './data-attributes';
+
+export { DATA_ATTR, DataAttrKey, DataAttrValue, createSelector };
 
 /**
- * Main Blok class
+ * Blok version string
  */
-declare class Blok {
-  public static version: string;
-
-  /**
-   * Header tool bundled with Blok
-   */
-  public static Header: HeaderConstructable;
+export const version: string;
 
+/**
+ * Main Blok class
+ */
+export class Blok {
   public isReady: Promise<void>;
 
   public blocks: Blocks;
   public caret: Caret;
+  public history: History;
   public sanitizer: Sanitizer;
   public saver: Saver;
   public selection: Selection;
@@ -195,6 +215,3 @@ declare class Blok {
    */
   public destroy(): void;
 }
-
-export as namespace Blok;
-export default Blok;

package/types/locales.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Public entry point for locale imports.
+ * Only English is bundled by default - all 68 other locales are loaded on-demand.
+ * @see README.md#localization for usage examples
+ */
+
+import type { LocaleConfig, LocaleRegistry, SupportedLocale } from './configs/i18n-config';
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+/** Default locale code ('en') */
+export declare const DEFAULT_LOCALE: SupportedLocale;
+
+/** All supported locale codes (68 languages) - all available for lazy loading */
+export declare const ALL_LOCALE_CODES: readonly SupportedLocale[];
+
+// ============================================================================
+// English locale - always bundled (default/fallback)
+// ============================================================================
+
+export declare const enLocale: LocaleConfig;
+
+// ============================================================================
+// Lazy loading functions
+// ============================================================================
+
+/** Load a single locale on-demand */
+export declare const loadLocale: (code: SupportedLocale) => Promise<LocaleConfig>;
+
+/** Preload multiple locales */
+export declare const preloadLocales: (codes: readonly SupportedLocale[]) => Promise<void>;
+
+/** Build a registry from locale codes (async) */
+export declare const buildRegistry: (codes: readonly SupportedLocale[]) => Promise<LocaleRegistry>;
+
+/** Get a loaded locale synchronously (returns undefined if not loaded) */
+export declare const getLocaleSync: (code: SupportedLocale) => LocaleConfig | undefined;
+
+// ============================================================================
+// Utility functions
+// ============================================================================
+
+/** Get text direction for a locale code */
+export declare const getDirection: (code: SupportedLocale) => 'ltr' | 'rtl';
+
+/**
+ * Clear the locale cache.
+ * Primarily useful for testing to ensure test isolation.
+ * @internal
+ */
+export declare const clearLocaleCache: () => void;
+
+// ============================================================================
+// Re-export types
+// ============================================================================
+
+export type { LocaleConfig, LocaleRegistry, SupportedLocale };

package/types/tools/adapters/inline-tool-adapter.d.ts

@@ -7,4 +7,14 @@ interface InlineToolAdapter extends BaseToolAdapter<ToolType.Inline, InlineTool>
    * Constructs new InlineTool instance from constructable
    */
   create(): IInlineTool;
+
+  /**
+   * Returns the tool title
+   */
+  title: string;
+
+  /**
+   * Returns the translation key for the tool title
+   */
+  titleKey: string | undefined;
 }

package/types/tools/block-tool.d.ts

@@ -78,6 +78,15 @@ export interface BlockTool extends BaseTool {
    * Called after block was moved
    */
   moved?(event: MoveEvent): void;
+
+  /**
+   * Returns the horizontal offset of the content at the hovered element.
+   * Used by the toolbar to position itself closer to nested content (e.g., nested list items).
+   *
+   * @param hoveredElement - The element that is currently being hovered
+   * @returns Object with left offset in pixels, or undefined if no offset should be applied
+   */
+  getContentOffset?(hoveredElement: Element): { left: number } | undefined;
 }
 
 /**

package/types/tools/header.d.ts

@@ -11,6 +11,22 @@ export interface HeaderData extends BlockToolData {
   level: number;
 }
 
+/**
+ * Level-specific overrides for customization
+ */
+export interface HeaderLevelConfig {
+  /** Custom HTML tag to use (e.g., 'div', 'p', 'span') */
+  tag?: string;
+  /** Custom display name for this level */
+  name?: string;
+  /** Custom font size (e.g., '3em', '24px') */
+  size?: string;
+  /** Custom margin top (e.g., '20px', '1rem') */
+  marginTop?: string;
+  /** Custom margin bottom (e.g., '10px', '0.5rem') */
+  marginBottom?: string;
+}
+
 /**
  * Header Tool's configuration
  */
@@ -21,6 +37,8 @@ export interface HeaderConfig {
   levels?: number[];
   /** Default level */
   defaultLevel?: number;
+  /** Level-specific overrides keyed by level number (1-6) */
+  levelOverrides?: Record<number, HeaderLevelConfig>;
 }
 
 /**

package/types/tools/index.d.ts

@@ -12,6 +12,7 @@ export * from './paste-events';
 export * from './hook-events';
 export * from './menu-config';
 export * from './header';
+export * from './list';
 
 export type Tool = BlockTool | InlineTool | BlockTune;
 export type ToolConstructable = BlockToolConstructable | InlineToolConstructable | BlockTuneConstructable;