@salty-css/react 0.1.0-alpha.25 → 0.1.0-alpha.27

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,131 @@ 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})`,
+  },
+});
+```
+
+## 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salty-css/react",
-  "version": "0.1.0-alpha.25",
+  "version": "0.1.0-alpha.27",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
   "typings": "./dist/index.d.ts",
@@ -78,7 +78,7 @@
     }
   },
   "dependencies": {
-    "@salty-css/core": "^0.1.0-alpha.25",
+    "@salty-css/core": "^0.1.0-alpha.27",
     "clsx": ">=2.x",
     "react": ">=19.x || >=18.3.x"
   },