@jackuait/blok 0.1.1 → 0.2.0

package/types/api/styles.d.ts

@@ -1,44 +1,99 @@
 /**
- * Describes styles API
+ * Describes styles API - provides Tailwind CSS utility classes for tool styling.
+ *
+ * All values are Tailwind utility class strings that can be extended using tailwind-merge.
+ *
+ * @example
+ * // Basic usage
+ * element.className = api.styles.block;
+ *
+ * @example
+ * // Extending with custom styles using tailwind-merge
+ * import { twMerge } from 'tailwind-merge';
+ * const customBlock = twMerge(api.styles.block, 'my-4 bg-gray-100');
+ *
+ * @since 2.0.0 - Changed from BEM class names to Tailwind utility strings
  */
 export interface Styles {
   /**
-   * Main Editor`s block styles
+   * Base block styles - applied to block tool wrappers.
+   * Provides vertical padding for consistent block spacing.
+   * Includes placeholder styling via pseudo-element.
+   *
+   * @example 'py-[theme(spacing.block-padding-vertical)] px-0 [&::-webkit-input-placeholder]:!leading-normal'
    */
   block: string;
 
   /**
-   * Styles for Inline Toolbar button
+   * Styles for Inline Toolbar button.
+   * Provides flexbox centering, transparent background, and proper sizing.
+   *
+   * @example 'flex justify-center items-center border-0 rounded h-full p-0 w-7 bg-transparent cursor-pointer'
    */
   inlineToolButton: string;
 
   /**
-   * Styles for active Inline Toolbar button
+   * Styles for active Inline Toolbar button.
+   * Apply alongside inlineToolButton when the tool is active.
+   *
+   * @example 'bg-icon-active-bg text-icon-active-text'
    */
   inlineToolButtonActive: string;
 
   /**
-   * Styles for inputs
+   * Styles for input elements.
+   * Provides full width, border, padding, shadow, and Firefox placeholder workaround.
+   *
+   * @example 'w-full rounded-[3px] border border-line-gray px-3 py-2.5 outline-none shadow-input'
    */
   input: string;
 
   /**
-   * Loader styles
+   * Loader styles for loading states.
+   * Provides relative positioning, border, and spinning animation.
+   *
+   * @example 'relative border border-line-gray before:animate-rotation'
    */
   loader: string;
 
   /**
-   * Styles for Settings box buttons
+   * Styles for Settings box buttons.
+   * Provides flexbox centering, transparent background, minimum sizing,
+   * mobile responsive sizing, and hover states.
+   *
+   * @example 'inline-flex items-center justify-center rounded-[3px] cursor-pointer'
    */
   settingsButton: string;
 
   /**
-   * Styles for active Settings box buttons
+   * Styles for active Settings box buttons.
+   * Apply alongside settingsButton when the button is active.
+   *
+   * @example 'text-active-icon'
    */
   settingsButtonActive: string;
 
   /**
-   * Styles for buttons
+   * Styles for focused Settings box buttons.
+   * Apply alongside settingsButton when the button has focus.
+   *
+   * @example 'shadow-button-focused bg-item-focus-bg'
+   */
+  settingsButtonFocused: string;
+
+  /**
+   * Styles for focused Settings box buttons with animation.
+   * Apply alongside settingsButton and settingsButtonFocused for click animation.
+   *
+   * @example 'animate-button-clicked'
+   */
+  settingsButtonFocusedAnimated: string;
+
+  /**
+   * Styles for general buttons.
+   * Provides padding, border, background, shadow, hover states, and SVG styling.
+   *
+   * @example 'p-[13px] rounded-[3px] border border-line-gray text-[14.9px] bg-white'
    */
   button: string;
 }

package/types/api/tools.d.ts

@@ -1,7 +1,7 @@
 import { BlockToolAdapter } from '../tools/adapters/block-tool-adapter';
 
 /**
- * Describes methods for accessing installed Editor tools
+ * Describes methods for accessing installed Blok tools
  */
 export interface Tools {
   /**

package/types/api/ui.d.ts

@@ -1,19 +1,19 @@
 /**
- * Describes API module allowing to access some Editor UI elements and methods
+ * Describes API module allowing to access some Blok UI elements and methods
  */
 export interface Ui {
   /**
-   * Allows accessing some Editor UI elements
+   * Allows accessing some Blok UI elements
    */
   nodes: UiNodes,
 }
 
 /**
- * Allows accessing some Editor UI elements
+ * Allows accessing some Blok UI elements
  */
 export interface UiNodes {
   /**
-   * Top-level editor instance wrapper
+   * Top-level blok instance wrapper
    */
   wrapper: HTMLElement,
 

package/types/block-tunes/block-tune.d.ts

@@ -8,7 +8,7 @@ import { BaseToolConstructable, MenuConfig } from '../tools';
 export interface BlockTune {
   /**
    * Returns BlockTune's UI.
-   * Should return either MenuConfig (recommended) (@see https://editorjs.io/menu-config/)
+   * Should return either MenuConfig (recommended)
    * or an HTMLElement (UI consistency is not guaranteed)
    */
   render(): HTMLElement | MenuConfig;

package/types/configs/{editor-config.d.ts → blok-config.d.ts}

@@ -4,14 +4,14 @@ import {SanitizerConfig} from './sanitizer-config';
 import {I18nConfig} from './i18n-config';
 import { BlockMutationEvent } from '../events/block';
 
-export interface EditorConfig {
+export interface BlokConfig {
   /**
-   * Element where Editor will be appended
+   * Element where Blok will be appended
    */
   holder?: string | HTMLElement;
 
   /**
-   * If true, set caret at the first Block after Editor is ready
+   * If true, set caret at the first Block after Blok is ready
    */
   autofocus?: boolean;
 
@@ -48,17 +48,17 @@ export interface EditorConfig {
   }
 
   /**
-   * Data to render on Editor start
+   * Data to render on Blok start
    */
   data?: OutputData;
 
   /**
-   * Height of Editor's bottom area that allows to set focus on the last Block
+   * Height of Blok's bottom area that allows to set focus on the last Block
    */
   minHeight?: number;
 
   /**
-   * Editors log level (how many logs you want to see)
+   * Blok's log level (how many logs you want to see)
    */
   logLevel?: LogLevels;
 
@@ -73,13 +73,13 @@ export interface EditorConfig {
   i18n?: I18nConfig;
 
   /**
-   * Fires when Editor is ready to work
+   * Fires when Blok is ready to work
    */
   onReady?(): void;
 
   /**
    * Fires when something changed in DOM
-   * @param api - editor.js api
+   * @param api - blok.js api
    * @param event - custom event describing mutation. If several mutations happened at once, they will be batched and you'll get an array of events here.
    */
   onChange?(api: API, event: BlockMutationEvent | BlockMutationEvent[]): void;

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

@@ -16,7 +16,7 @@ export interface I18nDictionary {
 
   /**
    * 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 EditorConfig
+   * The first-level keys of this object should be equal of keys ot the 'tools' property of BlokConfig
    * Includes internal tools: "paragraph", "stub"
    *
    * Example:
@@ -34,7 +34,7 @@ export interface I18nDictionary {
 
   /**
    * 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 EditorConfig
+   * 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:
@@ -53,7 +53,7 @@ export interface I18nDictionary {
   blockTunes?: Dictionary;
 
   /**
-   * Translation of internal UI components of the editor.js core
+   * Translation of internal UI components of the blok.js core
    */
   ui?: Dictionary;
 }

package/types/configs/index.d.ts

@@ -1,4 +1,4 @@
-export * from './editor-config';
+export * from './blok-config';
 export * from './sanitizer-config';
 export * from './paste-config';
 export * from './conversion-config';

package/types/configs/notifier.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Base options interface for notifications
+ */
+export interface NotifierOptions {
+  /**
+   * Notification message (can contains HTML)
+   */
+  message: string;
+
+  /**
+   * Type of notification:
+   * - 'alert' (default)
+   * - 'confirm'
+   * - 'prompt'
+   */
+  type?: string;
+
+  /**
+   * Add class `blok-notify--${style}` to popup
+   * We have some default styles: 'success' and 'error'
+   */
+  style?: string;
+
+  /**
+   * Notification expire time in ms (8s by default)
+   * Only 'alert' notifies expires
+   */
+  time?: number;
+}
+
+/**
+ * Confirm notification options
+ */
+export interface ConfirmNotifierOptions extends NotifierOptions {
+  /**
+   * Text for confirmation button
+   * 'Confirm' by default
+   */
+  okText?: string;
+
+  /**
+   * Confirm button pressing callback
+   * @param {Event} event
+   */
+  okHandler?: (event: Event) => void;
+
+  /**
+   * Text for cancel button
+   * 'Cancel' by default
+   */
+  cancelText?: string;
+
+  /**
+   * Cancel button or cross button pressing callback
+   * @param {Event} event
+   */
+  cancelHandler?: (event: Event) => void;
+}
+
+/**
+ * Prompt notification options
+ */
+export interface PromptNotifierOptions extends NotifierOptions {
+  /**
+   * Text for the Submit button
+   * 'Ok' by default
+   */
+  okText?: string;
+
+  /**
+   * Submit button pressing callback
+   * Gets input's value as a parameter
+   * @param {string} value
+   */
+  okHandler: (value: string) => void;
+
+  /**
+   * Cross button pressing callback
+   * @param {Event} event
+   */
+  cancelHandler?: (event: Event) => void;
+
+  /**
+   * Type of input
+   * 'text' by default
+   */
+  inputType?: string;
+
+  /**
+   * Input placeholder
+   */
+  placeholder?: string;
+
+  /**
+   * Input default value
+   */
+  default?: string;
+}

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

@@ -30,7 +30,7 @@ export interface OutputBlockData<Type extends string = string, Data extends obje
 
 export interface OutputData {
   /**
-   * Editor's version
+   * Blok's version
    */
   version?: string;
 

package/types/events/block/BlockAdded.ts

@@ -16,6 +16,6 @@ interface BlockAddedEventDetail extends BlockMutationEventDetail {
 }
 
 /**
- * Event will be fired when the new block is added to the editor
+ * Event will be fired when the new block is added to the blok
  */
 export type BlockAddedEvent = CustomEvent<BlockAddedEventDetail>;

package/types/index.d.ts

@@ -7,7 +7,7 @@
 import {
   Dictionary,
   DictValue,
-  EditorConfig,
+  BlokConfig,
   I18nConfig,
   I18nDictionary,
 } from './configs';
@@ -68,7 +68,7 @@ export {
 } from './tools';
 export {BlockTune, BlockTuneConstructable} from './block-tunes';
 export {
-  EditorConfig,
+  BlokConfig,
   SanitizerConfig,
   SanitizerRule,
   PasteConfig,
@@ -123,9 +123,9 @@ export interface API {
 }
 
 /**
- * Main Editor class
+ * Main Blok class
  */
-declare class EditorJS {
+declare class Blok {
   public static version: string;
 
   public isReady: Promise<void>;
@@ -140,7 +140,7 @@ declare class EditorJS {
   public inlineToolbar: InlineToolbar;
   public tooltip: Tooltip;
   public readOnly: ReadOnly;
-  constructor(configuration?: EditorConfig|string);
+  constructor(configuration?: BlokConfig|string);
 
   /**
    * API shorthands
@@ -182,10 +182,10 @@ declare class EditorJS {
   public emit(eventName: string, data: any): void;
 
   /**
-   * Destroy Editor instance and related DOM elements
+   * Destroy Blok instance and related DOM elements
    */
   public destroy(): void;
 }
 
-export as namespace EditorJS;
-export default EditorJS;
+export as namespace Blok;
+export default Blok;

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

@@ -13,12 +13,12 @@ export interface BaseToolAdapter<Type extends ToolType, ToolClass extends Tool>
   type: Type;
 
   /**
-   * Tool name specified in EditorJS config
+   * Tool name specified in Blok config
    */
   name: string;
 
   /**
-   * Flag show is current Tool internal (bundled with EditorJS core) or not
+   * Flag show is current Tool internal (bundled with Blok core) or not
    */
   readonly isInternal: boolean;
 

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

@@ -26,7 +26,7 @@ interface BlockToolAdapter extends BaseToolAdapter<ToolType.Block, BlockTool>{
    * Creates new Tool instance
    * @param data - Tool data
    * @param block - BlockAPI for current Block
-   * @param readOnly - True if Editor is in read-only mode
+   * @param readOnly - True if Blok is in read-only mode
    */
   create(data: BlockToolData, block: BlockAPI, readOnly: boolean): BlockTool;
 

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

@@ -51,7 +51,7 @@ export interface BlockTool extends BaseTool {
 
   /**
    * Cleanup resources used by your tool here
-   * Called when the editor is destroyed
+   * Called when the blok is destroyed
    */
   destroy?(): void;
 

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

@@ -28,7 +28,7 @@ export interface ToolboxConfigEntry {
 }
 
 /**
- * Object passed to the Tool's constructor by {@link EditorConfig#tools}
+ * Object passed to the Tool's constructor by {@link BlokConfig#tools}
  *
  * @template Config - the structure describing a config object supported by the tool
  */

package/types/tools/tool.d.ts

@@ -11,7 +11,6 @@ export interface BaseTool<RenderReturnType = HTMLElement> {
    * Tool`s render method
    *
    * For Inline Tools returns {@link MenuConfig}
-   * @see https://editorjs.io/menu-config
    *
    * For Block Tools returns tool`s wrapper html element
    */
@@ -20,7 +19,7 @@ export interface BaseTool<RenderReturnType = HTMLElement> {
 
 export interface BaseToolConstructorOptions<C extends object = any> {
   /**
-   * Editor.js API
+   * Blok API
    */
   api: API;
 

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

@@ -39,6 +39,12 @@ export interface PopoverItemChildren {
    * Called once children popover is closed
    */
   onClose?: () => void;
+
+  /**
+   * True if the chevron icon should be hidden for this item.
+   * Useful for items like link tool that render custom content instead of a dropdown list.
+   */
+  hideChevron?: boolean;
 }
 
 /**
@@ -226,12 +232,29 @@ type PopoverItemHintRenderParams = {
 };
 
 
+/**
+ * Common popover item render params shared across item types
+ */
+interface PopoverItemCommonRenderParams {
+  /**
+   * If true, item is rendered inside an inline popover.
+   * Applies different styling for inline context.
+   */
+  isInline?: boolean;
+
+  /**
+   * If true, item is rendered inside a nested popover within an inline popover.
+   * Applies nested popover styling.
+   */
+  isNestedInline?: boolean;
+}
+
 /**
  * Popover item render params.
  * The parameters that are not set by user via popover api but rather depend on technical implementation
  */
 export type PopoverItemRenderParamsMap = {
-  [PopoverItemType.Default]?: {
+  [PopoverItemType.Default]?: PopoverItemCommonRenderParams & {
     /**
      * Wrapper tag for the item.
      * Div by default
@@ -241,13 +264,21 @@ export type PopoverItemRenderParamsMap = {
     /**
      * Hint render params
      */
-    hint?: PopoverItemHintRenderParams
+    hint?: PopoverItemHintRenderParams;
+
+    /**
+     * If true, adds a gap/margin after the icon.
+     * True by default. Set to false for inline tools where icons are displayed without titles.
+     */
+    iconWithGap?: boolean;
   };
 
-  [PopoverItemType.Html]?: {
+  [PopoverItemType.Html]?: PopoverItemCommonRenderParams & {
     /**
      * Hint render params
      */
     hint?: PopoverItemHintRenderParams
   };
+
+  [PopoverItemType.Separator]?: PopoverItemCommonRenderParams;
 };