@jackuait/blok 0.6.0-beta.9 → 0.7.0-beta.1

package/src/stories/helpers.ts

@@ -8,6 +8,7 @@ import { BoldInlineTool } from '../components/inline-tools/inline-tool-bold';
 import { ConvertInlineTool } from '../components/inline-tools/inline-tool-convert';
 import { ItalicInlineTool } from '../components/inline-tools/inline-tool-italic';
 import { LinkInlineTool } from '../components/inline-tools/inline-tool-link';
+import { MarkerInlineTool } from '../components/inline-tools/inline-tool-marker';
 import { Header } from '../tools/header';
 import { ListItem } from '../tools/list';
 import { Paragraph } from '../tools/paragraph';
@@ -35,6 +36,7 @@ export const defaultTools: { [toolName: string]: ToolConstructable | ToolSetting
   bold: BoldInlineTool,
   italic: ItalicInlineTool,
   link: LinkInlineTool,
+  marker: MarkerInlineTool,
   convertTo: ConvertInlineTool,
 };
 

package/src/styles/main.css

@@ -1,61 +1,231 @@
-/* Tailwind CSS - must be first */
-@import 'tailwindcss/base';
-@import 'tailwindcss/components';
-@import 'tailwindcss/utilities';
+/*
+  Import Tailwind CSS sub-modules individually (without native @layer wrappers).
+  The default `@import 'tailwindcss'` wraps all output in @layer declarations,
+  which causes styles to lose to ANY un-layered consumer CSS — per the CSS spec,
+  un-layered styles always beat layered styles regardless of specificity.
+  Individual imports avoid this, making the library's styles work in real apps.
+  See: https://github.com/tailwindlabs/tailwindcss/discussions/13188
+*/
+@import 'tailwindcss/theme.css';
+@import 'tailwindcss/preflight.css';
+@import 'tailwindcss/utilities.css';
 
-/**
- * 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;
-  }
+/*
+  Exclude non-source directories from Tailwind's automatic content detection.
+  Without this, Tailwind v4 scans all non-gitignored files (including docs/,
+  test/, .claude/) and picks up false class candidates from code examples,
+  test fixtures, and markdown — generating dead CSS in the production bundle.
+*/
+@source not "../../docs";
+@source not "../../test";
+@source not "../../.claude";
+@source not "../../scripts";
+@source not "../../.storybook";
 
-  /* 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;
+@custom-variant mobile (@media (max-width: 650px));
+@custom-variant not-mobile (@media (min-width: 651px));
+@custom-variant can-hover (@media (hover: hover));
+
+@custom-variant dark (&:where(.dark-mode, .dark-mode *));
+
+@theme {
+  /* Z-index */
+  --z-index-overlay: 999;
+
+  /* Colors */
+  --color-selection: #e1f2ff;
+  --color-selection-inline: #d4ecff;
+  --color-selection-highlight: rgba(46, 170, 220, 0.2);
+  --color-bg-light: #eff2f5;
+  --color-gray-text: #707684;
+  --color-dark: #1d202b;
+  --color-active-icon: #388ae5;
+  --color-link: #388ae5;
+  --color-line-gray: #eff0f1;
+  --color-tooltip-bg: #1d202b;
+  --color-tooltip-font: #cdd1e0;
+  --color-icon-active-bg: rgba(56, 138, 229, 0.1);
+  --color-icon-active-text: #388ae5;
+  --color-text-primary: black;
+  --color-text-secondary: #707684;
+  --color-popover-border: #eff0f1;
+  --color-popover-shadow: rgba(13, 20, 33, 0.1);
+  --color-popover-bg: #ffffff;
+  --color-popover-border-icon: rgb(201 201 204 / 48%);
+  --color-popover-border-icon-disabled: #eff0f1;
+  --color-item-focus-bg: rgba(34, 186, 255, 0.08);
+  --color-item-focus-shadow: rgba(7, 161, 227, 0.08);
+  --color-item-hover-bg: #f8f8f8;
+  --color-icon-bg: rgba(0, 0, 0, 0.04);
+  --color-item-confirm-bg: #e24a4a;
+  --color-item-confirm-hover-bg: #ce4343;
+  --color-item-destructive-text: #e24a4a;
+  --color-item-destructive-hover-bg: rgba(226, 74, 74, 0.08);
+  --color-notify-success-bg: #fafffe;
+  --color-notify-success-bar: #41ffb1;
+  --color-notify-error-bg: #fffbfb;
+  --color-notify-error-bar: #fb5d5d;
+  --color-notify-btn-cancel-bg: #f2f5f7;
+  --color-notify-btn-cancel-text: #656b7c;
+  --color-notify-btn-confirm-bg: #34c992;
+
+  /* Spacing (also powers w-*, h-*, min-w-*, min-h-*, size-*) */
+  --spacing-content-width: 650px;
+  --spacing-narrow-mode-right-padding: 50px;
+  --spacing-toolbox-btn: 26px;
+  --spacing-toolbox-btn-mobile: 36px;
+  --spacing-icon: 20px;
+  --spacing-icon-mobile: 28px;
+  --spacing-block-padding-vertical: 0.4em;
+
+  /* Max-width */
+  --max-width-content: 650px;
+
+  /* Font family */
+  --font-mono: 'PT Mono', 'Menlo', 'Monaco', 'Consolas', 'Courier New', monospace;
+
+  /* Box shadows */
+  --shadow-overlay-pane: 0 3px 15px -3px rgba(13, 20, 33, 0.13);
+  --shadow-tool-icon: 0 0 0 1px #eff0f1;
+  --shadow-tooltip: 0 8px 12px 0 rgba(29, 32, 43, 0.17), 0 4px 5px -3px rgba(5, 6, 12, 0.49);
+  --shadow-notify: 0 11px 17px 0 rgba(23, 32, 61, 0.13);
+  --shadow-button-focused: inset 0 0 0 1px rgba(7, 161, 227, 0.08);
+  --shadow-input: inset 0 1px 2px 0 rgba(35, 44, 72, 0.06);
+  --shadow-button-base: 0 2px 2px 0 rgba(18, 30, 57, 0.04);
+  --shadow-button-base-hover: 0 1px 3px 0 rgba(18, 30, 57, 0.08);
+  --shadow-demo-btn: 0 22px 18px -4px rgba(137, 207, 255, 0.77);
+  --shadow-demo-btn-hover: 0 20px 15px -4px rgba(137, 207, 255, 0.77);
+  --shadow-demo-btn-primary: 0 7px 8px -4px rgba(137, 207, 255, 0.77);
+  --shadow-demo-dark-btn: 0 24px 18px -14px rgba(4, 154, 255, 0.24);
+
+  /* Animations */
+  --animate-fade-in: fade-in 300ms ease forwards;
+  --animate-bounce-in: bounceIn 0.75s cubic-bezier(0.215, 0.61, 0.355, 1) forwards;
+  --animate-selection-bounce: selectionBounce 0.75s cubic-bezier(0.215, 0.61, 0.355, 1) forwards;
+  --animate-button-clicked: buttonClicked 0.75s cubic-bezier(0.215, 0.61, 0.355, 1) forwards;
+  --animate-panel-showing: panelShowing 100ms ease;
+  --animate-panel-showing-mobile: panelShowingMobile 250ms ease;
+  --animate-wobble: wobble 400ms;
+  --animate-rotation: rotation 1.2s infinite linear;
+  --animate-notify-bounce-in: notifyBounceIn 600ms 1;
+
+  /* Keyframes */
+  @keyframes fade-in {
+    from { opacity: 0; }
+    to { opacity: 1; }
   }
 
-  .blok-inline-tool-button--active {
-    @apply bg-icon-active-bg text-icon-active-text;
+  @keyframes bounceIn {
+    0% { transform: scale3d(0.9, 0.9, 0.9); }
+    20% { transform: scale3d(1.03, 1.03, 1.03); }
+    60%, 100% { transform: scale3d(1, 1, 1); }
   }
 
-  /* 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;
+  @keyframes selectionBounce {
+    0%, 100% { transform: scale3d(1, 1, 1); }
+    50% { transform: scale3d(1.01, 1.01, 1.01); }
+    70% { transform: scale3d(1, 1, 1); }
   }
 
-  /* 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;
+  @keyframes buttonClicked {
+    0% { transform: scale3d(0.95, 0.95, 0.95); }
+    60% { transform: scale3d(1.02, 1.02, 1.02); }
+    80%, 100% { transform: scale3d(1, 1, 1); }
   }
 
-  /* 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;
+  @keyframes panelShowing {
+    from { opacity: 0; transform: translateY(-8px) scale(0.9); }
+    70% { opacity: 1; transform: translateY(2px); }
+    to { transform: translateY(0); }
   }
 
-  /* 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;
+  @keyframes panelShowingMobile {
+    from { opacity: 0; transform: translateY(14px) scale(0.98); }
+    70% { opacity: 1; transform: translateY(-4px); }
+    to { transform: translateY(0); }
   }
 
-  .blok-settings-button--active {
-    @apply text-active-icon;
+  @keyframes wobble {
+    from { transform: translate3d(0, 0, 0); }
+    15% { transform: translate3d(-9%, 0, 0); }
+    30% { transform: translate3d(9%, 0, 0); }
+    45% { transform: translate3d(-4%, 0, 0); }
+    60% { transform: translate3d(4%, 0, 0); }
+    75% { transform: translate3d(-1%, 0, 0); }
+    to { transform: translate3d(0, 0, 0); }
   }
 
-  .blok-settings-button--focused {
-    @apply shadow-button-focused bg-item-focus-bg;
+  @keyframes rotation {
+    0% { transform: rotate(0deg); }
+    100% { transform: rotate(360deg); }
   }
 
-  .blok-settings-button--focused-animated {
-    @apply animate-button-clicked;
+  @keyframes notifyBounceIn {
+    0% { opacity: 0; transform: scale(0.3); }
+    50% { opacity: 1; transform: scale(1.05); }
+    70% { transform: scale(0.9); }
+    100% { transform: scale(1); }
   }
 }
 
+/*
+  The default border color has changed to `currentcolor` in Tailwind CSS v4,
+  so we've added these compatibility styles to make sure everything still
+  looks the same as it did with Tailwind CSS v3.
+
+  If we ever want to remove these styles, we need to add an explicit border
+  color utility to any element that depends on these defaults.
+*/
+*,
+::after,
+::before,
+::backdrop,
+::file-selector-button {
+  border-color: var(--color-gray-200, currentcolor);
+}
+
+/**
+ * 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.
+ */
+@utility blok-block {
+  /* Base Blok styles - applied to block tool wrappers */
+  @apply py-[3px] px-[2px] [&::-webkit-input-placeholder]:leading-normal!;
+}
+@utility blok-inline-tool-button {
+  /* Inline Tools styles */
+  @apply flex justify-center items-center border-0 rounded-sm h-full p-0 w-7 bg-transparent cursor-pointer leading-normal text-black;
+}
+@utility blok-inline-tool-button--active {
+  @apply bg-icon-active-bg text-icon-active-text;
+}
+@utility blok-input {
+  /* Input element styles */
+  @apply w-full rounded-[3px] border border-line-gray px-3 py-2.5 outline-hidden 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;
+}
+@utility blok-loader {
+  /* Loader styles with spinning animation */
+  @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;
+}
+@utility blok-button {
+  /* Button styles */
+  @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;
+}
+@utility blok-settings-button {
+  /* Settings button styles */
+  @apply inline-flex items-center justify-center rounded-[3px] cursor-pointer border-0 outline-hidden 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;
+}
+@utility blok-settings-button--active {
+  @apply text-active-icon;
+}
+@utility blok-settings-button--focused {
+  @apply shadow-button-focused bg-item-focus-bg;
+}
+@utility blok-settings-button--focused-animated {
+  @apply animate-button-clicked;
+}
+
 /**
  * Navigation mode styles
  * Applied when user enters block navigation mode via Escape key
@@ -84,7 +254,7 @@
 }
 
 [data-drop-indicator]::before {
-  @apply content-[''] absolute w-full max-w-content h-1.5 rounded-sm bg-[#d4e3fc] pointer-events-none z-10;
+  @apply content-[''] absolute w-full max-w-content h-1.5 rounded-xs bg-[#d4e3fc] pointer-events-none z-10;
   left: 50%;
   margin-left: calc(var(--drop-indicator-depth, 0) * 12px);
   max-width: calc(650px - var(--drop-indicator-depth, 0) * 24px);
@@ -135,7 +305,7 @@
 }
 
 [data-blok-table-cell-blocks] .blok-block {
-  @apply p-0 m-0;
+  @apply p-0 m-0 min-h-[1.6em];
 }
 
 /**
@@ -146,3 +316,11 @@
 [data-blok-table-heading-col] {
   @apply font-semibold bg-gray-50;
 }
+
+/**
+ * Table scroll haze overlays
+ * Gradient indicators that show horizontal scroll availability
+ */
+[data-blok-table-haze][data-blok-table-haze-visible] {
+  @apply opacity-100;
+}

package/src/tools/header/index.ts

@@ -19,10 +19,12 @@ import type {
 } from '../../../types';
 import type { MenuConfig } from '../../../types/tools/menu-config';
 import { DATA_ATTR } from '../../components/constants';
-import { IconH1, IconH2, IconH3, IconH4, IconH5, IconH6, IconHeading } from '../../components/icons';
+import { IconH1, IconH2, IconH3, IconH4, IconH5, IconH6, IconHeading, IconToggleH1, IconToggleH2, IconToggleH3 } from '../../components/icons';
 import { PLACEHOLDER_CLASSES, setupPlaceholder } from '../../components/utils/placeholder';
 import { translateToolTitle } from '../../components/utils/tools';
 import { twMerge } from '../../components/utils/tw';
+import { ARROW_ICON, ARROW_STYLES, TOGGLE_ATTR, TOGGLE_WRAPPER_STYLES } from '../toggle/constants';
+import { updateArrowState, updateChildrenVisibility } from '../toggle/toggle-lifecycle';
 
 /**
  * Tool's input and output data format
@@ -32,6 +34,8 @@ export interface HeaderData extends BlockToolData {
   text: string;
   /** Header's level from 1 to 6 */
   level: number;
+  /** Whether this header has toggle (collapse/expand) behavior */
+  isToggleable?: boolean;
 }
 
 /**
@@ -125,6 +129,21 @@ export class Header implements BlockTool {
    */
   private _element: HTMLHeadingElement;
 
+  /**
+   * Arrow element for toggle heading
+   */
+  private _arrowElement: HTMLElement | null = null;
+
+  /**
+   * Whether the toggle is currently open (expanded)
+   */
+  private _isOpen: boolean = false;
+
+  /**
+   * Block ID from the editor
+   */
+  private blockId?: string;
+
   /**
    * Render plugin's main Element and fill it with saved data
    *
@@ -133,20 +152,25 @@ export class Header implements BlockTool {
    * @param options.config - user config for Tool
    * @param options.api - Editor API
    * @param options.readOnly - read only mode flag
+   * @param options.block - block instance
    */
-  constructor({ data, config, api, readOnly }: BlockToolConstructorOptions<HeaderData, HeaderConfig>) {
+  constructor({ data, config, api, readOnly, block }: BlockToolConstructorOptions<HeaderData, HeaderConfig>) {
     this.api = api;
     this.readOnly = readOnly;
 
     this._settings = config || {};
     this._data = this.normalizeData(data);
     this._element = this.getTag();
+
+    if (block) {
+      this.blockId = block.id;
+    }
   }
 
   /**
    * Base styles for all header levels
    */
-  private static readonly BASE_STYLES = 'py-[3px] px-[2px] m-0 !leading-[1.3] outline-none [&_p]:!p-0 [&_p]:!m-0 [&_div]:!p-0 [&_div]:!m-0';
+  private static readonly BASE_STYLES = 'py-[3px] px-[2px] m-0 leading-[1.3]! outline-hidden [&_p]:p-0! [&_p]:m-0! [&_div]:p-0! [&_div]:m-0!';
 
   /**
    * Styles
@@ -183,10 +207,16 @@ export class Header implements BlockTool {
     const parsedLevel = parseInt(String(data.level));
     const isValidLevel = data.level !== undefined && !isNaN(parsedLevel);
 
-    return {
+    const normalized: HeaderData = {
       text: data.text || '',
       level: isValidLevel ? parsedLevel : this.defaultLevel.number,
     };
+
+    if (data.isToggleable === true) {
+      normalized.isToggleable = true;
+    }
+
+    return normalized;
   }
 
   /**
@@ -198,6 +228,16 @@ export class Header implements BlockTool {
     return this._element;
   }
 
+  /**
+   * Called after the block is rendered in the DOM.
+   * Hides children if the toggle heading is collapsed.
+   */
+  public rendered(): void {
+    if (this._data.isToggleable) {
+      this.updateChildrenVisibility();
+    }
+  }
+
   /**
    * Returns header block tunes config
    *
@@ -219,28 +259,40 @@ export class Header implements BlockTool {
       toolboxEntries[0].data === undefined &&
       (toolboxEntries[0].title === undefined || toolboxEntries[0].title === 'Heading');
 
-    if (toolboxEntries !== undefined && toolboxEntries.length > 0 && !isDefaultToolboxEntry) {
-      return this.buildSettingsFromToolboxEntries(toolboxEntries);
-    }
+    const levelSettings: MenuConfig = toolboxEntries !== undefined && toolboxEntries.length > 0 && !isDefaultToolboxEntry
+      ? this.buildSettingsFromToolboxEntries(toolboxEntries)
+      : this.levels.map(level => {
+        const translated = this.api.i18n.t(level.nameKey);
+        const title = translated !== level.nameKey ? translated : level.name;
+
+        return {
+          icon: level.icon,
+          title,
+          onActivate: (): void => this.setLevel(level.number),
+          closeOnActivate: true,
+          isActive: this.currentLevel.number === level.number,
+          dataset: {
+            'blok-header-level': String(level.number),
+          },
+        };
+      });
+
+    const settingsArray = Array.isArray(levelSettings) ? levelSettings : [levelSettings];
 
     /**
-     * Fall back to existing behavior using levels config
+     * Add toggle heading option
      */
-    return this.levels.map(level => {
-      const translated = this.api.i18n.t(level.nameKey);
-      const title = translated !== level.nameKey ? translated : level.name;
-
-      return {
-        icon: level.icon,
-        title,
-        onActivate: (): void => this.setLevel(level.number),
-        closeOnActivate: true,
-        isActive: this.currentLevel.number === level.number,
-        dataset: {
-          'blok-header-level': String(level.number),
-        },
-      };
+    const toggleHeadingTitle = this.api.i18n.t('tools.header.toggleHeading');
+
+    settingsArray.push({
+      icon: ARROW_ICON,
+      title: toggleHeadingTitle !== 'tools.header.toggleHeading' ? toggleHeadingTitle : 'Toggle heading',
+      onActivate: (): void => this.toggleIsToggleable(),
+      closeOnActivate: true,
+      isActive: this._data.isToggleable === true,
     });
+
+    return settingsArray;
   }
 
   /**
@@ -294,6 +346,7 @@ export class Header implements BlockTool {
     this.data = {
       level: level,
       text: this.data.text,
+      isToggleable: this._data.isToggleable,
     };
   }
 
@@ -325,10 +378,16 @@ export class Header implements BlockTool {
    * @returns saved data
    */
   public save(toolsContent: HTMLHeadingElement): HeaderData {
-    return {
+    const data: HeaderData = {
       text: toolsContent.innerHTML,
       level: this.currentLevel.number,
     };
+
+    if (this._data.isToggleable === true) {
+      data.isToggleable = true;
+    }
+
+    return data;
   }
 
   /**
@@ -348,6 +407,7 @@ export class Header implements BlockTool {
     return {
       level: false,
       text: {},
+      isToggleable: false,
     };
   }
 
@@ -414,6 +474,27 @@ export class Header implements BlockTool {
     if (data.text !== undefined) {
       this._element.innerHTML = this._data.text || '';
     }
+
+    /**
+     * Re-add toggle arrow after innerHTML assignments (which destroy it).
+     * Also update toggle styles and attributes.
+     */
+    if (this._data.isToggleable) {
+      this._element.setAttribute(TOGGLE_ATTR.toggleOpen, String(this._isOpen));
+
+      if (!this._element.querySelector(`[${TOGGLE_ATTR.toggleArrow}]`)) {
+        const arrow = this.buildArrow();
+
+        this._arrowElement = arrow;
+        this._element.prepend(arrow);
+      }
+
+      this._element.className = twMerge(Header.BASE_STYLES, this.currentLevel.styles, PLACEHOLDER_CLASSES, TOGGLE_WRAPPER_STYLES);
+    } else {
+      this._element.removeAttribute(TOGGLE_ATTR.toggleOpen);
+      this._arrowElement = null;
+      this._element.className = twMerge(Header.BASE_STYLES, this.currentLevel.styles, PLACEHOLDER_CLASSES);
+    }
   }
 
   /**
@@ -434,9 +515,10 @@ export class Header implements BlockTool {
     tag.innerHTML = this._data.text || '';
 
     /**
-     * Add styles class using twMerge to combine base and level-specific styles
+     * Add styles class using twMerge to combine base and level-specific styles.
+     * When isToggleable, add flex layout to align arrow and text.
      */
-    tag.className = twMerge(Header.BASE_STYLES, this.currentLevel.styles, PLACEHOLDER_CLASSES);
+    tag.className = twMerge(Header.BASE_STYLES, this.currentLevel.styles, PLACEHOLDER_CLASSES, this._data.isToggleable ? TOGGLE_WRAPPER_STYLES : '');
 
     /**
      * Apply inline styles for custom overrides (dynamic values from config)
@@ -457,6 +539,17 @@ export class Header implements BlockTool {
      */
     tag.contentEditable = this.readOnly ? 'false' : 'true';
 
+    /**
+     * Add toggle arrow if isToggleable
+     */
+    if (this._data.isToggleable) {
+      tag.setAttribute(TOGGLE_ATTR.toggleOpen, String(this._isOpen));
+
+      const arrow = this.buildArrow();
+      this._arrowElement = arrow;
+      tag.prepend(arrow);
+    }
+
     /**
      * Add Placeholder with caret positioning support
      */
@@ -469,6 +562,71 @@ export class Header implements BlockTool {
     return tag;
   }
 
+  /**
+   * Build the arrow element for toggle heading.
+   *
+   * @returns The arrow element
+   */
+  private buildArrow(): HTMLElement {
+    const arrow = document.createElement('div');
+    arrow.className = ARROW_STYLES;
+    arrow.setAttribute(TOGGLE_ATTR.toggleArrow, '');
+    arrow.setAttribute('role', 'button');
+    arrow.setAttribute('tabindex', '-1');
+    arrow.setAttribute('aria-label', 'Expand');
+    arrow.contentEditable = 'false';
+    arrow.innerHTML = ARROW_ICON;
+
+    if (this._isOpen) {
+      arrow.style.transform = 'rotate(90deg)';
+    }
+
+    arrow.addEventListener('click', (event: MouseEvent) => {
+      event.stopPropagation();
+      this.toggleOpen();
+    });
+
+    return arrow;
+  }
+
+  /**
+   * Toggle the isToggleable state on/off.
+   * Called from the settings menu.
+   */
+  private toggleIsToggleable(): void {
+    const wasToggleable = this._data.isToggleable === true;
+
+    this.data = {
+      level: this._data.level,
+      text: this._data.text,
+      isToggleable: !wasToggleable || undefined,
+    };
+  }
+
+  /**
+   * Toggle the open/closed state of the toggle heading.
+   */
+  private toggleOpen(): void {
+    this._isOpen = !this._isOpen;
+
+    if (this._arrowElement && this._element) {
+      updateArrowState(this._arrowElement, this._element, this._isOpen);
+    }
+
+    this.updateChildrenVisibility();
+  }
+
+  /**
+   * Show or hide child blocks based on the toggle's open state.
+   */
+  private updateChildrenVisibility(): void {
+    if (this.blockId === undefined) {
+      return;
+    }
+
+    updateChildrenVisibility(this.api, this.blockId, this._isOpen);
+  }
+
   /**
    * Get current level
    *
@@ -636,7 +794,7 @@ export class Header implements BlockTool {
    * @returns ToolboxConfig array with entries for H1-H6
    */
   public static get toolbox(): ToolboxConfig {
-    return Header.DEFAULT_LEVELS.map(level => ({
+    const headingEntries = Header.DEFAULT_LEVELS.map(level => ({
       icon: level.icon,
       title: level.name,
       titleKey: level.nameKey,
@@ -645,5 +803,25 @@ export class Header implements BlockTool {
       searchTerms: [`h${level.number}`, 'title', 'header', 'heading'],
       shortcut: '#'.repeat(level.number),
     }));
+
+    const toggleHeadingIcons: Record<number, string> = {
+      1: IconToggleH1,
+      2: IconToggleH2,
+      3: IconToggleH3,
+    };
+
+    const toggleHeadingEntries = Header.DEFAULT_LEVELS
+      .filter(level => level.number <= 3)
+      .map(level => ({
+        icon: toggleHeadingIcons[level.number],
+        title: `Toggle heading ${level.number}`,
+        titleKey: `tools.header.toggleHeading${level.number}`,
+        name: `toggle-header-${level.number}`,
+        data: { level: level.number, isToggleable: true },
+        searchTerms: ['toggle', 'heading', `h${level.number}`, 'collapsible'],
+      }));
+
+    return [...headingEntries, ...toggleHeadingEntries];
   }
+
 }