@cssints/stuck 0.0.0-stage → 0.2.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,101 @@
-# Temporary Holding Version
+# @cssints/stuck
 
-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.
+Style what is inside a sticky element while it is stuck, for [cssints](../../README.md): `sticky()` makes an element
+sticky and a scroll-state container, `stuck(...)` wraps styles of its descendants in
+`@container scroll-state(stuck: top)` (Chrome 133). Where a target lacks scroll-state queries, `stuck(...)` also emits
+the same styles under an attribute that a tiny IntersectionObserver sets, in the way of
+[bramus/sticky-observer](https://github.com/bramus/sticky-observer).
+
+```ts
+import { cn, color, hover } from "cssints" with { type: "cssints" };
+import { sticky, stuck } from "@cssints/stuck" with { type: "cssints" };
+
+export const header = sticky().top("0"); // <header class={header}>
+export const title = cn(color("gray"), stuck(color("red"))); //   <h1 class={title}>
+export const footer = sticky().bottom(2);
+export const link = stuck("bottom")(color("green"), hover(color("black")));
+```
+
+```css
+@layer _.k {
+  ._stuck-core {
+    position: sticky;
+    container-type: scroll-state;
+  }
+}
+@layer _.a {
+  ._4k81c2 {
+    top: 0;
+  }
+  ._kg6w97 {
+    bottom: 0.5rem;
+  }
+}
+@layer _.b {
+  @container scroll-state(stuck: top) {
+    ._it4l7h {
+      color: red;
+    }
+  }
+  /* only when a browserslist target lacks scroll-state queries */
+  :where(._g-stuck[data-stuck~="top"]) ._fec935 {
+    color: red;
+  }
+}
+```
+
+`header` is `_stuck-core _g-stuck _4k81c2`, `title` holds both `_it4l7h` and `_fec935`.
+
+## Browsers
+
+- **Native**: `@container scroll-state()` and `container-type: scroll-state`, Chrome and Edge 133. Not in Firefox or
+  Safari yet.
+- **Fallback**: `@cssints/stuck/observer` (about 1.3 kB minified, no imports) sets `data-stuck="top"` (a list of the
+  stuck edges) on each `sticky()` element while it is stuck, and the fallback rules read it. It checks
+  `CSS.supports("container-type", "scroll-state")` first and does nothing where the browser has the queries. Nothing to
+  import by hand: the runtime entry names it (`script`), so the module that uses `sticky()` imports it through
+  `virtual:cssints/runtime/stuck.observer` when a target lacks the queries; that module is empty when none does.
+- The fallback rules are in the sheet only when a browserslist target lacks the queries (`chrome 133` alone gets the
+  `@container` rules only): `stuck()` asks `lacking()` of `cssints/plugin`, the same query and rules as the support
+  warnings. The kernel's support warnings (its `requires`, the queries, and its declaration
+  `container-type: scroll-state`) are covered by the observer, so a build for the default targets prints none.
+- Checked in Chrome (native, and the observer with the queries cut out), Firefox and WebKit (the observer):
+  `bun run test:browsers`.
+
+## Rules
+
+- **`sticky()`** is `position: sticky` and `container-type: scroll-state`, with methods for the insets, each once, in any
+  order: `top()`, `right()`, `bottom()`, `left()`, a `<length-percentage>` (a lone number is a spacing step, 0.25rem).
+  Its class list also holds `_g-stuck`, the group marker the fallback rules read.
+- **`stuck(...styles)`** applies the styles while the nearest `sticky()` ancestor is stuck to its top edge;
+  `stuck(side)(...styles)` to `top`, `right`, `bottom` or `left`. It is a condition: it counts as one (layer `_.b`),
+  wraps others (`stuck(hover(...))`) and goes inside them.
+- **Descendants only.** A scroll-state query matches the descendants of the container, never the container itself (the
+  spec's rule), so `stuck()` styles go on an element inside the sticky one. To style the sticky box itself, put an inner
+  wrapper in it.
+- **Conflicts.** `sticky()` sets `position` and `container-type`: one `cn()` with `position`, `container` or
+  `container-type` is a build error, derived from the kernel (written as styles): `cssints: stuck: kernel core sets
+position, container-type (this style also sets position)`.
+- **Errors**: a bad inset is the grammar's, in the types and at build time (`sticky.top: unexpected "red" in "red",
+expected <length-percentage>`), a method twice is `cssints: sticky().top() is used twice`, and an unknown side is a type
+  error and `cssints: stuck: stuck() takes top, right, bottom or left, got "middle"`. Each points at the call.
+
+## Limits
+
+- **The fallback reads the insets once**, when it first sees the element: an inset that a media query changes later is
+  not followed. A sticky element taller than its scroll container is not reported stuck. Shadow roots are not crossed.
+- The fallback's root is the nearest ancestor whose `overflow` is not `visible`, else the viewport; the native query
+  follows the real scroll container.
+- No logical sides (`block-start`, `inline-end`), and no `scrollable` or `snapped` scroll-state queries.
+
+```bash
+cd packages/stuck && bun run test            # fixtures through the engine (output, targets, errors, observer size)
+cd packages/stuck && bun run typecheck       # the type test
+cd packages/stuck && bun run test:browsers   # Chrome, Firefox and WebKit through playwright-core
+```
+
+## Credits
+
+The fallback follows [bramus/sticky-observer](https://github.com/bramus/sticky-observer) (MIT, Bramus Van Damme): an
+IntersectionObserver whose root is shrunk by the element's inset plus 1px. The observer is written here; no code is
+copied.

package/dist/index.d.mts

@@ -0,0 +1,82 @@
+import { Style, Wrap } from "cssints";
+//#region src/index.d.ts
+/** An edge a sticky element sticks to. */
+export type Side = "top" | "right" | "bottom" | "left";
+/** The scope of `sticky()`, for a scope that embeds it (its kernel `core`). */
+export declare const stuckScope: import("cssints/plugin").Scope<"stuck", {
+  readonly "#core": {
+    readonly css: (css: import("cssints/plugin").Css) => Style[];
+    readonly requires: ["css.at-rules.container.scroll-state_queries"];
+  };
+  readonly "#observer": {
+    readonly polyfills: ["css.at-rules.container.scroll-state_queries", "css.properties.container-type.scroll-state"];
+    readonly script: "@cssints/stuck/observer";
+  };
+  readonly sticky: {
+    readonly uses: readonly ["core", "observer"];
+    readonly group: true;
+    readonly chain: {
+      readonly top: {
+        args: "<length-percentage>";
+        spacing: true;
+        emit: (v: string) => (readonly [Side, string])[];
+      };
+      readonly right: {
+        args: "<length-percentage>";
+        spacing: true;
+        emit: (v: string) => (readonly [Side, string])[];
+      };
+      readonly bottom: {
+        args: "<length-percentage>";
+        spacing: true;
+        emit: (v: string) => (readonly [Side, string])[];
+      };
+      readonly left: {
+        args: "<length-percentage>";
+        spacing: true;
+        emit: (v: string) => (readonly [Side, string])[];
+      };
+    };
+  };
+}>;
+/**
+ * `sticky().top("0")`: `position: sticky`, `container-type: scroll-state` and the insets of its methods (each once, a
+ * `<length-percentage>`, a lone number a spacing step). Its descendants take `stuck(...)` styles. It sets `position`
+ * and `container-type`, so those in the same `cn()` are a build error.
+ */
+export declare const sticky: () => import("cssints/plugin").Chain<"sticky", {
+  readonly top: {
+    args: "<length-percentage>";
+    spacing: true;
+    emit: (v: string) => (readonly [Side, string])[];
+  };
+  readonly right: {
+    args: "<length-percentage>";
+    spacing: true;
+    emit: (v: string) => (readonly [Side, string])[];
+  };
+  readonly bottom: {
+    args: "<length-percentage>";
+    spacing: true;
+    emit: (v: string) => (readonly [Side, string])[];
+  };
+  readonly left: {
+    args: "<length-percentage>";
+    spacing: true;
+    emit: (v: string) => (readonly [Side, string])[];
+  };
+}, {}>;
+/** The styles of a descendant of `sticky()` while it is stuck: to the top edge, or to the side given. */
+export interface Stuck {
+  /** `stuck("bottom")(color("red"))`: while the sticky ancestor is stuck to that edge. */
+  (side: Side): Wrap;
+  /** `stuck(color("red"))`: while the sticky ancestor is stuck to the top edge. */
+  (...styles: Style[]): Style;
+}
+/**
+ * Styles of a descendant of `sticky()` while the sticky element is stuck: `stuck(...styles)` (top) or `stuck(side)(...styles)`.
+ *
+ * @returns {Style | Wrap} the styles under the condition, or the condition of that side
+ */
+export declare const stuck: Stuck;
+//#endregion

package/dist/index.mjs

@@ -0,0 +1,57 @@
+import { attr, cn, container, within } from "cssints" with { type: "cssints" };
+import { lacking, scope } from "cssints/plugin";
+//#region src/index.ts
+const SIDES = [
+	"top",
+	"right",
+	"bottom",
+	"left"
+];
+const QUERIES = "css.at-rules.container.scroll-state_queries";
+const inset = (side) => ({
+	args: "<length-percentage>",
+	spacing: true,
+	emit: (v) => [[side, v]]
+});
+/** The scope of `sticky()`, for a scope that embeds it (its kernel `core`). */
+const stuckScope = scope("stuck", {
+	"#core": {
+		css: (css) => [css.position("sticky"), css.containerType("scroll-state")],
+		requires: [QUERIES]
+	},
+	"#observer": {
+		polyfills: [QUERIES, "css.properties.container-type.scroll-state"],
+		script: "@cssints/stuck/observer"
+	},
+	sticky: {
+		uses: ["core", "observer"],
+		group: true,
+		chain: {
+			top: inset("top"),
+			right: inset("right"),
+			bottom: inset("bottom"),
+			left: inset("left")
+		}
+	}
+});
+/**
+* `sticky().top("0")`: `position: sticky`, `container-type: scroll-state` and the insets of its methods (each once, a
+* `<length-percentage>`, a lone number a spacing step). Its descendants take `stuck(...)` styles. It sets `position`
+* and `container-type`, so those in the same `cn()` are a build error.
+*/
+const { sticky } = stuckScope.export();
+const fallback = lacking(QUERIES).length > 0;
+const under = (side) => (...styles) => cn(container(`scroll-state(stuck: ${side})`)(...styles), ...fallback ? [within(attr("data-stuck", side, "~="), "stuck")(...styles)] : []);
+/**
+* Styles of a descendant of `sticky()` while the sticky element is stuck: `stuck(...styles)` (top) or `stuck(side)(...styles)`.
+*
+* @returns {Style | Wrap} the styles under the condition, or the condition of that side
+*/
+const stuck = ((...args) => {
+	const [side] = args;
+	if (typeof side !== "string") return under("top")(...args);
+	if (SIDES.includes(side)) return under(side);
+	throw new Error(`cssints: stuck: stuck() takes top, right, bottom or left, got "${side}"`);
+});
+//#endregion
+export { sticky, stuck, stuckScope };

package/dist/observer.d.mts

@@ -0,0 +1 @@
+export {}

package/dist/observer.mjs

@@ -0,0 +1,53 @@
+//#region src/observer.ts
+const SIDES = [
+	"top",
+	"right",
+	"bottom",
+	"left"
+];
+const watched = /* @__PURE__ */ new Map();
+const scroller = (el) => {
+	const up = [el];
+	while (up.at(-1).parentElement) up.push(up.at(-1).parentElement);
+	return up.slice(1, -2).find((p) => /auto|scroll|hidden|overlay/.test(getComputedStyle(p).overflow)) ?? null;
+};
+const watch = (el) => {
+	const s = getComputedStyle(el);
+	const insets = SIDES.map((k) => s[k]);
+	const io = new IntersectionObserver(([e]) => {
+		const r = e.boundingClientRect;
+		const b = e.rootBounds;
+		const past = b && [
+			r.top < b.top,
+			r.right > b.right,
+			r.bottom > b.bottom,
+			r.left < b.left
+		];
+		const on = SIDES.filter((_, i) => e.isIntersecting && past?.[i] && insets[i] !== "auto");
+		if (on.length) el.setAttribute("data-stuck", on.join(" "));
+		else el.removeAttribute("data-stuck");
+	}, {
+		root: scroller(el),
+		rootMargin: insets.map((v) => v === "auto" ? "0px" : `${-1 - parseFloat(v)}px`).join(" "),
+		threshold: [0, 1]
+	});
+	io.observe(el);
+	watched.set(el, io);
+};
+const scan = () => {
+	for (const [el, io] of watched) if (!el.isConnected || !el.classList.contains("_stuck-core")) {
+		io.disconnect();
+		watched.delete(el);
+		el.removeAttribute("data-stuck");
+	}
+	for (const el of document.querySelectorAll("._stuck-core")) if (!watched.has(el)) watch(el);
+};
+if (typeof document !== "undefined" && !CSS.supports("container-type", "scroll-state")) {
+	scan();
+	new MutationObserver(scan).observe(document.documentElement, {
+		subtree: true,
+		childList: true,
+		attributeFilter: ["class"]
+	});
+}
+//#endregion

package/package.json

@@ -1,6 +1,40 @@
 {
   "name": "@cssints/stuck",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Style a sticky element while it is stuck: @container scroll-state(stuck) natively, an IntersectionObserver fallback",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/alexeiaccio/css-in-ts-compiler.git",
+    "directory": "packages/stuck"
+  },
+  "homepage": "https://cssints.dev",
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": [
+    "./src/observer.ts",
+    "./dist/observer.mjs",
+    "./test/fixtures/*"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    },
+    "./observer": {
+      "types": "./dist/observer.d.mts",
+      "default": "./dist/observer.mjs"
+    }
+  },
+  "peerDependencies": {
+    "cssints": "^0.2.0"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}