@alikhalilll/a-smart-skeleton 1.0.0 → 2.0.0

package/src/core/measure.ts

@@ -8,13 +8,30 @@ import {
   TEXT_TAGS,
 } from './constants';
 
+/** Captured paint from a container — background / borders / box-shadow — reproduced on
+ *  the chrome bone so the outline survives shape recall from storage, SSR pre-paint, and
+ *  any path where the real DOM isn't visible under the layer. */
+export type SkeletonChrome = {
+  background?: string;
+  borderTop?: string;
+  borderRight?: string;
+  borderBottom?: string;
+  borderLeft?: string;
+  boxShadow?: string;
+};
+
 /** A box to draw, relative to the layer it was measured against. */
 export type SkeletonRect = {
+  /** Which kind of leaf this bone stands in for — exposed as `[ask-rect="<type>"]` so
+   *  consumers can style text / media / box / chrome bones differently in their own CSS. */
+  type: 'text' | 'media' | 'box' | 'chrome';
   x: number;
   y: number;
   width: number;
   height: number;
   radius: string;
+  /** Present on `type === 'chrome'` bones — the container's own paint, captured verbatim from `getComputedStyle`. */
+  chrome?: SkeletonChrome;
 };
 
 type Rect = { left: number; right: number; top: number; bottom: number };
@@ -213,6 +230,17 @@ const bordered = (style: CSSStyleDeclaration) =>
       isSet(style[`border${side}Style`], 'none') && isSet(style[`border${side}Width`], '0px')
   );
 
+// Dividers (`border-t` on a footer, `border-b` on a heading) still need to show
+// up in the skeleton, even though they don't make the container a solid block.
+// This looser check feeds chrome capture; `bordered` above remains what
+// `isPainted` reads so single-side borders keep their "divider" semantics for
+// the isBlock classifier.
+const anyBordered = (style: CSSStyleDeclaration) =>
+  SIDES.some(
+    (side) =>
+      isSet(style[`border${side}Style`], 'none') && isSet(style[`border${side}Width`], '0px')
+  );
+
 // An inset hairline along one side, drawn as a shadow, is a divider like a one-sided border
 const isRule = (shadow: string) => {
   const [x = 0, y = 0, blur = 0, spread = 0] = (
@@ -226,12 +254,71 @@ const isRule = (shadow: string) => {
 const shadowPaints = (boxShadow: string) =>
   isSet(boxShadow, 'none') && !boxShadow.split(/,(?![^(]*\))/).every(isRule);
 
+/** Splits `background-image` on its top-level commas (respecting nested parens, which
+ *  gradient stops abuse heavily) and drops any layer that starts with `url(`. Returns
+ *  an empty string when nothing survives — the caller treats that as "no background". */
+function stripUrlLayers(bgImage: string): string {
+  const layers: string[] = [];
+  let depth = 0;
+  let start = 0;
+  for (let i = 0; i < bgImage.length; i++) {
+    const ch = bgImage[i];
+    if (ch === '(') depth++;
+    else if (ch === ')') depth--;
+    else if (ch === ',' && depth === 0) {
+      layers.push(bgImage.slice(start, i));
+      start = i + 1;
+    }
+  }
+  layers.push(bgImage.slice(start));
+  return layers
+    .map((l) => l.trim())
+    .filter((l) => l && !l.startsWith('url('))
+    .join(', ');
+}
+
 const isPainted = (style: CSSStyleDeclaration) =>
   (isSet(style.backgroundColor, 'transparent') && !TRANSPARENT.test(style.backgroundColor)) ||
   isSet(style.backgroundImage, 'none') ||
   shadowPaints(style.boxShadow) ||
   bordered(style);
 
+/** Reads the painted chrome off a container so the skeleton can reproduce it exactly —
+ *  background, four border sides, and box-shadow, but only the properties that are set.
+ *  Returns `undefined` when nothing paints, so callers can skip emitting a chrome bone. */
+function captureChrome(style: CSSStyleDeclaration): SkeletonChrome | undefined {
+  const chrome: SkeletonChrome = {};
+
+  const bg = style.backgroundColor;
+  if (isSet(bg, 'transparent') && !TRANSPARENT.test(bg)) chrome.background = bg;
+  // Keep gradient layers (Tailwind ring utilities, shadcn chrome, etc.) but drop
+  // `url(...)` layers — a hero bitmap re-downloaded into the skeleton is wasteful
+  // and almost always wrong.
+  const bgImage = style.backgroundImage;
+  if (isSet(bgImage, 'none')) {
+    const gradientsOnly = stripUrlLayers(bgImage);
+    if (gradientsOnly) {
+      chrome.background = chrome.background
+        ? `${gradientsOnly}, ${chrome.background}`
+        : gradientsOnly;
+    }
+  }
+
+  for (const side of SIDES) {
+    const width = style[`border${side}Width`];
+    const styleProp = style[`border${side}Style`];
+    const color = style[`border${side}Color`];
+    if (isSet(styleProp, 'none') && isSet(width, '0px') && parseFloat(width) > 0) {
+      const key = `border${side}` as 'borderTop' | 'borderRight' | 'borderBottom' | 'borderLeft';
+      chrome[key] = `${width} ${styleProp} ${color}`;
+    }
+  }
+
+  if (shadowPaints(style.boxShadow)) chrome.boxShadow = style.boxShadow;
+
+  return Object.keys(chrome).length ? chrome : undefined;
+}
+
 const isMedia = (element: Element) => MEDIA.has(element.localName);
 
 const isEmptyText = (element: Element) =>
@@ -330,6 +417,7 @@ function toBars(lines: Line[]): SkeletonRect[] {
   return merged.map((line) => {
     const height = line.barBottom - line.barTop;
     return {
+      type: 'text' as const,
       x: line.left,
       y: line.barTop,
       width: line.right - line.left,
@@ -412,6 +500,7 @@ export function measureSkeleton(
         if (visible) {
           const box = local(visible);
           blocks.push({
+            type: isMedia(element) ? 'media' : 'box',
             x: box.left,
             y: box.top,
             width: box.right - box.left,
@@ -430,6 +519,34 @@ export function measureSkeleton(
         continue;
       }
 
+      // A painted container (a card, a chip) doesn't become a solid block — it still
+      // has interior bones to measure — but its own paint (bg / border / radius / shadow)
+      // is captured as a `chrome` bone so the outline survives shape recall and SSR
+      // pre-paint, when the real DOM isn't painted under the layer yet. Emitted BEFORE
+      // the recursion so it draws underneath the interior bones in document order.
+      //
+      // Single-side borders (`border-t` on a footer divider) deliberately fail
+      // `isPainted` — they're dividers, not chip paint — but they still need to
+      // appear in the skeleton, so `anyBordered` widens the capture trigger.
+      if (isPainted(style) || anyBordered(style)) {
+        const chrome = captureChrome(style);
+        if (chrome) {
+          const visible = clipped(element.getBoundingClientRect(), clip);
+          if (visible) {
+            const box = local(visible);
+            blocks.push({
+              type: 'chrome',
+              x: box.left,
+              y: box.top,
+              width: box.right - box.left,
+              height: box.bottom - box.top,
+              radius: roundedBy(clip, visible, radiusOf(element, style), style),
+              chrome,
+            });
+          }
+        }
+      }
+
       const clips = style.overflowX !== 'visible' || style.overflowY !== 'visible';
       visit(element, clips ? clipWithin(clip, element.getBoundingClientRect(), style) : clip);
     }

package/src/core/plan.ts

@@ -56,7 +56,7 @@ export type RevealSpec = {
 };
 
 /** A built-in reveal by name, or one of your own. */
-export type RevealMode = 'together' | 'sequence' | 'smart' | 'sweep' | RevealSpec;
+export type RevealMode = 'together' | 'sequence' | 'smart' | 'sweep' | 'instant' | RevealSpec;
 
 export const SKELETON_DELAY = 150; // A skeleton up for less than this is a flash — smart holds it back
 const QUICK_FADE = 120; // A refetch, already familiar

package/src/core/reveals.ts

@@ -1,5 +1,6 @@
 import { CASCADE_SPREAD, FADE_DURATION } from './constants';
 import {
+  instant,
   MAX_DELAY,
   MAX_DURATION,
   sequence,
@@ -10,10 +11,18 @@ import {
 } from './plan';
 import { sweep, SWEEP_SPREAD } from './sweep';
 
-const NAMED = { together, sequence, smart, sweep };
+// `instant` is advertised as a string mode in the README and is exported as a
+// `RevealSpec`, but was previously missing from this map, so passing
+// `reveal="instant"` returned `undefined` and crashed `arrive()` with
+// "Cannot read properties of undefined (reading 'hold')".
+const NAMED = { together, sequence, smart, sweep, instant };
 
-export const revealSpec = (mode: RevealMode = 'smart'): RevealSpec =>
-  typeof mode === 'string' ? NAMED[mode] : mode;
+// Unknown strings fall back to `smart` instead of crashing — a stale template
+// or a typo should quietly do the right thing, not blow up the reveal.
+export const revealSpec = (mode: RevealMode = 'smart'): RevealSpec => {
+  if (typeof mode !== 'string') return mode;
+  return (NAMED as Record<string, RevealSpec>)[mode] ?? smart;
+};
 
 /** Longest a pane can take to leave under `mode`, for a framework that has to know up front. */
 export function exitDuration(mode?: RevealMode) {

package/src/core/shimmer.ts

@@ -1,4 +1,4 @@
-import { ATTR_RECT, BASE, DURATIONS, HIGHLIGHT } from './constants';
+import { ATTR_RECT, DURATIONS, HIGHLIGHT } from './constants';
 import type { SkeletonAnimation, SkeletonSpeed } from './theme';
 import { animationsOf, prefersReducedMotion } from './motion';
 import type { SkeletonRect } from './measure';
@@ -123,16 +123,35 @@ export function paceOf(element: Element): number | null {
   return (motion.duration * SWEEP) / (REFERENCE_WIDTH + MAX_BAND);
 }
 
-// In a shadow root, so a framework hydrating `layer` never meets bones it didn't render
-const shadow = (layer: HTMLElement) => layer.shadowRoot ?? layer.attachShadow({ mode: 'open' });
-
 /** The rect elements drawn into `layer`. */
-export const rectsOf = (layer: Element): HTMLElement[] =>
-  layer.shadowRoot ? ([...layer.shadowRoot.children] as HTMLElement[]) : [];
+export const rectsOf = (layer: Element): HTMLElement[] => [
+  ...layer.querySelectorAll<HTMLElement>(`:scope > [${ATTR_RECT}]`),
+];
+
+/** Soft floor on skeleton bone corners — anything sharper than this reads as a glyph,
+ *  not a placeholder, which fights the whole point of a skeleton. 4 px is the smallest
+ *  radius that still reads as "rounded" at typical display DPI. Applied only to
+ *  text / media / box bones; chrome bones carry the consumer's own radius verbatim. */
+const MIN_BONE_RADIUS = 4;
+const clampRadius = (radius: string): string =>
+  radius.replace(/(\d+(?:\.\d+)?)px/g, (_, raw) => {
+    const n = parseFloat(raw);
+    return Number.isFinite(n) && n < MIN_BONE_RADIUS ? `${MIN_BONE_RADIUS}px` : `${n}px`;
+  });
 
-/** Draws `rects` into `layer`, reusing the elements already there. */
+/** Draws `rects` into `layer`, reusing the elements already there.
+ *
+ * Bones live in the light DOM (not a shadow root) so a consumer's stylesheet
+ * can reach them — selectors like `[ask-rect="text"]`, `[ask-rect="media"]`,
+ * `[ask-rect="box"]`, or the `--ask-base` / `--ask-highlight` custom
+ * properties — and theme the skeleton with the consumer's own tokens rather
+ * than plugin defaults. Positioning (x/y/width/height/radius) stays inline
+ * because it is per-bone; fill colour comes from the stylesheet.
+ *
+ * Added after mount, so Vue/React hydration never sees them.
+ */
 export function drawSkeleton(layer: HTMLElement, rects: SkeletonRect[]) {
-  const root = shadow(layer);
+  const existing = rectsOf(layer);
   const rect = layer.getBoundingClientRect();
   const group = {
     left: rect.left + scrollX,
@@ -144,23 +163,59 @@ export function drawSkeleton(layer: HTMLElement, rects: SkeletonRect[]) {
   const motion = motionOf(layer);
 
   rects.forEach((part, index) => {
-    let element = root.children[index] as HTMLElement | undefined;
+    let element = existing[index];
     if (!element) {
       element = document.createElement('div');
-      element.setAttribute(ATTR_RECT, '');
-      // Inline: no page stylesheet reaches into the shadow root
-      element.style.cssText = `position:absolute;display:block;pointer-events:none;background-color:${BASE};background-repeat:no-repeat`;
-      root.append(element);
+      // Positioning-only: the stylesheet owns colour so the consumer can retheme
+      element.style.cssText = `position:absolute;display:block;pointer-events:none;background-repeat:no-repeat`;
+      layer.append(element);
     }
+    // Type attribute set every pass — bone reuse across renders may change type
+    element.setAttribute(ATTR_RECT, part.type);
 
     Object.assign(element.style, {
       left: `${part.x}px`,
       top: `${part.y}px`,
       width: `${part.width}px`,
       height: `${part.height}px`,
-      borderRadius: part.radius,
+      // Chrome reproduces the real element's border-radius exactly (0 stays 0);
+      // placeholder bones get a 4-px floor so sharp-cornered text / media / box
+      // bones still read as rounded skeletons, not glyphs of the real content.
+      borderRadius: part.type === 'chrome' ? part.radius : clampRadius(part.radius),
     });
 
+    if (part.type === 'chrome') {
+      // Chrome bones reproduce the container's painted surface (bg / borders / shadow),
+      // captured from the consumer's own CSS. Reset shimmer side-effects so an element
+      // reused across draws isn't left with a shimmer background from a previous pass,
+      // then apply the captured paint inline — the stylesheet default fill would obscure
+      // the real colour.
+      for (const anim of animationsOf(element)) anim.cancel();
+      element.style.backgroundImage = '';
+      element.style.backgroundSize = '';
+      element.style.backgroundRepeat = '';
+      const chrome = part.chrome;
+      element.style.background = chrome?.background ?? '';
+      element.style.borderTop = chrome?.borderTop ?? '';
+      element.style.borderRight = chrome?.borderRight ?? '';
+      element.style.borderBottom = chrome?.borderBottom ?? '';
+      element.style.borderLeft = chrome?.borderLeft ?? '';
+      element.style.boxShadow = chrome?.boxShadow ?? '';
+      // Chrome never shimmers — it's the outline, not a loading placeholder
+      element.dataset.motion = 'chrome';
+      return;
+    }
+
+    // Non-chrome bones: drop any chrome state left on a reused element, then shimmer.
+    if (element.dataset.motion === 'chrome') {
+      element.style.background = '';
+      element.style.borderTop = '';
+      element.style.borderRight = '';
+      element.style.borderBottom = '';
+      element.style.borderLeft = '';
+      element.style.boxShadow = '';
+    }
+
     // Restarted only when its place, group, the page's width or the motion changes
     const key = `${Math.round(group.left + part.x)}|${Math.round(part.y)}|${Math.round(part.height)}|${Math.round(group.left)}|${Math.round(group.width)}|${Math.round(group.height)}|${document.documentElement.clientWidth}|${motion.animation}|${motion.duration}`;
     if (element.dataset.motion !== key) {
@@ -169,5 +224,6 @@ export function drawSkeleton(layer: HTMLElement, rects: SkeletonRect[]) {
     }
   });
 
-  while (root.children.length > rects.length) root.lastElementChild!.remove();
+  // Trim excess bones left over from a previous, longer draw
+  for (let i = existing.length - 1; i >= rects.length; i--) existing[i]!.remove();
 }

package/src/core/styles.ts

@@ -8,6 +8,7 @@ import {
   ATTR_LOADING,
   ATTR_OWN,
   ATTR_PANE,
+  ATTR_RECT,
   ATTR_REVEAL,
   ATTR_STATUS,
   ATTR_XRAY,
@@ -62,6 +63,25 @@ ask-reveal[loading]:not(:defined) {
   background-repeat: no-repeat;
 }
 
+/*
+ * Bones drawn by \`drawSkeleton\` live in the light DOM (no shadow root), so a
+ * consumer can target them with their own stylesheet. Positioning stays inline
+ * (per-bone), but the fill colour reads from a CSS custom property so the
+ * consumer's theme flows through — set \`--ask-base\` on any ancestor to
+ * recolour every bone inside it, or use the type modifier to style text / media
+ * / box bones separately.
+ *
+ * Chrome bones are excluded: they reproduce the consumer's own container paint
+ * (background, border, shadow) that \`captureChrome\` snapshotted, so they must
+ * NOT get a generic fill underneath. Without the \`:not()\`, a bordered-only
+ * container (e.g. a footer with \`border-t\`) would show as a solid filled
+ * rectangle instead of just its captured divider.
+ */
+[${ATTR_RECT}]:not([${ATTR_RECT}="chrome"]) {
+  background-color: var(--ask-base, var(--ask-block, var(--ak-skeleton-block, rgb(128 128 128 / 0.2))));
+  background-repeat: no-repeat;
+}
+
 /* Containers keep their surface; what they hold is drawn by bones, measured before the first paint */
 @scope ([${ATTR_LOADING}]) to ([${ATTR_OWN}], [${ATTR_LAYER}]) {
   :scope,

package/web-types.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/web-types",
   "name": "@alikhalilll/a-smart-skeleton",
-  "version": "1.0.0",
+  "version": "2.0.0",
   "js-types-syntax": "typescript",
   "description-markup": "markdown",
   "framework": "vue",