@salty-css/core 0.1.0-alpha.27 → 0.1.0-alpha.28

package/README.md

@@ -321,6 +321,88 @@ 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.

package/{class-name-generator-BIYysuhW.cjs → class-name-generator-DZcz_NT4.cjs}

@@ -2,7 +2,7 @@
 var __defProp = Object.defineProperty;
 var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
 var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
-const parseStyles = require("./parse-styles-jPtMfgXH.cjs");
+const parseStyles = require("./parse-styles-BFoV7HiL.cjs");
 const dashCase = require("./dash-case-DIwKaYgE.cjs");
 const toHash = require("./to-hash-C05Y906F.cjs");
 class StylesGenerator {

package/{class-name-generator-B2LriwKm.js → class-name-generator-zQ8zLbPI.js}

@@ -1,7 +1,7 @@
 var __defProp = Object.defineProperty;
 var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
 var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
-import { p as parseAndJoinStyles } from "./parse-styles--vHKY6Mw.js";
+import { p as parseAndJoinStyles } from "./parse-styles-CtA-RKqt.js";
 import { d as dashCase } from "./dash-case-DblXvymC.js";
 import { t as toHash } from "./to-hash-DAN2LcHK.js";
 class StylesGenerator {

package/compiler/salty-compiler.cjs

@@ -14,7 +14,7 @@ const dashCase = require("../dash-case-DIwKaYgE.cjs");
 const toHash = require("../to-hash-C05Y906F.cjs");
 const defineTemplates = require("../define-templates-Deq1aCbN.cjs");
 const module$1 = require("module");
-const parseStyles = require("../parse-styles-jPtMfgXH.cjs");
+const parseStyles = require("../parse-styles-BFoV7HiL.cjs");
 const css_merge = require("../css/merge.cjs");
 const parsers_index = require("../parsers/index.cjs");
 const moduleType = require("../util/module-type");
@@ -553,6 +553,7 @@ ${css}
       const templates = css_merge.mergeObjects(config.templates, generationResults.templates);
       const templateStylesString = await parsers_index.parseTemplates(templates);
       const templateTokens = parsers_index.getTemplateTypes(templates);
+      const templateVariantMaps = parsers_index.getTemplateVariantMaps(templates);
       fs.writeFileSync(templateStylesPath, `@layer templates { ${templateStylesString} }`);
       configCacheContent.templates = templates;
       const importsPath = path.join(destDir, "css/_imports.css");
@@ -592,16 +593,38 @@ ${css}
       }
       const tsTokensPath = path.join(destDir, "types/css-tokens.d.ts");
       const tsVariableTokens = [...variableTokens].join("|");
+      const pascal = (str) => str.split(/[.\-_]/).filter(Boolean).map((s) => s.charAt(0).toUpperCase() + s.slice(1)).join("");
+      const templateVariantMapEntries = Object.entries(templateVariantMaps);
+      const hasVariantMaps = templateVariantMapEntries.some(([, pathMap]) => Object.keys(pathMap).length > 0);
+      const tsTemplateVariantMap = hasVariantMaps ? `type TemplateVariantTokens = {
+        ${templateVariantMapEntries.filter(([, pathMap]) => Object.keys(pathMap).length > 0).map(([templateKey, pathMap]) => {
+        const pathEntries = Object.entries(pathMap).map(
+          ([dotPath, axes]) => `'${dotPath}': { ${Object.entries(axes).map(([axis, valueType]) => `${axis}?: ${valueType}`).join("; ")} }`
+        ).join(";\n          ");
+        return `${templateKey}: {
+          ${pathEntries}
+        }`;
+      }).join(";\n        ")}
+      }` : `type TemplateVariantTokens = Record<string, Record<string, Record<string, never>>>;`;
+      const tsTemplateVariantAliases = templateVariantMapEntries.flatMap(
+        ([templateKey, pathMap]) => Object.keys(pathMap).map(
+          (dotPath) => `type ${pascal(templateKey)}${pascal(dotPath)}Variants = TemplateVariantTokens['${templateKey}']['${dotPath}'];`
+        )
+      ).join("\n      ");
       const tsTokensTypes = `
       // Variable types
-      type VariableTokens = ${tsVariableTokens || `''`}; 
+      type VariableTokens = ${tsVariableTokens || `''`};
       type PropertyValueToken = \`{\${VariableTokens}}\`;
-    
+
       // Template types
       type TemplateTokens = {
         ${Object.entries(templateTokens).map(([key, value]) => `${key}?: ${value}`).join("\n")}
       }
-    
+
+      // Template variant types (per docs/template-variants-spec.md §7)
+      ${tsTemplateVariantMap}
+      ${tsTemplateVariantAliases}
+
       // Media query types
       type MediaQueryKeys = ${mediaQueryKeys || `''`};
       `;

package/compiler/salty-compiler.js

@@ -12,9 +12,9 @@ import { d as dashCase } from "../dash-case-DblXvymC.js";
 import { t as toHash } from "../to-hash-DAN2LcHK.js";
 import { d as defineTemplates } from "../define-templates-CVhhgPnd.js";
 import { createRequire } from "module";
-import { p as parseAndJoinStyles, b as parseVariableTokens } from "../parse-styles--vHKY6Mw.js";
+import { p as parseAndJoinStyles, b as parseVariableTokens } from "../parse-styles-CtA-RKqt.js";
 import { mergeObjects, mergeFactories } from "../css/merge.js";
-import { parseTemplates, getTemplateTypes } from "../parsers/index.js";
+import { parseTemplates, getTemplateTypes, getTemplateVariantMaps } from "../parsers/index.js";
 import { detectCurrentModuleType } from "../util/module-type";
 import console from "console";
 const logger = createLogger({
@@ -534,6 +534,7 @@ ${css}
       const templates = mergeObjects(config.templates, generationResults.templates);
       const templateStylesString = await parseTemplates(templates);
       const templateTokens = getTemplateTypes(templates);
+      const templateVariantMaps = getTemplateVariantMaps(templates);
       writeFileSync(templateStylesPath, `@layer templates { ${templateStylesString} }`);
       configCacheContent.templates = templates;
       const importsPath = join(destDir, "css/_imports.css");
@@ -573,16 +574,38 @@ ${css}
       }
       const tsTokensPath = join(destDir, "types/css-tokens.d.ts");
       const tsVariableTokens = [...variableTokens].join("|");
+      const pascal = (str) => str.split(/[.\-_]/).filter(Boolean).map((s) => s.charAt(0).toUpperCase() + s.slice(1)).join("");
+      const templateVariantMapEntries = Object.entries(templateVariantMaps);
+      const hasVariantMaps = templateVariantMapEntries.some(([, pathMap]) => Object.keys(pathMap).length > 0);
+      const tsTemplateVariantMap = hasVariantMaps ? `type TemplateVariantTokens = {
+        ${templateVariantMapEntries.filter(([, pathMap]) => Object.keys(pathMap).length > 0).map(([templateKey, pathMap]) => {
+        const pathEntries = Object.entries(pathMap).map(
+          ([dotPath, axes]) => `'${dotPath}': { ${Object.entries(axes).map(([axis, valueType]) => `${axis}?: ${valueType}`).join("; ")} }`
+        ).join(";\n          ");
+        return `${templateKey}: {
+          ${pathEntries}
+        }`;
+      }).join(";\n        ")}
+      }` : `type TemplateVariantTokens = Record<string, Record<string, Record<string, never>>>;`;
+      const tsTemplateVariantAliases = templateVariantMapEntries.flatMap(
+        ([templateKey, pathMap]) => Object.keys(pathMap).map(
+          (dotPath) => `type ${pascal(templateKey)}${pascal(dotPath)}Variants = TemplateVariantTokens['${templateKey}']['${dotPath}'];`
+        )
+      ).join("\n      ");
       const tsTokensTypes = `
       // Variable types
-      type VariableTokens = ${tsVariableTokens || `''`}; 
+      type VariableTokens = ${tsVariableTokens || `''`};
       type PropertyValueToken = \`{\${VariableTokens}}\`;
-    
+
       // Template types
       type TemplateTokens = {
         ${Object.entries(templateTokens).map(([key, value]) => `${key}?: ${value}`).join("\n")}
       }
-    
+
+      // Template variant types (per docs/template-variants-spec.md §7)
+      ${tsTemplateVariantMap}
+      ${tsTemplateVariantAliases}
+
       // Media query types
       type MediaQueryKeys = ${mediaQueryKeys || `''`};
       `;

package/css/dynamic-styles.cjs

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const parseStyles = require("../parse-styles-jPtMfgXH.cjs");
+const parseStyles = require("../parse-styles-BFoV7HiL.cjs");
 const toHash = require("../to-hash-C05Y906F.cjs");
 const cache_resolveDynamicConfigCache = require("../cache/resolve-dynamic-config-cache.cjs");
 const getDynamicStylesClassName = (styles) => {

package/css/dynamic-styles.js

@@ -1,4 +1,4 @@
-import { a as parseStyles } from "../parse-styles--vHKY6Mw.js";
+import { a as parseStyles } from "../parse-styles-CtA-RKqt.js";
 import { t as toHash } from "../to-hash-DAN2LcHK.js";
 import { resolveDynamicConfigCache } from "../cache/resolve-dynamic-config-cache.js";
 const getDynamicStylesClassName = (styles) => {

package/css/keyframes.cjs

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const parseStyles = require("../parse-styles-jPtMfgXH.cjs");
+const parseStyles = require("../parse-styles-BFoV7HiL.cjs");
 const toHash = require("../to-hash-C05Y906F.cjs");
 const keyframes = ({ animationName: _name, params: _params, appendInitialStyles, ...keyframes2 }) => {
   const modifyKeyframes = async (params = {}) => {

package/css/keyframes.js

@@ -1,4 +1,4 @@
-import { p as parseAndJoinStyles } from "../parse-styles--vHKY6Mw.js";
+import { p as parseAndJoinStyles } from "../parse-styles-CtA-RKqt.js";
 import { t as toHash } from "../to-hash-DAN2LcHK.js";
 const keyframes = ({ animationName: _name, params: _params, appendInitialStyles, ...keyframes2 }) => {
   const modifyKeyframes = async (params = {}) => {

package/generators/index.cjs

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const classNameGenerator = require("../class-name-generator-BIYysuhW.cjs");
+const classNameGenerator = require("../class-name-generator-DZcz_NT4.cjs");
 const dashCase = require("../dash-case-DIwKaYgE.cjs");
 class StyledGenerator extends classNameGenerator.StylesGenerator {
   constructor(tagName, _params) {

package/generators/index.js

@@ -1,5 +1,5 @@
-import { S as StylesGenerator } from "../class-name-generator-B2LriwKm.js";
-import { C } from "../class-name-generator-B2LriwKm.js";
+import { S as StylesGenerator } from "../class-name-generator-zQ8zLbPI.js";
+import { C } from "../class-name-generator-zQ8zLbPI.js";
 import { d as dashCase } from "../dash-case-DblXvymC.js";
 class StyledGenerator extends StylesGenerator {
   constructor(tagName, _params) {

package/instances/classname-instance.cjs

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const classNameGenerator = require("../class-name-generator-BIYysuhW.cjs");
+const classNameGenerator = require("../class-name-generator-DZcz_NT4.cjs");
 const classNameInstance = (params) => {
   const generator = new classNameGenerator.ClassNameGenerator(params);
   const createClass = (classNameStr) => {

package/instances/classname-instance.js

@@ -1,4 +1,4 @@
-import { C as ClassNameGenerator } from "../class-name-generator-B2LriwKm.js";
+import { C as ClassNameGenerator } from "../class-name-generator-zQ8zLbPI.js";
 const classNameInstance = (params) => {
   const generator = new ClassNameGenerator(params);
   const createClass = (classNameStr) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salty-css/core",
-  "version": "0.1.0-alpha.27",
+  "version": "0.1.0-alpha.28",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
   "typings": "./dist/index.d.ts",

package/{parse-styles-jPtMfgXH.cjs → parse-styles-BFoV7HiL.cjs}

@@ -94,6 +94,170 @@ const reportParserIssue = (strict, message) => {
 const pseudoTypoRegex = /^&(hover|focus(-(visible|within))?|active|visited|checked|disabled|enabled|empty|target|first-child|last-child|first-of-type|last-of-type|placeholder|placeholder-shown|root)\b/;
 const templateLiteralLeftoverRegex = /\$\{[^}]+\}/;
 const bareAtRuleRegex = /^@(media|supports|container|layer)\s*$/;
+const isRichTemplateNode = (node) => {
+  if (!node || typeof node !== "object") return false;
+  if (Array.isArray(node)) return false;
+  const keys = Object.keys(node);
+  return keys.includes("base") || keys.includes("variants");
+};
+const parseTemplateCallSite = (value) => {
+  if (typeof value === "string") {
+    const [rawPath, rawQuery] = value.split("@", 2);
+    const path = rawPath.split(".").filter(Boolean);
+    if (!path.length) return void 0;
+    const variants = {};
+    if (rawQuery) {
+      for (const segment of rawQuery.split("&")) {
+        if (!segment) continue;
+        const eq = segment.indexOf("=");
+        if (eq === -1) {
+          variants[segment.trim()] = true;
+        } else {
+          const axis = segment.slice(0, eq).trim();
+          const raw = segment.slice(eq + 1).trim();
+          if (!axis) continue;
+          if (raw === "true") variants[axis] = true;
+          else if (raw === "false") variants[axis] = false;
+          else variants[axis] = raw;
+        }
+      }
+    }
+    return { path, variants };
+  }
+  if (value && typeof value === "object" && !Array.isArray(value)) {
+    const obj = value;
+    const name = obj["name"];
+    if (typeof name !== "string") return void 0;
+    const path = name.split(".").filter(Boolean);
+    if (!path.length) return void 0;
+    const variants = {};
+    for (const [k, v] of Object.entries(obj)) {
+      if (k === "name") continue;
+      if (typeof v === "string" || typeof v === "boolean") variants[k] = v;
+    }
+    return { path, variants };
+  }
+  return void 0;
+};
+const normalizeAxisValue = (v) => {
+  if (v === void 0) return void 0;
+  return typeof v === "boolean" ? String(v) : v;
+};
+const buildPathStack = (root, path) => {
+  const stack = [{ node: root, isRich: isRichTemplateNode(root) }];
+  let cursor = root;
+  for (const segment of path) {
+    if (cursor == null || typeof cursor !== "object") return void 0;
+    const next = cursor[segment];
+    if (next === void 0) return void 0;
+    stack.push({ node: next, isRich: isRichTemplateNode(next) });
+    cursor = next;
+  }
+  return stack;
+};
+const pathHasRichNode = (root, path) => {
+  const stack = buildPathStack(root, path);
+  if (!stack) return false;
+  return stack.some((entry) => entry.isRich);
+};
+const matchesAll = (entry, effective) => {
+  for (const [axis, raw] of Object.entries(entry)) {
+    if (axis === "css") continue;
+    if (effective[axis] !== normalizeAxisValue(raw)) return false;
+  }
+  return true;
+};
+const matchesAny = (entry, effective) => {
+  let any = false;
+  for (const [axis, raw] of Object.entries(entry)) {
+    if (axis === "css") continue;
+    any = true;
+    if (effective[axis] === normalizeAxisValue(raw)) return true;
+  }
+  return !any;
+};
+const resolveRichTemplate = (root, path, callSiteVariants, templateName) => {
+  var _a, _b, _c, _d;
+  const stack = buildPathStack(root, path);
+  if (!stack) return void 0;
+  const rich = stack.map((entry) => {
+    if (entry.isRich) return entry.node;
+    if (entry.node && typeof entry.node === "object" && !Array.isArray(entry.node)) {
+      const onlyChildKeys = Object.keys(entry.node).every((k) => entry.node[k] && typeof entry.node[k] === "object" && !isRichTemplateNode(entry.node[k]));
+      return onlyChildKeys ? {} : { base: entry.node };
+    }
+    return {};
+  });
+  const declaredAxes = /* @__PURE__ */ new Set();
+  for (const r of rich) {
+    if (r.variants) for (const k of Object.keys(r.variants)) declaredAxes.add(k);
+  }
+  for (const r of rich) {
+    if (r.defaultVariants) for (const k of Object.keys(r.defaultVariants)) declaredAxes.add(k);
+  }
+  const effective = {};
+  for (const axis of declaredAxes) {
+    if (axis in callSiteVariants) {
+      effective[axis] = normalizeAxisValue(callSiteVariants[axis]);
+      continue;
+    }
+    for (let i = rich.length - 1; i >= 0; i--) {
+      const d = (_a = rich[i].defaultVariants) == null ? void 0 : _a[axis];
+      if (d !== void 0) {
+        effective[axis] = normalizeAxisValue(d);
+        break;
+      }
+    }
+  }
+  for (const [axis, raw] of Object.entries(callSiteVariants)) {
+    if (!declaredAxes.has(axis)) {
+      console.warn(`Template "${templateName}" path "${path.join(".")}" has no variant axis "${axis}"; ignored.`);
+      continue;
+    }
+    const wanted = normalizeAxisValue(raw);
+    let found = false;
+    for (const r of rich) {
+      if (((_b = r.variants) == null ? void 0 : _b[axis]) && wanted !== void 0 && wanted in r.variants[axis]) {
+        found = true;
+        break;
+      }
+    }
+    if (!found && wanted !== void 0) {
+      const anyBundle = rich.some((r) => r.variants && axis in r.variants);
+      if (anyBundle) {
+        console.warn(`Template "${templateName}" axis "${axis}" has no value "${wanted}" on path "${path.join(".")}"; ignored.`);
+      }
+    }
+  }
+  const acc = {};
+  for (const r of rich) {
+    if (r.base) Object.assign(acc, r.base);
+  }
+  for (const axis of Object.keys(effective)) {
+    const value = effective[axis];
+    if (value === void 0) continue;
+    for (let i = rich.length - 1; i >= 0; i--) {
+      const bundle = (_d = (_c = rich[i].variants) == null ? void 0 : _c[axis]) == null ? void 0 : _d[value];
+      if (bundle) {
+        Object.assign(acc, bundle);
+        break;
+      }
+    }
+  }
+  for (const r of rich) {
+    if (r.compoundVariants) {
+      for (const entry of r.compoundVariants) {
+        if (matchesAll(entry, effective) && entry.css) Object.assign(acc, entry.css);
+      }
+    }
+    if (r.anyOfVariants) {
+      for (const entry of r.anyOfVariants) {
+        if (matchesAny(entry, effective) && entry.css) Object.assign(acc, entry.css);
+      }
+    }
+  }
+  return acc;
+};
 const parseStyles = async (styles, currentScope = "", config, omitTemplates = false) => {
   if (!styles) throw new Error("No styles provided to parseStyles function!");
   const cssStyles = /* @__PURE__ */ new Set();
@@ -137,13 +301,29 @@ const parseStyles = async (styles, currentScope = "", config, omitTemplates = fa
     }
     if ((config == null ? void 0 : config.templates) && config.templates[_key]) {
       if (omitTemplates) return void 0;
-      const path = value.split(".");
-      const templateStyles = path.reduce((acc, key2) => acc[key2], config.templates[_key]);
-      if (templateStyles) {
-        const [result] = await parseStyles(templateStyles, "");
-        return result;
+      const root = config.templates[_key];
+      const callSite = parseTemplateCallSite(value);
+      if (callSite) {
+        const { path, variants } = callSite;
+        const hasCallSiteVariants = Object.keys(variants).length > 0;
+        if (hasCallSiteVariants || pathHasRichNode(root, path)) {
+          const resolved2 = resolveRichTemplate(root, path, variants, _key);
+          if (resolved2) {
+            const [result] = await parseStyles(resolved2, "");
+            return result;
+          }
+          console.warn(`Template "${_key}" with path of "${path.join(".")}" was not found in config!`);
+          return void 0;
+        }
+        const templateStyles = path.reduce((acc, key2) => acc == null ? void 0 : acc[key2], root);
+        if (templateStyles) {
+          const [result] = await parseStyles(templateStyles, "");
+          return result;
+        }
+        console.warn(`Template "${_key}" with path of "${path.join(".")}" was not found in config!`);
+        return void 0;
       }
-      console.warn(`Template "${_key}" with path of "${value}" was not found in config!`);
+      console.warn(`Template "${_key}" received an unsupported call-site value.`);
       return void 0;
     }
     const isVariantArrayKey = _key === "compoundVariants" || _key === "anyOfVariants";
@@ -323,6 +503,7 @@ const combineSelectors = (currentScope, key) => {
   }
   return combos.join(", ");
 };
+exports.isRichTemplateNode = isRichTemplateNode;
 exports.parseAndJoinStyles = parseAndJoinStyles;
 exports.parseStyles = parseStyles;
 exports.parseValueModifiers = parseValueModifiers;

package/{parse-styles--vHKY6Mw.js → parse-styles-CtA-RKqt.js}

@@ -93,6 +93,170 @@ const reportParserIssue = (strict, message) => {
 const pseudoTypoRegex = /^&(hover|focus(-(visible|within))?|active|visited|checked|disabled|enabled|empty|target|first-child|last-child|first-of-type|last-of-type|placeholder|placeholder-shown|root)\b/;
 const templateLiteralLeftoverRegex = /\$\{[^}]+\}/;
 const bareAtRuleRegex = /^@(media|supports|container|layer)\s*$/;
+const isRichTemplateNode = (node) => {
+  if (!node || typeof node !== "object") return false;
+  if (Array.isArray(node)) return false;
+  const keys = Object.keys(node);
+  return keys.includes("base") || keys.includes("variants");
+};
+const parseTemplateCallSite = (value) => {
+  if (typeof value === "string") {
+    const [rawPath, rawQuery] = value.split("@", 2);
+    const path = rawPath.split(".").filter(Boolean);
+    if (!path.length) return void 0;
+    const variants = {};
+    if (rawQuery) {
+      for (const segment of rawQuery.split("&")) {
+        if (!segment) continue;
+        const eq = segment.indexOf("=");
+        if (eq === -1) {
+          variants[segment.trim()] = true;
+        } else {
+          const axis = segment.slice(0, eq).trim();
+          const raw = segment.slice(eq + 1).trim();
+          if (!axis) continue;
+          if (raw === "true") variants[axis] = true;
+          else if (raw === "false") variants[axis] = false;
+          else variants[axis] = raw;
+        }
+      }
+    }
+    return { path, variants };
+  }
+  if (value && typeof value === "object" && !Array.isArray(value)) {
+    const obj = value;
+    const name = obj["name"];
+    if (typeof name !== "string") return void 0;
+    const path = name.split(".").filter(Boolean);
+    if (!path.length) return void 0;
+    const variants = {};
+    for (const [k, v] of Object.entries(obj)) {
+      if (k === "name") continue;
+      if (typeof v === "string" || typeof v === "boolean") variants[k] = v;
+    }
+    return { path, variants };
+  }
+  return void 0;
+};
+const normalizeAxisValue = (v) => {
+  if (v === void 0) return void 0;
+  return typeof v === "boolean" ? String(v) : v;
+};
+const buildPathStack = (root, path) => {
+  const stack = [{ node: root, isRich: isRichTemplateNode(root) }];
+  let cursor = root;
+  for (const segment of path) {
+    if (cursor == null || typeof cursor !== "object") return void 0;
+    const next = cursor[segment];
+    if (next === void 0) return void 0;
+    stack.push({ node: next, isRich: isRichTemplateNode(next) });
+    cursor = next;
+  }
+  return stack;
+};
+const pathHasRichNode = (root, path) => {
+  const stack = buildPathStack(root, path);
+  if (!stack) return false;
+  return stack.some((entry) => entry.isRich);
+};
+const matchesAll = (entry, effective) => {
+  for (const [axis, raw] of Object.entries(entry)) {
+    if (axis === "css") continue;
+    if (effective[axis] !== normalizeAxisValue(raw)) return false;
+  }
+  return true;
+};
+const matchesAny = (entry, effective) => {
+  let any = false;
+  for (const [axis, raw] of Object.entries(entry)) {
+    if (axis === "css") continue;
+    any = true;
+    if (effective[axis] === normalizeAxisValue(raw)) return true;
+  }
+  return !any;
+};
+const resolveRichTemplate = (root, path, callSiteVariants, templateName) => {
+  var _a, _b, _c, _d;
+  const stack = buildPathStack(root, path);
+  if (!stack) return void 0;
+  const rich = stack.map((entry) => {
+    if (entry.isRich) return entry.node;
+    if (entry.node && typeof entry.node === "object" && !Array.isArray(entry.node)) {
+      const onlyChildKeys = Object.keys(entry.node).every((k) => entry.node[k] && typeof entry.node[k] === "object" && !isRichTemplateNode(entry.node[k]));
+      return onlyChildKeys ? {} : { base: entry.node };
+    }
+    return {};
+  });
+  const declaredAxes = /* @__PURE__ */ new Set();
+  for (const r of rich) {
+    if (r.variants) for (const k of Object.keys(r.variants)) declaredAxes.add(k);
+  }
+  for (const r of rich) {
+    if (r.defaultVariants) for (const k of Object.keys(r.defaultVariants)) declaredAxes.add(k);
+  }
+  const effective = {};
+  for (const axis of declaredAxes) {
+    if (axis in callSiteVariants) {
+      effective[axis] = normalizeAxisValue(callSiteVariants[axis]);
+      continue;
+    }
+    for (let i = rich.length - 1; i >= 0; i--) {
+      const d = (_a = rich[i].defaultVariants) == null ? void 0 : _a[axis];
+      if (d !== void 0) {
+        effective[axis] = normalizeAxisValue(d);
+        break;
+      }
+    }
+  }
+  for (const [axis, raw] of Object.entries(callSiteVariants)) {
+    if (!declaredAxes.has(axis)) {
+      console.warn(`Template "${templateName}" path "${path.join(".")}" has no variant axis "${axis}"; ignored.`);
+      continue;
+    }
+    const wanted = normalizeAxisValue(raw);
+    let found = false;
+    for (const r of rich) {
+      if (((_b = r.variants) == null ? void 0 : _b[axis]) && wanted !== void 0 && wanted in r.variants[axis]) {
+        found = true;
+        break;
+      }
+    }
+    if (!found && wanted !== void 0) {
+      const anyBundle = rich.some((r) => r.variants && axis in r.variants);
+      if (anyBundle) {
+        console.warn(`Template "${templateName}" axis "${axis}" has no value "${wanted}" on path "${path.join(".")}"; ignored.`);
+      }
+    }
+  }
+  const acc = {};
+  for (const r of rich) {
+    if (r.base) Object.assign(acc, r.base);
+  }
+  for (const axis of Object.keys(effective)) {
+    const value = effective[axis];
+    if (value === void 0) continue;
+    for (let i = rich.length - 1; i >= 0; i--) {
+      const bundle = (_d = (_c = rich[i].variants) == null ? void 0 : _c[axis]) == null ? void 0 : _d[value];
+      if (bundle) {
+        Object.assign(acc, bundle);
+        break;
+      }
+    }
+  }
+  for (const r of rich) {
+    if (r.compoundVariants) {
+      for (const entry of r.compoundVariants) {
+        if (matchesAll(entry, effective) && entry.css) Object.assign(acc, entry.css);
+      }
+    }
+    if (r.anyOfVariants) {
+      for (const entry of r.anyOfVariants) {
+        if (matchesAny(entry, effective) && entry.css) Object.assign(acc, entry.css);
+      }
+    }
+  }
+  return acc;
+};
 const parseStyles = async (styles, currentScope = "", config, omitTemplates = false) => {
   if (!styles) throw new Error("No styles provided to parseStyles function!");
   const cssStyles = /* @__PURE__ */ new Set();
@@ -136,13 +300,29 @@ const parseStyles = async (styles, currentScope = "", config, omitTemplates = fa
     }
     if ((config == null ? void 0 : config.templates) && config.templates[_key]) {
       if (omitTemplates) return void 0;
-      const path = value.split(".");
-      const templateStyles = path.reduce((acc, key2) => acc[key2], config.templates[_key]);
-      if (templateStyles) {
-        const [result] = await parseStyles(templateStyles, "");
-        return result;
+      const root = config.templates[_key];
+      const callSite = parseTemplateCallSite(value);
+      if (callSite) {
+        const { path, variants } = callSite;
+        const hasCallSiteVariants = Object.keys(variants).length > 0;
+        if (hasCallSiteVariants || pathHasRichNode(root, path)) {
+          const resolved2 = resolveRichTemplate(root, path, variants, _key);
+          if (resolved2) {
+            const [result] = await parseStyles(resolved2, "");
+            return result;
+          }
+          console.warn(`Template "${_key}" with path of "${path.join(".")}" was not found in config!`);
+          return void 0;
+        }
+        const templateStyles = path.reduce((acc, key2) => acc == null ? void 0 : acc[key2], root);
+        if (templateStyles) {
+          const [result] = await parseStyles(templateStyles, "");
+          return result;
+        }
+        console.warn(`Template "${_key}" with path of "${path.join(".")}" was not found in config!`);
+        return void 0;
       }
-      console.warn(`Template "${_key}" with path of "${value}" was not found in config!`);
+      console.warn(`Template "${_key}" received an unsupported call-site value.`);
       return void 0;
     }
     const isVariantArrayKey = _key === "compoundVariants" || _key === "anyOfVariants";
@@ -327,6 +507,7 @@ export {
   parseVariableTokens as b,
   parseValueModifiers as c,
   parseValueTokens as d,
+  isRichTemplateNode as i,
   parseAndJoinStyles as p,
   reportParserIssue as r
 };

package/parsers/index.cjs

@@ -1,11 +1,31 @@
 "use strict";
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const parseStyles = require("../parse-styles-jPtMfgXH.cjs");
+const parseStyles = require("../parse-styles-BFoV7HiL.cjs");
 const dashCase = require("../dash-case-DIwKaYgE.cjs");
 const toHash = require("../to-hash-C05Y906F.cjs");
+const RICH_META_KEYS = /* @__PURE__ */ new Set(["base", "variants", "defaultVariants", "compoundVariants", "anyOfVariants"]);
+const isChildEntry = (key, value) => {
+  if (RICH_META_KEYS.has(key)) return false;
+  return !!value && typeof value === "object" && !Array.isArray(value);
+};
 const parseTemplates = async (obj, path = []) => {
   if (!obj) return "";
   const classes = [];
+  if (parseStyles.isRichTemplateNode(obj)) {
+    const rich = obj;
+    if (rich.base) {
+      const className = path.map((p) => dashCase.dashCase(String(p))).join("-");
+      const hashClass = "t_" + toHash.toHash(className, 4);
+      const result = await parseStyles.parseAndJoinStyles(rich.base, `.${className}, .${hashClass}`);
+      classes.push(result);
+    }
+    for (const [key, value] of Object.entries(rich)) {
+      if (!isChildEntry(key, value)) continue;
+      const result = await parseTemplates(value, [...path, key.trim()]);
+      classes.push(result);
+    }
+    return classes.join("\n");
+  }
   const levelStyles = {};
   for (const [key, value] of Object.entries(obj)) {
     if (typeof value === "function") ;
@@ -18,7 +38,7 @@ const parseTemplates = async (obj, path = []) => {
     }
   }
   if (Object.keys(levelStyles).length) {
-    const className = path.map(dashCase.dashCase).join("-");
+    const className = path.map((p) => dashCase.dashCase(String(p))).join("-");
     const hashClass = "t_" + toHash.toHash(className, 4);
     const result = await parseStyles.parseAndJoinStyles(levelStyles, `.${className}, .${hashClass}`);
     classes.push(result);
@@ -40,13 +60,69 @@ const getTemplateTypes = (templates) => {
 };
 const getTemplateTokens = (templates, parent = "", templateTokens = /* @__PURE__ */ new Set()) => {
   if (!templates) return [];
+  if (parseStyles.isRichTemplateNode(templates)) {
+    if (parent) templateTokens.add(parent);
+    Object.entries(templates).forEach(([key, value]) => {
+      if (!isChildEntry(key, value)) return;
+      const keyValue = parent ? `${parent}.${key}` : key;
+      getTemplateTokens(value, keyValue, templateTokens);
+    });
+    return [...templateTokens];
+  }
   Object.entries(templates).forEach(([key, value]) => {
     const keyValue = parent ? `${parent}.${key}` : key;
-    if (typeof value === "object") return getTemplateTokens(value, keyValue, templateTokens);
+    if (value && typeof value === "object") return getTemplateTokens(value, keyValue, templateTokens);
     return templateTokens.add(parent);
   });
   return [...templateTokens];
 };
+const getTemplateVariantMaps = (templates) => {
+  const result = {};
+  if (!templates) return result;
+  for (const [topKey, topNode] of Object.entries(templates)) {
+    if (!topNode || typeof topNode !== "object" || typeof topNode === "function") continue;
+    walk(topNode, [], result[topKey] || (result[topKey] = {}), {});
+  }
+  return result;
+};
+const mergeAxes = (inherited, node) => {
+  const next = {};
+  for (const [axis, vals] of Object.entries(inherited)) {
+    next[axis] = { ...vals };
+  }
+  if (parseStyles.isRichTemplateNode(node) && node.variants) {
+    for (const [axis, valueMap] of Object.entries(node.variants)) {
+      next[axis] = next[axis] || {};
+      for (const value of Object.keys(valueMap)) next[axis][value] = true;
+    }
+  }
+  return next;
+};
+const walk = (node, path, out, inheritedAxes) => {
+  if (!node || typeof node !== "object" || Array.isArray(node)) return;
+  const axes = mergeAxes(inheritedAxes, node);
+  const dot = path.join(".");
+  if (path.length && (parseStyles.isRichTemplateNode(node) || Object.keys(axes).length)) {
+    const axisMap = {};
+    for (const [axis, valSet] of Object.entries(axes)) {
+      const values = Object.keys(valSet);
+      const isBooleanOnly = values.length === 1 && values[0] === "true";
+      axisMap[axis] = isBooleanOnly ? "boolean" : values.map((v) => `"${v}"`).join(" | ");
+    }
+    if (Object.keys(axisMap).length) out[dot] = axisMap;
+  }
+  if (parseStyles.isRichTemplateNode(node)) {
+    for (const [key, value] of Object.entries(node)) {
+      if (!isChildEntry(key, value)) continue;
+      walk(value, [...path, key.trim()], out, axes);
+    }
+    return;
+  }
+  for (const [key, value] of Object.entries(node)) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) continue;
+    walk(value, [...path, key.trim()], out, axes);
+  }
+};
 exports.parseAndJoinStyles = parseStyles.parseAndJoinStyles;
 exports.parseStyles = parseStyles.parseStyles;
 exports.parseValueModifiers = parseStyles.parseValueModifiers;
@@ -56,4 +132,5 @@ exports.reportParserIssue = parseStyles.reportParserIssue;
 exports.getTemplateKeys = getTemplateKeys;
 exports.getTemplateTokens = getTemplateTokens;
 exports.getTemplateTypes = getTemplateTypes;
+exports.getTemplateVariantMaps = getTemplateVariantMaps;
 exports.parseTemplates = parseTemplates;

package/parsers/index.js

@@ -1,10 +1,30 @@
-import { p as parseAndJoinStyles } from "../parse-styles--vHKY6Mw.js";
-import { a, c, d, b, r } from "../parse-styles--vHKY6Mw.js";
+import { i as isRichTemplateNode, p as parseAndJoinStyles } from "../parse-styles-CtA-RKqt.js";
+import { a, c, d, b, r } from "../parse-styles-CtA-RKqt.js";
 import { d as dashCase } from "../dash-case-DblXvymC.js";
 import { t as toHash } from "../to-hash-DAN2LcHK.js";
+const RICH_META_KEYS = /* @__PURE__ */ new Set(["base", "variants", "defaultVariants", "compoundVariants", "anyOfVariants"]);
+const isChildEntry = (key, value) => {
+  if (RICH_META_KEYS.has(key)) return false;
+  return !!value && typeof value === "object" && !Array.isArray(value);
+};
 const parseTemplates = async (obj, path = []) => {
   if (!obj) return "";
   const classes = [];
+  if (isRichTemplateNode(obj)) {
+    const rich = obj;
+    if (rich.base) {
+      const className = path.map((p) => dashCase(String(p))).join("-");
+      const hashClass = "t_" + toHash(className, 4);
+      const result = await parseAndJoinStyles(rich.base, `.${className}, .${hashClass}`);
+      classes.push(result);
+    }
+    for (const [key, value] of Object.entries(rich)) {
+      if (!isChildEntry(key, value)) continue;
+      const result = await parseTemplates(value, [...path, key.trim()]);
+      classes.push(result);
+    }
+    return classes.join("\n");
+  }
   const levelStyles = {};
   for (const [key, value] of Object.entries(obj)) {
     if (typeof value === "function") ;
@@ -17,7 +37,7 @@ const parseTemplates = async (obj, path = []) => {
     }
   }
   if (Object.keys(levelStyles).length) {
-    const className = path.map(dashCase).join("-");
+    const className = path.map((p) => dashCase(String(p))).join("-");
     const hashClass = "t_" + toHash(className, 4);
     const result = await parseAndJoinStyles(levelStyles, `.${className}, .${hashClass}`);
     classes.push(result);
@@ -39,17 +59,74 @@ const getTemplateTypes = (templates) => {
 };
 const getTemplateTokens = (templates, parent = "", templateTokens = /* @__PURE__ */ new Set()) => {
   if (!templates) return [];
+  if (isRichTemplateNode(templates)) {
+    if (parent) templateTokens.add(parent);
+    Object.entries(templates).forEach(([key, value]) => {
+      if (!isChildEntry(key, value)) return;
+      const keyValue = parent ? `${parent}.${key}` : key;
+      getTemplateTokens(value, keyValue, templateTokens);
+    });
+    return [...templateTokens];
+  }
   Object.entries(templates).forEach(([key, value]) => {
     const keyValue = parent ? `${parent}.${key}` : key;
-    if (typeof value === "object") return getTemplateTokens(value, keyValue, templateTokens);
+    if (value && typeof value === "object") return getTemplateTokens(value, keyValue, templateTokens);
     return templateTokens.add(parent);
   });
   return [...templateTokens];
 };
+const getTemplateVariantMaps = (templates) => {
+  const result = {};
+  if (!templates) return result;
+  for (const [topKey, topNode] of Object.entries(templates)) {
+    if (!topNode || typeof topNode !== "object" || typeof topNode === "function") continue;
+    walk(topNode, [], result[topKey] || (result[topKey] = {}), {});
+  }
+  return result;
+};
+const mergeAxes = (inherited, node) => {
+  const next = {};
+  for (const [axis, vals] of Object.entries(inherited)) {
+    next[axis] = { ...vals };
+  }
+  if (isRichTemplateNode(node) && node.variants) {
+    for (const [axis, valueMap] of Object.entries(node.variants)) {
+      next[axis] = next[axis] || {};
+      for (const value of Object.keys(valueMap)) next[axis][value] = true;
+    }
+  }
+  return next;
+};
+const walk = (node, path, out, inheritedAxes) => {
+  if (!node || typeof node !== "object" || Array.isArray(node)) return;
+  const axes = mergeAxes(inheritedAxes, node);
+  const dot = path.join(".");
+  if (path.length && (isRichTemplateNode(node) || Object.keys(axes).length)) {
+    const axisMap = {};
+    for (const [axis, valSet] of Object.entries(axes)) {
+      const values = Object.keys(valSet);
+      const isBooleanOnly = values.length === 1 && values[0] === "true";
+      axisMap[axis] = isBooleanOnly ? "boolean" : values.map((v) => `"${v}"`).join(" | ");
+    }
+    if (Object.keys(axisMap).length) out[dot] = axisMap;
+  }
+  if (isRichTemplateNode(node)) {
+    for (const [key, value] of Object.entries(node)) {
+      if (!isChildEntry(key, value)) continue;
+      walk(value, [...path, key.trim()], out, axes);
+    }
+    return;
+  }
+  for (const [key, value] of Object.entries(node)) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) continue;
+    walk(value, [...path, key.trim()], out, axes);
+  }
+};
 export {
   getTemplateKeys,
   getTemplateTokens,
   getTemplateTypes,
+  getTemplateVariantMaps,
   parseAndJoinStyles,
   a as parseStyles,
   parseTemplates,

package/parsers/parse-templates.d.ts

@@ -2,3 +2,13 @@ export declare const parseTemplates: <T extends object>(obj: T, path?: PropertyK
 export declare const getTemplateKeys: <T extends object>(templates: T) => string[];
 export declare const getTemplateTypes: <T extends object>(templates: T) => Record<string, string>;
 export declare const getTemplateTokens: <T extends object>(templates: T, parent?: string, templateTokens?: Set<string>) => string[];
+/**
+ * Walk every rich-template path in a templates root and emit, for each reachable dot-path, the set of
+ * variant axes valid at that path (axis name → union of value names, with `boolean` for axes whose only
+ * declared value is `true`).
+ *
+ * Inheritance: a leaf's axis enum is the union of its own values and every ancestor's values for the
+ * same axis. Matches the resolver's bottom-up lookup semantics — anything reachable via fallback is a
+ * valid call-site value.
+ */
+export declare const getTemplateVariantMaps: (templates: Record<string, any>) => Record<string, Record<string, Record<string, string>>>;

package/parsers/resolve-template-variants.d.ts

@@ -0,0 +1,21 @@
+import { RichTemplateNode } from '../types/config-types';
+export type TemplateCallSite = {
+    path: string[];
+    variants: Record<string, string | boolean>;
+};
+export declare const isRichTemplateNode: (node: unknown) => node is RichTemplateNode;
+/**
+ * Parse a template call-site value into its dot-path and the axis values requested at the call site.
+ *
+ * String form:  `'heading.large@weight=heavy&emphasis=loud&italic'`
+ * Object form:  `{ name: 'heading.large', weight: 'heavy', emphasis: 'loud', italic: true }`
+ */
+export declare const parseTemplateCallSite: (value: unknown) => TemplateCallSite | undefined;
+export declare const pathHasRichNode: (root: any, path: string[]) => boolean;
+/**
+ * Resolve a rich-template invocation into a flat CSS-in-JS object.
+ * Implements docs/template-variants-spec.md §5 (parent-to-leaf inheritance, replace semantics).
+ *
+ * Returns `undefined` if the path doesn't resolve. Emits console.warn for unknown axes / values.
+ */
+export declare const resolveRichTemplate: (root: any, path: string[], callSiteVariants: Record<string, string | boolean>, templateName: string) => Record<string, any> | undefined;

package/runtime/index.cjs

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const parseStyles = require("../parse-styles-jPtMfgXH.cjs");
+const parseStyles = require("../parse-styles-BFoV7HiL.cjs");
 const defineRuntime = (config) => {
   const getDynamicStylesCss = async (styles, scope) => {
     const parsed = await parseStyles.parseStyles(styles, scope, config);

package/runtime/index.js

@@ -1,4 +1,4 @@
-import { a as parseStyles } from "../parse-styles--vHKY6Mw.js";
+import { a as parseStyles } from "../parse-styles-CtA-RKqt.js";
 const defineRuntime = (config) => {
   const getDynamicStylesCss = async (styles, scope) => {
     const parsed = await parseStyles(styles, scope, config);

package/types/config-types.d.ts

@@ -16,7 +16,38 @@ export interface SaltyVariables {
     conditional?: CssConditionalVariables;
     [key: string]: undefined | string | number | CssVariableTokensObject;
 }
-type CssTemplate = MediaQueryStyles | CssStyles | {
+/**
+ * A variant axis value bundle: a map from axis name to a map from value name (string keys or `'true'`)
+ * to a CSS-in-JS block. `name` is reserved as the call-site object form's path key and cannot be used
+ * as an axis name (build-time error).
+ */
+export type CssVariantAxes = {
+    [axis: string]: {
+        [value: string]: CssStyles;
+    };
+} & {
+    name?: never;
+};
+export interface CssCompoundVariant {
+    css: CssStyles;
+    [axis: string]: any;
+}
+/**
+ * A "rich" template node: declares its own base styles, named variant bundles, defaults, and compound rules.
+ * May coexist with child template nodes (descendants) as additional sibling keys.
+ */
+export type RichTemplateNode = {
+    base?: CssStyles;
+    variants?: CssVariantAxes;
+    defaultVariants?: {
+        [axis: string]: string | boolean;
+    };
+    compoundVariants?: CssCompoundVariant[];
+    anyOfVariants?: CssCompoundVariant[];
+} & {
+    [key: PropertyKey]: any;
+};
+type CssTemplate = MediaQueryStyles | CssStyles | RichTemplateNode | {
     [key: PropertyKey]: CssTemplate;
 };
 export interface CssTemplateObject {