Aspect Ratio

/** @jsxImportSource hono/jsx */
import type { Child } from "hono/jsx"
import { cloneElement, isValidElement } from "hono/jsx"
import { cn, type ClassValue } from "@/registry/lib/cn"

// Aspect Ratio — shadcn-htmx, htmx v4 + Tailwind v4.
//
// A ratio-box wrapper that locks a child (image / video / iframe / embed /
// chart slot) to a fixed width-to-height ratio while it resizes fluidly,
// eliminating layout shift. One CSS declaration does all the work — there
// is no JavaScript here.
//
// shadcn/ui's upstream AspectRatio wraps Radix's primitive, which predates
// native browser support and emulates the ratio with a padding-bottom hack
// + absolute positioning. We do NOT copy that: the platform now ships the
// real thing, so we use the native CSS `aspect-ratio` property instead. No
// hacks (see AGENTS.md rule 4).
//   Upstream (anatomy only):
//     repos/shadcn-ui/apps/v4/registry/new-york-v4/ui/aspect-ratio.tsx
//
// Built on:
//   - CSS `aspect-ratio` — defines the desired width-to-height ratio of the
//     box; the browser keeps it as the box resizes. At least one of the
//     box's sizes must be automatic for it to take effect (we leave height
//     auto, width fluid).
//       repos/mdn/files/en-us/web/css/reference/properties/aspect-ratio/index.md
//   - CSS `object-fit` — how a replaced element (img/video) fills the box:
//     `cover` crops to fill, `contain` letterboxes to fit. Note object-fit
//     has no effect on <iframe>/<embed>, which already stretch to the box.
//       repos/mdn/files/en-us/web/css/reference/properties/object-fit/index.md
//   - web.dev "Aspect ratio image card" pattern (`aspect-ratio: 16 / 9`,
//     no padding-top hack):
//       repos/web.dev/src/site/content/en/patterns/layout/aspect-ratio-image-card/index.md
//
// Tailwind v4: `aspect-video` = 16/9, `aspect-square` = 1/1; any other
// ratio is the arbitrary `aspect-[w/h]` utility. `object-cover` /
// `object-contain` map to the object-fit keywords.

export type AspectRatioFit = "cover" | "contain"

// Named ratios mapped to Tailwind's stock aspect utilities; everything else
// falls through to the arbitrary `aspect-[w/h]` form below.
const NAMED_RATIO: Record<string, string> = {
  "1/1": "aspect-square",
  "16/9": "aspect-video",
}

const fitClasses: Record<AspectRatioFit, string> = {
  cover: "object-cover",
  contain: "object-contain",
}

// Turn a ratio prop into a Tailwind class. Accepts:
//   - a number   → 1.78        → aspect-[1.78]
//   - "16/9"     → aspect-video (or aspect-[w/h] for unmapped ratios)
function ratioClass(ratio: number | string): string {
  if (typeof ratio === "number") return `aspect-[${ratio}]`
  const key = ratio.replace(/\s+/g, "")
  return NAMED_RATIO[key] ?? `aspect-[${key}]`
}

type AspectRatioProps = {
  // Width-to-height ratio. A number (e.g. 1.778) or a "w/h" string
  // (e.g. "16/9", "4/3"). Defaults to a 16:9 video frame.
  ratio?: number | string
  // How a replaced child (img/video) fills the box. `cover` crops, `contain`
  // letterboxes. Ignored for non-replaced children (iframe/embed/div).
  fit?: AspectRatioFit
  class?: ClassValue
  id?: string
  // The locked element: an <img>, <video>, <iframe>, <embed>, or any block.
  // A single valid element child is cloned so the sizing + object-fit
  // classes land directly on it (the wrapper only carries the ratio).
  children?: Child
  // Forward hx-*, data-*, aria-*, and standard attributes onto the root.
  [key: string]: unknown
}

const root = "relative block w-full overflow-hidden"

export function AspectRatio(props: AspectRatioProps) {
  const {
    ratio = "16/9",
    fit = "cover",
    class: className,
    id,
    children,
    ...rest
  } = props

  const rootClasses = cn(root, ratioClass(ratio), className)

  // Annotate the single child so it stretches to fill the ratio box and
  // applies object-fit (mirrors button/tooltip cloneElement convention).
  let child: Child = children
  if (isValidElement(children)) {
    const el = children as any
    child = cloneElement(el, {
      "data-slot": "aspect-ratio-content",
      class: cn("size-full", fitClasses[fit], el?.props?.class),
    })
  }

  return (
    <div
      id={id}
      data-slot="aspect-ratio"
      data-ratio={typeof ratio === "number" ? String(ratio) : ratio}
      class={rootClasses}
      {...rest}
    >
      {child}
    </div>
  )
}

{# Aspect Ratio macro — shadcn-htmx, htmx v4 + Tailwind v4.
   Mirrors registry/ui/aspect-ratio.tsx.

   Locks the slotted child to a fixed width-to-height ratio with the native
   CSS `aspect-ratio` property (no padding-top hack) and `object-fit` for
   replaced elements. Zero JS.
     MDN aspect-ratio: repos/mdn/files/en-us/web/css/reference/properties/aspect-ratio/index.md
     MDN object-fit:   repos/mdn/files/en-us/web/css/reference/properties/object-fit/index.md
     web.dev pattern:  repos/web.dev/src/site/content/en/patterns/layout/aspect-ratio-image-card/index.md

   The slotted child (passed via {{ caller() }}) should carry
   `size-full object-cover` / `object-contain` itself so the fit lands on
   the replaced element — mirroring how the .tsx clones the child.

   Usage:
     {% from "components/aspect-ratio.html" import aspect_ratio %}
     {% call aspect_ratio(ratio="16/9") %}
       <img src="/photo.jpg" alt="…" class="size-full object-cover">
     {% endcall %} #}

{% macro aspect_ratio(ratio="16/9", id=none, extra_class="", **attrs) %}
{%- set ratio_class -%}
{%- if ratio == "1/1" -%}aspect-square{%- elif ratio == "16/9" -%}aspect-video{%- else -%}aspect-[{{ ratio | replace(' ', '') }}]{%- endif -%}
{%- endset -%}
<div
  {%- if id %} id="{{ id }}"{% endif %}
  data-slot="aspect-ratio"
  data-ratio="{{ ratio }}"
  class="relative block w-full overflow-hidden {{ ratio_class }} {{ extra_class }}"
  {%- for k, v in attrs.items() %} {{ k|replace('_','-') }}="{{ v }}"{% endfor %}>{{ caller() }}</div>
{% endmacro %}

{{/*
  Aspect Ratio template — shadcn-htmx, htmx v4 + Tailwind v4.
  Mirrors registry/ui/aspect-ratio.tsx.

  Locks the slotted child to a fixed width-to-height ratio with the native
  CSS `aspect-ratio` property (no padding-top hack) and `object-fit` for
  replaced elements. Zero JS.
    MDN aspect-ratio: repos/mdn/files/en-us/web/css/reference/properties/aspect-ratio/index.md
    MDN object-fit:   repos/mdn/files/en-us/web/css/reference/properties/object-fit/index.md
    web.dev pattern:  repos/web.dev/src/site/content/en/patterns/layout/aspect-ratio-image-card/index.md

      type AspectRatioArgs struct {
          Ratio string      // "16/9" (default) | "1/1" | "4/3" | …
          ID    string
          Class string
          Body  template.HTML // the slotted child, already carrying
                              // size-full object-cover / object-contain
      }
*/}}

{{define "aspect-ratio"}}
{{- $ratio := or .Ratio "16/9" -}}
{{- $ratioClass := printf "aspect-[%s]" $ratio -}}
{{- if eq $ratio "1/1" -}}{{- $ratioClass = "aspect-square" -}}{{- else if eq $ratio "16/9" -}}{{- $ratioClass = "aspect-video" -}}{{- end -}}
<div {{if .ID}}id="{{.ID}}" {{end}}data-slot="aspect-ratio" data-ratio="{{$ratio}}" class="relative block w-full overflow-hidden {{$ratioClass}} {{.Class}}">{{htmlSafe .Body}}</div>
{{end}}

defmodule ShadcnHtmx.Components.AspectRatio do
  @moduledoc """
  Aspect Ratio — shadcn-htmx, htmx v4 + Tailwind v4 for Phoenix.

  Mirrors registry/ui/aspect-ratio.tsx.

  Locks the slotted child (image / video / iframe / embed / chart) to a
  fixed width-to-height ratio with the native CSS `aspect-ratio` property
  (no padding-top hack) and `object-fit` for replaced elements. Zero JS.

    * MDN aspect-ratio:
      repos/mdn/files/en-us/web/css/reference/properties/aspect-ratio/index.md
    * MDN object-fit:
      repos/mdn/files/en-us/web/css/reference/properties/object-fit/index.md
    * web.dev pattern:
      repos/web.dev/src/site/content/en/patterns/layout/aspect-ratio-image-card/index.md

  The slotted child should carry `size-full object-cover` / `object-contain`
  so the fit lands on the replaced element — mirroring how the .tsx clones
  the child.

  ## Examples

      <.aspect_ratio ratio="16/9">
        <img src="/photo.jpg" alt="…" class="size-full object-cover" />
      </.aspect_ratio>

      <.aspect_ratio ratio="1/1">
        <img src="/avatar.jpg" alt="…" class="size-full object-cover" />
      </.aspect_ratio>
  """

  use Phoenix.Component

  @root "relative block w-full overflow-hidden"

  attr :ratio, :string, default: "16/9"
  attr :class, :string, default: nil
  attr :rest, :global
  slot :inner_block, required: true

  def aspect_ratio(assigns) do
    assigns =
      assigns
      |> assign(:root, @root)
      |> assign(:ratio_class, ratio_class(assigns.ratio))

    ~H"""
    <div
      data-slot="aspect-ratio"
      data-ratio={@ratio}
      class={[@root, @ratio_class, @class]}
      {@rest}
    >
      {render_slot(@inner_block)}
    </div>
    """
  end

  defp ratio_class("1/1"), do: "aspect-square"
  defp ratio_class("16/9"), do: "aspect-video"
  defp ratio_class(ratio), do: "aspect-[#{String.replace(ratio, " ", "")}]"
end

<!--
  shadcn-htmx — raw HTML aspect-ratio snippets.

  Locks the slotted child to a fixed width-to-height ratio with the native
  CSS `aspect-ratio` property (no padding-top hack). Replaced elements
  (img/video) get `object-fit` via object-cover / object-contain; iframe /
  embed already stretch to the box (object-fit has no effect on them).
  Zero JavaScript — Tailwind utilities only.

    MDN aspect-ratio: repos/mdn/files/en-us/web/css/reference/properties/aspect-ratio/index.md
    MDN object-fit:   repos/mdn/files/en-us/web/css/reference/properties/object-fit/index.md
    web.dev pattern:  repos/web.dev/src/site/content/en/patterns/layout/aspect-ratio-image-card/index.md

  ROOT:
    relative block w-full overflow-hidden  +  the ratio utility
  RATIO utility:
    1/1  → aspect-square
    16/9 → aspect-video
    any  → aspect-[w/h]   e.g. aspect-[4/3]
-->

<!-- 16:9 image, cropped to fill (object-cover) -->
<div data-slot="aspect-ratio" data-ratio="16/9"
     class="relative block w-full overflow-hidden aspect-video">
  <img src="/photo.jpg" alt="Mountain lake at dawn"
       data-slot="aspect-ratio-content"
       class="size-full object-cover">
</div>

<!-- 1:1 square, letterboxed to fit (object-contain) -->
<div data-slot="aspect-ratio" data-ratio="1/1"
     class="relative block w-full overflow-hidden aspect-square">
  <img src="/logo.png" alt="Brand logo"
       data-slot="aspect-ratio-content"
       class="size-full object-contain">
</div>

<!-- 16:9 responsive iframe (video embed) — object-fit has no effect here;
     the iframe simply stretches to the ratio box. -->
<div data-slot="aspect-ratio" data-ratio="16/9"
     class="relative block w-full overflow-hidden aspect-video">
  <iframe src="https://www.youtube-nocookie.com/embed/VIDEO_ID"
          title="Embedded video"
          data-slot="aspect-ratio-content"
          class="size-full" allowfullscreen></iframe>
</div>

<!-- Arbitrary 4:3 ratio with a plain content slot (e.g. a chart canvas) -->
<div data-slot="aspect-ratio" data-ratio="4/3"
     class="relative block w-full overflow-hidden aspect-[4/3]">
  <div data-slot="aspect-ratio-content"
       class="flex size-full items-center justify-center bg-muted text-muted-foreground">
    4 / 3 slot
  </div>
</div>