@dashforge/tw 0.1.0-beta → 0.2.1-beta

package/src/components/Grid/grid.types.ts

@@ -0,0 +1,112 @@
+import type { ElementType, HTMLAttributes } from 'react';
+
+/**
+ * Grid types — discriminated union for container vs item role.
+ *
+ * Pattern is MUI v2: a single `<Grid>` component that switches role
+ * based on the `container` prop. Container exposes layout axes
+ * (cols, spacing, autoFlow). Item exposes per-breakpoint span axes
+ * (xs/sm/md/lg/xl).
+ *
+ * TypeScript-level enforcement (the key win over MUI):
+ *   • `<Grid container xs={6}>` is a TYPE ERROR — `xs` doesn't exist
+ *     on the container shape.
+ *   • `<Grid xs={6} spacing={4}>` is a TYPE ERROR — `spacing` doesn't
+ *     exist on the item shape.
+ *   IntelliSense filters suggestions per role, so the developer never
+ *   sees props that don't apply.
+ *
+ * Type-only file (no runtime). Lives separate from the variants so the
+ * union doesn't widen with the variant catalogue's enum unions.
+ */
+
+/**
+ * Valid column-span values for a grid item, at any breakpoint.
+ *   • 1..12  — explicit span count
+ *   • 'auto' — content-sized (CSS Grid auto-track)
+ *   • 'full' — `col-span-full` (spans all columns regardless of count)
+ */
+export type ColSpan =
+  | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12
+  | 'auto'
+  | 'full';
+
+/**
+ * Token-scale spacing step. Mirror of Box.p / Stack.gap so the value
+ * space across primitives is identical — `<Grid container spacing={4}>`
+ * and `<Stack gap={4}>` produce visually equivalent gaps.
+ */
+export type GridSpacingStep =
+  | 0 | '0.5' | 1 | 2 | 3 | 4 | 6 | 8 | 12 | 16 | 24;
+
+/**
+ * Container-role props. Discriminated on `container: true`.
+ *
+ * NOTE on `cols`: defaults to 12 in the component implementation
+ * (not in TV) — the MUI v2 convention. Override to 6/4/3/2/1 for
+ * dense dashboard layouts.
+ */
+export interface GridContainerProps {
+  /** Discriminator — `true` makes this a grid container. */
+  container: true;
+  /** Number of columns. Default 12. */
+  cols?: 1 | 2 | 3 | 4 | 6 | 12;
+  /** Gap between cells. Shorthand for spacingX + spacingY. */
+  spacing?: GridSpacingStep;
+  /** Horizontal gap override (wins over `spacing`). */
+  spacingX?: GridSpacingStep;
+  /** Vertical gap override (wins over `spacing`). */
+  spacingY?: GridSpacingStep;
+  /** `grid-auto-flow` — useful for dense or column-major packing. */
+  autoFlow?: 'row' | 'col' | 'dense' | 'row-dense' | 'col-dense';
+}
+
+/**
+ * Item-role props. Discriminated on `container: false | undefined`.
+ *
+ * Each breakpoint accepts a `ColSpan`. The cascade is Tailwind-native
+ * mobile-first: `xs` is the base (no media query), `sm/md/lg/xl`
+ * override at the corresponding min-width.
+ *
+ * Default behaviour when no breakpoint is set: spans `full` — the
+ * "comfortable default" so a forgotten prop doesn't collapse the cell
+ * to 1/12th of a row.
+ */
+export interface GridItemProps {
+  /** Discriminator — absent (or `false`) makes this a grid item. */
+  container?: false;
+  /** Base breakpoint (no media query). Default `'full'`. */
+  xs?: ColSpan;
+  /** Span at sm breakpoint and up. */
+  sm?: ColSpan;
+  /** Span at md breakpoint and up. */
+  md?: ColSpan;
+  /** Span at lg breakpoint and up. */
+  lg?: ColSpan;
+  /** Span at xl breakpoint and up. */
+  xl?: ColSpan;
+}
+
+/**
+ * Common props shared by both roles. Kept in a separate intersection
+ * so the discriminated union stays narrow and IntelliSense fast.
+ */
+interface GridCommonProps extends Omit<HTMLAttributes<HTMLDivElement>, 'className'> {
+  /** Override the rendered HTML tag. Default `'div'`. Ignored under `asChild`. */
+  as?: ElementType;
+  /**
+   * Render via Radix Slot onto the single child. Wins over `as`.
+   * Note: container Grids using `asChild` don't make sense for most
+   * cases — the Slot pattern collapses our wrapper, but Grid's
+   * `display:grid` only applies to direct children, so the child
+   * needs to BE a container with the right children.
+   */
+  asChild?: boolean;
+  /** Utility-class override, merged via tailwind-merge. */
+  sx?: string;
+}
+
+/**
+ * `<Grid>` props — discriminated union: container OR item, never both.
+ */
+export type GridProps = (GridContainerProps | GridItemProps) & GridCommonProps;

package/src/components/Grid/grid.variants.ts

@@ -0,0 +1,133 @@
+import { tv, type VariantProps } from 'tailwind-variants';
+
+/**
+ * `gridVariants` — CSS Grid container + item, polymorphic in role.
+ *
+ * Architectural choice (planned with the user — F9 deep dive):
+ *
+ *   Pattern is MUI Grid v2 from the API side (`<Grid container>` +
+ *   `<Grid xs={6}>`), but engine is REAL CSS Grid under the hood
+ *   (`display: grid` + `grid-template-columns: repeat(N, 1fr)` +
+ *   `col-span-*`). MUI v2 uses flexbox + basis percentages — historical
+ *   IE11 reasons. In 2026, CSS Grid is universally supported AND
+ *   Tailwind ships `grid-cols-*` / `col-span-*` natively, so flexbox
+ *   would be a downgrade.
+ *
+ * Two distinct shapes coexist in the same TV recipe:
+ *
+ *   • container=true   — display:grid + cols + gap + autoFlow
+ *   • container=false  — col-span at each breakpoint (xs/sm/md/lg/xl)
+ *
+ *   The discriminated union lives in grid.types.ts (TypeScript-level);
+ *   here the TV catalogue exposes every axis so the consumer's choice
+ *   triggers the right classes regardless of which role the component
+ *   is playing. Unused axes produce no classes (TV silently drops
+ *   undefined variants), so a container Grid never accidentally emits
+ *   `col-span-6` and an item Grid never accidentally emits `grid`.
+ *
+ * Mapping table size:
+ *   • cols                  : 6 entries (12, 6, 4, 3, 2, 1)
+ *   • autoFlow              : 5 entries
+ *   • span axes (5×14)      : 70 entries (xs/sm/md/lg/xl × {1..12, auto, full})
+ *   • gap / gapX / gapY     : 33 entries (11 steps × 3 axes)
+ *
+ *   Total: ~115 literal class names. All explicit, all Tailwind-scannable.
+ *   Bundle CSS impact when fully exercised: ~3 KB gz (mostly the
+ *   responsive col-span set).
+ */
+export const gridVariants = tv({
+  base: '',
+
+  variants: {
+    // ─── CONTAINER role ────────────────────────────────────────────────
+    container: { true: 'grid' },
+
+    cols: {
+      1:  'grid-cols-1',
+      2:  'grid-cols-2',
+      3:  'grid-cols-3',
+      4:  'grid-cols-4',
+      6:  'grid-cols-6',
+      12: 'grid-cols-12',
+    },
+
+    autoFlow: {
+      row:        'grid-flow-row',
+      col:        'grid-flow-col',
+      dense:      'grid-flow-dense',
+      'row-dense':'grid-flow-row-dense',
+      'col-dense':'grid-flow-col-dense',
+    },
+
+    /*
+     * Container gap — token-scale step. Same set as Box/Stack so muscle
+     * memory carries across primitives.
+     */
+    spacing: {
+      0:    'gap-0',    '0.5': 'gap-0.5', 1:  'gap-1',  2:  'gap-2',  3:  'gap-3',
+      4:    'gap-4',    6:     'gap-6',   8:  'gap-8',  12: 'gap-12', 16: 'gap-16',
+      24:   'gap-24',
+    },
+    spacingX: {
+      0:    'gap-x-0',  '0.5': 'gap-x-0.5', 1:  'gap-x-1',  2:  'gap-x-2',  3:  'gap-x-3',
+      4:    'gap-x-4',  6:     'gap-x-6',   8:  'gap-x-8',  12: 'gap-x-12', 16: 'gap-x-16',
+      24:   'gap-x-24',
+    },
+    spacingY: {
+      0:    'gap-y-0',  '0.5': 'gap-y-0.5', 1:  'gap-y-1',  2:  'gap-y-2',  3:  'gap-y-3',
+      4:    'gap-y-4',  6:     'gap-y-6',   8:  'gap-y-8',  12: 'gap-y-12', 16: 'gap-y-16',
+      24:   'gap-y-24',
+    },
+
+    // ─── ITEM role — col-span at each breakpoint ──────────────────────
+    /*
+     * `xs` is the base breakpoint (no prefix) — Tailwind's mobile-first
+     * convention. `sm/md/lg/xl` cascade up from there.
+     *
+     * Special values:
+     *   • 'auto' → col-auto (content-sized)
+     *   • 'full' → col-span-full (span all columns regardless of count)
+     */
+    xs: {
+      1: 'col-span-1', 2: 'col-span-2', 3: 'col-span-3', 4: 'col-span-4',
+      5: 'col-span-5', 6: 'col-span-6', 7: 'col-span-7', 8: 'col-span-8',
+      9: 'col-span-9', 10: 'col-span-10', 11: 'col-span-11', 12: 'col-span-12',
+      auto: 'col-auto', full: 'col-span-full',
+    },
+    sm: {
+      1: 'sm:col-span-1', 2: 'sm:col-span-2', 3: 'sm:col-span-3', 4: 'sm:col-span-4',
+      5: 'sm:col-span-5', 6: 'sm:col-span-6', 7: 'sm:col-span-7', 8: 'sm:col-span-8',
+      9: 'sm:col-span-9', 10: 'sm:col-span-10', 11: 'sm:col-span-11', 12: 'sm:col-span-12',
+      auto: 'sm:col-auto', full: 'sm:col-span-full',
+    },
+    md: {
+      1: 'md:col-span-1', 2: 'md:col-span-2', 3: 'md:col-span-3', 4: 'md:col-span-4',
+      5: 'md:col-span-5', 6: 'md:col-span-6', 7: 'md:col-span-7', 8: 'md:col-span-8',
+      9: 'md:col-span-9', 10: 'md:col-span-10', 11: 'md:col-span-11', 12: 'md:col-span-12',
+      auto: 'md:col-auto', full: 'md:col-span-full',
+    },
+    lg: {
+      1: 'lg:col-span-1', 2: 'lg:col-span-2', 3: 'lg:col-span-3', 4: 'lg:col-span-4',
+      5: 'lg:col-span-5', 6: 'lg:col-span-6', 7: 'lg:col-span-7', 8: 'lg:col-span-8',
+      9: 'lg:col-span-9', 10: 'lg:col-span-10', 11: 'lg:col-span-11', 12: 'lg:col-span-12',
+      auto: 'lg:col-auto', full: 'lg:col-span-full',
+    },
+    xl: {
+      1: 'xl:col-span-1', 2: 'xl:col-span-2', 3: 'xl:col-span-3', 4: 'xl:col-span-4',
+      5: 'xl:col-span-5', 6: 'xl:col-span-6', 7: 'xl:col-span-7', 8: 'xl:col-span-8',
+      9: 'xl:col-span-9', 10: 'xl:col-span-10', 11: 'xl:col-span-11', 12: 'xl:col-span-12',
+      auto: 'xl:col-auto', full: 'xl:col-span-full',
+    },
+  },
+
+  /*
+   * No `defaultVariants`. The default semantics are role-dependent:
+   *   • container Grid defaults to cols=12 (set in Grid.tsx)
+   *   • item Grid defaults to xs="full" — full-width until a breakpoint
+   *     prop overrides (also set in Grid.tsx)
+   * Encoding these defaults at the TV level would emit them even when
+   * irrelevant (e.g. an item Grid never wants `grid grid-cols-12`).
+   */
+});
+
+export type GridVariants = VariantProps<typeof gridVariants>;

package/src/components/NumberField/NumberField.tsx

@@ -1,4 +1,4 @@
-import { useCallback, useContext, useEffect, useId, useRef } from 'react';
+import { useCallback, useContext, useEffect, useId, useRef, useState } from 'react';
 import { DashFormContext, useEngineVisibility } from '@dashforge/ui-core';
 import type { DashFormBridge, FieldRegistration } from '@dashforge/ui-core';
 import { useDashFieldMeta } from '@dashforge/forms';
@@ -98,6 +98,22 @@ export function NumberField(props: NumberFieldProps) {
   const accessState = useAccessState(access);
 
   const inputId = useId();
+
+  /*
+   * Local state for the STANDALONE UNCONTROLLED case (no bridge, no
+   * `value` prop, only `defaultValue`). Mirrors OTPField. Without this,
+   * `resolvedDisplayValue` would be a snapshot computed ONCE from
+   * `defaultValue` and the controlled `<input value={...}>` would
+   * snap user input back on every keystroke / stepper click — same
+   * trap that hit Checkbox + RadioGroup in this package.
+   *
+   * In form mode the bridge owns state. In standalone CONTROLLED mode
+   * (consumer passes `value`) the consumer owns state. Only this
+   * branch needs the local hook.
+   */
+  const [uncontrolledValue, setUncontrolledValue] = useState<string>(() =>
+    formatForDisplay(defaultValue)
+  );
   const helperId = `${inputId}-help`;
 
   // StrictMode-safe unregister-on-unmount
@@ -140,7 +156,7 @@ export function NumberField(props: NumberFieldProps) {
     resolvedDisplayValue =
       userValue !== undefined
         ? formatForDisplay(userValue)
-        : formatForDisplay(defaultValue);
+        : uncontrolledValue;
   }
 
   const writeToBridge = (parsed: number | null | undefined) => {
@@ -157,6 +173,13 @@ export function NumberField(props: NumberFieldProps) {
       // internal logic still sees the raw string change.
       void registration.onChange(e);
     }
+    // Standalone uncontrolled mode: mirror the raw input string so the
+    // controlled `<input value={...}>` reflects what the user typed.
+    // Partial states (e.g. "-", "1.") are kept verbatim — `parseFromInput`
+    // returns `undefined` for them so `writeToBridge` is a no-op above.
+    if (!isFormMode && userValue === undefined) {
+      setUncontrolledValue(e.target.value);
+    }
     userOnChange?.(e);
   };
 
@@ -176,6 +199,11 @@ export function NumberField(props: NumberFieldProps) {
     if (typeof min === 'number') next = Math.max(min, next);
     if (typeof max === 'number') next = Math.min(max, next);
     writeToBridge(next);
+    // Standalone uncontrolled: also persist the new value to local
+    // state so the visible display tracks the stepper click.
+    if (!isFormMode && userValue === undefined) {
+      setUncontrolledValue(formatForDisplay(next));
+    }
   };
 
   const canIncrement =

package/src/components/RadioGroup/RadioGroup.tsx

@@ -200,9 +200,31 @@ export function RadioGroup(props: RadioGroupProps) {
         </div>
       )}
 
+      {/*
+       * Radix RadioGroup mode discrimination — mirrors the same fix
+       * applied to <Checkbox>:
+       *
+       *   - Form mode (bridge.register present): controlled — `value`
+       *     comes from the reactive bridge snapshot, `handleValueChange`
+       *     writes back through bridge.setValue.
+       *   - Standalone controlled (consumer passes `value`): controlled —
+       *     consumer owns state, `handleValueChange` forwards via
+       *     `onValueChange`.
+       *   - Standalone uncontrolled (only `defaultValue`): UNCONTROLLED —
+       *     Radix owns the state. Previously this code passed
+       *     `value={resolvedValue}` in this branch too, putting Radix
+       *     in controlled mode with a stale snapshot that never updated,
+       *     so user clicks fired Radix's onValueChange but the controlled
+       *     prop never changed and the selection snapped right back.
+       *
+       * Picking exactly one of `{ value, ... }` or `{ defaultValue, ... }`
+       * lets Radix track its own state correctly when nobody else can.
+       */}
       <RadixRadioGroup.Root
         name={name}
-        value={resolvedValue}
+        {...(isFormMode || explicitValue !== undefined
+          ? { value: resolvedValue }
+          : { defaultValue: defaultValue ?? undefined })}
         onValueChange={handleValueChange}
         onBlur={handleBlur}
         disabled={groupEffectiveDisabled}

package/src/components/Stack/Stack.test.tsx

@@ -0,0 +1,309 @@
+// @vitest-environment jsdom
+import { describe, it, expect } from 'vitest';
+import { render } from '@testing-library/react';
+import { Stack } from './Stack.js';
+
+describe('<Stack>', () => {
+  // ─── Default rendering ──────────────────────────────────────────────
+  describe('default rendering', () => {
+    it('renders a <div> by default', () => {
+      const { container } = render(<Stack>x</Stack>);
+      expect(container.firstElementChild?.tagName).toBe('DIV');
+    });
+
+    it('has flex + flex-col by default', () => {
+      const { container } = render(<Stack>x</Stack>);
+      const cls = container.firstElementChild?.className ?? '';
+      expect(cls).toContain('flex');
+      expect(cls).toContain('flex-col');
+    });
+  });
+
+  // ─── Direction ──────────────────────────────────────────────────────
+  describe('direction', () => {
+    it('row', () => {
+      const { container } = render(<Stack direction="row">x</Stack>);
+      expect(container.firstElementChild?.className).toContain('flex-row');
+    });
+
+    it('row-reverse', () => {
+      const { container } = render(<Stack direction="row-reverse">x</Stack>);
+      expect(container.firstElementChild?.className).toContain('flex-row-reverse');
+    });
+  });
+
+  // ─── Align + justify ────────────────────────────────────────────────
+  describe('align + justify', () => {
+    it('align="center" + justify="between"', () => {
+      const { container } = render(
+        <Stack align="center" justify="between">x</Stack>,
+      );
+      const cls = container.firstElementChild?.className ?? '';
+      expect(cls).toContain('items-center');
+      expect(cls).toContain('justify-between');
+    });
+
+    it('align="baseline"', () => {
+      const { container } = render(<Stack align="baseline">x</Stack>);
+      expect(container.firstElementChild?.className).toContain('items-baseline');
+    });
+  });
+
+  // ─── Gap + wrap + sizing ────────────────────────────────────────────
+  describe('gap + wrap + sizing', () => {
+    it('gap={4} emits gap-4', () => {
+      const { container } = render(<Stack gap={4}>x</Stack>);
+      expect(container.firstElementChild?.className).toContain('gap-4');
+    });
+
+    it('gap={"0.5"} emits gap-0.5', () => {
+      const { container } = render(<Stack gap="0.5">x</Stack>);
+      expect(container.firstElementChild?.className).toContain('gap-0.5');
+    });
+
+    it('wrap emits flex-wrap', () => {
+      const { container } = render(<Stack wrap>x</Stack>);
+      expect(container.firstElementChild?.className).toContain('flex-wrap');
+    });
+
+    it('fullWidth + fullHeight', () => {
+      const { container } = render(<Stack fullWidth fullHeight>x</Stack>);
+      const cls = container.firstElementChild?.className ?? '';
+      expect(cls).toContain('w-full');
+      expect(cls).toContain('h-full');
+    });
+  });
+
+  // ─── Divider ─────────────────────────────────────────────────────────
+  describe('divider', () => {
+    it('inserts N-1 dividers between N children', () => {
+      const { container } = render(
+        <Stack divider={<hr data-testid="div" />}>
+          <span>a</span>
+          <span>b</span>
+          <span>c</span>
+        </Stack>,
+      );
+      // 3 children + 2 dividers
+      expect(container.firstElementChild?.children.length).toBe(5);
+      const dividers = container.querySelectorAll('[data-testid="div"]');
+      expect(dividers.length).toBe(2);
+    });
+
+    it('does NOT insert dividers when there is only one child', () => {
+      const { container } = render(
+        <Stack divider={<hr data-testid="div" />}>
+          <span>only</span>
+        </Stack>,
+      );
+      expect(container.firstElementChild?.children.length).toBe(1);
+      expect(container.querySelectorAll('[data-testid="div"]').length).toBe(0);
+    });
+
+    it('treats a Fragment as a single child for divider boundary counting', () => {
+      const { container } = render(
+        <Stack divider={<hr data-testid="div" />}>
+          <>
+            <span>a</span>
+            <span>b</span>
+          </>
+          <span>c</span>
+        </Stack>,
+      );
+      // React.Children.toArray does NOT recursively flatten fragments — it
+      // treats them as opaque single children. Documented behaviour: 2
+      // top-level children → 1 divider between them. If you need a divider
+      // BETWEEN the items inside the fragment, hoist them out of it.
+      expect(container.querySelectorAll('[data-testid="div"]').length).toBe(1);
+    });
+
+    it('renders string/number divider correctly', () => {
+      const { container } = render(
+        <Stack divider=" · ">
+          <span>a</span>
+          <span>b</span>
+          <span>c</span>
+        </Stack>,
+      );
+      expect(container.firstElementChild?.textContent).toBe('a · b · c');
+    });
+
+    it('asChild silently ignores divider', () => {
+      const { container } = render(
+        <Stack asChild divider={<hr data-testid="div" />}>
+          <nav>
+            <a href="#">link</a>
+          </nav>
+        </Stack>,
+      );
+      // Slot wraps a single child — divider has nowhere to go
+      expect(container.firstElementChild?.tagName).toBe('NAV');
+      expect(container.querySelectorAll('[data-testid="div"]').length).toBe(0);
+    });
+  });
+
+  // ─── Override + sx ──────────────────────────────────────────────────
+  describe('override', () => {
+    it('sx wins over variant defaults', () => {
+      const { container } = render(
+        <Stack direction="row" sx="flex-col">x</Stack>,
+      );
+      const cls = container.firstElementChild?.className ?? '';
+      expect(cls).toContain('flex-col');
+      expect(cls).not.toContain('flex-row');
+    });
+
+    it('sx can add utilities Stack does not expose (overflow)', () => {
+      const { container } = render(<Stack sx="overflow-x-auto">x</Stack>);
+      expect(container.firstElementChild?.className).toContain('overflow-x-auto');
+    });
+  });
+
+  // ─── Polymorphism ───────────────────────────────────────────────────
+  describe('polymorphism', () => {
+    it('as="nav" renders a <nav>', () => {
+      const { container } = render(<Stack as="nav">x</Stack>);
+      expect(container.firstElementChild?.tagName).toBe('NAV');
+    });
+
+    it('asChild wins over as', () => {
+      const { container } = render(
+        <Stack as="nav" asChild>
+          <header>x</header>
+        </Stack>,
+      );
+      expect(container.firstElementChild?.tagName).toBe('HEADER');
+    });
+  });
+
+  // ─── Pass-through ────────────────────────────────────────────────────
+  it('forwards data-* + aria-*', () => {
+    const { container } = render(
+      <Stack data-testid="s" aria-label="settings">x</Stack>,
+    );
+    const el = container.firstElementChild;
+    expect(el?.getAttribute('data-testid')).toBe('s');
+    expect(el?.getAttribute('aria-label')).toBe('settings');
+  });
+
+  // ─── F11-bis edge cases: divider with array / null / mixed children ─
+  describe('divider edge cases', () => {
+    it('children passed as an array still gets N-1 dividers', () => {
+      // Children.toArray handles arrays the same as iterated siblings —
+      // the divider count is items.length - 1 regardless of how the
+      // children were passed in.
+      const items = ['a', 'b', 'c', 'd'];
+      const { container } = render(
+        <Stack divider={<hr data-testid="div" />}>
+          {items.map((t) => <span key={t}>{t}</span>)}
+        </Stack>,
+      );
+      expect(container.querySelectorAll('[data-testid="div"]').length).toBe(3);
+    });
+
+    it('null children are stripped before divider insertion', () => {
+      // React's Children.toArray filters out null/undefined/false before
+      // returning the flat array — so a conditional child collapses to
+      // nothing and dividers are sized to the remaining set.
+      const showB = false;
+      const { container } = render(
+        <Stack divider={<hr data-testid="div" />}>
+          <span>a</span>
+          {showB && <span>b</span>}
+          <span>c</span>
+        </Stack>,
+      );
+      // After stripping `false`: 2 effective children → 1 divider
+      expect(container.querySelectorAll('[data-testid="div"]').length).toBe(1);
+    });
+
+    it('mixed text + element children — divider between EVERY pair', () => {
+      const { container } = render(
+        <Stack divider={<hr data-testid="div" />}>
+          {'plain string'}
+          <span>element child</span>
+          {42}
+          <span>last</span>
+        </Stack>,
+      );
+      // 4 effective children (Children.toArray wraps primitives) → 3 dividers
+      expect(container.querySelectorAll('[data-testid="div"]').length).toBe(3);
+    });
+
+    it('nested Stack inside Stack with divider — inner Stack counts as 1 child', () => {
+      const { container } = render(
+        <Stack gap={2} divider={<hr data-testid="outer-div" />}>
+          <span>top</span>
+          <Stack gap={1} direction="row">
+            <span>nested-a</span>
+            <span>nested-b</span>
+          </Stack>
+          <span>bottom</span>
+        </Stack>,
+      );
+      // Outer has 3 effective children → 2 outer dividers
+      expect(container.querySelectorAll('[data-testid="outer-div"]').length).toBe(2);
+    });
+
+    it('divider key is stable across re-renders (no key warning)', () => {
+      // Re-rendering with the same children + divider shouldn't produce
+      // React key warnings. We assert nothing throws + the structure is
+      // identical to a single render.
+      const { container, rerender } = render(
+        <Stack divider={<hr data-testid="d" />}>
+          <span>a</span>
+          <span>b</span>
+        </Stack>,
+      );
+      const firstRender = container.innerHTML;
+      rerender(
+        <Stack divider={<hr data-testid="d" />}>
+          <span>a</span>
+          <span>b</span>
+        </Stack>,
+      );
+      expect(container.innerHTML).toBe(firstRender);
+    });
+  });
+
+  // ─── F11-bis edge cases: gap value coverage ─────────────────────────
+  describe('gap — every token step', () => {
+    const GAPS = [0, '0.5', 1, 2, 3, 4, 6, 8, 12, 16, 24] as const;
+    it.each(GAPS)('gap=%s emits gap-%s', (g) => {
+      const { container } = render(<Stack gap={g}>x</Stack>);
+      expect(container.firstElementChild?.className).toContain(`gap-${g}`);
+    });
+  });
+
+  // ─── F11-bis edge cases: align / justify all values ─────────────────
+  describe('align + justify — all valid values', () => {
+    const ALIGNS = ['start', 'center', 'end', 'stretch', 'baseline'] as const;
+    const JUSTIFIES = ['start', 'center', 'end', 'between', 'around', 'evenly'] as const;
+
+    it.each(ALIGNS)('align="%s"', (v) => {
+      const { container } = render(<Stack align={v}>x</Stack>);
+      expect(container.firstElementChild?.className).toContain(`items-${v}`);
+    });
+
+    it.each(JUSTIFIES)('justify="%s"', (v) => {
+      const { container } = render(<Stack justify={v}>x</Stack>);
+      expect(container.firstElementChild?.className).toContain(`justify-${v}`);
+    });
+  });
+
+  // ─── F11-bis edge cases: empty Stack ────────────────────────────────
+  describe('empty Stack', () => {
+    it('renders an empty div with flex classes', () => {
+      const { container } = render(<Stack gap={4} />);
+      const el = container.firstElementChild;
+      expect(el?.children.length).toBe(0);
+      expect(el?.className).toContain('flex');
+      expect(el?.className).toContain('gap-4');
+    });
+
+    it('empty Stack with divider does NOT render the divider', () => {
+      const { container } = render(<Stack divider={<hr data-testid="d" />} />);
+      expect(container.querySelectorAll('[data-testid="d"]').length).toBe(0);
+    });
+  });
+});