@jackuait/blok 0.4.1-beta.4 → 0.4.1-beta.6

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,169 @@
+/**
+ * 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 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

@@ -143,19 +143,19 @@ 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;
@@ -215,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;

package/types/tools/list.d.ts

@@ -0,0 +1,91 @@
+import { BlockTool, BlockToolConstructable, BlockToolConstructorOptions, BlockToolData } from './block-tool';
+import { MenuConfig } from './menu-config';
+
+/**
+ * List styles enum
+ */
+export type ListStyle = 'unordered' | 'ordered' | 'checklist';
+
+/**
+ * List Tool's input and output data format
+ */
+export interface ListData extends BlockToolData {
+  /** Item text content (can include HTML) */
+  text: string;
+  /** List style: unordered, ordered, or checklist */
+  style: ListStyle;
+  /** Checked state for checklist items */
+  checked?: boolean;
+  /** Starting number for ordered lists (only applies to root items) */
+  start?: number;
+  /** Nesting depth level (0 = root, 1 = first indent, etc.) */
+  depth?: number;
+}
+
+/**
+ * List Tool's configuration
+ */
+export interface ListConfig {
+  /** Default list style */
+  defaultStyle?: ListStyle;
+  /**
+   * Available list styles for the settings menu.
+   * When specified, only these styles will be available in the block settings dropdown.
+   */
+  styles?: ListStyle[];
+  /**
+   * List styles to show in the toolbox.
+   * When specified, only these list types will appear as separate entries in the toolbox.
+   * If not specified, all list types (unordered, ordered, checklist) will be shown.
+   */
+  toolboxStyles?: ListStyle[];
+  /**
+   * Custom color for list items.
+   * Accepts any valid CSS color value (hex, rgb, hsl, named colors, etc.)
+   */
+  itemColor?: string;
+  /**
+   * Custom font size for list items.
+   * Accepts any valid CSS font-size value (px, rem, em, etc.)
+   */
+  itemSize?: string;
+}
+
+/**
+ * List Tool for the Blok Editor
+ * Provides Ordered, Unordered, and Checklist Blocks
+ */
+export interface List extends BlockTool {
+  /**
+   * Return Tool's view
+   */
+  render(): HTMLElement;
+
+  /**
+   * Returns list block tunes config
+   */
+  renderSettings(): MenuConfig;
+
+  /**
+   * Method that specified how to merge two List blocks.
+   * Called by Editor by backspace at the beginning of the Block
+   */
+  merge(data: ListData): void;
+
+  /**
+   * Validate List block data
+   */
+  validate(blockData: ListData): boolean;
+
+  /**
+   * Extract Tool's data from the view
+   */
+  save(): ListData;
+}
+
+/**
+ * List Tool constructor
+ */
+export interface ListConstructable extends BlockToolConstructable {
+  new(config: BlockToolConstructorOptions<ListData, ListConfig>): List;
+}