@alikhalilll/a-skeleton 1.0.0

package/dist/index.d.cts

@@ -0,0 +1,351 @@
+import { CSSProperties, HTMLAttributes, PropType, Ref, VNode, VNodeArrayChildren, VNodeChild } from "vue";
+
+//#region src/types.d.ts
+type ShapeNodeType = 'block' | 'text' | 'image' | 'circle';
+/** A single shimmer block in a captured skeleton — positioned absolutely inside the layer. */
+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>>;
+}
+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;
+}
+type SkeletonAnimation = 'shimmer' | 'pulse' | 'none';
+type SkeletonFallback = 'shimmer' | 'block';
+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'];
+}
+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;
+}
+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'];
+}
+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'];
+}
+//#endregion
+//#region src/components/ASkeleton.vue.d.ts
+type __VLS_Slots = ASkeletonSlots;
+declare const __VLS_base: import("vue").DefineComponent<ASkeletonProps, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<ASkeletonProps> & Readonly<{}>, {
+  animation: SkeletonAnimation;
+  maxDepth: number;
+  maxNodes: number;
+  minNodeSize: number;
+  persist: boolean;
+  fallback: SkeletonFallback;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const __VLS_export$2: typeof __VLS_base;
+declare const _default: typeof __VLS_export$2;
+//#endregion
+//#region src/components/ASkeletonLayer.vue.d.ts
+declare const __VLS_export$1: import("vue").DefineComponent<ASkeletonLayerProps, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<ASkeletonLayerProps> & Readonly<{}>, {
+  animation: SkeletonAnimation;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default$2: typeof __VLS_export$1;
+//#endregion
+//#region src/components/ASkeletonBlock.vue.d.ts
+declare const __VLS_export: import("vue").DefineComponent<ASkeletonBlockProps, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<ASkeletonBlockProps> & Readonly<{}>, {
+  type: ShapeNodeType;
+  lines: number;
+  animation: SkeletonAnimation;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default$1: typeof __VLS_export;
+//#endregion
+//#region src/components/StructuralSkeleton.d.ts
+/**
+ * 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.
+ */
+declare const StructuralSkeleton: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
+  vnodes: {
+    type: PropType<VNodeArrayChildren>;
+    required: true;
+  };
+  animation: {
+    type: PropType<string | null>;
+    default: null;
+  };
+  maxDepth: {
+    type: NumberConstructor;
+    default: number;
+  };
+  maxNodes: {
+    type: NumberConstructor;
+    default: number;
+  };
+}>, () => VNode[], {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<{
+  vnodes: {
+    type: PropType<VNodeArrayChildren>;
+    required: true;
+  };
+  animation: {
+    type: PropType<string | null>;
+    default: null;
+  };
+  maxDepth: {
+    type: NumberConstructor;
+    default: number;
+  };
+  maxNodes: {
+    type: NumberConstructor;
+    default: number;
+  };
+}>> & Readonly<{}>, {
+  animation: string | null;
+  maxDepth: number;
+  maxNodes: number;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+//#endregion
+//#region src/composables/useSkeleton.d.ts
+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;
+}
+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.
+ */
+declare function useSkeleton(options: UseSkeletonOptions): UseSkeletonReturn;
+//#endregion
+//#region src/composables/useShapeProbe.d.ts
+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;
+}
+/**
+ * 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.
+ */
+declare function useShapeProbe(getTarget: () => HTMLElement | null, options: ShapeProbeOptions): void;
+//#endregion
+//#region src/composables/useSkeletonCache.d.ts
+/**
+ * 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).
+ */
+declare function getCached(key: string, persist: boolean): CachedShape | undefined;
+/** Store a captured shape. `persist=true` mirrors to `localStorage`. */
+declare function setCached(key: string, value: CachedShape, persist: boolean): void;
+/** Drop a single entry (or all entries when no key). Exposed for tests + manual invalidation. */
+declare function clearCached(key?: string): void;
+//#endregion
+//#region src/utils/walkDom.d.ts
+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;
+}
+/**
+ * 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.
+ */
+declare function walkDom(root: HTMLElement, options: WalkOptions): CachedShape;
+//#endregion
+//#region src/utils/buildStructuralSkeleton.d.ts
+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;
+}
+/**
+ * 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.
+ */
+declare function buildStructuralSkeleton(vnodes: VNodeChild | VNodeArrayChildren | undefined | null, opts: BuildOptions): VNode[];
+//#endregion
+//#region src/utils/fingerprint.d.ts
+/**
+ * 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`.
+ */
+declare function fingerprintSlot(vnodes: VNode[] | undefined): string;
+//#endregion
+export { _default as ASkeleton, _default$1 as ASkeletonBlock, type ASkeletonBlockProps, _default$2 as ASkeletonLayer, type ASkeletonLayerProps, type ASkeletonProps, type ASkeletonSlots, type BuildOptions, type CachedShape, type ShapeNode, type ShapeNodeType, type ShapeProbeOptions, type SkeletonAnimation, type SkeletonFallback, StructuralSkeleton, type UseSkeletonOptions, type UseSkeletonReturn, type WalkOptions, buildStructuralSkeleton, clearCached, fingerprintSlot, getCached, setCached, useShapeProbe, useSkeleton, walkDom };
+//# sourceMappingURL=index.d.cts.map