@salty-css/core 0.2.2-refactor-vite-8.5 → 0.2.2-refactor-vite-8.8

package/README.md

@@ -0,0 +1,535 @@
+![Salty CSS Banner](https://salty-css.dev/assets/banners/dvd.svg)
+
+# Salty CSS — CSS-in-JS that compiles away
+
+Salty CSS is a build-time, type-safe CSS-in-JS library. You author styles in `.css.ts` files; the compiler emits real CSS, your runtime ships zero styling logic.
+
+[Get started](#get-started) · [API index](#api-index) · [Docs](https://salty-css.dev/docs) · [Discord](https://discord.gg/R6kr4KxMhP) · [GitHub](https://github.com/margarita-form/salty-css) · [NPM](https://www.npmjs.com/package/@salty-css/core)
+
+## Features
+
+- **Build-time compilation** — no runtime style injection, no FOUC, no client bundle cost.
+- **Framework support** — Next.js (App + Pages, React Server Components, Webpack & Turbopack), React + Vite, React + Webpack, Astro.
+- **Type safety** — TypeScript-first authoring, generated token types, an [ESLint plugin](https://www.npmjs.com/package/@salty-css/eslint-plugin-core).
+- **Design tokens & theming** — static, responsive (media-bound), and conditional (data-attribute / class-bound) variables in one place.
+- **Templates** — reusable style bundles with their own variants.
+- **Modifiers** — custom value transformers (`'space:3'` → `'12px'`) defined in config.
+- **Variants, compound variants, anyOf variants, default variants** out of the box.
+
+## Get started
+
+```bash
+npx salty-css init
+```
+
+`init` detects your framework, installs the right packages, creates `salty.config.ts`, and wires the bundler plugin. Per-framework setup:
+
+- **Next.js** → [salty-css.dev/docs/installation](https://salty-css.dev/docs/installation) — `withSaltyCss(nextConfig)` in `next.config.ts`. Auto-detects Webpack vs Turbopack; React Server Components supported.
+- **React + Vite** → [salty-css.dev/docs/installation](https://salty-css.dev/docs/installation) — `saltyPlugin(__dirname)` in `vite.config.ts`.
+- **Astro** → [salty-css.dev/docs/installation](https://salty-css.dev/docs/installation) — `saltyIntegration()` in `astro.config.mjs`.
+
+React + Webpack (without Next.js) is also supported via `@salty-css/webpack`.
+
+## CLI
+
+| Command                             | Alias | What it does                                                                                                                   |
+| ----------------------------------- | ----- | ------------------------------------------------------------------------------------------------------------------------------ |
+| `npx salty-css init [directory]`    | —     | Detect framework, install packages, create `salty.config.ts`, wire the plugin.                                                 |
+| `npx salty-css generate [filePath]` | `g`   | Scaffold a new Salty component file. Flags: `--name`, `--className`, `--tag`.                                                  |
+| `npx salty-css build [directory]`   | `b`   | Compile `*.css.ts` files into `saltygen/index.css`. Not needed when the bundler plugin is running. Flags: `--watch`, `--mode`. |
+| `npx salty-css update [version]`    | `up`  | Update all `@salty-css/*` packages. Defaults to `latest`. Flags: `--dir`, `--yes`.                                             |
+| `npx salty-css --version`           | —     | Print CLI version.                                                                                                             |
+
+Full reference: [salty-css.dev/docs/cli](https://salty-css.dev/docs/cli).
+
+## Good to know
+
+1. **File extensions matter.** `styled`, `className`, `keyframes`, and every `defineX(...)` call must live in a file ending `.css.ts`, `.css.tsx`, `.salty.ts`, `.styles.ts`, or `.styled.ts`. The compiler ignores everything else.
+2. **Extending non-Salty components is fine** — `styled(NextLink, { ... })` — as long as the wrapped component forwards `className` to a DOM element.
+3. **Async values & functions are allowed** (`base: { color: async () => 'red' }`), but heavy imports inside `*.css.ts` slow the build.
+4. **React Server Components are supported** via `@salty-css/next` — no `'use client'` needed for styled output.
+
+## ESLint
+
+Salty CSS ships a small ESLint plugin and matching shareable config. Two rules, both `error` by default, both autofixable, both scoped to Salty files (`.css.ts`, `.css.tsx`, `.salty.ts`, `.styles.ts`, `.styled.ts`):
+
+- **`@salty-css/core/must-be-exported`** — every `styled`, `className`, `keyframes`, and `defineX*` call must be exported; the compiler ignores anything else.
+- **`@salty-css/core/no-variants-in-base`** — `variants` must be a sibling of `base`, not nested inside it.
+
+```bash
+npm i -D @salty-css/eslint-plugin-core @salty-css/eslint-config-core
+```
+
+**Flat config (ESLint 9+):**
+
+```js
+// eslint.config.mjs
+import saltyConfig from '@salty-css/eslint-config-core/flat';
+
+export default [saltyConfig];
+```
+
+**Legacy (`.eslintrc`):**
+
+```js
+module.exports = { extends: ['@salty-css/eslint-config-core'] };
+```
+
+Full reference → [salty-css.dev/docs/eslint](https://salty-css.dev/docs/eslint).
+
+## API index
+
+| Symbol                                          | Import                          | One-liner                                                                     | Docs                                                                    |
+| ----------------------------------------------- | ------------------------------- | ----------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
+| [`styled`](#styled)                             | `@salty-css/react/styled`       | React component factory with variants & extension.                            | [api/styled](https://salty-css.dev/docs/api/styled)                     |
+| [`className`](#classname)                       | `@salty-css/react/class-name`   | CSS class string with `.variant()` chaining.                                  | [api/classname](https://salty-css.dev/docs/api/classname)               |
+| [Variants](#variants)                           | —                               | `variants`, `compoundVariants`, `anyOfVariants`, `defaultVariants` semantics. | [variants](https://salty-css.dev/docs/variants)                         |
+| [Overrides](#overrides)                         | —                               | Extend components, swap element, override per-instance via `style`.           | [overrides](https://salty-css.dev/docs/overrides)                       |
+| [ESLint plugin](#eslint)                        | `@salty-css/eslint-config-core` | Two rules: enforce `export` and correct `variants` placement on Salty files.  | [eslint](https://salty-css.dev/docs/eslint)                             |
+| [`defineConfig`](#defineconfig)                 | `@salty-css/core/config`        | Top-level project config.                                                     | [api/config](https://salty-css.dev/docs/api/config)                     |
+| [`defineVariables`](#definevariables)           | `@salty-css/core/factories`     | Static, responsive, and conditional CSS variables (tokens).                   | [variables](https://salty-css.dev/docs/variables)                       |
+| [Theming](#theming)                             | —                               | `data-theme` switcher built on conditional variables.                         | [theming](https://salty-css.dev/docs/theming)                           |
+| [`defineGlobalStyles`](#defineglobalstyles)     | `@salty-css/core/factories`     | Global rules (`html`, `body`, etc.).                                          | [api/define-factories](https://salty-css.dev/docs/api/define-factories) |
+| [`defineMediaQuery`](#definemediaquery)         | `@salty-css/core/factories`     | Named, reusable media queries.                                                | [media-queries](https://salty-css.dev/docs/media-queries)               |
+| [`defineTemplates`](#definetemplates)           | `@salty-css/core/factories`     | Reusable style bundles, optionally with variants.                             | [templates](https://salty-css.dev/docs/templates)                       |
+| [`defineFont`](#definefont)                     | `@salty-css/core/factories`     | `@font-face` (or `@import`) + CSS variable in one.                            | [fonts](https://salty-css.dev/docs/fonts)                               |
+| [`defineImport`](#defineimport)                 | `@salty-css/core/factories`     | Pull external CSS into Salty's `imports` layer.                               | [imports](https://salty-css.dev/docs/imports)                           |
+| [`keyframes`](#keyframes)                       | `@salty-css/react/keyframes`    | Typed `@keyframes` with params and initial-state injection.                   | [animations](https://salty-css.dev/docs/animations)                     |
+| [`defineViewportClamp`](#defineviewportclamp)   | `@salty-css/core/helpers`       | Fluid `clamp()` values that scale with the viewport.                          | [viewport-clamp](https://salty-css.dev/docs/viewport-clamp)             |
+| [`color`](#color)                               | `@salty-css/core/helpers`       | Color manipulation (`alpha`, `darken`, …).                                    | [color-function](https://salty-css.dev/docs/color-function)             |
+| [Modifiers](#modifiers)                         | (on `defineConfig`)             | Custom value transformers, e.g. `'space:3'` → `'12px'`.                       | [modifiers](https://salty-css.dev/docs/modifiers)                       |
+| [`withSaltyCss`](#withsaltycss-nextjs)          | `@salty-css/next`               | Next.js config wrapper (Webpack + Turbopack).                                 | [installation](https://salty-css.dev/docs/installation)                 |
+| [`saltyPlugin` (Vite)](#saltyplugin-vite)       | `@salty-css/vite`               | Vite plugin.                                                                  | [installation](https://salty-css.dev/docs/installation)                 |
+| [`saltyPlugin` (Webpack)](#saltyplugin-webpack) | `@salty-css/webpack`            | Webpack loader + plugin.                                                      | [installation](https://salty-css.dev/docs/installation)                 |
+| [`saltyIntegration`](#saltyintegration-astro)   | `@salty-css/astro/integration`  | Astro integration.                                                            | [installation](https://salty-css.dev/docs/installation)                 |
+
+---
+
+## `styled`
+
+```ts
+// components/button.css.ts
+import { styled } from '@salty-css/react/styled';
+
+export const Button = styled('button', {
+  className: 'btn', // optional custom class
+  element: 'button', // optional element override
+  base: {
+    padding: '0.6em 1.2em',
+    border: '1px solid currentColor',
+    '&:hover': { background: 'black', color: 'white' },
+  },
+  variants: {
+    variant: {
+      outlined: {},
+      solid: { background: 'black', color: 'white' },
+    },
+  },
+  compoundVariants: [
+    /* { variant: 'solid', size: 'lg', css: { ... } } */
+  ],
+  defaultVariants: { variant: 'outlined' },
+  defaultProps: { type: 'button' },
+  passProps: false, // pass variant props through to the rendered element
+  priority: undefined, // 0–8, higher wins; usually leave to auto
+});
+```
+
+```tsx
+<Button variant="solid">Save</Button>
+```
+
+See full reference → [salty-css.dev/docs/api/styled](https://salty-css.dev/docs/api/styled).
+
+## `className`
+
+Framework-agnostic class-string factory. The return value is a `string` you can drop in `className=`, plus a `.variant(name, value)` method for chaining variant classes.
+
+```ts
+// components/card.css.ts
+import { className } from '@salty-css/react/class-name';
+
+export const card = className({
+  className: 'card',
+  base: {
+    padding: '1rem',
+    borderRadius: '8px',
+  },
+  variants: {
+    tone: {
+      neutral: { background: '#f6f6f6' },
+      brand: { background: '{colors.brand.main}' },
+    },
+  },
+});
+```
+
+```tsx
+<div className={`${card.variant('tone', 'brand')}`}>Hello</div>
+```
+
+See full reference → [salty-css.dev/docs/api/classname](https://salty-css.dev/docs/api/classname).
+
+## Variants
+
+`styled` and `className` share the same variant shape:
+
+- **`variants`** — named axes (e.g. `size: { sm, md, lg }`). Each axis becomes a prop.
+- **`compoundVariants`** — array; styles applied only when **all** listed axes match.
+- **`anyOfVariants`** — array; styles applied when **any** listed axis matches.
+- **`defaultVariants`** — values used when the prop is omitted at the call site.
+
+```ts
+styled('a', {
+  base: { textDecoration: 'none' },
+  variants: {
+    size: { sm: { fontSize: 14 }, lg: { fontSize: 18 } },
+    underline: { true: { textDecoration: 'underline' } },
+  },
+  compoundVariants: [{ size: 'lg', underline: true, css: { textUnderlineOffset: 4 } }],
+  defaultVariants: { size: 'sm' },
+});
+```
+
+Boolean variants accept `true`/`false` keys; pass them as `<Link underline />` shorthand. See [salty-css.dev/docs/variants](https://salty-css.dev/docs/variants).
+
+## Overrides
+
+- **Extend any component:** `styled(ExistingComponent, { ... })`. The wrapped component must accept `className`.
+- **Swap the rendered element** for one instance: `<Button as="a" href="/x" />` (use `passProps` if you want variant props to reach the underlying element).
+- **Per-instance style overrides:** `<Box style={{ ... }} />` and `<Box css={{ ... }} />` accept regular React `style` and Salty's `css` prop (overrides apply at the highest priority).
+
+See [salty-css.dev/docs/overrides](https://salty-css.dev/docs/overrides) for `as`, `style`, CSS-variable overrides, and ref forwarding.
+
+## `defineConfig`
+
+```ts
+// salty.config.ts
+import { defineConfig } from '@salty-css/core/config';
+
+export const config = defineConfig({
+  importStrategy: 'root', // 'root' | 'component'
+  variables: {
+    /* see defineVariables */
+  },
+  global: {
+    /* see defineGlobalStyles */
+  },
+  templates: {
+    /* see defineTemplates */
+  },
+  modifiers: {
+    /* see Modifiers */
+  },
+  reset: 'default', // 'default' | 'none' | GlobalStyles
+  externalModules: ['react', 'react-dom'],
+  strict: true, // true | 'warn' | false
+  defaultUnit: 'px', // px, rem, em, vh, vw, % …
+});
+```
+
+Full reference → [salty-css.dev/docs/api/config](https://salty-css.dev/docs/api/config).
+
+## `defineVariables`
+
+Tokens come in three flavours — static, responsive (media-bound), conditional (class/data-attribute-bound):
+
+```ts
+// styles/variables.css.ts
+import { defineVariables } from '@salty-css/core/factories';
+
+export default defineVariables({
+  colors: {
+    dark: '#111',
+    light: '#fefefe',
+    brand: { main: '#0070f3', highlight: '#ff4081' },
+  },
+  responsive: {
+    base: { fontSize: { heading: '48px', body: '16px' } },
+    '@largeMobileDown': { fontSize: { heading: '32px', body: '14px' } },
+  },
+  conditional: {
+    theme: {
+      dark: { backgroundColor: '{colors.dark}', textColor: '{colors.light}' },
+      light: { backgroundColor: '{colors.light}', textColor: '{colors.dark}' },
+    },
+  },
+});
+```
+
+Use as string references: `{colors.brand.main}`, `{fontSize.heading}`, `{theme.textColor}`.
+
+See [salty-css.dev/docs/variables](https://salty-css.dev/docs/variables).
+
+## Theming
+
+The `conditional` bucket above wires up data-attribute / class-based themes with zero providers. Toggle a `data-theme` attribute on `<html>` (or any ancestor) and conditional variables resolve to the matching branch:
+
+```html
+<html data-theme="dark">
+  <!-- '{theme.textColor}' resolves to '{colors.light}' -->
+</html>
+```
+
+See the dark-mode walkthrough (with SSR flash fix) → [salty-css.dev/docs/theming](https://salty-css.dev/docs/theming).
+
+## `defineGlobalStyles`
+
+```ts
+// styles/global.css.ts
+import { defineGlobalStyles } from '@salty-css/core/factories';
+
+export default defineGlobalStyles({
+  html: { fontFamily: 'Inter, system-ui, sans-serif' },
+  body: { margin: 0, background: '#fff' },
+});
+```
+
+## `defineMediaQuery`
+
+```ts
+// styles/media.css.ts
+import { defineMediaQuery } from '@salty-css/core/factories';
+
+export const largeMobileDown = defineMediaQuery((media) => media.maxWidth(600));
+export const darkMode = defineMediaQuery((media) => media.prefersColorScheme('dark'));
+```
+
+```ts
+styled('span', { base: { fontSize: 64, '@largeMobileDown': { fontSize: 32 } } });
+```
+
+See [salty-css.dev/docs/media-queries](https://salty-css.dev/docs/media-queries).
+
+## `defineTemplates`
+
+Reusable style bundles. Static templates pick values by dot-path; function templates take a parameter.
+
+```ts
+// styles/templates.css.ts
+import { defineTemplates } from '@salty-css/core/factories';
+
+export default defineTemplates({
+  textStyle: {
+    heading: {
+      base: { fontFamily: '{fontFamily.heading}', lineHeight: 1.1 },
+      variants: {
+        weight: { regular: { fontWeight: 500 }, heavy: { fontWeight: 800 } },
+      },
+      large: { fontSize: '{fontSize.heading.large}' },
+      small: { fontSize: '{fontSize.heading.small}' },
+    },
+  },
+  card: (padding: string) => ({
+    padding,
+    borderRadius: 8,
+    boxShadow: '0 0 10px rgba(0,0,0,0.1)',
+  }),
+});
+```
+
+```ts
+styled('h1', { base: { textStyle: 'heading.large@weight=heavy', card: '20px' } });
+```
+
+Rich-node variants, inheritance, and the `compoundVariants`/`anyOfVariants` rules: [salty-css.dev/docs/templates](https://salty-css.dev/docs/templates).
+
+## `defineFont`
+
+```ts
+// styles/fonts.css.ts
+import { defineFont } from '@salty-css/core/factories';
+
+export const Inter = defineFont({
+  name: 'Inter',
+  variable: '--font-inter',
+  display: 'swap',
+  fallback: 'system-ui, sans-serif',
+  variants: [
+    { weight: 400, style: 'normal', src: '/fonts/inter-400.woff2' },
+    { weight: 700, style: 'normal', src: ['/fonts/inter-700.woff2', '/fonts/inter-700.ttf'] },
+  ],
+});
+
+// Or pull a remote stylesheet (e.g. Google Fonts) — emits @import + variable.
+export const InterCdn = defineFont({
+  name: 'Inter',
+  variable: '--font-inter',
+  import: 'https://fonts.googleapis.com/css2?family=Inter:wght@400;700&display=swap',
+});
+```
+
+`Inter.className`, `Inter.variable`, `Inter.fontFamily`, and `Inter.style` are available for explicit usage. See [salty-css.dev/docs/fonts](https://salty-css.dev/docs/fonts).
+
+## `defineImport`
+
+Pull external CSS into Salty's `imports` cascade layer (which sits **before** `reset`, `global`, `templates`, and your component layers — so your styles always win).
+
+```ts
+// styles/imports.css.ts
+import { defineImport } from '@salty-css/core/factories';
+
+export default defineImport(
+  './reset.css', // relative
+  'modern-normalize/modern-normalize.css', // node_modules
+  '~normalize.css/normalize.css', // node_modules (~ form)
+  '/fonts/inter.css', // public/ folder
+  'https://fonts.googleapis.com/css2?family=Inter', // URL
+  { url: './print.css', media: 'print' }, // media-conditional
+  { url: './p3.css', supports: 'color(display-p3 1 1 1)' }, // supports-conditional
+);
+```
+
+Layer order: `@layer imports, reset, global, templates, fonts, l0…l8;`. See [salty-css.dev/docs/imports](https://salty-css.dev/docs/imports).
+
+## `keyframes`
+
+```ts
+// styles/animations.css.ts
+import { keyframes } from '@salty-css/react/keyframes';
+
+export const fadeIn = keyframes({
+  animationName: 'fadeIn',
+  appendInitialStyles: true, // injects `from`/`0%` as base styles on the component
+  params: { delay: '250ms', fillMode: 'forwards' },
+  from: { opacity: 0 },
+  to: { opacity: 1 },
+});
+```
+
+```ts
+styled('div', { base: { animation: fadeIn } });
+```
+
+See [salty-css.dev/docs/animations](https://salty-css.dev/docs/animations).
+
+## `defineViewportClamp`
+
+```ts
+// styles/clamp.css.ts
+import { defineViewportClamp } from '@salty-css/core/helpers';
+
+export const fhdClamp = defineViewportClamp({ screenSize: 1920 });
+export const mobileClamp = defineViewportClamp({ screenSize: 640, axis: 'horizontal' });
+```
+
+```ts
+styled('span', { base: { fontSize: fhdClamp(96), '@largeMobileDown': { fontSize: mobileClamp(48) } } });
+```
+
+Options: `screenSize`, `axis` (`'horizontal' | 'vertical'`), `minMultiplier`, `maxMultiplier`, `minMaxUnit`. See [salty-css.dev/docs/viewport-clamp](https://salty-css.dev/docs/viewport-clamp).
+
+## `color`
+
+```ts
+import { color } from '@salty-css/core/helpers';
+import { styled } from '@salty-css/react/styled';
+
+export const Tint = styled('span', {
+  base: { backgroundColor: color('#000').alpha(0.5) },
+});
+```
+
+Backed by the [Qix-/color](https://github.com/Qix-/color) library — `.alpha()`, `.darken()`, `.lighten()`, `.mix()`, etc. See [salty-css.dev/docs/color-function](https://salty-css.dev/docs/color-function).
+
+## Modifiers
+
+Custom value transformers registered on `defineConfig`. Each modifier is a `{ pattern, transform }` pair: when Salty sees a string value matching `pattern`, it replaces it with `transform(match).value` (and optionally emits extra CSS via `transform(match).css`).
+
+```ts
+// salty.config.ts
+import { defineConfig } from '@salty-css/core/config';
+
+export const config = defineConfig({
+  modifiers: {
+    spaceShorthand: {
+      pattern: /^space:(\d+)$/,
+      transform: (match) => {
+        const n = Number(match.replace('space:', ''));
+        return { value: `${n * 4}px` };
+      },
+    },
+  },
+});
+```
+
+```ts
+styled('div', { base: { padding: 'space:3' } }); // → padding: 12px
+```
+
+See [salty-css.dev/docs/modifiers](https://salty-css.dev/docs/modifiers).
+
+## `withSaltyCss` (Next.js)
+
+```ts
+// next.config.ts
+import { withSaltyCss } from '@salty-css/next';
+
+const nextConfig = {
+  /* your config */
+};
+export default withSaltyCss(nextConfig);
+// Or pin a bundler: withSaltyCss(nextConfig, { bundler: 'webpack' })
+```
+
+Options: `mode` (build mode override), `bundler` (`'auto' | 'webpack' | 'turbopack'`, defaults to auto-detect via `process.env.TURBOPACK`), `dir` (project root for Turbopack — defaults to `nextConfig.turbopack.root` or `process.cwd()`).
+
+Next.js 14 CommonJS:
+
+```js
+const { withSaltyCss } = require('@salty-css/next');
+module.exports = withSaltyCss(nextConfig);
+```
+
+See [salty-css.dev/docs/installation](https://salty-css.dev/docs/installation).
+
+## `saltyPlugin` (Vite)
+
+```ts
+// vite.config.ts
+import { defineConfig } from 'vite';
+import { saltyPlugin } from '@salty-css/vite';
+
+export default defineConfig({
+  plugins: [saltyPlugin(__dirname)],
+});
+```
+
+Options: `{ mode }`.
+
+## `saltyPlugin` (Webpack)
+
+```js
+// webpack.config.js
+const { saltyPlugin } = require('@salty-css/webpack');
+
+module.exports = (env, argv) => {
+  const config = {
+    /* … */
+  };
+  saltyPlugin(config, __dirname);
+  return config;
+};
+```
+
+Signature: `saltyPlugin(config, dir, isServer?, cjs?, { mode? })`.
+
+## `saltyIntegration` (Astro)
+
+```ts
+// astro.config.mjs
+import { defineConfig } from 'astro/config';
+import saltyIntegration from '@salty-css/astro/integration';
+
+export default defineConfig({
+  integrations: [saltyIntegration()],
+});
+```
+
+Options: `srcDir` (defaults to `'src'`), `rootDir` (defaults to the Astro config root).
+
+---
+
+## Support
+
+Help, questions, or feedback → [Join the Salty CSS Discord](https://discord.gg/R6kr4KxMhP). Bug reports → [GitHub issues](https://github.com/margarita-form/salty-css/issues).

package/package.json

@@ -14,7 +14,7 @@
   "bugs": {
     "url": "https://github.com/margarita-form/salty-css/issues"
   },
-  "version": "0.2.2-refactor-vite-8.5",
+  "version": "0.2.2-refactor-vite-8.8",
   "type": "module",
   "scripts": {
     "build": "vite build",