@cssints/skeleton 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alexei Accio
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,145 @@
-# Temporary Holding Version
+# @cssints/skeleton
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Loading placeholders for [cssints](../../README.md) whose shimmer is in phase across the page, whenever each one was
+mounted: one chain member of `cssints/plugin` `scope()`, after [sync-skeleton](https://github.com/crutchcorn/sync-skeleton).
+No runtime.
+
+```ts
+import { cn, height, hover, width } from "cssints" with { type: "cssints" };
+import { skeleton } from "@cssints/skeleton" with { type: "cssints" };
+
+export const line = cn(skeleton(), height("1em"), width("12rem"));
+export const avatar = cn(skeleton().radius("50%"), width("3rem"), height("3rem"));
+export const branded = cn(skeleton().color("#e4e4f0").highlight("#f4f4fa"), height("8rem"));
+export const card = cn(skeleton(), hover(skeleton().highlight("white")));
+```
+
+```css
+@property --skeleton-p {
+  syntax: "<percentage>";
+  inherits: true;
+  initial-value: 100%;
+}
+@layer _.k {
+  @keyframes kf-1a2b3c4d-skeleton {
+    from {
+      --skeleton-p: 100%;
+    }
+    to {
+      --skeleton-p: 0%;
+    }
+  }
+  @media (prefers-reduced-motion: no-preference) {
+    :root:has(._skeleton-clock) {
+      animation: kf-1a2b3c4d-skeleton 1.5s ease-in-out infinite;
+    }
+  }
+  ._skeleton-core {
+    border-radius: var(--skeleton-r, 0.25rem);
+    background-position: var(--skeleton-p) 0;
+    background-image: linear-gradient(
+      90deg,
+      var(--skeleton-c, color-mix(in oklab, currentColor 12%, transparent)) 40%,
+      var(--skeleton-h, color-mix(in oklab, currentColor 4%, transparent)) 50%,
+      var(--skeleton-c, color-mix(in oklab, currentColor 12%, transparent)) 60%
+    );
+    background-size: 300% 100%;
+    background-attachment: fixed;
+  }
+  /* only for targets without color-mix() (the defaults have Chrome 109) */
+  @supports not (color: color-mix(in oklab, red, red)) {
+    ._skeleton-core {
+      background-image: linear-gradient(
+        90deg,
+        var(--skeleton-c, rgb(128 128 128 / 20%)) 40%,
+        var(--skeleton-h, rgb(128 128 128 / 8%)) 50%,
+        var(--skeleton-c, rgb(128 128 128 / 20%)) 60%
+      );
+    }
+  }
+}
+@layer _.a {
+  ._kkw3xj {
+    --skeleton-r: 50%;
+  }
+  /* ... */
+}
+```
+
+`skeleton()` is `"_skeleton-core _skeleton-clock"`; each method adds one class. Both kernels are written as styles, no raw
+CSS: the clock is `media("(prefers-reduced-motion: no-preference)")(nest(":root:has(&)")(animation(keyframes({ from:
+vars({ "--_p": "100%" }), to: vars({ "--_p": "0%" }) }), "1.5s ease-in-out infinite")))`, and only its `@property`
+registration is a string (`atProperty`). The keyframes name is a hash of the steps with the scope's name after it.
+
+## How it stays in sync
+
+A CSS animation starts when its element gets its style, so a skeleton that mounts 700ms after another runs 700ms behind
+it, and the page flickers out of step. No skeleton here runs an animation. One animation on `:root` moves a registered,
+inherited percentage, `--skeleton-p`, and every skeleton reads it as its `background-position`: there is one clock, so
+there is one phase, in every browser that has `@property`. The animation is on only while a skeleton is in the document
+(`:root:has(._skeleton-clock)`), so a page with none runs nothing; when the last one goes and a new one comes, the clock
+starts again, with nothing to be out of step with.
+
+The gradient is three viewports wide and `fixed` to the viewport, so the band sweeps the page once, across every
+skeleton, as one picture (the same pixel at the same viewport x, as the browser test reads it). Where `fixed` has no
+effect (iOS Safari, which BCD marks as a partial implementation) each skeleton has a band of its own size, still on the
+same clock: in phase in time, not in space.
+
+The other ways were weighed and left: `background-attachment: fixed` with an animation on each skeleton lines up the
+space but not the time (each animation still starts at its own mount); a negative `animation-delay` from
+`document.timeline.currentTime` is script; CSS has no document timeline to name in `animation-timeline` (only scroll and
+view timelines), and `animation-delay: calc()` cannot read the time.
+
+## Rules
+
+- **Methods**, each once, in any order, all optional: `radius(<length-percentage [0,∞]>)` (`0.25rem`), `color(<color>)`
+  (the base, the text colour at 12%), `highlight(<color>)` (the band, the text colour at 4%). Each is one class that sets
+  a custom property, so a method works under a condition (`hover(skeleton().highlight("white"))`).
+- **Colours.** The defaults mix `currentColor` into transparent, so a skeleton is a darker box on a light page and a
+  lighter one on a dark page, and its band is less of it (a light sweep on light, a dark one on dark). The kernel reads
+  `--skeleton-c`, `--skeleton-h` and `--skeleton-r` with the defaults as fallbacks, so a value set on an ancestor themes
+  every skeleton under it. A `background-color` of your own shows through a translucent colour.
+- **Reduced motion.** Under `prefers-reduced-motion: reduce` the clock does not run: `--skeleton-p` stays at its initial
+  `100%`, which puts the band off the page, and every skeleton is its base colour, still.
+- **Conflicts.** `skeleton()` sets the background image, size, position and attachment and the corners: a `cn()` that
+  holds it and the `background` shorthand, one of those or a `border-radius*` property is a build error, derived from the
+  kernel: `cssints: skeleton: kernel core sets border-radius, background-image, background-size, background-position, background-attachment (this style also sets background)`.
+  `hover(skeleton())` is a build error too (a kernel cannot be conditional); wrap a method instead.
+- **Errors** are the grammar's, in the types and at build time: `skeleton.radius: unexpected "-4px" in "-4px", expected
+<length-percentage [0,∞]>`, `skeleton.color: unexpected "4px" in "4px", expected <color>`.
+
+## Browsers
+
+`bun run test:browsers` mounts a 600px skeleton, then 700ms later a 300px one under it and a control that runs the same
+keyframes on itself, pauses the animations and reads a row of each from a screenshot:
+
+| Browser                         | Animations      | A and B (300 columns) | Control | Reduced motion        |
+| ------------------------------- | --------------- | --------------------- | ------- | --------------------- |
+| Chrome (installed channel)      | one, on `:root` | 0 columns differ      | 132     | none, the base colour |
+| Firefox (Playwright build)      | one, on `:root` | 0 columns differ      | 132     | none, the base colour |
+| WebKit (Playwright trunk build) | one, on `:root` | 0 columns differ      | 132     | none, the base colour |
+
+`@property` (Chrome 85, Firefox 128, Safari 16.4) and `:has()` (Chrome 105, Firefox 121, Safari 15.4) are the kernel's
+`requires`: a target that lacks one is a build warning. Without `@property` the percentage animates as a discrete value
+and the band never shows (the base colour, still); without `:has()` nothing animates. For targets without `color-mix()`
+the build adds the grey defaults under `@supports not`, and only then.
+
+## Limits
+
+- The clock animates an inherited custom property on `:root`, so while a skeleton is mounted the browser updates the
+  style of the whole document on every frame. Fine for a loading page; keep skeletons out of a page that stays busy.
+- One clock for the page: the duration (1.5s), the easing and the direction are the same for every skeleton, and there are
+  no methods for them.
+- Text inside a skeleton shows: write it empty, or hide its children. A transparent text colour on the skeleton makes
+  the defaults transparent too (they mix `currentColor`); give it `skeleton().color(...).highlight(...)` then.
+- The band is horizontal, left to right; there is no pulse variant.
+
+```bash
+cd packages/skeleton && bun run test           # fixtures through the engine (output, conflicts, errors); bun run typecheck for the type test
+cd packages/skeleton && bun run test:browsers  # the phase and reduced motion in Chrome, Firefox and WebKit
+```
+
+## Credits
+
+The shared clock follows [sync-skeleton](https://github.com/crutchcorn/sync-skeleton) (MIT, Corbin Crutchley). The
+CSS is written here; no code is copied.

package/dist/index.d.mts

@@ -0,0 +1,23 @@
+//#region src/index.d.ts
+/**
+ * `skeleton().radius("8px").color("#ddd").highlight("#eee")`: a loading placeholder, each method once and optional
+ * (`0.25rem`, the text colour at 12% and 4%). The shimmer of every skeleton on the page is one animation on `:root`, so
+ * they are in phase whenever each was mounted; under `prefers-reduced-motion: reduce` it is the base colour, still. It
+ * sets the background and the corners, so a `background*` or `border-radius*` property in the same `cn()` is a build
+ * error.
+ */
+export declare const skeleton: () => import("cssints/plugin").Chain<"skeleton", {
+  readonly radius: {
+    readonly args: "<length-percentage [0,∞]>";
+    readonly emit: (v: string) => [string, string][];
+  };
+  readonly color: {
+    readonly args: "<color>";
+    readonly emit: (v: string) => [string, string][];
+  };
+  readonly highlight: {
+    readonly args: "<color>";
+    readonly emit: (v: string) => [string, string][];
+  };
+}, {}>;
+//#endregion

package/dist/index.mjs

@@ -0,0 +1,58 @@
+import { scope } from "cssints/plugin";
+//#region src/index.ts
+const BASE = "color-mix(in oklab, currentColor 12%, transparent)";
+const HIGHLIGHT = "color-mix(in oklab, currentColor 4%, transparent)";
+const GREY = "rgb(128 128 128 / 20%)";
+const GREY_HIGHLIGHT = "rgb(128 128 128 / 8%)";
+const gradient = (base, highlight) => `linear-gradient(90deg, var(--_c, ${base}) 40%, var(--_h, ${highlight}) 50%, var(--_c, ${base}) 60%)`;
+/**
+* `skeleton().radius("8px").color("#ddd").highlight("#eee")`: a loading placeholder, each method once and optional
+* (`0.25rem`, the text colour at 12% and 4%). The shimmer of every skeleton on the page is one animation on `:root`, so
+* they are in phase whenever each was mounted; under `prefers-reduced-motion: reduce` it is the base colour, still. It
+* sets the background and the corners, so a `background*` or `border-radius*` property in the same `cn()` is a build
+* error.
+*/
+const { skeleton } = scope("skeleton", {
+	core: { css: (css) => [
+		css.borderRadius("var(--_r, 0.25rem)"),
+		css.backgroundImage(gradient(BASE, HIGHLIGHT)),
+		css.backgroundSize("300% 100%"),
+		css.backgroundPosition("var(--_p) 0"),
+		css.backgroundAttachment("fixed")
+	] },
+	clock: {
+		css: (css) => css.media("(prefers-reduced-motion: no-preference)")(css.nest(":root:has(&)")(css.animation(css.keyframes({
+			from: css.vars({ "--_p": "100%" }),
+			to: css.vars({ "--_p": "0%" })
+		}), "1.5s ease-in-out infinite"))),
+		atProperty: "@property --_p{syntax:\"<percentage>\";inherits:true;initial-value:100%}",
+		requires: ["css.at-rules.property", "css.selectors.has"]
+	},
+	"#grey": {
+		polyfills: ["css.types.color.color-mix", "css.types.color.oklab"],
+		css: `@supports not (color:color-mix(in oklab,red,red)){&{background-image:${gradient(GREY, GREY_HIGHLIGHT)}}}`
+	},
+	skeleton: {
+		uses: [
+			"core",
+			"clock",
+			"grey"
+		],
+		chain: {
+			radius: {
+				args: "<length-percentage [0,∞]>",
+				emit: (v) => [["--_r", v]]
+			},
+			color: {
+				args: "<color>",
+				emit: (v) => [["--_c", v]]
+			},
+			highlight: {
+				args: "<color>",
+				emit: (v) => [["--_h", v]]
+			}
+		}
+	}
+}).export();
+//#endregion
+export { skeleton };

package/package.json

@@ -1,6 +1,32 @@
 {
   "name": "@cssints/skeleton",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Skeleton loaders for cssints whose shimmer is in phase across the page: one animation on :root, read by every skeleton",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/alexeiaccio/css-in-ts-compiler.git",
+    "directory": "packages/skeleton"
+  },
+  "homepage": "https://cssints.dev",
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "peerDependencies": {
+    "cssints": "^0.1.0"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}