{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "map-frame",
  "type": "registry:component",
  "title": "Map Frame",
  "description": "The frame around a map, not a map: it holds the map's size, shows a still until the person asks for the map, keeps a text list beside it, and takes the map to full screen and back. The map engine is yours.",
  "categories": [
    "layout"
  ],
  "dependencies": [
    "lucide-react"
  ],
  "registryDependencies": [
    "@rivier-ui/theme",
    "@rivier-ui/announce",
    "@rivier-ui/cn",
    "@rivier-ui/use-controllable-state"
  ],
  "files": [
    {
      "path": "registry/layout/map-frame.tsx",
      "type": "registry:component",
      "target": "components/layout/map-frame.tsx",
      "content": "\"use client\";\n/**\n * @name map-frame\n * @category layout\n * @description The frame around a map, not a map: it holds the map's size, shows a still until the person asks for the map, keeps a text list beside it, and takes the map to full screen and back. The map engine is yours.\n * @when Any page that shows a map from any engine (MapLibre, Leaflet, a hosted maps script). It gives the map what an engine does not: no request to a third party before the person presses the button (put the line about that in MapFrameNotice), no layout shift, the same information as a list (MapFrameList) so that the map is never the only way to it, a way to skip past the map with the keyboard, and full screen that behaves as a modal. For a still picture of a place with no interaction use an image in aspect.\n * @example\n * <MapFrame aria-label=\"Map of the three stops\">\n *   <MapFrameStage className=\"aspect-video\">\n *     <MapFramePlaceholder>\n *       <MapFrameActivate>Show the map</MapFrameActivate>\n *       <MapFrameNotice>The map is loaded from Example Maps, which will see your address.</MapFrameNotice>\n *     </MapFramePlaceholder>\n *     <MapFrameCanvas><MyMapEngine stops={stops} /></MapFrameCanvas>\n *     <MapFrameToolbar>\n *       <MapFrameFullscreen />\n *     </MapFrameToolbar>\n *   </MapFrameStage>\n *   <MapFrameList>\n *     <ol>{stops.map((stop) => <li key={stop.id}>{stop.name}, {stop.address}</li>)}</ol>\n *   </MapFrameList>\n * </MapFrame>\n */\nimport { Maximize2, Minimize2 } from \"lucide-react\";\nimport { createContext, use, useEffect, useId, useRef, type ComponentProps, type KeyboardEvent } from \"react\";\nimport { announce } from \"@/lib/announce\";\nimport { cn } from \"@/lib/cn\";\nimport { useControllableState } from \"@/lib/use-controllable-state\";\n\ntype MapFrameContextValue = {\n  id: string;\n  label: string | undefined;\n  active: boolean;\n  setActive: (active: boolean) => void;\n  fullscreen: boolean;\n  setFullscreen: (fullscreen: boolean) => void;\n};\n\nconst MapFrameContext = createContext<MapFrameContextValue | null>(null);\n\nfunction useMapFrame(part: string): MapFrameContextValue {\n  const context = use(MapFrameContext);\n  if (!context) throw new Error(`<${part}> must be used inside <MapFrame>.`);\n  return context;\n}\n\nexport type MapFrameProps = ComponentProps<\"section\"> & {\n  /** Whether the map has been asked for (controlled). Until it is true nothing inside MapFrameCanvas is rendered. */\n  active?: boolean;\n  /** Start with the map on, when no third party is involved or consent was given before. */\n  defaultActive?: boolean;\n  onActiveChange?: (active: boolean) => void;\n  /** Whether the stage fills the viewport (controlled). */\n  fullscreen?: boolean;\n  defaultFullscreen?: boolean;\n  onFullscreenChange?: (fullscreen: boolean) => void;\n};\n\n/** A named region: give it an `aria-label` that says what the map shows (\"Map of the three stops\"). */\nexport function MapFrame({ className, active, defaultActive = false, onActiveChange, fullscreen, defaultFullscreen = false, onFullscreenChange, ...props }: MapFrameProps) {\n  const id = useId();\n  const [isActive, setActive] = useControllableState({ value: active, defaultValue: defaultActive, onChange: onActiveChange });\n  const [isFullscreen, setFullscreen] = useControllableState({ value: fullscreen, defaultValue: defaultFullscreen, onChange: onFullscreenChange });\n  return (\n    <MapFrameContext\n      value={{ id, label: props[\"aria-label\"], active: isActive, setActive, fullscreen: isFullscreen && isActive, setFullscreen }}\n    >\n      <section data-slot=\"map-frame\" data-active={isActive ? \"\" : undefined} className={cn(\"flex w-full min-w-0 flex-col gap-3\", className)} {...props} />\n    </MapFrameContext>\n  );\n}\n\n/** Makes everything outside `element` inert, as a modal does, and returns the way back. */\nfunction isolate(element: HTMLElement): () => void {\n  const changed: HTMLElement[] = [];\n  for (let node: HTMLElement | null = element; node && node !== document.body; node = node.parentElement) {\n    for (const sibling of node.parentElement?.children ?? []) {\n      if (sibling !== node && sibling instanceof HTMLElement && !sibling.inert && sibling.id !== \"rui-announcer\") {\n        sibling.inert = true;\n        changed.push(sibling);\n      }\n    }\n  }\n  return () => {\n    for (const sibling of changed) sibling.inert = false;\n  };\n}\n\nexport type MapFrameStageProps = ComponentProps<\"div\"> & {\n  /** The link that lets a keyboard user go past the map. Translate it with the interface. */\n  skipLabel?: string;\n  /** Said when the stage fills the screen, and when it goes back. Translate them. */\n  enteredLabel?: string;\n  leftLabel?: string;\n};\n\n/**\n * The box the map lives in. Give it its size with a class (`aspect-video`, `h-96`): it holds that size\n * before, while and after the map loads, so nothing shifts. In full screen the same element is lifted to\n * the browser's top layer and fills the viewport: it is not moved in the document, so the map engine keeps\n * its state. While it is there the rest of the page is inert, Escape leaves, and focus is back on the\n * full-screen button.\n */\nexport function MapFrameStage({\n  className,\n  children,\n  skipLabel = \"Skip the map\",\n  enteredLabel = \"The map fills the screen. Press Escape to go back.\",\n  leftLabel = \"The map is back in the page.\",\n  onKeyDown,\n  ...props\n}: MapFrameStageProps) {\n  const frame = useMapFrame(\"MapFrameStage\");\n  const { fullscreen, setFullscreen, active } = frame;\n  const stage = useRef<HTMLDivElement>(null);\n  const labels = useRef({ enteredLabel, leftLabel });\n  useEffect(() => {\n    labels.current = { enteredLabel, leftLabel };\n  });\n\n  useEffect(() => {\n    const node = stage.current;\n    if (!fullscreen || !node) return;\n    // The top layer sits above every stacking context, wherever the frame is in the page.\n    const topLayer = typeof node.showPopover === \"function\";\n    if (topLayer) {\n      node.setAttribute(\"popover\", \"manual\");\n      node.showPopover();\n    }\n    const release = isolate(node);\n    const overflow = document.documentElement.style.overflow;\n    document.documentElement.style.overflow = \"hidden\";\n    announce(labels.current.enteredLabel);\n    return () => {\n      release();\n      document.documentElement.style.overflow = overflow;\n      if (topLayer) {\n        if (node.matches(\":popover-open\")) node.hidePopover();\n        node.removeAttribute(\"popover\");\n      }\n      announce(labels.current.leftLabel);\n    };\n  }, [fullscreen]);\n\n  const handleKeyDown = (event: KeyboardEvent<HTMLDivElement>): void => {\n    onKeyDown?.(event);\n    if (event.defaultPrevented || event.key !== \"Escape\" || !fullscreen) return;\n    event.preventDefault();\n    event.stopPropagation();\n    setFullscreen(false);\n    event.currentTarget.querySelector<HTMLElement>(\"[data-slot=map-frame-fullscreen]\")?.focus();\n  };\n\n  return (\n    <>\n      {active ? (\n        <a\n          data-slot=\"map-frame-skip\"\n          href={`#${frame.id}-after`}\n          onClick={(event) => {\n            event.preventDefault();\n            document.getElementById(`${frame.id}-after`)?.focus();\n          }}\n          className=\"sr-only focus-visible:not-sr-only focus-visible:w-fit focus-visible:rounded-control focus-visible:bg-background focus-visible:px-3 focus-visible:py-2 focus-visible:text-sm focus-visible:text-foreground focus-visible:underline\"\n        >\n          {skipLabel}\n        </a>\n      ) : null}\n      <div\n        ref={stage}\n        data-slot=\"map-frame-stage\"\n        data-fullscreen={fullscreen ? \"\" : undefined}\n        role={fullscreen ? \"dialog\" : undefined}\n        aria-modal={fullscreen ? true : undefined}\n        aria-label={fullscreen ? frame.label : undefined}\n        onKeyDown={handleKeyDown}\n        className={cn(\n          \"relative isolate aspect-video w-full min-w-0 overflow-hidden rounded-surface border border-border bg-muted text-foreground\",\n          \"data-[fullscreen]:fixed data-[fullscreen]:inset-0 data-[fullscreen]:z-50 data-[fullscreen]:m-0 data-[fullscreen]:aspect-auto data-[fullscreen]:h-dvh data-[fullscreen]:max-h-none data-[fullscreen]:w-full data-[fullscreen]:max-w-none data-[fullscreen]:rounded-none data-[fullscreen]:border-0 data-[fullscreen]:p-0\",\n          className,\n        )}\n        {...props}\n      >\n        {children}\n      </div>\n      <span id={`${frame.id}-after`} tabIndex={-1} data-slot=\"map-frame-after\" className=\"sr-only\" />\n    </>\n  );\n}\n\n/**\n * What the stage shows until the map is asked for: by default a flat block; give it a still picture or a\n * summary as children, with the MapFrameActivate button and the MapFrameNotice line. It is removed once\n * the map is on.\n */\nexport function MapFramePlaceholder({ className, ...props }: ComponentProps<\"div\">) {\n  const { active } = useMapFrame(\"MapFramePlaceholder\");\n  if (active) return null;\n  return (\n    <div\n      data-slot=\"map-frame-placeholder\"\n      className={cn(\"absolute inset-0 flex flex-col items-center justify-center gap-3 overflow-y-auto p-5 text-center\", className)}\n      {...props}\n    />\n  );\n}\n\nexport type MapFrameActivateProps = Omit<ComponentProps<\"button\">, \"type\">;\n\n/**\n * The button that turns the map on. Nothing inside MapFrameCanvas exists before it is pressed, so no\n * script is fetched and no address is sent. It is described by the MapFrameNotice of the same frame. Focus\n * moves to the map when it appears.\n */\nexport function MapFrameActivate({ className, onClick, ...props }: MapFrameActivateProps) {\n  const frame = useMapFrame(\"MapFrameActivate\");\n  const canvasId = `${frame.id}-canvas`;\n  // The button goes when the map comes: focus moves to the map, which exists once the state has been applied.\n  const pressed = useRef(false);\n  useEffect(\n    () => () => {\n      if (pressed.current) document.getElementById(canvasId)?.focus();\n    },\n    [canvasId],\n  );\n  return (\n    <button\n      type=\"button\"\n      data-slot=\"map-frame-activate\"\n      aria-describedby={`${frame.id}-notice`}\n      onClick={(event) => {\n        onClick?.(event);\n        if (event.defaultPrevented) return;\n        pressed.current = true;\n        frame.setActive(true);\n      }}\n      className={cn(\n        \"inline-flex h-control shrink-0 items-center justify-center gap-2 rounded-control bg-primary px-4 text-sm font-medium text-primary-foreground transition-[opacity,scale] duration-instant ease-out select-none hover:opacity-90 active:scale-[0.98] motion-reduce:transition-none motion-reduce:active:scale-100 [&_svg]:size-4\",\n        className,\n      )}\n      {...props}\n    />\n  );\n}\n\n/** The line beside the button that says what turning the map on does: who will see what. The project writes it. */\nexport function MapFrameNotice({ className, ...props }: ComponentProps<\"p\">) {\n  const frame = useMapFrame(\"MapFrameNotice\");\n  return <p id={`${frame.id}-notice`} data-slot=\"map-frame-notice\" className={cn(\"max-w-prose text-xs text-muted-foreground\", className)} {...props} />;\n}\n\nexport type MapFrameCanvasProps = ComponentProps<\"div\">;\n\n/**\n * Where the map engine goes. It is a box that fills the stage and nothing else: mount the engine in it and\n * let the engine watch the box's size (it changes on full screen). Its children are rendered only once the\n * map has been asked for, and stay mounted through full screen. Its name (\"Map\") is an `aria-label`.\n */\nexport function MapFrameCanvas({ className, children, \"aria-label\": ariaLabel = \"Map\", ...props }: MapFrameCanvasProps) {\n  const frame = useMapFrame(\"MapFrameCanvas\");\n  if (!frame.active) return null;\n  return (\n    <div id={`${frame.id}-canvas`} role=\"group\" aria-label={ariaLabel} tabIndex={-1} data-slot=\"map-frame-canvas\" className={cn(\"absolute inset-0 outline-none\", className)} {...props}>\n      {children}\n    </div>\n  );\n}\n\n/** Controls over the map, at the top end of the stage: MapFrameFullscreen and the project's own (zoom, layers, locate). Shown once the map is on. */\nexport function MapFrameToolbar({ className, \"aria-label\": ariaLabel = \"Map controls\", ...props }: ComponentProps<\"div\">) {\n  const { active } = useMapFrame(\"MapFrameToolbar\");\n  if (!active) return null;\n  return (\n    <div\n      role=\"group\"\n      aria-label={ariaLabel}\n      data-slot=\"map-frame-toolbar\"\n      className={cn(\"absolute end-2 top-2 z-10 flex max-w-[calc(100%-1rem)] flex-wrap items-center justify-end gap-1 rounded-control border border-border bg-background p-1\", className)}\n      {...props}\n    />\n  );\n}\n\nexport const mapFrameControlClass =\n  \"inline-flex size-(--control-h-sm) shrink-0 items-center justify-center rounded-control text-foreground transition-[background-color,color] duration-instant ease-out hover:bg-accent disabled:pointer-events-none disabled:opacity-50 motion-reduce:transition-none pointer-coarse:size-(--control-h) [&_svg]:size-4\";\n\nexport type MapFrameFullscreenProps = Omit<ComponentProps<\"button\">, \"type\" | \"aria-label\"> & {\n  /** The button's name in the page and in full screen. Translate them with the interface. */\n  enterLabel?: string;\n  exitLabel?: string;\n};\n\n/** Takes the stage to full screen and back. Its name says which way it goes. */\nexport function MapFrameFullscreen({ className, children, enterLabel = \"Full screen\", exitLabel = \"Leave full screen\", onClick, ...props }: MapFrameFullscreenProps) {\n  const frame = useMapFrame(\"MapFrameFullscreen\");\n  return (\n    <button\n      type=\"button\"\n      data-slot=\"map-frame-fullscreen\"\n      aria-label={frame.fullscreen ? exitLabel : enterLabel}\n      onClick={(event) => {\n        onClick?.(event);\n        if (!event.defaultPrevented) frame.setFullscreen(!frame.fullscreen);\n      }}\n      className={cn(mapFrameControlClass, className)}\n      {...props}\n    >\n      {children ?? (frame.fullscreen ? <Minimize2 aria-hidden=\"true\" strokeWidth={1.5} /> : <Maximize2 aria-hidden=\"true\" strokeWidth={1.5} />)}\n    </button>\n  );\n}\n\n/**\n * The same information as the map, as text: the places with their names and addresses, the route as\n * steps. The project renders it (a list, a table); it is always in the page, whether the map is on or not.\n */\nexport function MapFrameList({ className, ...props }: ComponentProps<\"div\">) {\n  return <div data-slot=\"map-frame-list\" className={cn(\"min-w-0 text-sm\", className)} {...props} />;\n}\n"
    }
  ],
  "meta": {
    "category": "layout",
    "when": "Any page that shows a map from any engine (MapLibre, Leaflet, a hosted maps script). It gives the map what an engine does not: no request to a third party before the person presses the button (put the line about that in MapFrameNotice), no layout shift, the same information as a list (MapFrameList) so that the map is never the only way to it, a way to skip past the map with the keyboard, and full screen that behaves as a modal. For a still picture of a place with no interaction use an image in aspect.",
    "example": "<MapFrame aria-label=\"Map of the three stops\">\n  <MapFrameStage className=\"aspect-video\">\n    <MapFramePlaceholder>\n      <MapFrameActivate>Show the map</MapFrameActivate>\n      <MapFrameNotice>The map is loaded from Example Maps, which will see your address.</MapFrameNotice>\n    </MapFramePlaceholder>\n    <MapFrameCanvas><MyMapEngine stops={stops} /></MapFrameCanvas>\n    <MapFrameToolbar>\n      <MapFrameFullscreen />\n    </MapFrameToolbar>\n  </MapFrameStage>\n  <MapFrameList>\n    <ol>{stops.map((stop) => <li key={stop.id}>{stop.name}, {stop.address}</li>)}</ol>\n  </MapFrameList>\n</MapFrame>",
    "client": true
  }
}
