Safe Area

npx shadcn@latest add https://ui.zyeon.ai/r/safe-area.json

<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />

import type { Viewport } from "next"

export const viewport: Viewport = {
  width: "device-width",
  initialScale: 1,
  viewportFit: "cover",
}

Build a React + TypeScript + Tailwind "SafeArea" component — a wrapper that keeps
content clear of the device's safe-area insets (notch / Dynamic Island, rounded
corners, home indicator, landscape side rails). No dependencies, no animation.

Contract
- Export a forwardRef<HTMLElement> component extending
  React.HTMLAttributes<HTMLElement>; the root element is `as` (React.ElementType,
  default "div") so it can be a header/footer/nav/main.
- edges: ("top" | "right" | "bottom" | "left")[] — which physical edges get the
  inset. Default: all four.
- mode: "padding" | "margin" (default "padding").
- min: number | string (default 0) — a floor applied to every listed edge.
  Number means px; strings pass through ("1rem", "var(--gutter)", "calc(...)").
- Remaining props spread onto the root; consumer className is merged with cn();
  consumer `style` is spread AFTER the generated inset styles so it always wins.

Behavior
- For each listed edge write ONE longhand — paddingTop/…/paddingLeft in
  "padding" mode, marginTop/…/marginLeft in "margin" mode — with the value
  `max(var(--safe-area-inset-<edge>, env(safe-area-inset-<edge>, 0px)), <min>)`.
  Edges that were not listed are not written at all, so a className like "px-4"
  on those edges keeps working; on the edges you DO list the component owns the
  longhand, so express the base value with `min` instead of a p-* class.
- The var() indirection is deliberate: setting --safe-area-inset-top/right/
  bottom/left on any ancestor overrides or simulates the OS value (device-frame
  previews, desktop development, screenshot tests) without touching a component.
- min clamping: a number is emitted as "<n>px" with 0 / negative / NaN /
  Infinity collapsed to "0px". This matters — "NaNpx" would make the whole
  declaration invalid and drop the inset entirely, which is exactly the silent
  failure the component exists to prevent. A string min is trimmed and falls
  back to "0px" when empty.
- Never read the insets from JavaScript. env() is not exposed to script; there
  is no matchMedia, no ResizeObserver, no state. That is what keeps this a
  server component — do NOT add "use client".
- The insets are viewport geometry, not element geometry: env() returns the same
  number no matter where the element sits, so only wrap elements that really
  touch the physical edge.

Rendering & styling
- The component paints nothing of its own: no background, no border, no radius,
  no color — semantic tokens are whatever the children already use. It only
  writes up to four length declarations.
- No ARIA: it is a layout wrapper, not a widget; it adds no role and does not
  interfere with the focus order. Nothing animates, so prefers-reduced-motion is
  not applicable.
- Consumer setup (state this in your docs, it is the number one failure mode):
  `<meta name="viewport" content="width=device-width, initial-scale=1,
  viewport-fit=cover">` — without it every inset is 0 and the wrapper does
  nothing at all. In Next.js: `export const viewport: Viewport = { viewportFit:
  "cover" }`.

Composition rules worth documenting
- Bar pinned to the bottom: wrap the BAR in "padding" mode so its background
  bleeds under the home indicator while its controls sit above it. Never use
  "margin" on a position:fixed bottom-0 bar — the margin lifts it and exposes
  the page behind it.
- Scroll containers: the inset must go on the scrolled CONTENT, not around the
  scroll box. A pinned bar needs bar height + inset of clearance, which is a
  SUM, and max() cannot express a sum — put a fixed-height spacer as the last
  child of the scrolled content and wrap that spacer in SafeArea, so its total
  height becomes height + inset. Padding the scroll box from the outside leaves
  the last row permanently under the bar. Match the bar's OUTER height, border
  included: a 1px border-t on the bar and not on the spacer leaves the last row
  1px short (measured, not guessed). Keeping the border on the bar's inner row
  makes the two heights line up by construction.
- Portrait side insets are 0 even on a notched phone (the rounded corners are
  covered by the top inset, not by left/right ones). If you want content held
  off the corner radius in portrait, that is what `min` is for.

Customization levers
- Which edges: default all four for a full-screen shell; ["bottom"] for a tab
  bar or a sticky action row; ["top"] for a translucent header; ["left","right"]
  for landscape rails only.
- Floor: min=0 keeps the wrapper purely additive (desktop looks untouched);
  min=12–16 turns it into "at least this much padding, more where the OS needs
  it". For asymmetric floors nest two SafeAreas — one for the x edges, one for
  the y edges — each with its own min.
- Mode: "padding" when the wrapped box has its own background that should reach
  the physical edge; "margin" for a floating card, toast or FAB that should keep
  a gap outside its own border.
- Element: as="header" / "footer" / "nav" / "main" keeps the landmark semantics
  instead of adding a wrapper div.
- Override hook: rename --safe-area-inset-* if it collides with your own naming,
  or set it on a device-frame preview container to demo notched layouts on a
  desktop browser.