@astryxdesign/core 0.1.7 → 0.1.8-canary.0c4d8d7

package/dist/authoring/doc.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"doc.d.ts","sourceRoot":"","sources":["../../src/authoring/doc.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"doc.d.ts","sourceRoot":"","sources":["../../src/authoring/doc.ts"],"names":[],"mappings":"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"}

package/dist/hooks/computeOverflow.d.ts

@@ -0,0 +1,47 @@
+/**
+ * @file computeOverflow.ts
+ * @input Plain measurements (item widths, gap, available width, indicator width, limits)
+ * @output Pure overflow computation: how many items are visible and their row layout
+ * @position Pure helper consumed by useOverflow; contains no DOM or React code so the
+ *           fit/clamp math and the multi-row packing can be unit-tested in isolation.
+ *
+ * There is a single source of truth for `visibleCount`:
+ *   visibleCount = clamp(fitCount, minVisibleItems, maxVisibleItems ?? itemCount)
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/hooks/useOverflow.ts (the only caller)
+ */
+export interface ComputeOverflowInput {
+    /** Measured widths of each item, in original DOM order. */
+    widths: number[];
+    /** Gap between items, in pixels. */
+    gap: number;
+    /** Width available to lay items out, in pixels. */
+    availableWidth: number;
+    /** Measured width of the overflow indicator (0 if none). */
+    indicatorWidth: number;
+    /** Floor — always show at least this many items. */
+    minVisibleItems: number;
+    /** Ceiling — never show more than this many items. `undefined` = no cap. */
+    maxVisibleItems?: number;
+    /**
+     * Bounded multi-row: wrap items across up to this many rows, then collapse
+     * the rest into the overflow indicator. `undefined` (or `1`) = single line.
+     */
+    maxRows?: number;
+    /** Which end items collapse from. */
+    collapseFrom: 'start' | 'end';
+}
+export interface ComputeOverflowResult {
+    /** Number of items that should be rendered in the visible container. */
+    visibleCount: number;
+    /** Number of rows the visible items occupy (always 1 for the single-line path). */
+    rows: number;
+}
+/**
+ * Pure overflow computation. Given plain measurements and the configured
+ * limits, return how many items should be visible and how many rows they
+ * occupy. No DOM, no React — safe to unit-test directly.
+ */
+export declare function computeOverflow(input: ComputeOverflowInput): ComputeOverflowResult;
+//# sourceMappingURL=computeOverflow.d.ts.map

package/dist/hooks/computeOverflow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"computeOverflow.d.ts","sourceRoot":"","sources":["../../src/hooks/computeOverflow.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;GAYG;AAEH,MAAM,WAAW,oBAAoB;IACnC,2DAA2D;IAC3D,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,oCAAoC;IACpC,GAAG,EAAE,MAAM,CAAC;IACZ,mDAAmD;IACnD,cAAc,EAAE,MAAM,CAAC;IACvB,4DAA4D;IAC5D,cAAc,EAAE,MAAM,CAAC;IACvB,oDAAoD;IACpD,eAAe,EAAE,MAAM,CAAC;IACxB,4EAA4E;IAC5E,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qCAAqC;IACrC,YAAY,EAAE,OAAO,GAAG,KAAK,CAAC;CAC/B;AAED,MAAM,WAAW,qBAAqB;IACpC,wEAAwE;IACxE,YAAY,EAAE,MAAM,CAAC;IACrB,mFAAmF;IACnF,IAAI,EAAE,MAAM,CAAC;CACd;AA0LD;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,oBAAoB,GAC1B,qBAAqB,CAqDvB"}

package/dist/hooks/computeOverflow.js

@@ -0,0 +1,213 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file computeOverflow.ts
+ * @input Plain measurements (item widths, gap, available width, indicator width, limits)
+ * @output Pure overflow computation: how many items are visible and their row layout
+ * @position Pure helper consumed by useOverflow; contains no DOM or React code so the
+ *           fit/clamp math and the multi-row packing can be unit-tested in isolation.
+ *
+ * There is a single source of truth for `visibleCount`:
+ *   visibleCount = clamp(fitCount, minVisibleItems, maxVisibleItems ?? itemCount)
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/hooks/useOverflow.ts (the only caller)
+ */
+
+function clamp(value, min, max) {
+  return Math.max(Math.min(value, max), min);
+}
+
+/**
+ * Resolve the ceiling and floor into a single [floor, ceiling] pair.
+ *
+ * `maxVisibleItems` is clamped to `itemCount` (a cap larger than the list is a
+ * no-op). When `maxVisibleItems < minVisibleItems`, the floor wins (D1) via the
+ * final clamp — the hook is responsible for the dev-only warning.
+ */
+function resolveBounds(itemCount, minVisibleItems, maxVisibleItems) {
+  const floor = Math.max(0, Math.min(minVisibleItems, itemCount));
+  const rawCeiling = maxVisibleItems == null ? itemCount : maxVisibleItems;
+  const ceiling = Math.max(0, Math.min(rawCeiling, itemCount));
+  return {
+    floor,
+    ceiling
+  };
+}
+
+/**
+ * Single-line greedy fit: how many items fit in one row of `availableWidth`,
+ * reserving indicator space for every non-final admitted item. Mirrors the
+ * original in-hook loop so single-line behavior is unchanged.
+ */
+function computeSingleLineFit(orderedWidths, gap, availableWidth, indicatorWidth, floor, ceiling) {
+  let totalWidth = 0;
+  let count = 0;
+  for (let i = 0; i < orderedWidths.length; i++) {
+    if (count >= ceiling) {
+      break;
+    }
+    const itemWidth = orderedWidths[i];
+    const gapWidth = i > 0 ? gap : 0;
+    const candidateWidth = totalWidth + itemWidth + gapWidth;
+    const isLastItem = i === orderedWidths.length - 1;
+    const reservedWidth = isLastItem ? 0 : indicatorWidth + (count > 0 || indicatorWidth > 0 ? gap : 0);
+    if (candidateWidth + reservedWidth > availableWidth && count >= floor) {
+      break;
+    }
+    totalWidth = candidateWidth;
+    count++;
+  }
+  return count;
+}
+
+/**
+ * Pack items into rows, wrapping when the next item would exceed
+ * `availableWidth`. On the last allowed row, keep `indicatorReserve` px free so
+ * the overflow indicator fits. Stops admitting once no further item can be
+ * placed within `maxRows`.
+ */
+function packRows(orderedWidths, gap, availableWidth, indicatorReserve, maxRows) {
+  let placed = 0;
+  let row = 1;
+  let rowWidth = 0;
+  for (let i = 0; i < orderedWidths.length; i++) {
+    const w = orderedWidths[i];
+    const isFirstInRow = rowWidth === 0;
+    const candidate = isFirstInRow ? w : rowWidth + gap + w;
+    const onLastRow = row === maxRows;
+    const reserve = onLastRow && indicatorReserve > 0 ? indicatorReserve + gap : 0;
+    if (candidate + reserve <= availableWidth) {
+      rowWidth = candidate;
+      placed++;
+      continue;
+    }
+    if (isFirstInRow) {
+      // A single item wider than the row occupies this row alone (it will be
+      // clipped visually). But if it can't coexist with the reserved indicator
+      // on the last row, stop here.
+      if (onLastRow && reserve > 0) {
+        break;
+      }
+      rowWidth = candidate;
+      placed++;
+      continue;
+    }
+    if (row >= maxRows) {
+      break;
+    }
+    row++;
+    rowWidth = 0;
+    i--; // re-attempt this item as the first on the new row
+  }
+  return {
+    placed,
+    rows: row
+  };
+}
+
+/** Count how many rows a set of items occupies when wrapped at availableWidth. */
+function countRows(orderedWidths, gap, availableWidth) {
+  if (orderedWidths.length === 0) {
+    return 0;
+  }
+  let rows = 1;
+  let rowWidth = 0;
+  for (let i = 0; i < orderedWidths.length; i++) {
+    const w = orderedWidths[i];
+    const isFirstInRow = rowWidth === 0;
+    const candidate = isFirstInRow ? w : rowWidth + gap + w;
+    if (candidate <= availableWidth || isFirstInRow) {
+      rowWidth = candidate;
+    } else {
+      rows++;
+      rowWidth = w;
+    }
+  }
+  return rows;
+}
+
+/**
+ * Multi-row packing (Strategy A): simulate wrapping items into rows of
+ * `availableWidth`, admitting items until a new item would require a row beyond
+ * `maxRows`, reserving indicator space on the final row when items overflow.
+ * Returns the admitted count and how many rows those items occupy. Assumes
+ * uniform row height.
+ */
+function computeMultiRowFit(orderedWidths, gap, availableWidth, indicatorWidth, maxRows) {
+  const n = orderedWidths.length;
+  if (n === 0) {
+    return {
+      count: 0,
+      rows: 0
+    };
+  }
+
+  // If everything fits within maxRows without reserving indicator space, there
+  // is no overflow and no indicator is needed.
+  const packAll = packRows(orderedWidths, gap, availableWidth, 0, maxRows);
+  if (packAll.placed === n) {
+    return {
+      count: n,
+      rows: packAll.rows
+    };
+  }
+
+  // Overflow → reserve indicator space on the final row and re-pack.
+  const packWithIndicator = packRows(orderedWidths, gap, availableWidth, indicatorWidth, maxRows);
+  const count = packWithIndicator.placed;
+  const rows = countRows(orderedWidths.slice(0, count), gap, availableWidth);
+  return {
+    count,
+    rows: Math.max(count > 0 ? 1 : 0, rows)
+  };
+}
+
+/**
+ * Pure overflow computation. Given plain measurements and the configured
+ * limits, return how many items should be visible and how many rows they
+ * occupy. No DOM, no React — safe to unit-test directly.
+ */
+export function computeOverflow(input) {
+  const {
+    widths,
+    gap,
+    availableWidth,
+    indicatorWidth,
+    minVisibleItems,
+    maxVisibleItems,
+    maxRows,
+    collapseFrom
+  } = input;
+  const itemCount = widths.length;
+  if (itemCount === 0) {
+    return {
+      visibleCount: 0,
+      rows: 0
+    };
+  }
+  const {
+    floor,
+    ceiling
+  } = resolveBounds(itemCount, minVisibleItems, maxVisibleItems);
+  const orderedWidths = collapseFrom === 'end' ? widths : [...widths].reverse();
+  const multiRow = maxRows != null && maxRows > 1;
+  if (!multiRow) {
+    const fitCount = computeSingleLineFit(orderedWidths, gap, availableWidth, indicatorWidth, floor, ceiling);
+    const visibleCount = clamp(fitCount, floor, ceiling);
+    return {
+      visibleCount,
+      rows: visibleCount > 0 ? 1 : 0
+    };
+  }
+  const {
+    count,
+    rows
+  } = computeMultiRowFit(orderedWidths, gap, availableWidth, indicatorWidth, maxRows);
+  const visibleCount = clamp(count, floor, ceiling);
+  const resolvedRows = visibleCount === count ? rows : countRows(orderedWidths.slice(0, visibleCount), gap, availableWidth);
+  return {
+    visibleCount,
+    rows: visibleCount > 0 ? Math.max(1, resolvedRows) : 0
+  };
+}

package/dist/hooks/useOverflow.d.ts

@@ -9,6 +9,21 @@ export interface UseOverflowOptions {
      * @default 0
      */
     minVisibleItems?: number;
+    /**
+     * Maximum number of items to ever show, even if they all fit. The ceiling
+     * partner to `minVisibleItems`. `undefined` means no cap. When it is less
+     * than `minVisibleItems`, the floor wins and a dev-only warning is emitted.
+     * @default undefined
+     */
+    maxVisibleItems?: number;
+    /**
+     * Wrap items across up to this many rows before collapsing the rest into the
+     * overflow indicator. `undefined` (or `1`) keeps the single-line behavior.
+     * A number, not a boolean: unbounded wrapping is a plain flex-wrap layout,
+     * not overflow collapse. Assumes uniform row height.
+     * @default undefined
+     */
+    maxRows?: number;
     /**
      * Which end to collapse items from.
      * @default 'end'
@@ -35,6 +50,10 @@ export interface UseOverflowReturn {
     visibleCount: number;
     /** Whether any items are overflowing */
     hasOverflow: boolean;
+    /** Number of rows the visible items occupy (1 for the single-line path) */
+    rows: number;
+    /** Measured max item height in pixels; used to size the multi-row container */
+    rowHeight: number;
 }
 /**
  * Hook for managing horizontal overflow of a list of items.

package/dist/hooks/useOverflow.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useOverflow.d.ts","sourceRoot":"","sources":["../../src/hooks/useOverflow.ts"],"names":[],"mappings":"AAsBA,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IAEzB;;;OAGG;IACH,YAAY,CAAC,EAAE,OAAO,GAAG,KAAK,CAAC;IAE/B;;;;;;;;;OASG;IACH,QAAQ,CAAC,EAAE,eAAe,GAAG,aAAa,CAAC;CAC5C;AAED,MAAM,WAAW,iBAAiB;IAChC,qDAAqD;IACrD,YAAY,EAAE,KAAK,CAAC,WAAW,CAAC,WAAW,CAAC,CAAC;IAC7C,wDAAwD;IACxD,UAAU,EAAE,KAAK,CAAC,WAAW,CAAC,WAAW,CAAC,CAAC;IAC3C,wDAAwD;IACxD,YAAY,EAAE,MAAM,CAAC;IACrB,wCAAwC;IACxC,WAAW,EAAE,OAAO,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,WAAW,CACzB,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE,kBAAuB,GAC/B,iBAAiB,CAsInB"}
+{"version":3,"file":"useOverflow.d.ts","sourceRoot":"","sources":["../../src/hooks/useOverflow.ts"],"names":[],"mappings":"AA0BA,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IAEzB;;;;;OAKG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IAEzB;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;OAGG;IACH,YAAY,CAAC,EAAE,OAAO,GAAG,KAAK,CAAC;IAE/B;;;;;;;;;OASG;IACH,QAAQ,CAAC,EAAE,eAAe,GAAG,aAAa,CAAC;CAC5C;AAED,MAAM,WAAW,iBAAiB;IAChC,qDAAqD;IACrD,YAAY,EAAE,KAAK,CAAC,WAAW,CAAC,WAAW,CAAC,CAAC;IAC7C,wDAAwD;IACxD,UAAU,EAAE,KAAK,CAAC,WAAW,CAAC,WAAW,CAAC,CAAC;IAC3C,wDAAwD;IACxD,YAAY,EAAE,MAAM,CAAC;IACrB,wCAAwC;IACxC,WAAW,EAAE,OAAO,CAAC;IACrB,2EAA2E;IAC3E,IAAI,EAAE,MAAM,CAAC;IACb,+EAA+E;IAC/E,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,WAAW,CACzB,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE,kBAAuB,GAC/B,iBAAiB,CAyJnB"}

package/dist/hooks/useOverflow.js

@@ -10,14 +10,18 @@
  *
  * Measures children rendered in a hidden container to determine how many fit
  * in the available width, without flickering. Uses ResizeObserver to react
- * to container size changes.
+ * to container size changes. Supports an optional item cap (`maxVisibleItems`)
+ * and bounded multi-row wrapping (`maxRows`); the fit/clamp/row-packing math
+ * lives in the pure `computeOverflow` helper.
  *
  * SYNC: When modified, update:
  * - /packages/core/src/hooks/index.ts
+ * - /packages/core/src/hooks/computeOverflow.ts (the pure computation)
  */
 import { useState, useCallback, useRef } from 'react';
 import { useIsomorphicLayoutEffect } from "./useIsomorphicLayoutEffect.js";
 import { observeResize, unobserveResize } from "../utils/sharedResizeObserver.js";
+import { computeOverflow } from "./computeOverflow.js";
 /**
  * Hook for managing horizontal overflow of a list of items.
  *
@@ -40,11 +44,18 @@ export function useOverflow(itemCount, options = {}) {
   const {
     gap = 0,
     minVisibleItems = 0,
+    maxVisibleItems,
+    maxRows,
     collapseFrom = 'end',
     behavior = 'observeSelf'
   } = options;
+  if (process.env.NODE_ENV !== 'production' && maxVisibleItems != null && maxVisibleItems < minVisibleItems) {
+    console.warn(`useOverflow: maxVisibleItems (${maxVisibleItems}) is less than ` + `minVisibleItems (${minVisibleItems}); the floor wins and ` + `minVisibleItems items will be shown.`);
+  }
   const observeParent = behavior === 'observeParent';
   const [visibleCount, setVisibleCount] = useState(itemCount);
+  const [rows, setRows] = useState(1);
+  const [rowHeight, setRowHeight] = useState(0);
   const containerElRef = useRef(null);
   const measureElRef = useRef(null);
   const observedElRef = useRef(null);
@@ -72,34 +83,33 @@ export function useOverflow(itemCount, options = {}) {
     if (children.length === 0) {
       // eslint-disable-next-line @eslint-react/set-state-in-effect -- overflow count is derived from measured DOM widths
       setVisibleCount(0);
+      // eslint-disable-next-line @eslint-react/set-state-in-effect -- derived from measured DOM
+      setRows(0);
       return;
     }
-
-    // Collect widths of all children
     const widths = children.map(child => child.offsetWidth);
-
-    // Determine how many items fit
-    let totalWidth = 0;
-    let count = 0;
-    const orderedWidths = collapseFrom === 'end' ? widths : [...widths].reverse();
-    for (let i = 0; i < orderedWidths.length; i++) {
-      const itemWidth = orderedWidths[i];
-      const gapWidth = i > 0 ? gap : 0;
-      const candidateWidth = totalWidth + itemWidth + gapWidth;
-
-      // If this isn't the last item, we need to reserve space for the indicator
-      const isLastItem = i === orderedWidths.length - 1;
-      const reservedWidth = isLastItem ? 0 : indicatorWidth + (count > 0 || indicatorWidth > 0 ? gap : 0);
-      if (candidateWidth + reservedWidth > availableWidth && count >= minVisibleItems) {
-        break;
-      }
-      totalWidth = candidateWidth;
-      count++;
-    }
+    const measuredRowHeight = children.reduce((max, child) => Math.max(max, child.offsetHeight || 0), 0);
+    const {
+      visibleCount: nextVisible,
+      rows: nextRows
+    } = computeOverflow({
+      widths,
+      gap,
+      availableWidth,
+      indicatorWidth,
+      minVisibleItems,
+      maxVisibleItems,
+      maxRows,
+      collapseFrom
+    });
 
     // eslint-disable-next-line @eslint-react/set-state-in-effect -- overflow count is derived from measured DOM widths
-    setVisibleCount(Math.max(Math.min(count, itemCount), minVisibleItems));
-  }, [itemCount, gap, minVisibleItems, collapseFrom, observeParent]);
+    setVisibleCount(nextVisible);
+    // eslint-disable-next-line @eslint-react/set-state-in-effect -- derived from measured DOM
+    setRows(prev => prev === nextRows ? prev : nextRows);
+    // eslint-disable-next-line @eslint-react/set-state-in-effect -- derived from measured DOM
+    setRowHeight(prev => prev === measuredRowHeight ? prev : measuredRowHeight);
+  }, [itemCount, gap, minVisibleItems, maxVisibleItems, maxRows, collapseFrom, observeParent]);
   const containerRef = useCallback(el => {
     containerElRef.current = el;
 
@@ -132,6 +142,8 @@ export function useOverflow(itemCount, options = {}) {
     containerRef,
     measureRef,
     visibleCount,
-    hasOverflow
+    hasOverflow,
+    rows,
+    rowHeight
   };
 }

package/dist/theme/Theme.js

@@ -115,7 +115,7 @@ function useThemeStyleInjection(theme) {
     // One-time perf hint per theme
     if (!warnedThemes.has(theme.name)) {
       warnedThemes.add(theme.name);
-      console.warn(`[Astryx] Theme "${theme.name}" is using runtime style injection. ` + `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 ` + `the built artifacts.`);
+      console.warn(`[Astryx] Theme "${theme.name}" is using runtime style injection. ` + `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 @astryxdesign/cli theme build <file>\` to generate ` + `the built artifacts.`);
     }
     const {
       prose,

package/dist/theme/defineTheme.d.ts

@@ -3,7 +3,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/dist/theme/defineTheme.js

@@ -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/dist/theme/generateThemeRules.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generateThemeRules.d.ts","sourceRoot":"","sources":["../../src/theme/generateThemeRules.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,eAAe,CAAC;AA+DhD;;;;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;AAgKD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,YAAY,GAAG,MAAM,EAAE,CAgChE;AAoMD;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,YAAY,GAAG,eAAe,CAe5E;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,YAAY,GAAG,MAAM,CA4E9D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,YAAY,GAAG,cAAc,CA2BpE;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,YAAY,GAAG,MAAM,CAQhE"}
+{"version":3,"file":"generateThemeRules.d.ts","sourceRoot":"","sources":["../../src/theme/generateThemeRules.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,eAAe,CAAC;AA+DhD;;;;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;AAgKD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,YAAY,GAAG,MAAM,EAAE,CAoChE;AAwPD;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,YAAY,GAAG,eAAe,CAe5E;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,YAAY,GAAG,MAAM,CA4E9D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,YAAY,GAAG,cAAc,CA2BpE;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,YAAY,GAAG,MAAM,CAQhE"}

package/dist/theme/generateThemeRules.js

@@ -247,6 +247,10 @@ export function generateThemeRules(theme) {
   // 4. Prop-level color overrides (for text/heading/link specificity)
   generateColorOverrides(theme.components || {}, parts);
 
+  // 5. Text `size`-prop font-size overrides (so an explicit size beats a
+  //    themed type's font-size across the astryx-base → astryx-theme layers)
+  generateSizeOverrides(theme.components || {}, parts);
+
   // (on-media rules are generated separately — see generateOnMediaCSS)
 
   return parts;
@@ -408,6 +412,53 @@ function generateColorOverrides(components, parts) {
   }
 }
 
+/**
+ * Map a Text `size` prop value to its raw font-size token.
+ * Mirrors `sizeStyles` in `Text/text.stylex.ts` (note `xsm` → `--font-size-xs`).
+ * <!-- SYNC: packages/core/src/Text/text.stylex.ts (sizeStyles) -->
+ */
+const TEXT_SIZE_TOKEN_MAP = {
+  '4xs': 'var(--font-size-4xs)',
+  '3xs': 'var(--font-size-3xs)',
+  '2xs': 'var(--font-size-2xs)',
+  xsm: 'var(--font-size-xs)',
+  sm: 'var(--font-size-sm)',
+  base: 'var(--font-size-base)',
+  lg: 'var(--font-size-lg)',
+  xl: 'var(--font-size-xl)',
+  '2xl': 'var(--font-size-2xl)',
+  '3xl': 'var(--font-size-3xl)',
+  '4xl': 'var(--font-size-4xl)'
+};
+
+/**
+ * Generate `size`-prop font-size overrides for the Text component.
+ *
+ * The `size` prop is documented as a font-size override that wins over the
+ * size implied by `type`. Its StyleX class lives in `@layer astryx-base`, but a
+ * theme's per-type font-size rule (`.astryx-text.<type>`) lives in the higher
+ * `@layer astryx-theme`, so the layer cascade let the theme silently shadow
+ * `size` for any `type` the theme styled. Re-emitting the size classes here —
+ * same layer as the type rules, same `.astryx-text.<x>` specificity, later in
+ * source — restores `size` as a real override.
+ *
+ * Only `font-size` is overridden; line-height and other type properties are
+ * intentionally preserved, matching the prop's documented contract.
+ *
+ * Gated on the theme touching `text` (which includes the auto-generated
+ * type-scale rules) — with no theme type rule to beat, the base-layer StyleX
+ * class already wins and no override is needed.
+ */
+function generateSizeOverrides(components, parts) {
+  if (!('text' in components)) {
+    return;
+  }
+  for (const [sizeName, sizeValue] of Object.entries(TEXT_SIZE_TOKEN_MAP)) {
+    const suffix = parseStyleKey(`size:${sizeName}`);
+    parts.push(`  ${componentClassSelector('text', suffix)} { font-size: ${sizeValue}; }`);
+  }
+}
+
 /**
  * Generate theme rules split into component and prose groups.
  *

package/dist/theme/hct.d.ts

@@ -4,7 +4,6 @@ export interface HCT {
     tone: number;
 }
 export declare function toneToY(tone: number): number;
-export declare function yToTone(y: number): number;
 /**
  * Convert a hex color to HCT.
  * Hue: 0-360, Chroma: 0-~120, Tone: 0-100.

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

@@ -1 +1 @@
-{"version":3,"file":"hct.d.ts","sourceRoot":"","sources":["../../src/theme/hct.ts"],"names":[],"mappings":"AAwBA,MAAM,WAAW,GAAG;IAClB,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;CACd;AAoFD,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE5C;AAED,wBAAgB,OAAO,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAEzC;AAkBD;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAkBzC;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,GAAG,GAAG,MAAM,CA8BzC;AAkDD;;;GAGG;AACH,wBAAgB,YAAY,CAC1B,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,MAAM,GACb,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAMxB;AAMD;;GAEG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAM/D"}
+{"version":3,"file":"hct.d.ts","sourceRoot":"","sources":["../../src/theme/hct.ts"],"names":[],"mappings":"AAwBA,MAAM,WAAW,GAAG;IAClB,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;CACd;AAoFD,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE5C;AAkBD;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAkBzC;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,GAAG,GAAG,MAAM,CA8BzC;AAkDD;;;GAGG;AACH,wBAAgB,YAAY,CAC1B,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,MAAM,GACb,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAMxB;AAMD;;GAEG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAM/D"}

package/dist/theme/hct.js

@@ -79,9 +79,6 @@ function labToXyz(L, a, b) {
 export function toneToY(tone) {
   return labFInv((tone + 16) / 116);
 }
-export function yToTone(y) {
-  return 116 * labF(y) - 16;
-}
 
 // =============================================================================
 // Hex <-> RGB

package/dist/utils/types.d.ts

@@ -8,6 +8,19 @@
  * Size value type - accepts numbers (treated as pixels) or strings (e.g., '100%', '50vh').
  */
 export type SizeValue = number | string;
+/**
+ * Resting elevation level for configurable surfaces.
+ *
+ * Maps to the shadow token scale:
+ * - `none` = flat (`box-shadow: none`)
+ * - `low`  = `--shadow-low`
+ * - `med`  = `--shadow-med`
+ * - `high` = `--shadow-high`
+ *
+ * Components narrow this union to the steps they actually need — e.g. Card
+ * exposes all four, while ChatComposer exposes only `'none' | 'low'`.
+ */
+export type Elevation = 'none' | 'low' | 'med' | 'high';
 /**
  * Numeric spacing step from the Astryx spacing scale.
  *

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

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/utils/types.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AAEH;;GAEG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,MAAM,CAAC;AAExC;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,GAAG,GAAG,GAAG,CAAC,GAAG,GAAG,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/utils/types.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AAEH;;GAEG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,MAAM,CAAC;AAExC;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,KAAK,GAAG,KAAK,GAAG,MAAM,CAAC;AAExD;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,GAAG,GAAG,GAAG,CAAC,GAAG,GAAG,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC"}