cssints 0.28.0 → 0.29.0

package/docs/API.md

@@ -1792,6 +1792,7 @@ createPanZoom(options?: {
   zoomIn(): void;
   zoomOut(): void;
   setScale(scale: number, origin?: { x: number; y: number }): void; // origin in the viewport's own space, its centre by default
+  panBy(dx: number, dy: number): void; // a relative pan through the same clamp as a drag; a host's glide uses this
   viewportProps: {
     tabindex: 0;
     role: "group";
@@ -1814,7 +1815,7 @@ createPanZoom(options?: {
 
 Wheel zooms **only with `ctrl` / `meta`** held: the browser's pinch gesture arrives that way, and a bare wheel is left to the page so trackpad scrolling still works — a swallowed wheel is never acceptable. Arrows pan the image with the arrow (like a drag), and with `bounds: "clamp"` they are inert at `min`, where there is nothing to reveal. The clamp bounds the offset by half the viewport's scaled overflow, so the image is expected to fill the viewport at `min` (`width: 100%; height: 100%` / `object-fit: cover`); a letterboxed image cannot be held gap-free, and `bounds: "free"` lets it be dragged out of view instead. `valueProps` carries no `hidden` — a `hidden` live region is not announced — so the host hides it visually.
 
-The host owns the box and the look: the viewport's size and `overflow: hidden`, `touch-action: none` if a touch drag should pan, `transform-origin: 50% 50%` (the default this maths assumes), and any transition on the transform. Controlled is `scale` + `onScaleChange`; the offset has no controlled prop, so a host that ignores a scale request also gets the offset resolved for the scale it refused. Not modelled: inertia, rotation, and pinching on platforms without `PointerEvent` (the browser's own pinch is the `ctrl+wheel` path).
+The host owns the box and the look: the viewport's size and `overflow: hidden`, `touch-action: none` if a touch drag should pan, `transform-origin: 50% 50%` (the default this maths assumes), and any transition on the transform. Controlled is `scale` + `onScaleChange`; the offset has no controlled prop, so a host that ignores a scale request also gets the offset resolved for the scale it refused. A host that moves the pan without a pointer calls `panBy(dx, dy)`: it takes the same bounded `move` as a drag, so the clamp and `onPanChange` hold for an inertial glide and a drag alike (the kit's `Panzoom` glides after a flick this way). Not modelled: rotation, and pinching on platforms without `PointerEvent` (the browser's own pinch is the `ctrl+wheel` path).
 
 ### Headless: `createMenu` (`@cssints/headless`)
 
@@ -3930,6 +3931,54 @@ createPlayer(options: {
   slider does not mirror its arrows under RTL — a time axis does not flip, a deliberate divergence
   from `slider.qnt`.
 
+### Stories: `@cssints/stories` (decided 2026-11-02)
+
+The CSF 3 loader of a storybook, with no DOM, no styles and no chrome: the modules an app globs in, the entries with the ids
+Storybook builds out, and the controls a story declares. It serves the starters' site, the reactive lab and (the reason it is
+a package rather than two copies) a native window.
+
+```ts skip
+// src/registry/button/button.stories.tsx — a Storybook CSF 3 file, unchanged
+import type { Meta, Story } from "@cssints/stories";
+import { Button, type ButtonProps } from "./button.tsx";
+
+const meta = {
+  title: "Button",
+  component: Button,
+  args: { children: "Save", tone: "neutral" },
+  argTypes: {
+    tone: { type: "select", options: ["neutral", "accent", "quiet"] },
+    disabled: { type: "boolean" },
+  },
+} satisfies Meta<ButtonProps>;
+export default meta;
+
+export const Default: Story<ButtonProps> = {};
+export const Publish: Story<ButtonProps> = { args: { tone: "accent", children: "Publish" } };
+```
+
+```ts skip
+import { entries, parseHash, storyOfId, type Module } from "@cssints/stories";
+
+const modules = import.meta.glob<Module>("../registry/*/*.stories.tsx", { eager: true });
+const stories = entries(modules); // [{ id: "button--default", item: "button", view, args, argTypes, … }]
+```
+
+- **`entries(modules, itemOf?)`** returns `Entry[]`: `id` (`button--publish`, the item's name and the story's,
+  kebab-cased), `item` (the story file's directory, or whatever `itemOf` reads from the path), `title`, `name`, `args` (the
+  meta's with the story's over them), `argTypes`, and `view(args)` — the meta's `component` called through
+  `createComponent`, or the story's own `render`. Entries are sorted by item and then by id; within a file the module
+  namespace's order is what Storybook lists.
+- **`storyOfId(stories, id)`** finds one entry, and **`parseHash(hash)`** splits `#button--publish` into the page
+  (`button`) and the story, so an app's hash is a link to a story.
+- **`argTypes`** is the controls model: `{ type: "boolean" }`, `{ type: "select", options }`, `{ type: "text" }`,
+  `{ type: "number", min?, max?, step? }`, `{ type: "range", min, max, step? }`. Storybook infers a control from a
+  component's props; a Solid component carries none at run time, so a story declares what it wants. **The panel is the
+  app's**: the site draws it on the kit's `Field`, `Select`, `Switch` and `Slider`, and a story with no `argTypes` gets no
+  panel.
+- **`Node`** is a type parameter: `entries<JSX.Element>(modules)` on the web, `entries<NativeNode>(modules)` in
+  `cssints-native`, and the package never names a renderer. `solid-js` is a peer (for `createComponent` alone).
+
 ### Publishing a library (decided 2026-10-02, cssints-0l3f)
 
 A package written on cssints ships JavaScript that still has the attribute, and its `.d.ts`. The app that installs it evaluates the package with its own engine: one sheet, the app's browserslist and themes, and a token, a kernel or an `@property` of the package is made once however many modules use it. Nothing is declared: the engine recognises a file by `with { type: "cssints" }`, the same marker as in app code.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cssints",
-  "version": "0.28.0",
+  "version": "0.29.0",
   "description": "CSS in TypeScript: typed css.* calls compiled to atomic CSS at build time (a Vite plugin)",
   "license": "MIT",
   "repository": {
@@ -72,7 +72,7 @@
     }
   },
   "dependencies": {
-    "@cssints/css-grammar": "^0.28.0",
+    "@cssints/css-grammar": "^0.29.0",
     "culori": "^4.0.2",
     "effect": "4.0.6",
     "happy-dom": "^20.14.5",