@camp.dev/bones 0.4.0 → 0.5.0

package/README.md

@@ -1,22 +1,12 @@
 # Bones
 
-[![Bundle Size](https://deno.bundlejs.com/badge?q=@camp.dev/bones)](https://bundlejs.com/?q=%40camp.dev%2Fbones)
+Automatic skeleton loaders for any stack. One stylesheet, ~5.7 kB gzipped, no JavaScript, 0 dependencies.
 
-Skeleton loaders designed for React Server Components and streaming. ~2.7 kB gzipped, 0 dependencies.
-
-With React Server Components, your component renders once on the server. There's no re-render from "loading" to "loaded," so `{data || <Skeleton />}` doesn't work anymore. The typical workaround is writing a separate skeleton component for every piece of UI and passing it as a Suspense fallback.
-
-Bones skips the duplication. You write your markup once and it handles both states. The skeleton and the real UI are the same component, so they can't drift apart.
+Set `aria-busy="true"` on a region and its content becomes a skeleton: a bar for every leaf, a box for every image and control. No skeleton components, no placeholder markup, no JavaScript in the loading path. When inference gets something wrong, a `data-bones-*` attribute on the real markup fixes it, and the attribute does nothing once the region is not busy.
 
 ## How it works
 
-`createBones` accepts data or a promise of data. While loading, its `bone` function returns HTML attributes that style elements as skeletons via CSS. Once the data resolves, `bone` returns an empty object and your component renders normally. There are no hooks and no context providers.
-
-- Works in Server Components. No hooks, no context, no `'use client'`.
-- One component handles both loading and loaded states.
-- 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.
+The stylesheet keys on `aria-busy="true"`. On that element and under it, an element with no element children paints as a text bar and an image or form control paints as a block. Text hides by zeroing the alpha of its own color, so bones take their color from the text around them and contrast on any background. `data-bones-type`, `data-bones-lines`, `data-bones-length`, `data-bones-auto`, and `data-bones-animate` adjust the result. That is the whole API.
 
 ## Installation
 
@@ -24,142 +14,107 @@ Bones skips the duplication. You write your markup once and it handles both stat
 npm install @camp.dev/bones
 ```
 
-Import the CSS once in your root layout or entry point:
+Import the stylesheet once in your root layout or entry point:
 
 ```tsx
 import "@camp.dev/bones/css";
 ```
 
-## Entry points
+Without a bundler, link it from a CDN:
 
-| 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.                                                                                                        |
+```html
+<link rel="stylesheet" href="https://unpkg.com/@camp.dev/bones/src/css/bones.css" />
+```
 
-React is an optional peer dependency: installing the package without React is supported and only the `/react` entry requires it.
+## Entry points
 
-## Basic usage
+| Import                | Contents                                                                                                          |
+| --------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| `@camp.dev/bones/css` | The stylesheet. Paints every leaf under `aria-busy="true"` and honors the `data-bones-*` attributes. Import once. |
 
-Pass data (or a promise of data) to `createBones`. Spread the `bone` function's return value onto elements that should show skeletons while loading.
+Zero dependencies. No framework is required or assumed, and nothing ships JavaScript.
 
-```tsx
-import { createBones } from "@camp.dev/bones/react";
+## Basic usage
 
-function ProfileCard({ user }: { user: Promise<User> | User }) {
-  const { bone, data, lines } = createBones(user);
+Plain HTML:
 
-  return (
-    <div>
-      <img src={data?.avatar} width={80} height={80} {...bone("block")} />
-      <h3 {...bone("text", { length: 10 })}>{data?.name}</h3>
-      {lines(data?.bio, 3, (item) => (
-        <p>{item}</p>
-      ))}
-    </div>
-  );
-}
+```html
+<section aria-busy="true">
+  <img src="/avatar.png" width="64" height="64" alt="" />
+  <h2>Sasha Greenfield</h2>
+  <p>Collects tape loops, birdsong, and the hum of old refrigerators.</p>
+</section>
 ```
 
-Pass the promise to the component, and reuse the same component with `forceBones` as the fallback:
+In a framework, write the component so it renders its shell when the data is missing and forwards its props to the root. The skeleton is then the component with `aria-busy` and no data:
 
 ```tsx
-import { forceBones } from "@camp.dev/bones/react";
-import { Suspense } from "react";
+import type { ComponentProps } from "react";
 
-export default function Page() {
-  const user = fetchUser();
+function ProfileCard({ user, ...rest }: { user?: User } & ComponentProps<"div">) {
   return (
-    <Suspense fallback={<ProfileCard user={forceBones} />}>
-      <ProfileCard user={user} />
-    </Suspense>
+    <div {...rest}>
+      <img src={user?.avatar} width={80} height={80} alt="" />
+      <h3>{user?.name}</h3>
+      <p data-bones-lines="3">{user?.bio}</p>
+      <ul>
+        {(user?.posts ?? Array.from({ length: 3 })).map((post, i) => (
+          <li key={post?.id ?? i}>{post?.title}</li>
+        ))}
+      </ul>
+    </div>
   );
 }
-```
-
-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
 
-| Type          | Use for                        | Example                              |
-| ------------- | ------------------------------ | ------------------------------------ |
-| `"text"`      | Headings, paragraphs, labels   | `<h2 {...bone("text")}>`             |
-| `"block"`     | Images, avatars, thumbnails    | `<img src={…} {...bone("block")} />` |
-| `"container"` | Wrappers with complex children | `<div {...bone("container")}>`       |
+async function Profile() {
+  return <ProfileCard user={await fetchUser()} />;
+}
 
-## Previewing skeletons
+<Suspense fallback={<ProfileCard aria-busy="true" />}>
+  <Profile />
+</Suspense>;
+```
 
-Use `forceBones` to see a component's skeleton state without setting up real data:
+The fallback is the component, and the async child is what suspends. `data-bones-lines="3"` says the bio is three lines tall while empty, and `Array.from` gives the list three placeholder rows, since CSS cannot add elements.
 
-```tsx
-import { createBones, forceBones } from "@camp.dev/bones/react";
+## Adjust a bone
 
-<ProfileCard user={forceBones} />;
-```
+| Attribute                                   | Effect                                                                                        |
+| ------------------------------------------- | --------------------------------------------------------------------------------------------- |
+| `data-bones-type="text"`                    | Paint a text bar regardless of inference.                                                     |
+| `data-bones-type="block"`                   | Paint one filled box and hide descendants. A `div` avatar, a card.                            |
+| `data-bones-lines="3"`                      | Paint three stacked bars in one element. 2 to 8 everywhere; any integer with modern `attr()`. |
+| `data-bones-length="9"`                     | Make the bar nine characters wide. 1 to 40 everywhere; any integer with modern `attr()`.      |
+| `data-bones-auto="off"`                     | Keep this subtree readable. On `<body>`, only explicit markup paints.                         |
+| `data-bones-animate="shimmer\|pulse\|none"` | Pick the animation for the bones inside, or on the bone itself.                               |
 
-To force a subtree into skeleton mode at once, pass `forceBones` to each component in it:
+Explicit attributes are unlayered, so page CSS cannot keep their text visible without a more specific rule of its own. Inferred bones live in `@layer bones-auto`, so a page rule that sets `color` on a leaf keeps that text visible over its bar; that is the one thing to know when a bar looks wrong. A bar sits inside its element's padding, so a badge or a pill keeps its shape while it loads. Padding in `px`, `em`, or `rem` is exact; percentage padding misses.
 
-```tsx
-<ProfileCard user={forceBones} />
-<PostList posts={forceBones} />
-```
+## Previewing skeletons
 
-`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:
+Render the component busy with no data. No promise, no boundary, no Storybook addon:
 
 ```tsx
-<PostCard key={item?.id ?? i} post={item ?? forceBones} />
+<ProfileCard aria-busy="true" />
 ```
 
-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
+## Focus and timing
 
-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:
+A skeleton's links and buttons are still focusable. Put `inert` beside `aria-busy` on a fallback that renders any:
 
 ```tsx
-import "@camp.dev/bones/auto.css";
+<Suspense fallback={<ProfileCard aria-busy="true" inert />}>
 ```
 
-Set `aria-busy="true"` on the loading region and every unmarked leaf inside it becomes a skeleton, no `bone()` calls required:
-
-```html
-<section aria-busy="true">
-  <h2>Title</h2>
-  <p>Summary text goes here.</p>
-</section>
-```
-
-`[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` 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>
-```
+Suspense paints the skeleton first, so it never flashes. A region you mark busy around your own `fetch` can. The docs' [Delay and hold](https://github.com/campdotdev/bones/blob/main/apps/docs/content/docs/examples.mdx#delay-and-hold) recipe waits before showing bones and keeps them long enough once shown; [Streaming](https://github.com/campdotdev/bones/blob/main/apps/docs/content/docs/streaming.mdx) shows the swap script for a server with no framework.
 
-`@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).
+## Theming
 
-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`.
+`--bone-base`, `--bone-highlight`, `--bone-radius`, and `--bone-duration` are CSS custom properties; set them on any ancestor. `--bone-radius` must carry a unit. `prefers-reduced-motion` turns shimmer into a slow pulse; `data-bones-animate="none"` stays still.
 
 ## Development
 
 ```bash
 vp install   # install dependencies
 vp test      # run tests
-vp pack      # build the library
 ```

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@camp.dev/bones",
-  "version": "0.4.0",
-  "description": "Skeleton loaders designed for React Server Components and streaming.",
+  "version": "0.5.0",
+  "description": "Automatic skeleton loaders for any stack. One stylesheet.",
   "homepage": "https://github.com/campdotdev/bones#readme",
   "bugs": {
     "url": "https://github.com/campdotdev/bones/issues"
@@ -13,63 +13,31 @@
     "url": "git+https://github.com/campdotdev/bones.git"
   },
   "files": [
-    "dist",
     "src/css"
   ],
   "type": "module",
   "sideEffects": [
-    "*.css",
-    "./dist/element/index.mjs"
+    "*.css"
   ],
   "exports": {
-    ".": "./dist/index.mjs",
-    "./element": "./dist/element/index.mjs",
-    "./react": "./dist/react/index.mjs",
-    "./server": "./dist/server/index.mjs",
     "./package.json": "./package.json",
     "./css": {
       "style": "./src/css/bones.css",
       "default": "./src/css/bones.css"
-    },
-    "./auto.css": {
-      "style": "./src/css/auto.css",
-      "default": "./src/css/auto.css"
     }
   },
   "publishConfig": {
     "access": "public"
   },
   "devDependencies": {
-    "@testing-library/jest-dom": "^6.9.1",
-    "@testing-library/react": "^16.3.2",
     "@types/node": "^25.5.0",
-    "@types/react": "^19.2.14",
-    "@types/react-dom": "^19.2.3",
-    "@typescript/native-preview": "7.0.0-dev.20260328.1",
-    "@vitest/coverage-v8": "^4.1.5",
     "jsdom": "^29.0.2",
     "playwright": "^1.62.1",
-    "react": "^19.2.5",
     "typescript": "^6.0.2",
     "vite-plus": "^0.1.14"
   },
-  "peerDependencies": {
-    "react": ">=18",
-    "react-dom": ">=18"
-  },
-  "peerDependenciesMeta": {
-    "react": {
-      "optional": true
-    },
-    "react-dom": {
-      "optional": true
-    }
-  },
   "scripts": {
-    "build": "vp pack",
-    "dev": "vp pack --watch",
     "test": "vp test",
-    "check": "vp check",
-    "health": "vp test --project unit --coverage && fallow health --root . --coverage coverage/coverage-final.json --format json --quiet"
+    "check": "vp check"
   }
 }