@jackuait/blok 0.19.0 → 0.19.2

package/src/tools/audio/index.ts

@@ -52,6 +52,8 @@ export class AudioTool implements BlockTool {
   private controlsHandle: ControlsHandle | null = null;
   private waveformHandle: WaveformHandle | null = null;
   private destroyed = false;
+  /** Pending fallback timer for the caption collapse-out animation. */
+  private captionExitTimer: ReturnType<typeof setTimeout> | null = null;
 
   constructor(options: BlockToolConstructorOptions<AudioData, AudioConfig>) {
     this.api = options.api;
@@ -199,6 +201,7 @@ export class AudioTool implements BlockTool {
 
   public removed(): void {
     this.destroyed = true;
+    if (this.captionExitTimer) { clearTimeout(this.captionExitTimer); this.captionExitTimer = null; }
     this.controlsHandle?.destroy();
     this.controlsHandle = null;
     this.waveformHandle?.destroy();
@@ -299,6 +302,7 @@ export class AudioTool implements BlockTool {
 
   private renderState(): void {
     if (!this.root) return;
+    if (this.captionExitTimer) { clearTimeout(this.captionExitTimer); this.captionExitTimer = null; }
     this.controlsHandle?.destroy();
     this.controlsHandle = null;
     this.waveformHandle?.destroy();
@@ -393,14 +397,9 @@ export class AudioTool implements BlockTool {
     body.appendChild(this.controlsHandle.element);
 
     // Caption row — outside body, below the card
-    const placeholder = this.config.captionPlaceholder ?? DEFAULT_CAPTION_PLACEHOLDER;
     const captionVisible = this.data.captionVisible !== false;
-    if (captionVisible || !this.readOnly) {
-      figure.appendChild(renderCaptionRow({
-        value: this.data.caption ?? '',
-        placeholder,
-        editable: !this.readOnly,
-      }));
+    if (captionVisible) {
+      figure.appendChild(this.createCaptionRow());
     }
 
     // Wire title/artist blur handlers
@@ -419,21 +418,32 @@ export class AudioTool implements BlockTool {
       }
     });
 
-    // Wire caption blur handler
-    const captionEl = figure.querySelector<HTMLElement>('[data-role="audio-caption"]');
-    if (captionEl) {
-      captionEl.addEventListener('blur', () => {
-        const next = captionEl.textContent ?? '';
-        if (next !== this.data.caption) {
-          this.data.caption = next || undefined;
-          this.block.dispatchChange();
-        }
-      });
-    }
-
     this.root.appendChild(figure);
   }
 
+  /** Build a caption row (with its blur handler wired) ready to mount. */
+  private createCaptionRow(): HTMLElement {
+    const placeholder = this.config.captionPlaceholder ?? DEFAULT_CAPTION_PLACEHOLDER;
+    const row = renderCaptionRow({
+      value: this.data.caption ?? '',
+      placeholder,
+      editable: !this.readOnly,
+    });
+    const captionEl = row.querySelector<HTMLElement>('[data-role="audio-caption"]');
+    captionEl?.addEventListener('blur', () => {
+      const next = captionEl.textContent ?? '';
+      if (next !== this.data.caption) {
+        this.data.caption = next || undefined;
+        this.block.dispatchChange();
+      }
+    });
+    return row;
+  }
+
+  private prefersReducedMotion(): boolean {
+    return globalThis.matchMedia?.('(prefers-reduced-motion: reduce)').matches ?? false;
+  }
+
   private setAlignment(next: AudioAlignment): void {
     if (this.data.alignment === next) return;
     this.data.alignment = next;
@@ -442,9 +452,54 @@ export class AudioTool implements BlockTool {
   }
 
   private toggleCaption(): void {
-    this.data.captionVisible = this.data.captionVisible === false;
+    const enabling = this.data.captionVisible === false;
+    this.data.captionVisible = enabling;
+    // Removing the caption clears its text too, so re-enabling starts fresh
+    // rather than resurrecting the old text.
+    if (!enabling) this.data.caption = undefined;
     this.block.dispatchChange();
-    this.renderState();
+
+    const figure = this.root?.querySelector<HTMLElement>('[data-role="audio-figure"]');
+    // No live card to animate (or motion is off) — fall back to an instant
+    // re-render so the caption snaps in/out.
+    if (!figure || this.prefersReducedMotion()) {
+      this.renderState();
+      return;
+    }
+    this.syncRootAttributes();
+    if (enabling) this.animateCaptionIn(figure);
+    else this.animateCaptionOut(figure);
+  }
+
+  private animateCaptionIn(figure: HTMLElement): void {
+    const existing = figure.querySelector<HTMLElement>('[data-role="audio-caption-row"]');
+    if (existing) {
+      // A collapse-out was mid-flight — cancel it and re-open in place.
+      if (this.captionExitTimer) { clearTimeout(this.captionExitTimer); this.captionExitTimer = null; }
+      existing.classList.remove('is-collapsed');
+      return;
+    }
+    const row = this.createCaptionRow();
+    row.classList.add('is-collapsed');
+    figure.appendChild(row);
+    // Force a reflow so the collapsed state is committed, then expand into view.
+    void row.offsetHeight;
+    row.classList.remove('is-collapsed');
+  }
+
+  private animateCaptionOut(figure: HTMLElement): void {
+    const row = figure.querySelector<HTMLElement>('[data-role="audio-caption-row"]');
+    if (!row) return;
+    row.classList.add('is-collapsed');
+    const finish = (): void => {
+      if (this.captionExitTimer) { clearTimeout(this.captionExitTimer); this.captionExitTimer = null; }
+      row.remove();
+    };
+    row.addEventListener('transitionend', (e) => {
+      if (e.propertyName === 'grid-template-rows') finish();
+    }, { once: true });
+    // Fallback in case transitionend never fires (display:none, interrupted, etc.).
+    this.captionExitTimer = setTimeout(finish, 360);
   }
 
   private toggleLoop(): void {

package/src/tools/audio/ui.ts

@@ -97,8 +97,13 @@ export function renderCaptionRow(opts: CaptionRowOptions): HTMLElement {
   const row = document.createElement('div');
   row.className = 'blok-audio-caption-row';
   row.setAttribute('data-role', 'audio-caption-row');
+  // Inner wrapper carries the visible layout (padding/border) so the row itself
+  // can collapse cleanly via grid-template-rows when toggled.
+  const inner = document.createElement('div');
+  inner.className = 'blok-audio-caption-row__inner';
   const cap = editableLine('audio-caption', opts.value, opts.editable, opts.placeholder);
   cap.className = 'blok-audio-caption';
-  row.appendChild(cap);
+  inner.appendChild(cap);
+  row.appendChild(inner);
   return row;
 }

package/types/api/tooltip.d.ts

@@ -1,7 +1,46 @@
 /**
  * Tooltip API
  */
-import {TooltipContent, TooltipOptions} from '../../src/components/utils/tooltip';
+
+/**
+ * Tooltip supported content
+ */
+export type TooltipContent = HTMLElement | DocumentFragment | Node | string;
+
+/**
+ * Base options interface for tooltips
+ */
+export interface TooltipOptions {
+  /**
+   * Tooltip placement: top|bottom|left|right
+   */
+  placement?: string;
+
+  /**
+   * Tooltip top margin
+   */
+  marginTop?: number;
+
+  /**
+   * Tooltip left margin
+   */
+  marginLeft?: number;
+
+  /**
+   * Tooltip right margin
+   */
+  marginRight?: number;
+
+  /**
+   * Tooltip bottom margin
+   */
+  marginBottom?: number;
+
+  /**
+   * Timeout before showing
+   */
+  delay?: number;
+}
 
 export interface Tooltip {
   /**

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

@@ -6,9 +6,12 @@ import { BlockId } from './block-id';
  * Output of one Tool
  *
  * @template Type - the string literal describing a tool type
- * @template Data - the structure describing a data object supported by the tool
+ * @template Data - the structure describing a data object supported by the tool.
+ *   Defaults to `Record<string, unknown>` (matching {@link BlockToolData}) so
+ *   reading saved block data is type-guarded: property access yields `unknown`,
+ *   not `any`. Pass a concrete shape for fully-typed access.
  */
-export interface OutputBlockData<Type extends string = string, Data extends object = any> {
+export interface OutputBlockData<Type extends string = string, Data extends object = Record<string, unknown>> {
   /**
    * Unique Id of the block
    */

package/types/index.d.ts

@@ -5,12 +5,11 @@
  */
 
 import {
-  Dictionary,
-  DictValue,
   BlokConfig,
   I18nConfig,
   I18nDictionary,
 } from './configs';
+import { InlineToolConstructable, InlineToolConstructorOptions } from './tools';
 
 import {
   Blocks,
@@ -81,8 +80,6 @@ export {
   LogLevels,
   ConversionConfig,
   I18nDictionary,
-  Dictionary,
-  DictValue,
   I18nConfig,
   UserInfo,
 } from './configs';
@@ -207,11 +204,37 @@ export function wrapLegacyInlineTool(
   }
 ): InlineToolConstructable;
 
+/**
+ * The surface of a Blok instance that is guaranteed to exist synchronously,
+ * immediately after `new Blok()` and before `isReady` has resolved.
+ *
+ * Blok constructs its module APIs (`blocks`, `caret`, `history`, `readOnly`, …)
+ * asynchronously: they only become available once `isReady` resolves. Accessing
+ * them earlier returns `undefined` at runtime. Type a reference you hold during
+ * that window as `PendingBlok` so the not-yet-available members are unreachable,
+ * then await `isReady` to obtain the fully-initialized {@link Blok}:
+ *
+ * @example
+ * const pending: PendingBlok = new Blok(config);
+ * const editor = await pending.isReady; // editor is a ready Blok
+ * editor.blocks.render(data);
+ */
+export interface PendingBlok {
+  /** Resolves with the fully-initialized Blok instance once core modules are ready. */
+  isReady: Promise<Blok>;
+  /** Destroy the instance. Safe to call before `isReady` resolves. */
+  destroy(): void;
+  /** Theme API, exposed immediately after construction. */
+  theme: Theme;
+  /** Width API, exposed immediately after construction. */
+  width: Width;
+}
+
 /**
  * Main Blok class
  */
 export class Blok {
-  public isReady: Promise<void>;
+  public isReady: Promise<Blok>;
 
   public blocks: Blocks;
   public caret: Caret;

package/types/tools/database.d.ts

@@ -1,4 +1,4 @@
-import { BlockToolData } from './block-tool';
+import { BlockToolData } from './block-tool-data';
 import { OutputData } from '../data-formats/output-data';
 
 // ─── Property types ───

package/types/tools/header.d.ts

@@ -1,4 +1,5 @@
-import { BlockTool, BlockToolConstructable, BlockToolConstructorOptions, BlockToolData } from './block-tool';
+import { BlockTool, BlockToolConstructable, BlockToolConstructorOptions } from './block-tool';
+import { BlockToolData } from './block-tool-data';
 import { MenuConfig } from './menu-config';
 
 /**

package/types/tools/list.d.ts

@@ -1,4 +1,5 @@
-import { BlockTool, BlockToolConstructable, BlockToolConstructorOptions, BlockToolData } from './block-tool';
+import { BlockTool, BlockToolConstructable, BlockToolConstructorOptions } from './block-tool';
+import { BlockToolData } from './block-tool-data';
 import { MenuConfig } from './menu-config';
 
 /**

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

@@ -1,7 +1,48 @@
 import { PopoverItemParams } from './popover-item';
-import type { Flipper } from '../../../src/components/flipper';
 import { PopoverEvent } from './popover-event';
 
+/**
+ * Public surface of the internal keyboard-navigation Flipper that a popover
+ * exposes for reuse via {@link PopoverParams.flipper}.
+ *
+ * Declared structurally here (rather than imported from raw src) so the
+ * published declarations stay self-contained: a bare `import` of the package
+ * must never drag Blok's `.ts` source into a consumer's type program. The
+ * concrete Flipper is internal — consumers never construct it; it is only
+ * passed between Blok's own popovers.
+ */
+export interface Flipper {
+  /** True while the flipper is handling keyboard navigation. */
+  readonly isActivated: boolean;
+
+  /** Begin handling keyboard navigation over the given items. */
+  activate(items?: HTMLElement[], cursorPosition?: number): void;
+
+  /** Stop handling keyboard navigation. */
+  deactivate(): void;
+
+  /** Focus the first navigable item. */
+  focusFirst(): void;
+
+  /** Focus the item at the given position. */
+  focusItem(position: number, options?: { skipNextTab?: boolean }): void;
+
+  /** True if a navigable item currently has focus. */
+  hasFocus(): boolean;
+
+  /** Register a callback fired on each flip (navigation step). */
+  onFlip(cb: () => void): void;
+
+  /** Remove a previously registered flip callback. */
+  removeOnFlip(cb: () => void): void;
+
+  /** Toggle handling of keydown events originating from contenteditable targets. */
+  setHandleContentEditableTargets(value: boolean): void;
+
+  /** Whether keydown events from contenteditable targets are handled. */
+  getHandleContentEditableTargets(): boolean;
+}
+
 /**
  * Params required to render popover
  */