@homebound/truss 2.22.0 → 2.23.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.
      *
@@ -261,4 +271,4 @@ declare function newIncrementMethods(config: Config, abbr: UtilityName, prop: Pr
 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 };
+export { type Aliases, type Config, type CreateMethodsFn, type FontConfig, type IncConfig, type SectionName, type Sections, type TokenRegistry, type UtilityMethod, type UtilityName, type WebEntry, defaultSections, defineConfig, generate, newAliasesMethods, newCoreIncrementMethods, newIncrementMethods, newMethod, newMethodsForProp, newParamMethod, newPxMethod, newSetCssVariablesMethod, startWebCollection, stopWebCollection };

package/build/index.js

@@ -940,6 +940,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 +987,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 +1051,8 @@ export type ${def("InlineStyle")} = Record<string, string | number | undefined>;
 
 ${typographyType}
 
+${emitTokensEnumAndSetVarTypes(tokens)}
+
 type Opts<T> = {
   rules: T,
   enabled: boolean,
@@ -1155,6 +1184,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 +1273,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 +1348,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 +1521,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);
@@ -1619,10 +1662,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 +1681,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++) {