rainbowindex 0.0.0 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,122 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.0] - 2026-07-16
+
+Initial public release. Rainbow Index began as a fork of Tailwind CSS v4; the
+entries below list the capabilities this release adds **on top of** what
+Tailwind CSS v4 provides. Shared functionality (utility classes, variants,
+`@apply`, CSS-first theming, `@source`, arbitrary values, the Vite/PostCSS
+plugins as such) is not repeated here.
+
+### Added — runtime & programmatic API
+
+- **`ri()` class merger** — built-in class composition with right-most-wins
+  conflict resolution, replacing both `clsx` (conditional composition) and
+  `tailwind-merge` (conflict resolution). Understands shorthand property
+  claims (`p-4` owns all four padding sides), variant-order canonicalization
+  (`sm:hover:` ≡ `hover:sm:`), `!important`, negative utilities, and
+  arbitrary properties; bracket-aware tokenization with LRU caching.
+- **`createRi(snapshot)`** — SSR- and multi-tenant-safe merger bound to a
+  frozen compilation snapshot, for servers where concurrent requests may
+  target different themes in one process. `ri()` emits a throttled
+  `[RI-2004]` warning when it detects that situation.
+- **Programmatic compilation API** — `compileProject()`, `createCompiler()`,
+  `createCompilationContext()`, `finalizeCompilationContext()`, and
+  registration helpers (`registerCustomUtility`, `registerCustomTextSizes`,
+  `registerCustomFontFamilies`, `registerColorNames`) as a stable library
+  surface for driving compilation and feeding the merge engine.
+- **`safelist()` helper** — a runtime identity-join whose static string
+  arguments are extracted by the scanner at build time, so component/icon
+  libraries can ship class names that are always emitted.
+- **Package-based safelist auto-discovery** — installed dependencies can
+  declare `rainbowindex.safelistSources` globs in their own `package.json`
+  to opt their published files into scanning, with no manual `@source`.
+- **Browser entry guard** — importing the PostCSS-plugin default export in a
+  browser bundle throws `[RI-2003]` with guidance to use named imports.
+
+### Added — CLI
+
+- **`rainbowindex generate-types`** — generates a `rainbowindex-env.d.ts`
+  with a `RainbowClass` TypeScript union (colors × stops, spacing, text
+  sizes, weights, variants, custom utilities) for editor autocomplete;
+  `--strict` drops the string escape hatch; hand-edited files are backed up
+  before overwrite.
+- **`rainbowindex preload-fonts`** — emits `<link rel="preload" as="font">`
+  tags for resolved font faces.
+- **`rainbowindex init`** — wires Rainbow Index into an existing Vite app:
+  detects the package manager, installs the dependency, patches
+  `vite.config.*`, and creates or updates the CSS entry.
+- **`rainbowindex create <dir>`** — scaffolds a fresh Vite app (default
+  template `react-ts`) with Rainbow Index pre-wired.
+- **`--optimize`** — LightningCSS pass with browser-fallback down-leveling
+  in addition to minification.
+- **Atomic output writes** — CSS output is written via temp-file + rename so
+  interrupted builds never leave partial files.
+
+### Added — theming directives
+
+- **Generative color system (`@color`)** — declare a color as two numbers
+  (`brand: 0.18 330;` — chroma + hue) and get a full 19-stop OKLCH palette
+  with automatic dark mode via ramp mirroring, tuned for even perceived
+  contrast. Also supports explicit values, light/dark pairs, aliases,
+  per-color dark-override strategies, and contrast warnings.
+- **Font system (`@font`)** — register font slots from Google Fonts, local
+  files, or URLs in CSS; multi-face slots (upright + italic via an
+  `italic:` shorthand), system/manual stacks, and metrics-adjusted fallback
+  `@font-face` blocks (size-adjust/ascent/descent overrides) for zero
+  cumulative layout shift. On-disk font metadata cache governed by
+  `RI_OFFLINE`, `RI_FETCH_FONTS`, `RI_CACHE_DIR`, and `RI_FONT_CACHE_TTL`.
+- **`@fluid`** — configurable fluid type/spacing range driving
+  `text-fluid-*` and `*-fluid` spacing/inset utilities with curve keywords.
+- **`@rounded` corner shapes** — border-radius tokens with corner-shape
+  modifiers and `corner-round/scoop/bevel/notch/square/squircle` (plus
+  `corner-[superellipse(N)]`) utilities mapping to the CSS `corner-shape`
+  property.
+- **`@animate`** — register named animations with inline `@keyframes`, plus
+  compositional enter/exit utilities (`animate-in`/`animate-out` with
+  `fade-`, `zoom-`, `spin-`, `blur-`, and `slide-` parts, each driving
+  independent CSS variables) and preset accordion/collapsible keyframes.
+- **`@register`** — declare typed custom properties (`@property`-style
+  registrations with syntax and initial value) directly from CSS.
+- **`@preflight`** — toggle preflight base styles from CSS.
+
+### Added — class-string syntax
+
+- **Variant groups** — `hover:{text-red-500 bg-blue-100 underline}` expands
+  at scan time to the repeated-prefix form; groups stack and nest
+  (`sm:hover:{…}`, `data-[state=open]:{…}`) with depth and output caps, and
+  are also expanded inside `@apply` bodies.
+- **Helper-call-aware scanner** — class literals are extracted from
+  `clsx`/`cn`/`classnames`/`cx`/`twJoin`/`twMerge`/`cva`/`tv`/`classMap`/
+  `safelist` call sites rather than treating source files as flat text.
+- **Math-operator value parsing** — CSS math functions (`calc`, `min`,
+  `max`, `clamp`, `mod`, trigonometric functions, `pow`, `round`, …) are
+  recognized inside utility values.
+
+### Added — integrations
+
+- **Vite plugin extras** — auto-injects a PostCSS config only when none
+  exists, auto-discovers the CSS entry on first dev-server listen (warning
+  `[RI-1602]` if Rainbow Index never activates), tracks per-file versions
+  for HMR, and pre-rewrites Rainbow-Index-specific directive syntax into
+  PostCSS-parseable form before PostCSS runs.
+- **PostCSS plugin `sources` option** — declare scan globs from
+  `postcss.config.js` in addition to CSS `@source`, merged with
+  package-discovered safelist sources.
+
+### Added — diagnostics
+
+- **`RI-NNNN` error-code system** — every warning carries a namespaced code
+  (10xx compilation, 11xx color, 12xx fonts, 13xx merge, 14xx scanner, 15xx
+  typography, 16xx integrations, 20xx CSS functions, 21xx runtime), with a
+  parity test enforcing that every emitted code is documented.
+- **Warning deduplication and severity budgeting** — warnings are deduped
+  and capped per compile, with reserved slots so high-severity errors are
+  never drowned out by informational warnings.
+- **"Did you mean" suggestions** — optimal-string-alignment matching powers
+  typo hints for unknown utilities, variants, and theme variables.

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+This project is a fork of Tailwind CSS v4. Portions of this software are derived from Tailwind CSS: Copyright (c) Tailwind Labs, Inc.
+
+The class merging algorithm is derived from tailwind-merge: Copyright (c) 2021 Dany Castillo
+
+The animation system is inspired by tw-animate-css: Copyright (c) 2025 Wombosvideo (Luca Bosin)
+
+Rainbow Index Copyright (c) 2026 Milo Tech Forecast
+
+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

@@ -0,0 +1,329 @@
+<p align="center">
+  <a href="https://rainbowindex.dev" target="_blank">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/rainbowindex/rainbowindex/HEAD/.github/logo-dark.svg">
+      <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/rainbowindex/rainbowindex/HEAD/.github/logo-light.svg">
+      <img alt="Rainbow Index" src="https://raw.githubusercontent.com/rainbowindex/rainbowindex/HEAD/.github/logo-light.svg" width="144" height="41" style="max-width: 100%;">
+    </picture>
+  </a>
+</p>
+
+**Rainbow Index** is a CSS-first system for building and maintaining consistent user interfaces.
+
+The project began as a fork of [Tailwind CSS](https://github.com/tailwindlabs/tailwindcss), then diverged with clear intent: to treat CSS as the primary source of truth for styling decisions and to provide tooling that translates design system definitions into predictable, inspectable output. Styling behavior is explicit and traceable, allowing developers to understand not only what is happening, but why.
+
+We built the system around composable primitives rather than finished components. Instead of prescribing layout patterns or UI components, it focuses on utilities, directives, and tokens that can be combined without accumulating configuration debt.
+
+Rainbow Index challenges several assumptions common in modern styling workflows. Configuration does not default to JavaScript. Flexibility is not achieved through layered indirection. Utility-based systems are not assumed to be verbose, opaque, or fragile.
+
+The product is not a visual design tool, a component library, or a framework abstraction layer. It assumes familiarity with core CSS concepts and expects users to engage with the underlying model.
+
+When tradeoffs arise, we consistently prioritize composability, user control, predictable performance, explicit behavior, and correctness over convenience or familiarity.
+
+## Install
+
+```sh
+pnpm add rainbowindex
+```
+
+Requires Node `>=20.19`. The package is **ESM-only** — there is no CommonJS build, so `require("rainbowindex")` is only supported on runtimes that can `require()` ES modules (Node 20.19+); use `import` otherwise (e.g. an ESM `postcss.config.js`/`.mjs`). `postcss` is a required peer dependency, `vite` an optional one; `lightningcss`, `chokidar`, and `tinyglobby` are bundled as direct deps.
+
+## Quick start (Vite)
+
+The fastest path is the Vite plugin, which auto-injects PostCSS config and discovers your CSS entry on first dev-server listen.
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import rainbowindex from "rainbowindex/vite";
+
+export default defineConfig({
+	plugins: [rainbowindex()],
+});
+```
+
+```css
+/* src/styles.css */
+@import "rainbowindex";
+```
+
+```tsx
+// src/App.tsx
+export default function App() {
+	return <div className="flex gap-4 px-6 py-3 bg-blue-500 text-white">Hello</div>;
+}
+```
+
+To scaffold a fresh app instead, use the CLI:
+
+```sh
+pnpm dlx rainbowindex create my-app --template react-ts
+# or wire into an existing Vite app
+pnpm dlx rainbowindex init
+```
+
+## CLI
+
+The `rainbowindex` binary exposes five subcommands. The default is `build`.
+
+```
+rainbowindex <glob> [options]        Generate CSS from source files
+rainbowindex init                    Wire Rainbow Index into the current Vite app
+rainbowindex create <dir>            Scaffold a Vite app with Rainbow Index ready
+rainbowindex generate-types          Generate TypeScript types for ri() autocomplete
+rainbowindex preload-fonts           Generate <link rel="preload"> tags for resolved fonts
+```
+
+Common flags:
+
+| Flag | Description |
+| --- | --- |
+| `-o`, `--output <file>` | Output CSS file path. Required with `--watch`. |
+| `--watch` | Re-run on source-file changes (chokidar). |
+| `--minify` | Minify output via LightningCSS. |
+| `--optimize` | Minification + browser-fallback passes. |
+| `--css <file>` | CSS input with directives. Auto-detected if omitted. |
+| `--strict` | Drop the string escape hatch in generated types. |
+| `--template <name>` | Vite template to scaffold (default: `react-ts`). |
+
+Example:
+
+```sh
+rainbowindex "src/**/*.{ts,tsx}" -o dist/styles.css --watch
+```
+
+## PostCSS plugin
+
+The package's default Node export is a PostCSS plugin.
+
+```js
+// postcss.config.js
+import rainbowindex from "rainbowindex";
+
+export default {
+	plugins: [rainbowindex({ sources: ["src/**/*.{ts,tsx,html}"] })],
+};
+```
+
+Options:
+
+| Option | Type | Description |
+| --- | --- | --- |
+| `sources` | `string[]` | Glob patterns for files to scan. Can also be declared via `@source` in CSS. |
+| `cwd` | `string` | Working directory. Defaults to `process.cwd()`. |
+
+## Vite plugin
+
+```ts
+import rainbowindex from "rainbowindex/vite";
+```
+
+Auto-detects your CSS entry, injects a PostCSS config if none exists, supports HMR with file versioning. No options required for the common case.
+
+## Class syntax
+
+### Utilities
+
+Roughly the same surface area as Tailwind: spacing, sizing, typography, color, layout, borders, effects, animations, and SVG. Use `rainbowindex generate-types` for autocomplete in your editor.
+
+### Variants
+
+Prefix any utility with one or more variants, separated by `:`.
+
+```html
+<button class="bg-blue-500 hover:bg-blue-600 dark:bg-blue-400 sm:px-6">…</button>
+```
+
+Supported variants:
+
+- **Pseudo-classes** — `hover`, `focus`, `focus-visible`, `active`, `visited`, `disabled`, `enabled`, `checked`, `empty`, `first`, `last`, `odd`, `even`, `only`
+- **Pseudo-elements** — `before`, `after`, `placeholder`, `file`, `marker`, `selection`, `first-line`, `first-letter`, `backdrop`
+- **Media** — `dark`, `print`, `portrait`, `landscape`, `motion-safe`, `motion-reduce`, `starting`
+- **Breakpoints** — `sm`, `md`, `lg`, `xl` (theme-driven, customizable via `@breakpoint`)
+- **Container queries** — `@sm`, `@md`, …
+- **Attribute selectors** — `data-[state=open]`, `aria-[pressed=true]`
+- **Arbitrary** — `[selector]`, `[@media(...)]`
+
+### Arbitrary values
+
+```html
+<div class="w-[37rem] bg-[#1a73e8] data-[state=open]:opacity-100"></div>
+```
+
+CSS variable shorthand:
+
+```html
+<div class="bg-(--brand-color) text-(--brand-text)"></div>
+```
+
+### Variant groups
+
+When multiple utilities share the same variant prefix, group them with `{…}` instead of repeating the prefix:
+
+```html
+<!-- These two lines are equivalent -->
+<div class="hover:text-red-500 hover:bg-blue-100 hover:underline">…</div>
+<div class="hover:{text-red-500 bg-blue-100 underline}">…</div>
+```
+
+Groups stack and nest:
+
+```html
+<!-- Chained variants -->
+<div class="sm:hover:{bg-gray-700 text-white}">…</div>
+
+<!-- Multiple groups in one class string -->
+<div class="focus:{outline-2 outline-blue-500} disabled:{opacity-50 cursor-not-allowed}">…</div>
+
+<!-- The data-attribute case -->
+<div class="data-[active]:{relative px-2} data-[slot=sidebar]:{fixed leading-none}">…</div>
+```
+
+Expansion happens at scan-time, so the runtime never sees the grouped form. Nesting is capped at depth 10; expanded output is capped at 1MB.
+
+## Theming with CSS directives
+
+Customization happens in your CSS input, not a JS config. The engine recognizes:
+
+| Directive | Purpose |
+| --- | --- |
+| `@color` | Define color tokens. Supports generative (`chroma hue`), explicit (`oklch(...)`, `#rrggbb`), light/dark pairs, and aliases. |
+| `@spacing` | Set the spacing base unit. |
+| `@text` | Define text size tokens (`size, line-height`). |
+| `@font`, `@font-face` | Register font families inside a single `@font { … }` block. One slot can own multiple `@face` faces (e.g. upright + italic) or use the `italic:` shorthand. |
+| `@rounded` | Border-radius tokens; modifier sets corner shape (`round`, `squircle`, `superellipse(N)`, etc). |
+| `@fluid` | Configure fluid type/spacing range. |
+| `@animate` | Register named animations with inline `@keyframes`. |
+| `@utility` | Define a custom utility (static or functional `name-*`). |
+| `@apply` | Compose utilities into a single rule. |
+| `@custom` | Define a custom variant. |
+| `@slot` | Slot marker inside `@custom` block form. |
+| `@source` | Declare additional source globs from CSS. Supports `not "..."` and `inline("...")`. |
+| `@preflight` | Toggle preflight base styles. |
+| `@layer`, `@media`, `@custom-media`, `@import` | Standard CSS plus a few extensions. |
+
+Example:
+
+```css
+@import "rainbowindex";
+
+@color {
+	brand: 0.18 330;                   /* generative: chroma hue */
+	brand-soft: oklch(0.92 0.04 330);  /* explicit */
+	surface: oklch(0.98 0.01 260) / oklch(0.15 0.01 260);  /* light/dark pair */
+}
+
+@spacing { base: 0.5rem; }
+
+@text {
+	display: 4rem, 1.05;
+	body: 1rem, 1.5;
+}
+
+@font {
+	sans: "Inter" from google { weight: 400 700; }
+	display: "Satoshi" from "/fonts/Satoshi.woff2" {
+		weight: 300 900;
+		italic: "/fonts/Satoshi-Italic.woff2";   /* second face, font-style: italic */
+	}
+}
+
+@source "../emails/**/*.html";
+@source not "../**/legacy/*";
+```
+
+Default theme keys: `colors`, `spacing`, `text`, `breakpoints`, `rounded`, `shadows`, `weights`, `easing`, `fluid`, `animations`, `blur`, `z`.
+
+## `ri()` — runtime class merger
+
+`ri()` merges class strings with right-most-wins conflict resolution. It replaces both `clsx` (for conditional composition) and `tailwind-merge` (for conflict resolution).
+
+```ts
+import { ri } from "rainbowindex";
+
+ri("px-2 py-1", isActive && "bg-blue-500", "px-4");
+// → "py-1 bg-blue-500 px-4"   (px-2 is dropped — px-4 wins)
+```
+
+Accepted inputs:
+
+```ts
+type ClassInput = string | false | null | undefined | ClassInput[];
+ri(...inputs: ClassInput[]): string;
+```
+
+Conflict resolution understands shorthands: `p-4` claims all four padding sides, but only drops if every side is overwritten by a class to its right.
+
+### `ri()` vs `createRi()` — which one do I use?
+
+| Situation | Use |
+| --- | --- |
+| Browser bundle / client components | **`ri()`** |
+| Vite build / PostCSS one-shot | **`ri()`** |
+| Single Node compile that exits | **`ri()`** |
+| Concurrent SSR (one server, many requests) | **`createRi(snapshot)`** |
+| Multi-tenant compile (different themes in the same process) | **`createRi(snapshot)`** |
+| Edge / serverless functions sharing module state across invocations | **`createRi(snapshot)`** |
+
+`ri()` reads module-level state published by the most recent compile. That's
+fast and ergonomic in any environment where there is exactly one compile
+per process. If two requests can be merging classes against two different
+themes in the same Node process, that shared state will leak — use
+`createRi(snapshot)` to bind each request to its own frozen snapshot.
+
+```ts
+// Anywhere ri() is single-compile-safe (browser, Vite, PostCSS):
+import { ri } from "rainbowindex";
+
+const className = ri("px-2 py-1", isActive && "bg-blue-500", "px-4");
+```
+
+```ts
+// SSR / multi-tenant — capture the snapshot at compile time, bind per-request:
+import { compileProject, createRi, finalizeCompilationContext } from "rainbowindex";
+
+// At server startup (once per theme):
+const ctx = await compileProject({ cwd, css });
+const snapshot = finalizeCompilationContext(ctx);
+const ri = createRi(snapshot);
+
+// In your request handler:
+function render(req, res) {
+	const html = `<div class="${ri("px-2 py-1", req.dark && "dark:bg-slate-900")}">…</div>`;
+	res.send(html);
+}
+```
+
+If you call `ri()` while a compilation is still in progress (e.g. inside a
+server-rendering pass that triggers a fresh compile), the runtime emits a
+throttled `[RI-2004]` warning. That's your signal to switch to `createRi()`.
+
+## Environment variables
+
+| Variable | Effect |
+| --- | --- |
+| `RI_DEBUG=1` | Enable debug logging. |
+| `RI_OFFLINE=1` | Skip network calls; use cached font data only. |
+| `RI_FETCH_FONTS=0` | Disable Google Fonts metadata requests. |
+| `RI_CACHE_DIR` | Override font cache directory (default: `node_modules/.cache/rainbowindex`). |
+| `RI_FONT_CACHE_TTL` | Font cache max age in seconds (default: `604800` — 7 days). |
+
+## Diagnostics
+
+Warnings carry `RI-NNNN` codes. Ranges:
+
+| Range | Subsystem |
+| --- | --- |
+| 10xx | Compilation & directives |
+| 11xx | Color directives |
+| 12xx | Font system |
+| 13xx | Merge / compilation context |
+| 14xx | Source scanner |
+| 15xx | Typography utilities |
+| 16xx | Integration plugins (Vite, PostCSS, CLI wiring) |
+| 20xx | CSS function processing |
+| 21xx | `ri()` runtime |
+
+See the [diagnostics reference](https://rainbowindex.dev/docs/diagnostics) for the full code → cause → fix table.
+
+Warnings are deduplicated and capped at 200 per compile, with 20 slots reserved for high-severity errors.

package/dist/browser.d.ts

@@ -0,0 +1,5 @@
+export { C as ColorDefinition, a as CompilationContext, b as CompilationSnapshot, D as DEFAULT_TEXT_SIZES, F as FluidConfig, T as TextSize, c as Theme, d as createCompilationContext, e as createRi, f as defaultTheme, g as finalizeCompilationContext, r as registerColorNames, h as registerCustomFontFamilies, i as registerCustomTextSizes, j as registerCustomUtility, k as ri, s as safelist } from './safelist-DRk1XXxi.js';
+
+declare function browserEntryUnavailable(): never;
+
+export { browserEntryUnavailable as default };

package/dist/browser.mjs

@@ -0,0 +1,41 @@
+import {
+  safelist
+} from "./chunk-PD4ZXGJ6.mjs";
+import {
+  DEFAULT_TEXT_SIZES,
+  createCompilationContext,
+  createRi,
+  defaultTheme,
+  devWarn,
+  finalizeCompilationContext,
+  registerColorNames,
+  registerCustomFontFamilies,
+  registerCustomTextSizes,
+  registerCustomUtility,
+  ri
+} from "./chunk-5N4GPK26.mjs";
+
+// src/entries/browser.ts
+function browserEntryUnavailable() {
+  devWarn(
+    '[RI-2003] The default export from "rainbowindex" is the PostCSS plugin and is not available in browser bundles. Use named imports like `import { ri } from "rainbowindex"` in client code, or import the plugin in Node/PostCSS only.'
+  );
+  throw new Error(
+    '[RI-2003] The default export from "rainbowindex" is not available in browser bundles.'
+  );
+}
+var browser_default = browserEntryUnavailable;
+export {
+  DEFAULT_TEXT_SIZES,
+  createCompilationContext,
+  createRi,
+  browser_default as default,
+  defaultTheme,
+  finalizeCompilationContext,
+  registerColorNames,
+  registerCustomFontFamilies,
+  registerCustomTextSizes,
+  registerCustomUtility,
+  ri,
+  safelist
+};