{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "thread-rail",
  "title": "ThreadRail",
  "description": "A thread beside its conversation: a labelled landmark with a header and a close button.",
  "registryDependencies": [
    "@ouro/button",
    "@ouro/kbd",
    "@ouro/lib-class-name-check",
    "@ouro/lib-cn",
    "@ouro/lib-env",
    "@ouro/lib-focus-handoff",
    "@ouro/lib-refs",
    "@ouro/lib-use-dev-messages",
    "@ouro/tooltip"
  ],
  "files": [
    {
      "path": "registry/ouro/components/ouro/thread-rail/thread-rail.tsx",
      "content": "\"use client\";\n\nimport { useId, useLayoutEffect, useRef, type JSX, type KeyboardEvent, type ReactNode, type RefObject } from \"react\";\nimport { Button } from \"@/registry/ouro/components/ouro/button/button\";\nimport { Kbd } from \"@/registry/ouro/components/ouro/kbd/kbd\";\nimport { Tooltip } from \"@/registry/ouro/components/ouro/tooltip/tooltip\";\nimport { useAppearanceClassNameCheck } from \"@/registry/ouro/lib/ouro/class-name-check\";\nimport { cn } from \"@/registry/ouro/lib/ouro/cn\";\nimport { useFocusHandoff } from \"@/registry/ouro/lib/ouro/focus-handoff\";\nimport { useMergedRef } from \"@/registry/ouro/lib/ouro/refs\";\nimport { useDevWarnings } from \"@/registry/ouro/lib/ouro/use-dev-messages\";\n\n/** Props for {@link ThreadRail}. */\nexport interface ThreadRailProps {\n  /** The rail's name for screen readers when `title` is left out, such as \"Thread\". Required, so the rail has a name. */\n  label: string;\n  /** The heading's words, which screen readers also hear as the rail's name. @default the label */\n  title?: string | undefined;\n  /** One muted line under the heading, cut short with an ellipsis: the conversation the thread belongs to. */\n  detail?: string | undefined;\n  /** Muted words after the heading, such as \"2 replies\". */\n  meta?: ReactNode;\n  /**\n   * Called when the close button is pressed, or Escape is pressed with focus in the rail. The app\n   * removes the rail in response.\n   */\n  onClose: () => void;\n  /** The close button's name, which its tooltip also shows. @default \"Close thread\" */\n  closeLabel?: string | undefined;\n  /** The control that takes focus when the rail opens, instead of the rail itself. */\n  initialFocus?: RefObject<HTMLElement | null> | undefined;\n  /** Whether the rail takes focus when it opens. Pass `false` to leave focus where it is. @default true */\n  autoFocus?: boolean | undefined;\n  /** Where focus goes when the rail closes, instead of the control that had focus when it opened. */\n  returnFocus?: RefObject<HTMLElement | null> | undefined;\n  /** The thread: usually a `MessageList` and a `Composer`, which fill the rail's height. */\n  children?: ReactNode;\n  /** Layout only: the rail's size and margins. Appearance classes warn in development; the colors come from the theme. */\n  className?: string | undefined;\n  /** Not a prop. The rail shows while it is rendered: `{thread && <ThreadRail onClose={close}>}`. */\n  open?: { \"ThreadRail is open while it is rendered: render it only when a thread is open\": never };\n  /** Not a prop. The rail closes through `onClose`: `<ThreadRail onClose={() => setOpen(false)}>`. */\n  onOpenChange?: { \"Use onClose\": never };\n}\n\n/** Elements that take Escape for themselves when they are open: a menu, a listbox or a dialog. */\nconst POPUP = '[role=\"menu\"], [role=\"listbox\"], [role=\"dialog\"]';\n/** Text a person types into: Escape there is not a request to close. */\nconst TEXT_ENTRY = 'input, textarea, select, [contenteditable]:not([contenteditable=\"false\"])';\n// Stryker disable next-line ArrayDeclaration: equivalent; the effect runs once, on mount, with any list that never changes\nconst MOUNT_ONLY: readonly never[] = [];\n\n/** Whether the target sits in a popup between it and the rail, or in one drawn outside the rail's DOM. */\nfunction inPopup(target: Element, rail: Element): boolean {\n  for (let node: Element | null = target; node !== null && node !== rail; node = node.parentElement) {\n    if (node.matches(POPUP)) return true;\n  }\n  return false;\n}\n\n/** The close button's icon, a cross. */\nfunction CloseIcon(): JSX.Element {\n  return (\n    <svg aria-hidden=\"true\" viewBox=\"0 0 16 16\" fill=\"none\" className=\"size-4\">\n      <path d=\"M4 4l8 8M12 4l-8 8\" stroke=\"currentColor\" strokeWidth=\"1.5\" strokeLinecap=\"round\" />\n    </svg>\n  );\n}\n\n/**\n * A thread beside its conversation: a labelled landmark with a header and a close button. Escape closes it.\n * It takes focus when it opens and gives it back when it closes.\n *\n * Use Sheet instead when the thread should cover the page, as on a phone, and close on a tap outside it.\n *\n * @group Chat\n * @example\n * <ThreadRail label=\"Thread\" title=\"Thread\" detail=\"Design reviews\" meta=\"2 replies\" onClose={closeThread}>\n *   <MessageList label=\"Replies\">{replies}</MessageList>\n *   <Composer label=\"Reply in thread\" onSend={send} />\n * </ThreadRail>\n * @claim \"It takes focus when it opens\" registry/ouro/components/ouro/thread-rail/thread-rail.test.tsx verify:testExists(registry/ouro/components/ouro/thread-rail/thread-rail.test.tsx::ThreadRail focus > takes focus on mount, on the rail itself or on initialFocus)\n * @claim \"gives it back when it closes\" registry/ouro/components/ouro/thread-rail/thread-rail.test.tsx verify:testExists(registry/ouro/components/ouro/thread-rail/thread-rail.test.tsx::ThreadRail focus > returns focus to the control that opened it when it closes)\n * @claim \"Escape closes it\" registry/ouro/components/ouro/thread-rail/thread-rail.test.tsx verify:testExists(registry/ouro/components/ouro/thread-rail/thread-rail.test.tsx::ThreadRail Escape > calls onClose on Escape with focus in the rail, and ignores other keys)\n */\nexport function ThreadRail(props: ThreadRailProps): JSX.Element {\n  const {\n    label,\n    title,\n    detail,\n    meta,\n    onClose,\n    closeLabel = \"Close thread\",\n    initialFocus,\n    autoFocus = true,\n    returnFocus,\n    children,\n    className,\n    open,\n    onOpenChange,\n  } = props;\n  const headingId = useId();\n  const railRef = useRef<HTMLElement>(null);\n  const opener = useRef<HTMLElement | null>(null);\n  const handoff = useFocusHandoff<HTMLElement>();\n  const rail = useMergedRef<HTMLElement>(railRef, handoff);\n\n  useAppearanceClassNameCheck(\n    \"ThreadRail\",\n    className,\n    process.env.NODE_ENV !== \"production\"\n      ? (token: string) => `remove \"${token}\"; the theme sets ThreadRail's colors`\n      : // Stryker disable next-line StringLiteral: production only; the check never runs there.\n        /* istanbul ignore next @preserve -- production only */ \"\",\n  );\n  useDevWarnings(\n    \"ThreadRail\",\n    process.env.NODE_ENV !== \"production\"\n      ? () => [\n          label === undefined && [\"label is missing, so screen readers cannot name the rail\", '<ThreadRail label=\"Thread\" onClose={close}>'],\n          open !== undefined && [\"open is not a prop; the rail shows while it is rendered\", '{thread && <ThreadRail label=\"Thread\" onClose={close}>}'],\n          onOpenChange !== undefined && [\"onOpenChange is not a prop\", \"<ThreadRail onClose={() => setOpen(false)}>\"],\n        ]\n      : /* istanbul ignore next @preserve -- production only */ undefined,\n  );\n\n  // Mount only: the rail takes focus when it opens, and gives focus back when it closes. The\n  // opener is remembered only when the rail took focus from it.\n  /* eslint-disable react-hooks/exhaustive-deps -- the effect runs once, on mount: the focus an open rail takes is decided then */\n  useLayoutEffect(() => {\n    const element = railRef.current!;\n    const returned = returnFocus;\n    if (autoFocus) {\n      opener.current = document.activeElement as HTMLElement | null;\n      (initialFocus?.current ?? element).focus();\n    }\n    return () => {\n      if (!element.contains(document.activeElement)) return;\n      [returned?.current, opener.current].find((candidate) => candidate?.isConnected && !element.contains(candidate))?.focus();\n    };\n  }, MOUNT_ONLY);\n  /* eslint-enable react-hooks/exhaustive-deps */\n\n  // Escape closes the rail unless it is pressed in a text field or a popup inside the rail, or\n  // something already handled it.\n  function onKeyDown(event: KeyboardEvent<HTMLElement>) {\n    if (event.key !== \"Escape\" || event.nativeEvent.defaultPrevented) return;\n    const target = event.target as Element;\n    if (target.matches(TEXT_ENTRY) || inPopup(target, event.currentTarget)) return;\n    event.preventDefault();\n    onClose();\n  }\n\n  return (\n    <aside\n      ref={rail}\n      data-ouro=\"thread-rail\"\n      aria-labelledby={headingId}\n      tabIndex={-1}\n      onKeyDown={onKeyDown}\n      className={cn(\"flex h-full min-h-0 flex-col border-s border-border bg-background outline-none\", className)}\n    >\n      <div data-ouro-thread-rail-header=\"\" className=\"flex min-w-0 shrink-0 items-start gap-2 border-b border-border px-4 py-3\">\n        <div className=\"min-w-0 flex-1\">\n          <h2 id={headingId} className=\"m-0 truncate text-base leading-6 font-semibold font-[family-name:var(--font-heading,inherit)]\">\n            {title ?? label}\n          </h2>\n          {detail !== undefined && <p className=\"m-0 truncate text-sm leading-5 text-muted-foreground\">{detail}</p>}\n          {meta !== undefined && <p className=\"m-0 text-xs leading-4 text-muted-foreground\">{meta}</p>}\n        </div>\n        <Tooltip content={<span className=\"inline-flex items-center gap-2\">{closeLabel}<Kbd keys={[\"escape\"]} /></span>}>\n          <Button\n            data-ouro-control=\"thread-rail\"\n            data-ouro-part=\"close\"\n            variant=\"plain\"\n            tone=\"secondary\"\n            size=\"sm\"\n            aria-label={closeLabel}\n            aria-keyshortcuts=\"Escape\"\n            onClick={() => onClose()}\n            className=\"px-2\"\n          >\n            <CloseIcon />\n          </Button>\n        </Tooltip>\n      </div>\n      <div className=\"flex min-h-0 flex-1 flex-col\">{children}</div>\n    </aside>\n  );\n}\n",
      "type": "registry:ui",
      "target": "@components/ouro/thread-rail/thread-rail.tsx"
    }
  ],
  "docs": "A thread beside its conversation: a labelled landmark with a header and a close button. Import: import { ThreadRail } from \"@/components/ouro/thread-rail/thread-rail\", with @/components replaced by your components alias (aliases.components in components.json, such as ~/components). Also installed: button, kbd, tooltip, 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/thread-rail.md Ouro UI v1.3.257.",
  "type": "registry:ui"
}