@alikhalilll/a-skeleton 1.0.0 → 1.2.0

package/src/components/variants/ASkeletonHeading.vue

@@ -0,0 +1,47 @@
+<script setup lang="ts">
+import { computed, type HTMLAttributes } from 'vue';
+import { cn } from '@alikhalilll/a-ui-base';
+
+interface Props {
+  level?: 1 | 2 | 3 | 4 | 5 | 6;
+  width?: number | string;
+  animation?: 'pulse' | 'shimmer' | 'wave' | 'none';
+  class?: HTMLAttributes['class'];
+}
+
+const props = withDefaults(defineProps<Props>(), { level: 2, animation: 'pulse' });
+
+const animClass = computed(() =>
+  props.animation === 'none' ? null : `a-skel-anim-${props.animation}`
+);
+
+const HEIGHT_BY_LEVEL: Record<number, string> = {
+  1: '2.25rem',
+  2: '1.75rem',
+  3: '1.5rem',
+  4: '1.25rem',
+  5: '1.125rem',
+  6: '1rem',
+};
+
+const rootStyle = computed(() => ({
+  width:
+    props.width !== undefined
+      ? typeof props.width === 'number'
+        ? `${props.width}px`
+        : String(props.width)
+      : '60%',
+  height: HEIGHT_BY_LEVEL[props.level],
+}));
+</script>
+
+<template>
+  <div
+    :class="cn('a-skel a-skel-variant-heading', animClass, props.class)"
+    :style="rootStyle"
+    role="status"
+    aria-busy="true"
+  >
+    <span class="a-skel-sr-only">Loading heading…</span>
+  </div>
+</template>

package/src/components/variants/ASkeletonImage.vue

@@ -0,0 +1,57 @@
+<script setup lang="ts">
+import { computed, type HTMLAttributes } from 'vue';
+import { cn } from '@alikhalilll/a-ui-base';
+
+interface Props {
+  ratio?: string;
+  width?: number | string;
+  height?: number | string;
+  showIcon?: boolean;
+  animation?: 'pulse' | 'shimmer' | 'wave' | 'none';
+  class?: HTMLAttributes['class'];
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  ratio: '16 / 9',
+  showIcon: true,
+  animation: 'pulse',
+});
+
+const animClass = computed(() =>
+  props.animation === 'none' ? null : `a-skel-anim-${props.animation}`
+);
+
+const rootStyle = computed(() => {
+  const s: Record<string, string> = {};
+  if (props.ratio) s.aspectRatio = props.ratio;
+  if (props.width !== undefined)
+    s.width = typeof props.width === 'number' ? `${props.width}px` : String(props.width);
+  if (props.height !== undefined)
+    s.height = typeof props.height === 'number' ? `${props.height}px` : String(props.height);
+  return s;
+});
+</script>
+
+<template>
+  <div
+    :class="cn('a-skel a-skel-variant-image', animClass, props.class)"
+    :style="rootStyle"
+    role="status"
+    aria-busy="true"
+  >
+    <svg
+      v-if="props.showIcon"
+      class="size-10"
+      viewBox="0 0 24 24"
+      fill="none"
+      xmlns="http://www.w3.org/2000/svg"
+      aria-hidden="true"
+    >
+      <path
+        d="M19 5H5a2 2 0 0 0-2 2v10a2 2 0 0 0 2 2h14a2 2 0 0 0 2-2V7a2 2 0 0 0-2-2Zm-3.5 4a1.5 1.5 0 1 1 0 3 1.5 1.5 0 0 1 0-3ZM19 17H5l3.5-4.5 2.5 3 3.5-4.5L19 17Z"
+        fill="currentColor"
+      />
+    </svg>
+    <span class="a-skel-sr-only">Loading image…</span>
+  </div>
+</template>

package/src/components/variants/ASkeletonInput.vue

@@ -0,0 +1,33 @@
+<script setup lang="ts">
+import { computed, type HTMLAttributes } from 'vue';
+import { cn } from '@alikhalilll/a-ui-base';
+
+interface Props {
+  width?: number | string;
+  height?: number | string;
+  animation?: 'pulse' | 'shimmer' | 'wave' | 'none';
+  class?: HTMLAttributes['class'];
+}
+
+const props = withDefaults(defineProps<Props>(), { width: '100%', height: 40, animation: 'pulse' });
+
+const animClass = computed(() =>
+  props.animation === 'none' ? null : `a-skel-anim-${props.animation}`
+);
+
+const rootStyle = computed(() => ({
+  width: typeof props.width === 'number' ? `${props.width}px` : String(props.width),
+  height: typeof props.height === 'number' ? `${props.height}px` : String(props.height),
+}));
+</script>
+
+<template>
+  <div
+    :class="cn('a-skel a-skel-variant-input', animClass, props.class)"
+    :style="rootStyle"
+    role="status"
+    aria-busy="true"
+  >
+    <span class="a-skel-sr-only">Loading input…</span>
+  </div>
+</template>

package/src/components/variants/ASkeletonListItem.vue

@@ -0,0 +1,40 @@
+<script setup lang="ts">
+import { computed, type HTMLAttributes } from 'vue';
+import { cn } from '@alikhalilll/a-ui-base';
+import ASkeletonAvatar from './ASkeletonAvatar.vue';
+import ASkeletonText from './ASkeletonText.vue';
+
+interface Props {
+  avatar?: boolean;
+  lines?: 1 | 2 | 3;
+  trailing?: boolean;
+  animation?: 'pulse' | 'shimmer' | 'wave' | 'none';
+  class?: HTMLAttributes['class'];
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  avatar: true,
+  lines: 2,
+  trailing: false,
+  animation: 'pulse',
+});
+
+const animClass = computed(() =>
+  props.animation === 'none' ? null : `a-skel-anim-${props.animation}`
+);
+</script>
+
+<template>
+  <div :class="cn('a-skel-variant-list-item', props.class)" role="status" aria-busy="true">
+    <ASkeletonAvatar v-if="props.avatar" :size="40" :animation="props.animation" />
+    <div class="a-skel-variant-list-item__body">
+      <ASkeletonText :lines="props.lines" :animation="props.animation" />
+    </div>
+    <div
+      v-if="props.trailing"
+      :class="cn('a-skel a-skel-variant-button', animClass)"
+      :style="{ width: '40px', height: '24px' }"
+    />
+    <span class="a-skel-sr-only">Loading list item…</span>
+  </div>
+</template>

package/src/components/variants/ASkeletonTable.vue

@@ -0,0 +1,49 @@
+<script setup lang="ts">
+import { computed, type HTMLAttributes } from 'vue';
+import { cn } from '@alikhalilll/a-ui-base';
+
+interface Props {
+  rows?: number;
+  columns?: number;
+  showHeader?: boolean;
+  animation?: 'pulse' | 'shimmer' | 'wave' | 'none';
+  class?: HTMLAttributes['class'];
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  rows: 5,
+  columns: 4,
+  showHeader: true,
+  animation: 'pulse',
+});
+
+const animClass = computed(() =>
+  props.animation === 'none' ? null : `a-skel-anim-${props.animation}`
+);
+
+const rowStyle = computed(() => ({
+  gridTemplateColumns: `repeat(${props.columns}, minmax(0, 1fr))`,
+}));
+</script>
+
+<template>
+  <div :class="cn('a-skel-variant-table', props.class)" role="status" aria-busy="true">
+    <div v-if="props.showHeader" class="a-skel-variant-table__row" :style="rowStyle">
+      <div
+        v-for="c in props.columns"
+        :key="`h-${c}`"
+        :class="cn('a-skel a-skel-variant-heading', animClass)"
+        :style="{ height: '1.5rem', width: '70%' }"
+      />
+    </div>
+    <div v-for="r in props.rows" :key="r" class="a-skel-variant-table__row" :style="rowStyle">
+      <div
+        v-for="c in props.columns"
+        :key="`${r}-${c}`"
+        :class="cn('a-skel a-skel-variant-text', animClass)"
+        :style="{ width: c === 1 ? '85%' : c === props.columns ? '50%' : '70%' }"
+      />
+    </div>
+    <span class="a-skel-sr-only">Loading table…</span>
+  </div>
+</template>

package/src/components/variants/ASkeletonText.vue

@@ -0,0 +1,49 @@
+<script setup lang="ts">
+import { computed, type HTMLAttributes } from 'vue';
+import { cn } from '@alikhalilll/a-ui-base';
+
+interface Props {
+  lines?: number;
+  width?: number | string;
+  /** Animation variant. Default `'pulse'`. */
+  animation?: 'pulse' | 'shimmer' | 'wave' | 'none';
+  class?: HTMLAttributes['class'];
+}
+
+const props = withDefaults(defineProps<Props>(), { lines: 1, animation: 'pulse' });
+
+const animClass = computed(() =>
+  props.animation === 'none' ? null : `a-skel-anim-${props.animation}`
+);
+const rootStyle = computed(() =>
+  props.width !== undefined
+    ? { width: typeof props.width === 'number' ? `${props.width}px` : String(props.width) }
+    : undefined
+);
+
+function widthForLine(i: number): string {
+  /* Vuetify-style: last line ≈ 65 %, intermediate lines ≈ 85–100 %.
+   * This adds rhythm so a 3-line paragraph doesn't look like a brick. */
+  if (i === props.lines - 1 && props.lines > 1) return '65%';
+  const palette = ['100%', '92%', '88%', '95%'];
+  return palette[i % palette.length]!;
+}
+</script>
+
+<template>
+  <div
+    :class="cn('a-skel-variants-text', props.class)"
+    :style="rootStyle"
+    role="status"
+    aria-live="polite"
+    aria-busy="true"
+  >
+    <div
+      v-for="i in props.lines"
+      :key="i"
+      :class="cn('a-skel a-skel-variant-text', animClass)"
+      :style="{ width: widthForLine(i - 1), marginTop: i > 1 ? '0.5em' : undefined }"
+    />
+    <span class="a-skel-sr-only">Loading…</span>
+  </div>
+</template>

package/src/components/variants/ASkeletonVideo.vue

@@ -0,0 +1,55 @@
+<script setup lang="ts">
+import { computed, type HTMLAttributes } from 'vue';
+import { cn } from '@alikhalilll/a-ui-base';
+
+interface Props {
+  ratio?: string;
+  width?: number | string;
+  height?: number | string;
+  showIcon?: boolean;
+  animation?: 'pulse' | 'shimmer' | 'wave' | 'none';
+  class?: HTMLAttributes['class'];
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  ratio: '16 / 9',
+  showIcon: true,
+  animation: 'pulse',
+});
+
+const animClass = computed(() =>
+  props.animation === 'none' ? null : `a-skel-anim-${props.animation}`
+);
+
+const rootStyle = computed(() => {
+  const s: Record<string, string> = {};
+  if (props.ratio) s.aspectRatio = props.ratio;
+  if (props.width !== undefined)
+    s.width = typeof props.width === 'number' ? `${props.width}px` : String(props.width);
+  if (props.height !== undefined)
+    s.height = typeof props.height === 'number' ? `${props.height}px` : String(props.height);
+  return s;
+});
+</script>
+
+<template>
+  <div
+    :class="cn('a-skel a-skel-variant-video', animClass, props.class)"
+    :style="rootStyle"
+    role="status"
+    aria-busy="true"
+  >
+    <svg
+      v-if="props.showIcon"
+      class="size-12"
+      viewBox="0 0 24 24"
+      fill="none"
+      xmlns="http://www.w3.org/2000/svg"
+      aria-hidden="true"
+    >
+      <circle cx="12" cy="12" r="10" stroke="currentColor" stroke-width="1.5" />
+      <path d="M10 8l6 4-6 4V8Z" fill="currentColor" />
+    </svg>
+    <span class="a-skel-sr-only">Loading video…</span>
+  </div>
+</template>

package/src/composables/useShapeProbe.ts

@@ -1,12 +1,24 @@
 import { onBeforeUnmount, watch } from 'vue';
-import type { CachedShape } from '../types';
+import type { CachedShape, StructuralShape } from '../types';
 import { walkDom } from '../utils/walkDom';
 
-export interface ShapeProbeOptions {
+export type ProbeShape = CachedShape | StructuralShape;
+
+/**
+ * Pluggable capture strategy. `walkDom` is the default (flat, absolute-
+ * positioned `CachedShape`). Recipe 3 passes `walkStructural` to produce a
+ * tree-shaped `StructuralShape` instead.
+ */
+export type CaptureStrategy<S extends ProbeShape> = (
+  el: HTMLElement,
+  options: { maxDepth: number; maxNodes?: number; minSize?: number }
+) => S;
+
+export interface ShapeProbeOptions<S extends ProbeShape = CachedShape> {
   maxDepth: number;
-  /** Forwarded to `walkDom`. Default 500. */
+  /** Forwarded to the capture strategy. Default 500. */
   maxNodes?: number;
-  /** Forwarded to `walkDom`. Default 4. */
+  /** Forwarded to the capture strategy. Default 4. */
   minSize?: number;
   /**
    * Debounce window for `ResizeObserver`-triggered re-captures, in ms.
@@ -15,7 +27,12 @@ export interface ShapeProbeOptions {
    * always immediate via `requestAnimationFrame`.
    */
   resizeDebounceMs?: number;
-  onCapture: (shape: CachedShape) => void;
+  /**
+   * Capture strategy. Default: `walkDom` (flat positioned-block model).
+   * Pass `walkStructural` for the tree-shaped Recipe 3 model.
+   */
+  capture?: CaptureStrategy<S>;
+  onCapture: (shape: S) => void;
 }
 
 const DEFAULT_RESIZE_DEBOUNCE_MS = 150;
@@ -30,16 +47,20 @@ const DEFAULT_RESIZE_DEBOUNCE_MS = 150;
  *     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.
+ *   - The capture strategy itself enforces `maxNodes` so even a worst-case
+ *     capture (10k descendants) returns in bounded time.
  */
-export function useShapeProbe(getTarget: () => HTMLElement | null, options: ShapeProbeOptions) {
+export function useShapeProbe<S extends ProbeShape = CachedShape>(
+  getTarget: () => HTMLElement | null,
+  options: ShapeProbeOptions<S>
+): void {
   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;
+  const captureFn = options.capture ?? (walkDom as unknown as CaptureStrategy<S>);
 
   function cleanup() {
     if (observer) {
@@ -57,11 +78,14 @@ export function useShapeProbe(getTarget: () => HTMLElement | null, options: Shap
   }
 
   function capture(el: HTMLElement) {
-    const result = walkDom(el, {
+    const result = captureFn(el, {
       maxDepth: options.maxDepth,
       maxNodes: options.maxNodes,
       minSize: options.minSize,
     });
+    /* Both shape variants expose `width`, `height`, `nodes` — guard against an
+     * empty capture (target rendered with zero size or an unreachable subtree)
+     * so the cache never receives a meaningless entry. */
     if (result.width > 0 && result.height > 0 && result.nodes.length > 0) {
       hasCaptured = true;
       options.onCapture(result);

package/src/composables/useSkeleton.ts

@@ -1,8 +1,12 @@
 import { shallowRef, type Ref } from 'vue';
-import type { CachedShape } from '../types';
+import type { StructuralShape } from '../types';
 import { useShapeProbe } from './useShapeProbe';
-import { clearCached, getCached, setCached } from './useSkeletonCache';
-import { walkDom } from '../utils/walkDom';
+import {
+  clearCachedStructural,
+  getCachedStructural,
+  setCachedStructural,
+} from './useSkeletonCache';
+import { walkStructural } from '../utils/walkStructural';
 
 export interface UseSkeletonOptions {
   /**
@@ -22,33 +26,37 @@ export interface UseSkeletonOptions {
   target?: () => HTMLElement | null;
   /** Persist to `localStorage` so first-paint after reload skips the cold start. Default false. */
   persist?: boolean;
-  /** Forwarded to `walkDom`. Default 6. */
+  /** Forwarded to `walkStructural`. Default 12. */
   maxDepth?: number;
-  /** Forwarded to `walkDom`. Default 500. */
+  /** Forwarded to `walkStructural`. Default 500. */
   maxNodes?: number;
-  /** Forwarded to `walkDom`. Default 4. */
+  /** Forwarded to `walkStructural`. 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>>;
+  /** Reactive captured shape — `undefined` on cache miss. Feed it to `<ASkeletonLayer>`. */
+  shape: Readonly<Ref<StructuralShape | 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;
+  captureNow: () => StructuralShape | undefined;
   /** Drop the cache entry for this `cacheKey`. The reactive `shape` flips to `undefined`. */
   clear: () => void;
 }
 
+const DEFAULT_MAX_DEPTH = 12;
+
 /**
- * High-level building block for custom skeleton UIs. Wires up the probe + cache
- * + reactivity so the consumer just renders something using the reactive shape:
+ * High-level building block for Recipe 3 — wires the structural capture +
+ * cache + reactivity around a target element. The reactive `shape` is fed to
+ * `<ASkeletonLayer>` which renders it in normal flow inside the consumer's
+ * container.
  *
  * ```ts
  * const containerRef = ref<HTMLElement | null>(null);
@@ -65,46 +73,50 @@ export interface UseSkeletonReturn {
  * </div>
  * ```
  *
- * For more control, drop down to `useShapeProbe` + `getCached`/`setCached` and
- * compose your own.
+ * For more control, drop down to `useShapeProbe` (pass `walkStructural` as the
+ * capture strategy) + `getCachedStructural` / `setCachedStructural` and compose
+ * your own orchestration.
  */
 export function useSkeleton(options: UseSkeletonOptions): UseSkeletonReturn {
   const persist = options.persist ?? false;
-  const maxDepth = options.maxDepth ?? 6;
+  const maxDepth = options.maxDepth ?? DEFAULT_MAX_DEPTH;
 
-  const shape = shallowRef<CachedShape | undefined>(getCached(options.cacheKey, persist));
+  const shape = shallowRef<StructuralShape | undefined>(
+    getCachedStructural(options.cacheKey, persist)
+  );
 
   if (options.target) {
     const getTarget = options.target;
-    useShapeProbe(getTarget, {
+    useShapeProbe<StructuralShape>(getTarget, {
       maxDepth,
       maxNodes: options.maxNodes,
       minSize: options.minSize,
       resizeDebounceMs: options.resizeDebounceMs,
+      capture: walkStructural,
       onCapture: (captured) => {
-        setCached(options.cacheKey, captured, persist);
+        setCachedStructural(options.cacheKey, captured, persist);
         shape.value = captured;
       },
     });
   }
 
-  function captureNow(): CachedShape | undefined {
+  function captureNow(): StructuralShape | undefined {
     const el = options.target?.();
     if (!el || typeof window === 'undefined') return undefined;
-    const captured = walkDom(el, {
+    const captured = walkStructural(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);
+    setCachedStructural(options.cacheKey, captured, persist);
     shape.value = captured;
     return captured;
   }
 
   function clear(): void {
-    clearCached(options.cacheKey);
+    clearCachedStructural(options.cacheKey);
     shape.value = undefined;
   }