@alikhalilll/a-smart-skeleton 0.0.0-stage → 2.0.0

package/src/components/ASmartSkeletonSuspense.vue

@@ -0,0 +1,142 @@
+<script lang="ts">
+import { defineComponent, h, onBeforeUnmount, onMounted, ref, Suspense, type PropType } from 'vue';
+import { ATTR_PANE, ATTR_REVEAL, boxOf, fadeIn, fadeOut, Memory, type RevealMode } from '../core';
+import { useSmartSkeleton } from '../composables/useSmartSkeleton';
+import { useStyles } from '../composables/useStyles';
+import { Loading } from './ASmartSkeleton.vue';
+
+type State = { waited: boolean; exit: (() => void) | null };
+const state = { type: Object as PropType<State>, required: true } as const;
+
+export const Fallback = defineComponent({
+  name: 'ASmartSkeletonFallback',
+  props: { id: String, label: String, reveal: [String, Object] as PropType<RevealMode>, state },
+  setup(props, { slots }) {
+    const element = ref<HTMLElement | null>(null);
+    const config = useSmartSkeleton();
+
+    onMounted(() => {
+      const pane = element.value;
+      const reveal = pane?.parentElement;
+      if (!pane || !reveal) return;
+      // eslint-disable-next-line vue/no-mutating-props
+      props.state.waited = true;
+      fadeIn(pane, props.reveal ?? config.reveal, { initial: true });
+      reveal.setAttribute('aria-busy', 'true');
+    });
+
+    onBeforeUnmount(() => {
+      const pane = element.value;
+      const reveal = pane?.parentElement;
+      if (!pane || !reveal) return;
+      reveal.removeAttribute('aria-busy');
+
+      const box = boxOf(pane);
+      const copy = pane.cloneNode(true) as HTMLElement;
+      // eslint-disable-next-line vue/no-mutating-props
+      props.state.exit = () => {
+        Object.assign(copy.style, {
+          position: 'absolute',
+          top: `${box.top}px`,
+          left: `${box.left}px`,
+          width: `${box.width}px`,
+        });
+        reveal.prepend(copy);
+        fadeOut(copy).then(() => copy.remove());
+      };
+    });
+
+    return () =>
+      h(
+        'div',
+        { ref: element, [ATTR_PANE]: '' },
+        h(Loading, { id: props.id, exact: false, label: props.label }, slots.default)
+      );
+  },
+});
+
+export const BoundaryContent = defineComponent({
+  name: 'ASmartSkeletonBoundaryContent',
+  props: { id: String, reveal: [String, Object] as PropType<RevealMode>, state },
+  emits: ['reveal'],
+  setup(props, { slots, emit }) {
+    const element = ref<HTMLElement | null>(null);
+    const config = useSmartSkeleton();
+    let memory: Memory | null = null;
+
+    onMounted(() => {
+      const pane = element.value;
+      if (!pane) return;
+      const waited = props.state.waited;
+      const arrival = fadeIn(pane, props.reveal ?? config.reveal, {
+        initial: !waited,
+      });
+      if (waited) arrival.then(() => emit('reveal'));
+
+      props.state.exit?.();
+      // eslint-disable-next-line vue/no-mutating-props
+      props.state.exit = null;
+      memory = new Memory(pane, { id: props.id });
+    });
+    onBeforeUnmount(() => memory?.destroy());
+
+    return () => h('div', { ref: element, [ATTR_PANE]: '' }, slots.default?.());
+  },
+});
+
+/**
+ * A Suspense boundary whose fallback is a measured skeleton, crossfading into the content.
+ *
+ * ```vue
+ * <ASmartSkeletonSuspense>
+ *   <LoadedQuote />
+ *   <template #skeleton><Quote :quote="SAMPLE_QUOTE" /></template>
+ * </ASmartSkeletonSuspense>
+ * ```
+ */
+export default defineComponent({
+  name: 'ASmartSkeletonSuspense',
+  props: {
+    /** Remembers the shape under this key across visits. */
+    id: String,
+    /** Read to screen readers while suspended, in place of the skeleton. */
+    label: String,
+    /** Overrides the provider's reveal for this boundary alone. */
+    reveal: [String, Object] as PropType<RevealMode>,
+  },
+  /** `reveal`: content has come in over the skeleton. */
+  emits: ['reveal'],
+  setup(props, { slots, emit }) {
+    useStyles();
+    const shared: State = { waited: false, exit: null };
+
+    return () =>
+      h('div', { [ATTR_REVEAL]: '' }, [
+        h(Suspense, null, {
+          default: () =>
+            h(
+              BoundaryContent,
+              {
+                id: props.id,
+                reveal: props.reveal,
+                state: shared,
+                onReveal: () => emit('reveal'),
+              },
+              slots.default
+            ),
+          fallback: () =>
+            h(
+              Fallback,
+              {
+                id: props.id,
+                label: props.label,
+                reveal: props.reveal,
+                state: shared,
+              },
+              slots.skeleton
+            ),
+        }),
+      ]);
+  },
+});
+</script>

package/src/composables/useSmartSkeleton.ts

@@ -0,0 +1,20 @@
+import { inject, type InjectionKey } from 'vue';
+import type { SmartSkeletonConfig } from '../types';
+
+export const SMART_SKELETON_CONFIG_KEY: InjectionKey<SmartSkeletonConfig> =
+  Symbol('a-smart-skeleton');
+
+/** Per server render: whether the full inline script has gone out yet, so the skeletons after it send a stub. */
+export const SMART_SKELETON_BOOT_KEY: InjectionKey<{ sent: boolean }> =
+  Symbol('a-smart-skeleton.boot');
+
+/** The provider settings in scope for this component. Empty outside a provider. */
+export const useSmartSkeleton = (): SmartSkeletonConfig => inject(SMART_SKELETON_CONFIG_KEY, {});
+
+/** Whether this skeleton should send the stub — claiming the full script if it's the first. */
+export function claimStub(): boolean {
+  const boot = inject(SMART_SKELETON_BOOT_KEY, null);
+  const stub = !!boot?.sent;
+  if (boot) boot.sent = true;
+  return stub;
+}

package/src/composables/useStyles.ts

@@ -0,0 +1,8 @@
+import { onBeforeMount, onUnmounted } from 'vue';
+import { addStyles, removeStyles } from '../core';
+
+/** Adds the stylesheet on mount and removes it on unmount — reference counted, so siblings share one copy. */
+export function useStyles(): void {
+  onBeforeMount(addStyles);
+  onUnmounted(removeStyles);
+}

package/src/core/boot.ts

@@ -0,0 +1,63 @@
+import { ATTR_LAYER, ATTR_GHOST, BOOT, GHOSTED, UNCOVER } from './constants';
+import { measureSkeleton } from './measure';
+import { drawSkeleton } from './shimmer';
+
+/*
+ * Inlined after a server-rendered skeleton (see build-inline.mjs). It measures in its
+ * ResizeObserver's first callback, after layout and before paint, so the first paint
+ * already shows the skeleton. It touches nothing a framework will hydrate: the skeleton
+ * lives in a shadow root. Sent once a page where a provider can tell; the skeletons after
+ * it carry a stub that calls the `boot` this leaves on window, or queues until it lands.
+ */
+
+// A path from the document root, so a painted chip's colour is hidden without an attribute hydration would see as a mismatch
+const pathOf = (element: Element): string =>
+  element.parentElement
+    ? `${pathOf(element.parentElement)} > :nth-child(${[...element.parentElement.children].indexOf(element) + 1})`
+    : ':root';
+
+type Root = HTMLElement & { [GHOSTED]?: boolean; [UNCOVER]?: () => void };
+
+function boot(script: Element | null) {
+  const root = script?.previousElementSibling as Root | null | undefined;
+  const ghost = root?.querySelector<HTMLElement>(`:scope > [${ATTR_GHOST}]`);
+  const layer = root?.querySelector<HTMLElement>(`:scope > [${ATTR_LAYER}]`);
+  if (!root || !ghost || !layer) return;
+
+  const sheet =
+    typeof CSSStyleSheet === 'function' && 'replaceSync' in CSSStyleSheet.prototype
+      ? new CSSStyleSheet()
+      : null;
+  if (sheet) {
+    document.adoptedStyleSheets = [...document.adoptedStyleSheets, sheet];
+    root[UNCOVER] = () => {
+      document.adoptedStyleSheets = document.adoptedStyleSheets.filter(
+        (adopted) => adopted !== sheet
+      );
+    };
+  }
+  const cover = (covered: Set<Element>) =>
+    sheet?.replaceSync(
+      covered.size
+        ? `${[...covered].map(pathOf).join(', ')} { visibility: hidden !important; }`
+        : ''
+    );
+
+  const draw = () => {
+    if (!layer.isConnected || root[GHOSTED]) return observer.disconnect();
+    // Streamed HTML is parsed into a hidden container first: nothing to measure until it's moved into place
+    if (!ghost.getClientRects().length) return;
+    drawSkeleton(layer, measureSkeleton(ghost, layer, { mark: false, onCovered: cover }));
+  };
+  // Measures in the first callback, after layout and before paint, then until Ghost takes over
+  const observer = new ResizeObserver(draw);
+  observer.observe(root);
+  document.fonts?.ready.then(draw);
+}
+
+const host = self as unknown as Record<symbol, unknown>;
+const key = Symbol.for(BOOT);
+const queued = host[key];
+host[key] = boot;
+if (Array.isArray(queued)) queued.forEach(boot);
+boot(document.currentScript);

package/src/core/canvas.ts

@@ -0,0 +1,7 @@
+let context: CanvasRenderingContext2D | null | undefined;
+
+// jsdom has no canvas, and logs an error for every context asked of it
+export const textContext = () =>
+  (context ??= /jsdom/.test(navigator.userAgent)
+    ? null
+    : document.createElement('canvas').getContext('2d'));

package/src/core/constants.ts

@@ -0,0 +1,76 @@
+export const ATTR_REVEAL = 'ask-reveal';
+export const ATTR_PANE = 'ask-pane';
+export const ATTR_LOADING = 'ask-loading';
+export const ATTR_GHOST = 'ask-ghost'; // The framework's render of the content, laid out but never seen
+export const ATTR_SNAPSHOT = 'ask-snapshot'; // A remembered or fallback shape, standing in for the ghost
+export const ATTR_LAYER = 'ask-layer';
+export const ATTR_RECT = 'ask-rect';
+export const ATTR_BAR = 'ask-bar';
+export const ATTR_INACTIVE = 'ask-inactive';
+export const ATTR_EXITING = 'ask-exiting'; // On a pane fading out — its skeleton holds still
+export const ATTR_COVERED = 'ask-covered'; // Drawn as one block by a bone, so its own paint is hidden
+export const ATTR_OWN = 'ask-own'; // A subtree that draws its own skeleton — measuring stops at it
+export const ATTR_IGNORE = 'ask-ignore';
+export const ATTR_BLOCK = 'ask-block';
+
+export const GHOSTED = Symbol.for('a-smart-skeleton.ghost'); // On a loading root once its Ghost runs: the inline script stands down
+export const UNCOVER = Symbol.for('a-smart-skeleton.uncover'); // On a served loading root: drops the inline script's sheet hiding covered paint, once Ghost marks it
+export const BOOT = 'a-smart-skeleton.boot'; // Symbol.for key on window: the inline script's measuring, sent once a page — later skeletons' stubs call it, or queue for it
+export const ATTR_STATUS = 'ask-status'; // Read to screen readers in place of the skeleton
+export const ATTR_XRAY = 'ask-xray'; // Debug, on any ancestor: shows the ghost through its bones
+export const ATTR_DEBUG = 'ask-debug'; // Debug outlines for this subtree alone
+
+// Themed by ASmartSkeletonProvider; the fallbacks are translucent so one grey reads on light and dark pages alike
+export const BASE = 'var(--ask-base, rgb(128 128 128 / 0.2))';
+export const HIGHLIGHT = 'var(--ask-highlight, rgb(255 255 255 / 0.12))';
+export const FADE_DURATION = 200;
+export const CASCADE_SPREAD = 320; // From the first piece of a sequenced reveal to the last
+export const RESIZE_DURATION = 280; // A reveal easing to its new height, when its skeleton guessed the content wrong
+export const IMAGE_TIMEOUT = 10000; // Longest a reveal holds for an image — a stalled request mustn't keep a skeleton up for good
+// One loop of each animation, by `speed`; a shimmer's is across a 1280px-wide screen
+export const DURATIONS = {
+  shimmer: { slow: 4000, fast: 2000 },
+  pulse: { slow: 2400, fast: 1200 },
+} as const;
+
+// Leaves that hold text, so an empty one still stands for a line of it
+export const TEXT_TAGS = [
+  'a',
+  'b',
+  'code',
+  'dd',
+  'dt',
+  'em',
+  'h1',
+  'h2',
+  'h3',
+  'h4',
+  'h5',
+  'h6',
+  'i',
+  'label',
+  'li',
+  'p',
+  'small',
+  'span',
+  'strong',
+  'td',
+  'th',
+  'time',
+];
+
+// Drawn as one block at their box — there is no text inside to measure
+export const MEDIA_TAGS = [
+  'audio',
+  'canvas',
+  'embed',
+  'iframe',
+  'img',
+  'input',
+  'object',
+  'picture',
+  'select',
+  'svg',
+  'textarea',
+  'video',
+];

package/src/core/debug.ts

@@ -0,0 +1,154 @@
+import { ATTR_DEBUG, ATTR_XRAY } from './constants';
+
+type Entry = {
+  state: 'loading' | 'shown';
+  source?: string;
+  moved?: { width: number; height: number };
+};
+
+const entries = new Map<Element, Entry>();
+let enabled: boolean | undefined;
+let host: HTMLElement | null = null;
+let frame = 0;
+
+function fromPage() {
+  try {
+    return (
+      new URLSearchParams(location.search).has('ask-debug') ||
+      localStorage.getItem('a-smart-skeleton:debug') === '1'
+    );
+  } catch {
+    return false;
+  }
+}
+
+const everywhere = () => (enabled ??= typeof window !== 'undefined' && fromPage());
+
+/** On with `?ask-debug`, `a-smart-skeleton:debug` = "1" in localStorage or `setDebug(true)`; for `element`, also inside `[ask-debug]`. */
+export const debugging = (element?: Element | null) =>
+  everywhere() || !!element?.closest(`[${ATTR_DEBUG}]`);
+
+export function setDebug(on: boolean) {
+  enabled = on;
+  if (on) start();
+  else stop();
+}
+
+export function reportLoading(reveal: Element | null, source: string) {
+  if (!reveal || !debugging(reveal)) return;
+  entries.set(reveal, { state: 'loading', source });
+  show();
+}
+
+export function reportReveal(reveal: Element | null, moved: { width: number; height: number }) {
+  if (!reveal || !debugging(reveal)) return;
+  entries.set(reveal, { ...entries.get(reveal), state: 'shown', moved });
+  show();
+}
+
+// Drawn at once, not on the next frame: a throttled page, like a test's iframe, may wait long for one
+function show() {
+  start();
+  cancelAnimationFrame(frame);
+  draw();
+}
+
+const PANEL_CSS = `
+:host { all: initial; }
+.box { position: fixed; box-sizing: border-box; border: 1px dashed; border-radius: 4px; }
+.label {
+  position: absolute; left: -1px; bottom: 100%; margin-bottom: 2px;
+  padding: 1px 6px; border-radius: 4px; white-space: nowrap;
+  font: 500 11px/16px ui-monospace, SFMono-Regular, Menlo, monospace; color: #fff;
+}
+.loading { border-color: #3b82f6; } .loading .label { background: #3b82f6; }
+.still { border-color: #22c55e; } .still .label { background: #16a34a; }
+.moved { border-color: #ef4444; border-style: solid; } .moved .label { background: #dc2626; }
+.panel {
+  position: fixed; right: 12px; bottom: 12px; display: flex; gap: 8px; align-items: center;
+  padding: 6px 10px; border-radius: 8px; background: #111; color: #fff; pointer-events: auto;
+  font: 500 12px/16px ui-sans-serif, system-ui, sans-serif; box-shadow: 0 4px 16px rgb(0 0 0 / 0.3);
+}
+.panel label { display: flex; gap: 4px; align-items: center; cursor: pointer; }
+`;
+
+function start() {
+  if (typeof document === 'undefined') return;
+  if (!host?.isConnected) {
+    host = document.createElement('div');
+    host.style.cssText = 'position:fixed;inset:0;pointer-events:none;z-index:2147483647';
+    const shadow = host.attachShadow({ mode: 'open' });
+    shadow.innerHTML = `<style>${PANEL_CSS}</style><div class="boxes"></div>`;
+    document.body.append(host);
+  }
+  // The panel, and its x-ray toggle, are for the whole page only
+  const shadow = host.shadowRoot!;
+  if (enabled && !shadow.querySelector('.panel')) {
+    const panel = document.createElement('div');
+    panel.className = 'panel';
+    panel.innerHTML = `a-smart-skeleton debug <label><input type="checkbox" class="xray"> x-ray</label>`;
+    panel.querySelector('.xray')!.addEventListener('change', (event) => {
+      document.documentElement.toggleAttribute(
+        ATTR_XRAY,
+        (event.target as HTMLInputElement).checked
+      );
+    });
+    shadow.append(panel);
+  }
+  if (!frame) frame = requestAnimationFrame(draw);
+}
+
+function stop() {
+  host?.shadowRoot?.querySelector('.panel')?.remove();
+  document.documentElement.removeAttribute(ATTR_XRAY);
+  if ([...entries.keys()].some((reveal) => debugging(reveal))) return;
+  cancelAnimationFrame(frame);
+  frame = 0;
+  host?.remove();
+  host = null;
+}
+
+const describe = ({ state, source, moved }: Entry) => {
+  const from = source ? ` · ${source}` : '';
+  if (state === 'loading') return { kind: 'loading', text: `skeleton${from}` };
+  if (!moved || (moved.width === 0 && moved.height === 0)) {
+    return { kind: 'still', text: `✓ no movement${from}` };
+  }
+  return {
+    kind: 'moved',
+    text: `✗ moved ${moved.width}×${moved.height}px${from}`,
+  };
+};
+
+// Follows every tracked reveal each frame, so scrolling and layout never leave a box behind
+function draw() {
+  frame = 0;
+  if (!host?.shadowRoot) return;
+  const boxes = host.shadowRoot.querySelector('.boxes')!;
+
+  for (const reveal of entries.keys()) {
+    if (!reveal.isConnected || !debugging(reveal)) entries.delete(reveal);
+  }
+
+  const items = [...entries];
+  while (boxes.children.length > items.length) boxes.lastElementChild!.remove();
+  items.forEach(([reveal, entry], index) => {
+    let box = boxes.children[index] as HTMLElement | undefined;
+    if (!box) {
+      box = boxes.appendChild(document.createElement('div'));
+      box.innerHTML = `<span class="label"></span>`;
+    }
+    const rect = reveal.getBoundingClientRect();
+    const { kind, text } = describe(entry);
+    box.className = `box ${kind}`;
+    Object.assign(box.style, {
+      left: `${rect.left - 2}px`,
+      top: `${rect.top - 2}px`,
+      width: `${rect.width + 4}px`,
+      height: `${rect.height + 4}px`,
+    });
+    box.firstElementChild!.textContent = text;
+  });
+
+  if (enabled || entries.size) frame = requestAnimationFrame(draw);
+}

package/src/core/dev.ts

@@ -0,0 +1,53 @@
+import { fill } from './snapshot';
+
+declare const process: { env: { NODE_ENV?: string } };
+
+let dev = false;
+try {
+  // Bundlers replace the whole expression; with none, `process` doesn't exist
+  dev = process.env.NODE_ENV !== 'production';
+} catch {
+  dev = false;
+}
+
+export const isDev = dev;
+
+const warned = new Set<string>();
+
+export function warnOnce(id: string, message: string) {
+  if (!isDev || warned.has(id)) return;
+  warned.add(id);
+  // eslint-disable-next-line no-console
+  console.warn(`[a-smart-skeleton] ${message}`);
+}
+
+const URL_LIKE = /^(https?:|\/|data:|blob:)/;
+
+/**
+ * Warns once per app if the page has a meta CSP that restricts inline scripts and
+ * the consumer did not pass a nonce through the provider. Silent when CSP is absent
+ * or when the loading pane isn't on the client yet — we can't read CSP headers from
+ * script, so the meta-tag check is a best-effort signal to developers.
+ */
+export function checkNonce(nonce: string | undefined): void {
+  if (!isDev || typeof document === 'undefined' || nonce) return;
+  const meta = document.querySelector('meta[http-equiv="Content-Security-Policy" i]');
+  const content = meta?.getAttribute('content') ?? '';
+  if (!/script-src/i.test(content)) return;
+  if (/'unsafe-inline'/.test(content) || /\*/.test(content)) return;
+  warnOnce(
+    'csp:missing-nonce',
+    'ASmartSkeleton ships an inline boot script that measures the server-rendered skeleton before first paint. Your page has a Content-Security-Policy with script-src but no nonce was passed to <ASmartSkeletonProvider :nonce="…">, so the browser will block it and first paint will be blank. Pass the same nonce you used for the response header.'
+  );
+}
+
+/** Same keys and lengths as `data`, with every string replaced by filler. */
+export function sampleFrom(data: unknown): unknown {
+  if (typeof data === 'string') return URL_LIKE.test(data) ? '' : fill(data);
+  if (Array.isArray(data)) return data.map(sampleFrom);
+  if (data instanceof Date) return data;
+  if (data && typeof data === 'object') {
+    return Object.fromEntries(Object.entries(data).map(([key, value]) => [key, sampleFrom(value)]));
+  }
+  return data;
+}