@jackuait/blok 0.19.1 → 0.20.0

package/src/components/modules/paste/notion-preprocessor.ts

@@ -0,0 +1,67 @@
+/**
+ * Pre-process Notion clipboard HTML before sanitization.
+ *
+ * Notion encodes block/inline state with classes (`to-do-list`, `checkbox-on`,
+ * `toggle`, `callout`, `block-color-*`) and non-semantic markup that Blok's
+ * sanitizer strips.  This function rewrites that markup into Blok's allowed
+ * semantic tag set BEFORE the sanitizer runs.  It mirrors
+ * `preprocessGoogleDocsHtml` and is a no-op when the source is not Notion.
+ *
+ * Scope note: this is the HTML *fallback* path (Notion desktop app /
+ * cross-browser paste).  The higher-fidelity path parses Notion's proprietary
+ * `text/_notion-blocks-v3-production` JSON flavor directly when present
+ * (web→web); see docs/plans/2026-06-22-notion-paste-migration-design.md §4.1b.
+ *
+ * @param html - raw clipboard HTML string
+ * @returns preprocessed HTML string (unchanged when not Notion)
+ */
+export function preprocessNotionHtml(html: string): string {
+  const wrapper = document.createElement('div');
+
+  wrapper.innerHTML = html;
+
+  if (!isNotionClipboard(wrapper)) {
+    return html;
+  }
+
+  normalizeInlineMarks(wrapper);
+
+  return wrapper.innerHTML;
+}
+
+/**
+ * Centralized Notion clipboard signature.  This is the ONE place to update
+ * when Notion changes its class names.
+ */
+const NOTION_SIGNATURE_SELECTOR = [
+  'figure.callout',
+  'ul.to-do-list',
+  'ul.toggle',
+  'ol.numbered-list',
+  'ul.bulleted-list',
+  '.notion-text-equation-token',
+  '[class*="block-color-"]',
+  'figure.equation',
+].join(', ');
+
+/**
+ * Whether the pasted markup originated from Notion.
+ */
+function isNotionClipboard(wrapper: HTMLElement): boolean {
+  return wrapper.querySelector(NOTION_SIGNATURE_SELECTOR) !== null;
+}
+
+/**
+ * Rewrite inline marks that Blok's sanitizer strips into allowed equivalents.
+ *
+ * Notion emits strikethrough as `<del>`/`<strike>`, but Blok's strikethrough
+ * inline tool only whitelists `<s>` — so the others are dropped unless rewritten.
+ */
+function normalizeInlineMarks(wrapper: HTMLElement): void {
+  wrapper.querySelectorAll('del, strike').forEach((el) => {
+    const s = document.createElement('s');
+
+    s.innerHTML = el.innerHTML;
+    el.replaceWith(s);
+  });
+}

package/src/components/modules/yjs/serializer.ts

@@ -6,7 +6,7 @@ import type { OutputBlockData } from '../../../../types/data-formats/output-data
  * Type alias for OutputBlockData with concrete types for the Yjs serializer.
  * Uses Record<string, unknown> for data to avoid the default `any` type.
  */
-export type YjsOutputBlockData = OutputBlockData<string, Record<string, unknown>>;
+export type YjsOutputBlockData = OutputBlockData;
 
 /**
  * Characters that mark potential undo checkpoint positions.

package/src/components/utils/data-model-transform.ts

@@ -33,7 +33,7 @@ type LegacyListItem = LegacyListItemObject | OldChecklistItem | string;
 /**
  * Legacy list data structure for data model transformation.
  */
-interface LegacyListData {
+type LegacyListData = {
   style: 'unordered' | 'ordered' | 'checklist';
   items: LegacyListItem[];
   start?: number;
@@ -45,7 +45,7 @@ interface LegacyListData {
  * Blok has no dedicated checklist tool — checklist is a style of the List tool —
  * so this is expanded into per-item flat `list` blocks with style 'checklist'.
  */
-interface LegacyChecklistData {
+type LegacyChecklistData = {
   items: LegacyListItem[];
 }
 
@@ -54,7 +54,7 @@ interface LegacyChecklistData {
  * Old format: { type: "linkTool", data: { link, meta: { title, description, image: { url }, favicon, domain } } }
  * Maps to Blok's flat Bookmark data shape (see types BookmarkMeta).
  */
-interface LegacyLinkToolData {
+type LegacyLinkToolData = {
   link: string;
   meta?: {
     title?: string;
@@ -70,7 +70,7 @@ interface LegacyLinkToolData {
  * Legacy toggle list data structure for data model transformation.
  * Old format: { title: string, isExpanded?: boolean, body: { blocks: [], time, version }, titleVariant?: number }
  */
-interface LegacyToggleListData {
+type LegacyToggleListData = {
   title: string;
   isExpanded?: boolean;
   titleVariant?: number;
@@ -85,7 +85,7 @@ interface LegacyToggleListData {
  * Legacy callout data structure for data model transformation.
  * Old format: { title?: string, body: { blocks: [] } | null, variant, emoji, isEmojiVisible }
  */
-interface LegacyCalloutData {
+type LegacyCalloutData = {
   title?: string;
   body?: {
     blocks?: OutputBlockData[];
@@ -311,7 +311,7 @@ const isLegacyToggleListBlock = (block: OutputBlockData): block is OutputBlockDa
     return false;
   }
 
-  const data = block.data as Record<string, unknown>;
+  const data = block.data;
 
   return typeof data === 'object' && data !== null && 'title' in data;
 };
@@ -326,7 +326,7 @@ const isLegacyCalloutBlock = (block: OutputBlockData): block is OutputBlockData<
     return false;
   }
 
-  const data = block.data as Record<string, unknown>;
+  const data = block.data;
 
   return typeof data === 'object' && data !== null && 'body' in data;
 };
@@ -761,7 +761,7 @@ const expandCalloutToHierarchical = (
  * can't silently lose information.
  */
 const expandImageToHierarchical = (block: OutputBlockData, warned: Set<string>): OutputBlockData => {
-  const rawData = (block.data ?? {}) as Record<string, unknown>;
+  const rawData = (block.data ?? {});
   const {
     file,
     url: flatUrl,
@@ -858,7 +858,7 @@ const expandLinkToolToHierarchical = (
 const expandQuoteToHierarchical = (block: OutputBlockData, warned: Set<string>): OutputBlockData[] => {
   warnLossyQuoteFields(block, warned);
 
-  const rawData = (block.data ?? {}) as Record<string, unknown>;
+  const rawData = (block.data ?? {});
   const { caption, alignment: _alignment, ...rest } = rawData;
 
   const quoteBlock: OutputBlockData = {
@@ -897,7 +897,7 @@ const expandQuoteToHierarchical = (block: OutputBlockData, warned: Set<string>):
  */
 const expandTableToHierarchical = (block: OutputBlockData): OutputBlockData[] => {
   const tableId = block.id ?? generateBlockId();
-  const rawData = (block.data ?? {}) as Record<string, unknown>;
+  const rawData = (block.data ?? {});
   const { content: _content, withHeadings, withHeadingColumn, stretched, ...restData } = rawData;
   const rows = getTableContentRows(rawData) ?? [];
   const childBlocks: OutputBlockData[] = [];
@@ -977,7 +977,7 @@ const WARNING_EMOJI = '⚠️';
  */
 const expandWarningToHierarchical = (block: OutputBlockData): OutputBlockData[] => {
   const calloutId = block.id ?? generateBlockId();
-  const data = (block.data ?? {}) as Record<string, unknown>;
+  const data = (block.data ?? {});
   const title = typeof data.title === 'string' ? data.title : '';
   const message = typeof data.message === 'string' ? data.message : '';
 
@@ -1021,7 +1021,7 @@ const expandWarningToHierarchical = (block: OutputBlockData): OutputBlockData[]
  * equivalent and is dropped + warned once per pass.
  */
 const expandAttachesToHierarchical = (block: OutputBlockData, warned: Set<string>): OutputBlockData => {
-  const data = (block.data ?? {}) as Record<string, unknown>;
+  const data = (block.data ?? {});
   const file = (typeof data.file === 'object' && data.file !== null ? data.file : {}) as Record<string, unknown>;
   const url = typeof file.url === 'string' ? file.url : '';
   const title = typeof data.title === 'string' ? data.title : undefined;
@@ -1389,7 +1389,7 @@ const isFlatModelCalloutBlock = (block: OutputBlockData): boolean => {
     return false;
   }
 
-  const data = block.data as Record<string, unknown>;
+  const data = block.data;
 
   return typeof data === 'object' && data !== null && !('body' in data);
 };
@@ -1404,7 +1404,7 @@ const processRootCalloutItem = (
 ): OutputBlockData => {
   markBlockAsProcessed(block.id, processedIds);
 
-  const data = block.data as Record<string, unknown>;
+  const data = block.data;
 
   // Map backgroundColor preset → variant
   const backgroundColor = data.backgroundColor as string | null | undefined;
@@ -1907,7 +1907,7 @@ export const reclaimDetachedTableCells = (blocks: OutputBlockData[]): OutputBloc
         });
       });
 
-      return { ...block, data: { ...(block.data as Record<string, unknown>), content: newContent } } as OutputBlockData;
+      return { ...block, data: { ...(block.data), content: newContent } } as OutputBlockData;
     }
 
     return block;

package/src/components/utils/media-empty-state.ts

@@ -48,8 +48,22 @@ export interface MediaEmptyStateOptions {
   labels: MediaEmptyStateLabels;
   onFile(file: File): void;
   onUrl(url: string): void;
+  /**
+   * How the panel transitions when switching Upload/Link tabs:
+   * - `'reflow'` (default): ease the panel height between the two layouts and
+   *   fade the incoming content in. Smooths the inline reflow of image/file
+   *   blocks, where content below the card shifts with the height.
+   * - `'slide'`: keep the height instant and slide + fade the incoming panel in
+   *   from the travel direction. A floating popover (audio cover-picker) has
+   *   nothing reflowing beneath it, so a height tween only reads as lag — the
+   *   directional slide gives the swap personality without the bottom-edge crawl.
+   * - `'none'`: swap instantly with no animation.
+   */
+  swap?: MediaEmptyStateSwap;
 }
 
+export type MediaEmptyStateSwap = 'reflow' | 'slide' | 'none';
+
 const MIME_LABELS: Record<string, string> = {
   'image/jpeg': 'JPG',
   'image/jpg': 'JPG',
@@ -170,6 +184,26 @@ function animatePanelSwap(panel: HTMLElement, startHeight: number): void {
   }
 }
 
+/**
+ * Slides the freshly-rendered panel content in from the travel direction while
+ * fading it up — `dir` is +1 when moving to a tab on the right, -1 to the left.
+ * The panel keeps its new height instantly; only the content moves, so there is
+ * no bottom-edge crawl (the part that read as lag in a floating popover).
+ */
+function animatePanelContent(panel: HTMLElement, dir: number): void {
+  const dx = dir * 12;
+  for (const child of Array.from(panel.children)) {
+    if (!canAnimate(child)) continue;
+    child.animate(
+      [
+        { opacity: 0, transform: `translateX(${dx}px)` },
+        { opacity: 1, transform: 'translateX(0)' },
+      ],
+      { duration: 200, easing: SWAP_EASING, fill: 'backwards' }
+    );
+  }
+}
+
 export function renderMediaEmptyState(opts: MediaEmptyStateOptions): MediaEmptyStateElement {
   const { labels } = opts;
   const types = opts.acceptTypes;
@@ -177,6 +211,8 @@ export function renderMediaEmptyState(opts: MediaEmptyStateOptions): MediaEmptyS
   const formats = formatsLabel(types);
   const sizeHint = opts.maxSize !== undefined ? formatBytes(opts.maxSize) : '';
 
+  const swapMode: MediaEmptyStateSwap = opts.swap ?? 'reflow';
+
   const root = document.createElement('div') as unknown as MediaEmptyStateElement;
   root.className = 'blok-media-empty';
   root.setAttribute('data-blok-media-empty-state', '');
@@ -349,10 +385,17 @@ export function renderMediaEmptyState(opts: MediaEmptyStateOptions): MediaEmptyS
     queueMicrotask(() => urlInput.focus());
   };
 
-  const activate = (kind: SourceKind, animate = false): void => {
-    const startHeight = animate && canAnimate(panel) && !prefersReducedMotion()
+  const activate = (kind: SourceKind, transition = false): void => {
+    const prevKind = card.getAttribute('data-active-tab') as SourceKind | null;
+    const motion = transition
+      && swapMode !== 'none'
+      && canAnimate(panel)
+      && !prefersReducedMotion();
+    // Capture the reflow start-height before the content swaps (height tween only).
+    const startHeight = motion && swapMode === 'reflow'
       ? panel.getBoundingClientRect().height
       : null;
+    const dir = prevKind ? Math.sign(tabKinds.indexOf(kind) - tabKinds.indexOf(prevKind)) : 0;
 
     const activeTab = tabList[tabKinds.indexOf(kind)];
     for (const tab of tabList) {
@@ -367,9 +410,9 @@ export function renderMediaEmptyState(opts: MediaEmptyStateOptions): MediaEmptyS
     if (kind === 'upload') renderUpload();
     else renderEmbed();
 
-    if (startHeight !== null) {
-      animatePanelSwap(panel, startHeight);
-    }
+    if (!motion) return;
+    if (swapMode === 'reflow' && startHeight !== null) animatePanelSwap(panel, startHeight);
+    else if (swapMode === 'slide') animatePanelContent(panel, dir);
   };
 
   tabList.forEach((tab, idx) => {

package/src/components/utils/popover/popover-desktop.ts

@@ -15,7 +15,7 @@ import { resolvePosition } from './popover-position';
 import { stripPopoverAttribute } from '../top-layer';
 import { twMerge } from '../tw';
 
-import type { PopoverParams } from '@/types/utils/popover/popover';
+import type { PopoverParams, Flipper as FlipperHandle } from '@/types/utils/popover/popover';
 import { PopoverEvent } from '@/types/utils/popover/popover-event';
 
 
@@ -51,9 +51,12 @@ if (typeof document !== 'undefined' && !(document as unknown as Record<string, u
  */
 export class PopoverDesktop extends PopoverAbstract {
   /**
-   * Flipper - module for keyboard iteration between elements
+   * Flipper - module for keyboard iteration between elements.
+   * Typed as the published structural handle so a reused flipper passed via
+   * params (also the handle type) assigns cleanly; `new Flipper()` is
+   * structurally assignable to it.
    */
-  public flipper: Flipper | undefined;
+  public flipper: FlipperHandle | undefined;
 
   /**
    * Popover nesting level. 0 value means that it is a root popover

package/src/components/utils/tooltip.ts

@@ -6,45 +6,12 @@ import {
 } from './top-layer';
 import { twJoin } from './tw';
 
-/**
- * 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;
+// TooltipContent / TooltipOptions are declared in the published types
+// (types/api/tooltip.d.ts) as the single source of truth, so the package's
+// declaration surface stays self-contained and never re-exports raw src.
+import type { TooltipContent, TooltipOptions } from '@/types/api/tooltip';
 
-  /**
-   * Tooltip bottom margin
-   */
-  marginBottom?: number;
-
-  /**
-   * Timout before showing
-   */
-  delay?: number;
-}
+export type { TooltipContent, TooltipOptions };
 
 const DEFAULT_OFFSET = 10;
 const TOOLTIP_ROLE = 'tooltip';

package/src/markdown/markdown-handler.ts

@@ -1,4 +1,3 @@
-import type { BlockToolData } from '../../types';
 import type { BlokModules } from '../types-internal/blok-modules';
 import type { SanitizerConfigBuilder } from '../components/modules/paste/sanitizer-config';
 import type { ToolRegistry } from '../components/modules/paste/tool-registry';
@@ -93,7 +92,7 @@ export class MarkdownHandler extends BasePasteHandler implements PasteHandler {
       BlockManager.composeBlock({
         id,
         tool: type,
-        data: blockData as BlockToolData,
+        data: blockData,
         parentId: parent,
       })
     );