@bearmenu/ui 0.8.4 → 0.8.7

package/src/components/coverflow.stories.tsx

@@ -0,0 +1,240 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { useState } from "react";
+import { Flame } from "lucide-react";
+import { expect, within } from "storybook/test";
+import { Coverflow, type CoverflowItem } from "./coverflow";
+
+const ITEMS: CoverflowItem[] = [
+  {
+    id: "warehouse-rave",
+    title: "Warehouse Rave",
+    meta: "Fri 4 · 90 going",
+    badge: (
+      <>
+        <Flame className="h-3 w-3" aria-hidden />
+        Busiest
+      </>
+    ),
+  },
+  {
+    id: "jazz-rooftop",
+    title: "Jazz on the Rooftop",
+    meta: "Sat 5 · 64 going",
+    isFree: true,
+  },
+  {
+    id: "open-mic",
+    title: "Open Mic Night",
+    meta: "Sun 6 · 21 going",
+  },
+  ...Array.from({ length: 4 }, (_, index) => ({
+    id: `side-event-${index + 1}`,
+    title: `Side event ${index + 1}`,
+    meta: `Event ${index + 1} details`,
+  })),
+];
+
+// Explicitly annotated rather than `satisfies`: the meta-level decorator makes
+// the inferred type reference storybook's internal CSF module, which tsc cannot
+// name portably (TS2742).
+const meta: Meta<typeof Coverflow> = {
+  title: "Events/Coverflow",
+  component: Coverflow,
+  tags: ["autodocs"],
+  args: {
+    items: ITEMS,
+    activeIndex: 0,
+    freeLabel: "Free",
+    prevLabel: "Previous event",
+    nextLabel: "Next event",
+    positionLabel: "1 of 7",
+  },
+  decorators: [
+    (Story) => (
+      <div className="max-w-[520px]">
+        <Story />
+      </div>
+    ),
+  ],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "The busiest-events browser: a 3D perspective **ring** with a large lead poster flanked by desaturating, shrinking side posters. A card's slot is the *signed shortest way round the list*, not `index - activeIndex`, so both flanks stay full at every index — at `activeIndex: 0` the last item sits immediately to the left of the lead rather than leaving that half of the stage empty — and prev/next carry on past either end, reporting the wrapped index through `onActiveIndexChange`. Only `|offset| <= 3` is mounted, so a long list paints seven posters, not all of them. Exactly one card per step crosses the ring's seam; it renders without its transition classes for that one commit so it teleports round the back instantly instead of sliding across the face of the stage. The lane drifts a few pixels back and forth, pauses off-screen, and stops outright (along with the position transition) under `prefers-reduced-motion`. Every rendered card is a real, focusable control — the injected link when it carries an `href`, otherwise a `<button>` — so a keyboard or screen-reader user can jump straight to any of them. The prev/next arrows float over the stage, vertically centred on the poster row, and are not rendered at all for a single item, where they would be inert.",
+      },
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof Coverflow>;
+
+export const Default: Story = {};
+
+/**
+ * The ring at its old worst case. `activeIndex: 0` used to leave the entire
+ * left half of the stage empty with three cards stacked to the right; now item
+ * 6 renders at offset −1, item 5 at −2 and item 4 at −3, so both flanks are
+ * full. Step backwards from here and the index reported to the parent is 6,
+ * not a clamp at 0.
+ */
+export const RingAtIndexZero: Story = {
+  render: (args) => {
+    function RingCoverflow() {
+      const [activeIndex, setActiveIndex] = useState(0);
+      return (
+        <Coverflow
+          {...args}
+          activeIndex={activeIndex}
+          positionLabel={`${activeIndex + 1} of ${args.items!.length}`}
+          onActiveIndexChange={setActiveIndex}
+        />
+      );
+    }
+    return <RingCoverflow />;
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Start at 0 and press *Previous*: the ring turns to item 6 instead of refusing. One card per step comes round the back — it teleports at the deepest tier, off-stage and behind the depth stack, rather than tweening across the middle.",
+      },
+    },
+  },
+};
+
+export const Free: Story = {
+  args: { activeIndex: 1, positionLabel: "2 of 7" },
+};
+
+/**
+ * Three items: the ring is smaller than the visible window, so every item is
+ * on stage at once — one on each flank rather than three.
+ */
+export const FewSidePosters: Story = {
+  args: { items: ITEMS.slice(0, 3), positionLabel: "1 of 3" },
+};
+
+/**
+ * Two items. The shortest path ties at `n / 2`, and the tie always resolves to
+ * the positive side, so the second card sits on the RIGHT flank at both
+ * indices instead of flipping sides as you step.
+ */
+export const TwoItems: Story = {
+  render: (args) => {
+    function TwoItemCoverflow() {
+      const items = args.items!.slice(0, 2);
+      const [activeIndex, setActiveIndex] = useState(0);
+      return (
+        <Coverflow
+          {...args}
+          items={items}
+          activeIndex={activeIndex}
+          positionLabel={`${activeIndex + 1} of ${items.length}`}
+          onActiveIndexChange={setActiveIndex}
+        />
+      );
+    }
+    return <TwoItemCoverflow />;
+  },
+};
+
+/**
+ * A single item — no ring, so no side posters AND no arrows. A prev/next
+ * control here could only ever return to the card already showing, and this
+ * component does not render controls that look operable and do nothing.
+ */
+export const NoSidePosters: Story = {
+  args: { items: ITEMS.slice(0, 1), positionLabel: "1 of 1" },
+};
+
+/**
+ * `caption` is optional. This is the consumer app's shape: `positionLabel`
+ * alone, on one clean line with no separator dot and no gap where the caption
+ * would have been. Passing a position string as `caption` *as well* is what
+ * printed "1 of 7 · 1 of 7".
+ */
+export const PositionWithoutCaption: Story = {
+  args: { activeIndex: 2, caption: undefined, positionLabel: "3 of 7" },
+};
+
+/** Both halves, for a caller that has a real caption to add to the position. */
+export const CaptionAndPosition: Story = {
+  args: { activeIndex: 2, caption: "7 events", positionLabel: "3 of 7" },
+};
+
+/**
+ * The caller owns `activeIndex` — the floating arrows advance it and the
+ * `aria-live` region announces the new lead. Watch the lead physically slide
+ * out to the side while the next card slides into its place.
+ */
+export const Interactive: Story = {
+  render: (args) => {
+    function InteractiveCoverflow() {
+      const [activeIndex, setActiveIndex] = useState(0);
+      return (
+        <Coverflow
+          {...args}
+          activeIndex={activeIndex}
+          positionLabel={`${activeIndex + 1} of ${args.items!.length}`}
+          onActiveIndexChange={setActiveIndex}
+        />
+      );
+    }
+    return <InteractiveCoverflow />;
+  },
+};
+
+/**
+ * Clicking any visible side poster jumps straight to it — the
+ * keyboard/screen-reader path a mouse user already has, instead of only
+ * stepping with `prevLabel`/`nextLabel`.
+ */
+export const SidePosterSelect: Story = {
+  render: (args) => {
+    function SelectableCoverflow() {
+      const [activeIndex, setActiveIndex] = useState(0);
+      return (
+        <Coverflow
+          {...args}
+          activeIndex={activeIndex}
+          positionLabel={`${activeIndex + 1} of ${args.items!.length}`}
+          onActiveIndexChange={setActiveIndex}
+        />
+      );
+    }
+    return <SelectableCoverflow />;
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Every visible side poster is a real button — click or Tab+Enter to any of them to jump straight there via `onActiveIndexChange`.",
+      },
+    },
+  },
+};
+
+/**
+ * Focus lands on the outermost, most degraded side poster (`|offset| === 3`)
+ * to prove the focus ring survives the tier's grayscale + reduced opacity —
+ * the ring lives on the un-filtered button wrapper, not the filtered media
+ * inside it.
+ */
+export const SidePosterFocused: Story = {
+  args: { activeIndex: 3 },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const poster = await canvas.findByRole("button", { name: "Warehouse Rave" });
+    poster.focus();
+    await expect(poster).toHaveFocus();
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "With `activeIndex` at 3, `Warehouse Rave` (index 0) sits three slots away on the left flank — the farthest, most desaturated tier still mounted. Its `focus-visible` ring is on the un-filtered button, so it stays crisp even though the poster art inside is grayscaled and dimmed.",
+      },
+    },
+  },
+};

package/src/components/coverflow.test.tsx

@@ -0,0 +1,193 @@
+import { describe, it, expect, vi } from "vitest";
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { Coverflow, type CoverflowItem } from "./coverflow";
+
+const items = (count: number): CoverflowItem[] =>
+  Array.from({ length: count }, (_, index) => ({
+    id: `e${index}`,
+    title: `Event ${index}`,
+    meta: `Meta ${index}`,
+  }));
+
+const renderCoverflow = (props: Partial<React.ComponentProps<typeof Coverflow>> = {}) =>
+  render(
+    <Coverflow
+      items={items(7)}
+      activeIndex={0}
+      freeLabel="Free"
+      prevLabel="Previous"
+      nextLabel="Next"
+      {...props}
+    />
+  );
+
+/** Every card is named by its title, so the mounted set is readable from the roles. */
+const mountedTitles = () =>
+  screen.getAllByRole("button").map((node) => node.getAttribute("aria-label"));
+
+describe("Coverflow", () => {
+  describe("the ring", () => {
+    // The reported defect: at activeIndex 0 nothing had a negative offset, so
+    // the left half of the stage was empty while three cards stacked right.
+    it("fills both flanks at activeIndex 0", () => {
+      renderCoverflow({ activeIndex: 0 });
+
+      // 7 items, visible window |offset| <= 3 — the whole ring is on stage,
+      // items 4/5/6 having wrapped round to offsets -3/-2/-1.
+      const titles = mountedTitles().filter((title) => title !== "Previous" && title !== "Next");
+      expect(titles).toEqual(expect.arrayContaining(["Event 4", "Event 5", "Event 6"]));
+    });
+
+    it("steps backwards from 0 to the last index instead of clamping", async () => {
+      const onActiveIndexChange = vi.fn();
+      renderCoverflow({ activeIndex: 0, onActiveIndexChange });
+
+      await userEvent.click(screen.getByRole("button", { name: "Previous" }));
+      expect(onActiveIndexChange).toHaveBeenCalledWith(6);
+    });
+
+    it("steps forwards from the last index back to 0 instead of clamping", async () => {
+      const onActiveIndexChange = vi.fn();
+      renderCoverflow({ activeIndex: 6, onActiveIndexChange });
+
+      await userEvent.click(screen.getByRole("button", { name: "Next" }));
+      expect(onActiveIndexChange).toHaveBeenCalledWith(0);
+    });
+
+    it("reports the index of the side poster that was clicked", async () => {
+      const onActiveIndexChange = vi.fn();
+      renderCoverflow({ activeIndex: 0, onActiveIndexChange });
+
+      // Event 6 sits at offset -1, immediately left of the lead.
+      await userEvent.click(screen.getByRole("button", { name: "Event 6" }));
+      expect(onActiveIndexChange).toHaveBeenCalledWith(6);
+    });
+  });
+
+  describe("the wrap", () => {
+    // The card that comes round the back must NOT tween across the face of the
+    // stage. It renders without its transition classes for exactly the commit
+    // in which it crosses the seam, so the transform lands instantly.
+    it("drops the transition only on the card crossing the seam", () => {
+      const ring = items(7);
+      const { rerender } = renderCoverflow({ items: ring, activeIndex: 0 });
+
+      const transitionClass = "transition-[transform,box-shadow]";
+      expect(screen.getByRole("button", { name: "Event 4" }).className).toContain(transitionClass);
+
+      // Advancing by one sends Event 4 from offset -3 to offset +3 the short
+      // way round, while Event 6 merely slides from -1 to -2.
+      rerender(
+        <Coverflow
+          items={ring}
+          activeIndex={1}
+          freeLabel="Free"
+          prevLabel="Previous"
+          nextLabel="Next"
+        />
+      );
+
+      expect(screen.getByRole("button", { name: "Event 4" }).className).not.toContain(
+        transitionClass
+      );
+      expect(screen.getByRole("button", { name: "Event 6" }).className).toContain(transitionClass);
+    });
+
+    it("keeps the transition on every card when the lead jumps several slots at once", () => {
+      const ring = items(20);
+      const { rerender } = renderCoverflow({ items: ring, activeIndex: 5 });
+
+      rerender(
+        <Coverflow
+          items={ring}
+          activeIndex={8}
+          freeLabel="Free"
+          prevLabel="Previous"
+          nextLabel="Next"
+        />
+      );
+
+      // A three-slot jump (clicking the outermost side poster) moves every card
+      // by three — nothing crossed the seam, so nothing may pop.
+      expect(screen.getByRole("button", { name: "Event 5" }).className).toContain(
+        "transition-[transform,box-shadow]"
+      );
+    });
+  });
+
+  describe("the visible window", () => {
+    // A 50-item ring must not paint 50 posters just because every item now
+    // resolves to some offset.
+    it("mounts only the cards within three slots of the lead", () => {
+      renderCoverflow({ items: items(50), activeIndex: 0 });
+
+      const titles = mountedTitles().filter((title) => title !== "Previous" && title !== "Next");
+      expect(titles).toHaveLength(7);
+      expect(titles).toEqual(
+        expect.arrayContaining([
+          "Event 47",
+          "Event 48",
+          "Event 49",
+          "Event 0",
+          "Event 1",
+          "Event 2",
+          "Event 3",
+        ])
+      );
+    });
+  });
+
+  describe("degenerate lengths", () => {
+    it("renders nothing at all for an empty list", () => {
+      const { container } = renderCoverflow({ items: [] });
+      expect(container).toBeEmptyDOMElement();
+    });
+
+    // A control that looks operable and does nothing is the bug the component's
+    // own docblock argues against — with one item there is nowhere to step to.
+    it("renders no arrows for a single item", () => {
+      renderCoverflow({ items: items(1) });
+
+      expect(screen.queryByRole("button", { name: "Previous" })).not.toBeInTheDocument();
+      expect(screen.queryByRole("button", { name: "Next" })).not.toBeInTheDocument();
+    });
+
+    it("keeps the two-item ring's second card on one consistent side", () => {
+      const { rerender } = renderCoverflow({ items: items(2), activeIndex: 0 });
+      const at0 = screen.getByRole("button", { name: "Event 1" }).getAttribute("style");
+
+      rerender(
+        <Coverflow
+          items={items(2)}
+          activeIndex={1}
+          freeLabel="Free"
+          prevLabel="Previous"
+          nextLabel="Next"
+        />
+      );
+      const at1 = screen.getByRole("button", { name: "Event 0" }).getAttribute("style");
+
+      // Whichever card is not the lead resolves the n/2 tie the same way, so
+      // both renders put it in the identical right-flank slot rather than
+      // flipping it between the two flanks.
+      expect(at0).toBe(at1);
+    });
+  });
+
+  describe("caption and position", () => {
+    it("renders the position on its own, with no separator dot, when there is no caption", () => {
+      renderCoverflow({ positionLabel: "1 of 7" });
+
+      expect(screen.getByText("1 of 7")).toBeInTheDocument();
+      expect(screen.queryByText("·")).not.toBeInTheDocument();
+    });
+
+    it("separates the two only when both are given", () => {
+      renderCoverflow({ caption: "7 events", positionLabel: "1 of 7" });
+
+      expect(screen.getByText("7 events")).toBeInTheDocument();
+      expect(screen.getByText("·")).toBeInTheDocument();
+    });
+  });
+});