@astryxdesign/core 0.1.2 → 0.1.3

package/src/Grid/Grid.doc.mjs

@@ -17,6 +17,7 @@ export const docs = {
       { guidance: true, description: 'Use `repeat: \'fill\'` (the default) for consistent item widths. Use `\'fit\'` when items should stretch to fill leftover space.' },
       { guidance: false, description: 'Write manual CSS grid; Grid handles spacing and responsive behavior for you.' },
       { guidance: false, description: 'Use `HStack` with wrapping for grids; use Grid instead.' },
+      { guidance: true, description: 'Track templates use CSS-variable indirection (not raw inline styles), so `xstyle` overrides of `gridTemplateColumns` — including inside `@media` queries — take effect.' },
     ],
   },
   theming: {
@@ -39,13 +40,23 @@ export const docs = {
     },
     {
       name: 'width',
-      type: 'number | string',
-      description: 'Container width.',
+      type: 'SizeValue',
+      description: 'Container width. Numbers are treated as pixels, strings are used as-is.',
     },
     {
       name: 'height',
-      type: 'number | string',
-      description: 'Container height.',
+      type: 'SizeValue',
+      description: 'Container height. Numbers are treated as pixels, strings are used as-is.',
+    },
+    {
+      name: 'maxWidth',
+      type: 'SizeValue',
+      description: 'Maximum container width. Numbers are treated as pixels, strings are used as-is.',
+    },
+    {
+      name: 'minHeight',
+      type: 'SizeValue',
+      description: 'Minimum container height. Numbers are treated as pixels, strings are used as-is.',
     },
     {
       name: 'gap',
@@ -101,6 +112,7 @@ export const docsZh = {
       { guidance: true, description: 'Use `repeat: \'fill\'` (the default) for consistent item widths. Use `\'fit\'` when items should stretch to fill leftover space.' },
       { guidance: false, description: 'Write manual CSS grid; Grid handles spacing and responsive behavior for you.' },
       { guidance: false, description: 'Use `HStack` with wrapping for grids; use Grid instead.' },
+      { guidance: true, description: 'Track templates use CSS-variable indirection (not raw inline styles), so `xstyle` overrides of `gridTemplateColumns` — including inside `@media` queries — take effect.' },
     ],
   },
 };
@@ -116,6 +128,7 @@ export const docsDense = {
       { guidance: true, description: 'Use repeat: \'fill\' (the default) for consistent item widths. Use \'fit\' when items should stretch to fill leftover space.' },
       { guidance: false, description: 'Write manual CSS grid; Grid handles spacing and responsive behavior for you.' },
       { guidance: false, description: 'Use HStack with wrapping for grids; use Grid instead.' },
+      { guidance: true, description: 'track templates use CSS-var indirection, not inline styles — xstyle/@media overrides of gridTemplateColumns work.' },
     ],
   },
 };

package/src/Grid/Grid.test.tsx

@@ -14,6 +14,17 @@ import {render, screen} from '@testing-library/react';
 import {Grid} from './Grid';
 import {GridSpan} from './GridSpan';
 
+/**
+ * The track template is applied via a StyleX dynamic style: the element
+ * carries an inline CSS variable while the `grid-template-columns`
+ * declaration lives in a class (so consumer xstyle/@media overrides can
+ * win). `--x-gridTemplateColumns` is the debug-mode variable name emitted
+ * by the StyleX transform in tests.
+ */
+function templateColumns(el: HTMLElement): string {
+  return el.style.getPropertyValue('--x-gridTemplateColumns');
+}
+
 describe('Grid', () => {
   it('renders with fixed columns', () => {
     render(
@@ -25,7 +36,22 @@ describe('Grid', () => {
     );
     const grid = screen.getByTestId('grid');
     expect(grid).toBeInTheDocument();
-    expect(grid.style.gridTemplateColumns).toBe('repeat(3, 1fr)');
+    expect(templateColumns(grid)).toBe('repeat(3, 1fr)');
+  });
+
+  it('does not write grid-template-columns as a raw inline style (regression: inline style defeats xstyle/@media overrides)', () => {
+    render(
+      <Grid columns={3} rowHeight={80} data-testid="grid">
+        <div>Item 1</div>
+      </Grid>,
+    );
+    const grid = screen.getByTestId('grid');
+    // The declaration must live in a class (via CSS-var indirection), never
+    // as a raw inline property — inline would beat any consumer override.
+    expect(grid.style.gridTemplateColumns).toBe('');
+    expect(grid.style.gridAutoRows).toBe('');
+    expect(templateColumns(grid)).toBe('repeat(3, 1fr)');
+    expect(grid.style.getPropertyValue('--x-gridAutoRows')).toBe('80px');
   });
 
   it('renders with columns object (auto-fill default)', () => {
@@ -36,9 +62,7 @@ describe('Grid', () => {
       </Grid>,
     );
     const grid = screen.getByTestId('grid');
-    expect(grid.style.gridTemplateColumns).toBe(
-      'repeat(auto-fill, minmax(250px, 1fr))',
-    );
+    expect(templateColumns(grid)).toBe('repeat(auto-fill, minmax(250px, 1fr))');
   });
 
   it('renders with columns object max (capped via track-max)', () => {
@@ -51,7 +75,7 @@ describe('Grid', () => {
     );
     const grid = screen.getByTestId('grid');
     // Track max caps at (100% - 2 * gap) / 3 — no maxWidth on container
-    expect(grid.style.gridTemplateColumns).toBe(
+    expect(templateColumns(grid)).toBe(
       'repeat(auto-fill, minmax(250px, calc((100% - 2 * var(--spacing-4)) / 3)))',
     );
     expect(grid.style.maxWidth).toBe('');
@@ -59,17 +83,14 @@ describe('Grid', () => {
 
   it('renders with columns object max using columnGap', () => {
     render(
-      <Grid
-        columns={{minWidth: 200, max: 4}}
-        columnGap={6}
-        data-testid="grid">
+      <Grid columns={{minWidth: 200, max: 4}} columnGap={6} data-testid="grid">
         <div>Item 1</div>
         <div>Item 2</div>
       </Grid>,
     );
     const grid = screen.getByTestId('grid');
     // columnGap takes precedence for track-max calculation
-    expect(grid.style.gridTemplateColumns).toBe(
+    expect(templateColumns(grid)).toBe(
       'repeat(auto-fill, minmax(200px, calc((100% - 3 * var(--spacing-6)) / 4)))',
     );
     expect(grid.style.maxWidth).toBe('');
@@ -118,7 +139,7 @@ describe('Grid', () => {
       </Grid>,
     );
     const grid = screen.getByTestId('grid');
-    expect(grid.style.gridTemplateColumns).toBe('1fr');
+    expect(templateColumns(grid)).toBe('1fr');
   });
 
   // --- P1: columns={0} guard (hardening #719) ---
@@ -131,7 +152,7 @@ describe('Grid', () => {
     );
     const grid = screen.getByTestId('grid');
     // columns={0} must not produce repeat(0, 1fr) — should fall back to default
-    expect(grid.style.gridTemplateColumns).toBe('1fr');
+    expect(templateColumns(grid)).toBe('1fr');
   });
 
   it('falls back to 1fr when columns is negative', () => {
@@ -141,7 +162,7 @@ describe('Grid', () => {
       </Grid>,
     );
     const grid = screen.getByTestId('grid');
-    expect(grid.style.gridTemplateColumns).toBe('1fr');
+    expect(templateColumns(grid)).toBe('1fr');
   });
 
   it('uses auto-fill without track-max cap when no max specified', () => {
@@ -151,9 +172,7 @@ describe('Grid', () => {
       </Grid>,
     );
     const grid = screen.getByTestId('grid');
-    expect(grid.style.gridTemplateColumns).toBe(
-      'repeat(auto-fill, minmax(200px, 1fr))',
-    );
+    expect(templateColumns(grid)).toBe('repeat(auto-fill, minmax(200px, 1fr))');
     expect(grid.style.maxWidth).toBe('');
   });
 
@@ -213,7 +232,7 @@ describe('Grid', () => {
     );
     const grid = screen.getByTestId('grid');
     // columnGap takes precedence over gap in track-max
-    expect(grid.style.gridTemplateColumns).toBe(
+    expect(templateColumns(grid)).toBe(
       'repeat(auto-fill, minmax(200px, calc((100% - 2 * var(--spacing-6)) / 3)))',
     );
     expect(grid.style.maxWidth).toBe('');
@@ -226,7 +245,7 @@ describe('Grid', () => {
       </Grid>,
     );
     const grid = screen.getByTestId('grid');
-    expect(grid.style.gridTemplateColumns).toBe(
+    expect(templateColumns(grid)).toBe(
       'repeat(auto-fill, minmax(150px, calc((100% - 1 * var(--spacing-3)) / 2)))',
     );
     expect(grid.style.maxWidth).toBe('');
@@ -239,7 +258,7 @@ describe('Grid', () => {
       </Grid>,
     );
     const grid = screen.getByTestId('grid');
-    expect(grid.style.gridTemplateColumns).toBe(
+    expect(templateColumns(grid)).toBe(
       'repeat(auto-fill, minmax(100px, calc(100% / 3)))',
     );
     expect(grid.style.maxWidth).toBe('');
@@ -288,9 +307,7 @@ describe('Grid', () => {
       </Grid>,
     );
     const grid = screen.getByTestId('grid');
-    expect(grid.style.gridTemplateColumns).toBe(
-      'repeat(auto-fill, minmax(280px, 1fr))',
-    );
+    expect(templateColumns(grid)).toBe('repeat(auto-fill, minmax(280px, 1fr))');
   });
 
   it('renders with columns={{minWidth, repeat: "fit"}} using auto-fit', () => {
@@ -301,9 +318,7 @@ describe('Grid', () => {
       </Grid>,
     );
     const grid = screen.getByTestId('grid');
-    expect(grid.style.gridTemplateColumns).toBe(
-      'repeat(auto-fit, minmax(280px, 1fr))',
-    );
+    expect(templateColumns(grid)).toBe('repeat(auto-fit, minmax(280px, 1fr))');
   });
 
   it('renders with columns={{minWidth, repeat: "fill"}} using auto-fill', () => {
@@ -314,9 +329,7 @@ describe('Grid', () => {
       </Grid>,
     );
     const grid = screen.getByTestId('grid');
-    expect(grid.style.gridTemplateColumns).toBe(
-      'repeat(auto-fill, minmax(280px, 1fr))',
-    );
+    expect(templateColumns(grid)).toBe('repeat(auto-fill, minmax(280px, 1fr))');
   });
 
   it('renders with columns={{minWidth, max}} capping via track-max', () => {
@@ -328,7 +341,7 @@ describe('Grid', () => {
     );
     const grid = screen.getByTestId('grid');
     // Track-max limits columns — grid stays full width
-    expect(grid.style.gridTemplateColumns).toBe(
+    expect(templateColumns(grid)).toBe(
       'repeat(auto-fill, minmax(280px, calc((100% - 2 * var(--spacing-4)) / 3)))',
     );
     expect(grid.style.maxWidth).toBe('');
@@ -345,7 +358,7 @@ describe('Grid', () => {
       </Grid>,
     );
     const grid = screen.getByTestId('grid');
-    expect(grid.style.gridTemplateColumns).toBe(
+    expect(templateColumns(grid)).toBe(
       'repeat(auto-fit, minmax(280px, calc((100% - 2 * var(--spacing-4)) / 3)))',
     );
     expect(grid.style.maxWidth).toBe('');

package/src/Grid/Grid.tsx

@@ -83,6 +83,18 @@ export interface GridProps extends BaseProps<HTMLDivElement> {
    */
   height?: SizeValue;
 
+  /**
+   * Maximum width of the grid container.
+   * Numbers are treated as pixels, strings are used as-is (e.g., '100%').
+   */
+  maxWidth?: SizeValue;
+
+  /**
+   * Minimum height of the grid container.
+   * Numbers are treated as pixels, strings are used as-is (e.g., '100%').
+   */
+  minHeight?: SizeValue;
+
   /**
    * Spacing between all grid items (both row and column).
    * Accepts numeric spacing steps: 0, 0.5, 1, 1.5, 2, 3, 4, 5, 6, 8, 10.
@@ -140,6 +152,19 @@ const baseStyles = stylex.create({
   },
 });
 
+// Dynamic track values compile to CSS variables + a class-level declaration
+// (grid-template-columns: var(--x)) instead of a raw inline style, so
+// consumer `xstyle` overrides — including ones inside @media queries — can
+// still win. A raw inline `grid-template-columns` would beat any class.
+const dynamicStyles = stylex.create({
+  templateColumns: (value: string) => ({
+    gridTemplateColumns: value,
+  }),
+  autoRows: (value: number) => ({
+    gridAutoRows: `${value}px`,
+  }),
+});
+
 const alignStyles = stylex.create({
   start: {
     alignItems: 'start',
@@ -346,6 +371,8 @@ export function Grid({
   rowHeight,
   width,
   height,
+  maxWidth,
+  minHeight,
   gap,
   rowGap,
   columnGap,
@@ -399,16 +426,22 @@ export function Grid({
     gridTemplateColumns = '1fr';
   }
 
-  // Build inline style for dynamic values
+  // Build inline style for dynamic values. Track templates go through
+  // dynamicStyles (CSS-var indirection) so xstyle/@media overrides work;
+  // width/height stay inline as explicit caller-set dimensions.
   const inlineStyle: React.CSSProperties = {
-    gridTemplateColumns,
-    ...(rowHeight != null && {gridAutoRows: `${rowHeight}px`}),
     ...(width != null && {
       width: typeof width === 'number' ? `${width}px` : width,
     }),
     ...(height != null && {
       height: typeof height === 'number' ? `${height}px` : height,
     }),
+    ...(maxWidth != null && {
+      maxWidth: typeof maxWidth === 'number' ? `${maxWidth}px` : maxWidth,
+    }),
+    ...(minHeight != null && {
+      minHeight: typeof minHeight === 'number' ? `${minHeight}px` : minHeight,
+    }),
   };
 
   // For themeProps, extract numeric columns value for variant tracking
@@ -426,6 +459,8 @@ export function Grid({
         themeProps('grid', {columns: columnsVariant, gap, align, justify}),
         stylex.props(
           baseStyles.grid,
+          dynamicStyles.templateColumns(gridTemplateColumns),
+          rowHeight != null && dynamicStyles.autoRows(rowHeight),
           gap != null && gapStyles[gap],
           rowGap != null && rowGapStyles[rowGap],
           columnGap != null && columnGapStyles[columnGap],

package/src/Icon/Icon.doc.mjs

@@ -51,7 +51,7 @@ export const docs = {
       { guidance: false, description: 'Resize icons with arbitrary pixel values; use the provided size props.' },
       { guidance: false, description: 'Mix icon styles (e.g. outline and filled) within the same context.' },
       { guidance: false, description: 'Render raw SVG elements; always wrap in Icon for consistent sizing and color.' },
-      { guidance: false, description: 'Pass a `name` prop \u2014 Icon uses `icon` (not `name`) to specify which icon to render.' },
+      { guidance: false, description: 'Pass a `name` prop; Icon uses `icon` (not `name`) to specify which icon to render.' },
     ],
   },
 };
@@ -96,7 +96,7 @@ export const docsZh = {
       { guidance: false, description: 'Resize icons with arbitrary pixel values; use the provided size props.' },
       { guidance: false, description: 'Mix icon styles (e.g. outline and filled) within the same context.' },
       { guidance: false, description: 'Render raw SVG elements; always wrap in Icon for consistent sizing and color.' },
-      { guidance: false, description: 'Pass a `name` prop \u2014 Icon uses `icon` (not `name`) to specify which icon to render.' },
+      { guidance: false, description: 'Pass a `name` prop; Icon uses `icon` (not `name`) to specify which icon to render.' },
     ],
   },
 };
@@ -116,7 +116,7 @@ export const docsDense = {
       { guidance: false, description: 'Resize icons with arbitrary pixel values; use the provided size props.' },
       { guidance: false, description: 'Mix icon styles (e.g. outline and filled) within the same context.' },
       { guidance: false, description: 'Render raw SVG elements; always wrap in Icon for consistent sizing and color.' },
-      { guidance: false, description: '`name` prop \u2014 does not exist. Use `icon` to specify which icon to render.' },
+      { guidance: false, description: '`name` prop, which does not exist. Use `icon` to specify which icon to render.' },
     ],
   },
   propDescriptions: {

package/src/InputGroup/InputGroup.doc.mjs

@@ -8,18 +8,28 @@ export const docs = {
   group: 'Field',
   category: 'Data Input',
   isHiddenFromOverview: true,
-  keywords: ["inputgroup","addon","prefix","suffix","connected","grouped","input"],
+  keywords: [
+    'inputgroup',
+    'addon',
+    'prefix',
+    'suffix',
+    'connected',
+    'grouped',
+    'input',
+  ],
   theming: {
     targets: [
       {className: 'astryx-input-group', visualProps: ['size', 'status']},
     ],
   },
-  description: 'Groups an input with prefix/suffix addons in a visually connected container with shared border and focus ring.',
+  description:
+    'Groups an input with prefix/suffix addons in a visually connected container with shared border and focus ring.',
   props: [
     {
       name: 'children',
       type: 'ReactNode',
-      description: 'Input and InputGroupText children.',
+      description:
+        'InputGroupText and compatible input children: TextInput, NumberInput, TimeInput, DateInput, Typeahead, Selector, or MultiSelector.',
       required: true,
     },
     {
@@ -84,39 +94,117 @@ export const docs = {
       description: 'Test selector.',
     },
   ],
-  components: [
-    {name: 'InputGroupText'},
-  ],
+  components: [{name: 'InputGroupText'}],
   usage: {
-    description: 'InputGroup connects an input with prefix/suffix addons in a single visual unit. Use it for URL fields, currency inputs, search fields with action buttons, or any input that needs contextual decorations.',
+    description:
+      'InputGroup connects an input with prefix/suffix addons in a single visual unit. Use it for URL fields, currency inputs, search fields with action buttons, or any input that needs contextual decorations.',
     bestPractices: [
-      {guidance: true, description: 'Use text addons to show units, prefixes, or suffixes that clarify the input format (e.g., "$", "kg", "https://").'},
-      {guidance: true, description: 'Use InputGroupText for static prefixes/suffixes like "$", "kg", or "https://".'},
-      {guidance: true, description: 'Set isLabelHidden on the inner input and let the group label be visible.'},
-      {guidance: false, description: 'Don\'t put multiple text inputs in one group; use separate fields instead.'},
-      {guidance: false, description: 'Don\'t use InputGroup for unrelated inputs; it\'s for a single input with decorations.'},
+      {
+        guidance: true,
+        description:
+          'Use text addons to show units, prefixes, or suffixes that clarify the input format (e.g., "$", "kg", "https://").',
+      },
+      {
+        guidance: true,
+        description:
+          'Use InputGroupText for static prefixes/suffixes like "$", "kg", or "https://".',
+      },
+      {
+        guidance: true,
+        description:
+          'Use InputGroup with compatible single-line inputs: TextInput, NumberInput, TimeInput, DateInput, Typeahead, Selector, and MultiSelector.',
+      },
+      {
+        guidance: true,
+        description:
+          "Keep each inner input's label specific; grouped inputs automatically combine the group label with their own label and inherit the group description/status context.",
+      },
+      {
+        guidance: false,
+        description:
+          "Don't put multiple text inputs in one group; use separate fields instead.",
+      },
+      {
+        guidance: false,
+        description:
+          "Don't use InputGroup for unrelated inputs; it's for a single input with decorations.",
+      },
+      {
+        guidance: false,
+        description:
+          "Don't use InputGroup with TextArea, Slider, Switch, CheckboxInput, or RadioList.",
+      },
     ],
     anatomy: [
       {name: 'Label', required: true, description: 'Text above the group.'},
-      {name: 'Prefix addon', required: false, description: 'Content before the input (text, icon, or button).'},
-      {name: 'Input', required: true, description: 'The main input element (TextInput, NumberInput, etc.).'},
-      {name: 'Suffix addon', required: false, description: 'Content after the input (text, icon, or button).'},
-      {name: 'Status message', required: false, description: 'An error, warning, or success message below the group.'},
+      {
+        name: 'Prefix addon',
+        required: false,
+        description: 'Content before the input (text, icon, or button).',
+      },
+      {
+        name: 'Input',
+        required: true,
+        description:
+          'The main input element (TextInput, NumberInput, TimeInput, DateInput, Typeahead, Selector, or MultiSelector).',
+      },
+      {
+        name: 'Suffix addon',
+        required: false,
+        description: 'Content after the input (text, icon, or button).',
+      },
+      {
+        name: 'Status message',
+        required: false,
+        description: 'An error, warning, or success message below the group.',
+      },
     ],
   },
 };
 
 /** @type {import('../docs-types').TranslationDoc} */
 export const docsDense = {
-  description: 'groups input with prefix/suffix addons in a connected container',
+  description:
+    'groups input with prefix/suffix addons in a connected container',
   usage: {
-    description: 'InputGroup connects an input with addons. Use for URL fields, currency inputs, search with actions.',
+    description:
+      'InputGroup connects an input with addons. Use for URL fields, currency inputs, search with actions.',
     bestPractices: [
-      {guidance: true, description: 'Use text addons to show units, prefixes, or suffixes that clarify input format (e.g. "$", "kg", "https://").'},
-      {guidance: true, description: 'Use InputGroupText for static prefixes/suffixes like "$", "kg", or "https://".'},
-      {guidance: true, description: 'Set isLabelHidden on the inner input and let the group label be visible.'},
-      {guidance: false, description: 'Don\'t put multiple text inputs in one group; use separate fields instead.'},
-      {guidance: false, description: 'Don\'t use InputGroup for unrelated inputs; it\'s for a single input with decorations.'},
+      {
+        guidance: true,
+        description:
+          'Use text addons to show units, prefixes, or suffixes that clarify input format (e.g. "$", "kg", "https://").',
+      },
+      {
+        guidance: true,
+        description:
+          'Use InputGroupText for static prefixes/suffixes like "$", "kg", or "https://".',
+      },
+      {
+        guidance: true,
+        description:
+          'Use InputGroup with compatible single-line inputs: TextInput, NumberInput, TimeInput, DateInput, Typeahead, Selector, and MultiSelector.',
+      },
+      {
+        guidance: true,
+        description:
+          "Keep each inner input's label specific; grouped inputs combine the group label with their own label and inherit group description/status.",
+      },
+      {
+        guidance: false,
+        description:
+          "Don't put multiple text inputs in one group; use separate fields instead.",
+      },
+      {
+        guidance: false,
+        description:
+          "Don't use InputGroup for unrelated inputs; it's for a single input with decorations.",
+      },
+      {
+        guidance: false,
+        description:
+          "Don't use InputGroup with TextArea, Slider, Switch, CheckboxInput, or RadioList.",
+      },
     ],
   },
 };