@bearmenu/ui 0.8.13 → 0.8.15

package/src/components/place-card.tsx

@@ -1,187 +1,395 @@
 "use client";
 
-import { memo, useState } from "react";
-import { MapPin, Star, Clock, UtensilsCrossed, Wine } from "lucide-react";
+import {
+  forwardRef,
+  memo,
+  useMemo,
+  useState,
+  type KeyboardEvent,
+  type MouseEvent,
+  type ReactNode,
+} from "react";
+import { MapPin, Star, UtensilsCrossed } from "lucide-react";
+import { motion } from "framer-motion";
 import { cn } from "../lib/utils";
-import { Text } from "./text";
+import {
+  HOVER_IMAGE_MOTION,
+  HOVER_IMAGE_WRAPPER,
+  HOVER_LIFT_GRID_GROUP,
+  HOVER_MOTION,
+} from "../lib/card-hover";
+import { showsGradeAtom } from "../lib/grade";
+import { NEUTRAL_ICON_FILTER } from "../lib/icon-depth";
+import { springSnappy } from "../lib/motion";
+import { OVERLAY_PILL } from "../lib/overlay-pill";
+import { Badge } from "./badge";
+import { GradeAtom } from "./grade-atom";
+import { Separator } from "./separator";
+import { Skeleton } from "./skeleton";
 import type { PlaceCardLabels, PlacePreview } from "./place-types";
 
-export interface PlaceCardProps {
+/**
+ * PlaceCard — the 4:3 cover card every place rail and grid reuses.
+ *
+ * RENDERS AN ANCHOR WHENEVER `href` IS GIVEN. Pass `href` AND `onOpen`: the
+ * anchor is real for crawlers, middle-click and "open in new tab", while a
+ * plain left-click is intercepted to open the in-page drawer. Without `href`
+ * the root is a `role="button"` (Enter / Space open too).
+ *
+ * Like `event-card.tsx`, this takes a DS-owned view model, injected labels and
+ * injected framework pieces — no app schema, no app hooks, no i18n. The link
+ * and the image are both injectable: a plain `<a>` / `<img>` by default, and
+ * `next/link` / `next/image` in a Next app, so the consumer keeps its srcset,
+ * its priority preload and its image loader on the card that is its LCP.
+ */
+
+export type PlaceCardLinkProps = {
+  href: string;
+  className?: string;
+  children: ReactNode;
+  onClick?: (mouseEvent: MouseEvent<HTMLAnchorElement>) => void;
+  "aria-label"?: string;
+};
+
+export type PlaceCardImageProps = {
+  src: string;
+  alt: string;
+  /** Responsive `sizes` hint; the default `<img>` ignores it. */
+  sizes: string;
+  /** The LCP candidate — preload / `loading="eager"`. */
+  priority: boolean;
+  /** Positions the image to fill the 4:3 box (`absolute inset-0 h-full w-full object-cover` + hover motion). */
+  className: string;
+  onError: () => void;
+};
+
+/**
+ * Both defaults forward refs: the root is `motion.create(LinkComponent)`, and
+ * framer-motion needs the ref to reach the DOM node. An injected link (e.g.
+ * `next/link`) must forward its ref too.
+ */
+const DefaultLink = forwardRef<HTMLAnchorElement, PlaceCardLinkProps>(function DefaultLink(
+  { href, ...props },
+  ref
+) {
+  return <a ref={ref} href={href} {...props} />;
+});
+
+function DefaultImage({ src, alt, priority, className, onError }: PlaceCardImageProps) {
+  return (
+    // eslint-disable-next-line @next/next/no-img-element
+    <img
+      src={src}
+      alt={alt}
+      loading={priority ? "eager" : "lazy"}
+      decoding="async"
+      className={className}
+      onError={onError}
+    />
+  );
+}
+
+export type PlaceCardProps = {
   place: PlacePreview;
   labels: PlaceCardLabels;
-  /** Locale tag (e.g. `"en"`, `"ro"`). Reserved for future Intl number/distance formatting. */
-  locale?: string;
-  /** Optional click handler. When omitted the card renders as a non-interactive div. */
-  onClick?: (place: PlacePreview) => void;
-  className?: string;
-  /** Forwarded to the thumbnail's `loading` attribute (`"eager"` when true). */
+  /** Marks this as the LCP candidate — forwarded to `imageComponent`. */
   priority?: boolean;
+  /**
+   * Responsive image `sizes` hint. Defaults to a viewport-width formula for
+   * grid layouts; rail callers (220px-wide carousels) should pass `"220px"` so
+   * the browser doesn't download a viewport-width variant for a tiny card.
+   */
+  imageSizes?: string;
+  /**
+   * Real detail-page URL. When set the card root renders as a crawlable
+   * anchor; a plain left-click is still intercepted to call `onOpen`, while
+   * modified / middle-clicks navigate. When omitted the root is a
+   * `role="button"`.
+   */
+  href?: string;
+  /**
+   * Defaults to a plain `<a>`. Pass a ref-forwarding `next/link` adapter in a
+   * Next app. MUST be module-scoped: the root is `motion.create(linkComponent)`
+   * keyed on its identity, so an inline component remounts the card (and
+   * re-requests its cover) on every render.
+   */
+  linkComponent?: React.ComponentType<PlaceCardLinkProps>;
+  /** Defaults to a plain `<img>`. Pass a `next/image` adapter in a Next app. Module-scoped, like `linkComponent`. */
+  imageComponent?: React.ComponentType<PlaceCardImageProps>;
+  /** Opens the in-page drawer / sheet. A left-click on the anchor is prevented in favour of this. */
+  onOpen?: (place: PlacePreview) => void;
+  /**
+   * Optional non-interactive context slot rendered below the place's own
+   * info rows, e.g. concept page: "Served as X / 45 RON / 300g". MUST be
+   * display-only — no buttons or links — since the card itself is the click
+   * target.
+   */
+  footer?: ReactNode;
+  /**
+   * Rendered over the photo's top-left corner as a SIBLING of the interactive
+   * root, not a child — so it MAY be a button or link (e.g. a trending marker
+   * that opens a popover) without nesting interactives inside the card's
+   * anchor / `role="button"`. It lifts with the card via the shared
+   * `group/card` wrapper. The caller decides when it renders (fe gates its
+   * trending badge on the API's `trending` flag).
+   */
+  photoOverlay?: ReactNode;
+  className?: string;
+};
+
+function formatDistance(meters: number): string {
+  if (meters < 1000) return `${Math.round(meters)} m`;
+  return `${(meters / 1000).toFixed(1)} km`;
 }
 
-function formatDistance(meters?: number): string {
-  return meters ? `${(meters / 1000).toFixed(1)} km` : "—";
+/** Title-row headline metric: the platform grade when the place has one,
+ *  otherwise the Google star rating (graceful fallback for ungraded places). */
+function HeadlineRating({ place, labels }: { place: PlacePreview; labels: PlaceCardLabels }) {
+  const grade = place.reviews_digest?.grade;
+  if (showsGradeAtom(grade, "xs")) return <GradeAtom grade={grade} labels={labels.grade} size="xs" />;
+  const rating = place.rating?.rating;
+  if (rating === undefined) return null;
+  return (
+    <div className="flex shrink-0 items-center gap-1 text-xs font-medium text-foreground">
+      <Star className="h-3 w-3 fill-current" aria-hidden />
+      <span className="tabular-nums">{rating.toFixed(1)}</span>
+    </div>
+  );
 }
 
-function formatRating(rating?: { rating: number; count: number }): string | null {
-  return rating?.rating ? rating.rating.toFixed(1) : null;
+function PriceLevel({ level, label }: { level: number; label: string }) {
+  // The schema documents 1–4 but types an int64; an out-of-range value must
+  // not turn into a `repeat(-1)` RangeError that unmounts the whole rail.
+  const filled = Math.min(Math.max(Math.round(level), 1), 4);
+  return (
+    <span className="text-muted-foreground" aria-label={label}>
+      {"$".repeat(filled)}
+      <span className="opacity-30">{"$".repeat(4 - filled)}</span>
+    </span>
+  );
 }
 
+const STATIC_ROOT_CLASSES = `group relative flex w-full select-none flex-col ${HOVER_MOTION} ${HOVER_LIFT_GRID_GROUP}`;
+const ROOT_CLASSES = `${STATIC_ROOT_CLASSES} cursor-pointer focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:rounded-xl`;
+
+const DEFAULT_SIZES = "(max-width: 640px) 100vw, (max-width: 1024px) 50vw, 33vw";
+
 export const PlaceCard = memo(function PlaceCard({
   place,
   labels,
-  onClick,
+  priority = false,
+  imageSizes = DEFAULT_SIZES,
+  href,
+  linkComponent: LinkComponent = DefaultLink,
+  imageComponent: ImageComponent = DefaultImage,
+  onOpen,
+  footer,
+  photoOverlay,
   className,
-  priority,
 }: PlaceCardProps) {
   const [imgError, setImgError] = useState(false);
+  // Module-scoped in spirit: memoised on the component identity so the
+  // motion-wrapped anchor keeps a stable type across renders (a fresh
+  // `motion.create` per render would remount the whole card).
+  const MotionLink = useMemo(() => motion.create(LinkComponent), [LinkComponent]);
 
-  const ratingDisplay = formatRating(place.rating);
-  const reviewCount = place.review_count ?? place.rating?.count;
-  const showHeader = !!place.thumbnail_url && !imgError;
-  const distanceMeters = place.location?.distance?.meters;
-  const schedule = place.today_schedule?.[0] ?? place.hours?.[0];
-  const scheduleHour = place.open_now ? schedule?.closes_at : schedule?.opens_at;
-  const scheduleLabel = place.open_now ? labels.until : labels.opensAt;
-
-  const sharedClasses = cn(
-    "glass rounded-3xl border border-transparent bg-transparent p-0 text-left text-card-foreground transition-transform duration-300 ease-in-out hover:border-border/20 h-full flex flex-col w-full",
-    onClick &&
-      "cursor-pointer [@media(hover:hover)]:hover:-translate-y-1 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
-    className
-  );
+  const coverUrl = imgError ? undefined : place.cover_url;
+  const cuisine = place.cuisines?.[0];
+  const distance = place.location?.distance?.meters;
+  // Neighbourhood is the SSR/primary location signal (API-backed, present
+  // without geolocation). "Distance from you" is a client-only enhancement
+  // that supersedes it once geolocation is granted.
+  const neighbourhood = place.areas?.[0]?.name;
+  const priceLevel = place.price_dishes?.price_score ?? place.price_drinks?.price_score;
+  const showPrice = priceLevel !== undefined && priceLevel > 0;
+  const ariaLabel = labels.viewDetails(place.name);
 
-  const content = (
-    <div className="p-4 flex-1 flex flex-col">
-      {/* SECTION 1 — HEADER */}
-      <div className="flex items-start gap-3 mb-3">
-        <div className="w-12 h-12 rounded-lg bg-primary/10 flex items-center justify-center overflow-hidden flex-shrink-0">
-          {showHeader ? (
-            // eslint-disable-next-line @next/next/no-img-element
-            <img
-              src={place.thumbnail_url}
-              alt={place.name}
-              title={place.name}
-              width={48}
-              height={48}
-              loading={priority ? "eager" : "lazy"}
-              decoding="async"
-              className="w-full h-full object-cover"
-              onError={() => setImgError(true)}
-            />
-          ) : (
+  const handleKeyDown = (e: KeyboardEvent<HTMLDivElement>) => {
+    if (e.key === "Enter" || e.key === " ") {
+      e.preventDefault();
+      onOpen?.(place);
+    }
+  };
+
+  // Crawlable-anchor path: a plain left-click opens the drawer (progressive
+  // enhancement); modified / middle-clicks fall through to real navigation.
+  const handleAnchorClick = (e: MouseEvent<HTMLAnchorElement>) => {
+    if (!onOpen || e.metaKey || e.ctrlKey || e.shiftKey || e.altKey || e.button !== 0) return;
+    e.preventDefault();
+    onOpen(place);
+  };
+
+  const body = (
+    <>
+      <div
+        className={cn(
+          "relative aspect-[4/3] w-full overflow-hidden rounded-xl",
+          HOVER_IMAGE_WRAPPER
+        )}
+      >
+        {coverUrl ? (
+          <ImageComponent
+            src={coverUrl}
+            alt={place.name}
+            sizes={imageSizes}
+            priority={priority}
+            className={`absolute inset-0 h-full w-full object-cover ${HOVER_IMAGE_MOTION} motion-image-enter`}
+            onError={() => setImgError(true)}
+          />
+        ) : (
+          /* The neutral grey placeholder every card type shares. The glyph
+             sits at `--accent` (the brand brown) rather than `text-muted-
+             foreground`, so it reads as intentional instead of as a washed-out
+             failed image. */
+          <div className="flex h-full w-full items-center justify-center bg-gradient-to-br from-muted to-border">
             <UtensilsCrossed
-              className="w-6 h-6 text-primary/60"
-              aria-hidden="true"
+              className="h-10 w-10 text-[color:var(--accent)]"
+              style={{ filter: NEUTRAL_ICON_FILTER }}
+              aria-hidden
             />
-          )}
-        </div>
+          </div>
+        )}
 
-        <div className="flex-1 min-w-0">
-          <Text as="h3" weight="bold" leading="tight" color="default" className="text-lg mb-2">
-            {place.name}
-          </Text>
-          {ratingDisplay !== null && (
-            <div className="flex items-center gap-1">
-              <Star className="w-4 h-4 fill-primary text-primary" aria-hidden="true" />
-              <span className="font-semibold text-sm">{ratingDisplay}</span>
-              {reviewCount !== undefined && reviewCount !== null && (
-                <span className="text-xs text-muted-foreground">({reviewCount})</span>
-              )}
-            </div>
-          )}
-        </div>
+        {place.open_now === true && (
+          <span
+            className="absolute right-2.5 top-2.5 h-2 w-2 rounded-full bg-green-500 ring-2 ring-white/70"
+            aria-hidden
+          />
+        )}
+        {place.open_now === false && (
+          /* `Badge variant="overlay"` + the shared cover geometry: this pill and
+             the caller's `photoOverlay` sit on the same photo and must match. */
+          <Badge variant="overlay" className={cn(OVERLAY_PILL, "absolute right-2 top-2")}>
+            {labels.closed}
+          </Badge>
+        )}
       </div>
 
-      {/* SECTION 2 — PRICE RANGES */}
-      {(place.price_dishes || place.price_drinks) && (
-        <div className="mb-3">
-          <div className="flex items-center gap-4 text-xs">
-            {place.price_dishes?.price_range_low != null &&
-              place.price_dishes?.price_range_high != null && (
-                <div className="flex items-center gap-1 text-primary">
-                  <UtensilsCrossed className="w-4 h-4" aria-hidden="true" />
-                  <span>
-                    {place.price_dishes.price_range_low}-{place.price_dishes.price_range_high}{" "}
-                    {labels.currency}
-                  </span>
-                </div>
-              )}
-            {place.price_drinks?.price_range_low != null &&
-              place.price_drinks?.price_range_high != null && (
-                <div className="flex items-center gap-1 text-primary">
-                  <Wine className="w-4 h-4" aria-hidden="true" />
-                  <span>
-                    {place.price_drinks.price_range_low}-{place.price_drinks.price_range_high}{" "}
-                    {labels.currency}
-                  </span>
-                </div>
-              )}
-          </div>
+      <div className="mt-2.5 flex flex-col">
+        {/* Title row: name (left) + rating (right) — title dominates.
+            `min-w-0` on the name is what makes `line-clamp-1` actually clamp:
+            without it the flex item refuses to shrink below its content, so a
+            wide right-hand pill pushed the row past the card edge instead of
+            truncating the name. */}
+        <div className="mb-1 flex items-baseline justify-between gap-2">
+          <p className="min-w-0 line-clamp-1 text-sm font-semibold text-foreground">{place.name}</p>
+          <HeadlineRating place={place} labels={labels} />
         </div>
-      )}
 
-      {/* SECTION 3 — LOCATION & STATUS */}
-      <div className="mb-3">
-        <div className="flex items-center gap-2 text-sm text-primary">
-          {distanceMeters !== undefined && distanceMeters !== null && (
-            <>
-              <div className="flex items-center gap-1">
-                <MapPin className="w-3 h-3" aria-hidden="true" />
-                <span className="text-xs">{formatDistance(distanceMeters)}</span>
-              </div>
-              <span>·</span>
-            </>
+        <div className="flex flex-col gap-0.5">
+          {(cuisine || showPrice) && (
+            <div className="flex items-center gap-1.5 text-xs text-muted-foreground">
+              {cuisine && <span className="capitalize">{cuisine}</span>}
+              {cuisine && showPrice && <span className="text-border">·</span>}
+              {showPrice && <PriceLevel level={priceLevel} label={labels.priceLevel(priceLevel)} />}
+            </div>
           )}
-          <div className="flex items-center gap-1">
-            <Clock
-              className={cn(
-                "w-3 h-3",
-                place.open_now ? "text-green-500" : "text-muted-foreground"
-              )}
-              aria-hidden="true"
-            />
-            <span
-              className={cn(
-                "text-xs",
-                place.open_now ? "text-green-500" : "text-muted-foreground"
-              )}
-            >
-              {place.open_now ? labels.open : labels.closed}
-            </span>
-            {scheduleHour != null && (
-              <span
-                className={cn(
-                  "text-xs",
-                  place.open_now ? "text-green-500" : "text-muted-foreground"
-                )}
-              >
-                {`· ${scheduleLabel} ${String(scheduleHour).padStart(2, "0")}:00`}
-              </span>
-            )}
-          </div>
+
+          {/* Location signal: distance when geolocation is granted (client
+              enhancement), otherwise the neighbourhood (SSR/primary). */}
+          {distance !== undefined ? (
+            <div className="flex items-center gap-1.5 text-xs text-muted-foreground">
+              <MapPin className="h-3 w-3 shrink-0" aria-hidden />
+              <span>{formatDistance(distance)}</span>
+            </div>
+          ) : neighbourhood ? (
+            <div className="flex items-center gap-1.5 text-xs text-muted-foreground">
+              <MapPin className="h-3 w-3 shrink-0" aria-hidden />
+              <span className="line-clamp-1">{neighbourhood}</span>
+            </div>
+          ) : null}
         </div>
+
+        {footer && (
+          <>
+            <Separator className="my-2" />
+            <div>{footer}</div>
+          </>
+        )}
       </div>
+    </>
+  );
 
-      {/* SECTION 4 — DESCRIPTION */}
-      {place.description && (
-        <div className="mb-4">
-          <Text as="p" variant="caption" color="muted" className="line-clamp-2">
-            {place.description}
-          </Text>
+  // The overlay renders as a SIBLING of the interactive card (not a child) so
+  // an interactive marker never nests inside the card's anchor / role="button"
+  // (invalid ARIA). Being a sibling, it cannot inherit the card's hover
+  // transform — so both it and the card take their lift from the shared
+  // `group/card` wrapper instead of their own `:hover`, which is what keeps the
+  // marker attached to the photo mid-lift. `left-2 top-2` is the SAME inset as
+  // the Closed pill on the opposite corner.
+  return (
+    <div className={cn("group/card relative w-full", className)}>
+      {href ? (
+        <MotionLink
+          href={href}
+          aria-label={ariaLabel}
+          onClick={handleAnchorClick}
+          whileTap={{ scale: 0.98 }}
+          transition={springSnappy}
+          className={ROOT_CLASSES}
+        >
+          {body}
+        </MotionLink>
+      ) : onOpen ? (
+        <motion.div
+          role="button"
+          tabIndex={0}
+          aria-label={ariaLabel}
+          onClick={() => onOpen(place)}
+          onKeyDown={handleKeyDown}
+          whileTap={{ scale: 0.98 }}
+          transition={springSnappy}
+          className={ROOT_CLASSES}
+        >
+          {body}
+        </motion.div>
+      ) : (
+        /* Neither destination nor handler (a fixture in a marketing hero): a
+           plain block, not a focusable control that announces and does nothing. */
+        <div className={STATIC_ROOT_CLASSES}>{body}</div>
+      )}
+      {photoOverlay && (
+        <div className={cn("absolute left-2 top-2 z-10", HOVER_MOTION, HOVER_LIFT_GRID_GROUP)}>
+          {photoOverlay}
         </div>
       )}
     </div>
   );
-
-  if (onClick) {
-    return (
-      <button type="button" className={sharedClasses} onClick={() => onClick(place)}>
-        {content}
-      </button>
-    );
-  }
-
-  return <div className={sharedClasses}>{content}</div>;
 });
 
-PlaceCard.displayName = "PlaceCard";
+export type PlaceCardSkeletonProps = {
+  /** Matches `PlaceCardProps["footer"]` — the caller's placeholder for its own footer, under the same divider. */
+  footer?: ReactNode;
+  className?: string;
+};
+
+/**
+ * Mirrors `<PlaceCard>`'s geometry so nothing shifts when data lands: the 4:3
+ * cover, the title row with its right-hand metric chip, the cuisine · price
+ * line and the location line.
+ */
+export function PlaceCardSkeleton({ footer, className }: PlaceCardSkeletonProps) {
+  return (
+    <div aria-hidden="true" className={cn("flex w-full flex-col", className)}>
+      <Skeleton className="aspect-[4/3] w-full rounded-xl" />
+      <div className="mt-2.5 flex flex-col">
+        <div className="mb-1 flex items-center justify-between gap-2">
+          <Skeleton className="h-4 w-3/5" />
+          <Skeleton className="h-6 w-9 rounded-md" />
+        </div>
+        {/* `h-4` = the 16px line-height of the card's `text-xs` rows, so the
+            two meta lines land without a shift. */}
+        <div className="flex flex-col gap-0.5">
+          <Skeleton className="h-4 w-2/5" />
+          <Skeleton className="h-4 w-1/3" />
+        </div>
+        {footer && (
+          <>
+            <Separator className="my-2" />
+            <div>{footer}</div>
+          </>
+        )}
+      </div>
+    </div>
+  );
+}

package/src/components/place-types.ts

@@ -1,3 +1,5 @@
+import type { GradeAtomLabels } from './grade-atom'
+
 /**
  * Structural mirror of the openapi `Place` schema, decoupled from any one app's
  * generated types. Both FE and admin map their domain shapes into this type
@@ -49,6 +51,13 @@ export type PlacePreview = {
    *  admin: form's primary photo URL or blob URL).
    */
   thumbnail_url?: string
+  /**
+   * The card's cover photo. What `<PlaceCard>` renders in its 4:3 slot; with
+   * the default plain `<img>` this must be a loadable URL, with an injected
+   * `imageComponent` it is whatever that component accepts (fe passes the
+   * bare storage key straight to `next/image`'s loader).
+   */
+  cover_url?: string
 }
 
 export type PlaceHourBlock = { opens_at: number; closes_at: number }
@@ -69,6 +78,8 @@ export type PlacePriceRange = {
   price_range_high?: number
   /** Median price across the place's menu, in the local currency. */
   median_price?: number
+  /** 1–4 price level, rendered as `$` glyphs on `<PlaceCard>`. 0 / absent = no signal. */
+  price_score?: number
 }
 
 /**
@@ -176,11 +187,13 @@ export type PlaceReviewsDigest = {
 
 /** Labels passed to `<PlaceCard>`. All translation happens in the caller. */
 export type PlaceCardLabels = {
-  open: string
+  /** The frosted pill on the photo when `open_now === false`. */
   closed: string
-  until: string
-  opensAt: string
-  currency: string
+  /** Accessible name of the whole card, e.g. "View details for Casa Gri". */
+  viewDetails: (name: string) => string
+  /** Accessible name of the `$` price glyphs, e.g. "Price level 2 of 4". */
+  priceLevel: (level: number) => string
+  grade: GradeAtomLabels
 }
 
 /**