@homebound/truss 2.11.3 → 2.13.0

package/build/index.js

@@ -1138,6 +1138,11 @@ class CssBuilder<T extends Properties> {
     return this;
   }
 
+  /** 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);
+  }
+
 }
 
 /** Sort keys so equivalent rule objects have deterministic shape. */
@@ -1258,6 +1263,7 @@ function generateStylexCssBuilder(config, sections) {
 // Target: native (build-time plugin)
 
 import { trussProps } from "@homebound/truss/runtime";
+export { RuntimeStyle } from "@homebound/truss/runtime";
 
 /** Given a type X, and the user's proposed type T, only allow keys in X and nothing else. */
 export type Only<X, T> = X & Record<Exclude<keyof T, keyof X>, never>;
@@ -1291,6 +1297,7 @@ type Opts<T> = {
   enabled: boolean;
   selector: string | undefined;
   elseApplied: boolean;
+  runtimeError: string | undefined;
 };
 
 class CssBuilder<T extends Properties> {
@@ -1299,6 +1306,12 @@ class CssBuilder<T extends Properties> {
   ${lines.join("\n  ").replace(/ +\n/g, "\n")}
 
   get $(): T {
+    if (this.opts.runtimeError) {
+      throw new Error(this.opts.runtimeError);
+    }
+    if (this.selector !== undefined) {
+      throw new Error("Selector-based Css helpers cannot be used in RuntimeStyle css expressions.");
+    }
     return this.rules as any;
   }
 
@@ -1329,12 +1342,12 @@ class CssBuilder<T extends Properties> {
 
   /** Marks this element as a default hover marker (for ancestor pseudo selectors). */
   get marker(): CssBuilder<T> {
-    return this;
+    return this.unsupportedRuntime("marker cannot be used in RuntimeStyle css expressions.");
   }
 
   /** Marks this element with a user-defined marker. */
   markerOf(_marker: Marker): CssBuilder<T> {
-    return this;
+    return this.unsupportedRuntime("markerOf() cannot be used in RuntimeStyle css expressions.");
   }
 
   /** Creates a marker token for use with markerOf() and when(). */
@@ -1361,16 +1374,16 @@ class CssBuilder<T extends Properties> {
     */
   when(marker: Marker, relationship: "ancestor" | "descendant" | "anySibling" | "siblingBefore" | "siblingAfter", pseudo: string): CssBuilder<T>;
   when(_selectorOrMarker: string | Marker, _relationship?: string, _pseudo?: string): CssBuilder<T> {
-    return this;
+    return this.unsupportedRuntime("when() cannot be used in RuntimeStyle css expressions.");
   }
 
   ifContainer(_props: { name?: string; lt?: number; gt?: number }) {
-    return this;
+    return this.unsupportedRuntime("ifContainer() cannot be used in RuntimeStyle css expressions.");
   }
 
   /** Apply styles within a pseudo-element (e.g. \`"::placeholder"\`, \`"::selection"\`). */
   element(_pseudoElement: string): CssBuilder<T> {
-    return this;
+    return this.unsupportedRuntime("element() cannot be used in RuntimeStyle css expressions.");
   }
 
   ${breakpointIfs}
@@ -1383,7 +1396,7 @@ class CssBuilder<T extends Properties> {
     if (typeof condOrMediaQuery === "boolean") {
       return new CssBuilder({ ...this.opts, enabled: condOrMediaQuery, elseApplied: false });
     }
-    return this.newCss({ selector: condOrMediaQuery, elseApplied: false });
+    return this.unsupportedRuntime("if(mediaQuery) cannot be used in RuntimeStyle css expressions.");
   }
 
   get else(): CssBuilder<T> {
@@ -1419,7 +1432,7 @@ class CssBuilder<T extends Properties> {
   /** Marker for the build-time transform to append a raw className. */
   className(className: string): CssBuilder<T> {
     void className;
-    return this;
+    return this.unsupportedRuntime("className() cannot be used in RuntimeStyle css expressions.");
   }
 
   /** Convert a style hash into \`{ className, style }\` props for manual spreading into non-\`css=\` contexts. */
@@ -1427,6 +1440,11 @@ class CssBuilder<T extends Properties> {
     return trussProps(styles as any);
   }
 
+  /** 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);
+  }
+
   private get rules(): T {
     return this.opts.rules;
   }
@@ -1436,6 +1454,9 @@ class CssBuilder<T extends Properties> {
   private get selector(): string | undefined {
     return this.opts.selector;
   }
+  private unsupportedRuntime(message: string): CssBuilder<T> {
+    return this.newCss({ runtimeError: message });
+  }
   private newCss(opts: Partial<Opts<T>>): CssBuilder<T> {
     return new CssBuilder({ ...this.opts, ...opts });
   }
@@ -1476,7 +1497,13 @@ export type Xss<P extends keyof Properties> = Pick<Properties, P>;
 export const marker: Marker = Symbol.for("truss-default-marker");
 
 /** An entry point for Css expressions. CssBuilder is immutable so this is safe to share. */
-export const Css = new CssBuilder({ rules: {}, enabled: true, selector: undefined, elseApplied: false });
+export const Css = new CssBuilder({
+  rules: {},
+  enabled: true,
+  selector: undefined,
+  elseApplied: false,
+  runtimeError: undefined,
+});
 
 ${typeAliasCode}