@bearmenu/ui 0.8.16 → 0.8.18

package/src/components/poster-stack.tsx

@@ -3,11 +3,29 @@
 import * as React from "react";
 import { useEffect, useRef, useState } from "react";
 import { cn } from "../lib/utils";
+import { EventPosterFallback } from "./event-poster-fallback";
 
 /**
  * PosterStack — three overlapping, gently rotated posters that float, the
  * hub hero's aside slot in the source design.
  *
+ * TAPPABLE SINCE 0.8.18. The stack was three decorative images: the loudest
+ * thing on the hub's first screen, and the one thing on it a reader could not
+ * tap. A poster with `href` is an anchor now — the event's detail page for
+ * the crawler and a modified click, whatever the app's `linkComponent` does
+ * for a plain tap (the hub opens its preview drawer). `caption` prints the
+ * title at the poster's foot: it gives the tap a visible reason on touch,
+ * where there is no hover, and it is the anchor's accessible name, so the
+ * `<img>` goes `alt=""` whenever a caption is set. Without `href` a poster is
+ * decorative, as before.
+ *
+ * The float and the press live on DIFFERENT elements. The wrapper carries
+ * the keyframe `transform` (rotation + drift); the anchor inside it carries
+ * the press scale and the focus ring. One element cannot animate one
+ * `transform` and transition another. The pointed poster comes to the front
+ * (`hover:z-[4]`, `focus-within:z-[4]`) — z-index is not animated, it is the
+ * "pick this one" cue.
+ *
  * Two motion rules, both mandatory:
  *   1. Stops entirely under `prefers-reduced-motion: reduce` — enforced via
  *      an injected `<style>` media query rather than relying on Tailwind's
@@ -20,15 +38,35 @@ import { cn } from "../lib/utils";
  *      reduced motion is on, since nothing is animating to pause.
  */
 
+export type PosterStackLinkProps = {
+  href: string;
+  className?: string;
+  children: React.ReactNode;
+  onClick?: (mouseEvent: React.MouseEvent) => void;
+};
+
+function DefaultLink({ href, ...props }: PosterStackLinkProps) {
+  return <a href={href} {...props} />;
+}
+
 export type PosterStackPoster = {
-  /** Absent renders a neutral placeholder block instead of an image. */
+  /** Absent renders `fallback` instead of an image. */
   src?: string;
   alt: string;
+  /** The event's detail page. With it the poster is an anchor; without it, decorative. */
+  href?: string;
+  /** Caption at the poster's foot — the event title. Becomes the anchor's
+   *  accessible name; the `<img>` then gets `alt=""`. */
+  caption?: string;
+  /** Rendered when `src` is absent or fails. Defaults to `<EventPosterFallback />`. */
+  fallback?: React.ReactNode;
 };
 
 export type PosterStackProps = {
   /** Rendered in order; only the first three are shown. */
   posters: PosterStackPoster[];
+  /** Defaults to a plain `<a>`. Pass `next/link`, or an anchor that opens the app's preview. */
+  linkComponent?: React.ComponentType<PosterStackLinkProps>;
   className?: string;
 };
 
@@ -51,22 +89,28 @@ type PosterSlotConfig = {
   zIndexClassName?: string;
 };
 
+/**
+ * Phone geometry fits a 343px column (375 minus the 16px gutters): the third
+ * poster used to reach 358px and ran into the right gutter. 112 / 128 / 112
+ * wide, 212px tall — 38px shorter than before, which is what lets the door
+ * row land in the first screen. Touch targets are 112×149 and 128×171.
+ */
 const POSTER_SLOTS: PosterSlotConfig[] = [
   {
-    positionClassName: "left-[6px] top-[34px] w-[120px] md:left-0 md:top-[52px] md:w-[196px]",
+    positionClassName: "left-0 top-[28px] w-[112px] md:left-0 md:top-[52px] md:w-[196px]",
     restTransform: "rotate(-5deg)",
     animationName: "ds-poster-stack-float-1",
     animationDurationMs: 9000,
   },
   {
-    positionClassName: "left-[110px] top-0 w-[140px] md:left-[168px] md:w-[232px]",
+    positionClassName: "left-[104px] top-0 w-[128px] md:left-[168px] md:w-[232px]",
     restTransform: "rotate(3deg)",
     animationName: "ds-poster-stack-float-2",
     animationDurationMs: 11000,
     zIndexClassName: "z-[3]",
   },
   {
-    positionClassName: "left-[238px] top-[58px] w-[120px] md:left-[378px] md:top-24 md:w-[196px]",
+    positionClassName: "left-[224px] top-[44px] w-[112px] md:left-[378px] md:top-24 md:w-[196px]",
     restTransform: "rotate(6deg)",
     animationName: "ds-poster-stack-float-3",
     animationDurationMs: 10000,
@@ -77,7 +121,11 @@ const POSTER_SLOTS: PosterSlotConfig[] = [
  * shadow is an art-directed literal rather than a `--shadow-card` token. */
 const POSTER_SHADOW = "0 22px 50px oklch(0.3 0.02 60 / 0.24)";
 
-export function PosterStack({ posters, className }: PosterStackProps) {
+export function PosterStack({
+  posters,
+  linkComponent: LinkComponent = DefaultLink,
+  className,
+}: PosterStackProps) {
   const containerRef = useRef<HTMLDivElement>(null);
   const posterRefs = useRef<Array<HTMLDivElement | null>>([]);
   const [failedIndices, setFailedIndices] = useState<Set<number>>(new Set());
@@ -106,12 +154,41 @@ export function PosterStack({ posters, className }: PosterStackProps) {
   const visiblePosters = posters.slice(0, POSTER_SLOTS.length);
 
   return (
-    <div ref={containerRef} className={cn("relative h-[250px] md:h-[400px]", className)}>
+    <div ref={containerRef} className={cn("relative h-[212px] md:h-[400px]", className)}>
       <style>{POSTER_STACK_ANIMATION_STYLE}</style>
 
       {visiblePosters.map((poster, index) => {
         const slot = POSTER_SLOTS[index];
         const showPoster = !!poster.src && !failedIndices.has(index);
+        const face = (
+          <>
+            {showPoster ? (
+              // eslint-disable-next-line @next/next/no-img-element
+              <img
+                src={poster.src}
+                alt={poster.caption ? "" : poster.alt}
+                loading="lazy"
+                decoding="async"
+                className={cn(
+                  "h-full w-full object-cover",
+                  poster.href &&
+                    "transition-transform duration-300 group-hover/poster:scale-[1.03] motion-reduce:transition-none"
+                )}
+                onError={() => setFailedIndices((current) => new Set(current).add(index))}
+              />
+            ) : (
+              (poster.fallback ?? <EventPosterFallback />)
+            )}
+            {poster.caption && (
+              <span className="absolute inset-x-0 bottom-0 bg-gradient-to-t from-black/70 to-transparent px-2 pb-2 pt-6">
+                <span className="line-clamp-2 text-[11px] font-semibold leading-[1.25] text-white md:text-[12.5px]">
+                  {poster.caption}
+                </span>
+              </span>
+            )}
+          </>
+        );
+
         return (
           <div
             key={poster.alt || index}
@@ -122,7 +199,8 @@ export function PosterStack({ posters, className }: PosterStackProps) {
             className={cn(
               "absolute aspect-[3/4] overflow-hidden rounded-xl bg-muted",
               slot.positionClassName,
-              slot.zIndexClassName
+              slot.zIndexClassName,
+              poster.href && "hover:z-[4] focus-within:z-[4]"
             )}
             style={{
               transform: slot.restTransform,
@@ -134,18 +212,19 @@ export function PosterStack({ posters, className }: PosterStackProps) {
               animationDirection: "alternate",
             }}
           >
-            {showPoster && (
-              // eslint-disable-next-line @next/next/no-img-element
-              <img
-                src={poster.src}
-                alt={poster.alt}
-                loading="lazy"
-                decoding="async"
-                className="h-full w-full object-cover"
-                onError={() =>
-                  setFailedIndices((current) => new Set(current).add(index))
-                }
-              />
+            {poster.href ? (
+              <LinkComponent
+                href={poster.href}
+                className={cn(
+                  "group/poster relative block h-full w-full overflow-hidden rounded-xl",
+                  "transition-transform duration-150 active:scale-[0.98] motion-reduce:transition-none",
+                  "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2"
+                )}
+              >
+                {face}
+              </LinkComponent>
+            ) : (
+              <div className="relative h-full w-full">{face}</div>
             )}
           </div>
         );

package/src/components/section-header.test.tsx

@@ -25,4 +25,19 @@ describe("SectionHeader", () => {
     expect(screen.getByText("Still to start").className).toContain("hidden");
     expect(screen.getByText("Still to start").className).toContain("lg:block");
   });
+
+  it("holds trailing controls at the row's end, beside the action", () => {
+    render(
+      <SectionHeader
+        title="Concepts"
+        action="See all"
+        actionHref="/concepts"
+        trailing={<button type="button">Next</button>}
+      />
+    );
+    const next = screen.getByRole("button", { name: "Next" });
+    const action = screen.getByRole("link", { name: "See all" });
+    expect(next.parentElement).toBe(action.parentElement);
+    expect(next.parentElement).not.toContainElement(screen.getByText("Concepts"));
+  });
 });

package/src/components/section-header.tsx

@@ -60,6 +60,12 @@ export type SectionHeaderProps = {
    * would dilute the headings that matter. Defaults to `"h2"`.
    */
   as?: "h1" | "h2" | "h3" | "h4" | "h5" | "h6" | "p" | "div";
+  /**
+   * Controls at the end of the title row, after `action` — a rail's
+   * previous / next pair on desktop. The header owns none of their
+   * behaviour; it only holds the slot.
+   */
+  trailing?: React.ReactNode;
   className?: string;
 };
 
@@ -91,6 +97,7 @@ export function SectionHeader({
   linkComponent: LinkComponent = DefaultLink,
   onAction,
   as: Heading = "h2",
+  trailing,
   className,
 }: SectionHeaderProps) {
   const actionIcon = <ChevronRight className="h-3.5 w-3.5" aria-hidden />;
@@ -110,18 +117,25 @@ export function SectionHeader({
           )}
         </div>
 
-        {action &&
-          (actionHref ? (
-            <LinkComponent href={actionHref} className={actionClasses} onClick={onAction}>
-              {action}
-              {actionIcon}
-            </LinkComponent>
-          ) : onAction ? (
-            <button type="button" className={actionClasses} onClick={onAction}>
-              {action}
-              {actionIcon}
-            </button>
-          ) : null)}
+        {/* The action and the trailing controls share the row's end, so the
+            action never floats to the middle when both are present. */}
+        {(action || trailing) && (
+          <div className="flex shrink-0 items-center gap-3">
+            {action &&
+              (actionHref ? (
+                <LinkComponent href={actionHref} className={actionClasses} onClick={onAction}>
+                  {action}
+                  {actionIcon}
+                </LinkComponent>
+              ) : onAction ? (
+                <button type="button" className={actionClasses} onClick={onAction}>
+                  {action}
+                  {actionIcon}
+                </button>
+              ) : null)}
+            {trailing}
+          </div>
+        )}
       </div>
 
       {subtitle && (

package/src/components/snap-rail.tsx

@@ -29,6 +29,9 @@ const snapRailVariants = cva(
   {
     variants: {
       itemWidth: {
+        /** Square door tiles — three and a third per phone screen, so the
+         *  cut fourth says "swipe"; more as the viewport widens. */
+        xs: "[&>*]:w-[30%] sm:[&>*]:w-[22%] md:[&>*]:w-[18%]",
         sm: "[&>*]:w-[46%]",
         md: "[&>*]:w-[60%]",
         lg: "[&>*]:w-[80%]",
@@ -42,7 +45,9 @@ const snapRailVariants = cva(
       bleed: {
         none: "",
         card: "-mx-3.5 px-3.5 scroll-px-3.5",
-        page: "-mx-4 px-4 scroll-px-4",
+        /** The consumer's page gutter, read from `--page-gutter` (16px on a
+         *  phone, 24px from md) — a fixed `-mx-4` was 8px short at md. */
+        page: "-mx-[var(--page-gutter,1rem)] px-[var(--page-gutter,1rem)] scroll-px-[var(--page-gutter,1rem)]",
       },
     },
     defaultVariants: {

package/src/components/timeline-day.stories.tsx

@@ -0,0 +1,201 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { TimelineDay, TimelineDaySkeleton } from "./timeline-day";
+import { TimelineHour } from "./timeline-hour";
+import { EventCard } from "./event-card";
+import { EventDayHeader } from "./event-day-header";
+import type { EventCardLabels, EventFormatters, EventPreview } from "./event-types";
+
+const labels: EventCardLabels = { free: "Free", liveNow: "Live now" };
+
+const formatters: EventFormatters = {
+  time: (iso) => iso.slice(11, 16),
+  day: () => "Thu, Sep 3",
+  price: (amount) => `${amount} RON`,
+};
+
+const POSTER =
+  "https://images.unsplash.com/photo-1514525253161-7a46d19cd819?w=640&q=70&auto=format&fit=crop";
+
+const event = (
+  id: string,
+  title: string,
+  place: string,
+  hour: string,
+  fee?: number,
+  poster = POSTER
+): EventPreview => ({
+  id,
+  title,
+  location: place,
+  place_name: place,
+  starts_at: `2026-09-03T${hour}:00`,
+  entry_fee: fee,
+  poster_url: poster,
+});
+
+const meta: Meta<typeof TimelineDay> = {
+  title: "Events/TimelineDay",
+  component: TimelineDay,
+  tags: ["autodocs"],
+  decorators: [
+    (Story) => (
+      <div className="mx-auto max-w-[1180px] bg-background px-4">
+        <Story />
+      </div>
+    ),
+  ],
+  parameters: {
+    layout: "fullscreen",
+    docs: {
+      description: {
+        component:
+          "One day of the timeline, ONE DOM for both viewports. Below `lg` it is a column of hours, each a `TimelineHour` with a gutter chip and the hour's cards. From `lg` the same nodes become lane │ spine │ content: the hour with `role=\"hero\"` is placed in the lane by the grid and pins, every other hour stations itself on the spine, and cards past the cap paint as rows (`EventCard density=\"row-lg\"`). Resize the canvas across 1024px to watch one tree change shape. `rows` counts the column-3 children.",
+      },
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof TimelineDay>;
+
+function Card(props: {
+  ev: EventPreview;
+  emphasis?: boolean | "lg";
+  hideWhen?: boolean | "below-lg";
+  density?: "card" | "row-lg";
+  liveStatus?: string;
+  priority?: boolean;
+}) {
+  return (
+    <EventCard
+      event={props.ev}
+      labels={labels}
+      formatters={formatters}
+      emphasis={props.emphasis}
+      hideWhen={props.hideWhen ?? true}
+      density={props.density}
+      liveStatus={props.liveStatus}
+      showPrice
+      tags={["Live music", "Jazz"]}
+      href={`#${props.ev.id}`}
+      priority={props.priority}
+    />
+  );
+}
+
+/**
+ * A six-hour Friday with the hero in the middle: 19:00 opens, the 20:00 hero
+ * is lifted into the lane on desktop while its hour's other event stays as a
+ * continuation, later hours demote to rows past the cap, and a group of
+ * events the ingest never timed trails the day off the axis.
+ */
+export const FullDay: Story = {
+  render: () => (
+    <div className="flex flex-col gap-3 py-6">
+      <EventDayHeader
+        dayNumber="03"
+        weekday="Thursday"
+        meta="September · 9 events · 1 live"
+        size="responsive"
+      />
+      <TimelineDay rows={6} laneTop="16px">
+        <TimelineHour time="19:00" countLabel="2 events">
+          <Card ev={event("a", "Vinyl night at the bar", "Joben Bistro", "19:00", 0)} priority />
+          <Card ev={event("b", "Pub quiz: nineties", "Klausen", "19:00", 20)} />
+        </TimelineHour>
+        <TimelineHour time="20:00" role="hero" isLive liveLabel="NOW ON" countLabel="1 event">
+          <Card
+            ev={event("c", "Subcarpați live — sold-out tour warm-up", "Form Space", "20:00", 60)}
+            emphasis="lg"
+            hideWhen="below-lg"
+            liveStatus="Live now · ends around 23:00"
+          />
+        </TimelineHour>
+        <TimelineHour time="20:00" role="continuation" isLive liveLabel="NOW ON" countLabel="1 event">
+          <Card ev={event("d", "Wine tasting: Dealu Mare", "Enoteca", "20:00", 90)} />
+        </TimelineHour>
+        <TimelineHour time="21:00" countLabel="3 events" layout="rows">
+          <Card ev={event("e", "Comedy open mic", "Flying Circus", "21:00", 25)} density="row-lg" />
+          <Card ev={event("f", "Techno: Berlin calling", "Mansion", "21:00", 40)} density="row-lg" />
+          <Card ev={event("g", "Salsa social", "Casa Tranzit", "21:00", 0)} density="row-lg" />
+        </TimelineHour>
+        <TimelineHour time="23:00" countLabel="1 event" layout="rows">
+          <Card ev={event("h", "Late-night jazz jam", "Jazz Club", "23:00")} density="row-lg" />
+        </TimelineHour>
+        <TimelineHour
+          time="Time to be confirmed"
+          role="unscheduled"
+          countLabel="1 event"
+          note="The venue has not published a start time."
+        >
+          <Card ev={event("i", "Board games afternoon", "Insomnia Café", "00:00", 0)} />
+        </TimelineHour>
+      </TimelineDay>
+    </div>
+  ),
+};
+
+/** A quiet Tuesday: one hour, one event, no hero — no lane on desktop either. */
+export const OneHour: Story = {
+  render: () => (
+    <div className="flex flex-col gap-3 py-6">
+      <EventDayHeader dayNumber="08" weekday="Tuesday" meta="September · 1 event" size="responsive" />
+      <TimelineDay rows={1}>
+        <TimelineHour time="19:30" countLabel="1 event">
+          <Card ev={event("a", "Book club: Cărtărescu", "Cărturești", "19:30", 0)} priority />
+        </TimelineHour>
+      </TimelineDay>
+    </div>
+  ),
+};
+
+/**
+ * Two full days stacked, so the lane's pin and release can be watched at
+ * 1024 and 1440: scroll the canvas and the first day's poster holds until
+ * its column runs out, then the second day's takes over.
+ */
+export const StickyLane: Story = {
+  render: () => (
+    <div className="flex flex-col gap-10 py-6">
+      {["03", "04"].map((day) => (
+        <div key={day} className="flex flex-col gap-3">
+          <EventDayHeader
+            dayNumber={day}
+            weekday={day === "03" ? "Thursday" : "Friday"}
+            meta="September · 7 events"
+            size="responsive"
+          />
+          <TimelineDay rows={4} laneTop="16px">
+            <TimelineHour time="18:00" role="hero" countLabel="1 event">
+              <Card
+                ev={event(`${day}-hero`, "Headliner of the night", "Form Space", "18:00", 50)}
+                emphasis="lg"
+                hideWhen="below-lg"
+              />
+            </TimelineHour>
+            {["19:00", "20:00", "21:00", "22:00"].map((hour) => (
+              <TimelineHour key={hour} time={hour} countLabel="2 events" layout="rows">
+                <Card
+                  ev={event(`${day}-${hour}-1`, `Something at ${hour}`, "Klausen", hour, 20)}
+                  density="row-lg"
+                />
+                <Card
+                  ev={event(`${day}-${hour}-2`, `Something else at ${hour}`, "Joben", hour, 0)}
+                  density="row-lg"
+                />
+              </TimelineHour>
+            ))}
+          </TimelineDay>
+        </div>
+      ))}
+    </div>
+  ),
+};
+
+export const Skeleton: Story = {
+  render: () => (
+    <div className="py-6">
+      <TimelineDaySkeleton hourCount={3} />
+    </div>
+  ),
+};

package/src/components/timeline-day.test.tsx

@@ -0,0 +1,78 @@
+import { describe, it, expect } from "vitest";
+import { render, screen } from "@testing-library/react";
+import { TimelineDay } from "./timeline-day";
+import { TimelineHour } from "./timeline-hour";
+
+describe("TimelineDay", () => {
+  it("renders every hour in source order, hero included, with one puck per stationed hour", () => {
+    const { container } = render(
+      <TimelineDay rows={2}>
+        <TimelineHour time="19:00" countLabel="1 event">
+          <p>Early</p>
+        </TimelineHour>
+        <TimelineHour time="20:00" role="hero">
+          <p>Hero</p>
+        </TimelineHour>
+        <TimelineHour time="21:00" countLabel="1 event">
+          <p>Late</p>
+        </TimelineHour>
+      </TimelineDay>
+    );
+
+    const hours = [...container.querySelectorAll("[data-timeline-hour]")];
+    expect(hours.map((hour) => hour.getAttribute("data-timeline-hour"))).toEqual([
+      "hour",
+      "hero",
+      "hour",
+    ]);
+    // Chronological in the DOM — the phone's visual order and the reading order.
+    expect(container.textContent).toMatch(/19:00[^]*Early[^]*20:00[^]*Hero[^]*21:00[^]*Late/);
+    expect(screen.getAllByText(/^\d\d:00$/)).toHaveLength(3);
+  });
+
+  it("sets the row count the lane and spine span", () => {
+    const { container } = render(
+      <TimelineDay rows={5} laneTop="120px">
+        <TimelineHour time="19:00">
+          <p>x</p>
+        </TimelineHour>
+      </TimelineDay>
+    );
+    const root = container.firstElementChild as HTMLElement;
+    expect(root.style.getPropertyValue("--timeline-rows")).toBe("5");
+    expect(root.style.getPropertyValue("--timeline-lane-top")).toBe("120px");
+  });
+
+  it("gives an unscheduled group an inline heading and no station", () => {
+    const { container } = render(
+      <TimelineDay rows={1}>
+        <TimelineHour time="Time to be confirmed" role="unscheduled" countLabel="2 events" note="No hour">
+          <p>a</p>
+          <p>b</p>
+        </TimelineHour>
+      </TimelineDay>
+    );
+    expect(screen.getByText("Time to be confirmed")).toBeInTheDocument();
+    expect(screen.getByText("2 events")).toBeInTheDocument();
+    expect(screen.getByText("No hour")).toBeInTheDocument();
+    expect(container.querySelector(".font-mono.tabular-nums.whitespace-nowrap")).toBeNull();
+  });
+
+  it("rules between rows but not between cards", () => {
+    const { container: rows } = render(
+      <TimelineHour time="21:00" layout="rows">
+        <p>a</p>
+        <p>b</p>
+      </TimelineHour>
+    );
+    const { container: cards } = render(
+      <TimelineHour time="21:00" layout="cards">
+        <p>a</p>
+        <p>b</p>
+      </TimelineHour>
+    );
+    // The hour's own hairline (vertical) plus the heading rule plus one between the two rows.
+    expect(rows.querySelectorAll('[data-orientation="horizontal"]').length).toBe(2);
+    expect(cards.querySelectorAll('[data-orientation="horizontal"]').length).toBe(1);
+  });
+});