@tenphi/tasty 0.0.0-snapshot.08a6610

package/docs/tasty-static.md

@@ -0,0 +1,421 @@
+# Zero Runtime Mode (tastyStatic)
+
+`tastyStatic` is a build-time utility for generating CSS with zero runtime overhead. It's designed for static sites, no-JS websites, and performance-critical applications where you want to eliminate all runtime styling code.
+
+---
+
+## When to Use
+
+- **Static site generation (SSG)** — Pre-render all styles at build time
+- **No-JavaScript websites** — CSS works without any JS runtime
+- **Performance-critical pages** — Zero runtime overhead for styling
+- **Landing pages** — Minimal bundle size with pre-generated CSS
+
+## Requirements
+
+The zero-runtime mode is part of the main `@tenphi/tasty` package but requires additional peer dependencies depending on your setup:
+
+| Dependency | Version | Required for |
+|---|---|---|
+| `@babel/core` | >= 7.24 | Babel plugin (`@tenphi/tasty/babel-plugin`) |
+| `@babel/helper-plugin-utils` | >= 7.24 | Babel plugin |
+| `@babel/types` | >= 7.24 | Babel plugin |
+| `jiti` | >= 2.6 | Next.js wrapper (`@tenphi/tasty/next`) when using `configFile` option |
+
+All of these are declared as optional peer dependencies of `@tenphi/tasty`. Install only what your setup requires:
+
+```bash
+# For any Babel-based setup (Vite, custom Babel config, etc.)
+pnpm add -D @babel/core @babel/helper-plugin-utils @babel/types
+
+# For Next.js with TypeScript config file
+pnpm add -D @babel/core @babel/helper-plugin-utils @babel/types jiti
+```
+
+---
+
+## Quick Start
+
+### Basic Usage
+
+```tsx
+import { tastyStatic } from '@tenphi/tasty/static';
+
+// Define styles - returns StaticStyle object
+const button = tastyStatic({
+  display: 'inline-flex',
+  padding: '2x 4x',
+  fill: '#purple',
+  color: '#white',
+  radius: '1r',
+});
+
+// Use in JSX - works via toString() coercion
+<button className={button}>Click me</button>
+
+// Or access className explicitly
+<button className={button.className}>Click me</button>
+```
+
+---
+
+## API Reference
+
+### tastyStatic(styles)
+
+Creates a `StaticStyle` object from a styles definition.
+
+```tsx
+const card = tastyStatic({
+  padding: '4x',
+  fill: '#white',
+  border: true,
+  radius: true,
+});
+```
+
+### tastyStatic(base, styles)
+
+Extends an existing `StaticStyle` with additional styles. Uses `mergeStyles` internally for proper nested selector handling.
+
+```tsx
+const button = tastyStatic({
+  padding: '2x 4x',
+  fill: '#blue',
+  Icon: { color: '#white' },
+});
+
+const primaryButton = tastyStatic(button, {
+  fill: '#purple',
+  Icon: { opacity: 0.8 },
+});
+```
+
+### tastyStatic(selector, styles)
+
+Generates global styles for a CSS selector. The call is removed from the bundle after transformation.
+
+```tsx
+tastyStatic('body', {
+  fill: '#surface',
+  color: '#text',
+  preset: 't3',
+});
+```
+
+---
+
+## StaticStyle Object
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `className` | `string` | Space-separated class names for use in JSX |
+| `styles` | `Styles` | The original (or merged) styles object |
+| `toString()` | `() => string` | Returns `className` for string coercion |
+
+---
+
+## Babel Plugin Configuration
+
+### Basic Configuration
+
+```javascript
+// babel.config.js
+module.exports = {
+  plugins: [
+    ['@tenphi/tasty/babel-plugin', {
+      output: 'public/tasty.css',
+    }]
+  ]
+};
+```
+
+### With Configuration
+
+```javascript
+module.exports = {
+  plugins: [
+    ['@tenphi/tasty/babel-plugin', {
+      output: 'public/tasty.css',
+      config: {
+        states: {
+          '@mobile': '@media(w < 768px)',
+          '@tablet': '@media(w < 1024px)',
+          '@dark': '@root(theme=dark)',
+        },
+        devMode: true,
+      },
+    }]
+  ]
+};
+```
+
+### Plugin Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `output` | `string` | `'tasty.css'` | Path for generated CSS file |
+| `configFile` | `string` | — | Absolute path to a TS/JS module that default-exports a `TastyZeroConfig` object. JSON-serializable alternative to `config` — required for Turbopack. |
+| `config` | `TastyZeroConfig \| () => TastyZeroConfig` | `{}` | Inline config object or factory function. Takes precedence over `configFile`. |
+| `configDeps` | `string[]` | `[]` | Absolute file paths that affect config (for cache invalidation) |
+| `config.states` | `Record<string, string>` | `{}` | Predefined state aliases |
+| `config.devMode` | `boolean` | `false` | Add source comments to CSS |
+| `config.recipes` | `Record<string, RecipeStyles>` | `{}` | Predefined style recipes |
+
+---
+
+## Recipes
+
+Recipes work with `tastyStatic` the same way as with runtime `tasty`:
+
+```javascript
+// babel.config.js
+module.exports = {
+  plugins: [
+    ['@tenphi/tasty/babel-plugin', {
+      output: 'public/tasty.css',
+      config: {
+        recipes: {
+          card: { padding: '4x', fill: '#surface', radius: '1r', border: true },
+          elevated: { shadow: '2x 2x 4x #shadow' },
+        },
+      },
+    }]
+  ]
+};
+```
+
+```tsx
+import { tastyStatic } from '@tenphi/tasty/static';
+
+const card = tastyStatic({
+  recipe: 'card elevated',
+  color: '#text',
+});
+
+<div className={card}>Styled card</div>
+```
+
+---
+
+## Next.js Integration
+
+The `withTastyZero` wrapper configures both **webpack** and **Turbopack** automatically. No `--webpack` flag is needed — it works with whichever bundler Next.js uses.
+
+```typescript
+// next.config.ts
+import { withTastyZero } from '@tenphi/tasty/next';
+
+export default withTastyZero({
+  output: 'public/tasty.css',
+  configFile: './app/tasty-zero.config.ts',
+  configDeps: ['./app/theme.ts'],
+})({
+  reactStrictMode: true,
+});
+```
+
+### `withTastyZero` Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `output` | `string` | `'public/tasty.css'` | Output path for CSS relative to project root |
+| `enabled` | `boolean` | `true` | Enable/disable the plugin |
+| `configFile` | `string` | — | Path to a TS/JS module that default-exports `TastyZeroConfig`. Recommended for Turbopack compatibility. |
+| `config` | `TastyZeroConfig` | — | Inline config object. For static configs that don't change during dev. |
+| `configDeps` | `string[]` | `[]` | Extra files the config depends on (for cache invalidation) |
+
+### Turbopack Support
+
+Starting with Next.js 16, Turbopack is the default bundler. `withTastyZero` supports it out of the box by injecting `turbopack.rules` with `babel-loader` and JSON-serializable options.
+
+The `configFile` option is key for Turbopack — it passes a file path (JSON-serializable) instead of a function, and the Babel plugin loads the config internally via jiti.
+
+**Requirements**: `babel-loader` must be installed in your project:
+
+```bash
+pnpm add babel-loader
+```
+
+### Including the CSS
+
+```tsx
+// app/layout.tsx (App Router)
+import '@/public/tasty.css';
+
+// or pages/_app.tsx (Pages Router)
+import '../public/tasty.css';
+```
+
+---
+
+## Vite Integration
+
+```typescript
+// vite.config.ts
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+
+export default defineConfig({
+  plugins: [
+    react({
+      babel: {
+        plugins: [
+          ['@tenphi/tasty/babel-plugin', {
+            output: 'public/tasty.css',
+            config: {
+              states: { '@mobile': '@media(w < 768px)' },
+            },
+          }],
+        ],
+      },
+    }),
+  ],
+});
+```
+
+---
+
+## Build Transformation
+
+### Before (Source Code)
+
+```tsx
+import { tastyStatic } from '@tenphi/tasty/static';
+
+const button = tastyStatic({
+  padding: '2x 4x',
+  fill: '#purple',
+  color: '#white',
+});
+
+tastyStatic('.heading', { preset: 'h1' });
+
+export const Button = () => <button className={button}>Click</button>;
+```
+
+### After (Production Build)
+
+```tsx
+const button = {
+  className: 'ts3f2a1b ts8c4d2e',
+  styles: { padding: '2x 4x', fill: '#purple', color: '#white' },
+  toString() { return this.className; }
+};
+
+export const Button = () => <button className={button}>Click</button>;
+```
+
+### Generated CSS (tasty.css)
+
+```css
+/* Generated by @tenphi/tasty/zero - DO NOT EDIT */
+
+.ts3f2a1b.ts3f2a1b {
+  padding: 16px 32px;
+}
+
+.ts8c4d2e.ts8c4d2e {
+  background: #9370db;
+  color: #fff;
+}
+
+.heading.heading {
+  font-size: 2.5rem;
+  font-weight: 700;
+  line-height: 1.2;
+}
+```
+
+---
+
+## Style Extension
+
+```tsx
+// Base button
+const button = tastyStatic({
+  display: 'inline-flex',
+  padding: '2x 4x',
+  radius: '1r',
+  fill: '#gray.20',
+  color: '#text',
+  transition: 'fill 0.15s',
+});
+
+// Variants
+const primaryButton = tastyStatic(button, {
+  fill: '#purple',
+  color: '#white',
+});
+
+const dangerButton = tastyStatic(button, {
+  fill: '#danger',
+  color: '#white',
+});
+```
+
+---
+
+## State-based Styling
+
+```tsx
+const card = tastyStatic({
+  padding: {
+    '': '4x',
+    '@mobile': '2x',
+  },
+  display: {
+    '': 'flex',
+    '@mobile': 'block',
+  },
+});
+```
+
+---
+
+## Extending Style Types (TypeScript)
+
+If you add custom style properties, use module augmentation so `tastyStatic` recognizes them too. See [Extending Style Types](configuration.md#extending-style-types-typescript) in the configuration docs.
+
+---
+
+## Limitations
+
+1. **Static values only** — All style values must be known at build time
+2. **No runtime props** — Cannot use `styleProps` or dynamic `styles` prop
+3. **No mods at runtime** — Modifiers must be defined statically
+4. **Build-time transformation required** — Babel plugin must process files
+
+### Workarounds
+
+For dynamic styling needs, combine with regular CSS or CSS variables:
+
+```tsx
+const card = tastyStatic({
+  padding: '4x',
+  fill: 'var(--card-bg, #white)',
+});
+
+<div
+  className={card}
+  style={{ '--card-bg': isActive ? '#purple' : '#white' }}
+/>
+```
+
+---
+
+## Best Practices
+
+1. **Define base styles** for common patterns, then extend for variants
+2. **Use selector mode** for global/body styles
+3. **Enable devMode** in development for easier debugging
+4. **Configure states** for consistent responsive breakpoints
+5. **Import generated CSS** early in your app entry point
+
+---
+
+## Related
+
+- [Style DSL](dsl.md) — State maps, tokens, units, extending semantics (shared by runtime and static)
+- [Runtime API](runtime.md) — Runtime styling: `tasty()` factory, component props, variants, sub-elements, hooks
+- [Configuration](configuration.md) — Global configuration: tokens, recipes, custom units, and style handlers

package/package.json

@@ -0,0 +1,209 @@
+{
+  "name": "@tenphi/tasty",
+  "version": "0.0.0-snapshot.08a6610",
+  "description": "A design-system-integrated styling system and DSL for concise, state-aware UI styling",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./static": {
+      "types": "./dist/static/index.d.ts",
+      "import": "./dist/static/index.js",
+      "default": "./dist/static/index.js"
+    },
+    "./babel-plugin": {
+      "types": "./dist/zero/babel.d.ts",
+      "import": "./dist/zero/babel.js",
+      "default": "./dist/zero/babel.js"
+    },
+    "./zero": {
+      "types": "./dist/zero/index.d.ts",
+      "import": "./dist/zero/index.js",
+      "default": "./dist/zero/index.js"
+    },
+    "./next": {
+      "types": "./dist/zero/next.d.ts",
+      "import": "./dist/zero/next.js",
+      "default": "./dist/zero/next.js"
+    },
+    "./core": {
+      "types": "./dist/core/index.d.ts",
+      "import": "./dist/core/index.js",
+      "default": "./dist/core/index.js"
+    },
+    "./ssr": {
+      "types": "./dist/ssr/index.d.ts",
+      "import": "./dist/ssr/index.js",
+      "default": "./dist/ssr/index.js"
+    },
+    "./ssr/next": {
+      "types": "./dist/ssr/next.d.ts",
+      "import": "./dist/ssr/next.js",
+      "default": "./dist/ssr/next.js"
+    },
+    "./ssr/astro": {
+      "types": "./dist/ssr/astro.d.ts",
+      "import": "./dist/ssr/astro.js",
+      "default": "./dist/ssr/astro.js"
+    },
+    "./tasty.config": "./tasty.config.ts"
+  },
+  "files": [
+    "dist",
+    "docs",
+    "tasty.config.ts"
+  ],
+  "sideEffects": [
+    "./dist/ssr/index.js",
+    "./dist/ssr/next.js",
+    "./dist/ssr/astro.js"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src",
+    "lint:fix": "eslint src --fix",
+    "format": "prettier --write \"src/**/*.{ts,tsx}\"",
+    "format:check": "prettier --check \"src/**/*.{ts,tsx}\"",
+    "size": "size-limit",
+    "prepublishOnly": "pnpm run build",
+    "changeset": "changeset",
+    "version": "changeset version",
+    "release": "changeset publish",
+    "hygiene": "pnpm lint && pnpm format:check && pnpm typecheck",
+    "hygiene:fix": "pnpm lint:fix && pnpm format && pnpm typecheck"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tenphi/tasty.git"
+  },
+  "keywords": [
+    "css-in-js",
+    "styling",
+    "design-system",
+    "react",
+    "state-aware",
+    "zero-runtime",
+    "babel-plugin",
+    "typescript",
+    "dsl"
+  ],
+  "author": "Andrey Yamanov",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/tenphi/tasty/issues"
+  },
+  "homepage": "https://github.com/tenphi/tasty#readme",
+  "peerDependencies": {
+    "@babel/core": "^7.24.0",
+    "@babel/helper-plugin-utils": "^7.24.0",
+    "@babel/types": "^7.24.0",
+    "jiti": "^2.6.1",
+    "react": "^18.0.0 || ^19.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@babel/core": {
+      "optional": true
+    },
+    "@babel/helper-plugin-utils": {
+      "optional": true
+    },
+    "@babel/types": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    },
+    "jiti": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "csstype": "^3.1.0"
+  },
+  "devDependencies": {
+    "@babel/core": "^7.24.0",
+    "@changesets/changelog-github": "^0.5.2",
+    "@changesets/cli": "^2.29.8",
+    "@eslint/js": "^10.0.1",
+    "@size-limit/esbuild": "^12.0.0",
+    "@size-limit/file": "^12.0.0",
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.2",
+    "@types/babel__core": "^7.20.5",
+    "@types/babel__helper-plugin-utils": "^7.10.3",
+    "@types/node": "^25.3.2",
+    "@types/react": "^19.0.0",
+    "@vitest/runner": "^4.0.18",
+    "eslint": "^10.0.0",
+    "eslint-config-prettier": "^10.1.8",
+    "jsdom": "^28.1.0",
+    "prettier": "^3.8.1",
+    "react": "^19.0.0",
+    "size-limit": "^12.0.0",
+    "tsdown": "^0.20.3",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.56.0",
+    "vitest": "^4.0.18"
+  },
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "esbuild"
+    ]
+  },
+  "packageManager": "pnpm@10.32.1",
+  "size-limit": [
+    {
+      "name": "main (import *)",
+      "path": "dist/index.js",
+      "import": "*",
+      "limit": "47 kB"
+    },
+    {
+      "name": "core (import *)",
+      "path": "dist/core/index.js",
+      "import": "*",
+      "limit": "45 kB"
+    },
+    {
+      "name": "static",
+      "path": "dist/static/index.js",
+      "import": "*",
+      "limit": "2 kB"
+    },
+    {
+      "name": "zero",
+      "path": "dist/zero/index.js",
+      "import": "*",
+      "ignore": [
+        "fs",
+        "path",
+        "crypto"
+      ],
+      "limit": "27 kB"
+    },
+    {
+      "name": "babel-plugin",
+      "path": "dist/zero/babel.js",
+      "import": "*",
+      "ignore": [
+        "fs",
+        "path",
+        "crypto"
+      ],
+      "limit": "38 kB"
+    }
+  ]
+}

package/tasty.config.ts

@@ -0,0 +1,14 @@
+export default {
+  tokens: [
+    '#white',
+    '#black',
+    '#current',
+    '$gap',
+    '$radius',
+    '$border-width',
+    '$outline-width',
+    '$transition',
+    '$sharp-radius',
+    '$bold-font-weight',
+  ],
+};