{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "part-frame",
  "type": "registry:ui",
  "title": "Part Frame",
  "description": "A card for one structured piece of a conversation (a plan, a result, a form) that has a life: loading, live, saving a change, replaced by a newer one, or final.",
  "categories": [
    "ui"
  ],
  "dependencies": [
    "lucide-react"
  ],
  "registryDependencies": [
    "@rivier-ui/theme",
    "@rivier-ui/announce",
    "@rivier-ui/cn",
    "@rivier-ui/dialog",
    "@rivier-ui/skeleton"
  ],
  "files": [
    {
      "path": "registry/ui/part-frame.tsx",
      "type": "registry:ui",
      "target": "components/ui/part-frame.tsx",
      "content": "\"use client\";\n/**\n * @name part-frame\n * @category ui\n * @description A card for one structured piece of a conversation (a plan, a result, a form) that has a life: loading, live, saving a change, replaced by a newer one, or final.\n * @when An assistant's reply contains something to look at or work in, not only words, and that thing changes over the conversation. The frame holds its size while it loads, says \"Saving\" in words while a change is on its way, shrinks to a one-line stub when a newer frame replaces it, and can open its content full screen. For a static card use card; for words use message; for a flow of steps put steps or a wizard inside it.\n * @example\n * <PartFrame state={plan.state} replacementRef={newerPlan}>\n *   <PartFrameHeader>\n *     <PartFrameTitle>Plan for Saturday</PartFrameTitle>\n *     <PartFrameExpand title=\"Plan for Saturday\"><PlanEditor plan={plan} roomy /></PartFrameExpand>\n *   </PartFrameHeader>\n *   <PartFrameContent className=\"min-h-40\"><PlanEditor plan={plan} /></PartFrameContent>\n *   <PartFrameFooter><Button size=\"sm\">Confirm</Button></PartFrameFooter>\n * </PartFrame>\n *\n * // Replaced by a newer one: a stub that says so and points to it\n * <PartFrame state=\"superseded\" supersededBy={<a href=\"#plan-2\">See the new plan</a>}>\n *   <PartFrameHeader><PartFrameTitle>Plan for Saturday</PartFrameTitle></PartFrameHeader>\n *   <PartFrameContent>…</PartFrameContent>\n * </PartFrame>\n */\nimport { Maximize2 } from \"lucide-react\";\nimport { createContext, use, useEffect, useId, useRef, type ComponentProps, type ReactNode, type RefObject } from \"react\";\nimport { Dialog, DialogContent, DialogHeader, DialogTitle, DialogTrigger } from \"@/components/ui/dialog\";\nimport { Skeleton } from \"@/components/ui/skeleton\";\nimport { announce } from \"@/lib/announce\";\nimport { cn } from \"@/lib/cn\";\n\nexport type PartFrameState = \"loading\" | \"live\" | \"pending\" | \"superseded\" | \"final\";\n\nexport type PartFrameLabels = {\n  /** Said to screen readers while loading. Default \"Loading\". */\n  loading?: string;\n  /** Shown and announced while a change is being saved. Default \"Saving\". */\n  pending?: string;\n  /** Shown on the stub of a frame that was replaced. Default \"Replaced\". */\n  superseded?: string;\n  /** Shown on a frame that can no longer change. Default: nothing. */\n  final?: string;\n};\n\ntype PartFrameContextValue = { state: PartFrameState; titleId: string; labels: PartFrameLabels };\n\nconst PartFrameContext = createContext<PartFrameContextValue | null>(null);\n\nfunction usePartFrameContext(part: string): PartFrameContextValue {\n  const context = use(PartFrameContext);\n  if (!context) throw new Error(`<${part}> must be used inside <PartFrame>.`);\n  return context;\n}\n\n/** The frame's state, for content that adapts to it (hide its controls when \"final\", for example). */\nexport function usePartFrame(): { state: PartFrameState } {\n  return { state: usePartFrameContext(\"usePartFrame\").state };\n}\n\nexport type PartFrameProps = Omit<ComponentProps<\"section\">, \"role\"> & {\n  /** Where the frame is in its life. Default \"live\". */\n  state?: PartFrameState;\n  /** The words for the states. Translate them with the interface. */\n  labels?: PartFrameLabels;\n  /** On a superseded frame: what replaced it, usually a link or button that goes there (\"See the new plan\"). */\n  supersededBy?: ReactNode;\n  /**\n   * The frame that replaces this one. If keyboard focus was inside this frame at the moment it became\n   * \"superseded\", focus is passed to that element (a PartFrame takes focus itself), so the person is not\n   * dropped at the top of the page. Without it, focus stays on this frame's stub.\n   */\n  replacementRef?: RefObject<HTMLElement | null>;\n};\n\n/**\n * A named group: PartFrameTitle is its heading and its accessible name. It can take focus from code\n * (`tabIndex={-1}`), never from Tab. An arriving frame does not take focus by itself.\n */\nexport function PartFrame({ className, state = \"live\", labels = {}, supersededBy, replacementRef, children, onFocus, onBlur, ...props }: PartFrameProps) {\n  const titleId = useId();\n  const rootRef = useRef<HTMLElement>(null);\n  /** Whether focus is inside. An element removed with its frame's content fires no blur, so this stays true through the change. */\n  const hadFocus = useRef(false);\n  const previous = useRef(state);\n  const pendingLabel = labels.pending ?? \"Saving\";\n\n  useEffect(() => {\n    const before = previous.current;\n    previous.current = state;\n    if (before === state) return;\n    if (state === \"pending\") announce(pendingLabel);\n    if (state === \"superseded\" && hadFocus.current) {\n      const root = rootRef.current;\n      const active = document.activeElement;\n      // Only when focus was dropped by the change, not when the person has since moved elsewhere.\n      if (active === null || active === document.body || (root !== null && root.contains(active))) {\n        (replacementRef?.current ?? root)?.focus();\n      }\n    }\n  }, [state, pendingLabel, replacementRef]);\n\n  return (\n    <PartFrameContext value={{ state, titleId, labels }}>\n      <section\n        ref={rootRef}\n        data-slot=\"part-frame\"\n        data-state={state}\n        role=\"group\"\n        aria-labelledby={titleId}\n        aria-busy={state === \"loading\" || state === \"pending\" || undefined}\n        tabIndex={-1}\n        onFocus={(event) => {\n          hadFocus.current = true;\n          onFocus?.(event);\n        }}\n        onBlur={(event) => {\n          if (!event.currentTarget.contains(event.relatedTarget)) hadFocus.current = false;\n          onBlur?.(event);\n        }}\n        className={cn(\n          \"flex w-full min-w-0 flex-col rounded-surface border bg-card text-card-foreground data-[state=superseded]:border-dashed data-[state=superseded]:bg-transparent\",\n          className,\n        )}\n        {...props}\n      >\n        {children}\n        {state === \"superseded\" && supersededBy ? (\n          <div data-slot=\"part-frame-superseded-by\" className=\"px-4 pb-3 text-sm\">\n            {supersededBy}\n          </div>\n        ) : null}\n      </section>\n    </PartFrameContext>\n  );\n}\n\n/** The top row: the title, then controls such as PartFrameExpand at the end. */\nexport function PartFrameHeader({ className, ...props }: ComponentProps<\"div\">) {\n  const { state } = usePartFrameContext(\"PartFrameHeader\");\n  return (\n    <div\n      data-slot=\"part-frame-header\"\n      className={cn(\"flex min-h-12 min-w-0 items-center gap-2 px-4 py-1.5\", state !== \"superseded\" && \"border-b\", className)}\n      {...props}\n    />\n  );\n}\n\nexport type PartFrameTitleProps = ComponentProps<\"h3\"> & {\n  /** The heading level, so the frame fits the page's outline. Default 3. */\n  level?: 2 | 3 | 4 | 5 | 6;\n};\n\n/**\n * The heading that names the frame (\"Plan for Saturday\"), followed by the state in words where there is\n * something to say: \"Saving\" with a turning mark, \"Replaced\" on a stub. \"Loading\" is for screen readers only,\n * since the skeleton shows it.\n */\nexport function PartFrameTitle({ className, level = 3, children, ...props }: PartFrameTitleProps) {\n  const { state, titleId, labels } = usePartFrameContext(\"PartFrameTitle\");\n  const Heading = `h${level}` as const;\n  const word =\n    state === \"loading\" ? (labels.loading ?? \"Loading\") : state === \"pending\" ? (labels.pending ?? \"Saving\") : state === \"superseded\" ? (labels.superseded ?? \"Replaced\") : state === \"final\" ? labels.final : undefined;\n  return (\n    <div data-slot=\"part-frame-title\" className=\"flex min-w-0 flex-1 flex-wrap items-center gap-x-3 gap-y-0.5\">\n      <Heading id={titleId} className={cn(\"min-w-0 truncate text-sm font-medium\", state === \"superseded\" && \"text-muted-foreground\", className)} {...props}>\n        {children}\n      </Heading>\n      {word ? (\n        <span data-slot=\"part-frame-status\" className={cn(\"inline-flex shrink-0 items-center gap-1.5 text-xs text-muted-foreground\", state === \"loading\" && \"sr-only\")}>\n          {state === \"pending\" ? (\n            <span aria-hidden=\"true\" className=\"size-3 animate-spin rounded-full border-2 border-current border-e-transparent motion-reduce:animate-none\" />\n          ) : null}\n          {word}\n        </span>\n      ) : null}\n    </div>\n  );\n}\n\nexport type PartFrameContentProps = ComponentProps<\"div\"> & {\n  /** What stands in while loading. Default: a few skeleton lines. It sits in the same box, so give the box its final size (`min-h-40`, an aspect ratio) and nothing jumps. */\n  fallback?: ReactNode;\n};\n\n/** The body. Not rendered on a superseded frame; replaced by the skeleton while loading. */\nexport function PartFrameContent({ className, fallback, children, ...props }: PartFrameContentProps) {\n  const { state } = usePartFrameContext(\"PartFrameContent\");\n  if (state === \"superseded\") return null;\n  return (\n    <div data-slot=\"part-frame-content\" className={cn(\"min-w-0 p-4\", className)} {...props}>\n      {state === \"loading\"\n        ? (fallback ?? (\n            <div className=\"flex flex-col gap-3\">\n              <Skeleton className=\"h-4 w-2/3\" />\n              <Skeleton className=\"h-4 w-full\" />\n              <Skeleton className=\"h-4 w-5/6\" />\n            </div>\n          ))\n        : children}\n    </div>\n  );\n}\n\n/** Actions under the body. Not rendered while loading or on a superseded frame. */\nexport function PartFrameFooter({ className, ...props }: ComponentProps<\"div\">) {\n  const { state } = usePartFrameContext(\"PartFrameFooter\");\n  if (state === \"superseded\" || state === \"loading\") return null;\n  return <div data-slot=\"part-frame-footer\" className={cn(\"flex min-w-0 flex-wrap items-center gap-2 border-t px-4 py-3\", className)} {...props} />;\n}\n\nexport type PartFrameExpandProps = {\n  /** The full-screen window's title: usually the same words as PartFrameTitle. */\n  title: ReactNode;\n  /** The button's name. Default \"Open full screen\". */\n  label?: string;\n  /** The close button's name in the window. Default \"Close\". */\n  closeLabel?: string;\n  /** What the window shows: usually the same content in a roomier layout. */\n  children: ReactNode;\n  open?: boolean;\n  defaultOpen?: boolean;\n  onOpenChange?: (open: boolean) => void;\n  className?: string;\n};\n\n/**\n * A button that opens the frame's content in a window that fills the screen (the library's dialog: focus\n * moves in, is kept in, Escape closes, and focus returns to this button). Not shown while loading or on a\n * superseded frame.\n */\nexport function PartFrameExpand({ title, label = \"Open full screen\", closeLabel, children, className, ...dialog }: PartFrameExpandProps) {\n  const { state } = usePartFrameContext(\"PartFrameExpand\");\n  if (state === \"superseded\" || state === \"loading\") return null;\n  return (\n    <Dialog {...dialog}>\n      <DialogTrigger\n        data-slot=\"part-frame-expand\"\n        aria-label={label}\n        className=\"-me-2 inline-flex size-(--control-h-sm) shrink-0 items-center justify-center rounded-control text-muted-foreground transition-[background-color,color] duration-instant ease-out hover:bg-accent hover:text-foreground motion-reduce:transition-none pointer-coarse:size-(--control-h) [&_svg]:size-4\"\n      >\n        <Maximize2 aria-hidden=\"true\" strokeWidth={1.5} />\n      </DialogTrigger>\n      <DialogContent aria-describedby={undefined} closeLabel={closeLabel} className={cn(\"h-[calc(100dvh-2rem)] max-w-none\", className)}>\n        <DialogHeader>\n          <DialogTitle>{title}</DialogTitle>\n        </DialogHeader>\n        <div data-slot=\"part-frame-expanded\" className=\"min-h-0 min-w-0 flex-1\">\n          {children}\n        </div>\n      </DialogContent>\n    </Dialog>\n  );\n}\n"
    }
  ],
  "meta": {
    "category": "ui",
    "when": "An assistant's reply contains something to look at or work in, not only words, and that thing changes over the conversation. The frame holds its size while it loads, says \"Saving\" in words while a change is on its way, shrinks to a one-line stub when a newer frame replaces it, and can open its content full screen. For a static card use card; for words use message; for a flow of steps put steps or a wizard inside it.",
    "example": "<PartFrame state={plan.state} replacementRef={newerPlan}>\n  <PartFrameHeader>\n    <PartFrameTitle>Plan for Saturday</PartFrameTitle>\n    <PartFrameExpand title=\"Plan for Saturday\"><PlanEditor plan={plan} roomy /></PartFrameExpand>\n  </PartFrameHeader>\n  <PartFrameContent className=\"min-h-40\"><PlanEditor plan={plan} /></PartFrameContent>\n  <PartFrameFooter><Button size=\"sm\">Confirm</Button></PartFrameFooter>\n</PartFrame>\n\n// Replaced by a newer one: a stub that says so and points to it\n<PartFrame state=\"superseded\" supersededBy={<a href=\"#plan-2\">See the new plan</a>}>\n  <PartFrameHeader><PartFrameTitle>Plan for Saturday</PartFrameTitle></PartFrameHeader>\n  <PartFrameContent>…</PartFrameContent>\n</PartFrame>",
    "client": true
  }
}
