@astryxdesign/core 0.6.2 → 0.6.3-canary.0788c49

package/dist/theme/generateThemeRules.js

@@ -9,11 +9,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
  */
 
@@ -22,6 +28,7 @@ import { parseStyleKey } from "../utils/parseStyleKey.js";
 import { getDerivedVars } from "./derivedVarRegistry.js";
 import { dataTokenDefaults } from "./domainTokens/dataTokens.js";
 import { cssVar, classPrefix, dataAttrNamespace } from "../naming.js";
+import { checkDeclarationName, checkDeclarationValue } from "./declarationBoundary.js";
 
 /**
  * Theme @scope selectors.
@@ -284,6 +291,77 @@ function expandContainerPadding(component, parsed, resetInheritedSpecificity = f
   return tokens;
 }
 
+// =============================================================================
+// Declaration assembly: a declaration always stays one declaration
+// =============================================================================
+
+const warnToConsole = message => {
+  console.warn(`[astryx theme] ${message}`);
+};
+
+/** Build receipts collect warning text; runtime callers warn by default. */
+function diagnosticSink(warnings) {
+  return warnings ? message => warnings.push(message) : warnToConsole;
+}
+
+/** Shorten an authored value for a one-line message. */
+function previewValue(value) {
+  const oneLine = JSON.stringify(value);
+  return oneLine.length > 80 ? `${oneLine.slice(0, 77)}..."` : oneLine;
+}
+function reportDrop(sink, property, value, location, reason) {
+  sink(`dropped "${property}" in ${location}: ${reason} (value: ${previewValue(value)})`);
+}
+
+/**
+ * True when `name: value;` stays exactly one declaration; otherwise reports
+ * the drop and returns false. Both checks follow CSS syntax, so valid CSS a
+ * browser keeps inside one declaration (a `data:` URI, `Gill\ Sans`, a closed
+ * comment, a vendor-prefixed property) is never refused; see
+ * declarationBoundary.ts for the rules.
+ */
+function acceptDeclaration(property, value, location, sink) {
+  const reason = checkDeclarationName(property) ?? checkDeclarationValue(value);
+  if (reason === null) {
+    return true;
+  }
+  reportDrop(sink, property, value, location, reason);
+  return false;
+}
+
+/**
+ * Assemble `prop: value;` lines, dropping (and reporting) any entry whose
+ * property or value could not stay a single declaration. Theme definitions
+ * are code, but apps do assemble them from stored input (brand colors,
+ * white-labeling), so the generated stylesheet must never extend beyond the
+ * declarations it means to emit.
+ */
+function joinDeclarations(entries, location, sink, mapProp = p => p) {
+  const lines = [];
+  for (const [rawProp, rawValue] of entries) {
+    // Legacy unenrolled tokens retain non-string values. Scan the same text
+    // interpolation has always emitted, without changing the normalized theme.
+    const value = `${rawValue}`;
+    const prop = mapProp(rawProp);
+    if (acceptDeclaration(prop, value, location, sink)) {
+      lines.push(`    ${prop}: ${value};`);
+    }
+  }
+  return lines.join('\n');
+}
+
+/** The `:scope` token block for portable and theme-local token values. */
+function tokenBlock(source, location, sink) {
+  const declarations = [joinDeclarations(Object.entries(source.tokens), `${location}tokens`, sink), joinDeclarations(Object.entries(source.localTokens ?? {}), `${location}localTokens`, sink)].filter(block => block.length > 0).join('\n');
+  const hasEntries = Object.keys(source.tokens).length > 0 || Object.keys(source.localTokens ?? {}).length > 0;
+  return hasEntries ? `  :scope {\n${declarations}\n  }` : null;
+}
+
+/** `components.button["variant:secondary"]`-style location for a rule. */
+function componentLocation(prefix, component, key) {
+  return `${prefix}components.${component}[${JSON.stringify(key)}]`;
+}
+
 // =============================================================================
 // Public API
 // =============================================================================
@@ -303,9 +381,9 @@ function expandContainerPadding(component, parsed, resetInheritedSpecificity = f
  * lost for every conditional rule, with no type error to catch it.
  */
 
-export function generateThemeRules(theme) {
+export function generateThemeRules(theme, warnings) {
   const parts = [];
-  const tokens = theme.tokens;
+  const sink = diagnosticSink(warnings);
 
   // Bare prose rules reference semantic variables instead of baking the root
   // value. That lets adaptation token writes take effect through CSS alone
@@ -313,16 +391,27 @@ export function generateThemeRules(theme) {
   const val = key => `var(${key})`;
 
   // 1. Token block — CSS custom properties on :scope
-  const tokenEntries = [...Object.entries(tokens), ...Object.entries(theme.localTokens ?? {})];
-  if (tokenEntries.length > 0) {
-    const declarations = tokenEntries.map(([prop, value]) => `    ${prop}: ${value};`).join('\n');
-    parts.push(`  :scope {\n${declarations}\n  }`);
+  const tokenRules = tokenBlock(theme, '', sink);
+  if (tokenRules !== null) {
+    parts.push(tokenRules);
+  }
+
+  // 1b. Base font — apply the theme's declared body font to the scope root.
+  // Components styled with `font-family: inherit` (SideNav items, Buttons)
+  // otherwise resolve against the browser default serif, since nothing else
+  // sets a page font. `font-family` inherits, so one rule on :scope covers
+  // the tree. Only emitted when the theme declares a body font, so a bare
+  // theme still contributes no scope rules of its own.
+  if (theme.tokens['--font-family-body']) {
+    parts.push(`  :scope {\n    font-family: var(--font-family-body);\n  }`);
   }
 
   // 2. Component overrides: stable .astryx-* target classes combined with
   // reflected data-* selectors for visual props and runtime states.
   if (theme.components) {
-    generateComponentRules(theme.components, parts);
+    generateComponentRules(theme.components, parts, {
+      sink
+    });
   }
 
   // 3. Prose HTML element rules (h1-h6, p, small, code, hr)
@@ -386,13 +475,21 @@ function generateHeadingWeightOverrides(components, parts, {
     parts.push(`  ${selector} { font-weight: ${effectiveWeight}; }`);
   }
 }
+
+/**
+ * The `fontWeight` a heading rule authors for `styleKey`, or undefined when
+ * it has none. A value that cannot stay one declaration is treated as not
+ * authored, so the override falls back to the inherited or token weight
+ * instead of interpolating it; the drop itself is reported where that same
+ * rule's declarations are emitted, so it is not reported twice here.
+ */
 function getAuthoredHeadingWeight(headingRuleMap, styleKey) {
   const rule = headingRuleMap[styleKey];
   if (rule == null || typeof rule !== 'object' || Array.isArray(rule)) {
     return undefined;
   }
   const fontWeight = rule.fontWeight;
-  return typeof fontWeight === 'string' ? fontWeight : undefined;
+  return typeof fontWeight === 'string' && checkDeclarationValue(fontWeight) === null ? fontWeight : undefined;
 }
 
 /** Options shared by root, adaptation, and media-surface component lowering. */
@@ -404,7 +501,9 @@ function getAuthoredHeadingWeight(headingRuleMap, styleKey) {
  */
 function generateComponentRules(components, parts, {
   resetInheritedPaddingSpecificity = false,
-  surface
+  surface,
+  sink = warnToConsole,
+  location: locationPrefix = ''
 } = {}) {
   for (const [component, rules] of Object.entries(components)) {
     for (const [key, styles] of Object.entries(rules)) {
@@ -414,6 +513,7 @@ function generateComponentRules(components, parts, {
       }
       const suffix = parseStyleKey(key);
       const baseSelector = componentSelector(component, suffix, surface);
+      const location = componentLocation(locationPrefix, component, key);
 
       // Separate regular properties from pseudo-class overrides
       const props = [];
@@ -421,7 +521,7 @@ function generateComponentRules(components, parts, {
       for (const [prop, value] of entries) {
         if (prop.startsWith(':') && typeof value === 'object') {
           pseudos.push([prop, value]);
-        } else {
+        } else if (acceptDeclaration(toKebabCase(prop), `${value}`, location, sink)) {
           props.push([prop, value]);
         }
       }
@@ -483,7 +583,7 @@ function generateComponentRules(components, parts, {
 
       // Emit base rule
       if (finalProps.length > 0) {
-        const declarations = finalProps.map(([prop, value]) => `    ${toKebabCase(prop)}: ${value};`).join('\n');
+        const declarations = joinDeclarations(finalProps, location, sink, toKebabCase);
         parts.push(`  ${baseSelector} {\n${declarations}\n  }`);
       }
 
@@ -491,7 +591,7 @@ function generateComponentRules(components, parts, {
       for (const [pseudo, pseudoStyles] of pseudos) {
         const pseudoEntries = Object.entries(pseudoStyles);
         if (pseudoEntries.length > 0) {
-          const declarations = pseudoEntries.map(([prop, value]) => `    ${toKebabCase(prop)}: ${value};`).join('\n');
+          const declarations = joinDeclarations(pseudoEntries, `${location}[${JSON.stringify(pseudo)}]`, sink, toKebabCase);
           parts.push(`  ${appendPseudoToSelectorList(baseSelector, pseudo)} {\n${declarations}\n  }`);
         }
       }
@@ -629,8 +729,8 @@ function generateSizeOverrides(components, parts, surface) {
  * Component rules (tokens, stable .astryx-* targets plus data-* selectors) are
  * that need to beat StyleX — they stay in astryx-theme (above StyleX layers).
  */
-export function generateThemeRulesSplit(theme) {
-  const allRules = generateThemeRules(theme);
+export function generateThemeRulesSplit(theme, warnings) {
+  const allRules = generateThemeRules(theme, warnings);
   const prose = [];
   const component = [];
   for (const rule of allRules) {
@@ -654,19 +754,21 @@ export function generateThemeRulesSplit(theme) {
  * to media contexts — only tokens change. Themes can further customize
  * via onDark.components / onLight.components.
  */
-export function generateOnMediaCSS(theme) {
+export function generateOnMediaCSS(theme, warnings) {
   const parts = [];
   const scopeSelector = themeScopeStart(theme.name);
+  const sink = diagnosticSink(warnings);
   for (const surface of ['dark', 'light']) {
     const onMedia = surface === 'dark' ? theme.__onDark : theme.__onLight;
     if (!onMedia) {
       continue;
     }
+    const location = surface === 'dark' ? 'onDark.' : 'onLight.';
 
     // Token overrides
     const tokenEntries = Object.entries(onMedia.tokens);
     if (tokenEntries.length > 0) {
-      const declarations = tokenEntries.map(([prop, value]) => `    ${prop}: ${value};`).join('\n');
+      const declarations = joinDeclarations(tokenEntries, `${location}tokens`, sink);
       parts.push(`  ${mediaSelector(surface)} {\n${declarations}\n  }`);
     }
 
@@ -675,7 +777,9 @@ export function generateOnMediaCSS(theme) {
     if (onMedia.components) {
       generateComponentRules(onMedia.components, parts, {
         resetInheritedPaddingSpecificity: true,
-        surface
+        surface,
+        sink,
+        location
       });
       generateColorOverrides(onMedia.components, parts, surface);
       generateSizeOverrides(onMedia.components, parts, surface);
@@ -697,16 +801,17 @@ export function generateOnMediaCSS(theme) {
 }
 
 /** Generate only the declarations one adaptation rule writes. */
-function generateAdaptationRuleRules(rule) {
+function generateAdaptationRuleRules(rule, location, sink) {
   const parts = [];
-  const tokenEntries = [...Object.entries(rule.tokens), ...Object.entries(rule.localTokens ?? {})];
-  if (tokenEntries.length > 0) {
-    const declarations = tokenEntries.map(([prop, value]) => `    ${prop}: ${value};`).join('\n');
-    parts.push(`  :scope {\n${declarations}\n  }`);
+  const tokens = tokenBlock(rule, location, sink);
+  if (tokens !== null) {
+    parts.push(tokens);
   }
   if (rule.components) {
     generateComponentRules(rule.components, parts, {
-      resetInheritedPaddingSpecificity: true
+      resetInheritedPaddingSpecificity: true,
+      sink,
+      location
     });
     generateColorOverrides(rule.components, parts);
     generateSizeOverrides(rule.components, parts);
@@ -730,7 +835,8 @@ function generateAdaptationMediaBlock(query, parts, scopeSelector) {
  * rule. Bare prose follows semantic variables, so token writes need no duplicate
  * prose selectors here.
  */
-export function generateAdaptationCSS(theme) {
+export function generateAdaptationCSS(theme, warnings) {
+  const sink = diagnosticSink(warnings);
   // Built themes can reach this compiler without passing through defineTheme.
   // Validate retained metadata even when it has no rules (and therefore emits
   // no CSS): width points remain observable through AppShell and inheritance.
@@ -751,8 +857,8 @@ export function generateAdaptationCSS(theme) {
   // active whenever the later condition matches, even if the earlier condition
   // does not. Pairwise merging cannot repair that: multiple mutually exclusive
   // earlier rules can each overlap one broad later rule.
-  for (const rule of rules) {
-    const parts = generateAdaptationRuleRules(rule);
+  for (const [index, rule] of rules.entries()) {
+    const parts = generateAdaptationRuleRules(rule, `adaptations[${index}].`, sink);
     if (parts.length === 0) {
       continue;
     }
@@ -787,9 +893,9 @@ export function generateAdaptationCSS(theme) {
   };
 }
 
-/** Indent a generated rule one level further, for nesting inside `@media`. */
+/** Indent the rule start without rewriting newlines inside authored values. */
 function indentRule(rule) {
-  return rule.split('\n').map(line => line.length > 0 ? `  ${line}` : line).join('\n');
+  return `  ${rule}`;
 }
 
 /**
@@ -828,11 +934,11 @@ export function generateDataTokenDefaultsCSS() {
  * The theme-independent `--color-data-*` defaults are not part of this output:
  * see `generateDataTokenDefaultsCSS`.
  */
-export function generateThemeCSS(theme) {
+export function generateThemeCSS(theme, warnings) {
   const {
     component,
     prose
-  } = generateThemeRulesSplit(theme);
+  } = generateThemeRulesSplit(theme, warnings);
   const scopeSelector = themeScopeStart(theme.name);
   const scopeTo = THEME_SCOPE_TO;
   let proseCss = '';
@@ -851,11 +957,11 @@ export function generateThemeCSS(theme) {
 
   // Adaptations follow the root theme in authored order. Media-surface rules
   // follow adaptations so onDark/onLight keep their specified precedence.
-  const adaptationCss = generateAdaptationCSS(theme);
+  const adaptationCss = generateAdaptationCSS(theme, warnings);
   if (adaptationCss.component) {
     componentCss = componentCss ? `${componentCss}\n\n${adaptationCss.component}` : adaptationCss.component;
   }
-  const onMediaCss = generateOnMediaCSS(theme);
+  const onMediaCss = generateOnMediaCSS(theme, warnings);
   if (onMediaCss) {
     componentCss = componentCss ? `${componentCss}\n\n${onMediaCss}` : onMediaCss;
   }

package/dist/utils/interactionOverlay.stylex.d.ts

@@ -4,6 +4,11 @@
  * @output Exports reusable background-color and background-image state styles
  * @position Internal styling utility for interactive core surfaces
  *
+ * Every surface that paints a press composes one of these (or carries its own
+ * `:active` rule), so a change to how the system answers a press is made here
+ * once. `pressedBackgroundColor` is the press without the hover, for controls
+ * whose hover is a colour or nothing.
+ *
  * Keep the enabled guard outside the individual states. StyleX assigns an
  * extra priority bucket (and generated selector specificity) to media-nested
  * rules. Repeating `:active` inside the hover-capable branch gives hover and
@@ -22,5 +27,8 @@ export declare const interactionOverlayStyles: Readonly<{
     readonly backgroundImageOnNeutral: Readonly<{
         readonly backgroundImage: stylex.StyleXClassNameFor<"backgroundImage", string | null>;
     }>;
+    readonly pressedBackgroundColor: Readonly<{
+        readonly backgroundColor: stylex.StyleXClassNameFor<"backgroundColor", "light-dark(#05365919, #FFFFFF19)" | null>;
+    }>;
 }>;
 //# sourceMappingURL=interactionOverlay.stylex.d.ts.map

package/dist/utils/interactionOverlay.stylex.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"interactionOverlay.stylex.d.ts","sourceRoot":"","sources":["../../src/utils/interactionOverlay.stylex.ts"],"names":[],"mappings":"AAMA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,MAAM,MAAM,kBAAkB,CAAC;AAU3C,eAAO,MAAM,wBAAwB;;;;;;;;;;EA2CnC,CAAC"}
+{"version":3,"file":"interactionOverlay.stylex.d.ts","sourceRoot":"","sources":["../../src/utils/interactionOverlay.stylex.ts"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,MAAM,MAAM,kBAAkB,CAAC;AAU3C,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;EA0DnC,CAAC"}

package/dist/utils/interactionOverlay.stylex.js

@@ -10,6 +10,11 @@
  * @output Exports reusable background-color and background-image state styles
  * @position Internal styling utility for interactive core surfaces
  *
+ * Every surface that paints a press composes one of these (or carries its own
+ * `:active` rule), so a change to how the system answers a press is made here
+ * once. `pressedBackgroundColor` is the press without the hover, for controls
+ * whose hover is a colour or nothing.
+ *
  * Keep the enabled guard outside the individual states. StyleX assigns an
  * extra priority bucket (and generated selector specificity) to media-nested
  * rules. Repeating `:active` inside the hover-capable branch gives hover and
@@ -38,5 +43,9 @@ export const interactionOverlayStyles = {
   backgroundImageOnNeutral: {
     kKwaWg: "x14bno8m xzmimnh x1otsd3y xo3fi6e",
     $$css: true
+  },
+  pressedBackgroundColor: {
+    kWkggS: "x1anq1lc",
+    $$css: true
   }
 };

package/dist/utils/safeUrl.d.ts

@@ -0,0 +1,11 @@
+/** Return a normalized navigation URL, or null for a blocked scheme. */
+export declare function sanitizeUrl(url: string): string | null;
+/** Inspect a navigation string without changing the value used by its sink. */
+export declare function isSafeUrl(url: string): boolean;
+/**
+ * Inspect React Router paths, Next.js URL objects, and URL instances without
+ * serializing or replacing the object handed to the router. Search/query/hash
+ * are route-relative data, not schemes. Absent destinations remain absent.
+ */
+export declare function isSafeDestination(destination: unknown): boolean;
+//# sourceMappingURL=safeUrl.d.ts.map

package/dist/utils/safeUrl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"safeUrl.d.ts","sourceRoot":"","sources":["../../src/utils/safeUrl.ts"],"names":[],"mappings":"AAcA,wEAAwE;AACxE,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAWtD;AAED,+EAA+E;AAC/E,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAE9C;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,OAAO,GAAG,OAAO,CA8C/D"}

package/dist/utils/safeUrl.js

@@ -0,0 +1,78 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file safeUrl.ts
+ * @input Navigation strings or supported structured router destinations
+ * @output The shared blocked-scheme decision, without rewriting accepted inputs
+ * @position Core navigation policy; embedded-resource policy is separate
+ */
+
+function normalizeUrl(url) {
+  // eslint-disable-next-line no-control-regex -- inspect schemes without browser-ignored controls
+  return url.replace(/[\x00-\x1f\x7f]/g, '').trim();
+}
+
+/** Return a normalized navigation URL, or null for a blocked scheme. */
+export function sanitizeUrl(url) {
+  const normalized = normalizeUrl(url);
+  const lower = normalized.toLowerCase();
+  if (lower.startsWith('javascript:') || lower.startsWith('vbscript:') || lower.startsWith('data:text/html')) {
+    return null;
+  }
+  return normalized;
+}
+
+/** Inspect a navigation string without changing the value used by its sink. */
+export function isSafeUrl(url) {
+  return sanitizeUrl(url) !== null;
+}
+
+/**
+ * Inspect React Router paths, Next.js URL objects, and URL instances without
+ * serializing or replacing the object handed to the router. Search/query/hash
+ * are route-relative data, not schemes. Absent destinations remain absent.
+ */
+export function isSafeDestination(destination) {
+  if (destination == null) {
+    return true;
+  }
+  if (typeof destination === 'string') {
+    return isSafeUrl(destination);
+  }
+  if (typeof destination !== 'object') {
+    return false;
+  }
+  const {
+    pathname,
+    href,
+    protocol,
+    host,
+    hostname
+  } = destination;
+  for (const field of [pathname, href, protocol, host, hostname]) {
+    if (field != null && typeof field !== 'string') {
+      return false;
+    }
+  }
+  if (typeof pathname === 'string' && !isSafeUrl(pathname)) {
+    return false;
+  }
+  if (typeof href === 'string' && !isSafeUrl(href)) {
+    return false;
+  }
+  if (typeof protocol === 'string' && protocol !== '') {
+    // URL-object formatters accept a protocol with or without its colon and
+    // can assemble a data media type from the host and pathname fields.
+    const normalizedProtocol = normalizeUrl(protocol);
+    const prefix = normalizedProtocol.endsWith(':') ? normalizedProtocol : `${normalizedProtocol}:`;
+    if (!isSafeUrl(prefix)) {
+      return false;
+    }
+    const body = host || hostname || '';
+    const path = typeof pathname === 'string' ? pathname : '';
+    if (!isSafeUrl(`${prefix}${body}${path}`)) {
+      return false;
+    }
+  }
+  return true;
+}