@bearmenu/ui 0.8.4 → 0.8.6

package/src/components/concept-card.stories.tsx

@@ -0,0 +1,80 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { PartyPopper, Music } from "lucide-react";
+import { ConceptCard, ConceptCardSkeleton } from "./concept-card";
+
+const kind = (
+  <>
+    <PartyPopper className="h-3 w-3" aria-hidden />
+    Party
+  </>
+);
+
+// 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 ConceptCard> = {
+  title: "Events/ConceptCard",
+  component: ConceptCard,
+  tags: ["autodocs"],
+  args: {
+    title: "Flying Circus",
+    meta: "Every Saturday · Flying Circus · 4 dates",
+    kind,
+  },
+  decorators: [
+    (Story) => (
+      <div className="w-[320px]">
+        <Story />
+      </div>
+    ),
+  ],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "`meta` is composed by the caller — the design's variants (\"Every Saturday · Flying Circus · 4 dates\") don't decompose into parts without hardcoding clause order.",
+      },
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof ConceptCard>;
+
+export const Default: Story = {};
+
+/** Absent `coverUrl` falls back to a flat muted block, same as `EventCard`. */
+export const NoCover: Story = {
+  args: { coverUrl: undefined },
+};
+
+export const WithCover: Story = {
+  args: {
+    coverUrl:
+      "data:image/svg+xml;utf8," +
+      encodeURIComponent(
+        `<svg xmlns="http://www.w3.org/2000/svg" width="640" height="320"><rect width="640" height="320" fill="#3a2c46"/><text x="50%" y="50%" font-family="monospace" font-size="18" fill="#fff" text-anchor="middle">cover</text></svg>`
+      ),
+  },
+};
+
+export const LiveMusicKind: Story = {
+  args: {
+    title: "Jazz at the Basement",
+    meta: "Every Thursday · The Basement · 12 dates",
+    kind: (
+      <>
+        <Music className="h-3 w-3" aria-hidden />
+        Live music
+      </>
+    ),
+  },
+};
+
+export const Clickable: Story = {
+  args: { href: "/events/flying-circus" },
+};
+
+export const Skeleton: Story = {
+  render: () => <ConceptCardSkeleton />,
+};

package/src/components/concept-card.tsx

@@ -0,0 +1,143 @@
+"use client";
+
+import { memo, useState } from "react";
+import { Calendar } from "lucide-react";
+import { cn } from "../lib/utils";
+import { Skeleton } from "./skeleton";
+
+/**
+ * ConceptCard — the recurring-series cover card (e.g. a weekly party
+ * concept), a wide 2:1 image with a bottom scrim carrying a kind pill,
+ * a composed date/venue/count line and the title.
+ *
+ * Same contract as `EventCard`: DS-owned props, plain `<img>`, anchor
+ * whenever `href` is given. Absent `coverUrl` falls back to a flat
+ * `bg-muted` block, same treatment `EventCard` gives a missing poster.
+ */
+
+export type ConceptCardLinkProps = {
+  href: string;
+  className?: string;
+  children: React.ReactNode;
+  onClick?: (mouseEvent: React.MouseEvent) => void;
+};
+
+function DefaultLink({ href, ...props }: ConceptCardLinkProps) {
+  return <a href={href} {...props} />;
+}
+
+export type ConceptCardProps = {
+  title: string;
+  /**
+   * The whole date/venue/count line, composed by the caller, e.g. "Every
+   * Saturday · Flying Circus · 4 dates" — clause order is locale-dependent.
+   */
+  meta: string;
+  /** Label plus its icon, e.g. `<><PartyPopper .../> Party</>`. */
+  kind: React.ReactNode;
+  coverUrl?: string;
+  href?: string;
+  /** Defaults to a plain `<a>`. Pass `next/link` in a Next app. */
+  linkComponent?: React.ComponentType<ConceptCardLinkProps>;
+  onClick?: (mouseEvent: React.MouseEvent) => void;
+  className?: string;
+  /** Forwarded to the cover's `loading` attribute (`"eager"` when true). */
+  priority?: boolean;
+};
+
+export const ConceptCard = memo(function ConceptCard({
+  title,
+  meta,
+  kind,
+  coverUrl,
+  href,
+  linkComponent: LinkComponent = DefaultLink,
+  onClick,
+  className,
+  priority,
+}: ConceptCardProps) {
+  const [imgError, setImgError] = useState(false);
+  const showCover = !!coverUrl && !imgError;
+
+  const body = (
+    <>
+      <div className="absolute inset-0 bg-muted">
+        {showCover && (
+          // eslint-disable-next-line @next/next/no-img-element
+          <img
+            src={coverUrl}
+            alt={title}
+            title={title}
+            loading={priority ? "eager" : "lazy"}
+            decoding="async"
+            className="h-full w-full object-cover"
+            onError={() => setImgError(true)}
+          />
+        )}
+      </div>
+
+      <div className="absolute inset-x-0 bottom-0 z-[1] h-[60%] bg-gradient-to-t from-black/90 via-black/60 to-transparent" />
+
+      <span className="absolute left-2 top-2 z-[2] inline-flex items-center gap-1 rounded-md bg-black/50 px-2 py-1 text-[11px] font-semibold text-white">
+        {kind}
+      </span>
+
+      <div className="relative z-[2] mt-auto flex w-full flex-col gap-0.5 p-2.5 text-white">
+        <div className="flex items-center gap-1 text-[11px] font-medium text-white/85">
+          <Calendar className="h-3 w-3 shrink-0" aria-hidden />
+          <span className="truncate">{meta}</span>
+        </div>
+        <div className="line-clamp-1 text-[14px] font-semibold leading-[1.25]">{title}</div>
+      </div>
+    </>
+  );
+
+  const rootClasses = cn(
+    "relative flex aspect-[2/1] flex-col overflow-hidden rounded-xl text-left",
+    (href || onClick) &&
+      "cursor-pointer focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2",
+    className
+  );
+
+  if (href) {
+    return (
+      <LinkComponent href={href} className={rootClasses} onClick={onClick}>
+        {body}
+      </LinkComponent>
+    );
+  }
+
+  if (onClick) {
+    return (
+      <button type="button" className={rootClasses} onClick={onClick}>
+        {body}
+      </button>
+    );
+  }
+
+  return <div className={rootClasses}>{body}</div>;
+});
+
+export type ConceptCardSkeletonProps = {
+  className?: string;
+};
+
+export function ConceptCardSkeleton({ className }: ConceptCardSkeletonProps) {
+  return (
+    <div
+      aria-hidden="true"
+      className={cn("relative flex aspect-[2/1] flex-col overflow-hidden rounded-xl", className)}
+    >
+      <Skeleton className="absolute inset-0 rounded-none" />
+
+      <div className="absolute inset-x-0 bottom-0 z-[1] h-[60%] bg-gradient-to-t from-black/90 via-black/60 to-transparent" />
+
+      <Skeleton className="absolute left-2 top-2 z-[2] h-[26px] w-16 rounded-md bg-white/20" />
+
+      <div className="relative z-[2] mt-auto flex w-full flex-col gap-1 p-2.5">
+        <Skeleton className="h-[11px] w-24 bg-white/15" />
+        <Skeleton className="h-[14px] w-2/3 bg-white/20" />
+      </div>
+    </div>
+  );
+}

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();
+    });
+  });
+});