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

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

package/types/tools/paragraph.d.ts

@@ -0,0 +1,71 @@
+import { BlockTool, BlockToolConstructable, BlockToolConstructorOptions, BlockToolData } from './block-tool';
+
+/**
+ * Paragraph Tool's input and output data format
+ */
+export interface ParagraphData extends BlockToolData {
+  /** Paragraph's content. Can include HTML tags: <a><b><i> */
+  text: string;
+}
+
+/**
+ * Style overrides for paragraph customization
+ */
+export interface ParagraphStyleConfig {
+  /** Custom font size (e.g., '16px', '1rem') */
+  size?: string;
+  /** Custom line height (e.g., '1.6', '24px') */
+  lineHeight?: string;
+  /** Custom margin top (e.g., '10px', '0.5rem') */
+  marginTop?: string;
+  /** Custom margin bottom (e.g., '10px', '0.5rem') */
+  marginBottom?: string;
+}
+
+/**
+ * Paragraph Tool's configuration
+ */
+export interface ParagraphConfig {
+  /** Placeholder for the empty paragraph */
+  placeholder?: string;
+  /** Whether or not to keep blank paragraphs when saving editor data */
+  preserveBlank?: boolean;
+  /** Style overrides for paragraph customization */
+  styles?: ParagraphStyleConfig;
+  /** Custom icon SVG string for the toolbox */
+  icon?: string;
+}
+
+/**
+ * Paragraph Tool for the Blok Editor
+ * Provides Text Block
+ */
+export interface Paragraph extends BlockTool {
+  /**
+   * Return Tool's view
+   */
+  render(): HTMLDivElement;
+
+  /**
+   * Method that specified how to merge two Paragraph blocks.
+   * Called by Editor by backspace at the beginning of the Block
+   */
+  merge(data: ParagraphData): void;
+
+  /**
+   * Validate Paragraph block data
+   */
+  validate(savedData: ParagraphData): boolean;
+
+  /**
+   * Extract Tool's data from the view
+   */
+  save(toolsContent: HTMLDivElement): ParagraphData;
+}
+
+/**
+ * Paragraph Tool constructor
+ */
+export interface ParagraphConstructable extends BlockToolConstructable {
+  new(config: BlockToolConstructorOptions<ParagraphData, ParagraphConfig>): Paragraph;
+}

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

@@ -1,6 +1,12 @@
 import { ToolConfig } from './tool-config';
 import { ToolConstructable, BlockToolData, MenuConfig, MenuConfigItem } from './index';
 
+/**
+ * Permissive type for tool class - accepts any constructor.
+ * Runtime validation ensures the tool has required methods.
+ */
+export type ToolClass = new (...args: any[]) => any;
+
 /**
  * Tool may specify its toolbox configuration
  * It may include several entries as well
@@ -12,10 +18,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
    */
@@ -24,7 +37,28 @@ export interface ToolboxConfigEntry {
   /**
    * May contain overrides for tool default data
    */
-  data?: BlockToolData
+  data?: BlockToolData;
+
+  /**
+   * Unique name for the toolbox entry, used for data-blok-item-name attribute.
+   * If not provided, falls back to the tool name.
+   * Useful when a tool has multiple toolbox entries (e.g., list with ordered/unordered/checklist variants).
+   */
+  name?: string;
+
+  /**
+   * Additional search terms for the tool (e.g., ['h1', 'title', 'header']).
+   * Users can search by these aliases in addition to the displayed title.
+   * Terms are matched case-insensitively.
+   */
+  searchTerms?: string[];
+
+  /**
+   * Shortcut hint to display in the toolbox (e.g., '#', '##', '-', '1.', '[]').
+   * This is displayed as a secondary label next to the tool title.
+   * Unlike tool-level shortcuts, these are per-entry hints for tools with multiple variants.
+   */
+  shortcut?: string;
 }
 
 /**
@@ -35,9 +69,9 @@ export interface ToolboxConfigEntry {
 export interface ExternalToolSettings<Config extends object = any> {
 
   /**
-   * Tool's class
+   * Tool's class - accepts any constructor, validated at runtime
    */
-  class: ToolConstructable;
+  class: ToolConstructable | ToolClass;
 
   /**
    * User configuration object that will be passed to the Tool's constructor
@@ -66,6 +100,13 @@ export interface ExternalToolSettings<Config extends object = any> {
    * It will be hidden from Toolbox when false is specified.
    */
   toolbox?: ToolboxConfig | false;
+
+  /**
+   * Additional search terms for finding this tool in the toolbox.
+   * Merged with any searchTerms defined in the tool's toolbox config.
+   * Useful for adding locale-specific search terms.
+   */
+  searchTerms?: string[];
 }
 
 /**
@@ -74,6 +115,58 @@ export interface ExternalToolSettings<Config extends object = any> {
 export type InternalToolSettings<Config extends object = any> = Omit<ExternalToolSettings<Config>, 'class'> & Partial<Pick<ExternalToolSettings<Config>, 'class'>>;
 
 /**
- * Union of external and internal Tools settings
+ * Keys that Blok extracts from tool settings (not passed to tool constructor)
+ */
+export type BlokToolSettingsKeys = 'class' | 'inlineToolbar' | 'tunes' | 'shortcut' | 'toolbox' | 'config';
+
+/**
+ * Flat tool settings - tool-specific options at top level.
+ * Blok extracts known keys and passes the rest as `config` to the tool.
+ */
+export interface FlatToolSettings<Config extends object = any> {
+  /**
+   * Tool's class
+   */
+  class: ToolConstructable | ToolClass;
+
+  /**
+   * Is need to show Inline Toolbar.
+   * Defaults to true for block tools.
+   */
+  inlineToolbar?: boolean | string[];
+
+  /**
+   * BlockTunes for Tool
+   */
+  tunes?: boolean | string[];
+
+  /**
+   * Define shortcut that will render Tool
+   */
+  shortcut?: string;
+
+  /**
+   * Tool's Toolbox settings
+   */
+  toolbox?: ToolboxConfig | false;
+
+  /**
+   * Legacy nested config - merged with top-level tool options
+   * @deprecated Use flat config instead
+   */
+  config?: ToolConfig<Config>;
+
+  /**
+   * Tool-specific options (placeholder, levels, etc.)
+   * These are passed to the tool constructor as `config`
+   */
+  [key: string]: unknown;
+}
+
+/**
+ * Union of all tool settings formats
  */
-export type ToolSettings<Config extends object = any> = InternalToolSettings<Config> | ExternalToolSettings<Config>;
+export type ToolSettings<Config extends object = any> =
+  | InternalToolSettings<Config>
+  | ExternalToolSettings<Config>
+  | FlatToolSettings<Config>;

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

@@ -45,6 +45,12 @@ export interface PopoverItemChildren {
    * Useful for items like link tool that render custom content instead of a dropdown list.
    */
   hideChevron?: boolean;
+
+  /**
+   * Width of the nested popover. Defaults to '280px'.
+   * Use 'auto' to fit content width.
+   */
+  width?: string;
 }
 
 /**
@@ -134,11 +140,6 @@ export interface PopoverItemDefaultBaseParams {
    */
   title?: string;
 
-  /**
-   * @deprecated Use title instead
-   */
-  label?: string;
-
   /**
    * Item icon to be appeared near a title
    */
@@ -182,6 +183,24 @@ export interface PopoverItemDefaultBaseParams {
    */
   hint?: HintParams;
 
+  /**
+   * Custom data attributes to be added to the item element.
+   * Keys should be in camelCase (e.g., 'headerLevel' becomes 'data-header-level')
+   */
+  dataset?: Record<string, string>;
+
+  /**
+   * English title for multilingual search.
+   * Used to search against English terms even when UI is in another language.
+   */
+  englishTitle?: string;
+
+  /**
+   * Additional search terms for this item.
+   * Used to match alternative names or keywords.
+   */
+  searchTerms?: string[];
+
   /**
    * Popover item activation handler
    *

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

@@ -38,6 +38,13 @@ export interface PopoverParams {
    */
   flipper?: Flipper;
 
+  /**
+   * Allow keyboard navigation from contenteditable elements.
+   * When true, arrow keys will navigate the popover even when focus is in a contenteditable.
+   * False by default.
+   */
+  handleContentEditableNavigation?: boolean;
+
   /**
    * Popover texts overrides
    */
@@ -58,6 +65,12 @@ export interface PopoverParams {
    * Used to close nested popover and return focus to parent.
    */
   onNavigateBack?: () => void;
+
+  /**
+   * Width of the popover. Defaults to '280px'.
+   * Use 'auto' to fit content width.
+   */
+  width?: string;
 }