@camp.dev/bones 0.2.0 → 0.4.0

package/README.md

@@ -14,7 +14,7 @@ Bones skips the duplication. You write your markup once and it handles both stat
 
 - Works in Server Components. No hooks, no context, no `'use client'`.
 - One component handles both loading and loaded states.
-- Pass a promise as a prop. Bones wires up Suspense for you.
+- Pass data or a promise. A pending promise suspends to your `<Suspense>` boundary; `forceBones` renders the skeleton.
 - Skeletons are pure CSS, themed with custom properties.
 - Loading elements get `aria-busy="true"` automatically.
 
@@ -32,12 +32,14 @@ import "@camp.dev/bones/css";
 
 ## Entry points
 
-| Import                     | Contents                                                                                                                            |
-| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
-| `@camp.dev/bones/react`    | `createBones`, `readPromise`, `forceBones`, `minMax`, `<Bones>`, `<BonesForce>`                                                     |
-| `@camp.dev/bones/css`      | The skeleton stylesheet. Import once in your root layout.                                                                           |
-| `@camp.dev/bones/auto.css` | Skeletonizes unmarked leaves under `aria-busy="true"`. Imports the base stylesheet itself, so a separate `/css` import is optional. |
-| `@camp.dev/bones`          | The framework-agnostic core (`boneAttributes`, `minMax`). You only need this to build your own renderer or adapter.                 |
+| Import                     | Contents                                                                                                                                                                                                                   |
+| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `@camp.dev/bones/react`    | `createBones`, `readPromise`, `forceBones`, `minMax`, `isMinMax`, `BonesBoundary`                                                                                                                                          |
+| `@camp.dev/bones/css`      | The skeleton stylesheet. Import once in your root layout.                                                                                                                                                                  |
+| `@camp.dev/bones/auto.css` | Skeletonizes unmarked leaves under `aria-busy="true"`. Imports the base stylesheet itself, so a separate `/css` import is optional.                                                                                        |
+| `@camp.dev/bones/element`  | `<bones-boundary>`, a custom element that sets `aria-busy` and `inert` on its subtree with `delay`, `min-duration`, and a crossfade. `precision="measured"` draws pixel-accurate per-line bones measured from the content. |
+| `@camp.dev/bones/server`   | `streamBones` and the wire-protocol primitives: stream a shell with busy boundaries, then flush each region's content out of order as it resolves.                                                                         |
+| `@camp.dev/bones`          | The framework-agnostic core (`boneAttributes`, `minMax`). You only need this to build your own renderer or adapter.                                                                                                        |
 
 React is an optional peer dependency: installing the package without React is supported and only the `/react` entry requires it.
 
@@ -63,21 +65,23 @@ function ProfileCard({ user }: { user: Promise<User> | User }) {
 }
 ```
 
-Wrap components that receive promises in `<Bones>`. It creates a Suspense boundary and generates the skeleton fallback for you:
+Pass the promise to the component, and reuse the same component with `forceBones` as the fallback:
 
 ```tsx
-import { Bones } from "@camp.dev/bones/react";
+import { forceBones } from "@camp.dev/bones/react";
+import { Suspense } from "react";
 
 export default function Page() {
+  const user = fetchUser();
   return (
-    <Bones>
-      <ProfileCard user={fetchUser()} />
-    </Bones>
+    <Suspense fallback={<ProfileCard user={forceBones} />}>
+      <ProfileCard user={user} />
+    </Suspense>
   );
 }
 ```
 
-While the promise is pending, `<Bones>` renders the same `<ProfileCard>` tree with skeletons visible. Once it resolves, the real content swaps in.
+While the promise is pending, the fallback renders `<ProfileCard>` with skeletons visible. Once it resolves, the real content swaps in. There is no separate skeleton component to keep in sync — the fallback is the component.
 
 ## Bone types
 
@@ -97,17 +101,21 @@ import { createBones, forceBones } from "@camp.dev/bones/react";
 <ProfileCard user={forceBones} />;
 ```
 
-To force an entire subtree into skeleton mode at once, wrap it with `<BonesForce>`:
+To force a subtree into skeleton mode at once, pass `forceBones` to each component in it:
 
 ```tsx
-import { BonesForce } from "@camp.dev/bones/react";
+<ProfileCard user={forceBones} />
+<PostList posts={forceBones} />
+```
+
+`forceBones` only forces the component it's passed to. A component that derives child props from its own data must forward it itself, such as `PostList` mapping items into cards. `repeat` yields `undefined` for items that don't exist yet:
 
-<BonesForce>
-  <ProfileCard />
-  <PostList />
-</BonesForce>;
+```tsx
+<PostCard key={item?.id ?? i} post={item ?? forceBones} />
 ```
 
+For content that has no bone markup at all, wrap it in [`<bones-boundary force>`](https://github.com/campdotdev/bones/blob/main/apps/docs/content/docs/api/bones-boundary.mdx) and let `auto.css` draw leaf bones.
+
 ## Automatic skeletons
 
 For markup you haven't wired up with `bone()` — third-party components, server-rendered HTML, anything without explicit attributes — import the auto stylesheet. It imports `/css` itself, so this one file is a complete setup:
@@ -127,7 +135,26 @@ Set `aria-busy="true"` on the loading region and every unmarked leaf inside it b
 
 `[data-bones-auto="off"]` opts a subtree out — useful for a status message you want to stay readable while its container skeletonizes. Explicit `data-bone` markup is left alone; `auto.css` only styles elements neither `bone()` nor a manual `data-bone` attribute has already claimed.
 
-Auto rules live in `@layer bones-auto`, so any page CSS that sets `color` on an element outranks the bone's transparent text, and that text stays visible over its skeleton bar. `data-bone-animate` also has to sit on an ancestor of the `aria-busy` element — set directly on it, it has no effect. The `data-bone-animate` overrides rely on `@scope`. In a browser without `@scope`, auto bones always shimmer, and `data-bone-animate="pulse"` and `"none"` cannot change that. The `prefers-reduced-motion` fallback to pulse still applies.
+Auto rules live in `@layer bones-auto`, so any page CSS that sets `color` on an element outranks the bone's transparent text, and that text stays visible over its skeleton bar. `data-bone-animate` works on the `aria-busy` element itself or on any ancestor. The `data-bone-animate` overrides rely on `@scope`. In a browser without `@scope`, every bone shimmers, and `data-bone-animate="pulse"` and `"none"` cannot change that. The `prefers-reduced-motion` fallback to pulse still applies.
+
+## Without React
+
+`<bones-boundary>` manages the loading state for any stack. Set `busy` when a request starts and clear it when the response lands. The element waits 200 ms before showing bones and keeps them for at least 400 ms, then crossfades to content with the View Transitions API where available.
+
+```html
+<script type="module">
+  import "@camp.dev/bones/element";
+</script>
+
+<bones-boundary busy>
+  <h2>Title</h2>
+  <p>Body copy.</p>
+</bones-boundary>
+```
+
+`@camp.dev/bones/element` is a bare specifier. A browser cannot resolve it on its own, so this snippet needs a bundler or an import map. To load the element straight from a CDN in a plain HTML file, see the URL form on the [bones-boundary docs page](https://github.com/campdotdev/bones/blob/main/apps/docs/content/docs/api/bones-boundary.mdx).
+
+Pair it with `auto.css` for zero-markup skeletons, or with `data-bone` markup from `boneAttributes`. The element is also exported for React as `<BonesBoundary>` from `@camp.dev/bones/react`.
 
 ## Development
 

package/dist/css/auto.css

@@ -44,7 +44,7 @@
       select *,
       object *
     ) {
-    color: transparent;
+    color: rgb(from currentcolor r g b / 0);
     position: relative;
     min-width: 4ch;
     min-height: 1lh;
@@ -144,7 +144,7 @@
       progress,
       meter
     ):not([data-bone], [data-bone] *, [data-bones-auto="off"], [data-bones-auto="off"] *) {
-    color: transparent;
+    color: rgb(from currentcolor r g b / 0);
     background-color: var(--bone-base);
     border-radius: var(--bone-radius);
     border-color: transparent;
@@ -283,10 +283,13 @@
 }
 
 @layer bones-auto {
-  /* Auto bones default to shimmer. bones.css only animates inside a
-     [data-bone-animate] scope; a zero-markup page has no such attribute, so
-     the default lives here and the scopes below mirror bones.css for pages
-     that do set it. */
+  /* Auto bones default to shimmer. bones.css has its own default, but its
+     rules match [data-bone] elements only and never the unmarked leaves
+     targeted here, so the default is restated for them, and the scopes below
+     mirror bones.css for pages that set the attribute (BON-16). In those
+     scopes, :is(:scope, :scope *) lets the attribute
+     sit on the aria-busy element itself: a scoped selector's implicit :scope
+     prefix matches strict descendants only (BON-17). */
   [aria-busy="true"]
     :not(:has(*)):not(
       [data-bone],
@@ -374,7 +377,7 @@
   }
 
   @scope ([data-bone-animate="shimmer"]) to ([data-bone-animate]:not([data-bone-animate="shimmer"])) {
-    [aria-busy="true"]
+    [aria-busy="true"]:is(:scope, :scope *)
       :not(:has(*)):not(
         [data-bone],
         [data-bone] *,
@@ -403,7 +406,7 @@
         select *,
         object *
       )::before,
-    [aria-busy="true"]
+    [aria-busy="true"]:is(:scope, :scope *)
       :not(:has(*)):not(
         [data-bone],
         [data-bone] *,
@@ -432,7 +435,7 @@
         select *,
         object *
       )::after,
-    [aria-busy="true"]
+    [aria-busy="true"]:is(:scope, :scope *)
       :is(
         img,
         svg,
@@ -461,7 +464,7 @@
     }
 
     @media (prefers-reduced-motion: reduce) {
-      [aria-busy="true"]
+      [aria-busy="true"]:is(:scope, :scope *)
         :not(:has(*)):not(
           [data-bone],
           [data-bone] *,
@@ -490,7 +493,7 @@
           select *,
           object *
         )::before,
-      [aria-busy="true"]
+      [aria-busy="true"]:is(:scope, :scope *)
         :not(:has(*)):not(
           [data-bone],
           [data-bone] *,
@@ -519,7 +522,7 @@
           select *,
           object *
         )::after,
-      [aria-busy="true"]
+      [aria-busy="true"]:is(:scope, :scope *)
         :is(
           img,
           svg,
@@ -544,7 +547,7 @@
     }
 
     @media (forced-colors: active) {
-      [aria-busy="true"]
+      [aria-busy="true"]:is(:scope, :scope *)
         :not(:has(*)):not(
           [data-bone],
           [data-bone] *,
@@ -573,7 +576,7 @@
           select *,
           object *
         )::after,
-      [aria-busy="true"]
+      [aria-busy="true"]:is(:scope, :scope *)
         :is(
           img,
           svg,
@@ -598,7 +601,7 @@
   }
 
   @scope ([data-bone-animate="pulse"]) to ([data-bone-animate]:not([data-bone-animate="pulse"])) {
-    [aria-busy="true"]
+    [aria-busy="true"]:is(:scope, :scope *)
       :not(:has(*)):not(
         [data-bone],
         [data-bone] *,
@@ -627,7 +630,7 @@
         select *,
         object *
       )::before,
-    [aria-busy="true"]
+    [aria-busy="true"]:is(:scope, :scope *)
       :not(:has(*)):not(
         [data-bone],
         [data-bone] *,
@@ -656,7 +659,7 @@
         select *,
         object *
       )::after,
-    [aria-busy="true"]
+    [aria-busy="true"]:is(:scope, :scope *)
       :is(
         img,
         svg,
@@ -680,7 +683,7 @@
     }
 
     @media (prefers-reduced-motion: reduce) {
-      [aria-busy="true"]
+      [aria-busy="true"]:is(:scope, :scope *)
         :not(:has(*)):not(
           [data-bone],
           [data-bone] *,
@@ -709,7 +712,7 @@
           select *,
           object *
         )::before,
-      [aria-busy="true"]
+      [aria-busy="true"]:is(:scope, :scope *)
         :not(:has(*)):not(
           [data-bone],
           [data-bone] *,
@@ -738,7 +741,7 @@
           select *,
           object *
         )::after,
-      [aria-busy="true"]
+      [aria-busy="true"]:is(:scope, :scope *)
         :is(
           img,
           svg,
@@ -763,7 +766,7 @@
     }
 
     @media (forced-colors: active) {
-      [aria-busy="true"]
+      [aria-busy="true"]:is(:scope, :scope *)
         :not(:has(*)):not(
           [data-bone],
           [data-bone] *,
@@ -792,7 +795,7 @@
           select *,
           object *
         )::after,
-      [aria-busy="true"]
+      [aria-busy="true"]:is(:scope, :scope *)
         :is(
           img,
           svg,
@@ -817,7 +820,7 @@
   }
 
   @scope ([data-bone-animate="none"]) to ([data-bone-animate]:not([data-bone-animate="none"])) {
-    [aria-busy="true"]
+    [aria-busy="true"]:is(:scope, :scope *)
       :not(:has(*)):not(
         [data-bone],
         [data-bone] *,
@@ -846,7 +849,7 @@
         select *,
         object *
       )::before,
-    [aria-busy="true"]
+    [aria-busy="true"]:is(:scope, :scope *)
       :not(:has(*)):not(
         [data-bone],
         [data-bone] *,
@@ -875,7 +878,7 @@
         select *,
         object *
       )::after,
-    [aria-busy="true"]
+    [aria-busy="true"]:is(:scope, :scope *)
       :is(
         img,
         svg,
@@ -899,7 +902,7 @@
     }
 
     @media (forced-colors: active) {
-      [aria-busy="true"]
+      [aria-busy="true"]:is(:scope, :scope *)
         :not(:has(*)):not(
           [data-bone],
           [data-bone] *,
@@ -928,7 +931,7 @@
           select *,
           object *
         )::after,
-      [aria-busy="true"]
+      [aria-busy="true"]:is(:scope, :scope *)
         :is(
           img,
           svg,
@@ -1090,3 +1093,13 @@
     }
   }
 }
+
+@layer bones-auto {
+  /* precision="measured" hides a boundary's content with inherited
+     visibility from the shadow side. Visibility, unlike display, can be
+     switched back on by a descendant, so the opt-out contract survives
+     measured mode: exempt subtrees stay visible under the overlay. */
+  bones-boundary[data-bones-measured] [data-bones-auto="off"] {
+    visibility: visible;
+  }
+}

package/dist/css/bones.css

@@ -1,19 +1,18 @@
 :root {
-  --bone-base: rgba(0, 0, 0, 0.12);
-  --bone-highlight: rgba(0, 0, 0, 0.06);
+  /* Bones derive their color from the text color in effect at the bone, so
+     they inherit the page's own contrast guarantee on any background in any
+     scheme (BON-13). currentColor resolves where var() is used, not here.
+     The alpha reset matters: bones hide their content by zeroing the alpha
+     of the color property (never with the transparent keyword, which would
+     discard the channels), and the mix restores it. */
+  --bone-base: color-mix(in srgb, rgb(from currentcolor r g b / 1) 12%, transparent);
+  --bone-highlight: color-mix(in srgb, rgb(from currentcolor r g b / 1) 6%, transparent);
   --bone-radius: 4px;
   --bone-duration: 1.5s;
 }
 
-@media (prefers-color-scheme: dark) {
-  :root {
-    --bone-base: rgba(255, 255, 255, 0.12);
-    --bone-highlight: rgba(255, 255, 255, 0.06);
-  }
-}
-
 [data-bone="text"] {
-  color: transparent;
+  color: rgb(from currentcolor r g b / 0);
   position: relative;
   min-width: 4ch;
   min-height: 1lh;
@@ -72,7 +71,7 @@
 
 img[data-bone="block"],
 video[data-bone="block"] {
-  color: transparent;
+  color: rgb(from currentcolor r g b / 0);
 }
 
 [data-bone="container"] {
@@ -111,11 +110,43 @@ video[data-bone="block"] {
   }
 }
 
-@scope ([data-bone-animate="shimmer"]) to ([data-bone-animate]:not([data-bone-animate="shimmer"])) {
+/* Marked bones shimmer by default, the same as auto bones and the measured
+   overlay (BON-16). data-bone-animate="none" is the opt-out; the @scope
+   blocks below override this at higher specificity, so their order relative
+   to this rule does not matter. */
+[data-bone="text"]::after,
+[data-bone="block"],
+[data-bone="container"]::before {
+  animation: bone-shimmer var(--bone-duration) ease-in-out infinite;
+  background: linear-gradient(
+    90deg,
+    var(--bone-base) 25%,
+    var(--bone-highlight) 50%,
+    var(--bone-base) 75%
+  );
+  background-size: 200% 100%;
+}
+
+@media (prefers-reduced-motion: reduce) {
   [data-bone="text"]::after,
-  [data-bone="text"]::before,
   [data-bone="block"],
   [data-bone="container"]::before {
+    animation: bone-pulse 2s ease-in-out infinite;
+    background: var(--bone-base);
+    background-size: auto;
+  }
+}
+
+/* :is(:scope, :scope *) lets the attribute work from the bone itself, not
+   only from a wrapper: a scoped selector's implicit :scope prefix matches
+   strict descendants only, so a plain compound never matches the scope root
+   (BON-17). The reduced-motion override sits inside each animated scope so it
+   matches at the scope's own specificity; "none" has no override because none
+   still means none. */
+@scope ([data-bone-animate="shimmer"]) to ([data-bone-animate]:not([data-bone-animate="shimmer"])) {
+  [data-bone="text"]:is(:scope, :scope *)::after,
+  [data-bone="block"]:is(:scope, :scope *),
+  [data-bone="container"]:is(:scope, :scope *)::before {
     animation: bone-shimmer var(--bone-duration) ease-in-out infinite;
     background: linear-gradient(
       90deg,
@@ -125,32 +156,42 @@ video[data-bone="block"] {
     );
     background-size: 200% 100%;
   }
+
+  @media (prefers-reduced-motion: reduce) {
+    [data-bone="text"]:is(:scope, :scope *)::after,
+    [data-bone="block"]:is(:scope, :scope *),
+    [data-bone="container"]:is(:scope, :scope *)::before {
+      animation: bone-pulse 2s ease-in-out infinite;
+      background: var(--bone-base);
+      background-size: auto;
+    }
+  }
 }
 
 @scope ([data-bone-animate="pulse"]) to ([data-bone-animate]:not([data-bone-animate="pulse"])) {
-  [data-bone="text"]::after,
-  [data-bone="text"]::before,
-  [data-bone="block"],
-  [data-bone="container"]::before {
+  [data-bone="text"]:is(:scope, :scope *)::after,
+  [data-bone="block"]:is(:scope, :scope *),
+  [data-bone="container"]:is(:scope, :scope *)::before {
     animation: bone-pulse var(--bone-duration) ease-in-out infinite;
     background: var(--bone-base);
     background-size: auto;
   }
+
+  @media (prefers-reduced-motion: reduce) {
+    [data-bone="text"]:is(:scope, :scope *)::after,
+    [data-bone="block"]:is(:scope, :scope *),
+    [data-bone="container"]:is(:scope, :scope *)::before {
+      animation: bone-pulse 2s ease-in-out infinite;
+    }
+  }
 }
 
 @scope ([data-bone-animate="none"]) to ([data-bone-animate]:not([data-bone-animate="none"])) {
-  [data-bone="text"]::after,
-  [data-bone="text"]::before,
-  [data-bone="block"],
-  [data-bone="container"]::before {
+  [data-bone="text"]:is(:scope, :scope *)::after,
+  [data-bone="block"]:is(:scope, :scope *),
+  [data-bone="container"]:is(:scope, :scope *)::before {
     animation: none;
     background: var(--bone-base);
     background-size: auto;
   }
 }
-
-@media (prefers-reduced-motion: reduce) {
-  [aria-busy="true"] {
-    animation: bone-pulse 2s ease-in-out infinite;
-  }
-}

package/dist/element/boundary.d.mts

@@ -0,0 +1,26 @@
+//#region src/element/boundary.d.ts
+declare const DEFAULT_DELAY = 200;
+declare const DEFAULT_MIN_DURATION = 400;
+declare const Base: typeof HTMLElement;
+declare class BonesBoundary extends Base {
+  #private;
+  static readonly observedAttributes: string[];
+  get busy(): boolean;
+  set busy(value: boolean);
+  get force(): boolean;
+  set force(value: boolean);
+  get delay(): number;
+  set delay(value: number);
+  get minDuration(): number;
+  set minDuration(value: number);
+  get transition(): "auto" | "none";
+  set transition(value: "auto" | "none");
+  get precision(): "css" | "measured";
+  set precision(value: "css" | "measured");
+  get showing(): boolean;
+  connectedCallback(): void;
+  disconnectedCallback(): void;
+  attributeChangedCallback(name: string): void;
+}
+//#endregion
+export { BonesBoundary, DEFAULT_DELAY, DEFAULT_MIN_DURATION };