Figure

1/** @jsxImportSource hono/jsx */
2import type { Child, PropsWithChildren } from "hono/jsx"
3import { cn, type ClassValue } from "@/registry/lib/cn"
4 
5// Figure — shadcn-htmx, htmx v4 + Tailwind v4.
6//
7// Self-contained captioned content — an image, diagram, code block, or
8// quotation — wrapped in a native <figure> whose <figcaption> supplies the
9// figure's accessible name. Unlike <Card> (a generic styled surface),
10// <Figure> is *referential*: it stands apart from the main flow and can be
11// moved elsewhere without breaking it, and the caption is semantically tied
12// to the content. No interactivity, no JavaScript.
13//
14// Built on (native elements; we add nothing the platform doesn't ship):
15//   - <figure> — represents self-contained content, optionally captioned;
16//     the figure, its caption, and its contents are one unit. Implicit ARIA
17//     role "figure".
18//       repos/mdn/files/en-us/web/html/reference/elements/figure/index.md
19//   - <figcaption> — caption/legend for the parent <figure>; provides the
20//     <figure> its accessible name. Must be the figure's first or last child
21//     (the first <figcaption> found is presented as the caption).
22//       repos/mdn/files/en-us/web/html/reference/elements/figcaption/index.md
23//
24// Anatomy mirrors shadcn's Card family (read for intent only, not copied —
25// different element, different semantics):
26//   repos/shadcn-ui/apps/v4/registry/new-york-v4/ui/card.tsx
27//
28// Theme tokens only: border / bg-card / text-card-foreground for the surface,
29// text-muted-foreground for the caption, bg-muted for plain content slots.
30 
31// Where the caption sits relative to the content. Both are valid per the
32// spec (first OR last child); we render the <figcaption> in the chosen DOM
33// position so the accessible name is correct either way.
34export type FigureCaptionSide = "top" | "bottom"
35 
36type FigureProps = PropsWithChildren<{
37  class?: ClassValue
38  id?: string
39  // Caption position. "bottom" (default) reads as a credit/label under the
40  // content; "top" reads as a legend introducing it (common for code blocks
41  // and quotations). See the MDN figure examples.
42  captionSide?: FigureCaptionSide
43  // Forward hx-*, data-*, aria-* and standard global attributes onto the
44  // <figure> root.
45  [key: string]: unknown
46}>
47 
48// Surface: a bordered card-like box. We keep it visually distinct from the
49// document body but lighter than a full Card (no shadow) so it reads as
50// … truncated