@homebound/truss 2.22.0 → 2.24.0

package/build/index.d.ts

@@ -7,6 +7,11 @@ import { Code } from 'ts-poet';
  * Or a set of properties, i.e. `f12` -> `{ fontFamily: ..., fontWeight: ... }`.
  */
 type FontConfig = Record<string, string | Properties>;
+/**
+ * Maps a design token name (enum member / key) to a CSS custom property name.
+ * Values must be valid custom property identifiers (`--…`).
+ */
+type TokenRegistry = Record<string, `--${string}`>;
 /**
  * Provides users with an easy way to configure the major/most-often configurable
  * aspect of a design system, i.e. the palette, fonts, and increments.
@@ -45,6 +50,11 @@ interface Config {
     typeAliases?: Record<string, Array<keyof Properties>>;
     /** Breakpoints, i.e. `{ sm: 0, md: 500 }`. */
     breakpoints?: Record<string, number>;
+    /**
+     * Optional design tokens: emitted as `Tokens` enum in generated `Css.ts` and available to
+     * `Css.setVar({ [Tokens.X]: … })` at build time (web target).
+     */
+    tokens?: TokenRegistry;
     /**
      * Which default methods to include.
      *
@@ -253,12 +263,24 @@ type IncConfig = [string, Prop | Prop[]];
 declare function newIncrementMethods(config: Config, abbr: UtilityName, prop: Prop | Prop[], opts?: {
     auto?: boolean;
 }): UtilityMethod[];
-/**
- * Creates just the core `<abbr>X` utility methods that set `props` with each increment value.
- *
- * See `newIncrementMethods` for handling the `<abbr>Px`, `<abbr>a`, and `<attr>(value)` methods.
- */
 declare function newCoreIncrementMethods(config: Config, abbr: UtilityName, props: Prop[]): UtilityMethod[];
 declare function newPxMethod(abbr: UtilityName, prop: Prop): UtilityMethod;
 
-export { type Aliases, type Config, type CreateMethodsFn, type FontConfig, type IncConfig, type SectionName, type Sections, type UtilityMethod, type UtilityName, type WebEntry, defaultSections, defineConfig, generate, newAliasesMethods, newCoreIncrementMethods, newIncrementMethods, newMethod, newMethodsForProp, newParamMethod, newPxMethod, newSetCssVariablesMethod, startWebCollection, stopWebCollection };
+/**
+ * Web increment utilities use `--t-spacing` with `calc` (see generated `Css.ts` and the Vite plugin).
+ * Keep literals in one place so codegen, emitted CSS, and the transform stay aligned.
+ * `--t-spacing` must be set (e.g. `:root` prelude from `collectCss()` / mapping `increment`).
+ */
+/** Custom property for increment-based spacing (web). */
+declare const SPACING_CUSTOM_PROPERTY = "--t-spacing";
+/** I.e. `calc(var(--t-spacing) * 3)` — requires prelude defining `--t-spacing`. */
+declare function incrementCssValue(multiplier: number): string;
+/**
+ * If `cssValue` is exactly `calc(var(--t-spacing) * k)` for this package's spacing property,
+ * returns the multiplier substring `k` (e.g. `"2"`, `"-1"`, `"2.5"`). Otherwise null.
+ */
+declare function tryParseIncrementCalcMultiplier(cssValue: string): string | null;
+/** Prepended to emitted Truss CSS; `incrementPx` comes from `truss-config` / `Css.json`. */
+declare function rootSpacingPreludeCss(incrementPx: number): string;
+
+export { type Aliases, type Config, type CreateMethodsFn, type FontConfig, type IncConfig, SPACING_CUSTOM_PROPERTY, type SectionName, type Sections, type TokenRegistry, type UtilityMethod, type UtilityName, type WebEntry, defaultSections, defineConfig, generate, incrementCssValue, newAliasesMethods, newCoreIncrementMethods, newIncrementMethods, newMethod, newMethodsForProp, newParamMethod, newPxMethod, newSetCssVariablesMethod, rootSpacingPreludeCss, startWebCollection, stopWebCollection, tryParseIncrementCalcMultiplier };

package/build/index.js

@@ -3,6 +3,21 @@ function defineConfig(config) {
   return config;
 }
 
+// src/spacing-css-var.ts
+var SPACING_CUSTOM_PROPERTY = "--t-spacing";
+function incrementCssValue(multiplier) {
+  return `calc(var(${SPACING_CUSTOM_PROPERTY}) * ${multiplier})`;
+}
+function tryParseIncrementCalcMultiplier(cssValue) {
+  const prop = SPACING_CUSTOM_PROPERTY.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const re = new RegExp(`^calc\\(var\\(${prop}\\) \\* (-?\\d+(?:\\.\\d+)?)\\)$`);
+  const m = cssValue.match(re);
+  return m ? m[1] : null;
+}
+function rootSpacingPreludeCss(incrementPx) {
+  return `:root { ${SPACING_CUSTOM_PROPERTY}: ${incrementPx}px; }`;
+}
+
 // src/methods.ts
 var _webCollector = null;
 function startWebCollection() {
@@ -74,12 +89,15 @@ function newIncrementMethods(config, abbr, prop, opts = {}) {
     `${pxComment} ${abbr}Px(px: number) { return this.${props.map((p) => `add("${p}", \`\${px}px\`)`).join(".")}; }`
   ];
 }
+function isWebIncrementTarget(config) {
+  return config.target !== "react-native";
+}
 function newCoreIncrementMethods(config, abbr, props) {
   return zeroTo(config.numberOfIncrements).map((i) => {
-    const px = `${i * config.increment}px`;
-    const defs = Object.fromEntries(props.map((p) => [p, px]));
+    const value = isWebIncrementTarget(config) ? incrementCssValue(i) : `${i * config.increment}px`;
+    const defs = Object.fromEntries(props.map((p) => [p, value]));
     collect({ kind: "static", abbr: `${abbr}${i}`, defs });
-    const sets = props.map((p) => `add("${p}", "${px}")`).join(".");
+    const sets = props.map((p) => `add("${p}", "${value}")`).join(".");
     return `${comment(defs)} get ${abbr}${i}() { return this.${sets}; }`;
   });
 }
@@ -940,6 +958,33 @@ var defaultTypeAliases = {
   Margin: ["margin", "marginTop", "marginRight", "marginBottom", "marginLeft"],
   Padding: ["padding", "paddingTop", "paddingRight", "paddingBottom", "paddingLeft"]
 };
+function emitTokensEnumAndSetVarTypes(tokens) {
+  const entries = tokens && typeof tokens === "object" ? Object.entries(tokens).filter(([, v]) => typeof v === "string") : [];
+  const hasTokens = entries.length > 0;
+  const enumBlock = hasTokens ? `export enum Tokens {
+${entries.map(([name, value]) => `  ${name} = ${JSON.stringify(value)},`).join("\n")}
+}
+
+` : "";
+  const keysType = hasTokens ? `export type CssSetVarKeys = Tokens | \`--\${string}\`;
+
+` : `export type CssSetVarKeys = \`--\${string}\`;
+
+`;
+  const scalar = `export type CssSetVarScalar = string | number;
+
+`;
+  const valueType = `export type CssSetVarValue =
+  | CssSetVarScalar
+  | {
+      default?: CssSetVarScalar;
+      media?: Partial<Record<Breakpoint, CssSetVarScalar>>;
+      container?: Array<{ name?: string; gt?: number; lt?: number; value: CssSetVarScalar }>;
+    };
+
+`;
+  return enumBlock + keysType + scalar + valueType;
+}
 async function generate(config) {
   const { outputPath } = config;
   const target = config.target ?? "web";
@@ -960,7 +1005,7 @@ async function generate(config) {
   throw new Error(`Unsupported truss target "${target}". Use "web" (default) or "react-native".`);
 }
 function generateReactNativeBuilder(config) {
-  const { fonts, increment, extras, typeAliases, breakpoints = {}, palette } = config;
+  const { fonts, increment, extras, typeAliases, breakpoints = {}, palette, tokens } = config;
   const sections = generateSections(config);
   const lines = Object.entries(sections).map(([name, value]) => [`// ${name}`, ...value, ""]).flat();
   const typeAliasCode = Object.entries({
@@ -1024,6 +1069,8 @@ export type ${def("InlineStyle")} = Record<string, string | number | undefined>;
 
 ${typographyType}
 
+${emitTokensEnumAndSetVarTypes(tokens)}
+
 type Opts<T> = {
   rules: T,
   enabled: boolean,
@@ -1155,6 +1202,12 @@ class CssBuilder<T extends Properties> {
     return this;
   }
 
+  /** Set CSS custom properties (web build-time only; not supported on react-native). */
+  setVar(_values: Partial<Record<CssSetVarKeys, CssSetVarValue>>): CssBuilder<T> {
+    void _values;
+    throw new Error("Css.setVar() is only supported when Truss target is \\\"web\\\" (build-time atomic CSS).");
+  }
+
   /** Tagged template literal for raw CSS in .css.ts files; passes through the string as-is. */
   raw(strings: TemplateStringsArray, ...values: unknown[]): string {
     return String.raw(strings, ...values);
@@ -1238,7 +1291,7 @@ function collectWebGenerationData(config) {
   }
 }
 function generateWebCssBuilder(config, sections) {
-  const { fonts, increment, extras, typeAliases, palette, breakpoints = {} } = config;
+  const { fonts, increment, extras, typeAliases, palette, breakpoints = {}, tokens } = config;
   const lines = Object.entries(sections).map(([name, value]) => [`// ${name}`, ...value, ""]).flat();
   const typeAliasCode = Object.entries({
     ...defaultTypeAliases,
@@ -1313,6 +1366,8 @@ export type ${def("RuntimeStyles")} = RawCssProperties & { readonly __kind: "run
 
 ${typographyType}
 
+${emitTokensEnumAndSetVarTypes(tokens)}
+
 // Augment React types so all JSX elements accept the \`css\` prop:
 // - HTMLAttributes/SVGAttributes cover intrinsic elements (div, svg, etc.)
 // - JSX.IntrinsicAttributes covers custom components (Card, Page, etc.)
@@ -1484,6 +1539,12 @@ class CssBuilder<T extends Properties, S extends StyleKind = "buildtime"> {
     return this.unsupportedRuntime("style() cannot be used in RuntimeStyle css expressions.");
   }
 
+  /** Set CSS custom properties via atomic classes (resolved at build time on web). */
+  setVar(_values: Partial<Record<CssSetVarKeys, CssSetVarValue>>): CssBuilder<T, S> {
+    void _values;
+    return this.unsupportedRuntime("setVar() cannot be used in RuntimeStyle css expressions.");
+  }
+
   /** Convert a style hash into \`{ className, style }\` props for manual spreading into non-\`css=\` contexts. */
   props(styles: Properties): Record<string, unknown> {
     return trussProps(styles as any);
@@ -1511,9 +1572,9 @@ class CssBuilder<T extends Properties, S extends StyleKind = "buildtime"> {
   }
 }
 
-/** Converts \`inc\` into pixels value with a \`px\` suffix. */
+/** Converts \`inc\` into a spacing length using \`--t-spacing\` (build-time atomic CSS). */
 export function maybeInc(inc: number | string): string {
-  return typeof inc === "string" ? inc : \`\${inc * ${increment}}px\`;
+  return typeof inc === "string" ? inc : \`calc(var(${SPACING_CUSTOM_PROPERTY}) * \${inc})\`;
 }
 
 /** Converts \`inc\` into pixels. */
@@ -1619,10 +1680,12 @@ function generateTrussMapping(config, entries) {
   for (const [name, mediaQuery] of Object.entries(genBreakpointsMap)) {
     breakpointEntries[`if${pascalCase(name)}`] = mediaQuery;
   }
+  const tokenEntries = config.tokens && Object.keys(config.tokens).length > 0 ? config.tokens : void 0;
   return {
     increment: config.increment,
     ...Object.keys(breakpointEntries).length > 0 ? { breakpoints: breakpointEntries } : {},
     ...Object.keys(config.fonts).length > 0 ? { typography: Object.keys(config.fonts) } : {},
+    ...tokenEntries ? { tokens: tokenEntries } : {},
     abbreviations
   };
 }
@@ -1636,6 +1699,9 @@ function condensedJson(mapping) {
   if (mapping.typography && mapping.typography.length > 0) {
     lines.push(`  "typography": ${JSON.stringify(mapping.typography)},`);
   }
+  if (mapping.tokens && Object.keys(mapping.tokens).length > 0) {
+    lines.push(`  "tokens": ${JSON.stringify(mapping.tokens)},`);
+  }
   lines.push(`  "abbreviations": {`);
   const entries = Object.entries(mapping.abbreviations);
   for (let i = 0; i < entries.length; i++) {
@@ -1648,9 +1714,11 @@ function condensedJson(mapping) {
   return lines.join("\n");
 }
 export {
+  SPACING_CUSTOM_PROPERTY,
   defaultSections,
   defineConfig,
   generate,
+  incrementCssValue,
   newAliasesMethods,
   newCoreIncrementMethods,
   newIncrementMethods,
@@ -1659,7 +1727,9 @@ export {
   newParamMethod,
   newPxMethod,
   newSetCssVariablesMethod,
+  rootSpacingPreludeCss,
   startWebCollection,
-  stopWebCollection
+  stopWebCollection,
+  tryParseIncrementCalcMultiplier
 };
 //# sourceMappingURL=index.js.map