@12-apps/ui 1.0.0 → 1.3.0

package/src/components/layout/CardGrid/CardGrid.md

@@ -0,0 +1,96 @@
+# CardGrid Component
+
+## Overview
+
+`CardGrid` is a shared grid container for card layouts. It arranges its children into responsive columns using CSS `grid` + `auto-fill`, so the column count adapts to the container width without media queries or JavaScript. It exposes two layout **variants** that differ only in how leftover row space is handled.
+
+Ported from the tabwoah card grid — the `"fixed"` variant is the original behavior verbatim; the one adaptation is that this app has no Tailwind, so the container's `display: grid`, gap, and bottom padding live in `style` instead of utility classes.
+
+## Features
+
+- **Two variants**: `fixed` (steady card width, even gutters) and `fluid` (cards stretch to fill)
+- **Responsive by default**: `auto-fill` recomputes the column count as the container resizes — 2-up on a phone, more columns as width grows
+- **Single-card friendly**: a lone card stays left-aligned at one track's width, never stretched edge to edge
+- **No JS / no media queries**: pure CSS grid
+- **Ref + testid passthrough**: `containerRef` (e.g. for row-clipping) and `gridTestId`
+
+## Variants
+
+| Variant   | Layout                        | Wraps?            | Card sizing                                  |
+| --------- | ----------------------------------- | ----------------- | -------------------------------------------- |
+| `fixed`   | `repeat(auto-fill, {cardWidth}px)` + `space-around` | wraps | Cards stay exactly `cardWidth`; column count changes |
+| `fluid`   | `repeat(auto-fill, minmax({cardWidth}px, 1fr))` | wraps | Cards grow to fill the row; `cardWidth` is the minimum |
+| `scroll`  | one row, `grid-auto-flow: column` + `overflow-x: auto`, `grid-auto-columns: min({maxCardWidth}px, calc((100% - 60px) / 2))` | no — scrolls sideways | Cards are sized from the container so 2 whole cards + a 28px peek of the third always fit, capped at `maxCardWidth` |
+
+- Use **`fixed`** when you want cards to keep a constant size and the row to breathe with even spacing (the tabwoah default).
+- Use **`fluid`** when you want cards to grow and the grid to always use the full width (e.g. a product menu that should fill edge to edge).
+- Use **`scroll`** when you want a swipeable rail — a single horizontally-scrolling row of fluid cards (e.g. a "highlights"/destaque strip). Two cards plus a peek of the third show on a phone; more appear as the viewport grows, and the rest are revealed by scrolling.
+
+**The peek is a guarantee, not a side effect.** On a phone the rail must never resolve to exactly two cards flush with the edge — that reads as "these are all the products". The track width is therefore computed _from the container_ (`(100% - 2 gaps - 28px peek) / 2`) rather than clamped to a minimum card width: a minimum is precisely what would swallow the peek on a narrow screen. `maxCardWidth` still caps the track, so wide viewports fit more cards instead of inflating them. When the rail holds two cards or fewer there is nothing to scroll to, so no peek is reserved and the cards divide the row evenly.
+
+## Usage
+
+### Fluid grid (cards grow to fill)
+
+```tsx
+import { CardGrid } from '@12-apps/ui/layout/CardGrid';
+
+<CardGrid variant="fluid" cardWidth={165} gridTestId="menu-grid">
+  {items.map((item) => (
+    <ProductCard key={item.id} item={item} />
+  ))}
+</CardGrid>;
+```
+
+At ~396px of content two 165px columns fit and each stretches to ~190px; on a
+wide screen the columns multiply and keep filling the row.
+
+### Fixed grid (steady width, even gutters)
+
+```tsx
+<CardGrid variant="fixed" cardWidth={230}>
+  {cards}
+</CardGrid>
+```
+
+Every card is exactly 230px; surplus width becomes even gutters between columns.
+
+### Scroll rail (fluid cards, horizontal scroll)
+
+```tsx
+<CardGrid variant="scroll" cardWidth={165} maxCardWidth={264}>
+  {cards}
+</CardGrid>
+```
+
+A single row that scrolls sideways. Each card is as wide as it can be while two
+whole cards plus a 28px peek of the third still fit — e.g. ~142px in a 348px
+container — capped at 264px on a wide viewport.
+
+### With a container ref (row clipping)
+
+```tsx
+const { containerRef, maxHeight } = useMaxRowsHeight(2, items.length);
+
+<CardGrid cardWidth={230} containerRef={containerRef} className="clipped">
+  {cards}
+</CardGrid>;
+```
+
+## Props
+
+| Prop         | Type                    | Default   | Description                                                                                       |
+| ------------ | ----------------------- | --------- | ------------------------------------------------------------------------------------------------- |
+| cardWidth    | number                  | -         | `fixed`: the exact column width in px. `fluid`: the minimum column width (columns grow from here). `scroll`: only seeds the default `maxCardWidth` — scroll tracks have no minimum. |
+| maxCardWidth | number                  | 1.6×cardWidth | `scroll` only: the upper bound of the fluid card width.                                     |
+| variant      | 'fixed' \| 'fluid' \| 'scroll' | 'fixed'   | Layout behavior (see [Variants](#variants)).                                                |
+| className    | string                  | -         | Extra classes appended to the grid container.                                                     |
+| gridTestId   | string                  | -         | `data-testid` for the grid container.                                                             |
+| containerRef | Ref\<HTMLDivElement\>   | -         | Ref forwarded to the grid container (e.g. for max-rows height clipping).                           |
+| children     | ReactNode               | -         | The cards to lay out.                                                                              |
+
+## Notes
+
+- The children control their own width: give each card `width: 100%` so it fills its grid track in both variants.
+- Card **height** equalizes per row automatically when tracks are equal width (equal columns ⇒ equal-height cells).
+- In tabwoah the card size is driven by a zoom slider (`useGridLayout`) that feeds a larger `cardWidth`; that control was not ported here — pass `cardWidth` directly (a fixed number or a responsive one) instead.

package/src/components/layout/CardGrid/CardGrid.tsx

@@ -0,0 +1,140 @@
+import { Children, type CSSProperties, type ReactNode, type Ref } from "react";
+
+import { cn } from "../../../utils/cn";
+
+/**
+ * How the grid turns surplus row space into layout:
+ *
+ * - `"fixed"` — every column is exactly `cardWidth` px; leftover row space is
+ *   spread as even gutters (`justify-content: space-around`). Cards never resize;
+ *   the column count changes with the viewport. This is the original tabwoah
+ *   card-grid behavior.
+ * - `"fluid"` — every column is *at least* `cardWidth` px and stretches (`1fr`)
+ *   to fill the row, so cards grow to use the whole width. A lone card stays
+ *   left-aligned at a single track's width rather than stretching edge to edge.
+ * - `"scroll"` — a single row that scrolls horizontally, with fluid-width cards
+ *   sized from the container so that exactly {@link SCROLL_VISIBLE_CARDS} cards
+ *   plus a {@link SCROLL_PEEK_WIDTH}px sliver of the next one fit on screen (up
+ *   to `maxCardWidth`, past which more cards simply fit). The sliver is the
+ *   point: it makes the rail visibly continue past the fold, so the row reads as
+ *   swipeable instead of as a finished pair of cards. Wrapping is off; the row
+ *   overflows on the x and scroll-snaps to each card's start so a swipe lands on
+ *   a clean card boundary.
+ */
+export type CardGridVariant = "fixed" | "fluid" | "scroll";
+
+/** The grid gap, in px — mirrors the `gap: 1rem` below, for the scroll math. */
+const GRID_GAP = 16;
+
+/** `scroll`: how many WHOLE cards the rail commits to showing at once. */
+const SCROLL_VISIBLE_CARDS = 2;
+
+/**
+ * `scroll`: px of the next card left visible past the last whole one — the
+ * "there's more, swipe" hint. Wide enough to read as a clipped card (rounded
+ * edge + a slice of its photo) rather than as a rendering glitch.
+ */
+const SCROLL_PEEK_WIDTH = 28;
+
+/**
+ * The `scroll` track width: the widest a card can be while the container still
+ * shows `SCROLL_VISIBLE_CARDS` of them plus the peek — or, when there is nothing
+ * to scroll to, while the cards still divide the row evenly. Capped at `max` so
+ * a desktop-width rail packs in more cards instead of inflating them.
+ *
+ * The container (`100%`) has to cover, in the overflow case: N cards, the N gaps
+ * that follow them (one between each pair, one before the peeked card), and the
+ * peek. With no overflow there are only N-1 gaps and no peek.
+ */
+function scrollTrackWidth(count: number, max: number): string {
+  const tracks = Math.max(1, Math.min(count, SCROLL_VISIBLE_CARDS));
+  const overflows = count > tracks;
+  const gaps = overflows ? tracks : tracks - 1;
+  const reserved = gaps * GRID_GAP + (overflows ? SCROLL_PEEK_WIDTH : 0);
+  return `min(${max}px, calc((100% - ${reserved}px) / ${tracks}))`;
+}
+
+interface CardGridProps {
+  /**
+   * `"fixed"`: the exact column width in px. `"fluid"`: the minimum column width
+   * (columns grow from here). `"scroll"`: only seeds the default `maxCardWidth`
+   * — a scroll track has no minimum, because a minimum is exactly what would
+   * break the "two cards plus a peek" promise on a narrow phone.
+   */
+  cardWidth: number;
+  /**
+   * `"scroll"` only: the maximum fluid card width in px. Defaults to
+   * `1.6 × cardWidth`.
+   */
+  maxCardWidth?: number;
+  /** Layout behavior — see {@link CardGridVariant}. Defaults to `"fixed"`. */
+  variant?: CardGridVariant;
+  /** Additional classes appended to the default grid container */
+  className?: string;
+  /** `data-testid` for the grid container */
+  gridTestId?: string;
+  /** Ref forwarded to the grid container (used by `useMaxRowsHeight` clipping). */
+  containerRef?: Ref<HTMLDivElement>;
+  children: ReactNode;
+}
+
+/**
+ * Shared grid container for card layouts. Renders responsive columns via CSS
+ * grid, in one of three variants (see {@link CardGridVariant}).
+ *
+ * Ported from the tabwoah card grid (the `"fixed"` variant is verbatim). The one
+ * adaptation: that app is Tailwind (`className="grid gap-4 pb-0.5"`); this one
+ * has no Tailwind, so those three utilities (display:grid, gap 1rem,
+ * padding-bottom 2px) live in `style`.
+ */
+export function CardGrid({
+  cardWidth,
+  maxCardWidth,
+  variant = "fixed",
+  className,
+  gridTestId,
+  containerRef,
+  children,
+}: CardGridProps) {
+  const style: CSSProperties = {
+    display: "grid",
+    gap: "1rem",
+    paddingBottom: "2px",
+  };
+
+  if (variant === "scroll") {
+    const max = maxCardWidth ?? Math.round(cardWidth * 1.6);
+    // One row, laid out as implicit columns, that scrolls sideways. Each column
+    // is derived from the container so two whole cards plus a peek of the third
+    // always fit (see `scrollTrackWidth`). Scroll-snap makes a swipe settle on a
+    // card boundary instead of drifting mid-card.
+    style.gridAutoFlow = "column";
+    style.gridAutoColumns = scrollTrackWidth(Children.count(children), max);
+    style.overflowX = "auto";
+    style.overflowY = "hidden";
+    style.scrollSnapType = "x mandatory";
+  } else if (variant === "fluid") {
+    style.gridTemplateColumns = `repeat(auto-fill, minmax(${cardWidth}px, 1fr))`;
+  } else {
+    style.gridTemplateColumns = `repeat(auto-fill, ${cardWidth}px)`;
+    // `space-around` only distributes leftover width in the fixed variant; the
+    // fluid variant consumes it via `1fr` and scroll overflows instead.
+    style.justifyContent = "space-around";
+  }
+
+  // In the scroll variant each card is a snap target, so a swipe aligns to its
+  // start. The snap-align sits on a wrapper (the grid item) so callers' children
+  // stay untouched; the other variants render children directly.
+  const content =
+    variant === "scroll"
+      ? Children.map(children, (child) => (
+          <div style={{ scrollSnapAlign: "start" }}>{child}</div>
+        ))
+      : children;
+
+  return (
+    <div ref={containerRef} className={cn(className)} style={style} data-testid={gridTestId}>
+      {content}
+    </div>
+  );
+}

package/src/components/layout/CardGrid/__tests__/CardGrid.test.tsx

@@ -0,0 +1,92 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+
+import { CardGrid } from "../CardGrid";
+
+/** The rendered grid container's inline `grid-auto-columns` track sizing. */
+function trackOf(children: number): string {
+  const { unmount } = render(
+    <CardGrid variant="scroll" cardWidth={165} maxCardWidth={190} gridTestId="rail">
+      {Array.from({ length: children }, (_, i) => (
+        <div key={i}>card {i}</div>
+      ))}
+    </CardGrid>,
+  );
+  const track = screen.getByTestId("rail").style.gridAutoColumns;
+  unmount();
+  return track;
+}
+
+describe("CardGrid scroll variant", () => {
+  it("sizes tracks so two cards plus a peek of the third always fit", () => {
+    // 2 cards + the 2 gaps that follow them + the 28px peek = the container.
+    expect(trackOf(3)).toBe("min(190px, calc((100% - 60px) / 2))");
+  });
+
+  it("keeps the peek at every rail length past the fold", () => {
+    expect(trackOf(7)).toBe(trackOf(3));
+  });
+
+  it("reserves no peek when there is nothing to scroll to", () => {
+    // Two cards: no overflow, so no "there's more" hint to make room for —
+    // they divide the row across the single gap between them.
+    expect(trackOf(2)).toBe("min(190px, calc((100% - 16px) / 2))");
+    expect(trackOf(1)).toBe("min(190px, calc((100% - 0px) / 1))");
+  });
+
+  it("never floors the track at cardWidth — a floor would swallow the peek", () => {
+    // The narrow-phone guarantee only holds if the track can shrink below the
+    // nominal card width; a `min-width` is exactly what broke it before.
+    expect(trackOf(5)).not.toContain("165px");
+  });
+
+  it("defaults maxCardWidth to 1.6 × cardWidth", () => {
+    render(
+      <CardGrid variant="scroll" cardWidth={100} gridTestId="default-max">
+        <div>a</div>
+        <div>b</div>
+        <div>c</div>
+      </CardGrid>,
+    );
+    expect(screen.getByTestId("default-max").style.gridAutoColumns).toContain("160px");
+  });
+
+  it("scrolls horizontally and snaps each card to the rail start", () => {
+    render(
+      <CardGrid variant="scroll" cardWidth={165} gridTestId="snap">
+        <div>a</div>
+        <div>b</div>
+        <div>c</div>
+      </CardGrid>,
+    );
+    const rail = screen.getByTestId("snap");
+    expect(rail.style.overflowX).toBe("auto");
+    expect(rail.style.scrollSnapType).toBe("x mandatory");
+    expect(rail.children).toHaveLength(3);
+    for (const child of rail.children) {
+      expect((child as HTMLElement).style.scrollSnapAlign).toBe("start");
+    }
+  });
+});
+
+describe("CardGrid wrapping variants", () => {
+  it("leaves the fluid and fixed track math untouched", () => {
+    render(
+      <CardGrid variant="fluid" cardWidth={165} gridTestId="fluid">
+        <div>a</div>
+      </CardGrid>,
+    );
+    render(
+      <CardGrid variant="fixed" cardWidth={230} gridTestId="fixed">
+        <div>a</div>
+      </CardGrid>,
+    );
+    expect(screen.getByTestId("fluid").style.gridTemplateColumns).toBe(
+      "repeat(auto-fill, minmax(165px, 1fr))",
+    );
+    expect(screen.getByTestId("fixed").style.gridTemplateColumns).toBe(
+      "repeat(auto-fill, 230px)",
+    );
+    expect(screen.getByTestId("fixed").style.justifyContent).toBe("space-around");
+  });
+});

package/src/components/layout/CardGrid/index.ts

@@ -0,0 +1,2 @@
+export { CardGrid } from "./CardGrid";
+export type { CardGridVariant } from "./CardGrid";

package/src/components/layout/Collapsible/Collapsible.helpers.ts

@@ -0,0 +1,83 @@
+import type { Theme } from '@mui/material';
+
+import type { CollapsibleVariant } from './Collapsible.types';
+
+/**
+ * `smooth` and `default` share their timing; only `spring` differs, stretching
+ * the duration and overshooting past the target before settling.
+ */
+export const transitionSettings = (
+  theme: Theme,
+  variant: CollapsibleVariant,
+  duration: number,
+  easing?: string,
+): { duration: number; easing: string } => {
+  if (variant === 'spring') {
+    return {
+      duration: duration * 1.2,
+      easing: easing || 'cubic-bezier(0.34, 1.56, 0.64, 1)',
+    };
+  }
+
+  return { duration, easing: easing || theme.transitions.easing.easeInOut };
+};
+
+interface RegionState {
+  open: boolean;
+  disabled: boolean;
+  dataTestId?: string;
+}
+
+/**
+ * Shared by both implementations: a disabled collapsible reads as collapsed to
+ * assistive technology whatever its `open` prop says, because it cannot be
+ * operated to see the rest.
+ */
+export const regionAttrs = ({ open, disabled, dataTestId }: RegionState) => ({
+  'data-disabled': disabled,
+  'data-testid': dataTestId,
+  role: 'region',
+  'aria-expanded': open && !disabled,
+  'aria-hidden': disabled || !open,
+});
+
+export const dimmedStyles = (disabled: boolean) => ({
+  opacity: disabled ? 0.6 : 1,
+  pointerEvents: (disabled ? 'none' : 'auto') as 'none' | 'auto',
+});
+
+export const triggerStyles = (
+  theme: Theme,
+  { disabled, expanded }: { disabled: boolean; expanded: boolean },
+) => {
+  const restingBackground = expanded ? theme.palette.action.selected : 'transparent';
+
+  return {
+    width: '100%',
+    padding: theme.spacing(1, 2),
+    border: 'none',
+    backgroundColor: restingBackground,
+    cursor: disabled ? 'not-allowed' : 'pointer',
+    display: 'flex',
+    alignItems: 'center',
+    justifyContent: 'space-between',
+    transition: theme.transitions.create(['background-color', 'opacity'], {
+      duration: theme.transitions.duration.short,
+    }),
+    opacity: disabled ? 0.6 : 1,
+    '&:hover': {
+      backgroundColor: disabled
+        ? 'transparent'
+        : expanded
+          ? theme.palette.action.selected
+          : theme.palette.action.hover,
+    },
+    '&:focus': {
+      outline: `2px solid ${theme.palette.primary.main}`,
+      outlineOffset: 2,
+    },
+    '&:active': {
+      backgroundColor: disabled ? 'transparent' : theme.palette.action.focus,
+    },
+  };
+};

package/src/components/layout/Collapsible/Collapsible.test.stories.tsx

@@ -1,4 +1,5 @@
-import { ExpandLess,ExpandMore } from '@mui/icons-material';
+import ExpandLess from '@mui/icons-material/ExpandLess';
+import ExpandMore from '@mui/icons-material/ExpandMore';
 import { Box,Button, Card, Stack, Typography } from '@mui/material';
 import type { Meta, StoryObj } from '@storybook/react-vite';
 import { useState } from 'react';
@@ -105,8 +106,11 @@ export const KeyboardNavigation: Story = {
 
     await step('Focus trigger with Tab', async () => {
       const trigger = canvas.getByTestId('keyboard-trigger');
-      trigger.focus();
-      await expect(trigger).toHaveFocus();
+      // Tab rather than .focus(): the trigger is the only focusable node in this
+      // story, so this proves it is reachable by keyboard — which is what the
+      // step claims to check. Asserting that .focus() focused only tests the DOM.
+      await userEvent.tab();
+      await waitFor(() => expect(trigger).toHaveFocus());
     });
 
     await step('Verify keyboard accessibility', async () => {