@jackuait/blok 0.13.0 → 0.13.2

package/src/components/utils/default-page-colors.ts

@@ -0,0 +1,130 @@
+/**
+ * Detect default page background colors that should NOT be mapped to a Blok preset.
+ *
+ * When browsers natively copy from a contenteditable, computed styles include
+ * the resolved page background (e.g. `rgb(255, 255, 255)` in light mode,
+ * `rgb(25, 25, 24)` in Blok's dark mode). These are not intentional formatting
+ * and would otherwise collapse onto the gray bg preset since gray is the only
+ * achromatic background.
+ *
+ * Centralized here so every consumer (paste preprocessors, table clipboard,
+ * HTML import, color-mapping itself) shares the same definition.
+ *
+ * Kept dependency-free (no import of color-mapping) to avoid a circular
+ * import — color-mapping uses these predicates as a defense-in-depth guard.
+ */
+
+/**
+ * True when bgColor is the default white page background
+ * (`#fff`, `#ffffff`, `rgb(255,255,255)`, or the keyword `white`).
+ */
+export function isDefaultWhiteBackground(bgColor: string): boolean {
+  const normalized = bgColor.replace(/\s/g, '').toLowerCase();
+
+  return (
+    normalized === 'rgb(255,255,255)' ||
+    normalized === '#ffffff' ||
+    normalized === '#fff' ||
+    normalized === 'white'
+  );
+}
+
+/**
+ * Compute simplified linear luminance (no gamma correction) of a CSS color
+ * value. Adequate for threshold comparisons used to spot default page bgs.
+ *
+ * Supports: `#rgb`, `#rrggbb`, `rgb(...)`, `rgba(...)`, `hsl(...)`, `hsla(...)`.
+ * Alpha is ignored. Returns -1 if the format is unrecognized.
+ */
+function computeRelativeLuminance(color: string): number {
+  const normalized = color.replace(/\s/g, '').toLowerCase();
+
+  const rgbMatch = /^rgba?\((\d+),(\d+),(\d+)(?:,[\d.]+)?\)$/.exec(normalized);
+
+  if (rgbMatch) {
+    const r = parseInt(rgbMatch[1], 10) / 255;
+    const g = parseInt(rgbMatch[2], 10) / 255;
+    const b = parseInt(rgbMatch[3], 10) / 255;
+
+    return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+  }
+
+  const hslMatch = /^hsla?\(([\d.]+),([\d.]+)%,([\d.]+)%(?:,[\d.]+)?\)$/.exec(normalized);
+
+  if (hslMatch) {
+    const h = parseFloat(hslMatch[1]) / 360;
+    const s = parseFloat(hslMatch[2]) / 100;
+    const l = parseFloat(hslMatch[3]) / 100;
+
+    if (s === 0) {
+      /* achromatic — r = g = b = l */
+      return 0.2126 * l + 0.7152 * l + 0.0722 * l;
+    }
+
+    const q = l < 0.5 ? l * (1 + s) : l + s - l * s;
+    const p = 2 * l - q;
+    const wrap = (t: number): number => {
+      if (t < 0) {
+        return t + 1;
+      }
+
+      if (t > 1) {
+        return t - 1;
+      }
+
+      return t;
+    };
+    const hueToChannel = (t: number): number => {
+      const wrapped = wrap(t);
+
+      if (wrapped < 1 / 6) {
+        return p + (q - p) * 6 * wrapped;
+      }
+
+      if (wrapped < 1 / 2) {
+        return q;
+      }
+
+      if (wrapped < 2 / 3) {
+        return p + (q - p) * (2 / 3 - wrapped) * 6;
+      }
+
+      return p;
+    };
+
+    const r = hueToChannel(h + 1 / 3);
+    const g = hueToChannel(h);
+    const b = hueToChannel(h - 1 / 3);
+
+    return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+  }
+
+  const hexMatch = /^#([0-9a-f]{6}|[0-9a-f]{3})$/.exec(normalized);
+
+  if (hexMatch) {
+    const hex = hexMatch[1];
+    const expand = hex.length === 3
+      ? [hex[0] + hex[0], hex[1] + hex[1], hex[2] + hex[2]]
+      : [hex.substring(0, 2), hex.substring(2, 4), hex.substring(4, 6)];
+    const r = parseInt(expand[0], 16) / 255;
+    const g = parseInt(expand[1], 16) / 255;
+    const b = parseInt(expand[2], 16) / 255;
+
+    return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+  }
+
+  return -1;
+}
+
+/**
+ * True when bgColor is a near-black (dark mode page) background.
+ *
+ * Uses simplified linear luminance < 0.12 — below all Blok dark bg presets
+ * (~18% minimum lightness for #2f2f2f, lin-luminance ≈ 0.184) while catching
+ * typical dark page backgrounds (`#191918` ≈ 0.098, `rgb(25,25,24)` ≈ 0.098).
+ */
+export function isDefaultDarkBackground(bgColor: string): boolean {
+  const luminance = computeRelativeLuminance(bgColor);
+
+  return luminance >= 0 && luminance < 0.12;
+}

package/src/components/utils/highlight-block-arrival.ts

@@ -0,0 +1,50 @@
+/**
+ * Applies a brief "target" highlight pulse to a block holder after the editor
+ * scrolls to it from a `#<block-id>` URL (Notion/Google Docs behaviour).
+ *
+ * The caller is responsible for choosing the right moment (after scroll + select).
+ * We toggle the `blok-block--target` class on the element; removal happens on
+ * `animationend` (preferred, avoids timer drift) with a defensive timeout
+ * fallback in case the animation is cancelled / never runs (e.g. element
+ * detached, reduced-motion stack collapses the keyframes to 0ms).
+ */
+
+const TARGET_CLASS = 'blok-block--target';
+const FALLBACK_REMOVE_MS = 1800;
+
+/**
+ * Briefly highlight the given element to signal arrival from a hash link.
+ * Safe to call repeatedly — re-triggers a fresh pulse.
+ */
+export function highlightBlockArrival(el: Element): void {
+  // Re-add: if class is already there (repeat navigation), force a reflow so
+  // the keyframes restart.
+  el.classList.remove(TARGET_CLASS);
+  // Force reflow to guarantee the animation restarts when class is re-added.
+  void (el as HTMLElement).offsetWidth;
+  el.classList.add(TARGET_CLASS);
+
+  const state = { removed: false };
+
+  const clear = (): void => {
+    if (state.removed) {
+      return;
+    }
+    state.removed = true;
+    el.classList.remove(TARGET_CLASS);
+    el.removeEventListener('animationend', onAnimationEnd);
+  };
+
+  const onAnimationEnd = (event: Event): void => {
+    // Only react to the holder's own animation, not a descendant's.
+    if (event.target === el) {
+      clear();
+    }
+  };
+
+  el.addEventListener('animationend', onAnimationEnd);
+
+  // Fallback: if animationend never fires (reduced motion, detached element,
+  // CSS not loaded) remove the class after the animation window.
+  window.setTimeout(clear, FALLBACK_REMOVE_MS);
+}

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

@@ -124,6 +124,15 @@ export class PopoverDesktop extends PopoverAbstract {
    */
   private trigger: HTMLElement | undefined;
 
+  /**
+   * Trigger rect captured at construction time. Used as a fallback if the
+   * live trigger rect has collapsed to zero size by the time `show()` runs
+   * (e.g. because a subscriber to an "opened" event set the trigger to
+   * `display:none`). Prevents the popover from rendering at the viewport's
+   * top-left corner when the trigger is no longer measurable.
+   */
+  private capturedTriggerRect: DOMRect | undefined;
+
   /**
    * Optional element whose left edge is used for horizontal positioning
    * instead of the trigger's left edge.
@@ -189,6 +198,12 @@ export class PopoverDesktop extends PopoverAbstract {
 
     if (params.trigger) {
       this.trigger = params.trigger;
+
+      const initialRect = params.trigger.getBoundingClientRect();
+
+      if (initialRect.width > 0 || initialRect.height > 0) {
+        this.capturedTriggerRect = initialRect;
+      }
     }
 
     if (params.leftAlignElement) {
@@ -413,7 +428,14 @@ export class PopoverDesktop extends PopoverAbstract {
    */
   private calculatePosition(): { top: number; left: number; openTop: boolean; openLeft: boolean } {
     const explicitPosition = this.params.position;
-    const rect = explicitPosition ?? this.trigger?.getBoundingClientRect();
+    const liveRect = this.trigger?.getBoundingClientRect();
+    const isLiveRectCollapsed = liveRect !== undefined
+      && liveRect.width === 0
+      && liveRect.height === 0;
+    const fallbackRect = isLiveRectCollapsed && this.capturedTriggerRect !== undefined
+      ? this.capturedTriggerRect
+      : liveRect;
+    const rect = explicitPosition ?? fallbackRect;
 
     if (!rect) {
       return { top: 0, left: 0, openTop: false, openLeft: false };

package/src/styles/image.css

@@ -19,6 +19,9 @@
 [data-blok-tool="image"][data-size="md"]   .blok-image-inner { width: 520px; }
 [data-blok-tool="image"][data-size="lg"]   .blok-image-inner { width: 100%; }
 [data-blok-tool="image"][data-size="full"] .blok-image-inner { width: 100%; }
+/* banner-shaped / tiny-natural images: force full width so resize handles
+   and toolbar row don't collide with a short figure. */
+[data-blok-tool="image"][data-auto-full="true"] .blok-image-inner { width: 100%; }
 
 [data-blok-tool="image"] .blok-image-inner img {
   display: block;
@@ -63,6 +66,10 @@
 }
 [data-blok-tool="image"][data-caption="off"] .blok-image-caption { display: none; }
 
+/* Hide caption row while image is loading — nothing to caption yet. */
+[data-blok-tool="image"]:has(.blok-image-inner[data-loading="true"]) .blok-image-caption-row,
+[data-blok-tool="image"]:has(.blok-image-inner[data-loading="true"]) .blok-image-caption { display: none; }
+
 /* caption row — caption text + inline alt button revealed on hover */
 [data-blok-tool="image"] .blok-image-caption-row {
   display: flex;
@@ -1019,3 +1026,82 @@
   animation: blok-image-retry-spin 0.65s linear infinite;
 }
 
+/* Auto-retry loading overlay — img failed once; re-fetching.
+   Ambient blur backdrop + shimmer sweep + soft-glow spinner. */
+[data-blok-tool="image"] .blok-image-inner[data-loading="true"] {
+  overflow: hidden;
+  border-radius: var(--blok-radius-md);
+  isolation: isolate;
+  min-height: 220px;
+  background: color-mix(in srgb, var(--blok-bg-secondary) 65%, var(--blok-bg-primary));
+}
+[data-blok-tool="image"] .blok-image-inner[data-loading="true"] img {
+  min-height: 220px;
+}
+[data-blok-tool="image"] .blok-image-inner[data-loading="true"] img {
+  opacity: 0.35;
+  filter: blur(18px) saturate(1.1);
+  transform: scale(1.08);
+  color: transparent; /* suppress alt-text fallback while loading */
+}
+[data-blok-tool="image"] .blok-image-inner[data-loading="true"]::before {
+  content: "";
+  position: absolute;
+  inset: 0;
+  background:
+    radial-gradient(
+      120% 80% at 50% 50%,
+      color-mix(in srgb, var(--blok-bg-primary) 55%, transparent) 0%,
+      color-mix(in srgb, var(--blok-bg-secondary) 45%, transparent) 55%,
+      transparent 100%
+    ),
+    linear-gradient(
+      115deg,
+      transparent 20%,
+      color-mix(in srgb, var(--blok-text-primary) 10%, transparent) 48%,
+      color-mix(in srgb, var(--blok-text-primary) 14%, transparent) 50%,
+      color-mix(in srgb, var(--blok-text-primary) 10%, transparent) 52%,
+      transparent 80%
+    );
+  background-size: 100% 100%, 220% 100%;
+  background-position: 0 0, 120% 0;
+  background-repeat: no-repeat;
+  animation: blok-image-loading-sheen 1.8s cubic-bezier(0.4, 0, 0.2, 1) infinite;
+  pointer-events: none;
+  z-index: 1;
+}
+[data-blok-tool="image"] .blok-image-inner[data-loading="true"]::after {
+  content: "";
+  position: absolute;
+  inset: 0;
+  width: 34px;
+  height: 34px;
+  margin: auto;
+  border-radius: 50%;
+  border: 2px solid color-mix(in srgb, var(--blok-text-primary) 14%, transparent);
+  border-top-color: var(--blok-text-primary);
+  border-right-color: color-mix(in srgb, var(--blok-text-primary) 55%, transparent);
+  box-shadow:
+    0 0 0 6px color-mix(in srgb, var(--blok-bg-primary) 22%, transparent),
+    0 8px 28px color-mix(in srgb, var(--blok-color-accent, var(--blok-text-primary)) 22%, transparent);
+  animation:
+    blok-image-retry-spin 0.9s cubic-bezier(0.65, 0, 0.35, 1) infinite,
+    blok-image-loading-pulse 1.8s ease-in-out infinite;
+  pointer-events: none;
+  z-index: 2;
+}
+@keyframes blok-image-loading-sheen {
+  0%   { background-position: 0 0, 120% 0; }
+  100% { background-position: 0 0, -120% 0; }
+}
+@keyframes blok-image-loading-pulse {
+  0%, 100% { opacity: 0.85; }
+  50%      { opacity: 1; }
+}
+@media (prefers-reduced-motion: reduce) {
+  [data-blok-tool="image"] .blok-image-inner[data-loading="true"]::before { animation: none; }
+  [data-blok-tool="image"] .blok-image-inner[data-loading="true"]::after {
+    animation: blok-image-retry-spin 1.4s linear infinite;
+  }
+}
+

package/src/styles/keyframes.css

@@ -60,3 +60,9 @@
 @keyframes blok-image-retry-spin {
   to { transform: rotate(360deg); }
 }
+
+@keyframes blok-block-target-pulse {
+  0%   { background-color: var(--blok-selection); }
+  60%  { background-color: var(--blok-selection); }
+  100% { background-color: transparent; }
+}

package/src/styles/main.css

@@ -193,6 +193,23 @@
   border-radius: var(--blok-space-1);
 }
 
+/*
+ * Arrival pulse: briefly highlight the block that a #<id> URL points to
+ * after scroll + select. Class is applied/removed by highlightBlockArrival().
+ */
+.blok-block--target {
+  animation: blok-block-target-pulse 1.5s ease-out;
+  border-radius: var(--blok-space-1);
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .blok-block--target {
+    /* Skip the keyframe tween but keep the hold so the class still clears. */
+    animation: none;
+    background-color: var(--blok-selection);
+  }
+}
+
 /**
  * Content alignment
  * Applies horizontal alignment to block content based on the editor's contentAlign setting.

package/src/tools/database/index.ts

@@ -260,12 +260,11 @@ export class DatabaseTool implements BlockTool {
   }
 
   /**
-   * Returns the outer wrapper element as the toolbar anchor so the toolbar
-   * vertically centers on the block's visual top, not on a deeply nested
-   * descendant (or falls back to pluginsContent when no contenteditable exists).
+   * Returns the title element so the block toolbar vertically centers on the
+   * database title line rather than on the outer wrapper's top edge.
    */
   getToolbarAnchorElement(): HTMLElement | undefined {
-    return this.element ?? undefined;
+    return this.titleElement ?? undefined;
   }
 
   // ---------------------------------------------------------------------------

package/src/tools/image/dimensions-from-svg.ts

@@ -0,0 +1,53 @@
+type Dims = { width: number; height: number };
+
+function parseNumber(raw: string | null): number | null {
+  if (raw == null) return null;
+  const match = /^(-?\d+(?:\.\d+)?)(px)?$/.exec(raw.trim());
+  if (!match) return null;
+  const n = Number(match[1]);
+  return Number.isFinite(n) && n > 0 ? n : null;
+}
+
+function isSvgUrl(url: string): boolean {
+  try {
+    const { pathname } = new URL(url, 'https://base.local');
+    return /\.svg(?:$|\?|#)/i.test(pathname);
+  } catch {
+    return false;
+  }
+}
+
+async function fetchSvgText(url: string): Promise<string | null> {
+  try {
+    const res = await fetch(url);
+    if (!res.ok) return null;
+    return await res.text();
+  } catch {
+    return null;
+  }
+}
+
+function dimsFromViewBox(viewBox: string | null): Dims | null {
+  if (!viewBox) return null;
+  const parts = viewBox.trim().split(/[\s,]+/);
+  if (parts.length !== 4) return null;
+  const vw = parseNumber(parts[2]);
+  const vh = parseNumber(parts[3]);
+  if (vw == null || vh == null) return null;
+  return { width: vw, height: vh };
+}
+
+export async function dimensionsFromSvg(url: string): Promise<Dims | null> {
+  if (!isSvgUrl(url)) return null;
+  const text = await fetchSvgText(url);
+  if (text == null) return null;
+  const doc = new DOMParser().parseFromString(text, 'image/svg+xml');
+  const root = doc.documentElement;
+  if (!root || root.tagName.toLowerCase() !== 'svg') return null;
+
+  const w = parseNumber(root.getAttribute('width'));
+  const h = parseNumber(root.getAttribute('height'));
+  if (w != null && h != null) return { width: w, height: h };
+
+  return dimsFromViewBox(root.getAttribute('viewBox'));
+}

package/src/tools/image/dimensions-from-url.ts

@@ -0,0 +1,87 @@
+type Dims = { width: number; height: number };
+
+function valid(w: unknown, h: unknown): Dims | null {
+  const width = Number(w);
+  const height = Number(h);
+  if (!Number.isFinite(width) || !Number.isFinite(height)) return null;
+  if (width <= 0 || height <= 0) return null;
+  return { width, height };
+}
+
+function fromSearchParams(params: URLSearchParams): Dims | null {
+  const size = params.get('size') ?? params.get('dim') ?? params.get('dimensions');
+  if (size) {
+    const match = /^(\d+)[xX](\d+)$/.exec(size);
+    if (match) return valid(match[1], match[2]);
+  }
+  const resize = params.get('resize') ?? params.get('fit');
+  if (resize) {
+    const match = /^(\d+),(\d+)$/.exec(resize);
+    if (match) return valid(match[1], match[2]);
+  }
+  const w = params.get('w') ?? params.get('width') ?? params.get('imwidth');
+  const h = params.get('h') ?? params.get('height') ?? params.get('imheight');
+  if (w && h) return valid(w, h);
+  return null;
+}
+
+function firstMatch(segments: string[], re: RegExp): string | null {
+  for (const seg of segments) {
+    const m = re.exec(seg);
+    if (m) return m[1];
+  }
+  return null;
+}
+
+function fromCloudinary(pathname: string): Dims | null {
+  const match = /\/(?:upload|fetch|private|authenticated)\/([^/]+(?:\/[^/]+)*)\//.exec(pathname);
+  if (!match) return null;
+  const segments = match[1].split('/');
+  const w = firstMatch(segments, /(?:^|,)w_(\d+)(?:,|$)/);
+  const h = firstMatch(segments, /(?:^|,)h_(\d+)(?:,|$)/);
+  return w && h ? valid(w, h) : null;
+}
+
+function fromCloudflare(pathname: string): Dims | null {
+  const match = /\/cdn-cgi\/image\/([^/]+)\//.exec(pathname);
+  if (!match) return null;
+  const w = /(?:^|,)width=(\d+)(?:,|$)/.exec(match[1]);
+  const h = /(?:^|,)height=(\d+)(?:,|$)/.exec(match[1]);
+  return w && h ? valid(w[1], h[1]) : null;
+}
+
+function fromImageKit(pathname: string): Dims | null {
+  const match = /\/tr:([^/]+)\//.exec(pathname);
+  if (!match) return null;
+  const w = /(?:^|,)w-(\d+)(?:,|$)/.exec(match[1]);
+  const h = /(?:^|,)h-(\d+)(?:,|$)/.exec(match[1]);
+  return w && h ? valid(w[1], h[1]) : null;
+}
+
+function fromPath(pathname: string): Dims | null {
+  return fromCloudinary(pathname) ?? fromCloudflare(pathname) ?? fromImageKit(pathname);
+}
+
+function fromFilename(pathname: string): Dims | null {
+  const base = pathname.split('/').pop() ?? '';
+  const wh = /[-_](\d{2,5})[xX](\d{2,5})(?:[._-]|\.[a-z0-9]+$)/.exec(base);
+  if (wh) return valid(wh[1], wh[2]);
+  const sep = /[-_]w(\d+)[-_]h(\d+)/.exec(base);
+  if (sep) return valid(sep[1], sep[2]);
+  return null;
+}
+
+function safeParse(url: string): URL | null {
+  try {
+    return new URL(url, 'https://base.local');
+  } catch {
+    return null;
+  }
+}
+
+export function dimensionsFromUrl(url: string): Dims | null {
+  if (!url) return null;
+  const parsed = safeParse(url);
+  if (!parsed) return null;
+  return fromSearchParams(parsed.searchParams) ?? fromPath(parsed.pathname) ?? fromFilename(parsed.pathname);
+}

package/src/tools/image/error-state.ts

@@ -1,10 +1,13 @@
-import { IconImageBroken } from '../../components/icons';
+import { IconImageBroken, IconUploadFailed } from '../../components/icons';
 import type { I18nInstance } from '../../components/utils/tools';
 import { tr } from './i18n';
 
+export type ErrorVariant = 'broken' | 'upload';
+
 export interface ErrorStateOptions {
   title?: string;
   message?: string;
+  variant?: ErrorVariant;
   onTryAgain?(): void;
   onSwap?(): void;
   i18n?: I18nInstance;
@@ -14,11 +17,13 @@ export function renderErrorState(opts: ErrorStateOptions): HTMLElement {
   const root = document.createElement('div');
   root.className = 'blok-image-error';
   root.setAttribute('data-role', 'error-state');
+  const variant: ErrorVariant = opts.variant ?? 'broken';
+  root.setAttribute('data-variant', variant);
 
   const icon = document.createElement('div');
   icon.className = 'blok-image-error__icon';
   icon.setAttribute('aria-hidden', 'true');
-  icon.innerHTML = IconImageBroken;
+  icon.innerHTML = variant === 'upload' ? IconUploadFailed : IconImageBroken;
 
   const body = document.createElement('div');
   body.className = 'blok-image-error__body';