simplestyle-js 5.5.1-alpha.2 → 6.1.0

package/README.md

@@ -2,26 +2,16 @@
 
 An ultra-tiny, neat, easy-to-use CSS-in-JS library with SSR support,
 tiny bundle size and only *one runtime dependency*.
+Framework agnostic by design — works with React, Vue, Svelte, Next.js, Astro, or no framework at all.
 
 `6.48kB` / `2.69kB gzip` ([courtesy of bundlejs.com](https://bundlejs.com/?q=simplestyle-js))
 
-# Simplestyle-js Reference
-
-A concise guide to the core `simplestyle-js` APIs, how they fit together, and how to use them in browser and server-rendered apps (including Next.js).
-
 ## Table of Contents
 - [Install](#install)
-- [Quick Start](#quick-start)
+- [Quick Start (Browser)](#quick-start-browser)
+- [SSR / Static Extraction (Framework-Agnostic)](#ssr--static-extraction-framework-agnostic)
 - [API Reference](#api-reference)
 - [Patterns and Tips](#patterns-and-tips)
-  - [Creating reusable variables and / or design system-like tokens](#reusable-variables)
-- [SSR](#ssr)
-  - [Next.js](#nextjs)
-  - [Astro](#astro)
-  - [SSR steps for most SSR / SSG frameworks](#ssr-steps-for-most-ssr--ssg-frameworks)
-    - [1. Set your seed, create a SimpleStyleRegistry and your style functions](#1-set-your-seed-create-a-simplestyleregistry-and-your-style-functions)
-    - [2. Render the generated styles in your HTML](#2-render-the-generated-styles-in-your-html)
-    - [3. Create your styles and have fun!](#3-create-your-styles-and-have-fun)
 - [Creating a simplestyle-js plugin](#creating-a-simplestyle-js-plugin)
   - [Plugin Example (Autoprefixer)](#plugin-example-autoprefixer)
 - [License](#license)
@@ -50,367 +40,239 @@ pnpm add simplestyle-js
 yarn add simplestyle-js
 ```
 
-## Quick Start
+## Quick Start (Runtime styles in the Browser)
+
+Use the browser entrypoint for runtime CSS injection. This variant creates `<style />` tags in the browser and is the most traditional CSS‑in‑JS experience.
+
+```tsx
+import { makeCssFuncs } from 'simplestyle-js/browser';
+
+const { createStyles, createKeyframes, createRawStyles } = makeCssFuncs();
 
-```jsx
-import createStyles from 'simplestyle-js';
+const { keyframe } = createKeyframes('Pulse', () => ({
+  '0%': { opacity: 0.6, transform: 'scale(0.98)' },
+  '100%': { opacity: 1, transform: 'scale(1)' },
+}));
+
+createRawStyles('GlobalReset', () => ({
+  '*, *::before, *::after': { boxSizing: 'border-box' },
+  body: { margin: 0, fontFamily: 'system-ui, sans-serif' },
+}));
 
 const { classes } = createStyles('Button', () => ({
   root: {
-    '&:hover': { backgroundColor: '#2d6cdf' },
-    '@media (max-width: 768px)': { padding: '10px 12px' },
     backgroundColor: '#1f4aa8',
     borderRadius: 6,
     color: '#fff',
     padding: '12px 16px',
+    animation: `${keyframe} 900ms ease-in-out infinite alternate`,
+    '&:hover': { backgroundColor: '#2d6cdf' },
+    '@media (max-width: 768px)': { padding: '10px 12px' },
   },
 }));
 
 document.querySelector('button')?.classList.add(classes.root);
-
-// or, in a React / JSX-like component
-const Button = (props) => <button {...props} className={classes.root}>Awesome button</button>
 ```
 
-Rules support nested selectors via `&`, media queries, and `$className` back-references to other generated classes.
-
-## API Reference
+Rules support nested selectors via `&`, media queries, and `$className` back‑references to other generated classes.
 
-- `createStyles(ruleId, rules, options?)`
-  - Builds a set of class names and CSS from a rules object. Returns `{ classes, stylesheet, updateSheet }`.
-  - `options.flush` (default `true`): injects a `<style>` tag into `document.head`.
-  - `options.insertBefore` / `insertAfter`: choose where the `<style>` tag is placed when flushing.
-  - `options.registry`: provide a `SimpleStyleRegistry` instance to **collect** CSS instead of touching the DOM (ideal for SSR).
-  - `updateSheet(updatedRules)` merges rules and updates the existing sheet (works when `flush` is `true` or a `registry` is provided). Returns `{ classes, stylesheet } | null`.
-  - Example:
-    ```ts
-    const { classes, stylesheet } = createStyles('Nav', () => ({
-      wrapper: { display: 'flex', gap: 12 },
-      link: {
-        '&:hover': { textDecoration: 'underline' },
-      },
-      '@media (max-width: 600px)': {
-        wrapper: { flexDirection: 'column' },
-      },
-    }), { flush: false }); // do not write to the DOM automatically
-    ```
-
-- `imports(ruleId, importRulesFnc, options?)`
-  - Allow you to define one or more `@import()` rules for importing or referencing external stylesheets. **Note**: These imports will not be transformed or attempted to have their contents imported.
-
-- `keyframes(ruleId, framesFnc, options?)`
-  - Generates a unique animation name and accompanying `@keyframes` CSS.
-  - Returns `{ keyframe: string; stylesheet: string; }`. Respects `flush` and `insertBefore/After` options.
-
-- `rawStyles(ruleId, rulesFnc, options?)`
-  - Writes rules without generating new class names. Keys must already be selectors (e.g., `html`, `body *`, `.app`).
-  - Good for global resets or theme primitives. Respects `flush` and `registry`.
-
-- `makeCssFuncs({ registry?, variables? })`
-  - Returns `createStyles`, `keyframes` and `rawStyles` functions for you to use that are bound to an optional `SimpleStyleRegistry` and an optional `variables` object.
-  - Use this variant if you want to bind all of the CSS functions to a set of styling tokens / variables that you want accessible and available wherever you write your CSS, complete with IDE intellisense.
-  - Use this as a convenience if you don't want to manually wire up each CSS function (listed below) to your registry.
-
-- `makeCreateStyles(registry)`
-  - Convenience wrapper that returns a `createStyles` instance pre-bound to a `SimpleStyleRegistry`. Use this when you want every call to accumulate in a registry (especially useful for SSR / Server-side rendering).
-
-- `makeRawStyles(registry)`
-  - Returns a `rawStyles` helper preconfigured with the provided registry; calls will auto-add to that registry instead of touching the DOM (same motivation as `makeCreateStyles` for SSR motivations).
-
-- `makeKeyframes(registry)`
-  - Returns a `keyframes` helper preconfigured with the provided registry; calls will auto-add to that registry instead of touching the DOM (same motivation as `makeCreateStyles` for SSR motivations).
-
-- `setSeed(seed: number | null)`
-  - Controls the deterministic suffix used for generated class names. Setting the same seed in server and client renders keeps class names stable for hydration. Pass `null` to reset to `Date.now()`.
-
-- `registerPosthook(fn: (sheet: string) => string)`
-  - Adds a transform that runs after CSS strings are generated but before they are flushed or stored. Use for autoprefixing, minification, or custom transforms. Hooks run in registration order.
-
-- Types
-  - `SimpleStyleRules`: `{ [selectorOrKey: string]: Properties | SimpleStyleRules }` (recursive rule tree).
-  - `CreateStylesOptions`: shape of the options described above.
-  - `PosthookPlugin`: signature for `registerPosthook`.
+## SSR / Static Extraction (Framework‑Agnostic)
 
-## Patterns and Tips
+The SSR workflow requires usage of the built in `ssjs` CLI tool.
+This works by scanning your source files and generating a single `.css` file, containing all of the collected styles.
+Your source code remains untouched and does not require any transformation or transpilation.
+To leverage this, you **must** use the SSR entrypoint and place all styles in files named with the following format:
 
-- **Nested selectors**: `&` is replaced with the parent selector. Comma-separated selectors are supported (e.g., `'&:hover, &:focus'`).
-- **Back-references**: Use `$otherRule` to reference another generated class in the same `createStyles` call.
-    - **NOTE:** The `$otherRule` needs to have been declared above where you're trying to use it in a descendant selector.
-- **Media queries**: Top-level `@media` keys contain further rule objects.
-- **DOM placement**: `insertBefore` and `insertAfter` let you control the exact placement for where `<style />` tags will be rendered (does not apply to SSR / Server-side rendering).br
-- **Updating styles**: `updateSheet` merges the new rules and updates the existing `<style>` tag (or registry entry, if you're not letting `simplestyle-js` flush to the DOM automatically for you). It also returns `{ classes, stylesheet }` so you can re-use class names if needed.
+```
+*.styles.{js|cjs|mjs|ts|mts|cts|jsx|tsx}
+```
 
-## Reusable Variables
+Run the `ssjs` CLI to compile a single CSS file. This works with **Next.js, Astro, or any framework** (SSR or SSG) because the output is just plain CSS.
 
-SimpleStyle provides an easy way to "bind" all of the CSS functions it exports to an object that contains your tokens, variables, etc.
-To do this, you would use the same API that's used to bind to a specific sheet registry, but specify the `variables` option:
+### 1) Write styles in `*.styles.*` files
 
-```typescript
-import { makeCssFuncs, SimpleStyleRegistry } from "simplestyle-js";
+```ts
+// src/components/button.styles.ts
+import { makeCssFuncs } from 'simplestyle-js/ssr';
 
+const { createStyles } = makeCssFuncs();
 
-export const { createStyles, keyframes } = makeCssFuncs({
-  variables: {
-    background: {
-      primary: '#f1f1f3',
-      secondary: '#555',
-    },
-  },
-});
-
-const { classes } = createStyles('my-component', vars => ({
-  card: {
-    // use all of your variables here.
-    // your IDE should provide code assistance to you
-    // to inform you of what variables are available
-    backgroundColor: vars.background.secondary,
+export const { classes } = createStyles('Button', () => ({
+  root: {
+    backgroundColor: '#1f4aa8',
+    borderRadius: 6,
+    color: '#fff',
+    padding: '12px 16px',
+    '&:hover': { backgroundColor: '#2d6cdf' },
   },
 }));
 ```
 
-## SSR
+```tsx
+// src/components/Button.tsx
+import { classes } from './button.styles';
 
-### Next.js
+export function Button() {
+  return <button className={classes.root}>Click me</button>;
+}
+```
 
-Create your scoped CSS functions using the per-request Next.js registry, then wrap the `SimpleStyleProvider` around your `layout` file. This ensures styles are collected during server rendering and injected into the `<head />` during streaming.
+### 2) Compile with `ssjs`
 
-```typescript
-// src/styleRegistry.ts
+Define **accurate `--entrypoints`** CLI flags for your code so the compiler can follow your import graph and discover all of your styles.
+The resulting CSS is written in the same order as your source code / import tree.
 
-import { makeCssFuncs, setSeed } from "simplestyle-js";
-import { getSimpleStyleRegistry } from "simplestyle-js/next";
+```bash
+bun ssjs --entrypoints src/app.tsx src/pages/**/*.tsx --outfile public/my-styles.css
+```
+```bash
+npx ssjs --entrypoints src/app.tsx src/pages/**/*.tsx --outfile public/my-styles.css
+```
+```bash
+pnpm ssjs --entrypoints src/app.tsx src/pages/**/*.tsx --outfile public/my-styles.css
+```
+```bash
+yarn ssjs --entrypoints src/app.tsx src/pages/**/*.tsx --outfile public/my-styles.css
+```
 
-// ensures deterministic creation of CSS classnames
-setSeed(11223344);
+Optional watch mode:
 
-export const { createStyles, imports, keyframes, rawStyles } = makeCssFuncs(() => ({
-  registry: getSimpleStyleRegistry(),
-}));
+```bash
+npx ssjs --entrypoints src/app.tsx src/pages/**/*.tsx --outfile public/my-styles.css --watch
 ```
 
-```tsx
-// src/app/layout.tsx
-import type { Metadata } from "next";
-import { SimpleStyleProvider } from "simplestyle-js/next";
-import { createStyles } from "./styleRegistry";
-
-// start writing CSS!
-const { classes } = createStyles('RootLayoutStyles', () => ({
-  rootLayout: {
-    backgroundColor: 'pink',
-    padding: '1rem',
-  },
-}));
+### 3) Include the generated CSS
 
-export default function RootLayout({
-  children,
-}: Readonly<{
-  children: React.ReactNode;
-}>) {
-  return (
-    <html lang="en">
-      <body className={classes.rootLayout}>
-        <SimpleStyleProvider>
-          {children}
-        </SimpleStyleProvider>
-      </body>
-    </html>
-  );
-}
+The output file is plain CSS. Include it the same way you would any stylesheet:
+
+```html
+<!-- SSR/SSG: add to your HTML head -->
+<link rel="stylesheet" href="/my-styles.css" />
 ```
 
-Check out this [Code Sandbox w/Next.js integration to see how it works](https://codesandbox.io/p/devbox/t3smf4).
+Or import it via your framework’s entry:
+
+```ts
+// e.g. Next.js or Astro entry files, or any UI application that uses a bundler
+import '../public/my-styles.css';
+```
 
-If you're building a component library that needs to work in Next.js with SSR, use the same `getSimpleStyleRegistry()` callback inside that library's `makeCssFuncs` call so it participates in the app's per-request registry. On the client, `getSimpleStyleRegistry()` returns `null`, so styles fall back to runtime injection.
+## API Reference
 
+**Important:** always call `makeCssFuncs()` from the correct entrypoint:
 
-### Astro
+- Browser runtime: `import { makeCssFuncs } from 'simplestyle-js/browser'`
+- SSR: `import { makeCssFuncs } from 'simplestyle-js/ssr'`
 
-Due to how Astro processes its front matter sections at build time, and how this also affects local development, each `.astro` file that has its own CSS rules will also need to have its own `SimpleStyleRegistry` instance.
-The overall developer experience is similar to Next.js, but requires a pinch more boilerplate.
+### `makeCssFuncs({ variables? }?)`
 
-```typescript
-// src/styleRegistry.ts
+Creates the CSS helpers and optionally binds your design tokens for typed access.
 
-import { makeCssFuncs, setSeed } from "simplestyle-js";
+```ts
+import { makeCssFuncs } from 'simplestyle-js/browser'; // or import the SSR variant from 'simplestyle-js/ssr';
 
-// ensures deterministic creation of CSS classnames
-setSeed(11223344);
+const { createStyles } = makeCssFuncs({
+  variables: {
+    colors: { brand: '#1f4aa8' },
+  },
+});
 
-export { createStyles, imports, keyframes, rawStyles } = makeCssFuncs({});
+const { classes } = createStyles('Card', (vars) => ({
+  root: { backgroundColor: vars.colors.brand },
+}));
 ```
 
-```astro
----
-import { SimpleStyleRegistry } from "simplestyle-js";
-import SimpleStyleProvider from "simplestyle-js/astro/SimpleStyleProvider";
-
-import {
-  createStyles,
-  keyframes,
-  rawStyles,
-} from "../styleRegistry";
+### `createStyles(ruleId, rulesFn, options?)`
 
-const registry = new SimpleStyleRegistry();
+Builds class names + CSS.
+Returns `{ classes, stylesheet, updateSheet }`.
+Use the returned `classes` directly in your component code / HTML.
 
-rawStyles("basic-css-reset", ()  => ({
-  "*": {
-    boxSizing: "border-box",
-  },
-  "body, html": {
-    fontFamily: "sans-serif",
-    fontSize: "16px",
-    padding: 0,
-  },
-}), {
-  // provide the registry used for this `.astro` file here
-  registry,
-});
+```ts
+const { classes } = createStyles('Nav', () => ({
+  wrapper: { display: 'flex', gap: 12 },
+  link: { '&:hover': { textDecoration: 'underline' } },
+  '@media (max-width: 600px)': { wrapper: { flexDirection: 'column' } },
+}));
+```
 
-// make changes to me and I will hot reload!
-const { keyframe } = keyframes("HomePage", () => ({
-  "0%": {
-    backgroundColor: "#cc2222cc",
-  },
-  "33%": {
-    backgroundColor: "#22cc22cc",
-  },
-  "66%": {
-    backgroundColor: "#2222cccc",
-  },
-  "100%": {
-    backgroundColor: "#cc2222cc",
-  },
-}), {
-  // provide the registry used for this `.astro` file here
-  registry,
-});
+Back‑reference example (use `$otherRule` to reference another generated class):
 
-const { classes } = createStyles("HomePage", () => ({
-  background: {
-    alignItems: "center",
-    animation: `${keyframe} 5s linear infinite`,
-    display: "flex",
-    flexFlow: "column",
-    height: "90vh",
-    justifyContent: "center",
-    margin: "0 auto",
-    width: "90vw",
-  },
-  content: {
-    backgroundColor: "#00000033",
-    borderRadius: "4px",
-    color: "white",
-    padding: "1rem",
+```ts
+const { classes } = createStyles('Card', () => ({
+  title: { fontWeight: 700, marginBottom: 8 },
+  root: {
+    padding: 16,
+    borderRadius: 8,
+    backgroundColor: '#f6f7fb',
+    '& $title': { color: '#1f4aa8' },
   },
-}), {
-  // provide the registry used for this `.astro` file here
-  registry,
-});
----
-<!-- wrap your astro content here with the provider and give it the registry you created in your front matter -->
-<SimpleStyleProvider registry={registry}>
-  <div class={classes.background}>
-    <div class={classes.content}>
-      <h1>Astro</h1>
-      <p>
-        Checkout the CSS class and animation applied to the body, which is
-        making my colors changes.
-      </p>
-      <p>Feel free to edit me and I'll hot reload!</p>
-    </div>
-  </div>
-</SimpleStyleProvider>
+}));
 ```
 
-Check out this [Code Sandbox w/Astro integration to see how it works](https://codesandbox.io/p/devbox/mq9twt).
-
-**General SSR Concepts**
+### `createKeyframes(ruleId, framesFn, options?)`
 
-`simplestyle-js` is intentionally unopinionated, especially when it comes to deep integrations with various frameworks. This also applies to SSR / Server-side rendering.
-The core APIs needed to make this work are:
+Generates a unique animation name and `@keyframes` CSS. Returns `{ keyframe, stylesheet }`.
 
-- `new SimpleStyleRegistry()` - creates a new StyleSheet registry where all of your styles will be accumulated
-- `setSeed(number)` - ensures that classNames are deterministically computed and will be the same on the server and when they're rehydrated on the client
-- `makeCssFuncs({ registry })` - returns `createStyles()`, `keyframes()` and `rawStyles()` functions that are locked to your StyleSheet registry
+```ts
+const { keyframe } = createKeyframes('FadeIn', () => ({
+  '0%': { opacity: 0, transform: 'translateY(6px)' },
+  '100%': { opacity: 1, transform: 'translateY(0px)' },
+}));
 
-### SSR steps for most SSR / SSG frameworks
+const { classes } = createStyles('Notice', () => ({
+  root: {
+    animation: `${keyframe} 320ms ease-out`,
+  },
+}));
+```
 
-#### 1. Set your seed, create a SimpleStyleRegistry and your style functions
+### `createRawStyles(ruleId, rulesFn, options?)`
 
-**Note**: This file can be located anywhere in your repository.
-For demonstration purposes, we'll locate this at our `src/` root, and name it `styleLib.js`
+Writes rules without generating class names. Keys must be selectors (`html`, `body *`, `.app`).
 
-```javascript
-import { makeCssFuncs, setSeed, SimpleStyleRegistry } from "simplestyle-js";
+```ts
+createRawStyles('GlobalReset', () => ({
+  '*, *::before, *::after': { boxSizing: 'border-box' },
+  'html, body': {
+    margin: 0,
+    padding: 0,
+    fontFamily: 'system-ui, sans-serif',
+    lineHeight: 1.4,
+    backgroundColor: '#fff',
+    color: '#111',
+  },
+  img: { maxWidth: '100%', display: 'block' },
+  button: { font: 'inherit' },
+}));
+```
 
-// set the className generation seed to ensure classNames are computed consistently
-// between the client and the server.
-// the number you use is arbitrary.
-// set it higher to have most characters injected in your generated class names
-setSeed(1);
+### `createImports(ruleId, rulesFn, options?)`
 
-// create the registry to hold all of the styles on the server
-export const StyleRegistry = new SimpleStyleRegistry();
+Creates `@import` rules. The array items must already be valid `@import` strings.
 
-// export the style functions that will be locked to your registry
-export const { createStyles, imports, keyframes, rawStyles } = makeCssFuncs({ registry: })
+```ts
+createImports('Imports', () => [
+  '@import "https://unpkg.com/normalize.css/normalize.css"',
+]);
 ```
 
-#### 2. Render the generated styles in your HTML
-
-**Note**: If you use Next.js, you would do this in your `layout.jsx` or `layout.tsx` file.
-Additionally, if you're not using React or any other JSX-inspired framework, you can use
-`StyleRegistry.getHTML()` to return an HTML string with all of the `<style />` tags you need,
-or `StyleRegistry.getCSS()` to just return a single, concatenated CSS string.
-
-```jsx
-import { StyleRegistry } from '../styleLib.js';
-
-export default function Layout({ children }) {
-  return (
-    <body lang="en">
-      {/* render your <style /> tags and set the IDs on them */}
-      {StyleRegistry.getRulesById().map(([id, css]) => (
-        <style id={id} key={id}>
-          {css}
-        </style>
-      ))}
-      {children}
-    </body>
-  );
-}
-```
+### `registerPosthook(fn: (sheet: string) => string)`
 
-#### 3. Create your styles and have fun!
+Registers a transform that runs after CSS strings are generated, but before they’re flushed or written.
 
-```jsx
-import { createStyles } from '../styleLib.js';
+### Types
 
-// create your styles
-const { classes } = createStyles('my-component', () => ({
-  awesome: {
-    backgroundColor: 'purple',
-    fontSize: '2rem',
-    padding: '2rem',
+- `SimpleStyleRules`: `{ [selectorOrKey: string]: Properties | SimpleStyleRules }`
+- `CreateStylesOptions`: options for flushing/placement in the browser runtime.
+- `PosthookPlugin`: signature for `registerPosthook`.
 
-    '& > span': {
-      fontStyle: 'italic',
-      fontWeight: 'bold',
-      textDecoration: 'underline',
-    },
-  },
-}));
+## Patterns and Tips
 
-export function MyCoolComponent() {
-  // use your styles here!
-  return (
-    <div className={classes.awesome}>
-      This is super <span>cool.</span>
-    </div>
-  );
-}
-```
+- **Nested selectors**: `&` is replaced with the parent selector. Comma‑separated selectors are supported (e.g., `'&:hover, &:focus'`).
+- **Back‑references**: Use `$otherRule` to reference another generated class in the same `createStyles` call (the referenced rule should appear earlier in the object).
+- **Media queries**: Top‑level `@media` keys contain further rule objects.
+- **Updating styles**: `updateSheet` merges new rules and updates the existing `<style>` tag (browser) or returns an updated sheet string (SSR extraction).
 
 ## Creating a simplestyle-js plugin
 
@@ -421,12 +283,13 @@ Do this if you want to integrate with `postcss`, `autoprefixer`, or any other CS
 ```ts
 import autoprefixer from 'autoprefixer';
 import postcss from 'postcss';
-import { registerPosthook } from 'simplestyle-js';
+import { registerPosthook } from 'simplestyle-js/browser';
 
 registerPosthook(css => postcss([autoprefixer]).process(css, { from: undefined }).css);
 ```
 
-Any future `createStyles`, `rawStyles`, or `keyframes` calls will run through the posthook chain.
+Any future `createStyles`, `createRawStyles`, or `createKeyframes` calls will run through the posthook chain.
+You can use the same API from `simplestyle-js/ssr` if you want the transform applied to extracted CSS as well.
 
 ## License
 [MIT](https://en.wikipedia.org/wiki/MIT_License)