{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "mobile-list-detail",
  "type": "registry:block",
  "title": "Mobile list to detail",
  "description": "A list of records that becomes one view at a time on phones, with large rows and a back button, and two panes side by side from 768px.",
  "registryDependencies": ["button"],
  "dependencies": [],
  "files": [
    {
      "path": "web/registry/items/mobile-list-detail/mobile-list-detail.tsx",
      "type": "registry:component",
      "content": "\"use client\";\n\nimport * as React from \"react\";\n\nimport { cn } from \"@/registry/shadcn/lib/utils\";\nimport { Button } from \"@/registry/shadcn/ui/button\";\n\nexport type MobileListDetailItem = {\n  /** Stable id; used to keep the selection and to return focus to the row. */\n  id: string;\n  /** What the record is called. Shown in the row and as the detail heading. */\n  title: string;\n  /** One short, scannable fact beside the title in the row: \"6 Oct\". */\n  meta?: string;\n  /** One or two lines from the content, so people can tell rows apart. */\n  summary?: string;\n  /** Facts shown at the top of the detail view, as label and value pairs. */\n  details?: { label: string; value: React.ReactNode }[];\n  /** The full content of the detail view. */\n  body: React.ReactNode;\n};\n\ntype Message = {\n  /** Says what happened, in the user's words. */\n  title: React.ReactNode;\n  description?: React.ReactNode;\n  /** One way forward: a link or button. */\n  action?: React.ReactNode;\n};\n\nexport type MobileListDetailProps = Omit<\n  React.ComponentProps<\"section\">,\n  \"title\"\n> & {\n  /** The list's name: the notebook, folder or inbox people are in. */\n  title: React.ReactNode;\n  /** Optional one line under the title. Keep it short; phones show it too. */\n  description?: React.ReactNode;\n  items: MobileListDetailItem[];\n  /** Used for the count beside the title: \"5 notes\". */\n  itemNoun?: { one: string; other: string };\n  /** Visible text of the back button on phones. Name where it goes. */\n  backLabel?: string;\n  /** The record shown first. On wide screens the first item is shown if unset. */\n  initialSelectedId?: string;\n  /** Which view a phone shows first. Defaults to the list. */\n  initialView?: \"list\" | \"detail\";\n  /** 1 when this is the page's main heading; the detail heading is one deeper. */\n  headingLevel?: 1 | 2;\n  /** Shown instead of the list when there are no items. */\n  empty?: Message;\n  /** Shown instead of the list when the items could not load. */\n  error?: Message & { label?: string };\n};\n\n// Matches Tailwind's `md` breakpoint (48rem), where the layout becomes two\n// panes. Change both together if your project uses another breakpoint.\nconst WIDE_QUERY = \"(min-width: 48rem)\";\n\nfunction subscribe(onChange: () => void) {\n  const query = window.matchMedia(WIDE_QUERY);\n  query.addEventListener(\"change\", onChange);\n  return () => query.removeEventListener(\"change\", onChange);\n}\n\nfunction useIsWide() {\n  return React.useSyncExternalStore(\n    subscribe,\n    () => window.matchMedia(WIDE_QUERY).matches,\n    () => false,\n  );\n}\n\nexport function MobileListDetail({\n  title,\n  description,\n  items,\n  itemNoun = { one: \"item\", other: \"items\" },\n  backLabel = \"Back to list\",\n  initialSelectedId,\n  initialView = \"list\",\n  headingLevel = 1,\n  empty,\n  error,\n  className,\n  ...props\n}: MobileListDetailProps) {\n  const id = React.useId();\n  const headingId = `${id}-heading`;\n  const detailHeadingId = `${id}-detail`;\n  const Heading = `h${headingLevel}` as const;\n  const DetailHeading = `h${headingLevel + 1}` as \"h2\" | \"h3\";\n\n  const isWide = useIsWide();\n  const [selectedId, setSelectedId] = React.useState<string | null>(\n    initialSelectedId ?? null,\n  );\n  const [view, setView] = React.useState<\"list\" | \"detail\">(\n    initialSelectedId ? initialView : \"list\",\n  );\n  const [announcement, setAnnouncement] = React.useState(\"\");\n\n  const rowRefs = React.useRef(new Map<string, HTMLButtonElement>());\n  const detailHeadingRef = React.useRef<HTMLHeadingElement>(null);\n  const pendingFocus = React.useRef<\"detail\" | \"list\" | null>(null);\n\n  // Wide screens always show a record; phones show one only once it is opened.\n  const shown =\n    items.find((item) => item.id === selectedId) ?? items[0] ?? null;\n  const currentId = isWide ? (shown?.id ?? null) : selectedId;\n  const status = error ? \"error\" : items.length === 0 ? \"empty\" : \"ready\";\n  const showDetail = status === \"ready\" && view === \"detail\";\n\n  // Move focus after the view has changed, so it never lands on a hidden pane.\n  React.useEffect(() => {\n    const target = pendingFocus.current;\n    pendingFocus.current = null;\n    if (target === \"detail\") detailHeadingRef.current?.focus();\n    if (target === \"list\" && selectedId) {\n      rowRefs.current.get(selectedId)?.focus();\n    }\n  }, [view, selectedId]);\n\n  function open(item: MobileListDetailItem) {\n    setSelectedId(item.id);\n    setView(\"detail\");\n    if (isWide) {\n      // The list stays in view, so keep focus on the row and announce the change.\n      setAnnouncement(`Showing ${item.title}`);\n    } else {\n      pendingFocus.current = \"detail\";\n    }\n  }\n\n  function back() {\n    pendingFocus.current = \"list\";\n    setView(\"list\");\n  }\n\n  const message =\n    status === \"error\" ? error : status === \"empty\" ? empty : null;\n\n  return (\n    <section\n      aria-labelledby={headingId}\n      data-slot=\"mobile-list-detail\"\n      data-view={showDetail ? \"detail\" : \"list\"}\n      className={cn(\"bg-background text-foreground\", className)}\n      {...props}\n    >\n      <div className=\"mx-auto w-full max-w-6xl md:px-6 md:py-10 lg:px-8 lg:py-12\">\n        <div className=\"md:overflow-hidden md:bg-card md:text-card-foreground md:rounded-lg md:border md:border-border\">\n          <header\n            className={cn(\n              \"flex flex-wrap items-baseline justify-between gap-x-4 gap-y-1 border-b border-border px-4 py-4 md:px-6\",\n              // On a phone's detail view the back button names the list, so\n              // the header is only kept for screen readers' heading outline.\n              showDetail && \"max-md:sr-only\",\n            )}\n          >\n            <div className=\"min-w-0\">\n              <Heading\n                id={headingId}\n                className=\"text-xl leading-tight font-semibold tracking-tight text-balance sm:text-2xl\"\n              >\n                {title}\n              </Heading>\n              {description ? (\n                <p className=\"mt-1 max-w-prose text-sm leading-relaxed text-pretty text-muted-foreground\">\n                  {description}\n                </p>\n              ) : null}\n            </div>\n            {status === \"ready\" ? (\n              <p className=\"text-sm text-muted-foreground tabular-nums\">\n                {items.length}{\" \"}\n                {items.length === 1 ? itemNoun.one : itemNoun.other}\n              </p>\n            ) : null}\n          </header>\n\n          {message ? (\n            <div\n              className={cn(\n                \"px-4 py-10 md:px-6 md:py-16\",\n                status === \"error\" && \"border-l-4 border-destructive\",\n              )}\n            >\n              <div className=\"max-w-prose\">\n                <DetailHeading className=\"text-lg leading-snug font-semibold tracking-tight text-balance\">\n                  {status === \"error\" ? (\n                    <span className=\"mb-1 block text-sm font-semibold text-destructive\">\n                      {error?.label ?? \"Error\"}\n                    </span>\n                  ) : null}\n                  {message.title}\n                </DetailHeading>\n                {message.description ? (\n                  <div className=\"mt-2 text-sm leading-relaxed text-pretty text-muted-foreground\">\n                    {message.description}\n                  </div>\n                ) : null}\n                {message.action ? (\n                  <div className=\"mt-6 flex flex-col gap-3 sm:flex-row sm:items-center\">\n                    {message.action}\n                  </div>\n                ) : null}\n              </div>\n            </div>\n          ) : (\n            <div className=\"md:grid md:grid-cols-[minmax(15rem,20rem)_minmax(0,1fr)] lg:grid-cols-[22rem_minmax(0,1fr)]\">\n              <ul\n                aria-labelledby={headingId}\n                className={cn(\n                  \"divide-y divide-border border-b border-border md:border-r md:border-b-0\",\n                  showDetail && \"max-md:hidden\",\n                )}\n              >\n                {items.map((item) => {\n                  const current = item.id === currentId;\n                  return (\n                    <li key={item.id}>\n                      <button\n                        type=\"button\"\n                        ref={(node) => {\n                          if (node) rowRefs.current.set(item.id, node);\n                          else rowRefs.current.delete(item.id);\n                        }}\n                        aria-current={current ? \"true\" : undefined}\n                        onClick={() => open(item)}\n                        className={cn(\n                          \"relative flex min-h-11 w-full flex-col items-start gap-1 px-4 py-3.5 text-left outline-none hover:bg-muted focus-visible:ring-[3px] focus-visible:ring-ring/50 focus-visible:ring-inset md:px-5\",\n                          // Selection is a bar and a fill, not colour alone.\n                          \"before:absolute before:inset-y-0 before:left-0 before:w-1\",\n                          current && \"bg-muted before:bg-foreground\",\n                        )}\n                      >\n                        <span className=\"flex w-full items-baseline justify-between gap-3\">\n                          <span\n                            className={cn(\n                              \"min-w-0 text-base leading-snug break-words\",\n                              current ? \"font-semibold\" : \"font-medium\",\n                            )}\n                          >\n                            {item.title}\n                          </span>\n                          {item.meta ? (\n                            <span className=\"shrink-0 text-sm text-muted-foreground tabular-nums\">\n                              {item.meta}\n                            </span>\n                          ) : null}\n                        </span>\n                        {item.summary ? (\n                          <span className=\"line-clamp-2 text-sm leading-relaxed text-muted-foreground\">\n                            {item.summary}\n                          </span>\n                        ) : null}\n                      </button>\n                    </li>\n                  );\n                })}\n              </ul>\n\n              {shown ? (\n                <article\n                  aria-labelledby={detailHeadingId}\n                  className={cn(\n                    \"min-w-0 px-4 pt-2 pb-10 md:px-8 md:py-8 lg:px-10\",\n                    !showDetail && \"max-md:hidden\",\n                  )}\n                >\n                  <Button\n                    type=\"button\"\n                    variant=\"ghost\"\n                    onClick={back}\n                    className=\"-ml-3 h-11 px-3 md:hidden\"\n                  >\n                    <svg\n                      aria-hidden=\"true\"\n                      viewBox=\"0 0 16 16\"\n                      fill=\"none\"\n                      stroke=\"currentColor\"\n                      strokeWidth=\"1.5\"\n                      strokeLinecap=\"round\"\n                      strokeLinejoin=\"round\"\n                    >\n                      <path d=\"M10 3 5 8l5 5\" />\n                    </svg>\n                    {backLabel}\n                  </Button>\n\n                  <DetailHeading\n                    id={detailHeadingId}\n                    ref={detailHeadingRef}\n                    tabIndex={-1}\n                    className=\"mt-4 text-xl leading-tight font-semibold tracking-tight text-balance outline-none sm:text-2xl md:mt-0\"\n                  >\n                    {shown.title}\n                  </DetailHeading>\n\n                  {shown.details?.length ? (\n                    <dl className=\"mt-4 grid grid-cols-[auto_minmax(0,1fr)] gap-x-6 gap-y-1 text-sm\">\n                      {shown.details.map((detail) => (\n                        <React.Fragment key={detail.label}>\n                          <dt className=\"text-muted-foreground\">\n                            {detail.label}\n                          </dt>\n                          <dd className=\"min-w-0 break-words\">\n                            {detail.value}\n                          </dd>\n                        </React.Fragment>\n                      ))}\n                    </dl>\n                  ) : null}\n\n                  <div className=\"mt-6 max-w-prose space-y-4 border-t border-border pt-6 text-base leading-relaxed text-pretty [&_li]:ml-5 [&_ul]:list-disc [&_ul]:space-y-1\">\n                    {shown.body}\n                  </div>\n                </article>\n              ) : null}\n            </div>\n          )}\n        </div>\n      </div>\n      <p className=\"sr-only\" aria-live=\"polite\">\n        {announcement}\n      </p>\n    </section>\n  );\n}\n"
    }
  ],
  "categories": ["mobile"],
  "docs": "Taste notes, states and rules: https://tessli.vercel.app/library/mobile-list-detail",
  "meta": {
    "tessli": {
      "id": "mobile-list-detail",
      "kind": "page",
      "category": "mobile",
      "title": "Mobile list to detail",
      "summary": "A list of records that becomes one view at a time on phones, with large rows and a back button, and two panes side by side from 768px.",
      "use_when": [
        "People scan a list of records (notes, messages, orders, tickets) and open one at a time to read or act on it.",
        "The same screen has to work on phones and on wide screens without a separate mobile app.",
        "Each record has a short title and one or two lines that tell rows apart."
      ],
      "avoid_when": [
        "People compare many records across columns; use a data table instead.",
        "Records are edited side by side or several at once; a list and one detail view will slow them down.",
        "The list has fewer than three records; show them all on one page."
      ],
      "rules": [
        "R-01",
        "R-03",
        "A-01",
        "A-06",
        "A-05",
        "K-01",
        "H-02",
        "ST-04"
      ],
      "ai_default": "The desktop layout shrunk to fit: a narrow sidebar list squeezed beside an unreadable detail column at 390px, or both stacked so the detail sits below a long list, with small rows, the selected item marked only by a tinted background, and no way back except the browser.",
      "why_this_is_better": [
        "On phones the list and the detail are separate views; opening a row replaces the list instead of pushing the content below the fold.",
        "Rows are full-width buttons at least 44px tall, with the title, a date and two lines of content, so people can tell records apart before they open one.",
        "The detail view has a visible back button that names where it goes (\"All notes\") and returns focus to the row that was opened.",
        "From 768px both panes fit, so the list stays in view beside the open record and the back button disappears.",
        "The selected row is marked with a bar, a fill, bolder text and aria-current, not by colour alone.",
        "Empty and failed loads replace the list with a message that says what happened and one way forward."
      ],
      "failures": [
        "Keeping the selection only in component state in a real app. Use your router so links, refresh and the browser Back button work; this item stays state-driven so it installs anywhere.",
        "Stacking the detail below the list on phones, so opening a row does nothing visible.",
        "Dropping the back button because \"the browser has one\", or labelling it only with an arrow icon.",
        "Moving focus into the detail on wide screens, which loses people's place in the list while they compare records.",
        "Shrinking row padding to fit more rows on a phone until the targets fall under 44px."
      ],
      "states": ["default", "detail", "empty", "error"],
      "responsive": {
        "desktop": "From 768px, a bordered two-pane layout under one header with the list name and count; the list (up to 22rem) sits beside the open record, which shows the first record until another is chosen.",
        "mobile": "Below 768px, one view at a time, edge to edge. The list shows full-width rows; opening one shows the record with a back button at the top, and the list header is kept only for screen readers."
      },
      "a11y": [
        "The list name is the section's heading and labels the list; the open record is an article labelled by its own heading, one level deeper.",
        "Rows are native buttons, at least 44px tall, with a visible focus ring; the open row has aria-current and a visible bar.",
        "On phones, opening a row moves focus to the record's heading and Back returns it to that row, so focus never lands on a hidden view.",
        "On wide screens focus stays in the list and a polite live region announces which record is shown.",
        "The error message starts with a text label, so it does not rely on colour."
      ],
      "status": "community",
      "reviewed_by": [],
      "reviewed_at": null,
      "contributors": [],
      "provenance": "original",
      "license": "MIT"
    }
  }
}
