@alikhalilll/a-skeleton 1.0.0

package/src/utils/buildStructuralSkeleton.ts

@@ -0,0 +1,261 @@
+import {
+  Comment,
+  Fragment,
+  Text,
+  h,
+  type VNode,
+  type VNodeArrayChildren,
+  type VNodeChild,
+} from 'vue';
+
+/**
+ * Atomic HTML tags — rendered as a single skeleton block. Their own class/style
+ * is preserved so Tailwind utilities (`size-16`, `rounded-full`, …) carry the
+ * dimensions across without us needing to measure.
+ */
+const ATOMIC_TAGS = new Set([
+  'img',
+  'svg',
+  'canvas',
+  'video',
+  'input',
+  'textarea',
+  'select',
+  'button',
+  'progress',
+  'meter',
+  'hr',
+]);
+
+/** Single-line text containers — produce one bar. */
+const HEADING_TAGS = new Set(['h1', 'h2', 'h3', 'h4', 'h5', 'h6']);
+
+/** Multi-line text containers — produce N bars with a shortened last line. */
+const PARAGRAPH_TAGS = new Set(['p', 'blockquote']);
+
+/** Inline text — single bar, but inherits parent font sizing. */
+const INLINE_TEXT_TAGS = new Set([
+  'span',
+  'a',
+  'small',
+  'strong',
+  'em',
+  'code',
+  'time',
+  'label',
+  'b',
+  'i',
+  'mark',
+]);
+
+export interface BuildOptions {
+  animationClass: string | null;
+  /** Max recursion depth — guards runaway templates. Default 8. */
+  maxDepth?: number;
+  /**
+   * Hard cap on emitted skeleton nodes. Default 300. A 200-row table doesn't
+   * need 200 distinct skeleton rows on first paint; cap and stop early.
+   */
+  maxNodes?: number;
+}
+
+const DEFAULT_MAX_DEPTH = 8;
+const DEFAULT_MAX_NODES = 300;
+
+interface WalkState {
+  emitted: number;
+  cap: number;
+}
+
+/**
+ * Walk a slot's vnode tree and produce a skeleton that mirrors its rendered
+ * structure: same wrapping tags, same `class` strings (so flex/grid/spacing/
+ * sizing utilities still apply), but text/atomic leaves replaced with shimmer
+ * blocks. The result renders correctly on the FIRST paint without any DOM
+ * measurement, as long as the slot's template renders structure even when its
+ * data is empty (use `v-if`/`v-else` to swap content, not to gate the wrapper).
+ *
+ * Performance: `maxNodes` caps the work. When the cap is hit we stop emitting
+ * — the caller still gets a valid skeleton, just clipped at the budget. A 1000-
+ * row list renders ~300 skeleton rows on first paint and then the measured cache
+ * takes over for subsequent loads.
+ */
+export function buildStructuralSkeleton(
+  vnodes: VNodeChild | VNodeArrayChildren | undefined | null,
+  opts: BuildOptions
+): VNode[] {
+  const maxDepth = opts.maxDepth ?? DEFAULT_MAX_DEPTH;
+  const state: WalkState = { emitted: 0, cap: opts.maxNodes ?? DEFAULT_MAX_NODES };
+  const out: VNode[] = [];
+  walk(vnodes, opts, 0, maxDepth, state, out);
+  return out;
+}
+
+function walk(
+  input: VNodeChild | VNodeArrayChildren | undefined | null,
+  opts: BuildOptions,
+  depth: number,
+  max: number,
+  state: WalkState,
+  out: VNode[]
+): void {
+  if (state.emitted >= state.cap) return;
+  if (input == null || typeof input === 'boolean') return;
+
+  if (Array.isArray(input)) {
+    for (let i = 0; i < input.length; i++) {
+      if (state.emitted >= state.cap) return;
+      walk(input[i] as VNodeChild, opts, depth, max, state, out);
+    }
+    return;
+  }
+
+  if (typeof input === 'string' || typeof input === 'number') {
+    const str = String(input).trim();
+    if (str) push(out, textBar(opts.animationClass), state);
+    return;
+  }
+
+  const v = input as VNode;
+  const type = v.type;
+
+  if (type === Comment) return;
+
+  if (type === Text) {
+    const t = typeof v.children === 'string' ? v.children.trim() : '';
+    if (t) push(out, textBar(opts.animationClass), state);
+    return;
+  }
+
+  if (type === Fragment) {
+    walk(v.children as VNodeArrayChildren, opts, depth, max, state, out);
+    return;
+  }
+
+  if (typeof type === 'string') {
+    push(out, transformElement(v, type.toLowerCase(), opts, depth, max, state), state);
+    return;
+  }
+
+  /* Component vnode — we can't introspect its template, so render an opaque
+   * skeleton block carrying any utility classes the user attached to it. */
+  if (typeof type === 'object' || typeof type === 'function') {
+    push(
+      out,
+      h('div', {
+        class: ['a-skel-block', v.props?.class, opts.animationClass],
+        style: v.props?.style as Record<string, string>,
+      }),
+      state
+    );
+  }
+}
+
+function push(out: VNode[], vn: VNode, state: WalkState): void {
+  if (state.emitted >= state.cap) return;
+  out.push(vn);
+  state.emitted++;
+}
+
+function transformElement(
+  v: VNode,
+  tag: string,
+  opts: BuildOptions,
+  depth: number,
+  max: number,
+  state: WalkState
+): VNode {
+  const cls = v.props?.class;
+  const styl = v.props?.style as Record<string, string> | string | undefined;
+
+  if (ATOMIC_TAGS.has(tag)) {
+    return h('div', { class: ['a-skel-block', cls, opts.animationClass], style: styl });
+  }
+
+  if (HEADING_TAGS.has(tag)) {
+    return h(tag, { class: cls, style: styl }, [textBar(opts.animationClass)]);
+  }
+
+  if (PARAGRAPH_TAGS.has(tag)) {
+    const children = v.children;
+    const recursedChildren: VNode[] = [];
+    walk(children as VNodeArrayChildren, opts, depth + 1, max, state, recursedChildren);
+    if (recursedChildren.length > 0) return h(tag, { class: cls, style: styl }, recursedChildren);
+    const lines = estimateLines(children, 3);
+    return h(tag, { class: cls, style: styl }, multiLineBars(lines, opts.animationClass));
+  }
+
+  if (INLINE_TEXT_TAGS.has(tag)) {
+    const children = v.children;
+    const recursedChildren: VNode[] = [];
+    walk(children as VNodeArrayChildren, opts, depth + 1, max, state, recursedChildren);
+    if (recursedChildren.length > 0) return h(tag, { class: cls, style: styl }, recursedChildren);
+    return h(tag, { class: cls, style: styl }, [textBar(opts.animationClass)]);
+  }
+
+  /* Generic container — keep its classes (flex/grid/padding/etc.) and recurse. */
+  if (depth >= max) {
+    return h('div', { class: ['a-skel-block', cls, opts.animationClass], style: styl });
+  }
+  const recursed: VNode[] = [];
+  walk(v.children as VNodeArrayChildren, opts, depth + 1, max, state, recursed);
+  if (recursed.length === 0) {
+    /* Empty container in the source — render as a single block so the layout
+     * still reserves space rather than collapsing to zero height. */
+    return h('div', { class: ['a-skel-block', cls, opts.animationClass], style: styl });
+  }
+  return h(tag, { class: cls, style: styl }, recursed);
+}
+
+function estimateLines(children: unknown, max: number): number {
+  if (typeof children !== 'string') return 1;
+  const len = children.trim().length;
+  if (len === 0)
+    return 2; /* empty interpolation — assume 2 lines so the bar looks paragraph-shaped */
+  if (len < 40) return 1;
+  if (len < 100) return 2;
+  return Math.min(max, 3);
+}
+
+function multiLineBars(lines: number, animationClass: string | null): VNode[] {
+  const out: VNode[] = [];
+  for (let i = 0; i < lines; i++) {
+    out.push(textBar(animationClass, i === lines - 1 && lines > 1 ? 0.65 : 1));
+  }
+  return out;
+}
+
+/* Style objects for the two common bar shapes are reused across calls so a
+ * structural skeleton with 200 text bars doesn't allocate 200 style objects. */
+const BAR_STYLE_FULL = Object.freeze({
+  display: 'inline-block',
+  width: '100%',
+  height: '0.75em',
+  verticalAlign: 'middle',
+  borderRadius: '4px',
+});
+
+const PARTIAL_BAR_CACHE = new Map<number, Readonly<Record<string, string>>>();
+
+function partialBarStyle(widthFraction: number): Readonly<Record<string, string>> {
+  /* Round to one decimal so 0.65, 0.7, 0.85 each get a single cached style. */
+  const key = Math.round(widthFraction * 10) / 10;
+  const hit = PARTIAL_BAR_CACHE.get(key);
+  if (hit) return hit;
+  const made = Object.freeze({
+    display: 'inline-block',
+    width: `${Math.round(key * 100)}%`,
+    height: '0.75em',
+    verticalAlign: 'middle',
+    borderRadius: '4px',
+  });
+  PARTIAL_BAR_CACHE.set(key, made);
+  return made;
+}
+
+function textBar(animationClass: string | null, widthFraction = 1): VNode {
+  return h('span', {
+    class: ['a-skel-block', 'a-skel-block--text', animationClass],
+    style: widthFraction === 1 ? BAR_STYLE_FULL : partialBarStyle(widthFraction),
+  });
+}

package/src/utils/fingerprint.ts

@@ -0,0 +1,42 @@
+import { Comment, Fragment, Text, type VNode } from 'vue';
+
+/**
+ * Derive a default cache key from a slot's vnode tree. Returns the first
+ * non-comment child's component name (or HTML tag). When the slot only contains
+ * text / comments / unknown content, returns `'anonymous'` so the caller can
+ * still cache, but with no useful identity — encourage an explicit `cacheKey`.
+ */
+export function fingerprintSlot(vnodes: VNode[] | undefined): string {
+  if (!vnodes) return 'anonymous';
+  for (const vnode of vnodes) {
+    const tag = describeVNode(vnode);
+    if (tag) return tag;
+  }
+  return 'anonymous';
+}
+
+function describeVNode(vnode: VNode): string | undefined {
+  const t = vnode.type;
+  if (t === Comment || t === Text) return undefined;
+  if (t === Fragment) {
+    const children = vnode.children;
+    if (Array.isArray(children)) {
+      for (const child of children) {
+        if (child && typeof child === 'object' && 'type' in (child as object)) {
+          const found = describeVNode(child as VNode);
+          if (found) return found;
+        }
+      }
+    }
+    return undefined;
+  }
+  if (typeof t === 'string') return t;
+  if (typeof t === 'object' && t !== null) {
+    const named =
+      (t as { name?: string }).name ??
+      (t as { __name?: string }).__name ??
+      (t as { displayName?: string }).displayName;
+    if (named) return named;
+  }
+  return undefined;
+}

package/src/utils/walkDom.ts

@@ -0,0 +1,226 @@
+import type { CSSProperties } from 'vue';
+import type { CachedShape, ShapeNode, ShapeNodeType } from '../types';
+
+export interface WalkOptions {
+  maxDepth: number;
+  /** Hard cap on captured nodes. Default 500. */
+  maxNodes?: number;
+  /** Min CSS-pixel size (either axis) for an element to be emitted. Default 4. */
+  minSize?: number;
+}
+
+const DEFAULT_MAX_NODES = 500;
+const DEFAULT_MIN_SIZE = 4;
+
+/* Atomic elements — never recursed into; rendered as a single block. */
+const LEAF_TAGS = new Set([
+  'IMG',
+  'SVG',
+  'CANVAS',
+  'VIDEO',
+  'INPUT',
+  'TEXTAREA',
+  'SELECT',
+  'BUTTON',
+  'PROGRESS',
+  'METER',
+  'HR',
+]);
+
+/**
+ * Walk `root`'s descendants and produce a list of shimmer blocks that mirror its
+ * rendered layout. Coordinates are relative to `root`'s top-left so the result can
+ * be replayed in any container of the same size.
+ *
+ * Performance:
+ *   - `maxNodes` caps the walk so a 5000-row table doesn't lock up the main thread.
+ *   - `minSize` filters out hairlines (1-2 px paddings, decorative dots) that
+ *     inflate node count without adding visual signal.
+ *   - All `getBoundingClientRect` / `getComputedStyle` reads happen in a single
+ *     top-down pass with no intervening writes, so the browser does one layout
+ *     up front and serves cached values from then on (no layout thrashing).
+ *   - Each emitted `ShapeNode` has a frozen pre-computed `style` (and `lineStyles`
+ *     for multi-line text) so the render path is allocation-free.
+ */
+export function walkDom(root: HTMLElement, options: WalkOptions): CachedShape {
+  const maxNodes = options.maxNodes ?? DEFAULT_MAX_NODES;
+  const minSize = options.minSize ?? DEFAULT_MIN_SIZE;
+
+  const nodes: ShapeNode[] = [];
+  const rootRect = root.getBoundingClientRect();
+  let truncated = false;
+
+  function visit(el: Element, depth: number): void {
+    if (nodes.length >= maxNodes) {
+      truncated = true;
+      return;
+    }
+
+    const html = el as HTMLElement;
+    if (html.dataset?.skeletonIgnore !== undefined) return;
+
+    const cs = window.getComputedStyle(el);
+    if (cs.display === 'none' || cs.visibility === 'hidden' || cs.opacity === '0') return;
+
+    const rect = el.getBoundingClientRect();
+    if (rect.width < minSize || rect.height < minSize) return;
+
+    const tag = el.tagName.toUpperCase();
+    const isLeafTag = LEAF_TAGS.has(tag);
+    const hasStop = html.dataset?.skeletonStop !== undefined;
+    const childElements: Element[] = [];
+    for (let i = 0; i < el.children.length; i++) {
+      const c = el.children[i];
+      if ((c as HTMLElement).dataset?.skeletonIgnore === undefined) childElements.push(c);
+    }
+    const hasOwnText = hasDirectTextContent(el);
+    const reachedDepth = depth >= options.maxDepth;
+    const isLeaf = isLeafTag || hasStop || reachedDepth || childElements.length === 0;
+
+    if (isLeaf) {
+      const node = elementToShape(tag, cs, rect, rootRect, hasOwnText);
+      if (node) nodes.push(node);
+      return;
+    }
+
+    for (let i = 0; i < childElements.length; i++) {
+      if (nodes.length >= maxNodes) {
+        truncated = true;
+        return;
+      }
+      visit(childElements[i], depth + 1);
+    }
+  }
+
+  for (let i = 0; i < root.children.length; i++) {
+    if (nodes.length >= maxNodes) {
+      truncated = true;
+      break;
+    }
+    visit(root.children[i], 1);
+  }
+
+  return Object.freeze({
+    nodes: Object.freeze(nodes),
+    width: Math.round(rootRect.width),
+    height: Math.round(rootRect.height),
+    truncated,
+  }) as CachedShape;
+}
+
+function hasDirectTextContent(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;
+}
+
+function elementToShape(
+  tag: string,
+  cs: CSSStyleDeclaration,
+  rect: DOMRect,
+  origin: DOMRect,
+  hasText: boolean
+): ShapeNode | 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(rect.height);
+
+  const radius = parseFloat(cs.borderRadius) || 0;
+  const minDim = Math.min(w, h);
+  const isCircle = radius >= minDim / 2 - 1 && Math.abs(w - h) <= 2 && minDim > 0;
+
+  let type: ShapeNodeType;
+  let resolvedRadius = radius;
+  let lines: number | undefined;
+  let lineHeight: number | undefined;
+
+  if (tag === 'IMG' || tag === 'SVG' || tag === 'VIDEO' || tag === 'CANVAS') {
+    type = 'image';
+  } else if (isCircle) {
+    type = 'circle';
+    resolvedRadius = Math.floor(minDim / 2);
+  } else if (hasText) {
+    type = 'text';
+    lineHeight = Math.round(parseFloat(cs.lineHeight) || parseFloat(cs.fontSize) * 1.4 || 16);
+    lines = Math.max(1, Math.round(h / lineHeight));
+    resolvedRadius = Math.min(radius, 4);
+  } else {
+    type = 'block';
+  }
+
+  return freezeShape({
+    type,
+    x,
+    y,
+    w,
+    h,
+    radius: resolvedRadius,
+    lines,
+    lineHeight,
+  });
+}
+
+/**
+ * Pre-compute (and freeze) the inline styles used at render time. Doing it once
+ * here means rendering 500 blocks doesn't allocate 500 style objects per frame.
+ */
+function freezeShape(node: {
+  type: ShapeNodeType;
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+  radius: number;
+  lines?: number;
+  lineHeight?: number;
+}): ShapeNode {
+  const style: CSSProperties = Object.freeze({
+    left: `${node.x}px`,
+    top: `${node.y}px`,
+    width: `${node.w}px`,
+    height: `${node.h}px`,
+    borderRadius: `${node.radius}px`,
+  });
+
+  let lineStyles: ReadonlyArray<Readonly<CSSProperties>> | undefined;
+  if (node.type === 'text' && node.lines && node.lines > 1) {
+    const lh = node.lineHeight ?? Math.round(node.h / node.lines);
+    const barHeight = Math.max(8, Math.round(lh * 0.7));
+    const widthFull = `${node.w}px`;
+    const widthLast = `${Math.max(40, Math.round(node.w * 0.7))}px`;
+    const heightStr = `${barHeight}px`;
+    const radiusStr = `${node.radius}px`;
+    const arr: Readonly<CSSProperties>[] = [];
+    for (let i = 1; i <= node.lines; i++) {
+      const isLast = i === node.lines;
+      arr.push(
+        Object.freeze<CSSProperties>({
+          left: `${node.x}px`,
+          top: `${node.y + (i - 1) * lh}px`,
+          width: isLast ? widthLast : widthFull,
+          height: heightStr,
+          borderRadius: radiusStr,
+        })
+      );
+    }
+    lineStyles = Object.freeze(arr);
+  }
+
+  return Object.freeze({
+    type: node.type,
+    x: node.x,
+    y: node.y,
+    w: node.w,
+    h: node.h,
+    radius: node.radius,
+    lines: node.lines,
+    lineHeight: node.lineHeight,
+    style,
+    lineStyles,
+  });
+}

package/web-types.json

@@ -0,0 +1,172 @@
+{
+  "$schema": "https://json.schemastore.org/web-types",
+  "name": "@alikhalilll/a-skeleton",
+  "version": "1.0.0",
+  "js-types-syntax": "typescript",
+  "description-markup": "markdown",
+  "framework": "vue",
+  "framework-config": {
+    "enable-when": {
+      "node-packages": [
+        "vue"
+      ]
+    }
+  },
+  "contributions": {
+    "html": {
+      "vue-components": [
+        {
+          "name": "ASkeleton",
+          "source": {
+            "module": "@alikhalilll/a-skeleton",
+            "symbol": "ASkeleton"
+          },
+          "props": [
+            {
+              "name": "animation",
+              "type": "SkeletonAnimation",
+              "required": false,
+              "description": "Animation variant applied to skeleton blocks. Default `'shimmer'`."
+            },
+            {
+              "name": "cacheKey",
+              "type": "string",
+              "required": false,
+              "description": "Identifier used to look up + persist the captured shape. Falls back to the\nslot's first child component name, then `'anonymous'`. Pass explicitly when\nthe same component renders different shapes depending on props."
+            },
+            {
+              "name": "class",
+              "type": "ClassValue",
+              "required": false,
+              "description": "Class on the outer wrapper."
+            },
+            {
+              "name": "fallback",
+              "type": "SkeletonFallback",
+              "required": false,
+              "description": "What to render when no cached shape is available yet. Default `'shimmer'`."
+            },
+            {
+              "name": "loading",
+              "type": "boolean",
+              "required": true,
+              "description": "When true, render the captured skeleton (or `fallback` slot) instead of the default slot."
+            },
+            {
+              "name": "maxDepth",
+              "type": "number",
+              "required": false,
+              "description": "Max recursion depth during shape capture. Default 6."
+            },
+            {
+              "name": "maxNodes",
+              "type": "number",
+              "required": false,
+              "description": "Hard cap on captured / structurally rendered nodes. Hit this and the walk\nbails out with `truncated: true`. Default 500 — enough for cards, lists,\nfull forms; cut deliberately for screens with hundreds of repeated rows."
+            },
+            {
+              "name": "minNodeSize",
+              "type": "number",
+              "required": false,
+              "description": "Skip elements smaller than this many CSS pixels on either axis during\ncapture. Default 4. Filters out hairlines / inline padding shims that\ninflate the node count without adding visual signal."
+            },
+            {
+              "name": "persist",
+              "type": "boolean",
+              "required": false,
+              "description": "Persist captured shapes to `localStorage` so first-visit skeletons survive reloads. Default false."
+            }
+          ],
+          "slots": [
+            {
+              "name": "default",
+              "description": "The real content. Rendered when `loading` is false; measured to build the skeleton."
+            },
+            {
+              "name": "fallback",
+              "description": "Custom UI to render on a cache miss. Defaults to a single shimmer block."
+            }
+          ]
+        },
+        {
+          "name": "ASkeletonLayer",
+          "source": {
+            "module": "@alikhalilll/a-skeleton",
+            "symbol": "ASkeletonLayer"
+          },
+          "props": [
+            {
+              "name": "animation",
+              "type": "SkeletonAnimation",
+              "required": false,
+              "description": "Animation variant. Default `'shimmer'`."
+            },
+            {
+              "name": "class",
+              "type": "ClassValue",
+              "required": false,
+              "description": "Class on the layer wrapper."
+            },
+            {
+              "name": "shape",
+              "type": "CachedShape",
+              "required": false,
+              "description": "Shape captured by `walkDom` / `useSkeleton`. Renders nothing when undefined."
+            }
+          ]
+        },
+        {
+          "name": "ASkeletonBlock",
+          "source": {
+            "module": "@alikhalilll/a-skeleton",
+            "symbol": "ASkeletonBlock"
+          },
+          "props": [
+            {
+              "name": "animation",
+              "type": "SkeletonAnimation",
+              "required": false,
+              "description": "Animation variant. Default `'shimmer'`."
+            },
+            {
+              "name": "class",
+              "type": "ClassValue",
+              "required": false,
+              "description": "Class on the root (the single block, or the stack wrapper for multi-line text)."
+            },
+            {
+              "name": "h",
+              "type": "string | number",
+              "required": false,
+              "description": "Height as CSS length. Number = pixels."
+            },
+            {
+              "name": "lines",
+              "type": "number",
+              "required": false,
+              "description": "For `type='text'`, render N stacked bars. Last bar is 70% width. Default 1."
+            },
+            {
+              "name": "radius",
+              "type": "string | number",
+              "required": false,
+              "description": "Border radius as CSS length. Number = pixels. For `type='circle'`, this\ndefaults to `'50%'` if not provided."
+            },
+            {
+              "name": "type",
+              "type": "ShapeNodeType",
+              "required": false,
+              "description": "Visual variant. Default `'block'`."
+            },
+            {
+              "name": "w",
+              "type": "string | number",
+              "required": false,
+              "description": "Width as CSS length. Number = pixels. Falls back to whatever the surrounding layout gives."
+            }
+          ]
+        }
+      ]
+    }
+  }
+}