@jackuait/blok 0.1.1

package/types/tools/paste-events.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Event detail for tag substitution on paste
+ */
+export interface HTMLPasteEventDetail {
+  /**
+   * Pasted element
+   */
+  data: HTMLElement;
+}
+
+/**
+ * Paste event for tag substitution
+ */
+export interface HTMLPasteEvent extends CustomEvent {
+  readonly detail: HTMLPasteEventDetail;
+}
+
+/**
+ * Event detail for file substitution on paste
+ */
+export interface FilePasteEventDetail {
+  /**
+   * Pasted file
+   */
+  file: File;
+}
+
+export interface FilePasteEvent extends CustomEvent {
+  readonly detail: FilePasteEventDetail;
+}
+
+/**
+ * Event detail for pattern substitution on paste
+ */
+export interface PatternPasteEventDetail {
+  /**
+   * Pattern key
+   */
+  key: string;
+
+  /**
+   * Pasted string
+   */
+  data: string;
+}
+
+export interface PatternPasteEvent extends CustomEvent {
+  readonly detail: PatternPasteEventDetail;
+}
+
+export type PasteEvent = HTMLPasteEvent | FilePasteEvent | PatternPasteEvent;
+export type PasteEventDetail = HTMLPasteEventDetail | FilePasteEventDetail | PatternPasteEventDetail;

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

@@ -0,0 +1,4 @@
+/**
+ * Tool configuration object. Specified by Tool developer, so leave it as object
+ */
+export type ToolConfig<T extends object = any> = T;

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

@@ -0,0 +1,79 @@
+import { ToolConfig } from './tool-config';
+import { ToolConstructable, BlockToolData, MenuConfig, MenuConfigItem } from './index';
+
+/**
+ * Tool may specify its toolbox configuration
+ * It may include several entries as well
+ */
+export type ToolboxConfig = ToolboxConfigEntry | ToolboxConfigEntry[];
+
+/**
+ * Tool's Toolbox settings
+ */
+export interface ToolboxConfigEntry {
+  /**
+   * Tool title for Toolbox
+   */
+  title?: string;
+
+  /**
+   * HTML string with an icon for Toolbox
+   */
+  icon?: string;
+
+  /**
+   * May contain overrides for tool default data
+   */
+  data?: BlockToolData
+}
+
+/**
+ * Object passed to the Tool's constructor by {@link EditorConfig#tools}
+ *
+ * @template Config - the structure describing a config object supported by the tool
+ */
+export interface ExternalToolSettings<Config extends object = any> {
+
+  /**
+   * Tool's class
+   */
+  class: ToolConstructable;
+
+  /**
+   * User configuration object that will be passed to the Tool's constructor
+   */
+  config?: ToolConfig<Config>;
+
+  /**
+   * Is need to show Inline Toolbar.
+   * Can accept array of Tools for InlineToolbar or boolean.
+   */
+  inlineToolbar?: boolean | string[];
+
+  /**
+   * BlockTunes for Tool
+   * Can accept array of tune names or boolean.
+   */
+  tunes?: boolean | string[];
+
+  /**
+   * Define shortcut that will render Tool
+   */
+  shortcut?: string;
+
+  /**
+   * Tool's Toolbox settings
+   * It will be hidden from Toolbox when false is specified.
+   */
+  toolbox?: ToolboxConfig | false;
+}
+
+/**
+ * For internal Tools 'class' property is optional
+ */
+export type InternalToolSettings<Config extends object = any> = Omit<ExternalToolSettings<Config>, 'class'> & Partial<Pick<ExternalToolSettings<Config>, 'class'>>;
+
+/**
+ * Union of external and internal Tools settings
+ */
+export type ToolSettings<Config extends object = any> = InternalToolSettings<Config> | ExternalToolSettings<Config>;

package/types/tools/tool.d.ts

@@ -0,0 +1,65 @@
+import {API} from '../index';
+import {ToolConfig} from './tool-config';
+import {SanitizerConfig} from '../configs';
+import {MenuConfig} from './menu-config';
+
+/**
+ * Abstract interface of all Tools
+ */
+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
+   */
+  render(): RenderReturnType | Promise<RenderReturnType>;
+}
+
+export interface BaseToolConstructorOptions<C extends object = any> {
+  /**
+   * Editor.js API
+   */
+  api: API;
+
+  /**
+   * Tool configuration
+   */
+  config?: ToolConfig<C>;
+}
+
+export interface BaseToolConstructable {
+  /**
+   * Define Tool type as Inline
+   */
+  isInline?: boolean;
+
+  /**
+   * Tool`s sanitizer configuration
+   */
+  sanitize?: SanitizerConfig;
+
+  /**
+   * Shortcut for Tool
+   */
+  shortcut?: string;
+
+  /**
+   * Title of Inline Tool.
+   * @deprecated use {@link MenuConfig} item title instead
+   */
+  title?: string;
+
+  /**
+   * Tool`s prepare method. Can be async
+   * @param data
+   */
+  prepare?(data: {toolName: string, config: ToolConfig}): void | Promise<void>;
+
+  /**
+   * Tool`s reset method to clean up anything set by prepare. Can be async
+   */
+  reset?(): void | Promise<void>;
+}

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

@@ -0,0 +1,29 @@
+/**
+ * Hint parameters
+ */
+export interface HintParams {
+  /**
+   * Title of the hint
+   */
+  title: string;
+
+  /**
+   * Secondary text to be displayed below the title
+   */
+  description?: string;
+
+  /**
+   * Horizontal alignment of the hint content. Default is 'start'
+   */
+  alignment?: HintTextAlignment;
+}
+
+/**
+ * Possible hint positions
+ */
+export type HintPosition = 'top' | 'bottom' | 'left' | 'right';
+
+/**
+ * Horizontal alignment of the hint content
+ */
+export type HintTextAlignment = 'start' | 'center';

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

@@ -0,0 +1,5 @@
+export type * from './hint';
+export type * from './popover-item';
+export * from './popover-item-type';
+export type * from './popover';
+export * from './popover-event';

package/types/utils/popover/popover-event.ts

@@ -0,0 +1,15 @@
+
+/**
+ * Event that can be triggered by the Popover
+ */
+export enum PopoverEvent {
+  /**
+   * When popover closes
+   */
+  Closed = 'closed',
+
+  /**
+   * When it closes because item with 'closeOnActivate' property set was clicked
+   */
+  ClosedOnActivate = 'closed-on-activate',
+}

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

@@ -0,0 +1,13 @@
+/**
+ * Popover item types
+ */
+export enum PopoverItemType {
+  /** Regular item with icon, title and other properties */
+  Default = 'default',
+
+  /** Gray line used to separate items from each other */
+  Separator = 'separator',
+
+  /** Item with custom html content */
+  Html = 'html'
+}

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

@@ -0,0 +1,253 @@
+import { HintParams, HintPosition, HintTextAlignment } from "./hint";
+import { PopoverItemType } from "./popover-item-type";
+
+export { PopoverItemType } from './popover-item-type';
+
+/**
+ * Represents popover item children configuration
+ */
+export interface PopoverItemChildren {
+  /**
+   * True if children items should be searchable
+   */
+  searchable?: boolean;
+
+  /**
+   * True if popover with children should be displayed instantly and not after item click/hover.
+   * False by default.
+   * Now is used only in the inline popover.
+   */
+  isOpen?: boolean;
+
+  /**
+   * False if keyboard navigation should be disabled in the children popover.
+   * True by default
+   */
+  isFlippable?: boolean;
+
+ /**
+  * Items of nested popover that should be open on the current item hover/click (depending on platform)
+  */
+  items?: PopoverItemParams[];
+
+  /**
+   * Called once children popover is opened
+   */
+  onOpen?: () => void;
+
+  /**
+   * Called once children popover is closed
+   */
+  onClose?: () => void;
+}
+
+/**
+ * Adds children property to the item
+ */
+export type WithChildren<T> = Omit<T, 'onActivate'> & {
+  /**
+   * Popover item children configuration
+   */
+  children: PopoverItemChildren;
+
+  /**
+   * Items with children should not have onActivate handler
+   */
+  onActivate?: never;
+};
+
+/**
+ * Represents popover item with confirmation.
+ */
+export type PopoverItemDefaultWithConfirmationParams = Omit<PopoverItemDefaultBaseParams, 'onActivate'> & {
+  /**
+   * Popover item parameters that should be applied on item activation.
+   * May be used to ask user for confirmation before executing popover item activation handler.
+   */
+  confirmation: PopoverItemDefaultBaseParams;
+
+  /**
+   * Items with confirmation should not have onActivate handler
+   */
+  onActivate?: never;
+};
+
+/**
+ * Represents popover item separator.
+ * Special item type that is used to separate items in the popover.
+ */
+export interface PopoverItemSeparatorParams {
+  /**
+   * Item type
+   */
+  type: PopoverItemType.Separator;
+}
+
+/**
+ * Represents popover item with custom html content
+ */
+export interface PopoverItemHtmlParams {
+  /**
+   * Item type
+   */
+  type: PopoverItemType.Html;
+
+  /**
+   * Custom html content to be displayed in the popover
+   */
+  element: HTMLElement;
+
+  /**
+   * Hint data to be displayed on item hover
+   */
+  hint?: HintParams;
+
+  /**
+   * True if popover should close once item is activated
+   */
+  closeOnActivate?: boolean;
+
+  /**
+   * Item name
+   * Used in data attributes needed for automated end-to-end tests
+   */
+  name?: string;
+}
+
+/**
+ * Common parameters for all kinds of default popover items: with or without confirmation
+ */
+export interface PopoverItemDefaultBaseParams {
+  /**
+   * Item type
+   */
+  type?: PopoverItemType.Default;
+
+  /**
+   * Displayed text
+   */
+  title?: string;
+
+  /**
+   * @deprecated Use title instead
+   */
+  label?: string;
+
+  /**
+   * Item icon to be appeared near a title
+   */
+  icon?: string;
+
+  /**
+   * Additional displayed text
+   */
+  secondaryLabel?: string;
+
+  /**
+   * True if item should be highlighted as active
+   */
+  isActive?: boolean | (() => boolean);
+
+  /**
+   * True if item should be disabled
+   */
+  isDisabled?: boolean;
+
+  /**
+   * True if popover should close once item is activated
+   */
+  closeOnActivate?: boolean;
+
+  /**
+   * Item name
+   * Used in data attributes needed for shortcuts work and automated end-to-end tests
+   */
+  name?: string;
+
+  /**
+   * Defines whether item should toggle on click.
+   * Can be represented as boolean value or a string key.
+   * In case of string, works like radio buttons group and highlights as inactive any other item that has same toggle key value.
+   */
+  toggle?: boolean | string;
+
+  /**
+   * Hint data to be displayed on item hover
+   */
+  hint?: HintParams;
+
+  /**
+   * Popover item activation handler
+   *
+   * @param item - activated item
+   * @param event - event that initiated item activation
+   */
+  onActivate: (item: PopoverItemParams, event?: PointerEvent) => void;
+}
+
+/**
+ * Default, non-separator and non-html popover items type
+ */
+export type PopoverItemDefaultParams =
+  PopoverItemDefaultBaseParams |
+  PopoverItemDefaultWithConfirmationParams |
+  WithChildren<PopoverItemDefaultBaseParams>;
+
+/**
+ * Represents single popover item
+ */
+export type PopoverItemParams =
+  PopoverItemDefaultParams |
+  PopoverItemSeparatorParams |
+  PopoverItemHtmlParams |
+  WithChildren<PopoverItemHtmlParams>;
+
+/**
+ * Parameters of how to render hint for the popover item
+ */
+type PopoverItemHintRenderParams = {
+  /**
+   * Hint position relative to the item
+   */
+  position?: HintPosition;
+
+  /**
+   * Horizontal alignment of the hint content.
+   * 'start' by default.
+   */
+  alignment?: HintTextAlignment;
+
+  /**
+   * If false, hint will not be rendered.
+   * True by default.
+   * Used to disable hints on mobile popover
+   */
+  enabled?: 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]?: {
+    /**
+     * Wrapper tag for the item.
+     * Div by default
+     */
+    wrapperTag?: 'div' | 'button';
+
+    /**
+     * Hint render params
+     */
+    hint?: PopoverItemHintRenderParams
+  };
+
+  [PopoverItemType.Html]?: {
+    /**
+     * Hint render params
+     */
+    hint?: PopoverItemHintRenderParams
+  };
+};

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

@@ -0,0 +1,112 @@
+import { PopoverItemParams } from './popover-item';
+import type Flipper from '../../../src/components/flipper';
+import { PopoverEvent } from './popover-event';
+
+/**
+ * Params required to render popover
+ */
+export interface PopoverParams {
+  /**
+   * Popover items config
+   */
+  items: PopoverItemParams[];
+
+  /**
+   * Element of the page that creates 'scope' of the popover.
+   * Depending on its size popover position will be calculated
+   */
+  scopeElement?: HTMLElement;
+
+  /**
+   * Element relative to which the popover should be positioned
+   */
+  trigger?: HTMLElement;
+
+  /**
+   * True if popover should contain search field
+   */
+  searchable?: boolean;
+
+  /**
+   * False if keyboard navigation should be disabled.
+   * True by default
+   */
+  flippable?: boolean;
+
+  /**
+   * Optional flipper instance to reuse for keyboard navigation
+   */
+  flipper?: Flipper;
+
+  /**
+   * Popover texts overrides
+   */
+  messages?: PopoverMessages
+
+  /**
+   * CSS class name for popover root element
+   */
+  class?: string;
+
+  /**
+   * Popover nesting level. 0 value means that it is a root popover
+   */
+  nestingLevel?: number;
+}
+
+
+/**
+ * Texts used inside popover
+ */
+export interface PopoverMessages {
+  /** Text displayed when search has no results */
+  nothingFound?: string;
+
+  /** Search input label */
+  search?: string
+}
+
+
+/**
+ * Events fired by the Popover
+ */
+export interface PopoverEventMap {
+  /**
+   * Fired when popover closes
+   */
+  [PopoverEvent.Closed]: undefined;
+
+  /**
+   * Fired when popover closes because item with 'closeOnActivate' property set was clicked
+   * Value is the item that was clicked
+   */
+  [PopoverEvent.ClosedOnActivate]: undefined;
+}
+
+/**
+ * HTML elements required to display popover
+ */
+export interface PopoverNodes {
+  /** Root popover element */
+  popover: HTMLElement;
+
+  /** Wraps all the visible popover elements, has background and rounded corners */
+  popoverContainer: HTMLElement;
+
+  /** Message displayed when no items found while searching */
+  nothingFoundMessage: HTMLElement;
+
+  /** Popover items wrapper */
+  items: HTMLElement;
+}
+
+/**
+ * HTML elements required to display mobile popover
+ */
+export interface PopoverMobileNodes extends PopoverNodes {
+  /** Popover header element */
+  header: HTMLElement;
+
+  /** Overlay, displayed under popover on mobile */
+  overlay: HTMLElement;
+}