@astryxdesign/core 0.6.2 → 0.6.3-canary.0899f21

package/dist/theme/declarationBoundary.js

@@ -0,0 +1,343 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Declaration boundary scanner
+ *
+ * Decides whether a consumer-supplied property name and value can be emitted
+ * as exactly one CSS declaration, `name: value;`, without the value ending
+ * the declaration early or swallowing what follows it. Theme definitions are
+ * code, but apps assemble them from stored input (brand colors,
+ * white-labeling), so the generated stylesheet must never extend beyond the
+ * declarations it means to emit.
+ *
+ * The scanner follows the CSS Syntax Module Level 3 tokenizer for everything
+ * that decides where a declaration ends: strings with backslash escapes and
+ * line continuations, comments, `url()` with an unquoted body, escaped code
+ * points outside strings, and `()`, `[]`, `{}` block nesting. Inside any of
+ * those a `;` or a brace is inert, exactly as a browser reads it, so a `data:`
+ * URI, `Gill\ Sans`, or a closed comment passes through byte-identically.
+ * Only what a browser would read as the end of the declaration or rule is
+ * rejected: an unnested `;`, `{` or `}`, an unbalanced closer, and anything
+ * left open at the end of the value (a string, comment, block, or url whose
+ * closer would then be the generator's own `;` or `}`). A `bad-string` or
+ * `bad-url` token is rejected as well: the browser would discard the
+ * declaration anyway, and a diagnostic beats a silent no-op.
+ *
+ * @input A property name or a declaration value as authored in a theme
+ * @output `null` when it can be emitted, otherwise the reason it cannot
+ * @position packages/core/src/theme/declarationBoundary.ts
+ */
+
+/** Newline per CSS Syntax §4.2 (after preprocessing, CR and FF are newlines). */
+function isNewline(ch) {
+  return ch === '\n' || ch === '\r' || ch === '\f';
+}
+function isWhitespace(ch) {
+  return ch === ' ' || ch === '\t' || isNewline(ch);
+}
+function isHexDigit(ch) {
+  return /^[0-9a-fA-F]$/.test(ch);
+}
+
+/** Name-start code point: letter, underscore, or any non-ASCII code point. */
+function isNameStart(ch) {
+  return /^[A-Za-z_]$/.test(ch) || ch.charCodeAt(0) >= 0x80;
+}
+function isNameChar(ch) {
+  return isNameStart(ch) || /^[0-9-]$/.test(ch);
+}
+
+/** CSS Syntax §3.3 preprocessing, for scanning only; emitted bytes stay intact. */
+function preprocess(input) {
+  return input.replace(/\r\n?|\f/g, '\n').replace(/\0/g, '\uFFFD');
+}
+
+/** Non-printable code points make an unquoted url() a bad-url token. */
+// eslint-disable-next-line no-control-regex -- these code points are the subject
+const NON_PRINTABLE = /[\x01-\x08\x0b\x0e-\x1f\x7f]/;
+
+/** "Check if two code points are a valid escape" (§4.3.8). */
+function isValidEscape(input, pos) {
+  return input[pos] === '\\' && pos + 1 < input.length && !isNewline(input[pos + 1]);
+}
+
+/** "Check if three code points would start an ident sequence" (§4.3.9). */
+function startsIdent(input, pos) {
+  const ch = input[pos];
+  if (ch === '-') {
+    const next = input[pos + 1];
+    return next !== undefined && (next === '-' || isNameStart(next) || isValidEscape(input, pos + 1));
+  }
+  if (ch === '\\') {
+    return isValidEscape(input, pos);
+  }
+  return ch !== undefined && isNameStart(ch);
+}
+
+/**
+ * "Consume an escaped code point" (§4.3.7), positioned after the backslash.
+ * Returns the position after the escape. A hex escape takes up to six hex
+ * digits plus one optional whitespace; anything else takes one code point.
+ */
+function consumeEscape(input, pos) {
+  if (isHexDigit(input[pos])) {
+    let end = pos;
+    while (end < input.length && end - pos < 6 && isHexDigit(input[end])) {
+      end++;
+    }
+    if (end < input.length && isWhitespace(input[end])) {
+      end++;
+    }
+    return end;
+  }
+  // A surrogate pair is one code point.
+  const code = input.codePointAt(pos) ?? 0;
+  return pos + (code > 0xffff ? 2 : 1);
+}
+
+/**
+ * "Consume an ident sequence" (§4.3.11) starting at `pos`. Returns the
+ * position after it and the decoded name (escapes resolved, for the
+ * case-insensitive `url` check; hex escapes decode to their code point).
+ */
+function consumeIdent(input, pos) {
+  let name = '';
+  let i = pos;
+  while (i < input.length) {
+    const ch = input[i];
+    if (isNameChar(ch)) {
+      name += ch;
+      i++;
+    } else if (isValidEscape(input, i)) {
+      const end = consumeEscape(input, i + 1);
+      if (isHexDigit(input[i + 1])) {
+        const hex = input.slice(i + 1, end).trim();
+        const code = parseInt(hex, 16);
+        name += code === 0 || code > 0x10ffff || code >= 0xd800 && code <= 0xdfff ? '\uFFFD' : String.fromCodePoint(code);
+      } else {
+        name += input.slice(i + 1, end);
+      }
+      i = end;
+    } else {
+      break;
+    }
+  }
+  return {
+    end: i,
+    name
+  };
+}
+
+/**
+ * "Consume a string token" (§4.3.5), positioned at the opening quote.
+ * Returns the position after the closing quote, or a rejection reason.
+ */
+function consumeString(input, pos) {
+  const quote = input[pos];
+  let i = pos + 1;
+  while (i < input.length) {
+    const ch = input[i];
+    if (ch === quote) {
+      return {
+        end: i + 1
+      };
+    }
+    if (isNewline(ch)) {
+      // A raw newline ends the string as a bad-string token; the browser
+      // discards the declaration, so a diagnostic is more useful than
+      // reasoning about where that leaves the next `;`.
+      return {
+        reason: 'a newline inside a quoted string makes a bad string'
+      };
+    }
+    if (ch === '\\') {
+      if (i + 1 >= input.length) {
+        break;
+      }
+      // Escaped newline is a line continuation; any other escape consumes
+      // the escaped code point (so `\"` never closes the string).
+      i = isNewline(input[i + 1]) ? i + 2 : consumeEscape(input, i + 1);
+      continue;
+    }
+    i++;
+  }
+  return {
+    reason: `an unclosed ${quote} string would swallow the rest of the rule`
+  };
+}
+
+/**
+ * "Consume a url token" (§4.3.6), positioned after `url(` and any leading
+ * whitespace, with a non-quote next code point. Returns the position after
+ * the closing `)`, or a rejection reason (bad-url or unclosed).
+ */
+function consumeUrl(input, pos) {
+  let i = pos;
+  while (i < input.length) {
+    const ch = input[i];
+    if (ch === ')') {
+      return {
+        end: i + 1
+      };
+    }
+    if (isWhitespace(ch)) {
+      while (i < input.length && isWhitespace(input[i])) {
+        i++;
+      }
+      if (i >= input.length) {
+        break;
+      }
+      if (input[i] === ')') {
+        return {
+          end: i + 1
+        };
+      }
+      return {
+        reason: 'whitespace inside an unquoted url() makes a bad url'
+      };
+    }
+    if (NON_PRINTABLE.test(ch)) {
+      return {
+        reason: 'a non-printable character inside url() makes a bad url'
+      };
+    }
+    if (ch === '"' || ch === "'" || ch === '(') {
+      return {
+        reason: `"${ch}" inside an unquoted url() makes a bad url; quote the URL instead`
+      };
+    }
+    if (ch === '\\') {
+      if (!isValidEscape(input, i)) {
+        return {
+          reason: 'a stray backslash inside url() makes a bad url'
+        };
+      }
+      i = consumeEscape(input, i + 1);
+      continue;
+    }
+    i++;
+  }
+  return {
+    reason: 'an unclosed url( would swallow the rest of the rule'
+  };
+}
+const CLOSER = {
+  '(': ')',
+  '[': ']',
+  '{': '}'
+};
+
+/**
+ * Why `value` cannot be emitted as the value of one declaration, or `null`
+ * when it can. Valid CSS a browser keeps inside one declaration always
+ * returns `null`; see the file header for the exact rules.
+ */
+export function checkDeclarationValue(input) {
+  const value = preprocess(input);
+  const open = [];
+  let i = 0;
+  while (i < value.length) {
+    const ch = value[i];
+    if (ch === '/' && value[i + 1] === '*') {
+      const close = value.indexOf('*/', i + 2);
+      if (close === -1) {
+        return 'an unclosed /* comment would swallow the rest of the rule';
+      }
+      i = close + 2;
+      continue;
+    }
+    if (ch === '"' || ch === "'") {
+      const result = consumeString(value, i);
+      if ('reason' in result) {
+        return result.reason;
+      }
+      i = result.end;
+      continue;
+    }
+    if (startsIdent(value, i)) {
+      const ident = consumeIdent(value, i);
+      i = ident.end;
+      if (value[i] === '(' && ident.name.toLowerCase() === 'url') {
+        let j = i + 1;
+        while (j < value.length && isWhitespace(value[j])) {
+          j++;
+        }
+        if (value[j] === '"' || value[j] === "'") {
+          // `url("...")` is an ordinary function token; the string and the
+          // closing paren are handled by the loop.
+          open.push(')');
+          i = i + 1;
+          continue;
+        }
+        const result = consumeUrl(value, j);
+        if ('reason' in result) {
+          return result.reason;
+        }
+        i = result.end;
+      }
+      continue;
+    }
+    if (ch === '\\') {
+      if (i + 1 >= value.length) {
+        // `\` followed by the generator's own `;` would escape it.
+        return 'a trailing backslash would escape the declaration terminator';
+      }
+      // `\` + newline is not an escape: the backslash is a delim and the
+      // newline is whitespace. Anything else escapes the next code point.
+      i = isNewline(value[i + 1]) ? i + 1 : consumeEscape(value, i + 1);
+      continue;
+    }
+    if (ch === '(' || ch === '[' || ch === '{') {
+      if (ch === '{' && open.length === 0) {
+        return 'an unquoted "{" would open a nested block';
+      }
+      open.push(CLOSER[ch]);
+      i++;
+      continue;
+    }
+    if (ch === ')' || ch === ']' || ch === '}') {
+      if (open.length === 0) {
+        return ch === '}' ? 'an unquoted "}" would close the rule' : `an unbalanced "${ch}" has nothing to close`;
+      }
+      const expected = open.pop();
+      if (expected !== ch) {
+        return `"${ch}" does not close the open "${expected === ')' ? '(' : expected === ']' ? '[' : '{'}"`;
+      }
+      i++;
+      continue;
+    }
+    if (ch === ';' && open.length === 0) {
+      return 'an unquoted ";" would end the declaration';
+    }
+    i++;
+  }
+  if (open.length > 0) {
+    const closer = open[open.length - 1];
+    const opener = closer === ')' ? '(' : closer === ']' ? '[' : '{';
+    return `an unclosed "${opener}" would swallow the rest of the rule`;
+  }
+  return null;
+}
+
+/**
+ * Why `name` cannot be emitted as a declaration's property name, or `null`
+ * when it can. A property name is one CSS ident sequence: a standard
+ * property (`color`), a vendor-prefixed one (`-webkit-line-clamp`), or a
+ * custom property (`--brand-accent`, `--_internal`). Escapes are allowed
+ * because an ident allows them. Whether the name means anything to the
+ * browser is not this check's concern; only that it cannot end the
+ * declaration or leak a second one.
+ */
+export function checkDeclarationName(input) {
+  const name = preprocess(input);
+  if (name.length === 0 || !startsIdent(name, 0)) {
+    return 'a property name must be a CSS identifier';
+  }
+  const {
+    end
+  } = consumeIdent(name, 0);
+  if (end !== name.length) {
+    return `a property name must be one CSS identifier; "${name[end]}" cannot appear in one`;
+  }
+  return null;
+}

package/dist/theme/derivedVarRegistry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"derivedVarRegistry.d.ts","sourceRoot":"","sources":["../../src/theme/derivedVarRegistry.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;GAgBG;AAEH,MAAM,WAAW,eAAe;IAC9B,2EAA2E;IAC3E,QAAQ,EAAE,MAAM,CAAC;IACjB,2EAA2E;IAC3E,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,iFAAiF;IACjF,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,EAAE,CA+ChE,CAAC;AAiBF;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,GACf,eAAe,EAAE,CASnB"}
+{"version":3,"file":"derivedVarRegistry.d.ts","sourceRoot":"","sources":["../../src/theme/derivedVarRegistry.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;GAgBG;AAEH,MAAM,WAAW,eAAe;IAC9B,2EAA2E;IAC3E,QAAQ,EAAE,MAAM,CAAC;IACjB,2EAA2E;IAC3E,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,iFAAiF;IACjF,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,EAAE,CAgDhE,CAAC;AAiBF;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,GACf,eAAe,EAAE,CASnB"}

package/dist/theme/derivedVarRegistry.js

@@ -81,6 +81,10 @@ export const derivedVarRegistry = {
     property: 'borderRadius',
     vars: ['--_hovercard-radius']
   }],
+  item: [{
+    property: 'paddingInline',
+    vars: ['--_item-inset-inline']
+  }],
   'number-input': [{
     property: 'padding',
     expand: 'container'

package/dist/theme/generateThemeRules.d.ts

@@ -7,11 +7,17 @@
  * Used by both the runtime path (Theme injects <style>) and the build
  * path (`astryx theme build` pre-compiles to CSS files).
  *
+ * Every consumer-supplied declaration is checked by declarationBoundary.ts
+ * before it is emitted, so a value can never end its declaration or rule
+ * early. A refused declaration is dropped and reported in the supplied
+ * warnings array (build receipts), or through `console.warn` (runtime).
+ *
  * Extracted from defineTheme.ts to reduce cyclomatic complexity and provide
  * a clear single-responsibility module for CSS generation.
  *
- * @input DefinedTheme (resolved theme object from defineTheme)
- * @output CSS rule strings, split by layer (component vs prose)
+ * @input DefinedTheme (resolved theme object from defineTheme), optional warnings array
+ * @output CSS rule strings, split by layer (component vs prose), and warning text
+ *   for each dropped declaration
  * @position packages/core/src/theme/generateThemeRules.ts
  */
 import type { ComponentStyleMap, DefinedTheme } from './defineTheme';
@@ -65,7 +71,7 @@ export interface ThemeRuleSource {
     /** Resolved component style overrides. */
     components?: ComponentStyleMap;
 }
-export declare function generateThemeRules(theme: ThemeRuleSource): string[];
+export declare function generateThemeRules(theme: ThemeRuleSource, warnings?: string[]): string[];
 /**
  * Generate theme rules split into component and prose groups.
  *
@@ -76,7 +82,7 @@ export declare function generateThemeRules(theme: ThemeRuleSource): string[];
  * Component rules (tokens, stable .astryx-* targets plus data-* selectors) are
  * that need to beat StyleX — they stay in astryx-theme (above StyleX layers).
  */
-export declare function generateThemeRulesSplit(theme: DefinedTheme): ThemeRulesSplit;
+export declare function generateThemeRulesSplit(theme: DefinedTheme, warnings?: string[]): ThemeRulesSplit;
 /**
  * Generate CSS for on-media token and component overrides.
  *
@@ -85,7 +91,7 @@ export declare function generateThemeRulesSplit(theme: DefinedTheme): ThemeRules
  * to media contexts — only tokens change. Themes can further customize
  * via onDark.components / onLight.components.
  */
-export declare function generateOnMediaCSS(theme: DefinedTheme): string;
+export declare function generateOnMediaCSS(theme: DefinedTheme, warnings?: string[]): string;
 /**
  * Generate CSS for a theme's ordered adaptation rules.
  *
@@ -95,7 +101,7 @@ export declare function generateOnMediaCSS(theme: DefinedTheme): string;
  * rule. Bare prose follows semantic variables, so token writes need no duplicate
  * prose selectors here.
  */
-export declare function generateAdaptationCSS(theme: DefinedTheme): ThemeCSSOutput;
+export declare function generateAdaptationCSS(theme: DefinedTheme, warnings?: string[]): ThemeCSSOutput;
 /**
  * The `--color-data-*` defaults as one unscoped `:root` block.
  *
@@ -128,5 +134,5 @@ export declare function generateDataTokenDefaultsCSS(): string;
  * The theme-independent `--color-data-*` defaults are not part of this output:
  * see `generateDataTokenDefaultsCSS`.
  */
-export declare function generateThemeCSS(theme: DefinedTheme): ThemeCSSOutput;
+export declare function generateThemeCSS(theme: DefinedTheme, warnings?: string[]): ThemeCSSOutput;
 //# sourceMappingURL=generateThemeRules.d.ts.map

package/dist/theme/generateThemeRules.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generateThemeRules.d.ts","sourceRoot":"","sources":["../../src/theme/generateThemeRules.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAC,iBAAiB,EAAE,YAAY,EAAC,MAAM,eAAe,CAAC;AAiHnE;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,+EAA+E;IAC/E,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,kFAAkF;IAClF,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;OAIG;IACH,KAAK,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,SAAS,EAAE,MAAM,CAAC;CACnB;AAoND;;;;;GAKG;AACH;;;;;;;GAOG;AACH,MAAM,WAAW,eAAe;IAC9B,sCAAsC;IACtC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,yCAAyC;IACzC,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,0CAA0C;IAC1C,UAAU,CAAC,EAAE,iBAAiB,CAAC;CAChC;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,EAAE,CA6CnE;AAsXD;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,YAAY,GAAG,eAAe,CAe5E;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,YAAY,GAAG,MAAM,CA6C9D;AA+CD;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,YAAY,GAAG,cAAc,CA+EzE;AAUD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,4BAA4B,IAAI,MAAM,CAKrD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,YAAY,GAAG,cAAc,CAoCpE"}
+{"version":3,"file":"generateThemeRules.d.ts","sourceRoot":"","sources":["../../src/theme/generateThemeRules.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAC,iBAAiB,EAAE,YAAY,EAAC,MAAM,eAAe,CAAC;AAqHnE;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,+EAA+E;IAC/E,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,kFAAkF;IAClF,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;OAIG;IACH,KAAK,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,SAAS,EAAE,MAAM,CAAC;CACnB;AAmUD;;;;;GAKG;AACH;;;;;;;GAOG;AACH,MAAM,WAAW,eAAe;IAC9B,sCAAsC;IACtC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,yCAAyC;IACzC,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,0CAA0C;IAC1C,UAAU,CAAC,EAAE,iBAAiB,CAAC;CAChC;AAED,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,eAAe,EACtB,QAAQ,CAAC,EAAE,MAAM,EAAE,GAClB,MAAM,EAAE,CAiDV;AAoZD;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,YAAY,EACnB,QAAQ,CAAC,EAAE,MAAM,EAAE,GAClB,eAAe,CAejB;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,YAAY,EACnB,QAAQ,CAAC,EAAE,MAAM,EAAE,GAClB,MAAM,CAmDR;AA+CD;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,YAAY,EACnB,QAAQ,CAAC,EAAE,MAAM,EAAE,GAClB,cAAc,CAoFhB;AAOD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,4BAA4B,IAAI,MAAM,CAKrD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,YAAY,EACnB,QAAQ,CAAC,EAAE,MAAM,EAAE,GAClB,cAAc,CAoChB"}