{
  "name": "PageHeader",
  "source": "src/components/PageHeader.tsx",
  "propsType": "PageHeaderProps",
  "description": "PageHeader — the top of a page: where you are, what it is, and what you can\ndo to it.\n\nPromoted from the demo app, where five screens hand-wrote it in three\ndifferent shapes (`.demo-page__header`, `.demo-run-header`, and a bare\n`<div>`), each with its own gap and its own idea of where the actions\naligned. Every enterprise system ships one — Carbon's PageHeader,\nLightning's page headers — because every page has one.\n\nNOT A LANDMARK\n\nIt renders a `<div>`, not a `<header>`. A `<header>` that is a child of\n`<body>` is the page's banner, and the app shell's Header already is that.\nThe page's landmark is `<main>`, named by this title: pass `titleId` and\npoint `<main aria-labelledby>` at it.\n\nNo `'use client'`: `useId` resolves on the server, and nothing here is\ninteractive. Interactive parts arrive through the slots.",
  "import": "import { PageHeader } from 'ionbase-ui';",
  "status": "stable",
  "summary": "The top of a page: breadcrumb, the page's h1, a description, the record's status, and the page's actions. Not a landmark — main is, named by this title.",
  "useWhen": [
    "the top of every page inside the app shell — list pages, record pages, settings, wizards",
    "the page has a title and actions that act on the whole page, such as New agent or Pause"
  ],
  "useInstead": [
    {
      "when": "it is the bar across the top of the whole app, with the logo and the account menu",
      "use": "Header",
      "why": "Header is the banner landmark, rendered once by the shell. PageHeader is inside main and changes with each page"
    },
    {
      "when": "it titles one section of a page rather than the page",
      "use": "Card",
      "why": "a Card's title is an h2 for a named region; a page has one PageHeader and one h1"
    },
    {
      "when": "the page is empty or failed to load",
      "use": "EmptyState",
      "why": "keep the PageHeader so the user still knows where they are, and put the EmptyState beneath it with headingLevel 2"
    }
  ],
  "composition": {
    "order": [
      "PageHeader",
      "Breadcrumb",
      "Badge",
      "Button",
      "MenuTrigger",
      "Tabs"
    ],
    "note": "Slots, not children: `breadcrumb` above, `status` beside the title, `actions` at the end of the title row, and `children` as a row beneath for the page's Tabs or filters. Pass `titleId` and point `<main aria-labelledby>` at it.",
    "example": "<main aria-labelledby=\"page-title\"><PageHeader titleId=\"page-title\" title=\"Payroll reconciler\" description=\"Matches payroll exports against the ledger every night.\" breadcrumb={<Breadcrumb><BreadcrumbItem href=\"/agents\">Agents</BreadcrumbItem><BreadcrumbItem isCurrent>Payroll reconciler</BreadcrumbItem></Breadcrumb>} status={<Badge intent=\"warning\">Paused</Badge>} actions={<><MenuTrigger><Button variant=\"tertiary\" aria-label=\"More actions\" startIcon={<Icon as={Ellipsis} />} /><Menu onAction={run}><MenuItem key=\"delete\">Delete…</MenuItem></Menu></MenuTrigger><Button variant=\"primary-brand\">Resume</Button></>} /></main>"
  },
  "slots": {
    "breadcrumb": {
      "accepts": "Breadcrumb"
    },
    "status": {
      "accepts": [
        "Badge",
        "Tag"
      ],
      "note": "the record's state. Never an action, and never colour alone — a Badge carries its label"
    },
    "actions": {
      "accepts": [
        "Button",
        "MenuTrigger",
        "Link"
      ],
      "note": "most important last, so the primary action sits at the end of the row. One primary Button at most; beyond two or three actions, put the rest in a MenuTrigger"
    },
    "children": {
      "accepts": [
        "Tabs",
        "SegmentedControl"
      ],
      "note": "a row that belongs to the header: the page's own tabs, or the filters its table answers to"
    }
  },
  "a11y": {
    "role": "none — a <div>. The page's landmark is <main>, named by this title",
    "guarantees": [
      "the title is a real heading, h1 by default, with a stable id for aria-labelledby",
      "actions keep their DOM order when they wrap beneath the title on a narrow screen, so reading order matches visual order"
    ],
    "notes": [
      "`headingLevel` is 1 by default. Use 2 only for a header on a pane that is not the page — the detail half of a list-detail layout, under the list's h1.",
      "It is deliberately not a <header>: a <header> directly inside <body> is the banner, and the app shell's Header already is that."
    ]
  },
  "antiPatterns": [
    {
      "dont": "two PageHeaders on one page",
      "why": "two h1s, and two answers to where am I. Sections below the header are Cards with h2 titles"
    },
    {
      "dont": "dropping the PageHeader while the page loads or fails",
      "why": "the user loses where they are exactly when something went wrong. Keep the title; put Skeleton or EmptyState beneath it"
    },
    {
      "dont": "putting filters or a search field in `actions`",
      "why": "actions act on the page; filters narrow what it shows. Filters go in `children`, the row beneath"
    },
    {
      "dont": "several primary Buttons in `actions`",
      "why": "a page has one next step. The one-primary-action lint rule counts them"
    }
  ],
  "stylesheet": "src/styles/page-header.css",
  "tokens": [
    "--font-family-sans",
    "--font-weight-semibold",
    "--ion-page-header-heading-basis",
    "--spacing-16",
    "--spacing-4",
    "--spacing-8",
    "--text-default",
    "--text-secondary",
    "--type-body",
    "--type-body-line-height",
    "--type-h4",
    "--type-h4-line-height"
  ],
  "props": {
    "title": {
      "type": "React.ReactNode",
      "required": true,
      "origin": "own",
      "description": "The page's title. Rendered as the `h1`."
    },
    "titleId": {
      "type": "string | undefined",
      "required": false,
      "origin": "own",
      "description": "The title's id. Pass it when something else points at the heading —\n`<main aria-labelledby>` is the usual one. Generated when omitted."
    },
    "headingLevel": {
      "type": "PageHeaderHeadingLevel | undefined",
      "required": false,
      "origin": "own",
      "description": "Heading element for the title. Defaults to `1`."
    },
    "description": {
      "type": "React.ReactNode",
      "required": false,
      "origin": "own",
      "description": "One or two sentences under the title: what this page is for."
    },
    "breadcrumb": {
      "type": "React.ReactNode",
      "required": false,
      "origin": "own",
      "description": "A Breadcrumb, above the title."
    },
    "status": {
      "type": "React.ReactNode",
      "required": false,
      "origin": "own",
      "description": "Beside the title: a Badge or two for the record's state — \"Paused\",\n\"Draft\". State, not actions."
    },
    "actions": {
      "type": "React.ReactNode",
      "required": false,
      "origin": "own",
      "description": "At the end of the title row: the page's actions, most important last.\nOne primary Button at most; several more go in a MenuTrigger."
    },
    "children": {
      "type": "React.ReactNode",
      "required": false,
      "origin": "own",
      "description": "A row beneath, that belongs to the header rather than the page's\ncontent: the page's Tabs, or the filters its table answers to."
    }
  },
  "propCounts": {
    "own": 8,
    "aria": 0,
    "dom": 276,
    "other": 0
  }
}