@astryxdesign/core 0.1.6 → 0.1.7-canary.04cd8f7

package/src/theme/Theme.doc.mjs

@@ -39,12 +39,12 @@ export const docs = {
   },
   usage: {
     description:
-      'Wraps a subtree with a specific Astryx theme. For static production themes, use `npx astryx theme build` and import the generated CSS plus built theme object for first-paint and SSR performance. Use runtime `defineTheme()` when themes are dynamic or for prototyping.\n\n`defineTheme` accepts a `tokens` object whose keys are CSS custom property names (always prefixed with `--`). Common token names include `--color-accent`, `--color-background-surface`, `--color-background-body`, `--color-text-primary`, `--color-text-secondary`, `--radius-container`, `--spacing-1` through `--spacing-6`. Values can be a string (same for light/dark) or a `[light, dark]` tuple.\n\nExample:\n```ts\nimport {defineTheme} from \'@astryxdesign/core/theme\';\nconst myTheme = defineTheme({\n  name: \'ocean\',\n  tokens: {\n    \'--color-accent\': [\'#0077B6\', \'#48CAE4\'],\n    \'--color-background-surface\': [\'#F0F8FF\', \'#0A1628\'],\n    \'--color-text-primary\': [\'#0A1317\', \'#FFFFFF\'],\n    \'--radius-container\': \'16px\',\n  },\n});\n```',
+      'Wraps a subtree with a specific Astryx theme. For static production themes, use `astryx theme build` and import the generated CSS plus built theme object for first-paint and SSR performance. Use runtime `defineTheme()` when themes are dynamic or for prototyping.\n\n`defineTheme` accepts a `tokens` object whose keys are CSS custom property names (always prefixed with `--`). Common token names include `--color-accent`, `--color-background-surface`, `--color-background-body`, `--color-text-primary`, `--color-text-secondary`, `--radius-container`, `--spacing-1` through `--spacing-6`. Values can be a string (same for light/dark) or a `[light, dark]` tuple.\n\nExample:\n```ts\nimport {defineTheme} from \'@astryxdesign/core/theme\';\nconst myTheme = defineTheme({\n  name: \'ocean\',\n  tokens: {\n    \'--color-accent\': [\'#0077B6\', \'#48CAE4\'],\n    \'--color-background-surface\': [\'#F0F8FF\', \'#0A1628\'],\n    \'--color-text-primary\': [\'#0A1317\', \'#FFFFFF\'],\n    \'--radius-container\': \'16px\',\n  },\n});\n```',
     bestPractices: [
       {
         guidance: true,
         description:
-          'Build app themes that are known ahead of time with `npx astryx theme build`, then import the generated CSS and built theme object.',
+          'Build app themes that are known ahead of time with `astryx theme build`, then import the generated CSS and built theme object.',
       },
       {
         guidance: true,
@@ -90,12 +90,12 @@ export const docs = {
 export const docsDense = {
   usage: {
     description:
-      'Wraps subtree w/ specific Astryx theme. For static production themes, use `npx astryx theme build` + generated CSS + built theme object for first-paint/SSR performance. Use runtime `defineTheme()` for dynamic themes or prototyping. Token names always start with `--` (e.g. `--color-accent`, `--color-background-surface`).',
+      'Wraps subtree w/ specific Astryx theme. For static production themes, use `astryx theme build` + generated CSS + built theme object for first-paint/SSR performance. Use runtime `defineTheme()` for dynamic themes or prototyping. Token names always start with `--` (e.g. `--color-accent`, `--color-background-surface`).',
     bestPractices: [
       {
         guidance: true,
         description:
-          'Build app themes known ahead of time w/ `npx astryx theme build`; import generated CSS + built theme object.',
+          'Build app themes known ahead of time w/ `astryx theme build`; import generated CSS + built theme object.',
       },
       {
         guidance: true,

package/src/theme/Theme.tsx

@@ -127,7 +127,7 @@ function useThemeStyleInjection(theme: DefinedTheme): void {
           `For better performance, use the pre-built theme:\n\n` +
           `  import {${theme.name}Theme} from '@astryxdesign/theme-${theme.name}/built';\n` +
           `  import '@astryxdesign/theme-${theme.name}/theme.css';\n\n` +
-          `For custom themes, run \`npx astryx theme build <file>\` to generate ` +
+          `For custom themes, run \`npx @astryxdesign/cli theme build <file>\` to generate ` +
           `the built artifacts.`,
       );
     }

package/src/theme/defineTheme.ts

@@ -5,7 +5,7 @@
  *
  * Two distribution modes:
  * - Unbuilt: Theme generates CSS and injects a <style> tag at runtime
- * - Built: `npx astryx theme build` pre-compiles to a CSS file; Theme just
+ * - Built: `astryx theme build` pre-compiles to a CSS file; Theme just
  *   sets the data-astryx-theme attribute
  *
  * Token values can be:

package/src/theme/hct.ts

@@ -114,10 +114,6 @@ export function toneToY(tone: number): number {
   return labFInv((tone + 16) / 116);
 }
 
-export function yToTone(y: number): number {
-  return 116 * labF(y) - 16;
-}
-
 // =============================================================================
 // Hex <-> RGB
 // =============================================================================

package/src/utils/color.test.ts

@@ -1,7 +1,14 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 import {describe, expect, it} from 'vitest';
-import {parseHex, parseRgb, parseColor, formatHex, formatColor} from './color';
+import {
+  parseHex,
+  parseRgb,
+  parseColor,
+  formatHex,
+  formatColor,
+  toGLFloats,
+} from './color';
 
 describe('parseHex', () => {
   it('parses #rrggbb', () => {
@@ -131,3 +138,96 @@ describe('formatColor', () => {
     expect(formatColor(parsed!)).toBe('rgba(10, 20, 30, 0.5)');
   });
 });
+
+describe('toGLFloats', () => {
+  const GL_FALLBACK: [number, number, number] = [0.5, 0.5, 0.5];
+
+  it('converts RGBA channels to 0-1 floats, dropping alpha', () => {
+    expect(toGLFloats({r: 0, g: 100, b: 224, a: 0.5})).toEqual([
+      0,
+      100 / 255,
+      224 / 255,
+    ]);
+  });
+
+  it('returns the neutral fallback for null so the GPU never gets NaN', () => {
+    expect(toGLFloats(null)).toEqual(GL_FALLBACK);
+  });
+
+  it('clamps hand-constructed out-of-range channels', () => {
+    expect(toGLFloats({r: 300, g: -5, b: 127.5, a: 1})).toEqual([
+      1,
+      0,
+      127.5 / 255,
+    ]);
+  });
+
+  it('returns the fallback for hand-constructed non-finite channels', () => {
+    expect(toGLFloats({r: NaN, g: 0, b: 0, a: 1})).toEqual(GL_FALLBACK);
+    expect(toGLFloats({r: 0, g: Infinity, b: 0, a: 1})).toEqual(GL_FALLBACK);
+  });
+
+  // Conformance table for the GL hex path (#3739): pins the behavior of the
+  // previously duplicated `hexToGL` copies in charts/lab, standardized on the
+  // robust charts implementation. Composed as `toGLFloats(parseHex(input))`,
+  // exactly as the migrated call sites do.
+  it.each([
+    ['#rrggbb', '#0064E0', [0, 100 / 255, 224 / 255]],
+    ['bare rrggbb (no #)', '0064E0', [0, 100 / 255, 224 / 255]],
+    ['#rgb shorthand', '#f00', [1, 0, 0]],
+    ['#rgba shorthand (alpha ignored)', '#f008', [1, 0, 0]],
+    ['#rrggbbaa (alpha byte ignored)', '#00000080', [0, 0, 0]],
+    ['surrounding whitespace', '  #ffffff  ', [1, 1, 1]],
+    ['truncated hex → fallback', '#12', [0.5, 0.5, 0.5]],
+    ['non-hex garbage → fallback', 'not-a-color', [0.5, 0.5, 0.5]],
+    ['CSS variable → fallback', 'var(--color-accent)', [0.5, 0.5, 0.5]],
+    [
+      'rgb() string → fallback on the hex path',
+      'rgb(255, 0, 0)',
+      [0.5, 0.5, 0.5],
+    ],
+    ['empty string → fallback', '', [0.5, 0.5, 0.5]],
+  ])('%s: %j → %j', (_label, input, expected) => {
+    expect(toGLFloats(parseHex(input))).toEqual(expected);
+  });
+
+  it('composes with parseColor when the caller wants rgb()/named support', () => {
+    expect(toGLFloats(parseColor('rgb(255, 0, 0)'))).toEqual([1, 0, 0]);
+    expect(toGLFloats(parseColor('transparent'))).toEqual([0, 0, 0]);
+  });
+});
+
+describe('alpha application (conformance for charts/lab `colors.alpha`)', () => {
+  // The charts/lab `hexAlpha` helpers are rebuilt on parseColor + parseHex +
+  // formatColor (#3739). These pin the composed behavior they rely on.
+  const applyAlpha = (color: string, opacity: number): string => {
+    const rgba = parseColor(color) ?? parseHex(color);
+    return rgba === null ? color : formatColor({...rgba, a: opacity});
+  };
+
+  it('applies opacity to an opaque hex color', () => {
+    expect(applyAlpha('#0064E0', 0.2)).toBe('rgba(0, 100, 224, 0.2)');
+  });
+
+  it('applies opacity to bare hex without the leading #', () => {
+    expect(applyAlpha('0064E0', 0.2)).toBe('rgba(0, 100, 224, 0.2)');
+  });
+
+  it('opacity argument wins over an existing alpha byte', () => {
+    expect(applyAlpha('#0064E080', 0.2)).toBe('rgba(0, 100, 224, 0.2)');
+  });
+
+  it('opacity argument wins over rgba() input alpha', () => {
+    expect(applyAlpha('rgba(0, 100, 224, 0.9)', 0.2)).toBe(
+      'rgba(0, 100, 224, 0.2)',
+    );
+  });
+
+  it('full opacity serializes back to hex', () => {
+    expect(applyAlpha('#0064E0', 1)).toBe('#0064E0');
+  });
+
+  it('unparseable input is preserved unchanged', () => {
+    expect(applyAlpha('var(--color-accent)', 0.2)).toBe('var(--color-accent)');
+  });
+});

package/src/utils/color.ts

@@ -4,7 +4,7 @@
  * @file color.ts
  * @input CSS color strings (hex, rgb()/rgba(), a small set of named colors)
  * @output Shared color parsing/formatting primitives used across the design system
- * @position Package utility; backs theme token resolution, HCT color math, and chart rendering
+ * @position Package utility; backs theme token resolution, HCT color math, and chart/WebGL rendering
  *
  * A single home for the color parsers that were previously duplicated across
  * the theme layer, charts, and lab. Consumers get one well-tested definition of
@@ -146,3 +146,25 @@ export function formatColor({r, g, b, a}: RGBA): string {
   const round = (n: number): number => clamp(Math.round(n), 0, 255);
   return `rgba(${round(r)}, ${round(g)}, ${round(b)}, ${parseFloat(a.toFixed(4))})`;
 }
+
+/** Neutral fallback (mid-grey) for colors a GL path can't parse — visible, never NaN. */
+const GL_FALLBACK: [number, number, number] = [0.5, 0.5, 0.5];
+
+/**
+ * Convert a parsed {@link RGBA} to `[r, g, b]` floats in 0-1 for WebGL
+ * uniforms and attributes.
+ *
+ * Takes the parsed type rather than a raw string so every caller goes through
+ * one validation path ({@link parseHex} / {@link parseColor}) — compose as
+ * `toGLFloats(parseHex(color))`. Unparseable input (null) and non-finite
+ * channels return a neutral mid-grey fallback, so the GPU never receives a
+ * NaN uniform. Alpha is intentionally dropped — GL chart paths blend with
+ * their own alpha.
+ */
+export function toGLFloats(color: RGBA | null): [number, number, number] {
+  if (color === null || ![color.r, color.g, color.b].every(Number.isFinite)) {
+    return GL_FALLBACK;
+  }
+  const channel = (c: number): number => clamp(c, 0, 255) / 255;
+  return [channel(color.r), channel(color.g), channel(color.b)];
+}

package/src/utils/index.ts

@@ -83,5 +83,12 @@ export {isRenderable} from './isRenderable';
 export {getInputARIA} from './inputAria';
 export type {InputARIA, InputARIAInputGroup} from './inputAria';
 
-export {parseHex, parseRgb, parseColor, formatHex, formatColor} from './color';
+export {
+  parseHex,
+  parseRgb,
+  parseColor,
+  formatHex,
+  formatColor,
+  toGLFloats,
+} from './color';
 export type {RGBA} from './color';

package/dist/NavItem/index.d.ts

@@ -1,9 +0,0 @@
-/**
- * @file index.ts
- * @input Imports from navItemStyles.stylex.ts
- * @output Exports navItemStyles and NavItemSize type
- * @position Entry point for NavItem module
- */
-export { navItemStyles } from './navItemStyles.stylex';
-export type { NavItemSize } from './navItemStyles.stylex';
-//# sourceMappingURL=index.d.ts.map

package/dist/NavItem/index.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/NavItem/index.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AAEH,OAAO,EAAC,aAAa,EAAC,MAAM,wBAAwB,CAAC;AACrD,YAAY,EAAC,WAAW,EAAC,MAAM,wBAAwB,CAAC"}

package/dist/NavItem/index.js

@@ -1,10 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/**
- * @file index.ts
- * @input Imports from navItemStyles.stylex.ts
- * @output Exports navItemStyles and NavItemSize type
- * @position Entry point for NavItem module
- */
-
-export { navItemStyles } from "./navItemStyles.stylex.js";

package/src/NavItem/index.ts

@@ -1,11 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/**
- * @file index.ts
- * @input Imports from navItemStyles.stylex.ts
- * @output Exports navItemStyles and NavItemSize type
- * @position Entry point for NavItem module
- */
-
-export {navItemStyles} from './navItemStyles.stylex';
-export type {NavItemSize} from './navItemStyles.stylex';