@stonedogcode/style 0.20.3 → 0.23.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stonedogcode/style",
-  "version": "0.20.3",
+  "version": "0.23.0",
   "description": "A Panda CSS design system: a themeable Panda preset plus the React components built on it.",
   "license": "Apache-2.0",
   "author": "StoneDogCode L.L.C.",
@@ -37,7 +37,7 @@
     "prepare": "npm run panda:prepare",
     "pretype-check": "npm run panda:prepare",
     "type-check": "tsc --noEmit",
-    "lint": "eslint . --ext ts,tsx",
+    "lint": "eslint .",
     "//pretest": "panda:build, not panda:prepare — the token-contract suite asserts against the generated stylesheet, which cssgen produces and codegen alone does not.",
     "pretest": "npm run panda:build",
     "test": "jest",
@@ -64,6 +64,7 @@
     "csstype": "^3.2.3"
   },
   "devDependencies": {
+    "@eslint/js": "^9.0.0",
     "@pandacss/dev": "^1.11.1",
     "@playwright/experimental-ct-react": "^1.62.1",
     "@playwright/test": "^1.62.1",
@@ -75,9 +76,10 @@
     "@types/react-dom": "^19.2.3",
     "@typescript-eslint/eslint-plugin": "^8.0.0",
     "@typescript-eslint/parser": "^8.0.0",
-    "eslint": "^8.57.1",
+    "eslint": "^9.39.5",
     "eslint-plugin-react": "^7.37.0",
     "eslint-plugin-react-hooks": "^5.0.0",
+    "globals": "^17.12.0",
     "jest": "^29.7.0",
     "jest-environment-jsdom": "^29.7.0",
     "react": "^19.0.4",

package/src/components/StyledBox.tsx

@@ -101,6 +101,79 @@ export interface StyledBoxProps
   scrollbar?: "auto" | "on" | "off";
 }
 
+/**
+ * The layout props that describe how a caller wants THEIR CHILDREN arranged.
+ *
+ * Without `noWrap`, `StyledBox` puts children three levels down:
+ *
+ * ```
+ * StyledBoxRoot        ← these props used to land here, and only here
+ *   └ StyledVStack     ← ...whose only child is this
+ *       └ div
+ *           └ StyledGridPanel
+ *               └ div  ← a plain block div, where the children actually live
+ * ```
+ *
+ * So a root flex container laid out exactly ONE item and the caller's children
+ * stayed in ordinary block flow — `display="flex" flexDirection="column"` did
+ * nothing, `alignItems` centred a wrapper, and `gap` separated nothing.
+ *
+ * The visible cost, three times over: two adjacent `StyledText` siblings render
+ * as one welded run, because `StyledText` is a `<span>` and JSX strips the
+ * whitespace between elements on separate lines. Hopper Vitals shipped
+ * `264.2Weight` and `Sep 6Record another to see a trend.` (NEH-1473), which is
+ * the same symptom NEH-490 fixed twice at the call site. Fixing it at the call
+ * site is why it came back.
+ *
+ * **This cannot break anything that currently works.** These declarations were
+ * discarded before — a flex container with one child arranges nothing — so
+ * nothing can be depending on their effect. Same argument `StyledText`'s block
+ * promotion makes for vertical margins on an inline box.
+ *
+ * They are FORWARDED, not moved: the root keeps them too, so a caller relying
+ * on the root's own box (a `gap` between header, content and footer, say) is
+ * unaffected.
+ *
+ * Sizing props are deliberately absent — `width`, `height`, `padding`,
+ * `margin`, `overflow` and friends genuinely apply to the root's own box, and
+ * copying them inward would double padding and re-clip content.
+ */
+const LAYOUT_PROPS = [
+  "display",
+  "flexDirection",
+  "flexWrap",
+  "alignItems",
+  "alignContent",
+  "justifyContent",
+  "justifyItems",
+  "gap",
+  "rowGap",
+  "columnGap",
+  "gridTemplateColumns",
+  "gridTemplateRows",
+  "gridAutoFlow",
+  "placeItems",
+  "placeContent",
+] as const;
+
+/**
+ * Did the caller ask for a layout of their own?
+ *
+ * When they did, and nothing else needs the wrapper, `StyledBox` renders the
+ * children DIRECTLY inside the root so the root really is their parent — which
+ * is what makes every Panda prop work, `gap` included.
+ *
+ * Forwarding the props as inline CSS was tried first and is wrong: `gap="2"` is
+ * a Panda spacing TOKEN, not a length, so `style={{ gap: "2" }}` is invalid CSS
+ * and silently dropped. Panda resolves tokens at build time for props on a
+ * styled component; it cannot for a runtime value written into a style
+ * attribute. Making the root the parent sidesteps the problem entirely — the props
+ * stay exactly where Panda already handles them.
+ */
+function wantsOwnLayout(rest: Record<string, unknown>): boolean {
+  return LAYOUT_PROPS.some((prop) => rest[prop] !== undefined && rest[prop] !== null);
+}
+
 const StyledBoxRoot = styled("div", boxRecipe);
 
 const StyledBox = React.forwardRef<HTMLDivElement, StyledBoxProps>(
@@ -137,6 +210,10 @@ const StyledBox = React.forwardRef<HTMLDivElement, StyledBoxProps>(
     // scrollbar prop controls inner content overflow
     const innerOverflow: Property.Overflow = scrollbar === "auto" ? "auto" : scrollbar === "on" ? "scroll" : "hidden";
 
+    // Does the caller lay out their own children? If so the wrapper is what
+    // stands between their props and the elements those props describe.
+    const callerLaysOutChildren = wantsOwnLayout(rest as Record<string, unknown>);
+
     if (noWrap) {
       if (resolvedHeader || resolvedFooter) {
         return (
@@ -153,6 +230,30 @@ const StyledBox = React.forwardRef<HTMLDivElement, StyledBoxProps>(
         </StyledBoxRoot>
       );
     }
+    /*
+      The caller lays out their own children and nothing else needs the
+      wrapper, so the root parents them directly.
+
+      Gated on there being no header, footer, panels or scrollbar: each of
+      those is a real reason the wrapper exists, and this must not take any of
+      them away. What is left is the case where the wrapper only ever stood
+      between a caller's layout props and the children they describe.
+    */
+    if (
+      callerLaysOutChildren &&
+      !resolvedHeader &&
+      !resolvedFooter &&
+      !leftPanel &&
+      !rightPanel &&
+      scrollbar === undefined
+    ) {
+      return (
+        <StyledBoxRoot ref={ref} {...(as ? { as } : {})} className={combinedClassName} {...rest}>
+          {children}
+        </StyledBoxRoot>
+      );
+    }
+
     return (
       <StyledBoxRoot ref={ref} {...(as ? { as } : {})} className={combinedClassName} {...rest}>
         <StyledVStack gap="0" width="100%" height="100%" style={{ overflow: innerOverflow }}>

package/src/components/StyledGrid.tsx

@@ -3,7 +3,6 @@ import { cx, css } from "styled-system/css";
 import { stripedRecipe } from "styled-system/recipes";
 import React from "react";
 import { log } from "../config/logger";
-import type { ConditionalValue } from "styled-system/types";
 
 const PandaGrid = styled("div", {
   base: {
@@ -11,25 +10,300 @@ const PandaGrid = styled("div", {
   },
 });
 
-export interface StyledGridProps extends Omit<HTMLStyledProps<"div">, "columns"> {
+/**
+ * The breakpoints this component's responsive objects understand.
+ *
+ * Exactly the six declared by the preset, plus `base`. Order matters: the
+ * runtime fills a value forward from each key to the next, so this array is the
+ * cascade.
+ */
+const GRID_BREAKPOINTS = ["base", "sm", "md", "lg", "xl", "2xl", "3xl"] as const;
+
+export type GridBreakpoint = (typeof GRID_BREAKPOINTS)[number];
+
+/** A plain value, or one value per breakpoint. */
+export type GridResponsiveValue<T> = T | Partial<Record<GridBreakpoint, T>>;
+
+/*
+ * ---------------------------------------------------------------------------
+ * Why the track definitions travel as CSS custom properties (NEH-1453)
+ * ---------------------------------------------------------------------------
+ *
+ * `StyledGrid` used to compute its `grid-template-*` values at runtime and hand
+ * them to Panda as style props:
+ *
+ *     resolvedColumns = `repeat(${columns}, 1fr)`;
+ *     <PandaGrid gridTemplateColumns={resolvedColumns} />
+ *
+ * Panda extracts styles by **statically parsing source at build time**. A value
+ * computed at runtime is never seen by `panda cssgen`, so Panda's runtime
+ * constructs a class *name* derived from the value and no rule is ever emitted
+ * for it. Measured in this package's own component tier, `<StyledGrid
+ * columns={2}>` inside a 320px container:
+ *
+ *     class="d_grid grid-tc_repeat(2,_1fr)"
+ *     inline style: null
+ *     computed grid-template-columns: 445.188px   <- ONE implicit, content-sized track
+ *     rules in the sheet mentioning grid-template-columns: 1, and it is
+ *       `.grid-tc_max-content_1fr` from StyledDefinitionList
+ *
+ * The same is true of `templateColumns` / `templateRows` / `templateAreas`,
+ * which are not Panda property names at all, so even a static literal at the
+ * call site is never extracted.
+ *
+ * Where it appeared to work in an app it was a **coincidence**: the class name
+ * is derived from the value, so a consumer whose own source happened to contain
+ * the same literal elsewhere got a rule by accident. That is why the fix cannot
+ * simply rewrite the emitted string — a new string breaks the coincidence and
+ * silently drops the columns.
+ *
+ * So the value has to reach the element by a route that does not depend on
+ * static extraction. Inline `style` is that route, and it is what
+ * `StyledSimpleGrid` already does. But a plain inline `grid-template-columns`
+ * cannot carry media queries, which is why `StyledSimpleGrid` pays for the
+ * responsive form with a JS resize listener (no server-rendered value, a
+ * listener per grid, a flash on first paint).
+ *
+ * This component avoids that trade by splitting the two halves:
+ *
+ *   - the **rules** are literals in this file, so Panda really does extract
+ *     them, one per breakpoint, with real `@media` conditions;
+ *   - the **values** ride in on inline custom properties, which are never
+ *     extracted, never parsed by Panda, and always applied.
+ *
+ * Result: real CSS breakpoints, correct on the server, no resize listener, and
+ * no upper bound on the column count.
+ *
+ * The runtime fills a value FORWARD across breakpoints rather than relying on
+ * nested `var()` fallbacks, so each rule is a flat `var(--x, none)`. `none` is
+ * the initial value of every `grid-template-*` property, so an axis nobody set
+ * resolves to exactly what it would have been.
+ */
+
+const TRACK_VAR = {
+  columns: "--sds-grid-tc",
+  rows: "--sds-grid-tr",
+  areas: "--sds-grid-ta",
+} as const;
+
+type GridAxis = keyof typeof TRACK_VAR;
+
+/**
+ * One class per axis, applied only when that axis has a value.
+ *
+ * They are separate constants on purpose. A single combined class would declare
+ * `grid-template-rows: none` on every grid, which is the initial value but is
+ * still a *declaration* — and it would then race, at equal specificity, with
+ * any `grid-template-rows` a consumer set through `className`. An axis nobody
+ * asked about is left untouched instead.
+ *
+ * Every value below is a string LITERAL. That is the entire point: Panda has to
+ * be able to read them without running anything.
+ */
+const AXIS_CLASS: Record<GridAxis, string> = {
+  columns: css({
+    gridTemplateColumns: "var(--sds-grid-tc-base, none)",
+    sm: { gridTemplateColumns: "var(--sds-grid-tc-sm, none)" },
+    md: { gridTemplateColumns: "var(--sds-grid-tc-md, none)" },
+    lg: { gridTemplateColumns: "var(--sds-grid-tc-lg, none)" },
+    xl: { gridTemplateColumns: "var(--sds-grid-tc-xl, none)" },
+    "2xl": { gridTemplateColumns: "var(--sds-grid-tc-2xl, none)" },
+    "3xl": { gridTemplateColumns: "var(--sds-grid-tc-3xl, none)" },
+  }),
+  rows: css({
+    gridTemplateRows: "var(--sds-grid-tr-base, none)",
+    sm: { gridTemplateRows: "var(--sds-grid-tr-sm, none)" },
+    md: { gridTemplateRows: "var(--sds-grid-tr-md, none)" },
+    lg: { gridTemplateRows: "var(--sds-grid-tr-lg, none)" },
+    xl: { gridTemplateRows: "var(--sds-grid-tr-xl, none)" },
+    "2xl": { gridTemplateRows: "var(--sds-grid-tr-2xl, none)" },
+    "3xl": { gridTemplateRows: "var(--sds-grid-tr-3xl, none)" },
+  }),
+  areas: css({
+    gridTemplateAreas: "var(--sds-grid-ta-base, none)",
+    sm: { gridTemplateAreas: "var(--sds-grid-ta-sm, none)" },
+    md: { gridTemplateAreas: "var(--sds-grid-ta-md, none)" },
+    lg: { gridTemplateAreas: "var(--sds-grid-ta-lg, none)" },
+    xl: { gridTemplateAreas: "var(--sds-grid-ta-xl, none)" },
+    "2xl": { gridTemplateAreas: "var(--sds-grid-ta-2xl, none)" },
+    "3xl": { gridTemplateAreas: "var(--sds-grid-ta-3xl, none)" },
+  }),
+};
+
+/**
+ * Spread a responsive value across every breakpoint, carrying each value
+ * forward until the next one overrides it.
+ *
+ * Filling forward is what lets each emitted rule be a flat `var(--x, none)`: at
+ * `lg` the rule reads `--sds-grid-tc-lg`, so that property has to hold the
+ * value in force at `lg` whether it was set there or inherited from `md`.
+ *
+ * Returns `undefined` when the caller supplied nothing, so the axis class is
+ * not applied at all.
+ */
+function resolveAxis(
+  value: GridResponsiveValue<string> | undefined,
+  componentName: string,
+): Partial<Record<GridBreakpoint, string>> | undefined {
+  if (value === undefined || value === null) return undefined;
+
+  if (typeof value === "string") {
+    const filled: Partial<Record<GridBreakpoint, string>> = {};
+    for (const breakpoint of GRID_BREAKPOINTS) filled[breakpoint] = value;
+    return filled;
+  }
+
+  if (typeof value !== "object") return undefined;
+
+  const unsupported = Object.keys(value).filter(
+    (key) => !(GRID_BREAKPOINTS as readonly string[]).includes(key),
+  );
+  if (unsupported.length > 0) {
+    // Loud rather than silent. Panda conditions other than a breakpoint
+    // (`_hover`, `_dark`, the array syntax) cannot be carried by a custom
+    // property, because there is no rule here that reads one under that
+    // condition. Before NEH-1453 they were dropped without a word; now they are
+    // dropped with one. Reach for `className={css({ ... })}` instead, which
+    // Panda extracts from the call site.
+    log.warn(`[${componentName}] ignoring unsupported responsive key(s)`, {
+      unsupported,
+      supported: GRID_BREAKPOINTS,
+    });
+  }
+
+  const filled: Partial<Record<GridBreakpoint, string>> = {};
+  let carried: string | undefined;
+  for (const breakpoint of GRID_BREAKPOINTS) {
+    const declared = (value as Partial<Record<GridBreakpoint, string>>)[breakpoint];
+    if (declared !== undefined) carried = declared;
+    if (carried !== undefined) filled[breakpoint] = carried;
+  }
+  return Object.keys(filled).length > 0 ? filled : undefined;
+}
+
+/**
+ * `repeat(n, minmax(<minTrackWidth>, 1fr))`, not `repeat(n, 1fr)`.
+ *
+ * In CSS `1fr` **is** shorthand for `minmax(auto, 1fr)`, and that `auto` floor
+ * is the grid item's automatic minimum size — its min-content. One child that
+ * cannot shrink therefore drags the whole track past the grid's container, and
+ * every sibling sized `width: 100%` inherits the overflow (NEH-1446/NEH-1447,
+ * measured at 425.875px inside a 375px container).
+ *
+ * `StyledSimpleGrid` made this change in 0.21.0 and `StyledGrid` deliberately
+ * did not, because at the time the emitted string still had to match a literal
+ * in the consumer's own source for any rule to exist at all — a new string
+ * would have broken that coincidence and dropped the columns entirely. Once the
+ * value stops travelling through Panda, that objection disappears, which is why
+ * the two changes belong in the same commit and not before it.
+ */
+function columnsToTemplate(count: number, minTrackWidth: string): string {
+  return `repeat(${count}, minmax(${minTrackWidth}, 1fr))`;
+}
+
+function columnsToTemplateValue(
+  columns: GridResponsiveValue<number>,
+  minTrackWidth: string,
+): GridResponsiveValue<string> | undefined {
+  if (typeof columns === "number") return columnsToTemplate(columns, minTrackWidth);
+  if (typeof columns !== "object" || columns === null) return undefined;
+
+  const mapped: Partial<Record<GridBreakpoint, string>> = {};
+  for (const [key, count] of Object.entries(columns)) {
+    if (typeof count === "number") {
+      mapped[key as GridBreakpoint] = columnsToTemplate(count, minTrackWidth);
+    }
+  }
+  return mapped;
+}
+
+/** Write one axis' resolved values out as inline custom properties. */
+function writeAxisVars(
+  target: Record<string, string>,
+  axis: GridAxis,
+  resolved: Partial<Record<GridBreakpoint, string>>,
+) {
+  for (const breakpoint of GRID_BREAKPOINTS) {
+    const value = resolved[breakpoint];
+    if (value !== undefined) target[`${TRACK_VAR[axis]}-${breakpoint}`] = value;
+  }
+}
+
+export interface StyledGridProps
+  extends Omit<
+    HTMLStyledProps<"div">,
+    "columns" | "gridTemplateColumns" | "gridTemplateRows" | "gridTemplateAreas"
+  > {
   children?: React.ReactNode;
   isStriped?: boolean;
   showGridLines?: boolean;
-  templateColumns?: ConditionalValue<string>;
-  templateRows?: ConditionalValue<string>;
-  templateAreas?: ConditionalValue<string>;
-  columns?: ConditionalValue<number | { base?: number; sm?: number; md?: number; lg?: number; xl?: number }>;
+  /**
+   * A `grid-template-columns` value, or one per breakpoint.
+   *
+   * Narrower than Panda's `ConditionalValue` on purpose: only `base` and the
+   * six preset breakpoints are carried. Any other condition is ignored with a
+   * warning — see `resolveAxis`.
+   */
+  templateColumns?: GridResponsiveValue<string>;
+  templateRows?: GridResponsiveValue<string>;
+  templateAreas?: GridResponsiveValue<string>;
+  /** Alias for `templateColumns`; takes precedence when both are supplied. */
+  gridTemplateColumns?: GridResponsiveValue<string>;
+  gridTemplateRows?: GridResponsiveValue<string>;
+  gridTemplateAreas?: GridResponsiveValue<string>;
+  /** Column count. Emits `repeat(n, minmax(minTrackWidth, 1fr))`. */
+  columns?: GridResponsiveValue<number>;
+  /**
+   * The minimum size of each `columns`-generated track. Defaults to `"0"`.
+   *
+   * Pass `"auto"` to let a track refuse to shrink below its widest unbreakable
+   * child, which is occasionally what you want — a deliberately horizontally
+   * scrolled strip — but now has to be asked for by name. Mirrors
+   * `StyledSimpleGrid`.
+   */
+  minTrackWidth?: string;
 }
 
 const StyledGrid = React.forwardRef<HTMLDivElement, StyledGridProps>(
-  ({
-    isStriped,
-    showGridLines,
-    className,
-    templateColumns,
-    templateRows,
-    templateAreas,
-    columns, ...props }, ref) => {
+  (
+    {
+      isStriped,
+      showGridLines,
+      className,
+      style,
+      templateColumns,
+      templateRows,
+      templateAreas,
+      gridTemplateColumns,
+      gridTemplateRows,
+      gridTemplateAreas,
+      columns,
+      minTrackWidth = "0",
+      ...props
+    },
+    ref,
+  ) => {
+    // Explicit template wins over the `columns` shorthand, as before.
+    const columnsValue =
+      gridTemplateColumns ??
+      templateColumns ??
+      (columns === undefined ? undefined : columnsToTemplateValue(columns, minTrackWidth));
+
+    const resolved: Record<GridAxis, Partial<Record<GridBreakpoint, string>> | undefined> = {
+      columns: resolveAxis(columnsValue, "StyledGrid"),
+      rows: resolveAxis(gridTemplateRows ?? templateRows, "StyledGrid"),
+      areas: resolveAxis(gridTemplateAreas ?? templateAreas, "StyledGrid"),
+    };
+
+    const trackVars: Record<string, string> = {};
+    const axisClasses: string[] = [];
+    for (const axis of ["columns", "rows", "areas"] as const) {
+      const axisValues = resolved[axis];
+      if (axisValues === undefined) continue;
+      writeAxisVars(trackVars, axis, axisValues);
+      axisClasses.push(AXIS_CLASS[axis]);
+    }
+
     const combinedClassName = cx(
       isStriped ? stripedRecipe() : undefined,
       showGridLines
@@ -42,35 +316,10 @@ const StyledGrid = React.forwardRef<HTMLDivElement, StyledGridProps>(
           },
         })
         : undefined,
+      ...axisClasses,
       className,
     );
 
-    // Map shorthand props to CSS grid properties
-    const gridTemplateColumns = props.gridTemplateColumns ?? templateColumns;
-    const gridTemplateRows = props.gridTemplateRows ?? templateRows;
-    const gridTemplateAreas = props.gridTemplateAreas ?? templateAreas;
-    delete props.gridTemplateColumns;
-    delete props.gridTemplateRows;
-    delete props.gridTemplateAreas;
-
-    // Handle columns prop (responsive column count)
-    let resolvedColumns = gridTemplateColumns;
-    if (columns !== undefined && !resolvedColumns) {
-      if (typeof columns === "number") {
-        resolvedColumns = `repeat(${columns}, 1fr)`;
-      } else if (typeof columns === "object" && columns !== null) {
-        const colObj = columns as { base?: number; sm?: number; md?: number; lg?: number; xl?: number };
-        // For responsive objects, we need to generate a responsive value
-        const responsive: Record<string, string> = {};
-        if (colObj.base !== undefined) responsive.base = `repeat(${colObj.base}, 1fr)`;
-        if (colObj.sm !== undefined) responsive.sm = `repeat(${colObj.sm}, 1fr)`;
-        if (colObj.md !== undefined) responsive.md = `repeat(${colObj.md}, 1fr)`;
-        if (colObj.lg !== undefined) responsive.lg = `repeat(${colObj.lg}, 1fr)`;
-        if (colObj.xl !== undefined) responsive.xl = `repeat(${colObj.xl}, 1fr)`;
-        resolvedColumns = responsive as ConditionalValue<string>;
-      }
-    }
-
     const childrenDetails = React.Children.map(props.children, (child) => {
       if (React.isValidElement(child)) {
         const element = child as React.ReactElement<{ id?: string }>;
@@ -91,13 +340,19 @@ const StyledGrid = React.forwardRef<HTMLDivElement, StyledGridProps>(
       childrenDetails
     });
 
+    // The caller's own `style` goes first: a `grid-template-columns` they set
+    // inline is their business and should still beat our class. Our custom
+    // properties are appended so nothing can accidentally shadow them.
+    const mergedStyle =
+      Object.keys(trackVars).length > 0
+        ? ({ ...style, ...trackVars } as React.CSSProperties)
+        : style;
+
     return (
       <PandaGrid
         ref={ref}
         className={combinedClassName}
-        gridTemplateColumns={resolvedColumns}
-        gridTemplateRows={gridTemplateRows}
-        gridTemplateAreas={gridTemplateAreas}
+        {...(mergedStyle === undefined ? {} : { style: mergedStyle })}
         {...props}
       />
     );

package/src/components/StyledSimpleGrid.tsx

@@ -17,6 +17,19 @@ interface StyledSimpleGridProps extends Omit<HTMLStyledProps<"div">, "columns">
   columns?: number | { base?: number; sm?: number; md?: number; lg?: number; xl?: number };
   gridTemplateRows?: string;
   gap?: string | number;
+  /**
+   * The minimum size of each `columns`-generated track. Defaults to `"0"`.
+   *
+   * `columns={n}` emits `repeat(n, minmax(<minTrackWidth>, 1fr))`. The default
+   * of `0` lets a track shrink below its content's min-content width, which is
+   * what keeps the grid inside its container.
+   *
+   * Pass `"auto"` to restore the pre-0.21.0 behaviour, in which a track refuses
+   * to shrink below its widest unbreakable child and the whole grid grows past
+   * its container. That is occasionally what you want — a deliberately
+   * horizontally scrolled strip — but it now has to be asked for by name.
+   */
+  minTrackWidth?: string;
 }
 
 const PandaSimpleGrid = styled("div", {
@@ -51,6 +64,7 @@ const StyledSimpleGrid: React.FC<StyledSimpleGridProps> = ({
   columns,
   gridTemplateRows,
   gap,
+  minTrackWidth = "0",
   style,
   children,
   ...rest
@@ -78,9 +92,22 @@ const StyledSimpleGrid: React.FC<StyledSimpleGridProps> = ({
   }, [recalculate]);
 
   // Runtime-computed grid values MUST use inline style — Panda CSS drops them at build time
+  //
+  // `minmax(minTrackWidth, 1fr)`, not a bare `1fr`. In CSS `1fr` IS shorthand
+  // for `minmax(auto, 1fr)`, and that `auto` floor is the grid item's automatic
+  // minimum size — its min-content. So one child that cannot shrink (a long
+  // unbroken string, a `white-space: nowrap` row, a fixed-width control) drags
+  // the track wider than the grid's own container, and every sibling sized
+  // `width: 100%` inherits the overflow. Measured on HopperGuard's dashboard at
+  // 375px: a 1-column grid resolved a 425.875px track inside a 375px container,
+  // and the shell clipped rather than scrolled (NEH-1446, NEH-1447).
+  //
+  // Guarded by grid-track-shrink.ct.tsx, which measures the resolved track in a
+  // real browser. jsdom cannot see this at all — it has no layout engine, so it
+  // reports every box as 0x0 and would agree that a 426px track fits 375px.
   const gridStyles: React.CSSProperties = {
     ...style,
-    gridTemplateColumns: `repeat(${resolvedCols}, 1fr)`,
+    gridTemplateColumns: `repeat(${resolvedCols}, minmax(${minTrackWidth}, 1fr))`,
     gridTemplateRows,
     gap,
   };