@alikhalilll/a-skeleton 1.0.0 → 1.2.0

package/src/utils/captureStyles.ts

@@ -0,0 +1,378 @@
+/**
+ * Comprehensive style-capture engine.
+ *
+ * Walks the slot's rendered DOM after mount and captures **every visible CSS
+ * property** of every element it encounters, plus geometry, into a frozen
+ * snapshot tree. The snapshot is replayed by `<ASkeletonClone>` as a tree
+ * of positioned divs each carrying its captured inline style.
+ *
+ * Why this exists (vs the DOM-mirror walker in `buildStructuralSkeleton.ts`):
+ *
+ *   - DOM-mirror preserves the slot's vnode tree and inherits styling from the
+ *     consumer's `class` / inline `style` attributes. That works for *static*
+ *     styles, but it can't see styles applied via:
+ *       - JavaScript-set inline style (refs, watchers, animation libs)
+ *       - CSS-in-JS runtimes that hash class names per instance
+ *       - DaisyUI / shadcn / custom CSS where the computed result differs
+ *         from what the class string implies
+ *       - Scoped styles compiled with content-hash data attributes
+ *
+ *   - `captureSnapshot` reads `getComputedStyle()` for each element — the
+ *     **final** computed style after the cascade has resolved. Replaying that
+ *     produces a pixel-identical surface no matter what styling system the
+ *     consumer uses.
+ *
+ * Cost is bounded by the same `maxNodes` / `maxDepth` / `minSize` filters
+ * as the legacy `walkDom` capture. The whole pass is a single top-down read
+ * with no DOM writes between, so the browser does one layout up front.
+ */
+
+import {
+  captureTextLines,
+  collectVisibleChildren,
+  hasDirectText,
+  readComputedStyles,
+  type TextLineRect,
+} from './domRead';
+
+export type { TextLineRect };
+
+/** A captured element — geometry + comprehensive style snapshot + children. */
+export interface CapturedNode {
+  /** Tag name lowercased — used by the replay to decide content-type treatment. */
+  tag: string;
+  /** Root-relative position + size in CSS pixels. */
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+  /**
+   * Frozen, ready-to-apply `style` object. Only non-default visual
+   * properties are included — the snapshot for a default `<div>` is tiny.
+   */
+  style: Readonly<Record<string, string>>;
+  /**
+   * Content classification — drives how `<ASkeletonClone>` renders the leaf:
+   *   - `text`     → shimmer text bar (optionally with per-line rects)
+   *   - `image`    → solid surface with image-placeholder icon
+   *   - `video`    → solid surface with play-icon
+   *   - `media`    → atomic block (svg/canvas/iframe — no icon)
+   *   - `block`    → opaque shimmer block (default for unrecognised leaves)
+   *   - `container` → has children; rendered as a positioned wrapper
+   */
+  kind: 'text' | 'image' | 'video' | 'media' | 'block' | 'container';
+  /**
+   * Per-line text rects (only set when `kind === 'text'`). Replaces the
+   * single-rect bar with one bar per rendered text line at the exact width
+   * of that line — handles wrapping, RTL, centered headings 1:1.
+   */
+  textLines?: ReadonlyArray<TextLineRect>;
+  /** Children (only set when `kind === 'container'`). */
+  children?: ReadonlyArray<CapturedNode>;
+}
+
+export interface CaptureSnapshot {
+  /** Overall bounding box. */
+  width: number;
+  height: number;
+  /** Top-level captured nodes (siblings of the root's direct children). */
+  nodes: ReadonlyArray<CapturedNode>;
+  /** True if `maxNodes` was hit and the walk bailed out early. */
+  truncated: boolean;
+  /** When the snapshot was taken (ms since epoch). For cache invalidation policies. */
+  capturedAt: number;
+}
+
+export interface CaptureOptions {
+  /** Max recursion depth. Default 12. */
+  maxDepth?: number;
+  /** Hard cap on captured nodes. Default 800. */
+  maxNodes?: number;
+  /** Skip elements smaller than this many CSS pixels (either axis). Default 4. */
+  minSize?: number;
+  /**
+   * When true, capture child elements even inside leaves that we'd normally
+   * treat atomically. Default false (atomic = single block).
+   */
+  walkAtomic?: boolean;
+}
+
+const DEFAULT_MAX_DEPTH = 12;
+const DEFAULT_MAX_NODES = 800;
+const DEFAULT_MIN_SIZE = 4;
+
+/** Tags treated as atomic leaves — no recursion into their contents. */
+const ATOMIC_TAGS = new Set([
+  'img',
+  'svg',
+  'canvas',
+  'video',
+  'audio',
+  'input',
+  'textarea',
+  'select',
+  'progress',
+  'meter',
+  'hr',
+  'iframe',
+  'object',
+  'embed',
+  'picture',
+  'br',
+]);
+
+/** Tags whose content is text — captured as text bars (per-line via Range). */
+const TEXT_OWNERS = new Set([
+  'p',
+  'h1',
+  'h2',
+  'h3',
+  'h4',
+  'h5',
+  'h6',
+  'span',
+  'a',
+  'em',
+  'strong',
+  'small',
+  'code',
+  'b',
+  'i',
+  'mark',
+  'label',
+  'caption',
+  'time',
+  'dt',
+  'dd',
+  'li',
+  'th',
+  'td',
+  'figcaption',
+  'blockquote',
+  'cite',
+  'q',
+]);
+
+/**
+ * Visual CSS properties read from `getComputedStyle()`. Property listed here
+ * is included in the captured snapshot **only when its value differs from the
+ * skip set** — so a plain unstyled `<div>` produces an empty style object.
+ *
+ * Listed in the order they're written into the snapshot's `style` object so
+ * the replay is deterministic across captures.
+ */
+const VISUAL_PROPS = [
+  /* Box model — padding only (margin doesn't apply to absolute children). */
+  'padding-top',
+  'padding-right',
+  'padding-bottom',
+  'padding-left',
+
+  /* Border — per edge so non-uniform borders survive. */
+  'border-top-width',
+  'border-right-width',
+  'border-bottom-width',
+  'border-left-width',
+  'border-top-style',
+  'border-right-style',
+  'border-bottom-style',
+  'border-left-style',
+  'border-top-color',
+  'border-right-color',
+  'border-bottom-color',
+  'border-left-color',
+  'border-top-left-radius',
+  'border-top-right-radius',
+  'border-bottom-right-radius',
+  'border-bottom-left-radius',
+
+  /* Background. */
+  'background-color',
+  'background-image',
+  'background-position',
+  'background-size',
+  'background-repeat',
+  'background-origin',
+  'background-clip',
+
+  /* Effects. */
+  'box-shadow',
+  'opacity',
+  'filter',
+  'backdrop-filter',
+  'transform',
+  'transform-origin',
+  'mix-blend-mode',
+
+  /* Typography (only meaningful for text leaves but harmless to read for all). */
+  'font-family',
+  'font-size',
+  'font-weight',
+  'font-style',
+  'line-height',
+  'letter-spacing',
+  'text-align',
+  'text-transform',
+  'text-decoration-line',
+  'text-decoration-color',
+];
+
+/**
+ * Snapshot the rendered DOM under `root`, returning a frozen tree of every
+ * visible element + its computed visual styles. Replaying the snapshot
+ * produces a surface visually identical to `root`.
+ */
+export function captureSnapshot(root: HTMLElement, options: CaptureOptions = {}): CaptureSnapshot {
+  const maxDepth = options.maxDepth ?? DEFAULT_MAX_DEPTH;
+  const maxNodes = options.maxNodes ?? DEFAULT_MAX_NODES;
+  const minSize = options.minSize ?? DEFAULT_MIN_SIZE;
+  const walkAtomic = options.walkAtomic ?? false;
+
+  const rootRect = root.getBoundingClientRect();
+  const state = { count: 0, truncated: false };
+  const nodes: CapturedNode[] = [];
+
+  for (let i = 0; i < root.children.length; i++) {
+    if (state.count >= maxNodes) {
+      state.truncated = true;
+      break;
+    }
+    const node = capture(root.children[i] as HTMLElement, rootRect, 1, {
+      maxDepth,
+      maxNodes,
+      minSize,
+      walkAtomic,
+      state,
+    });
+    if (node) nodes.push(node);
+  }
+
+  return Object.freeze({
+    width: Math.round(rootRect.width),
+    height: Math.round(rootRect.height),
+    nodes: Object.freeze(nodes),
+    truncated: state.truncated,
+    capturedAt: Date.now(),
+  });
+}
+
+interface InternalCtx {
+  maxDepth: number;
+  maxNodes: number;
+  minSize: number;
+  walkAtomic: boolean;
+  state: { count: number; truncated: boolean };
+}
+
+function capture(
+  el: HTMLElement,
+  origin: DOMRect,
+  depth: number,
+  ctx: InternalCtx
+): CapturedNode | null {
+  if (ctx.state.count >= ctx.maxNodes) {
+    ctx.state.truncated = true;
+    return null;
+  }
+  if (el.dataset?.skeletonIgnore !== undefined) return null;
+
+  const cs = window.getComputedStyle(el);
+  if (cs.display === 'none' || cs.visibility === 'hidden') return null;
+  /* Opacity zero — skip (the element is invisible). */
+  const o = parseFloat(cs.opacity);
+  if (Number.isFinite(o) && o === 0) return null;
+
+  const rect = el.getBoundingClientRect();
+  const tag = el.tagName.toLowerCase();
+  const isTextOwnerTag = TEXT_OWNERS.has(tag);
+
+  /* Text-owner tags can have zero height when their interpolation is empty
+   * (e.g. `<h3>{{ data?.name }}</h3>` with `data === null`). The base
+   * `minSize` filter would drop them, leaving the heading invisible in the
+   * clone replay. For text-owners only, synthesize a height from the
+   * element's `line-height` (or `font-size * 1.4` as a fallback) so the
+   * fallback bar still renders at the heading's natural rendered height. */
+  let effectiveHeight = rect.height;
+  if (isTextOwnerTag && effectiveHeight < ctx.minSize) {
+    const lh = parseFloat(cs.lineHeight);
+    const fs = parseFloat(cs.fontSize);
+    if (Number.isFinite(lh) && lh > 0) effectiveHeight = lh;
+    else if (Number.isFinite(fs) && fs > 0) effectiveHeight = fs * 1.4;
+  }
+
+  if (rect.width < ctx.minSize || effectiveHeight < ctx.minSize) return null;
+
+  const x = Math.round(rect.left - origin.left);
+  const y = Math.round(rect.top - origin.top);
+  const w = Math.round(rect.width);
+  const h = Math.round(effectiveHeight);
+
+  const style = readComputedStyles(cs, VISUAL_PROPS);
+
+  /* Classify the leaf — drives how `<ASkeletonClone>` renders this node. */
+  const isAtomic = ATOMIC_TAGS.has(tag);
+  const hasOwnText = hasDirectText(el);
+  const childrenEls = collectVisibleChildren(el);
+
+  let kind: CapturedNode['kind'];
+
+  if (tag === 'img' || tag === 'picture') {
+    kind = 'image';
+  } else if (tag === 'video') {
+    kind = 'video';
+  } else if (isAtomic) {
+    kind = 'media';
+  } else if (childrenEls.length === 0 && (hasOwnText || isTextOwnerTag)) {
+    /* Text-owner tags with no children (e.g. `<h3>{{ data?.name }}</h3>` with
+     * null data) classify as text even though their interpolation is empty —
+     * the renderer falls back to a single full-box bar at the element's
+     * natural rendered dimensions, so the heading shimmers at the right
+     * height instead of rendering as a generic block. */
+    kind = 'text';
+  } else if (childrenEls.length === 0) {
+    kind = 'block';
+  } else {
+    kind = 'container';
+  }
+
+  /* For text leaves, capture per-line rects via Range API. */
+  let textLines: CapturedNode['textLines'];
+  if (kind === 'text') {
+    textLines = captureTextLines(el, origin);
+  }
+
+  /* Recurse into children for containers (and atomic if walkAtomic). */
+  let children: CapturedNode[] | undefined;
+  if (kind === 'container' && depth < ctx.maxDepth) {
+    children = [];
+    for (const c of childrenEls) {
+      if (ctx.state.count >= ctx.maxNodes) {
+        ctx.state.truncated = true;
+        break;
+      }
+      const childNode = capture(c, origin, depth + 1, ctx);
+      if (childNode) children.push(childNode);
+    }
+    if (children.length === 0) {
+      /* All children filtered — degrade to block so the surface still renders. */
+      children = undefined;
+      kind = style && Object.keys(style).length > 0 ? 'block' : 'container';
+    }
+  } else if ((kind === 'container' && depth >= ctx.maxDepth) || (isAtomic && ctx.walkAtomic)) {
+    kind = 'block';
+  }
+
+  ctx.state.count++;
+
+  return Object.freeze({
+    tag,
+    x,
+    y,
+    w,
+    h,
+    style,
+    kind,
+    textLines: textLines ? Object.freeze(textLines) : undefined,
+    children: children ? Object.freeze(children) : undefined,
+  });
+}

package/src/utils/domRead.ts

@@ -0,0 +1,143 @@
+/**
+ * Shared DOM-read helpers used by both capture strategies:
+ *   - `captureStyles.ts` (clone-mode comprehensive style snapshot)
+ *   - `walkStructural.ts` (Recipe 3 tree-shaped capture)
+ *
+ * One source of truth for "what counts as a default CSS value", how to read a
+ * computed-style subset into a frozen camelCased object, and how to measure
+ * per-line text rectangles. Keeping both walkers behind these helpers prevents
+ * silent drift between the two pipelines.
+ */
+
+/** A single rendered text-line rectangle, expressed in root-relative pixels. */
+export interface TextLineRect {
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+}
+
+/**
+ * Computed values that count as "default" and shouldn't be persisted. Stripped
+ * before a captured `style` object lands on a node so a plain unstyled element
+ * produces an empty style — keeps snapshots small and the rendered DOM clean.
+ */
+export const SKIP_VALUES: ReadonlySet<string> = new Set([
+  'none',
+  'normal',
+  'auto',
+  '0px',
+  '0',
+  '0 0',
+  '0% 0%',
+  '0px 0px',
+  '0deg',
+  '0s',
+  'visible',
+  'static',
+  'transparent',
+  'rgba(0, 0, 0, 0)',
+  'rgb(0, 0, 0, 0)',
+  'initial',
+  'inherit',
+  'unset',
+  'currentcolor',
+]);
+
+/**
+ * Read the subset of `props` from `cs` and return a frozen camelCased style
+ * map with the SKIP_VALUES entries omitted. `opacity: 1` is treated as default
+ * (matches CSS' initial value).
+ */
+export function readComputedStyles(
+  cs: CSSStyleDeclaration,
+  props: ReadonlyArray<string>
+): Readonly<Record<string, string>> {
+  const out: Record<string, string> = {};
+  for (const prop of props) {
+    const val = cs.getPropertyValue(prop).trim();
+    if (!val) continue;
+    if (SKIP_VALUES.has(val.toLowerCase())) continue;
+    if (prop === 'opacity' && (val === '1' || parseFloat(val) === 1)) continue;
+    out[camelCase(prop)] = val;
+  }
+  return Object.freeze(out);
+}
+
+export function camelCase(prop: string): string {
+  return prop.replace(/-([a-z])/g, (_, c: string) => c.toUpperCase());
+}
+
+/** True when the element has at least one non-whitespace direct text-node child. */
+export function hasDirectText(el: Element): boolean {
+  for (let i = 0; i < el.childNodes.length; i++) {
+    const node = el.childNodes[i];
+    if (node.nodeType === Node.TEXT_NODE && (node.textContent ?? '').trim().length > 0) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/** Element children, with `data-skeleton-ignore` descendants filtered out. */
+export function collectVisibleChildren(el: Element): HTMLElement[] {
+  const out: HTMLElement[] = [];
+  for (let i = 0; i < el.children.length; i++) {
+    const c = el.children[i] as HTMLElement;
+    if (c.dataset?.skeletonIgnore !== undefined) continue;
+    out.push(c);
+  }
+  return out;
+}
+
+/**
+ * Per-line text rects via `Range.getClientRects()`. Returns one rect per visual
+ * line — exact left/width for each line so wrapped paragraphs, RTL last-line
+ * positions, centered headings replay 1:1 without heuristics. Returns
+ * `undefined` if the element has no direct text or the Range API isn't usable.
+ *
+ * Two rects on the same baseline AND horizontally touching (gap ≤ 2 px) are
+ * merged so inline spans on the same line collapse to one bar. Same-baseline
+ * rects on different visual lines (rare; float-into-paragraph layouts) won't
+ * touch horizontally and stay separate.
+ */
+export function captureTextLines(el: Element, origin: DOMRect): TextLineRect[] | undefined {
+  if (typeof document === 'undefined' || typeof document.createRange !== 'function')
+    return undefined;
+  let range: Range;
+  try {
+    range = document.createRange();
+    range.selectNodeContents(el);
+  } catch {
+    return undefined;
+  }
+  const rects = range.getClientRects();
+  if (!rects || rects.length === 0) return undefined;
+
+  const merged: TextLineRect[] = [];
+  for (let i = 0; i < rects.length; i++) {
+    const r = rects[i];
+    if (r.width <= 0 || r.height <= 0) continue;
+    const lr: TextLineRect = {
+      x: Math.round(r.left - origin.left),
+      y: Math.round(r.top - origin.top),
+      w: Math.round(r.width),
+      h: Math.round(r.height),
+    };
+    const last = merged[merged.length - 1];
+    const sameLine = last && Math.abs(last.y - lr.y) <= 1 && Math.abs(last.h - lr.h) <= 1;
+    /* Touching = gap between the trailing edge of `last` and the leading
+     * edge of `lr` is at most 2 px (one rounding slack per end). */
+    const touching =
+      sameLine && Math.max(last!.x, lr.x) - Math.min(last!.x + last!.w, lr.x + lr.w) <= 2;
+    if (touching) {
+      const leftEdge = Math.min(last!.x, lr.x);
+      const rightEdge = Math.max(last!.x + last!.w, lr.x + lr.w);
+      last!.x = leftEdge;
+      last!.w = rightEdge - leftEdge;
+    } else {
+      merged.push(lr);
+    }
+  }
+  return merged.length > 0 ? merged : undefined;
+}