@homebound/truss 2.19.2 → 2.20.0

package/build/index.js

@@ -1054,7 +1054,7 @@ class CssBuilder<T extends Properties> {
 
   ${lines.join("\n  ").replace(/ +\n/g, "\n")}
     
-  get $(): T { return maybeImportant(sortObject(this.rules), this.opts.important); }
+  get $(): T { maybeImportant(sortObject(this.rules), this.opts.important); }
 
   if(bp: Breakpoint): CssBuilder<T>;
   if(cond: boolean): CssBuilder<T>;
@@ -1113,21 +1113,31 @@ class CssBuilder<T extends Properties> {
 
   get important() { return this.newCss({ important: true }); }
 
-  /** Adds new properties, either a specific key/value or a Properties object, to the current css. */
+  /** Add real CSS property/value pairs, either as add("prop", value) or add({ prop: value, ... }). */
   add<P extends Properties>(props: P): CssBuilder<T & P>;
   add<K extends keyof Properties>(prop: K, value: Properties[K]): CssBuilder<T & { [U in K]: Properties[K] }>;
   add<K extends keyof Properties>(propOrProperties: K | Properties, value?: Properties[K]): CssBuilder<any> {
     if (!this.enabled) return this;
     const newRules = typeof propOrProperties === "string" ?  { [propOrProperties]: value } : propOrProperties;
+    if (typeof propOrProperties !== "string" && (newRules as any).$css) {
+      throw new Error("add() received a Css expression — use with() to compose Css expressions");
+    }
     const rules = this.selector
       ? { ...this.rules, [this.selector]: { ...(this.rules as any)[this.selector], ...newRules } }
       : { ...this.rules, ...newRules };
     return this.newCss({ rules: rules as any });
   }
 
-  /** Adds a partial style hash, skipping any undefined values. */
-  addCss<P extends Properties>(props: P): CssBuilder<T & P> {
-    return this.add(omitUndefinedValues(props));
+  /** Compose an existing Css expression or partial style hash into this builder, skipping undefined values. */
+  with<P extends Properties>(cssProp: P): CssBuilder<T & P>;
+  with(cssProp: Properties): CssBuilder<any> {
+    if (!this.enabled) return this;
+    const { $css, ...rest } = cssProp as any;
+    const filtered = omitUndefinedValues(rest);
+    const rules = this.selector
+      ? { ...this.rules, [this.selector]: { ...(this.rules as any)[this.selector], ...filtered } }
+      : { ...this.rules, ...filtered };
+    return this.newCss({ rules: rules as any });
   }
 
   /** Adds new properties, either a specific key/value or a Properties object, to a nested selector. */
@@ -1144,7 +1154,7 @@ class CssBuilder<T extends Properties> {
   }
 
   /** Marker for the build-time transform to append a raw className. */
-  className(className: string): CssBuilder<T> {
+  className(className: string | undefined): CssBuilder<T> {
     void className;
     return this;
   }
@@ -1450,25 +1460,37 @@ class CssBuilder<T extends Properties> {
     return this.newCss({ selector: undefined, elseApplied: false });
   }
 
+  /** Add real CSS property/value pairs, either as add("prop", value) or add({ prop: value, ... }). */
   add<P extends Properties>(props: P): CssBuilder<T & P>;
   add<K extends keyof Properties>(prop: K, value: Properties[K]): CssBuilder<T & { [U in K]: Properties[K] }>;
   add<K extends keyof Properties>(propOrStyles: K | Properties, value?: Properties[K]): CssBuilder<any> {
     if (!this.enabled) return this;
 
     const newRules = typeof propOrStyles === "string" ? { [propOrStyles]: value } : propOrStyles;
+    if (typeof propOrStyles !== "string" && (newRules as any).$css) {
+      throw new Error("add() received a Css expression — use with() to compose Css expressions");
+    }
     const rules = this.selector
       ? { ...this.rules, [this.selector]: { ...(this.rules as any)[this.selector], ...newRules } }
       : { ...this.rules, ...newRules };
     return this.newCss({ rules: rules as any });
   }
 
-  /** Inline a partial style hash, skipping any undefined values. */
-  addCss<P extends Properties>(props: P): CssBuilder<T & P> {
-    return this.add(omitUndefinedValues(props));
+  /** Compose an existing Css expression or partial style hash into this builder, skipping undefined values. */
+  with<P extends Properties>(cssProp: P): CssBuilder<T & P>;
+  with(cssProp: Properties): CssBuilder<any> {
+    if (!this.enabled) return this;
+    const { $css, ...rest } = cssProp as any;
+    const filtered = omitUndefinedValues(rest);
+    const rules = this.selector
+      ? { ...this.rules, [this.selector]: { ...(this.rules as any)[this.selector], ...filtered } }
+      : { ...this.rules, ...filtered };
+    return this.newCss({ rules: rules as any });
   }
 
+
   /** Marker for the build-time transform to append a raw className. */
-  className(className: string): CssBuilder<T> {
+  className(className: string | undefined): CssBuilder<T> {
     void className;
     return this.unsupportedRuntime("className() cannot be used in RuntimeStyle css expressions.");
   }