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

package/src/resolver/index.ts

@@ -0,0 +1,35 @@
+import type { ComponentResolver } from 'unplugin-vue-components';
+
+/**
+ * `@alikhalilll/a-smart-skeleton/resolver` — auto-import resolver for non-Nuxt
+ * Vite / Webpack consumers via `unplugin-vue-components`.
+ *
+ *   import Components from 'unplugin-vue-components/vite';
+ *   import ASmartSkeletonResolver from '@alikhalilll/a-smart-skeleton/resolver';
+ *   export default { plugins: [Components({ resolvers: [ASmartSkeletonResolver()] })] };
+ */
+
+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> = {
+  ASmartSkeleton: '@alikhalilll/a-smart-skeleton',
+  ASmartSkeletonBox: '@alikhalilll/a-smart-skeleton',
+  ASmartSkeletonSuspense: '@alikhalilll/a-smart-skeleton',
+  ASmartSkeletonProvider: '@alikhalilll/a-smart-skeleton',
+};
+
+export default function ASmartSkeletonResolver(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,100 @@
+import type { VNodeChild } from 'vue';
+import type {
+  RevealMode,
+  SkeletonBoxOptions,
+  SkeletonMode,
+  SkeletonText,
+  SkeletonTheme,
+} from './core';
+
+export interface ASmartSkeletonBoxProps extends SkeletonBoxOptions {
+  class?: string;
+  style?: Record<string, string | number>;
+}
+
+/**
+ * Slots: `default` (with `{ data }` when `data` is bound), `skeleton`, `empty`,
+ * `error` (with `{ error }`).
+ */
+export interface ASmartSkeletonProps<T = unknown> {
+  /** Shows the skeleton, even over `data`. With `data`, it also shows while there is none. */
+  loading?: boolean;
+  /** Loading while `null` or `undefined`; handed to the default slot as `{ data }`. */
+  data?: T | null;
+  /** Stands in for `data` to draw the skeleton before any has loaded. */
+  sample?: T;
+  /** Remembers the shape under this key across visits. */
+  id?: string;
+  /** Read to screen readers while loading, in place of the skeleton — "Loading profile". */
+  label?: string;
+  /** Renders the `empty` slot instead of the content. */
+  empty?: boolean;
+  /** When set, renders the `error` slot with `{ error }` instead of the content. */
+  error?: unknown;
+  /** Overrides the provider's reveal for this skeleton alone. */
+  reveal?: RevealMode;
+  /** Called once content has come in over a skeleton; `@reveal` in a template. */
+  onReveal?: () => void;
+  class?: string;
+  style?: Record<string, string | number>;
+}
+
+export interface ASmartSkeletonSlots<T = unknown> {
+  /** The content. Receives `{ data }` when `data` is bound. */
+  default?: (props: { data: T }) => VNodeChild;
+  /** Shown while loading instead of the measured skeleton. */
+  skeleton?: () => VNodeChild;
+  /** Shown when `empty` is set. Falls back to the content. */
+  empty?: () => VNodeChild;
+  /** Shown when `error` is set. Receives `{ error }`. */
+  error?: (props: { error: unknown }) => VNodeChild;
+}
+
+export interface ASmartSkeletonEmits {
+  /** Content has come in over a skeleton. */
+  reveal: () => void;
+}
+
+/** Slots: `default`, the content that suspends; `skeleton`, the content rendered from sample data. */
+export interface ASmartSkeletonSuspenseProps {
+  /** 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?: RevealMode;
+  /** Called once content has come in over the skeleton; `@reveal` in a template. */
+  onReveal?: () => void;
+}
+
+export interface ASmartSkeletonSuspenseSlots {
+  default?: () => VNodeChild;
+  skeleton?: () => VNodeChild;
+}
+
+export interface ASmartSkeletonSuspenseEmits {
+  /** Content has come in over the skeleton. */
+  reveal: () => void;
+}
+
+/** Settings for every skeleton inside. Per request on the server, as a nonce must be. */
+export interface ASmartSkeletonProviderProps {
+  /** Set on the inline script and stylesheets rendered, for a Content Security Policy. */
+  nonce?: string;
+  /** Colours for light and dark; `mode` picks between them. */
+  theme?: SkeletonTheme;
+  /** `system` follows `prefers-color-scheme`; the others pin one set of colours. */
+  mode?: SkeletonMode;
+  /** Where text bars run: from `top` (ascender, cap-height, x-height) down to `bottom` (baseline, descender). */
+  text?: SkeletonText;
+  /** How content replaces its skeleton: `smart` (the default), `together`, `sequence`, `sweep`, or a `RevealSpec` of your own. */
+  reveal?: RevealMode;
+  /** Outlines every reveal with where its skeleton came from and whether anything moved. */
+  debug?: boolean;
+}
+
+export interface ASmartSkeletonProviderSlots {
+  default?: () => VNodeChild;
+}
+
+export type SmartSkeletonConfig = ASmartSkeletonProviderProps;

package/src/vue/Skeleton.ts

@@ -0,0 +1,275 @@
+import {
+  defineComponent,
+  getCurrentInstance,
+  h,
+  onBeforeMount,
+  onBeforeUnmount,
+  onMounted,
+  onUnmounted,
+  ref,
+  Transition,
+  watch,
+  type PropType,
+  type VNodeChild,
+} from 'vue';
+import {
+  addStyles,
+  ATTR_BAR,
+  ATTR_GHOST,
+  ATTR_LAYER,
+  ATTR_LOADING,
+  ATTR_OWN,
+  ATTR_PANE,
+  ATTR_REVEAL,
+  ATTR_SNAPSHOT,
+  ATTR_STATUS,
+  checkNonce,
+  fadeIn,
+  fadeOut,
+  Ghost,
+  INLINE_SCRIPT,
+  INLINE_STUB,
+  Memory,
+  removeStyles,
+  shimmer,
+  skeletonBoxStyle,
+  type MemoryOptions,
+  type RevealMode,
+} from '../core';
+import { claimStub, useSmartSkeleton } from './config';
+
+const length = [String, Number] as PropType<string | number>;
+
+/** Adds the stylesheet on mount and removes it on unmount — reference counted, so siblings share one copy. */
+export function useStyles() {
+  onBeforeMount(addStyles);
+  onUnmounted(removeStyles);
+}
+
+/**
+ * One shimmering bar. Numbers are read as pixels.
+ *
+ * ```vue
+ * <ASmartSkeletonBox width="60%" height="1em" radius="0.25em" />
+ * ```
+ */
+export const ASmartSkeletonBox = defineComponent({
+  name: 'ASmartSkeletonBox',
+  props: {
+    height: length,
+    width: length,
+    radius: length,
+  },
+  setup(props) {
+    const element = ref<HTMLElement | null>(null);
+    useStyles();
+    onMounted(() => {
+      if (element.value) shimmer(element.value);
+    });
+    return () =>
+      h('span', {
+        ref: element,
+        [ATTR_BAR]: '',
+        style: skeletonBoxStyle(props),
+      });
+  },
+});
+
+/**
+ * The measured loading pane. Internal — `<ASmartSkeleton>` renders it.
+ *
+ * The ghost is laid out but never seen; the layer holds bones in a shadow root,
+ * so hydration never touches what was measured.
+ */
+export const Loading = defineComponent({
+  name: 'ASmartSkeletonLoading',
+  props: {
+    id: String,
+    exact: Boolean,
+    refetch: Boolean,
+    label: String,
+  },
+  setup(props, { slots }) {
+    const element = ref<HTMLElement | null>(null);
+    const config = useSmartSkeleton();
+    const script = claimStub() ? INLINE_STUB : INLINE_SCRIPT;
+    let ghost: Ghost | null = null;
+
+    const optionsOf = () => ({ id: props.id, exact: props.exact, refetch: props.refetch });
+    onMounted(() => {
+      checkNonce(config.nonce);
+      if (element.value) ghost = new Ghost(element.value, optionsOf());
+    });
+    // Options-only changes update the live ghost in place; the observers and shadow sheet
+    // outlive a prop flip, which happens every data arrival in data-driven mode.
+    watch(
+      () => [props.id, props.exact, props.refetch],
+      () => ghost?.update(optionsOf())
+    );
+    onBeforeUnmount(() => ghost?.destroy());
+
+    // Snapshot and bones are Ghost's to fill, never Vue's.
+    return () => [
+      props.label ? h('span', { [ATTR_STATUS]: '' }, props.label) : null,
+      h(
+        'div',
+        {
+          ref: element,
+          [ATTR_LOADING]: '',
+          'aria-hidden': 'true',
+          inert: '',
+        },
+        [
+          h('div', { [ATTR_GHOST]: '' }, slots.default?.()),
+          h('div', { [ATTR_SNAPSHOT]: '' }),
+          h('div', { [ATTR_LAYER]: '' }),
+        ]
+      ),
+      h('script', { nonce: config.nonce, innerHTML: script }),
+    ];
+  },
+});
+
+const Content = defineComponent({
+  name: 'ASmartSkeletonContent',
+  props: {
+    memory: { type: Object as PropType<MemoryOptions>, required: true },
+  },
+  setup(props, { slots }) {
+    const element = ref<HTMLElement | null>(null);
+    let memory: Memory | null = null;
+
+    onMounted(() => {
+      if (element.value) memory = new Memory(element.value, props.memory);
+    });
+    onBeforeUnmount(() => memory?.destroy());
+
+    return () => h('div', { ref: element }, slots.default?.());
+  },
+});
+
+/**
+ * Shows a skeleton measured from the content it wraps, then reveals the content.
+ *
+ * ```vue
+ * <ASmartSkeleton :data="user" :sample="SAMPLE_USER">
+ *   <template #default="{ data }">
+ *     <UserCard :user="data" />
+ *   </template>
+ * </ASmartSkeleton>
+ * ```
+ */
+export const ASmartSkeleton = defineComponent({
+  name: 'ASmartSkeleton',
+  props: {
+    /** Shows the skeleton, even over `data`. With `data`, it also shows while there is none. */
+    loading: { type: Boolean, default: undefined },
+    /** Loading while `null` or `undefined`; handed to the default slot as `{ data }`. */
+    data: { type: null as unknown as PropType<unknown>, required: false },
+    /** Stands in for `data` to draw the skeleton before any has loaded. */
+    sample: { type: null as unknown as PropType<unknown>, required: false },
+    /** Remembers the shape under this key across visits. */
+    id: String,
+    /** Read to screen readers while loading, in place of the skeleton — "Loading profile". */
+    label: String,
+    empty: Boolean,
+    error: { type: null as unknown as PropType<unknown>, required: false },
+    /** Overrides the provider's reveal for this skeleton alone. */
+    reveal: [String, Object] as PropType<RevealMode>,
+  },
+  /** `reveal`: content has come in over a skeleton. */
+  emits: ['reveal'],
+  setup(props, { slots, emit }) {
+    const instance = getCurrentInstance();
+    const config = useSmartSkeleton();
+    // The last data shown, so a reload's skeleton has its exact shape — of the same `id` only.
+    let last: { id?: string; data: unknown } | null = null;
+    // The pane on screen and the one before it, so content knows whether it replaced a skeleton.
+    let shown: string | null = null;
+    let from: string | null = null;
+    useStyles();
+
+    return () => {
+      // Data-driven when `data` is bound at all, even to null.
+      const driven = !!instance?.vnode.props && 'data' in instance.vnode.props;
+      const data = props.data;
+      if (data != null) last = { id: props.id, data };
+
+      const show = (value: unknown): VNodeChild =>
+        driven
+          ? value != null
+            ? slots.default?.({ data: value })
+            : null
+          : slots.default?.({ data: undefined });
+
+      // A slot fed data has nothing to render without it, so that's a skeleton too.
+      const loading = !!props.loading || (driven && data == null && !props.error && !props.empty);
+
+      let key: string;
+      let content: VNodeChild;
+      if (loading) {
+        const previous = last as { id?: string; data: unknown } | null;
+        const real = data ?? (previous && previous.id === props.id ? previous.data : null);
+        key = 'skeleton';
+        content = slots.skeleton
+          ? // Marked as drawing its own skeleton, so the reveal treats it as one.
+            h('div', { [ATTR_OWN]: '', 'aria-hidden': 'true' }, slots.skeleton())
+          : h(
+              Loading,
+              {
+                id: props.id,
+                exact: real != null,
+                refetch: data != null,
+                label: props.label,
+              },
+              () => show(real ?? props.sample)
+            );
+      } else if (props.error) {
+        key = 'error';
+        content = slots.error?.({ error: props.error });
+      } else if (props.empty) {
+        key = 'empty';
+        content = slots.empty?.() ?? show(data);
+      } else {
+        key = 'content';
+        content = h(
+          Content,
+          {
+            memory: {
+              id: props.id,
+              data,
+              rendered: driven,
+              sample: props.sample !== undefined,
+            },
+          },
+          () => show(data)
+        );
+      }
+
+      if (key !== shown) {
+        from = shown;
+        shown = key;
+      }
+      const revealing = key === 'content' && from === 'skeleton';
+
+      const reveal = props.reveal ?? config.reveal;
+      return h('div', { [ATTR_REVEAL]: '', 'aria-busy': loading || undefined }, [
+        h(
+          Transition,
+          {
+            css: false,
+            appear: true,
+            onAppear: (el, done) => fadeIn(el as HTMLElement, reveal, { initial: true }).then(done),
+            onEnter: (el, done) =>
+              fadeIn(el as HTMLElement, reveal).then(() => {
+                done();
+                if (revealing) emit('reveal');
+              }),
+            onLeave: (el, done) => fadeOut(el as HTMLElement).then(done),
+          },
+          () => h('div', { key, [ATTR_PANE]: '' }, [content])
+        ),
+      ]);
+    };
+  },
+});

package/src/vue/Suspense.ts

@@ -0,0 +1,157 @@
+import { defineComponent, h, onBeforeUnmount, onMounted, ref, Suspense, type PropType } from 'vue';
+import {
+  ATTR_LOADING,
+  ATTR_PANE,
+  ATTR_REVEAL,
+  boxOf,
+  fadeIn,
+  fadeOut,
+  Ghost,
+  Memory,
+  type RevealMode,
+} from '../core';
+import { useSmartSkeleton } from './config';
+import { Loading, useStyles } from './Skeleton';
+
+type State = { waited: boolean; exit: (() => void) | null };
+const state = { type: Object as PropType<State>, required: true } as const;
+
+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 -- intentional shared-state coordination */
+      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');
+
+      // Measured now, alone in flow; the copy fades out once the content has decided how it arrives.
+      const box = boxOf(pane);
+      const copy = pane.cloneNode(true) as HTMLElement;
+      /* eslint-disable-next-line vue/no-mutating-props -- intentional shared-state coordination */
+      props.state.exit = () => {
+        Object.assign(copy.style, {
+          position: 'absolute',
+          top: `${box.top}px`,
+          left: `${box.left}px`,
+          width: `${box.width}px`,
+        });
+        reveal.prepend(copy);
+
+        // A clone leaves its skeleton's shadow root behind; draw it again.
+        const loading = copy.querySelector<HTMLElement>(`[${ATTR_LOADING}]`);
+        if (loading) new Ghost(loading, { id: props.id, exact: true }).destroy();
+        fadeOut(copy, box).then(() => copy.remove());
+      };
+    });
+
+    // A skeleton given is what the content will be — drawn as given, not swapped for a remembered shape.
+    return () =>
+      h('div', { ref: element, [ATTR_PANE]: '' }, [
+        h(Loading, { id: props.id, exact: !!slots.default, label: props.label }, slots.default),
+      ]);
+  },
+});
+
+const Content = defineComponent({
+  name: 'ASmartSkeletonSuspenseContent',
+  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;
+      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 -- intentional shared-state coordination */
+      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 const ASmartSkeletonSuspense = 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(
+              Content,
+              {
+                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
+            ),
+        }),
+      ]);
+  },
+});

package/src/vue/config.ts

@@ -0,0 +1,78 @@
+import { defineComponent, h, inject, provide, watch, type InjectionKey, type PropType } from 'vue';
+import {
+  setDebug,
+  skeletonCSS,
+  type RevealMode,
+  type SkeletonMode,
+  type SkeletonText,
+  type SkeletonTheme,
+} from '../core';
+
+export type SmartSkeletonConfig = {
+  /** Set on the inline script and stylesheets rendered, for a Content Security Policy. */
+  nonce?: string;
+  /** Colours for light and dark; `mode` picks between them. */
+  theme?: SkeletonTheme;
+  mode?: SkeletonMode;
+  /** Where text bars run: from `top` (ascender, cap-height, x-height) down to `bottom` (baseline, descender). */
+  text?: SkeletonText;
+  /** How content replaces its skeleton: `smart` (the default), `together`, `sequence`, `sweep`, or a `RevealSpec` of your own. */
+  reveal?: RevealMode;
+  /** Outlines every reveal with where its skeleton came from and whether anything moved. */
+  debug?: boolean;
+};
+
+const 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. */
+const bootKey: 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(key, {});
+
+/** Whether this skeleton should send the stub — claiming the full script if it's the first. */
+export function claimStub() {
+  const boot = inject(bootKey, null);
+  const stub = !!boot?.sent;
+  if (boot) boot.sent = true;
+  return stub;
+}
+
+/**
+ * Settings for every skeleton inside — per request on the server, as a nonce must be.
+ *
+ * ```vue
+ * <ASmartSkeletonProvider :theme="theme" reveal="smart" :nonce="nonce">
+ *   <App />
+ * </ASmartSkeletonProvider>
+ * ```
+ */
+export const ASmartSkeletonProvider = defineComponent({
+  name: 'ASmartSkeletonProvider',
+  props: {
+    nonce: String,
+    theme: Object as PropType<SkeletonTheme>,
+    mode: String as PropType<SkeletonMode>,
+    text: Object as PropType<SkeletonText>,
+    reveal: [String, Object] as PropType<RevealMode>,
+    debug: { type: Boolean, default: undefined },
+  },
+  setup(props, { slots }) {
+    // The props object itself, so components inside read every change.
+    provide(key, props);
+    provide(bootKey, { sent: false });
+
+    watch(
+      () => props.debug,
+      (debug) => {
+        if (debug !== undefined && typeof window !== 'undefined') setDebug(debug);
+      },
+      { immediate: true }
+    );
+
+    return () => {
+      const css = skeletonCSS(props);
+      return [css ? h('style', { nonce: props.nonce }, css) : null, slots.default?.()];
+    };
+  },
+});

package/src/vue/index.ts

@@ -0,0 +1,7 @@
+export { default as ASmartSkeleton } from '../components/ASmartSkeleton.vue';
+export { default as ASmartSkeletonBox } from '../components/ASmartSkeletonBox.vue';
+export { default as ASmartSkeletonSuspense } from '../components/ASmartSkeletonSuspense.vue';
+export { default as ASmartSkeletonProvider } from '../components/ASmartSkeletonProvider.vue';
+export { useSmartSkeleton, claimStub } from '../composables/useSmartSkeleton';
+export { useStyles } from '../composables/useStyles';
+export type { SmartSkeletonConfig } from '../types';