@homebound/truss 2.29.13 → 2.30.0

package/build/index.d.ts

@@ -11,8 +11,58 @@ 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 (`--…`).
+ *
+ * The object form additionally registers the property with `@property`, i.e. so the browser
+ * types the value and can animate it. See `TokenDefinition`.
  */
-type TokenRegistry = Record<string, `--${string}`>;
+type TokenRegistry = Record<string, `--${string}` | TokenDefinition>;
+/**
+ * A token that is also registered with `@property`.
+ *
+ * Naming a token and registering it are two different things. The string form of `tokens` only
+ * gives the variable a TypeScript name and emits no CSS. Registering it tells the browser about
+ * the variable: to parse and type-check its value, to fall back to `initialValue` instead of
+ * inheriting an unparsed token stream, and — the reason most design systems want it — to
+ * *interpolate* it, since an unregistered custom property is an opaque token stream that no
+ * transition or keyframe can animate.
+ *
+ * I.e. `{ var: "--angle", syntax: "<angle>", inherits: false, initialValue: "0deg" }` emits
+ * `@property --angle { syntax: "<angle>"; inherits: false; initial-value: 0deg; }`.
+ */
+interface TokenDefinition {
+    /** The CSS custom property name, i.e. `--angle`. */
+    var: `--${string}`;
+    /** The `@property` syntax descriptor, i.e. `"<angle>"`, or `"*"` to register without typing. */
+    syntax: string;
+    /** The `@property` inherits descriptor. Defaults to `false`. */
+    inherits?: boolean;
+    /** The `@property` initial-value descriptor, i.e. `"0deg"`. Required unless `syntax` is `"*"`. */
+    initialValue?: string;
+}
+/**
+ * A map from `@keyframes` name to its animation timeline.
+ *
+ * The object form is keyframe selector (`from`, `to`, `50%`, `0%, 100%`) to declarations, which
+ * csstype validates like any other declaration. The string form is a raw body, for a timeline the
+ * typed form cannot express. Either way Truss owns the name, so it can check the animations that
+ * use it and write the block only when one still does.
+ *
+ * `null` declares a name that some other stylesheet defines — a global CSS file, a third-party
+ * package. Truss accepts the name and writes nothing. Without it, adopting `keyframes` at all would
+ * make every animation Truss did not declare fail the build.
+ *
+ * I.e. `{ spin: { to: { transform: "rotate(360deg)" } }, aiStarLoader: null }`.
+ */
+type KeyframesConfig = Record<string, Record<string, KeyframeDeclarations> | string | null>;
+/**
+ * The declarations in one keyframe selector.
+ *
+ * Custom properties are allowed alongside real CSS properties, because animating a registered
+ * property is written as a keyframe that sets it, i.e. `{ to: { "--angle": "360deg" } }`.
+ */
+type KeyframeDeclarations = Properties & {
+    [customProperty: `--${string}`]: string | number;
+};
 /**
  * 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.
@@ -56,6 +106,11 @@ interface Config {
      * `Css.setVar({ [Tokens.X]: … })` at build time (web target).
      */
     tokens?: TokenRegistry;
+    /**
+     * Optional `@keyframes` animations: emitted as a `Keyframes` enum in generated `Css.ts` (web
+     * target), and written to the stylesheet only while some rule still names them.
+     */
+    keyframes?: KeyframesConfig;
     /**
      * Which default methods to include.
      *
@@ -290,4 +345,4 @@ declare function tryParseIncrementCalcMultiplier(cssValue: string): string | nul
 /** 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 };
+export { type Aliases, type Config, type CreateMethodsFn, type FontConfig, type IncConfig, type KeyframeDeclarations, type KeyframesConfig, SPACING_CUSTOM_PROPERTY, type SectionName, type Sections, type TokenDefinition, 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

@@ -586,6 +586,9 @@ function lowerCaseFirst(s) {
 function quote(s) {
   return JSON.stringify(s);
 }
+function camelToKebab(s) {
+  return s.replace(/^(Webkit|Moz|Ms|O)/, (m) => `-${m.toLowerCase()}`).replace(/[A-Z]/g, (m) => `-${m.toLowerCase()}`);
+}
 
 // src/sections/tachyons/skins.ts
 var skins = (config) => {
@@ -1013,6 +1016,59 @@ var TRUSS_PSEUDO_METHODS = {
   ifLastOfType: ":last-of-type"
 };
 
+// src/at-rules.ts
+function tokenVarName(token) {
+  return typeof token === "string" ? token : token.var;
+}
+function tokenDefinition(token) {
+  return typeof token === "string" ? void 0 : token;
+}
+function tokenVarNames(tokens) {
+  const names = {};
+  for (const [name, token] of Object.entries(tokens ?? {})) {
+    names[name] = tokenVarName(token);
+  }
+  return names;
+}
+function tokenPropertyBlocks(tokens) {
+  const blocks = {};
+  for (const [name, token] of Object.entries(tokens ?? {})) {
+    const definition = tokenDefinition(token);
+    if (!definition) continue;
+    if (definition.syntax !== "*" && definition.initialValue === void 0) {
+      throw new Error(
+        `Token "${name}" has syntax ${JSON.stringify(definition.syntax)} but no initialValue. @property requires an initial value for every syntax except "*".`
+      );
+    }
+    blocks[definition.var] = propertyCssText(definition);
+  }
+  return blocks;
+}
+function propertyCssText(definition) {
+  const descriptors = [`syntax: ${JSON.stringify(definition.syntax)}`, `inherits: ${definition.inherits ?? false}`];
+  if (definition.initialValue !== void 0) {
+    descriptors.push(`initial-value: ${definition.initialValue}`);
+  }
+  return `@property ${definition.var} { ${descriptors.join("; ")}; }`;
+}
+function keyframesBlocks(keyframes) {
+  const blocks = {};
+  for (const [name, frames] of Object.entries(keyframes ?? {})) {
+    blocks[name] = frames === null ? "" : keyframesCssText(name, frames);
+  }
+  return blocks;
+}
+function keyframesCssText(name, frames) {
+  if (typeof frames === "string") {
+    return `@keyframes ${name} { ${frames.trim().replace(/\s+/g, " ")} }`;
+  }
+  const steps = Object.entries(frames).map(([selector, properties]) => {
+    const declarations = Object.entries(properties).filter((entry) => entry[1] !== void 0).map((entry) => `${camelToKebab(entry[0])}: ${entry[1]};`).join(" ");
+    return `${selector} { ${declarations} }`;
+  });
+  return `@keyframes ${name} { ${steps.join(" ")} }`;
+}
+
 // src/generate.ts
 var CssProperties = imp("t:Properties@csstype");
 var defaultTypeAliases = {
@@ -1020,7 +1076,7 @@ var defaultTypeAliases = {
   Padding: ["padding", "paddingTop", "paddingRight", "paddingBottom", "paddingLeft"]
 };
 function emitTokensEnumAndSetVarTypes(tokens) {
-  const entries = tokens && typeof tokens === "object" ? Object.entries(tokens).filter(([, v]) => typeof v === "string") : [];
+  const entries = Object.entries(tokenVarNames(tokens));
   const hasTokens = entries.length > 0;
   const enumBlock = hasTokens ? `export enum Tokens {
 ${entries.map(([name, value]) => `  ${name} = ${JSON.stringify(value)},`).join("\n")}
@@ -1046,6 +1102,16 @@ ${entries.map(([name, value]) => `  ${name} = ${JSON.stringify(value)},`).join("
 `;
   return enumBlock + keysType + scalar + valueType;
 }
+function emitKeyframesEnum(keyframes) {
+  const names = Object.keys(keyframes ?? {});
+  if (names.length === 0) return "";
+  const members = names.map((name) => `  ${pascalCase(name)} = ${JSON.stringify(name)},`).join("\n");
+  return `export enum Keyframes {
+${members}
+}
+
+`;
+}
 async function generate(config) {
   const { outputPath } = config;
   const target = config.target ?? "web";
@@ -1442,7 +1508,7 @@ export type ${def("RuntimeStyles")} = RawCssProperties & { readonly __kind: "run
 ${typographyType}
 
 ${emitTokensEnumAndSetVarTypes(tokens)}
-
+${emitKeyframesEnum(config.keyframes)}
 // 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.)
@@ -1769,12 +1835,16 @@ 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;
+  const tokenEntries = tokenVarNames(config.tokens);
+  const propertyEntries = tokenPropertyBlocks(config.tokens);
+  const keyframeEntries = keyframesBlocks(config.keyframes);
   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 } : {},
+    ...Object.keys(tokenEntries).length > 0 ? { tokens: tokenEntries } : {},
+    ...Object.keys(propertyEntries).length > 0 ? { properties: propertyEntries } : {},
+    ...Object.keys(keyframeEntries).length > 0 ? { keyframes: keyframeEntries } : {},
     abbreviations
   };
 }
@@ -1791,6 +1861,12 @@ function condensedJson(mapping) {
   if (mapping.tokens && Object.keys(mapping.tokens).length > 0) {
     lines.push(`  "tokens": ${JSON.stringify(mapping.tokens)},`);
   }
+  if (mapping.properties && Object.keys(mapping.properties).length > 0) {
+    lines.push(`  "properties": ${JSON.stringify(mapping.properties)},`);
+  }
+  if (mapping.keyframes && Object.keys(mapping.keyframes).length > 0) {
+    lines.push(`  "keyframes": ${JSON.stringify(mapping.keyframes)},`);
+  }
   lines.push(`  "abbreviations": {`);
   const entries = Object.entries(mapping.abbreviations);
   for (let i = 0; i < entries.length; i++) {