@salty-css/core 0.1.0-alpha.3 → 0.1.0-alpha.31

package/README.md

@@ -57,6 +57,8 @@ To get help with problems, [Join Salty CSS Discord server](https://discord.gg/R6
 - [defineVariables](#variables) - create CSS variables (tokens) that can be used in any styling function
 - [defineMediaQuery](#media-queries) - create CSS media queries and use them in any styling function
 - [defineTemplates](#templates) - create reusable templates that can be applied when same styles are used over and over again
+- [defineFont](#custom-fonts) - register custom fonts via `@font-face` (or a remote stylesheet) and expose them as a CSS variable
+- [defineImport](#importing-additional-css) - pull in external CSS files (relative, public, node_modules, or URL)
 - [keyframes](#keyframes-animations) - create CSS keyframes animation that can be used and imported in any styling function
 
 ### Styling helpers & utility
@@ -319,6 +321,213 @@ Example usage:
 styled('div', { base: { textStyle: 'headline.large', card: '20px' } });
 ```
 
+### Template variants
+
+Static templates can opt into named variants by switching a node from a plain styles object to a "rich" shape with `base` and `variants` keys — the same authoring API as `styled`. Variants declared at a parent node are inherited by every descendant leaf, so one declaration of `weight` on `heading` flows down to `heading.large`, `heading.small`, etc.
+
+```ts
+// /styles/templates.css.ts
+import { defineTemplates } from '@salty-css/core/factories';
+
+export default defineTemplates({
+  textStyle: {
+    heading: {
+      // Rich node: variants declared here are available to every child leaf.
+      base: {
+        fontFamily: '{fontFamily.heading}',
+        lineHeight: '1.1em',
+      },
+      variants: {
+        weight: {
+          light: { fontWeight: 300 },
+          regular: { fontWeight: 500 },
+          heavy: { fontWeight: 800 },
+        },
+        italic: {
+          true: { fontStyle: 'italic' },
+        },
+      },
+      defaultVariants: {
+        weight: 'regular',
+      },
+      compoundVariants: [
+        // Applied when ALL listed axes match.
+        { weight: 'heavy', italic: true, css: { letterSpacing: '-0.01em' } },
+      ],
+      // Leaves can be plain styles…
+      small: { fontSize: '{fontSize.heading.small}' },
+      regular: { fontSize: '{fontSize.heading.regular}' },
+      // …or rich, with their own additional variants / overrides.
+      large: {
+        base: { fontSize: '{fontSize.heading.large}' },
+        variants: {
+          weight: {
+            // Override the inherited bundle just for `large`.
+            heavy: { fontWeight: 900, letterSpacing: '-0.02em' },
+          },
+        },
+      },
+    },
+  },
+});
+```
+
+Apply variants at the call site in either of two equivalent forms — string query or object:
+
+```ts
+styled('h1', {
+  base: {
+    // String form: `path@axis=value&axis=value&boolFlag`
+    textStyle: 'heading.large@weight=heavy&italic',
+  },
+});
+
+styled('h2', {
+  base: {
+    // Object form: `name` is the dot-path, the rest are axis values.
+    textStyle: { name: 'heading.large', weight: 'heavy', italic: true },
+  },
+});
+
+// No variants — existing simple usage still works.
+styled('p', { base: { textStyle: 'heading.regular' } });
+```
+
+Behaviour worth knowing:
+
+- **Inheritance is parent → leaf only.** A leaf sees variants from its ancestors; siblings and children are invisible.
+- **Closest wins.** If the same axis/value bundle is declared at multiple levels, the deepest one replaces (not merges) the ancestor's bundle for that single call.
+- **`defaultVariants` apply when the call site omits an axis.** Walked bottom-up, same closest-wins rule.
+- **`compoundVariants` (AND) and `anyOfVariants` (OR) are accumulated top-down** across the path — every matching rule contributes.
+- **Boolean axes accept a shorthand.** `@italic` is equivalent to `@italic=true`; in object form pass `italic: true`.
+- **Reserved keys** inside a rich node: `base`, `variants`, `defaultVariants`, `compoundVariants`, `anyOfVariants`. Don't use `name` as an axis (reserved for the object call-site form).
+- **Function templates** (e.g. `card: (v) => ({ … })`) don't support variants — keep them as plain functions.
+
+## Custom fonts
+
+Register custom fonts that will be emitted as `@font-face` declarations and exposed as a CSS variable. Mirrors the developer experience of Next.js / Astro font loaders, but generated at build time alongside the rest of your Salty CSS output.
+
+The returned object stringifies to its `font-family` value and exposes helpers for explicit usage:
+
+- `Font.variable` → CSS variable name (e.g. `--font-inter`)
+- `Font.fontFamily` → final `font-family` string with fallbacks
+- `Font.className` → class that sets the variable + applies the font on a subtree
+- `Font.style` → object you can spread on a React `style` prop
+
+```ts
+// /styles/fonts.css.ts
+import { defineFont } from '@salty-css/core/factories';
+
+// 1. Local or self-hosted @font-face sources.
+//    URLs are passed through as-is (use a public-folder path or a CDN URL).
+export const Inter = defineFont({
+  name: 'Inter', // CSS font-family value
+  variable: '--font-inter', // Optional — accepts 'font-inter' too; if omitted we derive `--font-<name>-<hash>` from the inputs
+  display: 'swap', // Optional default applied to variants without their own `display`
+  fallback: ['system-ui', 'sans-serif'], // Optional family fallbacks appended after `name`
+  variants: [
+    {
+      weight: 400,
+      style: 'normal',
+      // Shorthand: pass a string and the `format()` descriptor is auto-detected
+      // from the file extension (woff2, woff, ttf, otf, eot, svg, ttc).
+      src: '/fonts/inter-400.woff2',
+    },
+    {
+      weight: 700,
+      style: 'normal',
+      // Multiple sources can be a string array — first entry is preferred;
+      // the browser picks the first format it supports.
+      src: ['/fonts/inter-700.woff2', '/fonts/inter-700.ttf'],
+    },
+    {
+      weight: 400,
+      style: 'italic',
+      // Use the `{ url, format }` object form when the URL has no recognisable
+      // extension (signed CDN URLs, query-only endpoints, etc.). You can also
+      // mix strings and objects in the same array.
+      src: ['/fonts/inter-400-italic.woff2', { url: 'https://cdn.example.com/inter-italic', format: 'woff' }],
+    },
+  ],
+});
+
+// 2. Remote stylesheet (Google Fonts, etc.). Emits `@import url(...)` and still
+//    registers the CSS variable so usage stays the same as the @font-face flow.
+export const InterCdn = defineFont({
+  name: 'Inter',
+  variable: '--font-inter',
+  import: 'https://fonts.googleapis.com/css2?family=Inter:wght@400;700&display=swap',
+});
+```
+
+Example usage:
+
+```tsx
+import { Inter } from './fonts.css';
+import { styled } from '@salty-css/react/styled';
+
+// Apply the font globally by attaching its className high up in the tree.
+// This sets `--font-inter` on the subtree and applies `font-family: var(--font-inter)`.
+export const App = ({ children }) => <div className={Inter.className}>{children}</div>;
+
+// `Inter` stringifies to its font-family value (with fallbacks), so it can be used directly.
+export const Heading = styled('h1', {
+  base: {
+    fontFamily: `${Inter}`,
+  },
+});
+
+// Or reference the CSS variable explicitly.
+export const Body = styled('p', {
+  base: {
+    fontFamily: `var(${Inter.variable})`,
+  },
+});
+```
+
+## Importing additional CSS
+
+Use `defineImport` to pull in CSS that lives outside of Salty's authoring API — a reset stylesheet from npm, a Google Fonts URL, an asset in your app's `public/` folder, or a sibling `.css` file. The compiler turns each spec into an `@import` rule in the generated `saltygen/index.css`, so the imported stylesheets travel with the rest of your build.
+
+```ts
+// /styles/imports.css.ts
+import { defineImport } from '@salty-css/core/factories';
+
+export default defineImport(
+  // Relative to this file
+  './reset.css',
+  // From node_modules (bare specifier — same as Vite / native CSS @import)
+  'modern-normalize/modern-normalize.css',
+  // From node_modules (~ prefix — same resolver, webpack-style)
+  '~normalize.css/normalize.css',
+  // From your app's public/ folder (served at the host root)
+  '/fonts/inter.css',
+  // External URL
+  'https://fonts.googleapis.com/css2?family=Inter&display=swap',
+  // Object form — attach media or supports() conditions
+  { url: './print.css', media: 'print' },
+  { url: './p3.css', supports: 'color(display-p3 1 1 1)' }
+);
+```
+
+Path resolution:
+
+| Pattern                     | Behaviour                                                                                |
+| --------------------------- | ---------------------------------------------------------------------------------------- |
+| `http://`, `https://`, `//` | Emitted verbatim                                                                         |
+| Starts with `/`             | Public-folder URL — emitted verbatim, the browser resolves it against your host          |
+| Starts with `./` or `../`   | Resolved at build time relative to the file that called `defineImport`                   |
+| `~package/file.css`         | Stripped of the leading `~`, then resolved from `node_modules` and copied into the build |
+| `package/file.css` (bare)   | Same `node_modules` resolution as the `~` form                                           |
+
+All imports are placed inside a new `imports` cascade layer that sits **before** `reset`, `global`, `templates`, and your component styles. This means your own styles always win over third-party CSS you pull in — which is what most teams expect when they drop in something like `modern-normalize`.
+
+The full layer order in the generated `index.css` is:
+
+```css
+@layer imports, reset, global, templates, l0, l1, l2, l3, l4, l5, l6, l7, l8;
+```
+
 ## Keyframes animations
 
 ```ts

package/astro-component-5hrNTCJ5.js

@@ -0,0 +1,4 @@
+const astroComponent = "---\nimport { <%- styledComponentName %> } from './<%- fileName %>.css';\n\ninterface Props {\n  text?: string;\n}\n\nconst { text = 'Lorem ipsum' } = Astro.props;\n---\n\n<<%- styledComponentName %>>\n  {text}\n</<%- styledComponentName %>>\n";
+export {
+  astroComponent as default
+};

package/astro-component-Dj3enX6K.cjs

@@ -0,0 +1,4 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const astroComponent = "---\nimport { <%- styledComponentName %> } from './<%- fileName %>.css';\n\ninterface Props {\n  text?: string;\n}\n\nconst { text = 'Lorem ipsum' } = Astro.props;\n---\n\n<<%- styledComponentName %>>\n  {text}\n</<%- styledComponentName %>>\n";
+exports.default = astroComponent;

package/bin/commands/build.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare const registerBuildCommand: (program: Command, defaultProject: string | undefined) => void;

package/bin/commands/generate.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare const registerGenerateCommand: (program: Command, defaultProject: string | undefined) => void;

package/bin/commands/init.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare const registerInitCommand: (program: Command) => void;

package/bin/commands/update.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare const registerUpdateCommand: (program: Command) => void;

package/bin/commands/version.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare const registerVersionOption: (program: Command) => void;

package/bin/confirm-install.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Renders a single package spec for display. Translates the internal
+ * `'-D <pkg>@<ver>'` shorthand used by `npmInstall` into a `<pkg>@<ver> (dev)`
+ * suffix so the user-facing list reads naturally.
+ */
+export declare const formatPackageForDisplay: (spec: string) => string;
+export declare const renderPackageList: (packages: string[]) => string;
+export interface ConfirmInstallOptions {
+    /** Streams used for the prompt — defaults to process.stdin/stdout. Allows tests to inject. */
+    input?: NodeJS.ReadableStream;
+    output?: NodeJS.WritableStream;
+    /** Whether the input is a TTY — defaults to process.stdin.isTTY. Allows tests to override. */
+    isTTY?: boolean;
+}
+/**
+ * Confirm a batched install. Resolves on success, throws on decline.
+ *
+ * - `yes=true` or empty `packages` → no prompt, resolves immediately.
+ * - Non-TTY without `yes` → throws, telling the user to pass `--yes`.
+ * - Otherwise prints the list and asks `Proceed? (y/N)`. Accepts y/yes
+ *   (case-insensitive); anything else throws to abort the command.
+ */
+export declare const confirmInstall: (packages: string[], yes: boolean, options?: ConfirmInstallOptions) => Promise<void>;
+export interface ConfirmYesNoOptions extends ConfirmInstallOptions {
+    /** When true, resolves true without prompting. */
+    yes?: boolean;
+    /** When true, an empty answer counts as yes. Defaults to false (empty = no). */
+    defaultYes?: boolean;
+}
+/**
+ * Generic yes/no prompt. Unlike `confirmInstall`, non-TTY without `yes`
+ * resolves `false` instead of throwing — callers can choose policy.
+ */
+export declare const confirmYesNo: (question: string, options?: ConfirmYesNoOptions) => Promise<boolean>;

package/bin/context.d.ts

@@ -0,0 +1,22 @@
+import { RCFile } from '../types/cli-types';
+import { PackageJson } from './package-json';
+export interface ProjectContext {
+    cwd: string;
+    projectDir: string;
+    relativeProjectPath: string;
+    packageJson?: PackageJson;
+    rcFile: RCFile;
+    cliVersion: string;
+    skipInstall: boolean;
+    yes: boolean;
+}
+export declare const resolveProjectDir: (dir: string, rootDir?: string) => string;
+export interface BuildContextOptions {
+    dir: string;
+    skipInstall?: boolean;
+    /** Skip the install confirmation prompt and install without asking. */
+    yes?: boolean;
+    /** When false, build context even if package.json is missing (used by commands that should not require one). */
+    requirePackageJson?: boolean;
+}
+export declare const buildContext: (opts: BuildContextOptions) => Promise<ProjectContext>;

package/bin/detection/css-file.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Looks for a global CSS file inside `projectDir` and returns its path relative to it,
+ * or undefined when none is found.
+ */
+export declare const findGlobalCssFile: (projectDir: string) => Promise<string | undefined>;

package/bin/frameworks/astro.d.ts

@@ -0,0 +1,4 @@
+import { FrameworkAdapter } from './types';
+export declare const astroConfigFiles: readonly ["astro.config.mjs", "astro.config.ts", "astro.config.js", "astro.config.cjs"];
+export declare const findAstroConfig: (projectDir: string) => string | null;
+export declare const astroFramework: FrameworkAdapter;

package/bin/frameworks/index.d.ts

@@ -0,0 +1,13 @@
+import { ProjectContext } from '../context';
+import { FrameworkAdapter, FrameworkName } from './types';
+/**
+ * Adapters are evaluated in this order; the first whose `detect()` returns true wins.
+ * React is the final fallback, so its `detect()` always returns true.
+ */
+export declare const frameworkRegistry: FrameworkAdapter[];
+export declare const frameworksByName: Record<FrameworkName, FrameworkAdapter>;
+export declare const detectFramework: (ctx: ProjectContext) => Promise<FrameworkAdapter>;
+export declare const getFramework: (name: string | undefined) => FrameworkAdapter | undefined;
+export type { FrameworkAdapter, FrameworkName } from './types';
+export { reactFramework } from './react';
+export { astroFramework, findAstroConfig, astroConfigFiles } from './astro';

package/bin/frameworks/react.d.ts

@@ -0,0 +1,2 @@
+import { FrameworkAdapter } from './types';
+export declare const reactFramework: FrameworkAdapter;

package/bin/frameworks/types.d.ts

@@ -0,0 +1,27 @@
+import { ProjectContext } from '../context';
+import { TemplateKey } from '../templates';
+export type FrameworkName = 'react' | 'astro';
+export interface ComponentTemplates {
+    /** Template used for the styled-file when the wrapper component is requested. */
+    styled: TemplateKey;
+    /** Template used for the wrapper component file. */
+    wrapper: TemplateKey;
+    /** Extension for the wrapper component file (including dot), e.g. '.tsx' or '.astro'. */
+    wrapperExt: string;
+}
+export interface FrameworkAdapter {
+    name: FrameworkName;
+    /** The path to the framework's source files. */
+    srcDirectory: string;
+    /** True when this framework matches the project. Adapters are evaluated in registry order. */
+    detect(ctx: ProjectContext): Promise<boolean> | boolean;
+    /** The runtime npm spec to install for this framework, e.g. `@salty-css/react@1.2.3`. */
+    runtimePackage(version: string): string;
+    /** Templates used by the `generate` command. */
+    templates: {
+        /** Template used for a standalone styled-file (no wrapper). */
+        styled: TemplateKey;
+        /** Optional wrapper component templates. Omit if the framework does not support `--reactComponent`. */
+        component?: ComponentTemplates;
+    };
+}

package/bin/integrations/astro.d.ts

@@ -0,0 +1,11 @@
+import { BuildIntegrationAdapter, ConfigEdit } from './types';
+export declare const astroPackage: (version: string) => string;
+/**
+ * Returns the new content of an Astro config (with saltyIntegration wired in),
+ * or `{ content: null }` if the integration is already present or if no safe
+ * insertion point was found.
+ */
+export declare const editAstroConfig: (existing: string) => ConfigEdit & {
+    warning?: string;
+};
+export declare const astroIntegration: BuildIntegrationAdapter;

package/bin/integrations/eslint.d.ts

@@ -0,0 +1,6 @@
+import { BuildIntegrationAdapter, ConfigEdit } from './types';
+export declare const eslintConfigCandidates: (projectDir: string, rootDir: string) => string[];
+export declare const editEslintConfig: (existing: string, isJsFlat: boolean) => ConfigEdit & {
+    warning?: string;
+};
+export declare const eslintIntegration: BuildIntegrationAdapter;

package/bin/integrations/index.d.ts

@@ -0,0 +1,21 @@
+import { ProjectContext } from '../context';
+import { BuildIntegrationAdapter, IntegrationPlan } from './types';
+export declare const buildIntegrationRegistry: BuildIntegrationAdapter[];
+export interface PlannedIntegration {
+    name: string;
+    configPath: string;
+    plan: IntegrationPlan;
+}
+/** Detect every integration that has work to do and compute its plan. */
+export declare const planIntegrations: (ctx: ProjectContext) => Promise<PlannedIntegration[]>;
+/** Execute each previously-planned integration (writes config files). */
+export declare const applyIntegrationPlans: (planned: PlannedIntegration[]) => Promise<{
+    name: string;
+    configPath: string;
+    changed: boolean;
+}[]>;
+export type { BuildIntegrationAdapter, ConfigEdit, IntegrationPlan } from './types';
+export { viteIntegration, editViteConfig, vitePackage } from './vite';
+export { nextIntegration, editNextConfig, nextPackage, nextConfigFiles } from './next';
+export { astroIntegration, editAstroConfig, astroPackage } from './astro';
+export { eslintIntegration, editEslintConfig, eslintConfigCandidates } from './eslint';

package/bin/integrations/next.d.ts

@@ -0,0 +1,9 @@
+import { BuildIntegrationAdapter, ConfigEdit } from './types';
+export declare const nextConfigFiles: readonly ["next.config.js", "next.config.cjs", "next.config.ts", "next.config.mjs"];
+export declare const nextPackage: (version: string) => string;
+/**
+ * Returns the new content of a Next.js config (with withSaltyCss wired in),
+ * or `{ content: null }` if the plugin is already present.
+ */
+export declare const editNextConfig: (existing: string) => ConfigEdit;
+export declare const nextIntegration: BuildIntegrationAdapter;

package/bin/integrations/types.d.ts

@@ -0,0 +1,29 @@
+import { ProjectContext } from '../context';
+export interface IntegrationApplyResult {
+    /** Whether any file was edited or any install was performed. */
+    changed: boolean;
+}
+/**
+ * Pending integration work — the packages it would like installed and a
+ * closure that writes the config edits once the install (if any) has run.
+ */
+export interface IntegrationPlan {
+    /** Packages to install, using the same `npmInstall` shorthand (e.g. `'-D @salty-css/vite@1.2.3'`). */
+    packages: string[];
+    execute(): Promise<IntegrationApplyResult>;
+}
+export interface BuildIntegrationAdapter {
+    name: string;
+    /** Returns the config file path this integration targets, or null when not applicable. */
+    detect(ctx: ProjectContext): Promise<string | null> | string | null;
+    /**
+     * Idempotently produce the work needed to wire the integration in. Returns
+     * null when the integration is already wired (nothing to do).
+     */
+    plan(ctx: ProjectContext, configPath: string): Promise<IntegrationPlan | null>;
+}
+/** Pure transform — returned by an integration when it knows how to rewrite a config file. */
+export interface ConfigEdit {
+    /** New content to write, or null when no edit is needed. */
+    content: string | null;
+}

package/bin/integrations/vite.d.ts

@@ -0,0 +1,8 @@
+import { BuildIntegrationAdapter, ConfigEdit } from './types';
+export declare const vitePackage: (version: string) => string;
+/**
+ * Returns the new content of a Vite config (with the salty plugin wired in),
+ * or `{ content: null }` if the plugin is already present.
+ */
+export declare const editViteConfig: (existing: string) => ConfigEdit;
+export declare const viteIntegration: BuildIntegrationAdapter;