@jackuait/blok 0.4.1 → 0.4.2

package/src/stories/helpers.ts

@@ -0,0 +1,463 @@
+/**
+ * Storybook test helpers for Blok editor stories.
+ * These utilities help work around browser environment differences in Chromatic.
+ */
+
+import { Blok } from '../blok';
+import type { OutputData, BlokConfig, ToolConstructable, ToolSettings, I18nConfig } from '@/types';
+import { Paragraph } from '../tools/paragraph';
+import { Header } from '../tools/header';
+import { ListItem } from '../tools/list';
+import { BoldInlineTool } from '../components/inline-tools/inline-tool-bold';
+import { ItalicInlineTool } from '../components/inline-tools/inline-tool-italic';
+import { LinkInlineTool } from '../components/inline-tools/inline-tool-link';
+import { ConvertInlineTool } from '../components/inline-tools/inline-tool-convert';
+
+/**
+ * Default tools configuration for Storybook stories.
+ * Since tools are no longer bundled by default, stories need to explicitly include them.
+ */
+export const defaultTools: { [toolName: string]: ToolConstructable | ToolSettings } = {
+  paragraph: {
+    class: Paragraph,
+    inlineToolbar: true,
+    config: { preserveBlank: true },
+  },
+  header: {
+    class: Header,
+    inlineToolbar: true,
+  },
+  list: {
+    class: ListItem,
+    inlineToolbar: true,
+  },
+  bold: BoldInlineTool,
+  italic: ItalicInlineTool,
+  link: LinkInlineTool,
+  convertTo: ConvertInlineTool,
+};
+
+/**
+ * Test ID selectors used in story tests
+ */
+export const TOOLBAR_TESTID = '[data-blok-testid="toolbar"]';
+
+/**
+ * Configuration options for the shared editor factory
+ */
+export interface EditorFactoryOptions {
+  /** Minimum height of the editor container in pixels */
+  minHeight?: number;
+  /** Width of the editor container in pixels (optional, defaults to auto) */
+  width?: number;
+  /** Initial data to populate the editor */
+  data?: OutputData;
+  /** Whether the editor is read-only */
+  readOnly?: boolean;
+  /** Placeholder text for empty blocks */
+  placeholder?: string;
+  /** Whether to autofocus the editor */
+  autofocus?: boolean;
+  /** Tools configuration */
+  tools?: { [toolName: string]: ToolConstructable | ToolSettings };
+  /** i18n configuration (e.g., for RTL support) */
+  i18n?: I18nConfig;
+}
+
+/**
+ * Extended HTMLElement interface that stores the Blok editor instance
+ */
+export interface EditorContainer extends HTMLElement {
+  __blokEditor?: Blok;
+}
+
+/** Shared editor state to avoid let declarations */
+const editorState: { editor: Blok | null; holder: HTMLElement | null } = {
+  editor: null,
+  holder: null,
+};
+
+/**
+ * Creates an editor container with a Blok editor instance.
+ * Reuses a single shared editor instance across stories when possible.
+ *
+ * @param options - Configuration options for the editor
+ * @returns HTMLElement container with the editor
+ */
+export const createEditorContainer = (options: EditorFactoryOptions = {}): HTMLElement => {
+  const {
+    minHeight = 300,
+    width,
+    data,
+    readOnly = false,
+    placeholder,
+    autofocus = false,
+    tools,
+    i18n,
+  } = options;
+
+  const container = document.createElement('div') as EditorContainer;
+
+  container.style.border = '1px solid #e0e0e0';
+  container.style.borderRadius = '8px';
+  container.style.padding = '16px';
+  container.style.minHeight = `${minHeight}px`;
+  container.style.backgroundColor = '#fff';
+  container.setAttribute('data-story-container', 'true');
+
+  if (width) {
+    container.style.width = `${width}px`;
+  }
+
+  const editorHolder = document.createElement('div');
+
+  editorHolder.id = `blok-editor-${Date.now()}`;
+  container.appendChild(editorHolder);
+
+  // Merge default tools with user-provided tools (user tools override defaults)
+  const mergedTools = { ...defaultTools, ...tools };
+
+  const config: BlokConfig = {
+    holder: editorHolder,
+    autofocus,
+    readOnly,
+    data,
+    placeholder,
+    tools: mergedTools,
+    i18n,
+  };
+
+  // Clean up and initialize editor after DOM is ready
+  setTimeout(async () => {
+    // Destroy previous editor if it exists and holder changed
+    if (editorState.editor && editorState.holder !== editorHolder) {
+      try {
+        await editorState.editor.destroy();
+      } catch {
+        // Editor may already be destroyed
+      }
+      editorState.editor = null;
+    }
+
+    // Create new editor instance
+    const editor = new Blok(config);
+
+    await editor.isReady;
+    await waitForIdleCallback();
+
+    // Store references
+    editorState.editor = editor;
+    editorState.holder = editorHolder;
+    container.__blokEditor = editor;
+  }, 0);
+
+  return container;
+};
+
+/**
+ * Gets the current shared editor instance (if available)
+ */
+export const getSharedEditor = (): Blok | null => editorState.editor;
+
+/**
+ * Cleans up the shared editor instance
+ */
+export const destroySharedEditor = async (): Promise<void> => {
+  if (editorState.editor) {
+    try {
+      await editorState.editor.destroy();
+    } catch {
+      // Editor may already be destroyed
+    }
+    editorState.editor = null;
+    editorState.holder = null;
+  }
+};
+
+/**
+ * Simulates a full click sequence (mousedown → mouseup → click) with proper event bubbling.
+ * This is needed because userEvent.click() doesn't properly trigger mousedown events
+ * in headless browser environments like Chromatic.
+ */
+export const simulateClick = (element: Element): void => {
+  const rect = element.getBoundingClientRect();
+  const clientX = rect.left + rect.width / 2;
+  const clientY = rect.top + rect.height / 2;
+
+  const eventOptions = {
+    bubbles: true,
+    cancelable: true,
+    clientX,
+    clientY,
+    button: 0,
+  };
+
+  element.dispatchEvent(new MouseEvent('mousedown', eventOptions));
+  element.dispatchEvent(new MouseEvent('mouseup', eventOptions));
+  element.dispatchEvent(new MouseEvent('click', eventOptions));
+
+  if (element instanceof HTMLElement) {
+    element.focus();
+  }
+};
+
+/**
+ * Waits for requestIdleCallback to fire, ensuring toolbar is fully initialized.
+ * This is needed because toolbar UI is created in requestIdleCallback.
+ */
+export const waitForIdleCallback = (): Promise<void> => {
+  return new Promise<void>((resolve) => {
+    if ('requestIdleCallback' in window) {
+      window.requestIdleCallback(() => resolve(), { timeout: 100 });
+    } else {
+      setTimeout(resolve, 0);
+    }
+  });
+};
+
+/**
+ * Waits for the toolbar element to be present in the DOM.
+ * The toolbar is created in requestIdleCallback with a 2000ms timeout,
+ * so we need to poll for its existence.
+ * @param container - The container element to search within
+ * @param timeout - Maximum time to wait in ms (default: 3000)
+ */
+export const waitForToolbar = (container: Element, timeout = 3000): Promise<Element> => {
+  return new Promise((resolve, reject) => {
+    const startTime = Date.now();
+    const checkInterval = 50;
+
+    const check = (): void => {
+      const toolbar = container.querySelector(TOOLBAR_TESTID);
+
+      if (toolbar) {
+        resolve(toolbar);
+
+        return;
+      }
+
+      if (Date.now() - startTime >= timeout) {
+        reject(new Error(`Toolbar not found within ${timeout}ms`));
+
+        return;
+      }
+
+      setTimeout(check, checkInterval);
+    };
+
+    check();
+  });
+};
+
+/**
+ * Key codes used for keyboard event simulation
+ */
+const KEY_CODES: Record<string, number> = {
+  TAB: 9,
+  ENTER: 13,
+  ARROW_LEFT: 37,
+  ARROW_UP: 38,
+  ARROW_RIGHT: 39,
+  ARROW_DOWN: 40,
+};
+
+/**
+ * Dispatches a keyboard event from a target element or finds a suitable target.
+ * This is needed because userEvent.keyboard() may not properly trigger
+ * document-level event listeners in headless browser environments.
+ * @param key - The key to simulate (e.g., 'ArrowDown', 'Enter', 'Tab')
+ * @param options - Additional event options (ctrlKey, metaKey, shiftKey, target)
+ */
+export const dispatchKeyboardEvent = (
+  key: string,
+  options: { ctrlKey?: boolean; metaKey?: boolean; shiftKey?: boolean; target?: Element } = {}
+): void => {
+  const keyCode = KEY_CODES[key.toUpperCase().replace('ARROW', 'ARROW_')] ?? 0;
+
+  const event = new KeyboardEvent('keydown', {
+    bubbles: true,
+    cancelable: true,
+    key,
+    code: key,
+    ctrlKey: options.ctrlKey ?? false,
+    metaKey: options.metaKey ?? false,
+    shiftKey: options.shiftKey ?? false,
+  });
+
+  // Set keyCode for older browser compatibility
+  Object.defineProperty(event, 'keyCode', { get: () => keyCode });
+  Object.defineProperty(event, 'which', { get: () => keyCode });
+
+  // Dispatch from the target element if provided, otherwise from body
+  // This ensures event.target has proper DOM methods like closest()
+  const targetElement = options.target ?? document.activeElement ?? document.body;
+
+  targetElement.dispatchEvent(event);
+};
+
+/**
+ * Simulates typing text by dispatching keyboard events and input events.
+ * This is needed for search/filter functionality that listens to document-level events.
+ * @param text - The text to type
+ */
+export const simulateTyping = (text: string): void => {
+  for (const char of text) {
+    const keydownEvent = new KeyboardEvent('keydown', {
+      bubbles: true,
+      cancelable: true,
+      key: char,
+      code: `Key${char.toUpperCase()}`,
+    });
+
+    document.dispatchEvent(keydownEvent);
+
+    // Also dispatch keypress for compatibility
+    const keypressEvent = new KeyboardEvent('keypress', {
+      bubbles: true,
+      cancelable: true,
+      key: char,
+      code: `Key${char.toUpperCase()}`,
+    });
+
+    document.dispatchEvent(keypressEvent);
+  }
+};
+
+/**
+ * Triggers a select-all action using the cross-platform shortcut.
+ * Uses Ctrl+A which works in Chromium browser (used by storybook tests).
+ * @param element - The element to focus before triggering select-all
+ */
+export const triggerSelectAll = (element: Element): void => {
+  if (element instanceof HTMLElement) {
+    element.focus();
+  }
+
+  // Dispatch Ctrl+A (works in Chromium, which is used for storybook tests)
+  const event = new KeyboardEvent('keydown', {
+    bubbles: true,
+    cancelable: true,
+    key: 'a',
+    code: 'KeyA',
+    ctrlKey: true,
+    metaKey: false,
+  });
+
+  Object.defineProperty(event, 'keyCode', { get: () => 65 });
+  Object.defineProperty(event, 'which', { get: () => 65 });
+
+  element.dispatchEvent(event);
+};
+
+/**
+ * Selects text within a block, handling DOM normalization (e.g., <b> → <strong>).
+ * Focuses the contenteditable element and creates a proper selection.
+ * @param block - The block wrapper element containing the contenteditable
+ * @param selector - CSS selector for the element to select (e.g., 'strong', 'em', 'a')
+ * @param contentEditableSelector - Selector for the contenteditable element
+ * @returns True if selection was created successfully
+ */
+export const selectTextInBlock = (
+  block: Element,
+  selector: string,
+  contentEditableSelector = '[contenteditable="true"]'
+): boolean => {
+  const contentEditable = block.querySelector(contentEditableSelector);
+  const targetElement = block.querySelector(selector);
+
+  if (!contentEditable || !targetElement) {
+    return false;
+  }
+
+  // Focus the contenteditable first to ensure selection is rendered
+  if (contentEditable instanceof HTMLElement) {
+    contentEditable.focus();
+  }
+
+  // Create and apply the selection
+  const range = document.createRange();
+
+  range.selectNodeContents(targetElement);
+
+  const selection = window.getSelection();
+
+  selection?.removeAllRanges();
+  selection?.addRange(range);
+
+  // Dispatch selectionchange event to trigger toolbar
+  document.dispatchEvent(new Event('selectionchange'));
+
+  return true;
+};
+
+/**
+ * Focuses the popover search input and types text into it.
+ * This is needed because userEvent.keyboard() types into the wrong element.
+ * @param text - The text to type into the search input
+ * @param searchInputSelector - Selector for the search input
+ * @returns True if search was performed successfully
+ */
+export const focusSearchInput = (
+  text: string,
+  searchInputSelector = '[data-blok-testid="popover-search-input"]'
+): boolean => {
+  const searchInput = document.querySelector(searchInputSelector) as HTMLInputElement | null;
+
+  if (!searchInput) {
+    return false;
+  }
+
+  searchInput.focus();
+  searchInput.value = text;
+  searchInput.dispatchEvent(new Event('input', { bubbles: true }));
+
+  return true;
+};
+
+/**
+ * Waits for an element to have pointer-events enabled.
+ * This is needed because popover containers start with pointer-events: none.
+ * @param selector - CSS selector for the element to check
+ * @param timeout - Maximum time to wait in ms (default: 3000)
+ */
+export const waitForPointerEvents = (selector: string, timeout = 3000): Promise<Element> => {
+  return new Promise((resolve, reject) => {
+    const startTime = Date.now();
+    const checkInterval = 50;
+
+    const check = (): void => {
+      const isTimedOut = Date.now() - startTime >= timeout;
+      const element = document.querySelector(selector);
+
+      if (!element && isTimedOut) {
+        reject(new Error(`Element ${selector} did not get pointer-events enabled within ${timeout}ms`));
+
+        return;
+      }
+
+      if (!element) {
+        setTimeout(check, checkInterval);
+
+        return;
+      }
+
+      const computedStyle = window.getComputedStyle(element);
+
+      if (computedStyle.pointerEvents !== 'none') {
+        resolve(element);
+
+        return;
+      }
+
+      if (isTimedOut) {
+        reject(new Error(`Element ${selector} did not get pointer-events enabled within ${timeout}ms`));
+
+        return;
+      }
+
+      setTimeout(check, checkInterval);
+    };
+
+    check();
+  });
+};

package/src/styles/main.css

@@ -0,0 +1,123 @@
+/* Tailwind CSS - must be first */
+@import 'tailwindcss/base';
+@import 'tailwindcss/components';
+@import 'tailwindcss/utilities';
+
+/**
+ * Component classes for the Styles API.
+ * These single-class names can be safely used with classList.add() by external plugins.
+ * Each class bundles multiple Tailwind utilities using @apply.
+ */
+@layer components {
+  /* Base Blok styles - applied to block tool wrappers */
+  .blok-block {
+    @apply py-[3px] px-[2px] [&::-webkit-input-placeholder]:!leading-normal;
+  }
+
+  /* Inline Tools styles */
+  .blok-inline-tool-button {
+    @apply flex justify-center items-center border-0 rounded h-full p-0 w-7 bg-transparent cursor-pointer leading-normal text-black;
+  }
+
+  .blok-inline-tool-button--active {
+    @apply bg-icon-active-bg text-icon-active-text;
+  }
+
+  /* Input element styles */
+  .blok-input {
+    @apply w-full rounded-[3px] border border-line-gray px-3 py-2.5 outline-none shadow-input [&[data-blok-placeholder]]:before:!static [&[data-blok-placeholder]]:before:inline-block [&[data-blok-placeholder]]:before:w-0 [&[data-blok-placeholder]]:before:whitespace-nowrap [&[data-blok-placeholder]]:before:pointer-events-none;
+  }
+
+  /* Loader styles with spinning animation */
+  .blok-loader {
+    @apply relative border border-line-gray before:absolute before:left-1/2 before:top-1/2 before:w-[18px] before:h-[18px] before:rounded-full before:content-[''] before:-ml-[11px] before:-mt-[11px] before:border-2 before:border-line-gray before:border-l-active-icon before:animate-rotation;
+  }
+
+  /* Button styles */
+  .blok-button {
+    @apply p-[13px] rounded-[3px] border border-line-gray text-[14.9px] bg-white text-center cursor-pointer text-gray-text shadow-button-base hover:bg-[#fbfcfe] hover:shadow-button-base-hover [&_svg]:h-5 [&_svg]:mr-[0.2em] [&_svg]:-mt-0.5;
+  }
+
+  /* Settings button styles */
+  .blok-settings-button {
+    @apply inline-flex items-center justify-center rounded-[3px] cursor-pointer border-0 outline-none bg-transparent align-bottom text-inherit m-0 min-w-toolbox-btn min-h-toolbox-btn [&_svg]:w-auto [&_svg]:h-auto mobile:w-toolbox-btn-mobile mobile:h-toolbox-btn-mobile mobile:rounded-lg mobile:[&_svg]:w-icon-mobile mobile:[&_svg]:h-icon-mobile can-hover:hover:bg-bg-light;
+  }
+
+  .blok-settings-button--active {
+    @apply text-active-icon;
+  }
+
+  .blok-settings-button--focused {
+    @apply shadow-button-focused bg-item-focus-bg;
+  }
+
+  .blok-settings-button--focused-animated {
+    @apply animate-button-clicked;
+  }
+}
+
+/**
+ * Navigation mode styles
+ * Applied when user enters block navigation mode via Escape key
+ */
+[data-blok-navigation-focused="true"] {
+  @apply bg-item-focus-bg rounded-md w-content-width max-w-full mx-auto;
+}
+
+/**
+ * Delete button hover styles
+ * Makes the delete button text and icon appear red on hover
+ */
+@media (hover: hover) {
+  [data-blok-item-name="delete"]:hover {
+    @apply text-item-confirm-bg transition-colors;
+  }
+}
+
+/**
+ * Drop indicator styles for drag and drop
+ * Shows a visual line at the top or bottom of a block during drag
+ * The --drop-indicator-depth CSS variable controls indentation based on target nesting level
+ */
+[data-drop-indicator] {
+  @apply relative;
+}
+
+[data-drop-indicator]::before {
+  @apply content-[''] absolute -translate-x-1/2 w-full max-w-content h-1.5 rounded-sm bg-[#d4e3fc] pointer-events-none z-10;
+  left: calc(50% + var(--drop-indicator-depth, 0) * 12px);
+  max-width: calc(650px - var(--drop-indicator-depth, 0) * 24px);
+}
+
+[data-drop-indicator="bottom"]::before {
+  @apply translate-y-1/2 bottom-0;
+}
+
+[data-drop-indicator="top"]::before {
+  @apply -translate-y-1/2 top-0;
+}
+
+/**
+ * Multi-block drag visual feedback
+ * Makes selected blocks semi-transparent during multi-block drag operation
+ */
+[data-blok-dragging-multi="true"] [data-blok-selected="true"] {
+  @apply opacity-40 transition-opacity duration-200;
+}
+
+/**
+ * List item selection styles
+ * Applies selection background to the list item itself (not the content wrapper)
+ * so that margin-left indentation is respected
+ */
+[data-blok-selected="true"] [data-blok-element-content]:has([data-list-style]) {
+  @apply bg-transparent;
+}
+
+[data-blok-selected="true"] [data-list-style] [role="listitem"] {
+  @apply bg-selection rounded-[4px];
+}
+
+[data-blok-selected="true"] [data-list-style] [role="listitem"] [contenteditable] {
+  @apply select-none;
+}