@jackuait/blok 0.4.1 → 0.4.2

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,31 +143,19 @@ export interface API {
   ui: Ui;
 }
 
-import { HeaderConstructable } from './tools/header';
-import { ParagraphConstructable } from './tools/paragraph';
-import { ListConstructable } from './tools/list';
+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;
-
-  /**
-   * Paragraph tool bundled with Blok
-   */
-  public static Paragraph: ParagraphConstructable;
-
-  /**
-   * List tool bundled with Blok
-   */
-  public static List: ListConstructable;
+export const version: string;
 
+/**
+ * Main Blok class
+ */
+export class Blok {
   public isReady: Promise<void>;
 
   public blocks: Blocks;
@@ -227,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/list.d.ts

@@ -6,26 +6,20 @@ import { MenuConfig } from './menu-config';
  */
 export type ListStyle = 'unordered' | 'ordered' | 'checklist';
 
-/**
- * Single list item data
- */
-export interface ListItem {
-  /** Item content (can include HTML) */
-  content: string;
-  /** Checked state for checklist items */
-  checked?: boolean;
-  /** Nested items for indentation */
-  items?: ListItem[];
-}
-
 /**
  * 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;
-  /** Array of list items */
-  items: ListItem[];
+  /** 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;
 }
 
 /**
@@ -34,13 +28,26 @@ export interface ListData extends BlockToolData {
 export interface ListConfig {
   /** Default list style */
   defaultStyle?: ListStyle;
-  /** Available list styles */
+  /**
+   * 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 */
+  /**
+   * 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 */
+  /**
+   * 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 */
+  /**
+   * Custom font size for list items.
+   * Accepts any valid CSS font-size value (px, rem, em, etc.)
+   */
   itemSize?: string;
 }
 

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

@@ -12,10 +12,17 @@ export type ToolboxConfig = ToolboxConfigEntry | ToolboxConfigEntry[];
  */
 export interface ToolboxConfigEntry {
   /**
-   * Tool title for Toolbox
+   * Tool title for Toolbox (human-readable fallback)
    */
   title?: string;
 
+  /**
+   * Translation key for the title (e.g., 'text', 'heading', 'bulletedList').
+   * Used to look up translations in the toolNames.* namespace.
+   * If provided, the translated value is used; otherwise falls back to title.
+   */
+  titleKey?: string;
+
   /**
    * HTML string with an icon for Toolbox
    */

package/types/tools/tool.d.ts

@@ -51,6 +51,12 @@ export interface BaseToolConstructable {
    */
   title?: string;
 
+  /**
+   * Translation key for the tool title (e.g., 'bold', 'italic', 'link').
+   * Used to look up translations in the toolNames.* namespace.
+   */
+  titleKey?: string;
+
   /**
    * Tool`s prepare method. Can be async
    * @param data

package/types/tools-entry.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Type definitions for @jackuait/blok/tools entry point
+ * Re-exports all built-in tools for easy importing
+ */
+
+import { HeaderConstructable, HeaderData, HeaderConfig } from './tools/header';
+import { ParagraphConstructable, ParagraphData, ParagraphConfig } from './tools/paragraph';
+import { ListConstructable, ListData, ListConfig, ListStyle } from './tools/list';
+import { InlineToolConstructable } from './tools/inline-tool';
+import { BlockTuneConstructable } from './block-tunes';
+import { ToolSettings } from './tools';
+
+// Block tools
+export const Paragraph: ParagraphConstructable;
+export const Header: HeaderConstructable;
+export const List: ListConstructable;
+
+// Re-export data and config types for convenience
+export { HeaderData, HeaderConfig } from './tools/header';
+export { ParagraphData, ParagraphConfig } from './tools/paragraph';
+export { ListData, ListConfig, ListStyle } from './tools/list';
+
+// Inline tools
+export const Bold: InlineToolConstructable;
+export const Italic: InlineToolConstructable;
+export const Link: InlineToolConstructable;
+export const Convert: InlineToolConstructable;
+
+// Block tunes
+export const Delete: BlockTuneConstructable;
+
+/**
+ * Default block tools configuration
+ */
+export const defaultBlockTools: {
+  readonly paragraph: { readonly inlineToolbar: true; readonly config: { readonly preserveBlank: true } };
+  readonly header: { readonly inlineToolbar: true };
+  readonly list: { readonly inlineToolbar: true };
+};
+
+/**
+ * Default inline tools configuration
+ */
+export const defaultInlineTools: {
+  readonly bold: {};
+  readonly italic: {};
+  readonly link: {};
+  readonly convertTo: {};
+};

package/types/utils/popover/popover-item.d.ts

@@ -134,11 +134,6 @@ export interface PopoverItemDefaultBaseParams {
    */
   title?: string;
 
-  /**
-   * @deprecated Use title instead
-   */
-  label?: string;
-
   /**
    * Item icon to be appeared near a title
    */