{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "hero",
  "title": "Hero",
  "description": "The top of a page: a headline with an optional line above it (`eyebrow`) and a status beside that (`badge`), a trail above them (`breadcrumb`), a lede under the headline (`description`), the page's buttons (`actions`), more such as a byline (`children`), and a big picture, or something live in its place (`media`), below.",
  "registryDependencies": [
    "@ouro/heading",
    "@ouro/lib-class-name-check",
    "@ouro/lib-cn",
    "@ouro/lib-env",
    "@ouro/lib-use-dev-messages"
  ],
  "files": [
    {
      "path": "registry/ouro/components/ouro/hero/hero.tsx",
      "content": "\"use client\";\n\nimport { useLayoutEffect, useRef, useState, useSyncExternalStore, type CSSProperties, type HTMLAttributes, type JSX, type ReactNode, type Ref } from \"react\";\nimport { useAppearanceClassNameCheck } from \"@/registry/ouro/lib/ouro/class-name-check\";\nimport { cn } from \"@/registry/ouro/lib/ouro/cn\";\nimport { useDevWarnings } from \"@/registry/ouro/lib/ouro/use-dev-messages\";\nimport { Heading } from \"@/registry/ouro/components/ouro/text/heading\";\n\n/** How the hero is laid out: `stage` centres the text over a wide picture; `column` aligns both to a reading column; `split` sets the copy beside the media. */\nexport type HeroLayout = \"stage\" | \"column\" | \"split\";\n\n/** One `<source>` element of a hero picture, in the order given. */\nexport interface HeroPictureSource {\n  /** The source's `srcset`, such as an AVIF or WebP file. */\n  srcSet: string;\n  /** The MIME type, such as `image/avif`. */\n  type?: string;\n  /** A media query that picks this source, such as `(max-width: 40rem)`. */\n  media?: string;\n  /** The `sizes` for this source. */\n  sizes?: string;\n  /**\n   * This source's intrinsic pixel width, when its art has another shape than the picture's own,\n   * such as a phone crop. With `height`, it holds the image's box to this source's shape before\n   * the file arrives, so the page doesn't shift.\n   *\n   * @claim \"it holds the image's box to this source's shape\" registry/ouro/components/ouro/hero/hero.test.tsx verify:testExists(registry/ouro/components/ouro/hero/hero.test.tsx::Hero > gives each source its own width and height, so a source of another shape holds its box before it loads)\n   */\n  width?: number;\n  /** This source's intrinsic pixel height, with `width`. */\n  height?: number;\n}\n\n/**\n * The hero's picture. It never shows wider than its intrinsic `width`.\n *\n * @claim \"It never shows wider than its intrinsic\" registry/ouro/components/ouro/hero/hero.test.tsx verify:testExists(registry/ouro/components/ouro/hero/hero.test.tsx::Hero > never shows the picture wider than its intrinsic width)\n */\nexport interface HeroPicture {\n  /** The fallback `<img>` file. */\n  src: string;\n  /**\n   * The intrinsic pixel width of the wide file. The picture is never shown wider than this.\n   *\n   * @claim \"The picture is never shown wider than this\" registry/ouro/components/ouro/hero/hero.test.tsx verify:testExists(registry/ouro/components/ouro/hero/hero.test.tsx::Hero > never shows the picture wider than its intrinsic width)\n   */\n  width: number;\n  /** The intrinsic pixel height, which sets the picture's aspect ratio and stops layout shift. */\n  height: number;\n  /** What the picture shows. Required unless `decorative` is set. */\n  alt?: string;\n  /** Hides the picture from assistive technology, with `alt=\"\"`. */\n  decorative?: boolean;\n  /** `<source>` elements, in order: for example phone formats with a `media` query, then wide formats. */\n  sources?: HeroPictureSource[];\n  /** The `<img>`'s `srcset`. */\n  srcSet?: string;\n  /** The `<img>`'s `sizes`. */\n  sizes?: string;\n  /** Loads the picture early with `fetchPriority=\"high\"`. Otherwise it loads lazily. In `{ light, dark }`, see `HeroPictures` for how each twin loads. */\n  priority?: boolean;\n  /**\n   * A wide aspect ratio, such as `\"8 / 3\"`, applied on wider screens in the stage and column\n   * layouts. Without it the picture keeps its own ratio, as it does on a phone and in the split\n   * layout, so a wide crop never cuts the subject in the split layout's narrower column.\n   *\n   * @claim \"as it does on a phone and in the split\" registry/ouro/components/ouro/hero/hero.test.tsx verify:testExists(registry/ouro/components/ouro/hero/hero.test.tsx::Hero > shows the whole picture in the split layout, so a wide crop never cuts its subject in the narrower column)\n   */\n  crop?: string;\n  /**\n   * The focal point kept in view when the picture is cropped, as an `object-position`, such as\n   * `\"50% 80%\"` for a subject near the bottom. Set it on each picture: the dark one takes the\n   * light one's unless it has its own.\n   *\n   * @claim \"the dark one takes the light one's unless it has its own\" registry/ouro/components/ouro/hero/hero.test.tsx verify:testExists(registry/ouro/components/ouro/hero/hero.test.tsx::Hero > gives the dark picture the light one's focus unless it has its own)\n   * @default \"50% 42%\"\n   */\n  focus?: string;\n  /**\n   * A colour painted in the picture's box while the image loads, such as the art's main colour,\n   * in place of an empty hole. It fills the box the `width` and `height` already reserve, so it\n   * moves nothing, and an opaque image covers it once it decodes. Give the dark picture its own,\n   * as it never takes the light one's: a day colour would flash at night. Hero has the file's\n   * address but not its pixels, so take the colour from your image pipeline, for example the\n   * `dominant` colour of `sharp(file).stats()`, or pick it by eye. Leave it out for art with\n   * transparency, which would show it through.\n   *\n   * @claim \"as it never takes the light one's\" registry/ouro/components/ouro/hero/hero.test.tsx verify:testExists(registry/ouro/components/ouro/hero/hero.test.tsx::Hero > paints each picture's placeholder behind it while it loads, and the day's never at night)\n   */\n  placeholder?: string;\n}\n\n/**\n * The hero's art in light and dark mode: the same scene by day and at night. Hero shows `light`\n * or `dark` in CSS, with your app's Tailwind `dark` variant, the one every Ouro component's dark\n * styles follow, so the right one is there from the first paint. That variant reads the `.dark`\n * class Ouro's `colorSchemeScript` sets; a site that marks dark mode with `data-theme` or the\n * system setting redefines it, as the theming guide's [dark mode recipe](guides/theming.md#dark-mode)\n * shows, and Hero follows.\n *\n * `dark` shares `light`'s frame: its `width` and `crop` size the box. It is the same scene, so\n * without its own `alt`, `decorative` or `focus` it takes `light`'s.\n *\n * `priority` decides how the twin that shows loads. A twin without it is lazy, and a hidden lazy\n * image is never fetched. Give `priority` to the twin most of your visitors see, and it loads\n * straight from the HTML at high fetch priority while the other stays lazy. Give it to both to\n * fetch the twin for the page's scheme once: add `heroPreloadScript` to the `<head>` right after\n * `colorSchemeScript`, with the same `picture`, as\n * `<script dangerouslySetInnerHTML={{ __html: colorSchemeScript() + heroPreloadScript({ light, dark }) }} />`.\n * The HTML then holds neither twin's address. An inline script after the pictures copies the shown\n * twin's address onto it, and the hidden twin stays empty until the page hydrates.\n * Without JavaScript, both twins sit in a `<noscript>`, and the CSS shows the one for the page's scheme.\n * A page that can't run inline scripts gets its picture from React after hydration.\n *\n * @claim \"Hero shows `light`\" registry/ouro/components/ouro/hero/hero.test.tsx verify:testExists(registry/ouro/components/ouro/hero/hero.test.tsx::Hero > shows the dark picture only while the page is in dark mode)\n * @claim \"and a hidden lazy\" registry/ouro/components/ouro/hero/hero.test.tsx verify:testExists(registry/ouro/components/ouro/hero/hero.test.tsx::Hero > keeps a lone priority twin eager in the HTML and the other lazy, at high fetch priority)\n * @claim \"and it loads\" registry/ouro/components/ouro/hero/hero.test.tsx verify:testExists(registry/ouro/components/ouro/hero/hero.test.tsx::Hero > keeps a lone priority twin eager in the HTML and the other lazy, at high fetch priority)\n * @claim \"fetch the twin for the page's scheme once\" site/e2e/hero-preload.spec.ts verify:testExists(site/e2e/hero-preload.spec.ts::a hero whose twins both have priority > fetches the twin for the page's scheme once, for a stored dark choice with the system in light)\n * @claim \"The HTML then holds neither twin's address\" registry/ouro/components/ouro/hero/hero.test.tsx verify:testExists(registry/ouro/components/ouro/hero/hero.test.tsx::Hero > holds neither twin's address in the HTML of a pair both priority, until the script copies the shown one's)\n * @claim \"copies the shown twin's address onto it\" registry/ouro/components/ouro/hero/hero.test.tsx verify:testExists(registry/ouro/components/ouro/hero/hero.test.tsx::Hero > copies the shown twin's addresses onto it from server HTML, and leaves the hidden one empty)\n * @claim \"the hidden twin stays empty until the page hydrates\" registry/ouro/components/ouro/hero/hero.test.tsx verify:testExists(registry/ouro/components/ouro/hero/hero.test.tsx::Hero > copies the shown twin's addresses onto it from server HTML, and leaves the hidden one empty)\n * @claim \"both twins sit in a `<noscript>`\" site/e2e/hero-preload.spec.ts verify:testExists(site/e2e/hero-preload.spec.ts::a hero whose twins both have priority > without JavaScript, the noscript twins are the pictures shown, and each file loads once)\n * @claim \"A page that can't run inline\" registry/ouro/components/ouro/hero/hero.test.tsx verify:testExists(registry/ouro/components/ouro/hero/hero.test.tsx::Hero > gives the shown twin its address after hydration where the page's scripts did not run)\n * @claim \"redefines it, as the theming guide's\" docs/guides/theming.md verify:fileLine(docs/guides/theming.md, /@custom-variant dark/)\n */\nexport interface HeroPictures {\n  /** The art shown in light mode, and the frame both are shown in. */\n  light: HeroPicture;\n  /** The same scene at night, shown in dark mode. */\n  dark: HeroPicture;\n}\n\n/** The props Hero adds to the `<header>` attributes it passes through. */\nexport interface HeroOwnProps {\n  /** The hero's headline, its `<h1>` (or `<h2>` with `headingLevel={2}`). Required. */\n  title: ReactNode;\n  /**\n   * A trail above everything else, such as a `Breadcrumb`, on the text's edge.\n   *\n   * @claim \"A trail above everything else\" registry/ouro/components/ouro/hero/hero.test.tsx verify:testExists(registry/ouro/components/ouro/hero/hero.test.tsx::Hero > puts the trail above the eyebrow and the badge beside it, on the text's edge)\n   */\n  breadcrumb?: ReactNode;\n  /** A short line above the title that says what kind of page this is. */\n  eyebrow?: ReactNode;\n  /**\n   * A short status beside the eyebrow, such as a `Badge`: `badge={<Badge>Beta</Badge>}`. Hero\n   * sets it on the eyebrow's line, or on that line alone without an eyebrow, and leaves its look\n   * to what you pass.\n   *\n   * @claim \"Hero sets it on the eyebrow's line\" registry/ouro/components/ouro/hero/hero.test.tsx verify:testExists(registry/ouro/components/ouro/hero/hero.test.tsx::Hero > puts the trail above the eyebrow and the badge beside it, on the text's edge)\n   */\n  badge?: ReactNode;\n  /**\n   * The lede: a short paragraph under the title. Text is set in a `<p>`; anything else, such as\n   * paragraphs or a list, is set in a `<div>` so it can hold blocks, and Hero clears its first\n   * block's top margin and its last block's bottom margin, so a paragraph needs no `m-0`. It runs the full width of the\n   * hero's text column, like the title. Its lines are balanced to even lengths in every layout, so\n   * the last line is never left short; a lede longer than the browser balances, a few lines, wraps\n   * as usual. To choose where a lede breaks, set each phrase in its own `inline-block` span,\n   * as the `LongLede` story does.\n   *\n   * @claim \"and Hero clears its first\" registry/ouro/components/ouro/hero/hero.test.tsx verify:testExists(registry/ouro/components/ouro/hero/hero.test.tsx::Hero > clears the outer margins of the lede's first and last blocks, and keeps the space between them)\n   * @claim \"Its lines are balanced to even lengths\" registry/ouro/components/ouro/hero/hero.test.tsx verify:testExists(registry/ouro/components/ouro/hero/hero.test.tsx::Hero > balances the lede in each layout, so its last line is never short)\n   *\n   * @claim \"It runs the full width\" registry/ouro/components/ouro/hero/hero.test.tsx verify:testExists(registry/ouro/components/ouro/hero/hero.test.tsx::Hero > runs the lede the full width of the text column in each layout)\n   */\n  description?: ReactNode;\n  /**\n   * The hero's buttons or links, such as Ouro buttons. They sit right under the lede, its next\n   * element, on the lede's edge, set a little further from it than the lines of text are from\n   * each other. Pass the page's main button here, not in `description`.\n   *\n   * @claim \"They sit right under the lede\" registry/ouro/components/ouro/hero/hero.test.tsx verify:testExists(registry/ouro/components/ouro/hero/hero.test.tsx::Hero > sets the actions right under the lede, a step further from it than the lines of text, on the lede's edge)\n   */\n  actions?: ReactNode;\n  /**\n   * The big picture, shown under the text: `{ light, dark }`, the same scene by day and at\n   * night, swapped with the page's dark mode. Both are required: a hero has night art.\n   *\n   * Once the picture shown has loaded, the media frame carries `data-loaded`, so a site or a test\n   * can wait on `[data-slot=\"media\"][data-loaded]`. A small inline script in the server's HTML\n   * sets it before any JavaScript bundle runs, and Hero sets it itself after hydration or a client\n   * render, so it also arrives where a content security policy blocks inline scripts.\n   *\n   * @claim \"A small inline script in the server's HTML\" registry/ouro/components/ouro/hero/hero.test.tsx verify:testExists(registry/ouro/components/ouro/hero/hero.test.tsx::Hero > marks the frame data-loaded once the picture shown has loaded, from server HTML with no hydration)\n   * @claim \"so it also arrives where a content security policy blocks inline scripts\" registry/ouro/components/ouro/hero/hero.test.tsx verify:testExists(registry/ouro/components/ouro/hero/hero.test.tsx::Hero > marks a picture that loaded before hydration once it hydrates, where the page's scripts did not run)\n   */\n  picture?: HeroPictures | undefined;\n  /**\n   * More under the actions, in the text column, such as a byline, a note or a short recording. In\n   * the split layout it sits beside the picture. A second picture or a demo belongs in the next\n   * section, not the hero.\n   *\n   * @claim \"In the split layout it sits beside the picture\" registry/ouro/components/ouro/hero/hero.test.tsx verify:testExists(registry/ouro/components/ouro/hero/hero.test.tsx::Hero > sets more under the actions in the text column, beside the art in the split layout)\n   */\n  children?: ReactNode;\n  /** Something live in the picture's place, such as a video, a demo or a scene. It rises in like a picture and fills the hero's width, up to `mediaWidth`. Use `picture` for a still image. */\n  media?: ReactNode;\n  /**\n   * The widest the live `media` is shown, in pixels, such as a scene image's intrinsic width, so it is never\n   * upscaled. Without it the media fills the hero's width. A `picture` uses its own `width` instead.\n   *\n   * @claim \"so it is never upscaled\" registry/ouro/components/ouro/hero/hero.test.tsx verify:testExists(registry/ouro/components/ouro/hero/hero.test.tsx::Hero > never shows live media wider than mediaWidth)\n   */\n  mediaWidth?: number | undefined;\n  /**\n   * Stretches the hero to the width of its container, with no gutter or cap of its own, for a hero\n   * inside a page column that already sets the width. Without it the hero keeps a gutter at either\n   * side and caps its width.\n   *\n   * @claim \"Stretches the hero to the\" registry/ouro/components/ouro/hero/hero.test.tsx verify:testExists(registry/ouro/components/ouro/hero/hero.test.tsx::Hero > takes its container's width with fullWidth, with no gutter or cap of its own)\n   */\n  fullWidth?: boolean | undefined;\n  /**\n   * `stage` centres the text over the picture; `column` aligns both to a reading column; `split` puts the copy and the media side by side from 64rem, and stacks them like `column` below that, for a page whose picture or live media belongs next to its words.\n   *\n   * @claim \"puts the copy and the media side by side from 64rem\" registry/ouro/components/ouro/hero/hero.test.tsx verify:testExists(registry/ouro/components/ouro/hero/hero.test.tsx::Hero > switches to the split layout, with copy and media side by side from 64rem)\n   * @default \"stage\"\n   */\n  layout?: HeroLayout | (string & { 'Use \"stage\", \"column\" or \"split\"': never }) | undefined;\n  /**\n   * `rise` lifts the picture into place when it first appears, with reduced motion fading it in. The\n   * rise is a CSS transition from `@starting-style` in Hero's own classes, so it plays from\n   * server-rendered HTML before any JavaScript runs, and it needs no keyframes and no stylesheet to\n   * import. It takes its duration and easing from `ouro-base`'s `--ouro-duration-slow`,\n   * `--ouro-duration-fast` and `--ouro-ease-out`. The wrapper carries `data-starting-style` only\n   * while a hydrated page sees the rise running, so server HTML that never hydrates, such as an Astro\n   * page without client JavaScript, carries no marker.\n   *\n   * @claim \"so server HTML that never hydrates\" registry/ouro/components/ouro/hero/hero.test.tsx verify:testExists(registry/ouro/components/ouro/hero/hero.test.tsx::Hero > marks the rise only while it runs, so server HTML that never hydrates carries no marker)\n   * @claim \"so it plays from server-rendered HTML\" registry/ouro/components/ouro/hero/hero.test.tsx verify:testExists(registry/ouro/components/ouro/hero/hero.test.tsx::Hero > rises the picture in from server-rendered HTML before any JavaScript runs, and only fades it with reduced motion)\n   * @claim \"it needs no keyframes and no stylesheet\" registry/ouro/components/ouro/hero/hero.test.tsx verify:testExists(registry/ouro/components/ouro/hero/hero.test.tsx::Hero > rises with no keyframes: its own transition, on ouro-base's durations and easing)\n   * @default \"rise\"\n   */\n  motion?: \"rise\" | \"none\" | (string & { 'Use \"rise\" or \"none\"': never }) | undefined;\n  /** The title's heading level: `1` for the page's headline, `2` when the hero heads a section. @default 1 */\n  headingLevel?: 1 | 2 | (number & { 'Use 1 for the page headline or 2 for a section': never }) | undefined;\n  ref?: Ref<HTMLElement> | undefined;\n\n  /** Not a prop. The lede is `description`: `<Hero description=\"…\" />`. */\n  subtitle?: { 'Use <Hero description=\"...\" />': never };\n  /** Not a prop. The headline is `title`: `<Hero title=\"Dinner, sorted\" />`. */\n  heading?: { 'Use <Hero title=\"Dinner, sorted\" />': never };\n  /** Not a prop. The line above the title is `eyebrow`: `<Hero eyebrow=\"Recipes\" />`. */\n  overline?: { 'Use <Hero eyebrow=\"Recipes\" />': never };\n  /** Not a prop. The picture is `picture`: `<Hero picture={{ light: { src, width, height, alt }, dark: { src, width, height } }} />`. */\n  image?: { 'Use picture={{ light, dark }}': never };\n  /** Not a prop. The buttons are `actions`: `<Hero actions={<Button>Start</Button>} />`. */\n  action?: { 'Use actions={<Button>Start</Button>}': never };\n}\n\n/** Props for {@link Hero}: its own props and the `<header>` attributes it passes through. */\nexport type HeroProps = Omit<HTMLAttributes<HTMLElement>, keyof HeroOwnProps> & HeroOwnProps;\n\n// The rise is a transition from @starting-style, in the hero's own classes, so it needs no keyframes\n// and no script. Its durations and easing are ouro-base's tokens, which every app loads.\nconst riseMotion =\n  \"starting:opacity-0 motion-safe:[transition:opacity_var(--ouro-duration-slow)_var(--ouro-ease-out),transform_var(--ouro-duration-slow)_var(--ouro-ease-out)] motion-safe:starting:[transform:translateY(1rem)] motion-reduce:[transition:opacity_var(--ouro-duration-fast)_var(--ouro-ease-out)]\";\n\nconst layoutRoot: Record<HeroLayout, string> = {\n  stage:\n    \"[--hero-width:calc(100%_-_2rem)] min-[40rem]:[--hero-width:min(80rem,calc(100%_-_4rem),max(48rem,calc((100svh_-_36rem)*8/3)))]\",\n  column: \"[--hero-width:calc(100%_-_2rem)] min-[40rem]:[--hero-width:min(75rem,calc(100%_-_4rem))]\",\n  split: \"mx-auto w-[calc(100%_-_2rem)] pt-10 [--hero-width:100%] min-[40rem]:w-[min(75rem,calc(100%_-_4rem))] min-[40rem]:pt-12\",\n};\n\n// A full-width hero takes its container's width: no gutter and no cap.\nconst fullWidthRoot: Record<HeroLayout, string> = {\n  stage: \"[--hero-width:100%]\",\n  column: \"[--hero-width:100%]\",\n  split: \"w-full pt-10 [--hero-width:100%] min-[40rem]:pt-12\",\n};\n\n// Split sets the copy and the media side by side only when there is media to set beside it.\nconst splitColumns = \"min-[64rem]:grid-cols-[minmax(0,1.15fr)_minmax(0,0.85fr)] min-[64rem]:items-center min-[64rem]:gap-16\";\n\nconst layoutText: Record<HeroLayout, string> = {\n  stage: \"mx-auto grid w-[calc(100%_-_2rem)] min-[40rem]:w-[min(80rem,calc(100%_-_4rem))] justify-items-center gap-4 pt-6 text-center min-[40rem]:pt-12\",\n  column: \"mx-auto grid w-[var(--hero-width)] justify-items-start gap-4 text-start pt-10 min-[40rem]:pt-12\",\n  split: \"grid w-[var(--hero-width)] min-w-0 justify-items-start gap-4 text-start\",\n};\n\nconst fullWidthStageText = \"mx-auto grid w-full justify-items-center gap-4 pt-6 text-center min-[40rem]:pt-12\";\n\n\nconst layoutActions: Record<HeroLayout, string> = {\n  stage: \"justify-center\",\n  column: \"justify-start\",\n  split: \"justify-start\",\n};\n\nconst layoutMedia: Record<HeroLayout, string> = {\n  stage: \"mx-auto mt-8 min-[40rem]:mt-12\",\n  column: \"mx-auto mt-8\",\n  split: \"mx-auto mt-8 min-[64rem]:mt-0\",\n};\n\n// A twinned picture shows only in its scheme. The hidden one is display: none, so assistive\n// technology hears one picture, and a lazy image that is not shown is never fetched.\nconst schemeClass = { light: \"dark:hidden\", dark: \"hidden dark:block\" } as const;\n\n// Run as the parser reaches it, after the pictures and once the page's CSS has loaded: it marks the\n// frame `data-loaded` once the picture shown has loaded. For urgent twins (`u`) it loads that\n// picture now, leaving the hidden one lazy, so it is never fetched. For a deferred pair (`d`) the\n// HTML holds the addresses in `data-` attributes, and it copies the shown twin's onto its sources\n// and `<img>`, sources first, so the browser picks the same candidate the preload did.\nconst firstPaintScript = (urgent: boolean, deferred?: boolean) =>\n  `(function(s,u,d){function c(e,a){var v=e.getAttribute(\"data-\"+a);if(v!==null)e.setAttribute(a,v)}var f=s.parentNode,p=f.children;for(var i=0;i<p.length;i++){var g=p[i].tagName===\"PICTURE\"&&getComputedStyle(p[i]).display!==\"none\"&&p[i].querySelector(\"img\");if(g){if(d){for(var j=0,q=p[i].querySelectorAll(\"source\");j<q.length;j++)c(q[j],\"srcset\");c(g,\"srcset\");c(g,\"src\")}if(u&&g.loading===\"lazy\")g.loading=\"eager\";var e2=function(){f.setAttribute(\"data-loaded\",\"\")};if(g.complete&&g.naturalWidth)e2();else g.addEventListener(\"load\",e2)}}})(document.currentScript,${urgent ? 1 : 0},${deferred ? 1 : 0})`;\n\n/** Whether the picture holding this image is the one shown, rather than its twin for the other scheme. */\nconst isShown = (image: HTMLImageElement) => getComputedStyle(image.parentElement!).display !== \"none\";\n\n// Stryker disable next-line ArrowFunction: the type never changes after hydration, so nothing subscribes and the unsubscribe has nothing to undo.\nconst noSubscription = () => () => {};\nconst clientScriptType = () => \"text/plain\";\nconst serverScriptType = () => undefined;\n\n// A deferred pair's server HTML, and hydration, hold no addresses; a client render has them.\nconst clientHasAddresses = () => true;\n// Stryker disable next-line ArrowFunction: undefined reads as false, the same \"no addresses yet\".\nconst serverHasAddresses = () => false;\n\n/**\n * The script, in the server's HTML only. A client render marks it as data, which React neither runs\n * nor warns about; hydration keeps the server's type until it has adopted the script, which has run.\n */\nfunction FirstPaintScript({ urgent, deferred }: { urgent: boolean; deferred?: boolean }): JSX.Element {\n  const type = useSyncExternalStore(noSubscription, clientScriptType, serverScriptType);\n  return <script type={type} dangerouslySetInnerHTML={{ __html: firstPaintScript(urgent, deferred) }} />;\n}\n\n// The dark twin is the same scene as `day`, so it takes day's alt text, decorative flag and focus unless it has its own.\n// `eager` loads it straight from the HTML; `urgent` fetches it first once it loads, and lets the script flip it.\n// `deferred` is set on a twin of a pair both `priority`: `data` keeps its addresses in `data-` attributes for the\n// first-paint script to copy, and `live` renders them as a client render does. Such a twin is hidden without scripts.\nfunction renderPicture(\n  picture: HeroPicture,\n  crop: string | undefined,\n  scheme: \"light\" | \"dark\" | undefined,\n  load: { eager: boolean; urgent: boolean; onLoad: (image: HTMLImageElement) => void; deferred?: \"data\" | \"live\" | undefined },\n  day?: HeroPicture,\n): JSX.Element {\n  const decorative = picture.decorative ?? day?.decorative;\n  const data = load.deferred === \"data\";\n  return (\n    <picture\n      key={scheme}\n      data-scheme={scheme}\n      aria-hidden={decorative ? true : undefined}\n      className={cn(\"block\", scheme && schemeClass[scheme], load.deferred !== undefined && \"[@media(scripting:none)]:hidden\")}\n    >\n      {picture.sources?.map((source) => {\n        // Stryker disable next-line LogicalOperator,StringLiteral: the key only keeps React's list stable; no output reads it.\n        const key = `${source.type ?? \"\"}-${source.media ?? \"\"}-${source.srcSet}`;\n        const addresses = data ? { \"data-srcset\": source.srcSet } : { srcSet: source.srcSet };\n        return (\n          <source\n            key={key}\n            {...addresses}\n            type={source.type}\n            media={source.media}\n            sizes={source.sizes}\n            width={source.width}\n            height={source.height}\n            suppressHydrationWarning={data}\n          />\n        );\n      })}\n      <img\n        data-slot=\"image\"\n        // Before the addresses: WebKit fetches an image given its address while it is still eager, as a hydrated twin is.\n        loading={load.eager ? undefined : \"lazy\"}\n        {...(data ? { \"data-src\": picture.src, \"data-srcset\": picture.srcSet } : { src: picture.src, srcSet: picture.srcSet })}\n        sizes={picture.sizes}\n        width={picture.width}\n        height={picture.height}\n        alt={decorative ? \"\" : (picture.alt ?? day?.alt)}\n        draggable={false}\n        fetchPriority={load.urgent ? \"high\" : undefined}\n        decoding={load.urgent ? undefined : \"async\"}\n        // The first-paint script may have set loading=\"eager\" before React hydrates.\n        suppressHydrationWarning={load.urgent}\n        onLoad={(event) => load.onLoad(event.currentTarget)}\n        style={{ objectPosition: picture.focus ?? day?.focus ?? \"50% 42%\", backgroundColor: picture.placeholder }}\n        className={cn(\n          \"block h-auto w-full object-cover select-none\",\n          crop && \"min-[40rem]:absolute min-[40rem]:inset-0 min-[40rem]:h-full\",\n        )}\n      />\n    </picture>\n  );\n}\n\n/**\n * A pair both `priority`. Its server HTML holds neither twin's addresses, so nothing loads until the first-paint\n * script copies the shown twin's onto it. A `<noscript>` carries both twins for a page without scripts. A client\n * render, and a page once it hydrates, has the addresses, both lazy: the shown twin, on screen, loads, and the\n * hidden one loads only on a change of scheme.\n */\nfunction TwinPictures({\n  light,\n  dark,\n  crop,\n  onLoad,\n}: {\n  light: HeroPicture;\n  dark: HeroPicture;\n  crop: string | undefined;\n  onLoad: (image: HTMLImageElement) => void;\n}): JSX.Element {\n  const live = useSyncExternalStore(noSubscription, clientHasAddresses, serverHasAddresses);\n  // Stryker disable next-line StringLiteral: renderPicture tests only \"data\" and undefined, so \"live\" and any other value render alike.\n  const deferred = live ? \"live\" : \"data\";\n  // In the HTML both wait eager, for the script to give the shown one its addresses. With addresses both are lazy:\n  // the shown one, on screen, loads (or has loaded), and the hidden one waits for a change of scheme. Which one shows\n  // is the page's CSS's to say, so it is not guessed from a class here.\n  return (\n    <>\n      {renderPicture(light, crop, \"light\", { eager: !live, urgent: true, onLoad, deferred })}\n      {renderPicture(dark, crop, \"dark\", { eager: !live, urgent: true, onLoad, deferred }, light)}\n      <FirstPaintScript urgent deferred />\n      <noscript>\n        {renderPicture(light, crop, \"light\", { eager: false, urgent: true, onLoad })}\n        {renderPicture(dark, crop, \"dark\", { eager: false, urgent: true, onLoad }, light)}\n      </noscript>\n    </>\n  );\n}\n\n/**\n * The top of a page: a headline with an optional line above it (`eyebrow`) and a status beside\n * that (`badge`), a trail above them (`breadcrumb`), a lede under the headline (`description`),\n * the page's buttons (`actions`), more such as a byline (`children`), and a big picture, or\n * something live in its place (`media`), below. The picture is light and dark art, swapped with the page's dark\n * mode. The picture rises into place when it first appears unless `motion=\"none\"`,\n * and it is never shown wider than its intrinsic width. Its frame takes the theme's xl corners,\n * in Ouro's corner shape.\n *\n * Use `PageHeader` instead for a page's top with no picture, and `Heading`\n * for a plain title with nothing around it.\n *\n * @claim \"it is never shown wider than its intrinsic width\" registry/ouro/components/ouro/hero/hero.test.tsx verify:testExists(registry/ouro/components/ouro/hero/hero.test.tsx::Hero > never shows the picture wider than its intrinsic width)\n * @claim \"Its frame takes the theme's xl corners\" registry/ouro/components/ouro/hero/hero.test.tsx verify:testExists(registry/ouro/components/ouro/hero/hero.test.tsx::Hero > frames the picture with the theme's xl squircle corners)\n * @group Layout\n * @see https://ui.ouroboros.bot/docs/hero\n *\n * @example\n * <Hero\n *   eyebrow=\"Recipes\"\n *   title=\"Dinner, sorted\"\n *   description=\"Plan the week, shop once, cook without the scramble.\"\n *   actions={<Button>Start planning</Button>}\n *   picture={{\n *     light: { src: \"/hero.jpg\", width: 1536, height: 576, alt: \"A table set for four\" },\n *     dark: { src: \"/hero-night.jpg\", width: 1536, height: 576 },\n *   }}\n * />\n */\nexport function Hero(props: HeroProps): JSX.Element {\n  const {\n    title,\n    breadcrumb,\n    eyebrow,\n    badge,\n    description,\n    actions,\n    children,\n    picture,\n    media,\n    mediaWidth,\n    fullWidth = false,\n    layout: layoutProp = \"stage\",\n    motion: motionProp = \"rise\",\n    headingLevel: headingLevelProp = 1,\n    // Guard props (hint types), dropped here so they never reach the DOM.\n    subtitle,\n    heading,\n    overline,\n    image,\n    action,\n    className,\n    ...rest\n  } = props;\n  // A lede that is only text is a paragraph; one made of blocks needs a <div> to be valid HTML.\n  const light = picture?.light;\n  const dark = picture?.dark;\n  const Lede = typeof description === \"string\" || typeof description === \"number\" ? \"p\" : \"div\";\n  const layout: HeroLayout = layoutProp === \"column\" ? \"column\" : layoutProp === \"split\" ? \"split\" : \"stage\";\n  // Stryker disable next-line StringLiteral: motion is only compared with \"rise\", so \"\" and \"none\" behave the same.\n  const motion = motionProp === \"none\" ? \"none\" : \"rise\";\n  const headingLevel = headingLevelProp === 2 ? 2 : 1;\n  // The marker names the rise for the motion evidence. It is set only once the rise is seen running here, never in the\n  // server's HTML, so a page that never hydrates keeps no marker, and it goes when the rise ends.\n  const [rising, setRising] = useState(false);\n  const [loaded, setLoaded] = useState(false);\n  const onImageLoad = (image: HTMLImageElement) => {\n    if (isShown(image)) setLoaded(true);\n  };\n  const mediaRef = useRef<HTMLDivElement>(null);\n  useLayoutEffect(\n    () => {\n      // A finished transition leaves the list, so any animation here is the rise still running.\n      const running = mediaRef.current?.getAnimations().length;\n      if (running) setRising(true);\n      // A picture that loaded before hydration, where the page's scripts did not run, fired its load event unheard.\n      const shownImage = [...(mediaRef.current?.querySelectorAll<HTMLImageElement>(\"picture > img\") ?? [])].find(isShown);\n      if (shownImage?.complete && shownImage.naturalWidth > 0) setLoaded(true);\n    },\n    // Stryker disable next-line ArrayDeclaration: any constant list runs the effect once, like an empty one.\n    [],\n  );\n  useAppearanceClassNameCheck(\n    \"Hero\",\n    className,\n    process.env.NODE_ENV !== \"production\"\n      ? (token: string) => `remove \"${token}\"; Hero sets its own look from the theme`\n      : // Stryker disable next-line StringLiteral: production only; the check never runs there.\n        /* istanbul ignore next @preserve -- production only */ \"\",\n  );\n  useDevWarnings(\n    \"Hero\",\n    process.env.NODE_ENV !== \"production\"\n      ? () => [\n          layout !== layoutProp && [\n            `layout=\"${String(layoutProp)}\" is not a layout; use \"stage\", \"column\" or \"split\"`,\n            '<Hero layout=\"column\" />',\n          ],\n          motion !== motionProp && [\n            `motion=\"${String(motionProp)}\" is not a motion; use \"rise\" or \"none\"`,\n            '<Hero motion=\"none\" />',\n          ],\n          headingLevel !== headingLevelProp && [\n            `headingLevel={${String(headingLevelProp)}} is not a heading level; use 1 for the page headline or 2 for a section`,\n            '<Hero headingLevel={2} />',\n          ],\n          light !== undefined &&\n            light.alt === undefined &&\n            light.decorative !== true && [\n              \"picture has no alt text\",\n              '<Hero picture={{ light: { src, width, height, alt: \"A table set for four\" }, dark }} />',\n            ],\n          picture !== undefined &&\n            (light === undefined || dark === undefined) && [\n              \"picture needs light and dark art, the same scene by day and at night\",\n              \"<Hero picture={{ light: { src, width, height, alt }, dark: { src, width, height } }} />\",\n            ],\n          light !== undefined &&\n            media != null && [\n              \"picture and media are both set; show one: picture for a still image, media for something live\",\n              '<Hero media={<video src=\"...\" muted autoPlay loop playsInline />} />',\n            ],\n          subtitle !== undefined && [\"subtitle is not a prop\", '<Hero description=\"...\" />'],\n          heading !== undefined && [\"heading is not a prop\", '<Hero title=\"Dinner, sorted\" />'],\n          overline !== undefined && [\"overline is not a prop\", '<Hero eyebrow=\"Recipes\" />'],\n          image !== undefined && [\"image is not a prop\", \"<Hero picture={{ light: { src, width, height, alt }, dark: { src, width, height } }} />\"],\n          action !== undefined && [\"action is not a prop\", \"<Hero actions={<Button>Start</Button>} />\"],\n        ]\n      : /* istanbul ignore next @preserve -- production only */ undefined,\n  );\n  const crop = layout === \"split\" ? undefined : light?.crop;\n  const pictureStyle = light\n    ? ({\n        maxWidth: `${light.width}px`,\n        ...(crop ? { \"--hero-crop\": crop } : {}),\n      } as CSSProperties)\n    : // Stryker disable next-line ConditionalExpression: without mediaWidth the style would be \"undefinedpx\", which the browser drops, so the page is the same.\n      mediaWidth !== undefined\n      ? ({ maxWidth: `${mediaWidth}px` } as CSSProperties)\n      : undefined;\n  // Untyped code can still leave out the dark art: it is warned, and the light art then shows in both modes.\n  // A twin with `priority` loads from the HTML unless both have it; then the first-paint script loads the one shown.\n  const urgent = light?.priority === true || dark?.priority === true;\n  const deferred = light?.priority === true && dark?.priority === true;\n  const shown = light ? (\n    dark ? (\n      deferred ? (\n        <TwinPictures light={light} dark={dark} crop={crop} onLoad={onImageLoad} />\n      ) : (\n        <>\n          {renderPicture(light, crop, \"light\", { eager: light.priority === true, urgent, onLoad: onImageLoad })}\n          {renderPicture(dark, crop, \"dark\", { eager: dark.priority === true, urgent, onLoad: onImageLoad }, light)}\n          <FirstPaintScript urgent={urgent} />\n        </>\n      )\n    ) : (\n      <>\n        {renderPicture(light, crop, undefined, { eager: light.priority === true, urgent, onLoad: onImageLoad })}\n        <FirstPaintScript urgent={false} />\n      </>\n    )\n  ) : typeof media === \"boolean\" ? null : (\n    // `media={isWide && <video … />}` passes false: no empty frame rises in its place.\n    media\n  );\n  const eyebrowLine =\n    eyebrow != null ? (\n      <p data-slot=\"eyebrow\" className=\"m-0 text-sm leading-5 font-medium text-muted-foreground\">\n        {eyebrow}\n      </p>\n    ) : null;\n  return (\n    <header\n      {...rest}\n      data-ouro=\"hero\"\n      data-layout={layout}\n      className={cn(\"grid min-w-0\", (fullWidth ? fullWidthRoot : layoutRoot)[layout], layout === \"split\" && shown != null && splitColumns, className)}\n    >\n      <div className={fullWidth && layout === \"stage\" ? fullWidthStageText : layoutText[layout]}>\n        {breadcrumb != null ? (\n          <div data-slot=\"breadcrumb\" className=\"min-w-0\">\n            {breadcrumb}\n          </div>\n        ) : null}\n        {badge != null ? (\n          <div className={cn(\"flex min-w-0 flex-wrap items-center gap-x-3 gap-y-1\", layoutActions[layout])}>\n            {eyebrowLine}\n            <span data-slot=\"badge\" className=\"inline-flex\">\n              {badge}\n            </span>\n          </div>\n        ) : (\n          eyebrowLine\n        )}\n        <Heading level={headingLevel} size=\"display\" className=\"min-w-0 text-balance\">\n          {title}\n        </Heading>\n        {description != null ? (\n          <Lede\n            data-slot=\"description\"\n            className={cn(\n              \"m-0 text-base leading-7 text-balance text-muted-foreground min-[40rem]:text-lg min-[40rem]:leading-8\",\n              // In the reset layer, so a margin class the app puts on a paragraph still wins.\n              \"[@layer_ouro-reset]:[&>:first-child]:mt-0 [@layer_ouro-reset]:[&>:last-child]:mb-0\",\n            )}\n          >\n            {description}\n          </Lede>\n        ) : null}\n        {actions != null ? (\n          // A step further from the lede than the lines of text are from each other, so the buttons read as the lede's next move.\n          <div data-slot=\"actions\" className={cn(\"mt-2 flex flex-wrap gap-3\", layoutActions[layout])}>\n            {actions}\n          </div>\n        ) : null}\n        {children != null ? (\n          <div data-slot=\"more\" className=\"min-w-0\">\n            {children}\n          </div>\n        ) : null}\n      </div>\n      {shown != null ? (\n        <div\n          data-slot=\"media\"\n          data-ouro-part=\"media\"\n          ref={mediaRef}\n          data-starting-style={rising ? \"\" : undefined}\n          data-loaded={loaded ? \"\" : undefined}\n          // The first-paint script may have set data-loaded before React hydrates.\n          suppressHydrationWarning\n          onTransitionEnd={() => setRising(false)}\n          style={pictureStyle}\n          className={cn(\n            \"block w-[var(--hero-width)] overflow-clip rounded-ouro-xl\",\n            layoutMedia[layout],\n            motion === \"rise\" && riseMotion,\n            crop && \"relative min-[40rem]:aspect-[var(--hero-crop)]\",\n          )}\n        >\n          {shown}\n        </div>\n      ) : null}\n    </header>\n  );\n}\n",
      "type": "registry:ui",
      "target": "@components/ouro/hero/hero.tsx"
    }
  ],
  "docs": "The top of a page: a headline with an optional line above it (`eyebrow`) and a status beside that (`badge`), a trail above them (`breadcrumb`), a lede under the headline (`description`), the page's buttons (`actions`), more such as a byline (`children`), and a big picture, or something live in its place (`media`), below. Import: import { Hero } from \"@/components/ouro/hero/hero\", with @/components replaced by your components alias (aliases.components in components.json, such as ~/components). Also installed: heading, text, the helpers they import in lib/ouro. Needs ouro-base in your stylesheet: add that item once per app, from the same place as this one, if you have not. Docs: https://ui.ouroboros.bot/docs/hero.md Ouro UI v1.3.257.",
  "type": "registry:ui"
}