stablekit.ts 0.2.0

package/llms.txt

@@ -0,0 +1,463 @@
+# stablekit — Instructions for AI Code Generators
+
+You are working with `stablekit`, a React library that enforces a strict
+rendering paradigm: **Deterministic Geometric Pre-allocation.**
+
+Read these instructions before generating any code that imports from `stablekit`.
+They override your default React patterns.
+
+## The Paradigm
+
+Standard React couples paint and geometry — when state changes, the DOM
+reflows. StableKit decouples them. The rule:
+
+> A container's dimensions must be a function of its maximum possible
+> future state, not its current instantaneous state.
+
+This means:
+- **Temporal pre-allocation:** If a component depends on async data, its
+  bounding box must be declared synchronously before the data arrives.
+  (`MediaSkeleton` forces `aspectRatio`, `CollectionSkeleton` forces
+  `stubCount`, `StableText` reserves space at line-height.)
+- **Spatial pre-allocation:** If a UI region has multiple states, all
+  states must render simultaneously in a CSS grid overlap. The container
+  sizes to the largest. (`LayoutMap`, `LayoutGroup`, `StateSwap`)
+- **Monotonic geometry:** Once a container expands, it cannot shrink
+  unless explicitly reset. (`SizeRatchet` with optional `resetKey`)
+- **Structural Integrity over Temporal Hacks:** Never unmount a state
+  to show another. Stack all possible states in the DOM and use CSS
+  `opacity`/`visibility` to transition between them. Conditional
+  mounting (`{loading ? <A/> : <B/>}`) is a fatal architectural error
+  in StableKit. All layers coexist permanently; only opacity and
+  interactivity (`inert`, `pointer-events`) change. LayoutView exposes
+  a `data-state="active"|"inactive"` attribute — consumers can target
+  `.sk-layout-view[data-state]` selectors to add CSS transitions for
+  custom enter/exit animations without specificity fights.
+
+When you generate code with StableKit, you are not adding progressive
+enhancement to existing React patterns. You are replacing the rendering
+model. Do not mix StableKit components with ternary-based conditional
+rendering for the same UI region.
+
+## Component API
+
+| Component            | Paradigm               | Purpose                                      |
+|----------------------|------------------------|----------------------------------------------|
+| `StateSwap`          | Spatial                | Boolean content swap, zero shift             |
+| `LayoutGroup`        | Spatial                | Multi-state spatial stability container       |
+| `LayoutView`         | Spatial                | Single view inside a LayoutGroup             |
+| `LayoutMap`          | Spatial                | Dictionary-based state mapping (typo-proof)  |
+| `StableCounter`      | Spatial                | Numeric/text width pre-allocation            |
+| `StableField`        | Spatial                | Form error height pre-allocation             |
+| `SizeRatchet`        | Monotonic              | Container that never shrinks                 |
+| `LoadingBoundary`    | All three              | Loading orchestrator (shimmer + ratchet)     |
+| `LoadingContext`     | Temporal               | Ambient loading provider                     |
+| `StableText`         | Temporal               | Typography + skeleton in one tag             |
+| `TextSkeleton`       | Temporal               | Inline loading shimmer for text              |
+| `MediaSkeleton`      | Temporal               | Aspect-ratio media placeholder               |
+| `CollectionSkeleton` | Temporal + Monotonic   | Loading-aware list                           |
+| `FadeTransition`     | Animation              | Enter/exit animation wrapper                 |
+| `createPrimitive`    | Enforcement            | Factory for firewalled UI primitives         |
+
+## Anti-patterns you must not generate
+
+### 1. Do not use ternaries to swap content when layout stability matters
+
+WRONG — geometry changes when state changes:
+```tsx
+{isLoading ? <Spinner /> : <Profile user={user} />}
+```
+
+CORRECT — one tree, geometry pre-allocated:
+```tsx
+<LoadingBoundary loading={isLoading} exitDuration={150}>
+  <StableText as="h2">{user.name}</StableText>
+</LoadingBoundary>
+```
+
+### 2. Do not use fixed CSS widths to prevent layout shift
+
+WRONG — using Tailwind fixed width to stabilize a button:
+```tsx
+<button className="w-28">{expanded ? "Close" : "View Details"}</button>
+```
+
+CORRECT — use StateSwap inside the button:
+```tsx
+<button onClick={toggle}>
+  <StateSwap state={expanded} true="Close" false="View Details" />
+</button>
+```
+
+StateSwap renders as an inline `<span>` by default. It is safe inside
+buttons, table cells, and any inline context.
+
+### 3. Do not swap text with a ternary when layout stability matters
+
+WRONG — conditional text causes the container to resize:
+```tsx
+<span>{isOpen ? "Collapse" : "Expand"}</span>
+```
+
+CORRECT — StateSwap reserves the width of the wider option:
+```tsx
+<StateSwap state={isOpen} true="Collapse" false="Expand" />
+```
+
+### 4. Do not duplicate entire components to swap between states
+
+WRONG — two separate buttons wrapped in LayoutView:
+```tsx
+<LayoutGroup value={expanded ? "close" : "view"}>
+  <LayoutView name="view"><button>View Details</button></LayoutView>
+  <LayoutView name="close"><button>Close</button></LayoutView>
+</LayoutGroup>
+```
+
+CORRECT — one button, swap content inside it:
+```tsx
+<button onClick={toggle}>
+  <StateSwap state={expanded} true="Close" false="View Details" />
+  <StateSwap state={expanded} true={<ChevronUp />} false={<ChevronDown />} />
+</button>
+```
+
+Use LayoutGroup/LayoutView only when swapping structurally different
+components (e.g. tab panels, multi-step forms).
+
+### 5. Do not use LayoutGroup/LayoutView for tab content — use LayoutMap
+
+WRONG — string typos silently break rendering:
+```tsx
+<LayoutGroup value={activeTab}>
+  <LayoutView name="profile"><Profile /></LayoutView>
+  <LayoutView name="inovices"><Invoices /></LayoutView>
+</LayoutGroup>
+```
+
+CORRECT — dictionary keys are checked by TypeScript:
+```tsx
+<LayoutMap value={activeTab} map={{
+  profile: <Profile />,
+  invoices: <Invoices />,
+}} />
+```
+
+### 6. Do not wrap text in TextSkeleton inside HTML tags — use StableText
+
+WRONG — easy to forget the skeleton wrapper:
+```tsx
+<p className="text-xl font-semibold">
+  <TextSkeleton>{user.name}</TextSkeleton>
+</p>
+```
+
+CORRECT — the tag IS the skeleton:
+```tsx
+<StableText as="p" className="text-xl font-semibold">{user.name}</StableText>
+```
+
+### 7. Do not add dimension classes to children inside MediaSkeleton
+
+WRONG — relying on developer to constrain the image:
+```tsx
+<MediaSkeleton aspectRatio={1}>
+  <img src={url} className="w-full h-full object-cover" />
+</MediaSkeleton>
+```
+
+CORRECT — MediaSkeleton enforces child constraints automatically:
+```tsx
+<MediaSkeleton aspectRatio={1}>
+  <img src={url} alt={name} />
+</MediaSkeleton>
+```
+
+MediaSkeleton uses React.cloneElement to apply position, size, and
+object-fit as inline styles. The child cannot break out of the frame.
+
+### 8. Do not use fixed widths to stabilize changing numbers — use StableCounter
+
+WRONG — hardcoded width that breaks with different values:
+```tsx
+<span className="w-16 text-right">{cartCount}</span>
+```
+
+CORRECT — ghost reserve pre-allocates the width:
+```tsx
+<StableCounter value={cartCount} reserve="999" />
+```
+
+StableCounter uses CSS Grid overlap: a hidden `reserve` node props open
+the bounding box, and the visible `value` renders on top. Both require a
+`reserve` prop — there is no auto-detection. The developer must declare
+the maximum expected content.
+
+### 9. Do not let form validation errors cause vertical layout shift — use StableField
+
+WRONG — error message pops in and pushes fields down:
+```tsx
+<div>
+  <input type="email" />
+  {errors.email && <p className="text-red-500">{errors.email}</p>}
+</div>
+```
+
+CORRECT — error slot height is pre-allocated:
+```tsx
+<StableField error={errors.email} reserve="Please enter a valid email address">
+  <input type="email" />
+</StableField>
+```
+
+StableField uses the same CSS Grid overlap physics as StableCounter,
+applied vertically. A hidden `reserve` node permanently holds the error
+slot open. The actual error message renders on top when present. The
+field container never changes height. Both require a `reserve` prop.
+
+### 10. Do not use CSS !important to enforce layout constraints
+
+WRONG — global CSS !important in a library pollutes the consumer's cascade:
+```css
+.my-frame > * { width: 100% !important; height: 100% !important; }
+```
+
+CORRECT — enforce constraints at the React component layer:
+```tsx
+React.cloneElement(child, {
+  style: { position: "absolute", inset: 0, width: "100%", height: "100%" }
+})
+```
+
+When you need to enforce rigid layout physics, always operate at the React
+layer (cloneElement, inline styles, context) — never at the CSS layer.
+
+### 11. Do not hand-write UI primitives — use createPrimitive
+
+WRONG — manual boilerplate, easy to forget the Omit firewall:
+```tsx
+interface BadgeProps extends Omit<HTMLAttributes<HTMLSpanElement>, "className" | "style"> {
+  variant: Status;
+}
+export function Badge({ variant, children, ...props }: BadgeProps) {
+  return <span className="sk-badge" data-variant={variant} {...props}>{children}</span>;
+}
+```
+
+CORRECT — factory handles the firewall automatically:
+```tsx
+import { createPrimitive } from "stablekit";
+export const Badge = createPrimitive("span", "sk-badge", {
+  variant: ["active", "trial", "churned"],
+});
+```
+
+`createPrimitive` blocks `className` and `style` at the type level, maps
+variant props to `data-*` attributes, and type-checks variant values. The
+consumer writes `variant="active"`, the DOM gets `data-variant="active"`,
+and CSS selects on it. The firewall is automatic — you cannot forget it.
+
+## The StableKit Separation of Concerns
+
+The codebase enforces four layers with a strict one-directional dependency
+flow. Each layer answers exactly one question.
+
+```
+Data → Contract → Structure → Presentation
+```
+
+| # | Layer | Question | Knows about | Never knows about |
+|---|-------|----------|-------------|-------------------|
+| 1 | Data | What is the value? | Nothing — raw payload | Structure, appearance, types |
+| 2 | Contract | What values are valid? | Allowed value sets | Structure, appearance, data source |
+| 3 | Structure | What is the DOM? | Contract (via props), class names, data-attributes | Appearance, data source |
+| 4 | Presentation | What does it look like? | Class names, data-attributes | Data source, React, TypeScript |
+
+Each layer depends only on the one to its left. Presentation never imports
+TypeScript. Structure never fetches data. Contract never references a CSS class.
+
+**Litmus test:** if a change to appearance requires editing a `.tsx` file, or a
+change to structure requires editing `.css`, a boundary has leaked.
+
+### Enforcement
+
+- **Data → Contract:** TypeScript compiler. If the API returns a value outside
+  the union type, it is a compile error.
+- **Contract → Structure:** TypeScript compiler. Component props reference the
+  contract type (`variant: Status`), so invalid values are compile errors.
+- **Structure → Presentation:** Four mechanisms:
+  1. `createPrimitive` blocks `className` and `style` at the type level,
+     preventing consumers from injecting appearance at the Structure layer.
+  2. CSS uses `[data-variant="..."]` attribute selectors to map contract values
+     to visual styles.
+  3. **ESLint** (`stablekit/eslint`) — `createArchitectureLint({ stateTokens, variantProps, banColorUtilities })`
+     bans data-dependent visual properties in JS (state tokens like
+     `text-success`, conditional style ternaries), hardcoded visual values
+     (bare hex colors like `"#f0c040"`, color functions like `rgba()`, `hsl()`,
+     `oklch()`), color properties in style props (`style={{ color: x }}`),
+     visual state properties in style props (`style={{ opacity, visibility,
+     transition, pointerEvents }}`), className ternaries
+     (`className={x ? "a" : "b"}`), className logical AND
+     (`className={cn("base", x && "bold")}`), className object syntax
+     (`cx({ class: condition })`), `!important` in className, hardcoded
+     z-index (`z-[999]`), negative margins (`m-[-4px]`), hardcoded pixel
+     dimensions (`w-[347px]`), and all arbitrary magic numbers in Tailwind
+     bracket syntax. `banColorUtilities` (default: true) bans ALL Tailwind
+     palette color utilities in className (`bg-red-500`, `text-green-600`,
+     `border-cyan-400`, etc.) — colors must live in CSS, not in component
+     classNames. `stateTokens` declares your project's functional color
+     vocabulary. `variantProps` declares prop names from `createPrimitive` —
+     bans ternaries like `intent={x ? "primary" : "outline"}`.
+     The linter also enforces geometric stability by banning all conditional
+     content in JSX children: ternary swaps (`{x ? <A/> : <B/>}`), conditional
+     mounting (`{x && <Panel/>}`), fallback content (`{x || "default"}`),
+     nullish fallbacks (`{x ?? "loading"}`), and interpolated template literals
+     (`` {`text ${var}`} ``). Each error message guides toward the right fix:
+     extract the expression to a variable above the JSX (for data transforms),
+     or use a StableKit component (for state-driven swaps — StateSwap,
+     LayoutMap, LoadingBoundary, FadeTransition, StableField, StableCounter,
+     LayoutGroup). These rules are always on.
+  4. **Stylelint** (`stablekit/stylelint`) — `createStyleLint({ functionalTokens })`
+     bans element selectors in CSS (`& svg`, `& span`), bans `!important`, and
+     bans functional color tokens inside `@utility` blocks. `functionalTokens`
+     declares CSS custom property prefixes (e.g. `["--color-status-"]`) that must
+     not appear in `@utility` — they belong in scoped selectors only.
+     Run `npx eslint src/components/` and `npx stylelint "src/**/*.css"` before
+     committing. Zero errors is the requirement — do not add disable comments.
+
+### Example: Badge
+
+```ts
+// Layer 2 — Contract (types.ts)
+export type Status = "active" | "trial" | "churned";
+```
+
+```tsx
+// Layer 3 — Structure (badge.tsx)
+// className and style are Omit'd — consumers cannot inject appearance
+<span className="sk-badge" data-variant={variant}>{children}</span>
+```
+
+```css
+/* Layer 4 — Presentation (index.css) */
+.sk-badge[data-variant="active"] { color: var(--color-success); }
+```
+
+## Internal Contribution Rules
+
+Never write raw `process.env.NODE_ENV` checks in components. Always import
+and use `invariant` or `warning` from `src/internal/invariant.ts`.
+
+```ts
+// WRONG — raw environment check in a component
+if (process.env.NODE_ENV !== "production") {
+  throw new Error("bad usage");
+}
+
+// CORRECT — declarative assertion
+import { invariant } from "../internal/invariant";
+invariant(someCondition, "Explanation of what went wrong.");
+```
+
+`invariant(condition, message)` throws a fatal error in development and is
+stripped entirely in production. `warning(condition, message)` emits a
+console.warn in development and is stripped entirely in production.
+
+### Banned Pattern: Logic Leakage
+
+Never store CSS classes, Tailwind strings, or styling logic in data files or
+non-UI modules. Data exports raw values only. Visual mapping belongs in CSS
+(via class or attribute selectors) or in dumb UI primitives that accept a
+semantic `variant` prop and map it to a class name.
+
+```ts
+// WRONG — data file contains Tailwind classes
+export const statusColors = {
+  active: "bg-green-100 text-green-800 border-green-300",
+};
+
+// WRONG — component maps data to inline Tailwind
+<span className={statusColors[status]}>{status}</span>
+
+// CORRECT — dumb component, semantic variant
+<Badge variant={status}>{status}</Badge>
+
+// CORRECT — CSS owns the visual mapping
+.sk-badge[data-variant="active"] { color: var(--color-success); ... }
+```
+
+If changing a color requires editing a `.ts` file, the architecture is broken.
+
+### Banned Pattern: Class Concatenation for Mutually Exclusive States
+
+Never use CSS class concatenation for mutually exclusive component states or
+variants (e.g., `primary`/`secondary`, `active`/`trial`/`churned`). A DOM node
+can accidentally receive two conflicting classes
+(`class="sk-badge-active sk-badge-churned"`), but it can only ever have one
+value for a given data-attribute (`data-variant="active"`).
+
+Classes define **what** a component is. Data-attributes define **how** it is
+currently behaving.
+
+```tsx
+// WRONG — class concatenation for variants
+<span className={`sk-badge sk-badge-${variant}`}>{children}</span>
+
+// CORRECT — base class + data-attribute
+<span className="sk-badge" data-variant={variant}>{children}</span>
+```
+
+```css
+/* WRONG — modifier class */
+.sk-badge-active { color: var(--color-success); }
+
+/* CORRECT — attribute selector on the base class */
+.sk-badge[data-variant="active"] { color: var(--color-success); }
+```
+
+## Component selection guide
+
+| Problem                                    | Component            |
+|--------------------------------------------|----------------------|
+| Button text changes on toggle              | `StateSwap`          |
+| Icon changes on toggle                     | `StateSwap`          |
+| Tab panels with stable height              | `LayoutMap`          |
+| Multi-step wizard with stable dimensions   | `LayoutGroup` + `LayoutView` |
+| Text loading from API                      | `StableText` inside `LoadingBoundary` |
+| Image/video loading causes shift           | `MediaSkeleton`      |
+| List loading from API                      | `CollectionSkeleton` |
+| Card/form loading from API                 | `LoadingBoundary` + `StableText` |
+| Panel enters/exits with animation          | `FadeTransition`     |
+| Container should never shrink              | `SizeRatchet`        |
+| Number/price changes digit count           | `StableCounter`      |
+| Cart badge, notification count             | `StableCounter`      |
+| Form validation error appears/disappears   | `StableField`        |
+| Need a UI primitive (badge, button, card)  | `createPrimitive`    |
+
+## Quick start pattern
+
+```tsx
+import {
+  LoadingBoundary,
+  StableText,
+  MediaSkeleton,
+  StateSwap,
+  LayoutMap,
+  SizeRatchet,
+  StableCounter,
+  StableField,
+  FadeTransition,
+  createPrimitive,
+} from "stablekit";
+```
+
+Loading a user profile with zero layout shift:
+```tsx
+<LoadingBoundary loading={isLoading} exitDuration={150}>
+  <MediaSkeleton aspectRatio={1} className="w-16 rounded-full">
+    <img src={user.avatar} alt={user.name} />
+  </MediaSkeleton>
+  <StableText as="h2" className="text-xl font-bold">{user.name}</StableText>
+  <StableText as="p" className="text-sm text-muted">{user.email}</StableText>
+</LoadingBoundary>
+```

package/package.json

@@ -0,0 +1,92 @@
+{
+  "name": "stablekit.ts",
+  "version": "0.2.0",
+  "description": "React toolkit for layout stability — zero-shift components for loading states, content swaps, and spatial containers.",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./styles.css": "./dist/styles.css",
+    "./eslint": {
+      "import": {
+        "types": "./dist/eslint.d.ts",
+        "default": "./dist/eslint.js"
+      },
+      "require": {
+        "types": "./dist/eslint.d.cts",
+        "default": "./dist/eslint.cjs"
+      }
+    },
+    "./stylelint": {
+      "import": {
+        "types": "./dist/stylelint.d.ts",
+        "default": "./dist/stylelint.js"
+      },
+      "require": {
+        "types": "./dist/stylelint.d.cts",
+        "default": "./dist/stylelint.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "llms.txt"
+  ],
+  "sideEffects": [
+    "./dist/styles.css"
+  ],
+  "scripts": {
+    "build": "tsup && cp src/styles.css dist/styles.css",
+    "prepare": "npm run build",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0",
+    "react-dom": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.2",
+    "@types/node": "^25.3.5",
+    "@types/react": "^19.0.0",
+    "eslint": "^10.0.3",
+    "jsdom": "^28.1.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^4.0.18"
+  },
+  "keywords": [
+    "layout-stability",
+    "loading-skeleton",
+    "state-swap",
+    "layout-shift",
+    "react",
+    "resize-observer",
+    "skeleton",
+    "shimmer",
+    "stable-layout",
+    "zero-cls"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ryandward/stablekit"
+  },
+  "author": "Ryan Ward"
+}