@alikhalilll/a-skeleton 1.0.0

package/src/components/StructuralSkeleton.ts

@@ -0,0 +1,41 @@
+import { defineComponent, type PropType, type VNode, type VNodeArrayChildren } from 'vue';
+import { buildStructuralSkeleton } from '../utils/buildStructuralSkeleton';
+
+/**
+ * Renders a structural skeleton derived from a slot's vnode tree. Pure render
+ * function — no template, no scoped styles — so the parent's class strings
+ * pass through unchanged and Tailwind utilities continue to drive layout.
+ *
+ * `maxNodes` is forwarded to the walker; cap defaults to 300 (see
+ * `buildStructuralSkeleton`). Beyond that the walk stops emitting and the cap
+ * propagates back as a clipped tree, keeping first-paint bounded.
+ */
+export const StructuralSkeleton = defineComponent({
+  name: 'StructuralSkeleton',
+  props: {
+    vnodes: {
+      type: Array as unknown as PropType<VNodeArrayChildren>,
+      required: true,
+    },
+    animation: {
+      type: String as PropType<string | null>,
+      default: null,
+    },
+    maxDepth: {
+      type: Number,
+      default: 8,
+    },
+    maxNodes: {
+      type: Number,
+      default: 300,
+    },
+  },
+  setup(props) {
+    return (): VNode[] =>
+      buildStructuralSkeleton(props.vnodes, {
+        animationClass: props.animation,
+        maxDepth: props.maxDepth,
+        maxNodes: props.maxNodes,
+      });
+  },
+});

package/src/composables/useShapeProbe.ts

@@ -0,0 +1,108 @@
+import { onBeforeUnmount, watch } from 'vue';
+import type { CachedShape } from '../types';
+import { walkDom } from '../utils/walkDom';
+
+export interface ShapeProbeOptions {
+  maxDepth: number;
+  /** Forwarded to `walkDom`. Default 500. */
+  maxNodes?: number;
+  /** Forwarded to `walkDom`. Default 4. */
+  minSize?: number;
+  /**
+   * Debounce window for `ResizeObserver`-triggered re-captures, in ms.
+   * Default 150. Prevents a re-walk every animation frame while the user is
+   * actively dragging the viewport edge. The first capture (initial mount) is
+   * always immediate via `requestAnimationFrame`.
+   */
+  resizeDebounceMs?: number;
+  onCapture: (shape: CachedShape) => void;
+}
+
+const DEFAULT_RESIZE_DEBOUNCE_MS = 150;
+
+/**
+ * Observe `getTarget()` and capture its rendered shape whenever the element
+ * appears or resizes.
+ *
+ * Performance:
+ *   - Initial capture runs via `requestAnimationFrame` so it sneaks into the
+ *     first idle window after mount — no synchronous layout from inside the
+ *     render queue.
+ *   - Subsequent `ResizeObserver` callbacks are debounced (default 150 ms) so a
+ *     drag-resize doesn't trigger a fresh DOM walk per frame.
+ *   - `walkDom` itself enforces `maxNodes` so even a worst-case capture (10k
+ *     descendants) returns in bounded time.
+ */
+export function useShapeProbe(getTarget: () => HTMLElement | null, options: ShapeProbeOptions) {
+  let observer: ResizeObserver | undefined;
+  let frame: number | undefined;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let hasCaptured = false;
+
+  const debounceMs = options.resizeDebounceMs ?? DEFAULT_RESIZE_DEBOUNCE_MS;
+
+  function cleanup() {
+    if (observer) {
+      observer.disconnect();
+      observer = undefined;
+    }
+    if (frame !== undefined) {
+      cancelAnimationFrame(frame);
+      frame = undefined;
+    }
+    if (timer !== undefined) {
+      clearTimeout(timer);
+      timer = undefined;
+    }
+  }
+
+  function capture(el: HTMLElement) {
+    const result = walkDom(el, {
+      maxDepth: options.maxDepth,
+      maxNodes: options.maxNodes,
+      minSize: options.minSize,
+    });
+    if (result.width > 0 && result.height > 0 && result.nodes.length > 0) {
+      hasCaptured = true;
+      options.onCapture(result);
+    }
+  }
+
+  function scheduleImmediate(el: HTMLElement) {
+    if (frame !== undefined) cancelAnimationFrame(frame);
+    frame = requestAnimationFrame(() => {
+      frame = undefined;
+      capture(el);
+    });
+  }
+
+  function scheduleDebounced(el: HTMLElement) {
+    if (timer !== undefined) clearTimeout(timer);
+    timer = setTimeout(() => {
+      timer = undefined;
+      capture(el);
+    }, debounceMs);
+  }
+
+  watch(
+    getTarget,
+    (el) => {
+      cleanup();
+      hasCaptured = false;
+      if (!el || typeof window === 'undefined') return;
+      scheduleImmediate(el);
+      if (typeof ResizeObserver !== 'undefined') {
+        observer = new ResizeObserver(() => {
+          /* ResizeObserver fires once on observe() — let the rAF capture above
+           * handle the initial measurement, then debounce everything that
+           * follows so a drag-resize doesn't trigger a re-walk per frame. */
+          if (hasCaptured) scheduleDebounced(el);
+        });
+        observer.observe(el);
+      }
+    },
+    { immediate: true, flush: 'post' }
+  );
+
+  onBeforeUnmount(cleanup);
+}

package/src/composables/useSkeleton.ts

@@ -0,0 +1,112 @@
+import { shallowRef, type Ref } from 'vue';
+import type { CachedShape } from '../types';
+import { useShapeProbe } from './useShapeProbe';
+import { clearCached, getCached, setCached } from './useSkeletonCache';
+import { walkDom } from '../utils/walkDom';
+
+export interface UseSkeletonOptions {
+  /**
+   * Identifier for the shape cache. Pass the same key wherever the same visual
+   * structure appears so the captured shape replays everywhere.
+   */
+  cacheKey: string;
+  /**
+   * Getter for the element to measure. When it returns `null` (e.g. during the
+   * loading state), no measurement happens. The probe re-arms automatically
+   * once the getter returns an element again.
+   *
+   * Typical pattern: return `null` while loading so the real content is the
+   * only thing ever measured, then the cache feeds the skeleton on the next
+   * load.
+   */
+  target?: () => HTMLElement | null;
+  /** Persist to `localStorage` so first-paint after reload skips the cold start. Default false. */
+  persist?: boolean;
+  /** Forwarded to `walkDom`. Default 6. */
+  maxDepth?: number;
+  /** Forwarded to `walkDom`. Default 500. */
+  maxNodes?: number;
+  /** Forwarded to `walkDom`. Default 4. */
+  minSize?: number;
+  /** Forwarded to `useShapeProbe`. Default 150 ms. */
+  resizeDebounceMs?: number;
+}
+
+export interface UseSkeletonReturn {
+  /** Reactive captured shape — `undefined` on cache miss. Replace your skeleton render path. */
+  shape: Readonly<Ref<CachedShape | undefined>>;
+  /**
+   * Synchronously measure the current target and write to cache. Returns the
+   * captured shape, or `undefined` if the target wasn't available / nothing
+   * worth measuring was rendered. Use when you want to force a capture outside
+   * the automatic `ResizeObserver` flow (e.g. after an animation settles).
+   */
+  captureNow: () => CachedShape | undefined;
+  /** Drop the cache entry for this `cacheKey`. The reactive `shape` flips to `undefined`. */
+  clear: () => void;
+}
+
+/**
+ * High-level building block for custom skeleton UIs. Wires up the probe + cache
+ * + reactivity so the consumer just renders something using the reactive shape:
+ *
+ * ```ts
+ * const containerRef = ref<HTMLElement | null>(null);
+ * const { shape } = useSkeleton({
+ *   cacheKey: 'user-card',
+ *   target: () => (loading.value ? null : containerRef.value),
+ * });
+ * ```
+ *
+ * ```vue
+ * <div ref="containerRef">
+ *   <ASkeletonLayer v-if="loading && shape" :shape="shape" />
+ *   <UserCard v-else :data="user" />
+ * </div>
+ * ```
+ *
+ * For more control, drop down to `useShapeProbe` + `getCached`/`setCached` and
+ * compose your own.
+ */
+export function useSkeleton(options: UseSkeletonOptions): UseSkeletonReturn {
+  const persist = options.persist ?? false;
+  const maxDepth = options.maxDepth ?? 6;
+
+  const shape = shallowRef<CachedShape | undefined>(getCached(options.cacheKey, persist));
+
+  if (options.target) {
+    const getTarget = options.target;
+    useShapeProbe(getTarget, {
+      maxDepth,
+      maxNodes: options.maxNodes,
+      minSize: options.minSize,
+      resizeDebounceMs: options.resizeDebounceMs,
+      onCapture: (captured) => {
+        setCached(options.cacheKey, captured, persist);
+        shape.value = captured;
+      },
+    });
+  }
+
+  function captureNow(): CachedShape | undefined {
+    const el = options.target?.();
+    if (!el || typeof window === 'undefined') return undefined;
+    const captured = walkDom(el, {
+      maxDepth,
+      maxNodes: options.maxNodes,
+      minSize: options.minSize,
+    });
+    if (captured.width <= 0 || captured.height <= 0 || captured.nodes.length === 0)
+      return undefined;
+    setCached(options.cacheKey, captured, persist);
+    shape.value = captured;
+    return captured;
+  }
+
+  function clear(): void {
+    clearCached(options.cacheKey);
+    shape.value = undefined;
+  }
+
+  return { shape, captureNow, clear };
+}

package/src/composables/useSkeletonCache.ts

@@ -0,0 +1,141 @@
+import type { CSSProperties } from 'vue';
+import type { CachedShape, ShapeNode } from '../types';
+
+const memory = new Map<string, CachedShape>();
+const STORAGE_PREFIX = 'a-skeleton:';
+
+/**
+ * Lookup a captured shape by key. Reads in-memory first, then `localStorage` if
+ * `persist` is enabled. SSR-safe — bypasses `window` access on the server.
+ * Rehydrates pre-computed styles for shapes deserialized from older sessions
+ * (Object.freeze + style/lineStyles don't survive `JSON.stringify` round-trip).
+ */
+export function getCached(key: string, persist: boolean): CachedShape | undefined {
+  const hit = memory.get(key);
+  if (hit) return hit;
+  if (!persist || typeof window === 'undefined') return undefined;
+  try {
+    const raw = window.localStorage.getItem(STORAGE_PREFIX + key);
+    if (!raw) return undefined;
+    const parsed = JSON.parse(raw) as CachedShape;
+    const rehydrated = rehydrateShape(parsed);
+    memory.set(key, rehydrated);
+    return rehydrated;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Store a captured shape. `persist=true` mirrors to `localStorage`. */
+export function setCached(key: string, value: CachedShape, persist: boolean): void {
+  memory.set(key, value);
+  if (!persist || typeof window === 'undefined') return;
+  try {
+    /* Only the geometry survives the round-trip; styles get rebuilt on read. */
+    const lean = { width: value.width, height: value.height, nodes: leanNodes(value.nodes) };
+    window.localStorage.setItem(STORAGE_PREFIX + key, JSON.stringify(lean));
+  } catch {
+    /* quota exceeded / disabled storage — silently degrade to in-memory only. */
+  }
+}
+
+/** Drop a single entry (or all entries when no key). Exposed for tests + manual invalidation. */
+export function clearCached(key?: string): void {
+  if (!key) {
+    memory.clear();
+    if (typeof window === 'undefined') return;
+    try {
+      for (const k of Object.keys(window.localStorage)) {
+        if (k.startsWith(STORAGE_PREFIX)) window.localStorage.removeItem(k);
+      }
+    } catch {
+      /* ignore */
+    }
+    return;
+  }
+  memory.delete(key);
+  if (typeof window === 'undefined') return;
+  try {
+    window.localStorage.removeItem(STORAGE_PREFIX + key);
+  } catch {
+    /* ignore */
+  }
+}
+
+/**
+ * Rebuild `style` + `lineStyles` for nodes that lost them via serialization.
+ * Walks the array in-place where possible and freezes the result so the render
+ * path stays allocation-free.
+ */
+function rehydrateShape(shape: CachedShape): CachedShape {
+  const nodes = shape.nodes.map((n) => (n.style ? n : freezeNodeStyles(n)));
+  return Object.freeze({
+    nodes: Object.freeze(nodes),
+    width: shape.width,
+    height: shape.height,
+    truncated: shape.truncated,
+  }) as CachedShape;
+}
+
+function leanNodes(nodes: ReadonlyArray<ShapeNode>): Partial<ShapeNode>[] {
+  /* Strip the (re-derivable) style fields before persisting so the localStorage
+   * payload stays small — a 500-node shape would otherwise serialize ~500 frozen
+   * style objects redundantly. */
+  return nodes.map((n) => ({
+    type: n.type,
+    x: n.x,
+    y: n.y,
+    w: n.w,
+    h: n.h,
+    radius: n.radius,
+    lines: n.lines,
+    lineHeight: n.lineHeight,
+  }));
+}
+
+function freezeNodeStyles(node: ShapeNode): 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/src/index.ts

@@ -0,0 +1,32 @@
+/* Components */
+export { default as ASkeleton } from './components/ASkeleton.vue';
+export { default as ASkeletonLayer } from './components/ASkeletonLayer.vue';
+export { default as ASkeletonBlock } from './components/ASkeletonBlock.vue';
+export { StructuralSkeleton } from './components/StructuralSkeleton';
+
+/* Composables */
+export { useSkeleton } from './composables/useSkeleton';
+export { useShapeProbe } from './composables/useShapeProbe';
+export { getCached, setCached, clearCached } from './composables/useSkeletonCache';
+
+/* Pure utilities — for direct measurement, vnode-walking, default key derivation. */
+export { walkDom } from './utils/walkDom';
+export { buildStructuralSkeleton } from './utils/buildStructuralSkeleton';
+export { fingerprintSlot } from './utils/fingerprint';
+
+/* Types */
+export type {
+  ASkeletonProps,
+  ASkeletonSlots,
+  ASkeletonLayerProps,
+  ASkeletonBlockProps,
+  CachedShape,
+  ShapeNode,
+  ShapeNodeType,
+  SkeletonAnimation,
+  SkeletonFallback,
+} from './types';
+export type { UseSkeletonOptions, UseSkeletonReturn } from './composables/useSkeleton';
+export type { ShapeProbeOptions } from './composables/useShapeProbe';
+export type { WalkOptions } from './utils/walkDom';
+export type { BuildOptions } from './utils/buildStructuralSkeleton';

package/src/nuxt/index.ts

@@ -0,0 +1,47 @@
+import { defineNuxtModule, addComponent } from '@nuxt/kit';
+import type { NuxtModule } from '@nuxt/schema';
+
+/**
+ * `@alikhalilll/a-skeleton/nuxt` — registers the skeleton components for Nuxt
+ * auto-import. The auto-imported names are the package's native names:
+ *
+ *   <ASkeleton :loading>…</ASkeleton>     <!-- slot wrapper, two-layer flow -->
+ *   <ASkeletonLayer :shape="…" />          <!-- replay a CachedShape directly -->
+ *   <ASkeletonBlock type="circle" w="64" h="64" />  <!-- hand-crafted skeleton primitive -->
+ *
+ *   modules: ['@alikhalilll/a-skeleton/nuxt'],
+ *   aSkeleton: { prefix: 'A' },   // optional
+ *
+ * Styles are not auto-injected; add `'@alikhalilll/a-skeleton/styles.css'` to
+ * your Nuxt `css` array.
+ */
+
+export interface ModuleOptions {
+  /** Optional prefix prepended to the registered component name. */
+  prefix?: string;
+}
+
+const COMPONENTS: Record<string, string> = {
+  ASkeleton: '@alikhalilll/a-skeleton',
+  ASkeletonLayer: '@alikhalilll/a-skeleton',
+  ASkeletonBlock: '@alikhalilll/a-skeleton',
+};
+
+const module: NuxtModule<ModuleOptions> = defineNuxtModule<ModuleOptions>({
+  meta: {
+    name: '@alikhalilll/a-skeleton',
+    configKey: 'aSkeleton',
+    compatibility: { nuxt: '>=3.0.0' },
+  },
+  defaults: { prefix: '' },
+  setup(opts) {
+    const prefix = opts.prefix ?? '';
+    for (const [exportName, from] of Object.entries(COMPONENTS)) {
+      const baseName = exportName.startsWith('A') ? exportName.slice(1) : exportName;
+      const registeredName = `${prefix}${prefix ? baseName : exportName}`;
+      addComponent({ name: registeredName, export: exportName, filePath: from });
+    }
+  },
+});
+
+export default module;

package/src/resolver/index.ts

@@ -0,0 +1,36 @@
+import type { ComponentResolver } from 'unplugin-vue-components';
+
+/**
+ * `@alikhalilll/a-skeleton/resolver` — auto-import resolver for non-Nuxt
+ * Vite/Webpack consumers via `unplugin-vue-components`.
+ *
+ *   import Components from 'unplugin-vue-components/vite';
+ *   import ASkeletonResolver from '@alikhalilll/a-skeleton/resolver';
+ *   export default { plugins: [Components({ resolvers: [ASkeletonResolver()] })] };
+ *
+ * Registers `<ASkeleton>`, `<ASkeletonLayer>`, `<ASkeletonBlock>`.
+ */
+
+export interface ResolverOptions {
+  /** Optional prefix the consumer uses (e.g. `'A'`). Defaults to the native `A*` names. */
+  prefix?: string;
+}
+
+const COMPONENT_TO_ENTRY: Record<string, string> = {
+  ASkeleton: '@alikhalilll/a-skeleton',
+  ASkeletonLayer: '@alikhalilll/a-skeleton',
+  ASkeletonBlock: '@alikhalilll/a-skeleton',
+};
+
+export default function ASkeletonResolver(opts: ResolverOptions = {}): ComponentResolver {
+  const prefix = opts.prefix ?? '';
+  return {
+    type: 'component',
+    resolve(name) {
+      const bare = prefix && name.startsWith(prefix) ? name.slice(prefix.length) : name;
+      const from = COMPONENT_TO_ENTRY[bare];
+      if (!from) return;
+      return { name: bare, from };
+    },
+  };
+}

package/src/types.ts

@@ -0,0 +1,108 @@
+import type { CSSProperties, HTMLAttributes } from 'vue';
+
+export type ShapeNodeType = 'block' | 'text' | 'image' | 'circle';
+
+/** A single shimmer block in a captured skeleton — positioned absolutely inside the layer. */
+export interface ShapeNode {
+  type: ShapeNodeType;
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+  radius: number;
+  /** For multi-line text leaves, how many lines to render. */
+  lines?: number;
+  /** Line-height used when expanding `lines` into stacked bars. */
+  lineHeight?: number;
+  /**
+   * Pre-computed (and frozen) inline style for the block. Built once during
+   * capture so the render path never allocates a style object per node per
+   * render — meaningful when a cache has hundreds of nodes.
+   */
+  style?: Readonly<CSSProperties>;
+  /**
+   * Pre-computed line styles for multi-line text. `lines` long when set. Same
+   * reason as `style`: avoids `textLineStyle(node, i)` calls in the template.
+   */
+  lineStyles?: ReadonlyArray<Readonly<CSSProperties>>;
+}
+
+export interface CachedShape {
+  nodes: ReadonlyArray<ShapeNode>;
+  width: number;
+  height: number;
+  /** Was the walk cut short by `maxNodes`? Surface so consumers can tune the budget. */
+  truncated?: boolean;
+}
+
+export type SkeletonAnimation = 'shimmer' | 'pulse' | 'none';
+export type SkeletonFallback = 'shimmer' | 'block';
+
+export interface ASkeletonProps {
+  /** When true, render the captured skeleton (or `fallback` slot) instead of the default slot. */
+  loading: boolean;
+  /**
+   * Identifier used to look up + persist the captured shape. Falls back to the
+   * slot's first child component name, then `'anonymous'`. Pass explicitly when
+   * the same component renders different shapes depending on props.
+   */
+  cacheKey?: string;
+  /** Max recursion depth during shape capture. Default 6. */
+  maxDepth?: number;
+  /**
+   * Hard cap on captured / structurally rendered nodes. Hit this and the walk
+   * bails out with `truncated: true`. Default 500 — enough for cards, lists,
+   * full forms; cut deliberately for screens with hundreds of repeated rows.
+   */
+  maxNodes?: number;
+  /**
+   * Skip elements smaller than this many CSS pixels on either axis during
+   * capture. Default 4. Filters out hairlines / inline padding shims that
+   * inflate the node count without adding visual signal.
+   */
+  minNodeSize?: number;
+  /** Persist captured shapes to `localStorage` so first-visit skeletons survive reloads. Default false. */
+  persist?: boolean;
+  /** Animation variant applied to skeleton blocks. Default `'shimmer'`. */
+  animation?: SkeletonAnimation;
+  /** What to render when no cached shape is available yet. Default `'shimmer'`. */
+  fallback?: SkeletonFallback;
+  /** Class on the outer wrapper. */
+  class?: HTMLAttributes['class'];
+}
+
+export interface ASkeletonSlots {
+  /** The real content. Rendered when `loading` is false; measured to build the skeleton. */
+  default?: () => unknown;
+  /** Custom UI to render on a cache miss. Defaults to a single shimmer block. */
+  fallback?: () => unknown;
+}
+
+export interface ASkeletonLayerProps {
+  /** Shape captured by `walkDom` / `useSkeleton`. Renders nothing when undefined. */
+  shape?: CachedShape;
+  /** Animation variant. Default `'shimmer'`. */
+  animation?: SkeletonAnimation;
+  /** Class on the layer wrapper. */
+  class?: HTMLAttributes['class'];
+}
+
+export interface ASkeletonBlockProps {
+  /** Visual variant. Default `'block'`. */
+  type?: ShapeNodeType;
+  /** Width as CSS length. Number = pixels. Falls back to whatever the surrounding layout gives. */
+  w?: number | string;
+  /** Height as CSS length. Number = pixels. */
+  h?: number | string;
+  /**
+   * Border radius as CSS length. Number = pixels. For `type='circle'`, this
+   * defaults to `'50%'` if not provided.
+   */
+  radius?: number | string;
+  /** For `type='text'`, render N stacked bars. Last bar is 70% width. Default 1. */
+  lines?: number;
+  /** Animation variant. Default `'shimmer'`. */
+  animation?: SkeletonAnimation;
+  /** Class on the root (the single block, or the stack wrapper for multi-line text). */
+  class?: HTMLAttributes['class'];
+}