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

package/dist/compiler/variables.js

@@ -0,0 +1,272 @@
+import { createHash } from 'node:crypto';
+import { transform } from 'lightningcss';
+import { key, overrideKey, PreStyleError, valueOf } from './block.js';
+import { atRuleInfo } from './at-rules.js';
+import { SLOT_PREFIX } from './interpolate.js';
+import { print } from './print.js';
+import { withClass } from './selectors.js';
+// A variable a block's runtime values set. In parsed rules, a generated
+// variable's name is this prefix and a hash of what it's for, and the compiler
+// gives it a name when printing, like localized keyframes.
+export const VARIABLE_PREFIX = '--\0pre.style-variable:';
+const isSlot = (node) => {
+    const value = node;
+    return value?.type === 'var' && value.value.name.ident.startsWith(SLOT_PREFIX);
+};
+// A placeholder's slot, and its type from `type()`, which is in its name (in
+// hex) so that blocks differing only by type don't share a parse.
+const parseSlot = (node) => {
+    const [, slot, type] = /^(\d+)(?:-t([\da-f]+))?/.exec(node.value.name.ident.slice(SLOT_PREFIX.length));
+    return {
+        slot: Number(slot),
+        syntax: type === undefined ? null : Buffer.from(type, 'hex').toString(),
+    };
+};
+// Calls `visit` for each slot in a value, in the order they're written.
+function eachSlot(value, visit) {
+    if (Array.isArray(value)) {
+        for (const item of value)
+            eachSlot(item, visit);
+        return;
+    }
+    if (value === null || typeof value !== 'object')
+        return;
+    if (isSlot(value))
+        visit(value);
+    for (const child of Object.values(value))
+        eachSlot(child, visit);
+}
+const IGNORED = (token) => token.type === 'token' && token.value?.type === 'white-space';
+// The slot a declaration is entirely made of, for `--brand: ${color}` directly
+// on the element, which can set `--brand` itself. Under at-rules or a selector
+// variant, the generated class would have to be too, so those use a variable.
+function directSlot(atom) {
+    if (atom.atRules.length > 0 || atom.variant !== null || atom.declaration.important)
+        return null;
+    const declaration = atom.declaration.value;
+    // Lightning CSS also uses `custom` for properties it doesn't parse, such as
+    // `content` with a `var()`.
+    if (declaration.property !== 'custom' || !atom.property.startsWith('--'))
+        return null;
+    const tokens = declaration.value.value.filter((t) => !IGNORED(t));
+    const [token] = tokens;
+    if (tokens.length !== 1 || !isSlot(token))
+        return null;
+    return !token.value.fallback || parseSlot(token).syntax !== null ? token : null;
+}
+const hash = (identity) => createHash('sha256').update(JSON.stringify(identity)).digest('base64url').slice(0, 16);
+const SELF = '__pre-style-self__';
+// A declaration's selector, for where to set its variables. Null when it's the
+// element itself, as for `&:hover` and `.dark &`.
+function selectorOf(atom) {
+    if (atom.variant === null)
+        return null;
+    const selectors = withClass(atom.variant.selectors, SELF);
+    const onElement = selectors.every((selector) => {
+        const compound = selector.slice(selector.findLastIndex((c) => c.type === 'combinator') + 1);
+        return (compound.some((c) => c.type === 'class' && c.name === SELF) &&
+            !compound.some((c) => c.type === 'pseudo-element'));
+    });
+    if (onElement)
+        return null;
+    const rule = {
+        type: 'style',
+        value: {
+            selectors,
+            // Empty rules aren't printed.
+            declarations: {
+                declarations: [
+                    {
+                        property: 'custom',
+                        value: {
+                            name: '--z',
+                            value: [{ type: 'token', value: { type: 'ident', value: 'z' } }],
+                        },
+                    },
+                ],
+            },
+            rules: [],
+            loc: { source_index: 0, line: 0, column: 1 },
+        },
+    };
+    const { code } = print([rule], [], {}, false);
+    return code
+        .slice(0, code.indexOf('{'))
+        .trim()
+        .replace(/\s*\n\s*/g, ' ')
+        .split(`.${SELF}`);
+}
+const atomIdentity = (atom, index) => [
+    atom.atRules.map((segment) => segment.key),
+    atom.variant?.key ?? '',
+    atom.property,
+    index,
+];
+// `@property --a { syntax: "*"; inherits: false; }`. Without it, an element
+// with no value of its own takes its parent's instead of its default.
+const registration = (name) => {
+    const rule = {
+        type: 'property',
+        value: {
+            name,
+            syntax: { type: 'universal' },
+            inherits: false,
+            initialValue: null,
+            loc: { source_index: 0, line: 0, column: 1 },
+        },
+    };
+    return {
+        key: key(rule),
+        rule,
+        hoist: atRuleInfo('property').hoist,
+        overrideKey: null,
+        position: null,
+    };
+};
+// Units and functions that depend on where they're used. Browsers drop a
+// typed `@property` whose `initial-value` has them (tested in Chromium), and
+// Lightning CSS doesn't report them.
+const NOT_INDEPENDENT = /(?<![\w-])[+-]?[\d.]+(?:e[+-]?\d+)?(?:em|rem|ex|rex|ch|rch|lh|rlh|cap|rcap|ic|ric|cqw|cqh|cqi|cqb|cqmin|cqmax)\b|\b(?:env|attr)\(/i;
+const QUOTED = /"(?:[^"\\]|\\.)*"|'(?:[^'\\]|\\.)*'/g;
+// A slot's default, as CSS.
+function defaultText(node) {
+    const rule = {
+        type: 'style',
+        value: {
+            selectors: [[{ type: 'class', name: 'z' }]],
+            declarations: {
+                declarations: [
+                    { property: 'custom', value: { name: '--z', value: node.value.fallback ?? [] } },
+                ],
+            },
+            rules: [],
+            loc: { source_index: 0, line: 0, column: 1 },
+        },
+    };
+    const { code } = print([rule], [], {}, false);
+    return /--z:\s*(.*?);?\s*\}/s.exec(code)[1];
+}
+// `@property --a { syntax: "<length>"; inherits: false; initial-value: 1px; }`.
+function typedRegistration(name, syntax, initial, position) {
+    const invalid = (reason, cause) => new PreStyleError(`\`${initial}\` can't be the default of \`type(${syntax})\`: ${reason}`, position, { cause });
+    if (NOT_INDEPENDENT.test(initial.replace(QUOTED, '')))
+        throw invalid("a typed variable's default can't depend on where it's used, such as `em`, `rem`, container units, `env()`, or `attr()`, or browsers drop its `@property` rule. Use an absolute value, or leave out `type()`.");
+    let parsed;
+    try {
+        transform({
+            filename: 'type.css',
+            code: Buffer.from(`@property --z{syntax:${JSON.stringify(syntax)};inherits:false;initial-value:${initial}}`),
+            visitor: {
+                StyleSheetExit(sheet) {
+                    [parsed] = sheet.rules;
+                },
+            },
+        });
+    }
+    catch (error) {
+        throw invalid(`it isn't valid for that type (${error.message}).`, error);
+    }
+    const rule = { ...parsed, value: { ...valueOf(parsed), name } };
+    return {
+        key: key(rule),
+        rule,
+        hoist: atRuleInfo('property').hoist,
+        overrideKey: null,
+        position,
+    };
+}
+const SLOT_MESSAGE = "`${…}` can only be used in a declaration's value, because it becomes a `var()`, which isn't valid here.";
+// Points a slot at its variable, and registers the variable. A typed
+// variable's default moves to its `initial-value`, so each type and default
+// has its own variable.
+function useVariable(node, identity, slot, syntax, variables, added, position, selector = null) {
+    const initial = syntax === null ? null : defaultText(node);
+    const variable = hash([identity, syntax, initial]);
+    const name = VARIABLE_PREFIX + variable;
+    variables.push({ key: variable, property: null, slot, selector });
+    node.value.name.ident = name;
+    if (syntax !== null)
+        node.value.fallback = null;
+    if (added.has(variable))
+        return;
+    added.set(variable, syntax === null ? registration(name) : typedRegistration(name, syntax, initial, position));
+}
+// Replaces the slots in a global rule, such as a `@keyframes`, with variables
+// identified by the rule and their place in it, so the same rule in any block
+// shares them.
+function globalVariables(global, variables, added) {
+    const rule = structuredClone(global.rule);
+    const slots = [];
+    eachSlot(rule, (node) => slots.push(node));
+    const parsed = slots.map(parseSlot);
+    slots.forEach((node, index) => {
+        const type = parsed[index].syntax === null ? '' : `:${parsed[index].syntax}`;
+        node.value.name.ident = `${SLOT_PREFIX}${index}${type}`;
+    });
+    const identity = key(rule);
+    slots.forEach((node, index) => {
+        const { slot, syntax } = parsed[index];
+        useVariable(node, [identity, index], slot, syntax, variables, added, global.position);
+    });
+    const json = key(rule);
+    // Anywhere else, such as a selector Sass built, it isn't a `var()` node.
+    if (json.includes(SLOT_PREFIX))
+        throw new PreStyleError(SLOT_MESSAGE, global.position);
+    return { ...global, key: json, rule };
+}
+// Turns a parsed block's placeholder variables into its real ones. Runs after
+// overridden atoms are dropped, so their slots are left out. Variables are
+// identified by what they're for, so `width: ${w}px` in any block shares one
+// variable and class.
+export function extractVariables(atoms, globals) {
+    const variables = [];
+    const added = new Map();
+    const kept = globals.map((global) => global.key.includes(SLOT_PREFIX) ? globalVariables(global, variables, added) : global);
+    const keptAtoms = [];
+    for (const atom of atoms) {
+        const prefix = atom.atRules.map((segment) => segment.key).join() + (atom.variant?.key ?? '');
+        // Sass can move a placeholder, so its position is checked again here.
+        if (prefix.includes(SLOT_PREFIX))
+            throw new PreStyleError(SLOT_MESSAGE, atom.position);
+        if (!atom.declaration.key.includes(SLOT_PREFIX)) {
+            keptAtoms.push(atom);
+            continue;
+        }
+        const direct = directSlot(atom);
+        if (direct !== null) {
+            const { slot, syntax } = parseSlot(direct);
+            variables.push({
+                key: `direct:${atom.property}`,
+                property: atom.property,
+                slot,
+                selector: null,
+            });
+            // A typed custom property registers itself, under its own name.
+            if (syntax !== null) {
+                const registered = typedRegistration(atom.property, syntax, defaultText(direct), atom.position);
+                added.set(`direct:${atom.property}:${registered.key}`, {
+                    ...registered,
+                    overrideKey: overrideKey(registered.rule),
+                });
+            }
+            continue;
+        }
+        const value = structuredClone(atom.declaration.value);
+        const selector = selectorOf(atom);
+        let index = 0;
+        eachSlot(value, (node) => {
+            const { slot, syntax } = parseSlot(node);
+            const identity = atomIdentity(atom, index++);
+            useVariable(node, identity, slot, syntax, variables, added, atom.position, selector);
+        });
+        keptAtoms.push({
+            ...atom,
+            declaration: {
+                ...atom.declaration,
+                key: key(value) + (atom.declaration.important ? '!' : ''),
+                value,
+            },
+        });
+    }
+    return { atoms: keptAtoms, globals: [...kept, ...added.values()], variables };
+}

package/dist/index.d.ts

@@ -1,6 +1,7 @@
-export declare function css(_strings: TemplateStringsArray): string;
-export declare function scss(_strings: TemplateStringsArray): string;
+export type RuntimeValue = string | number | null | undefined;
+export declare function css(_strings: TemplateStringsArray, ..._values: RuntimeValue[]): string;
+export declare function scss(_strings: TemplateStringsArray, ..._values: RuntimeValue[]): string;
 import { createCn } from './cn.ts';
 export declare const cn: (...inputs: import("./cn.ts").ClassValue[]) => string;
 export { createCn };
-export type { ClassDictionary, ClassValue, CnTable } from './cn.ts';
+export type { ClassDictionary, ClassValue, CnLookup, CnTable } from './cn.ts';

package/dist/index.js

@@ -4,10 +4,10 @@
 function notTransformed() {
     throw new Error('pre.style transform not applied. css and scss blocks must be compiled by a pre.style bundler plugin, such as @pre.style/vite.');
 }
-export function css(_strings) {
+export function css(_strings, ..._values) {
     return notTransformed();
 }
-export function scss(_strings) {
+export function scss(_strings, ..._values) {
     return notTransformed();
 }
 import { createCn } from './cn.js';

package/dist/runtime-dev.d.ts

@@ -0,0 +1,2 @@
+export declare const dynamic: (classes: string, values: readonly unknown[], ...variables: import("./runtime.ts").RuntimeVariable[]) => string;
+export declare const dynamicLowercase: (classes: string, values: readonly unknown[], ...variables: import("./runtime.ts").RuntimeVariable[]) => string;

package/dist/runtime-dev.js

@@ -0,0 +1,9 @@
+import { CASE_INSENSITIVE, CASE_SENSITIVE, create } from './runtime.js';
+// `./runtime.ts` with full error messages, which the bundler plugin uses
+// outside production builds.
+const invalidValue = (value, strings) => {
+    const got = typeof value === 'number' ? String(value) : typeof value;
+    throw new TypeError(`pre.style: \`\${…}\` values must be strings or numbers, or null or undefined to use the default. Got ${got} in \`${strings.join('${…}')}\`. For a condition, write \`\${open ? width : null}\` rather than \`\${open && width}\`.`);
+};
+export const dynamic = /* @__PURE__ */ create(CASE_SENSITIVE, invalidValue);
+export const dynamicLowercase = /* @__PURE__ */ create(CASE_INSENSITIVE, invalidValue);

package/dist/runtime.d.ts

@@ -0,0 +1,16 @@
+import type { CnLookup } from './cn.ts';
+export type RuntimeVariable = [
+    name: string,
+    strings: readonly string[],
+    indexes: readonly number[],
+    property?: string | 0,
+    selector?: readonly string[]
+];
+export declare const CASE_SENSITIVE: string;
+export declare const CASE_INSENSITIVE: string;
+export type InvalidValue = (value: unknown, strings: readonly string[]) => never;
+export declare const create: (alphabet: string, invalid: InvalidValue) => (classes: string, values: readonly unknown[], ...variables: RuntimeVariable[]) => string;
+export declare const dynamic: (classes: string, values: readonly unknown[], ...variables: RuntimeVariable[]) => string;
+export declare const dynamicLowercase: (classes: string, values: readonly unknown[], ...variables: RuntimeVariable[]) => string;
+export type CnVariables = Record<string, string>;
+export declare const generatedClasses: (variables: CnVariables) => CnLookup;

package/dist/runtime.js

@@ -0,0 +1,99 @@
+const DIGITS = '0123456789';
+const LOWERCASE = 'abcdefghijklmnopqrstuvwxyz';
+export const CASE_SENSITIVE = DIGITS + LOWERCASE + LOWERCASE.toUpperCase();
+export const CASE_INSENSITIVE = DIGITS + LOWERCASE;
+const HASH_LENGTH = 4;
+// A hash of a value that's the same on the server and in the browser, since
+// the class names it's part of have to match for hydration. FNV-1a.
+function hash(value, alphabet) {
+    let h = 0x811c9dc5;
+    for (let i = 0; i < value.length; i++) {
+        h ^= value.charCodeAt(i);
+        h = Math.imul(h, 0x01000193);
+    }
+    h >>>= 0;
+    let result = '';
+    for (let i = 0; i < HASH_LENGTH; i++) {
+        result += alphabet[h % alphabet.length];
+        h = Math.floor(h / alphabet.length);
+    }
+    return result;
+}
+// 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.
+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]];
+        if (value === null || value === undefined)
+            missing = true;
+        else if (typeof value === 'string' || (typeof value === 'number' && Number.isFinite(value)))
+            result += value + strings[i + 1];
+        else
+            invalid(value, strings);
+    }
+    return missing ? null : result;
+}
+let sheet;
+const inserted = new Set();
+// Inserts a generated class's rule once. `setProperty` parses the value alone,
+// so a value can't add rules or declarations, even if it comes from a user.
+function insert(selector, className, property, value) {
+    if (inserted.has(className))
+        return;
+    inserted.add(className);
+    // An unknown selector is ignored, as it is in the CSS file. Browsers without
+    // constructable stylesheets, or where the list can't be changed (Chrome before
+    // 99, Firefox before 101, Safari before 16.4), keep the defaults rather than
+    // failing the render.
+    try {
+        if (sheet === undefined) {
+            sheet = new CSSStyleSheet();
+            document.adoptedStyleSheets.push(sheet);
+        }
+        const index = sheet.insertRule(`${selector}{}`, sheet.cssRules.length);
+        sheet.cssRules[index].style.setProperty(property, value);
+    }
+    catch { }
+}
+export const create = (alphabet, invalid) => (classes, values, ...variables) => {
+    let result = classes;
+    for (const [name, strings, indexes, property, selector] of variables) {
+        const value = text(strings, indexes, values, invalid);
+        if (value === null)
+            continue;
+        const className = `_${name}${hash(value, alphabet)}`;
+        // The server returns the same class strings, without the rules, so
+        // hydration matches and the page uses its defaults until this runs.
+        if (typeof document !== 'undefined')
+            insert(selector ? selector.join(`.${className}`) : `.${className}`, className, property || `--${name}`, value);
+        result += result === '' ? className : ` ${className}`;
+    }
+    return result;
+};
+// Production errors are numbered, to keep the runtime small. The site's
+// `/errors` pages explain them, and `./runtime-dev.ts` has the full messages.
+const invalidValue = (value) => {
+    throw new TypeError(`pre.style error 1 (${typeof value}): https://pre.style/errors/1`);
+};
+// What a block with `${…}` compiles to. It takes the block's class string, its
+// expressions' values, so each runs once and in order, and its variables, and
+// returns the class string with a generated class for each value.
+export const dynamic = /* @__PURE__ */ create(CASE_SENSITIVE, invalidValue);
+// For the `quirksMode` setting, where class selectors ignore case.
+export const dynamicLowercase = /* @__PURE__ */ create(CASE_INSENSITIVE, invalidValue);
+// A `cn` lookup that also recognizes generated classes, which aren't in its
+// table: `_`, a variable's name, and four characters. Each sets its variable on
+// the element. It's here rather than in `cn`, so apps without `${…}` don't ship
+// it.
+export const generatedClasses = (variables) => new (class extends Map {
+    get(className) {
+        const name = className.slice(1, -4);
+        return (super.get(className) ??
+            (className[0] === '_' && Object.hasOwn(variables, name)
+                ? ['', variables[name] || `--${name}`]
+                : undefined));
+    }
+})();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pre.style/core",
-  "version": "3.1.0-alpha.1",
+  "version": "3.1.0-alpha.3",
   "description": "Zero-runtime CSS-in-JS that compiles css and scss blocks into atomic CSS classes.",
   "keywords": [
     "atomic-css",
@@ -37,6 +37,16 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
+    "./runtime": {
+      "pre.style-source": "./src/runtime.ts",
+      "types": "./dist/runtime.d.ts",
+      "default": "./dist/runtime.js"
+    },
+    "./runtime/dev": {
+      "pre.style-source": "./src/runtime-dev.ts",
+      "types": "./dist/runtime-dev.d.ts",
+      "default": "./dist/runtime-dev.js"
+    },
     "./compiler": {
       "pre.style-source": "./src/compiler/index.ts",
       "types": "./dist/compiler/index.d.ts",

package/package.schema.json

@@ -61,6 +61,10 @@
         "prependFiles": {
           "$ref": "#/definitions/prependFiles"
         },
+        "customPropertyLocalization": {
+          "description": "Give each custom property declared in the library's blocks and stylesheet files a generated name, used only in the block or file that declares it. Names it only reads, and names from prepended files, stay global. The app's setting doesn't apply to libraries.",
+          "type": "boolean"
+        },
         "keyframeLocalization": {
           "description": "Give each @keyframes in the library's blocks and stylesheet files a generated name, used only in the block or file that defines it, like styled-components' `keyframes`. The app's setting doesn't apply to libraries.",
           "type": "boolean"
@@ -88,6 +92,10 @@
         "prependFiles": {
           "$ref": "#/definitions/prependFiles"
         },
+        "customPropertyLocalization": {
+          "description": "Give each custom property declared in the app's blocks and stylesheet files a generated name, used only in the block or file that declares it. Names it only reads, and names from prepended files, stay global. Libraries use their own setting.",
+          "type": "boolean"
+        },
         "keyframeLocalization": {
           "description": "Give each @keyframes in the app's blocks and stylesheet files a generated name, used only in the block or file that defines it (including keyframes from prepended files), like styled-components' `keyframes`. Libraries use their own setting.",
           "type": "boolean"