@pre.style/core 3.1.0-alpha.3 → 3.1.0-alpha.4

package/README.md

@@ -246,14 +246,10 @@ css`
 }
 ```
 
-Values work in nested selectors too, including pseudo-elements and other elements. The generated class's rule uses the same selector, so the value reaches them. `content` needs a string, so pass one:
+Values work in nested selectors too, including pseudo-elements and other elements. The generated class's rule uses the same selector, so the value reaches them:
 
 ```js
 css`
-  &::before {
-    content: var(${JSON.stringify(String(count))}, "0");
-  }
-
   & > * {
     margin-top: ${gap}px;
   }
@@ -266,11 +262,38 @@ css`
 
 ```css
 /* Inserted by the runtime */
-._A3fK9::before {
-  --A: "5";
+._A3fK9 > * {
+  --A: 8px;
+}
+```
+
+#### Strings and URLs
+
+Write quotes around `${…}` for a string, with any text you like. The runtime escapes the value, and numbers work too. `url()` needs its quotes:
+
+```js
+css`
+  background-image: url("/img/${name}.png");
+
+  &::before {
+    content: var("Count: ${count}", "Loading");
+  }
+`;
+```
+
+```css
+/* Inserted by the runtime */
+._A3fK9 {
+  --A: url("/img/photo.png");
+}
+
+._B7xQ2::before {
+  --B: "Count: 5";
 }
 ```
 
+The whole string is the value, so a default goes around it, as above. `content: ${x}` without quotes doesn't add any: use it for values that are already CSS, such as `none` or `counter(n)`. In `scss` blocks, `#{…}` can't be in the same value as `${…}`.
+
 #### Custom properties
 
 Name a custom property to share a value: with other elements, which inherit it, with something else that reads that name, or across several declarations in a block. For a value that's only used on one element, write `${…}` directly instead. A name is global, so two blocks using the same one can affect each other. To avoid that, use distinctive names, or [`customPropertyLocalization`](#local-custom-properties).
@@ -408,18 +431,7 @@ css`
   margin-${side}: 0;                       /* property names */
   @media (min-width: ${bp}px) { top: 0; }  /* at-rule conditions, see Sharing media queries */
   @font-face { font-weight: ${weight}; }   /* @font-face, @property, @page, and similar */
-  content: "${label}";                     /* quoted strings */
-  background-image: url(${path});          /* url() */
-`;
-```
-
-For strings and URLs, pass the whole value:
-
-```js
-css`
-  content: ${JSON.stringify(label)};
-  --image: ${`url("${path}")`};
-  background-image: var(--image);
+  background-image: url(${path});          /* url() without quotes */
 `;
 ```
 
@@ -448,16 +460,30 @@ In older browsers:
 
 #### When to use `style` instead
 
-Every new value adds a rule that's never removed. That suits values with a limited set of results, such as a theme color or a chosen size. For values that change constantly, such as a drag position or anything set per frame, use the `style` attribute and read it from the block:
+A block compiles to a class string, so the runtime can't tell which element it's for. That's why each distinct value gets its own class, rather than one class whose value changes: two elements from the same block can have different values, as in a list. So the class changes with the value, and every new value adds a rule that's never removed.
+
+That suits values from a small set, such as a theme color or a chosen size, where going back to a value reuses its class. For values that change constantly, such as a counter, a drag position, or anything set per frame, use the `style` attribute and read it from a static block. The class never changes, no rules are added, the server renders the real value, and no runtime is needed:
 
 ```jsx
 const box = css`
-  transform: translateX(var(--x));
+  transform: translateX(var(--x, 0));
 `;
 
 <div className={box} style={{ "--x": `${x}px` }} />;
 ```
 
+| | `${…}` | `style` |
+| --- | --- | --- |
+| The class | Changes with the value | Stays the same |
+| CSS rules | One per distinct value, kept | None added |
+| On the server | The default, until the runtime runs | The real value |
+| In `cn` | Later values win | Not involved |
+| Runtime | Needed | Not needed |
+| In pseudo-elements and other elements | Reaches them | Only if the property inherits |
+| Best for | Values from a small set | Values that change constantly |
+
+The demos' Interpolation pages show both side by side.
+
 ### Selectors
 
 Use `&` for the element, as in native CSS nesting. Anything that isn't the bare element (pseudo-classes, pseudo-elements, and complex selectors) becomes a selector variant:

package/dist/compiler/interpolate.js

@@ -16,7 +16,8 @@ const NO_VARIABLES = /^@(font-face|property|page|counter-style|font-feature-valu
 const SASS_AT_RULES = /^@(include|return|if|else|each|for|while|debug|warn|error|function|mixin)\b/;
 const POSITION_MESSAGE = "`${…}` can only be used in a declaration's value, because it becomes a `var()`, which isn't valid in selectors, property names, or at-rule conditions. To share media queries, use Sass variables.";
 const NO_VARIABLES_MESSAGE = "`${…}` can't be used here: this at-rule doesn't accept `var()`, or has no element for the runtime to set it on.";
-const QUOTED_MESSAGE = '`${…}` can\'t be used inside a quoted string or `url()`, because it becomes a `var()`, which doesn\'t work there. Pass the whole value instead: `content: ${JSON.stringify(label)}`, or `--image: ${`url("${path}")`}` with `background-image: var(--image)`.';
+const UNQUOTED_URL_MESSAGE = '`${…}` can\'t be used in an unquoted `url()`. Add quotes: `url("${path}")`.';
+const SASS_MESSAGE = "`#{…}` can't be used in the same value as `${…}`, because that value is set at runtime, after Sass has run. Use a Sass variable in a separate declaration.";
 const TYPE_RUNTIME_MESSAGE = "`type()` and its default are written to the CSS file, so they can't use `${…}`.";
 const TYPE_DEFAULT_MESSAGE = '`type()` needs a default, because a typed `@property` requires an `initial-value`: `var(${w}px type(<length>), 120px)`.';
 const FUNCTION_MESSAGE = "`${…}` can't be used as a function's name.";
@@ -50,11 +51,26 @@ export function interpolate(strings, expressions, lang) {
     // Adds a slot for the text at [start, end), and returns its placeholder's
     // name, and the newlines to write after it, so later lines stay in place.
     const addSlot = (start, end) => {
+        const span = text.slice(start, end);
+        if (lang === 'scss' && span.includes('#{'))
+            fail(SASS_MESSAGE, start);
         const first = expressionIndex(start);
-        const parts = text.slice(start, end).split(EXPRESSION);
-        const used = Array.from({ length: parts.length - 1 }, (_, i) => first + i);
+        const parts = span.split(EXPRESSION);
+        const used = [];
+        let quote = null;
+        for (let i = 0; i < span.length; i++) {
+            const ch = span[i];
+            if (ch === '\\')
+                i++;
+            else if (ch === EXPRESSION) {
+                const index = first + used.length;
+                used.push(quote === null ? index : ~index);
+            }
+            else if (quote === null ? ch === '"' || ch === "'" : ch === quote)
+                quote = quote === null ? ch : null;
+        }
         const index = slots.push({ strings: parts, expressions: used }) - 1;
-        const lines = newlines(text.slice(start, end)) + used.reduce((n, e) => n + newlines(expressions[e]), 0);
+        const lines = newlines(span) + used.reduce((n, e) => n + newlines(expressions[e < 0 ? ~e : e]), 0);
         return { name: `${SLOT_PREFIX}${index}`, lines: '\n'.repeat(lines) };
     };
     // What's open: parentheses and Sass's `#{…}`, which don't end statements,
@@ -62,15 +78,14 @@ export function interpolate(strings, expressions, lang) {
     const open = [];
     const atStatementLevel = () => open.length === 0 || open.at(-1).type === '{';
     let statementStart = 0;
-    // The end of the string starting at `start`, an error if it has an
-    // expression in it.
+    // Where the last `#{…}` ended, since it can't touch a slot.
+    let sassEnd = -1;
+    // The end of the string starting at `start`.
     const stringEnd = (start) => {
         let i = start + 1;
         for (; i < text.length && text[i] !== text[start]; i++) {
             if (text[i] === '\\')
                 i++;
-            else if (text[i] === EXPRESSION)
-                fail(QUOTED_MESSAGE, i);
         }
         return i + 1;
     };
@@ -172,25 +187,43 @@ export function interpolate(strings, expressions, lang) {
         }
         if (ch === '"' || ch === "'") {
             const end = stringEnd(i);
-            code += text.slice(i, end);
+            const string = text.slice(i, end);
+            // `"Count: ${i}"`: the whole string is the value, since a `var()` can't
+            // go inside one.
+            if (string.includes(EXPRESSION)) {
+                checkPosition(i, end);
+                const slot = addSlot(i, end);
+                code += `var(${slot.name})${slot.lines}`;
+            }
+            else
+                code += string;
             i = end;
             tokenStart = i;
             tokenCode = code.length;
             continue;
         }
         const standsAlone = i === 0 || !IDENT.test(text[i - 1]);
-        // An unquoted `url()` is one token, which can't hold a `var()`.
+        // A `url()` can't hold a `var()`, so it's a value as a whole.
         if (standsAlone && text.slice(i, i + 4).toLowerCase() === 'url(') {
             const argument = /\s*/y;
             argument.lastIndex = i + 4;
-            const first = text[i + 4 + argument.exec(text)[0].length];
-            if (first !== '"' && first !== "'") {
-                const close = text.indexOf(')', i);
-                const end = close === -1 ? text.length : close + 1;
-                const inside = text.indexOf(EXPRESSION, i);
-                if (inside !== -1 && inside < end)
-                    fail(QUOTED_MESSAGE, inside);
-                code += text.slice(i, end);
+            const firstAt = i + 4 + argument.exec(text)[0].length;
+            const first = text[firstAt];
+            const quoted = first === '"' || first === "'";
+            const close = text.indexOf(')', quoted ? stringEnd(firstAt) : i);
+            const end = close === -1 ? text.length : close + 1;
+            const inside = text.slice(i, end).indexOf(EXPRESSION);
+            if (inside !== -1 && !quoted)
+                fail(UNQUOTED_URL_MESSAGE, i + inside);
+            if (inside !== -1 || !quoted) {
+                // `url("${path}")`: the whole `url()` is the value.
+                if (inside !== -1) {
+                    checkPosition(i, end);
+                    const slot = addSlot(i, end);
+                    code += `var(${slot.name})${slot.lines}`;
+                }
+                else
+                    code += text.slice(i, end);
                 i = end;
                 tokenStart = i;
                 tokenCode = code.length;
@@ -237,6 +270,8 @@ export function interpolate(strings, expressions, lang) {
                 end++;
             if (text[end] === '(')
                 fail(FUNCTION_MESSAGE, i);
+            if (tokenStart === sassEnd || (text[end - 1] === '#' && text[end] === '{'))
+                fail(SASS_MESSAGE, i);
             checkPosition(tokenStart, end);
             const slot = addSlot(tokenStart, end);
             code = `${code.slice(0, tokenCode)}var(${slot.name})${slot.lines}`;
@@ -264,9 +299,10 @@ export function interpolate(strings, expressions, lang) {
             }
         }
         else if (ch === '}') {
-            if (open.length > 0)
-                open.pop();
-            if (atStatementLevel())
+            // Sass's `#{…}` is part of a value, so it doesn't end a statement.
+            if (open.pop()?.type === '#{')
+                sassEnd = i + 1;
+            else if (atStatementLevel())
                 statementStart = i + 1;
         }
         else if (ch === ';' && atStatementLevel())

package/dist/runtime.js

@@ -19,6 +19,8 @@ function hash(value, alphabet) {
     }
     return result;
 }
+// What can't be written as it is in a quoted CSS string.
+const UNSAFE_IN_STRING = /["'\\\n\r\f]/g;
 // The variable's value, or null when any of its values is null or undefined,
 // so its default applies. Anything else is almost always a bug, which falling
 // back would hide.
@@ -26,11 +28,15 @@ function text(strings, indexes, values, invalid) {
     let result = strings[0];
     let missing = false;
     for (let i = 0; i < indexes.length; i++) {
-        const value = values[indexes[i]];
+        const index = indexes[i];
+        const value = values[index < 0 ? ~index : index];
         if (value === null || value === undefined)
             missing = true;
         else if (typeof value === 'string' || (typeof value === 'number' && Number.isFinite(value)))
-            result += value + strings[i + 1];
+            result +=
+                (index < 0
+                    ? String(value).replace(UNSAFE_IN_STRING, (c) => `\\${c.charCodeAt(0).toString(16)} `)
+                    : value) + strings[i + 1];
         else
             invalid(value, strings);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pre.style/core",
-  "version": "3.1.0-alpha.3",
+  "version": "3.1.0-alpha.4",
   "description": "Zero-runtime CSS-in-JS that compiles css and scss blocks into atomic CSS classes.",
   "keywords": [
     "atomic-css",