@salty-css/core 0.1.0-alpha.2 → 0.1.0-alpha.21

package/README.md

@@ -57,6 +57,7 @@ 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
 - [keyframes](#keyframes-animations) - create CSS keyframes animation that can be used and imported in any styling function
 
 ### Styling helpers & utility
@@ -319,6 +320,88 @@ Example usage:
 styled('div', { base: { textStyle: 'headline.large', card: '20px' } });
 ```
 
+## 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})`,
+  },
+});
+```
+
 ## 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;