torch-glare 2.2.1 → 2.4.0

package/apps/lib/components/TabSwitch.tsx

@@ -0,0 +1,181 @@
+"use client";
+
+import { forwardRef, type ReactNode } from "react";
+import { cva, type VariantProps } from "class-variance-authority";
+import { cn } from "../utils/cn";
+import { Themes } from "../utils/types";
+
+/**
+ * TabSwitch — a segmented control for picking one option from a small set.
+ *
+ * The classic "List / Cards"-style pill switcher: a rounded track holding one
+ * button per option, with the active option rendered as a raised pill. Thin
+ * dividers sit between adjacent inactive options (never flanking the active
+ * pill). Generic over the option value, controlled via `value`/`onValueChange`,
+ * theme-aware, and built on semantic presentation tokens so it adapts to
+ * light/dark/default themes.
+ */
+
+export interface TabSwitchOption<T extends string = string> {
+  value: T;
+  label?: ReactNode;
+  /** Optional leading icon (Remix `<i>`, lucide svg, etc.). */
+  icon?: ReactNode;
+  disabled?: boolean;
+}
+
+// The track (outer container) holds the segmented buttons.
+const trackStyles = cva(
+  [
+    "inline-flex items-center w-fit",
+    "rounded-[10px]",
+    "bg-background-presentation-body-primary",
+    "shadow-[inset_0_0_4px_0_rgba(0,0,0,0.08)]",
+  ],
+  {
+    variants: {
+      size: {
+        S: ["gap-[2px] p-[2px]"],
+        M: ["gap-[2px] p-[2px]"],
+        L: ["gap-[3px] p-[3px]"],
+      },
+    },
+    defaultVariants: { size: "M" },
+  },
+);
+
+// Each option button. The active pill is raised; inactive options are
+// transparent and lighten on hover.
+const optionStyles = cva(
+  [
+    "flex items-center justify-center gap-[6px]",
+    "rounded-[8px]",
+    "font-[510] leading-none",
+    "transition-all duration-200 ease-in-out",
+    "outline-none",
+    "focus-visible:ring-2 focus-visible:ring-border-presentation-state-focus",
+    "disabled:cursor-not-allowed disabled:opacity-50",
+  ],
+  {
+    variants: {
+      size: {
+        S: [
+          "h-5 px-2 text-[12px]",
+          "[&_svg]:h-3 [&_svg]:w-3",
+          "[&_i]:text-[12px]",
+        ],
+        M: [
+          "h-6 px-3 text-[14px]",
+          "[&_svg]:h-[14px] [&_svg]:w-[14px]",
+          "[&_i]:text-[14px]",
+        ],
+        L: [
+          "h-8 px-4 text-[16px]",
+          "[&_svg]:h-4 [&_svg]:w-4",
+          "[&_i]:text-[16px]",
+        ],
+      },
+      active: {
+        // Active option = a solid raised WHITE pill with dark text, in every
+        // theme. The selected-tab design tokens encode a different look per
+        // theme (black pill on light, translucent-white on dark), but the
+        // intended switcher is always a white pill — and it must stay visible
+        // on the always-dark DataViews header bar — so the active pill is
+        // theme-independent here. The track + inactive options remain
+        // theme-aware.
+        true: [
+          "bg-white",
+          "text-[#1C1D1F]",
+          "border border-black/5",
+          "shadow-[0_1px_3px_0_rgba(0,0,0,0.18)]",
+        ],
+        false: [
+          "border border-transparent",
+          "bg-transparent",
+          "text-content-presentation-global-primary",
+          "hover:bg-background-presentation-tab-hover",
+        ],
+      },
+    },
+    defaultVariants: { size: "M", active: false },
+  },
+);
+
+interface Props<T extends string = string>
+  extends
+    Omit<React.HTMLAttributes<HTMLDivElement>, "onChange">,
+    VariantProps<typeof trackStyles> {
+  options: TabSwitchOption<T>[];
+  /** Controlled selected value. */
+  value: T;
+  onValueChange: (value: T) => void;
+  theme?: Themes;
+  disabled?: boolean;
+}
+
+function TabSwitchInner<T extends string = string>(
+  {
+    options,
+    value,
+    onValueChange,
+    size,
+    theme,
+    disabled,
+    className,
+    ...props
+  }: Props<T>,
+  ref: React.ForwardedRef<HTMLDivElement>,
+) {
+  return (
+    <div
+      ref={ref}
+      role="tablist"
+      data-theme={theme}
+      className={cn(trackStyles({ size }), className)}
+      {...props}
+    >
+      {options.map((option, idx) => {
+        const active = option.value === value;
+        const prevActive = idx > 0 && options[idx - 1].value === value;
+        // A divider sits between two inactive options only — the active pill is
+        // never flanked by one.
+        const showDivider = idx > 0 && !active && !prevActive;
+        const isDisabled = disabled || option.disabled;
+
+        return (
+          <div key={option.value} className="flex items-center">
+            {showDivider && (
+              <div className="mx-[3px] h-3 w-px bg-border-presentation-action-disabled" />
+            )}
+            <button
+              type="button"
+              role="tab"
+              aria-selected={active}
+              aria-pressed={active}
+              disabled={isDisabled}
+              onClick={() => onValueChange(option.value)}
+              className={cn(optionStyles({ size, active }))}
+            >
+              {option.icon && (
+                <span className="flex items-center justify-center">
+                  {option.icon}
+                </span>
+              )}
+              {option.label}
+            </button>
+          </div>
+        );
+      })}
+    </div>
+  );
+}
+
+// forwardRef loses the generic, so we cast to preserve `<TabSwitch<T> />` typing.
+export const TabSwitch = forwardRef(TabSwitchInner) as <
+  T extends string = string,
+>(
+  props: Props<T> & { ref?: React.ForwardedRef<HTMLDivElement> },
+) => ReturnType<typeof TabSwitchInner>;
+
+// @ts-expect-error — attach displayName to the cast function for devtools.
+TabSwitch.displayName = "TabSwitch";

package/docs/components/context-menu.md

@@ -233,6 +233,33 @@ function RtlMenu() {
 }
 ```
 
+### Long Menu (max height + scroll)
+
+Tall menus scroll instead of overflowing off-screen. The surface caps at `maxHeight` (default `320`px) and never exceeds the space available after collision handling. Pass `maxHeight` to change the cap.
+
+```typescript
+import { ContextMenu, ContextMenuTrigger, ContextMenuContent, ContextMenuItem, ContextMenuLabel } from '@torch-ui/components'
+
+function LongMenu() {
+  return (
+    <ContextMenu>
+      <ContextMenuTrigger asChild>
+        <div className="flex h-40 w-72 items-center justify-center rounded-md border border-dashed">
+          Right-click here
+        </div>
+      </ContextMenuTrigger>
+      {/* Cap the surface at 220px — the rest scrolls. */}
+      <ContextMenuContent maxHeight={220}>
+        <ContextMenuLabel>Jump to section</ContextMenuLabel>
+        {Array.from({ length: 20 }, (_, i) => (
+          <ContextMenuItem key={i}>Section {i + 1}</ContextMenuItem>
+        ))}
+      </ContextMenuContent>
+    </ContextMenu>
+  )
+}
+```
+
 ## API Reference
 
 ### ContextMenu (Root)
@@ -264,6 +291,7 @@ The right-click zone. Wrap it around the element the menu should open from.
 | `theme` | `'dark' \| 'light' \| 'default'` | - | Theme variant (applied as `data-theme`) |
 | `className` | `string` | - | Additional CSS classes |
 | `collisionPadding` | `number` | `8` | Min distance kept from the viewport edge |
+| `maxHeight` | `number` | `320` | Max height (px) of the surface before it scrolls. Capped at `min(maxHeight, available-height)` so the menu never overflows off-screen |
 | `autoGroup` | `boolean` | `true` | Auto-wrap loose items in a Boxed group (see Behavior notes) |
 
 ### ContextMenuItem
@@ -353,6 +381,7 @@ interface ContextMenuContentProps {
   theme?: 'dark' | 'light' | 'default'
   className?: string
   collisionPadding?: number // default 8
+  maxHeight?: number         // default 320 — surface scrolls past this
   autoGroup?: boolean        // default true
 }
 
@@ -403,6 +432,7 @@ export const ContextMenuRadioItem: React.ForwardRefExoticComponent<ContextMenuRa
 - **Opens at the pointer**: the menu opens on right-click (`contextmenu`) at the exact cursor position, not anchored to a fixed trigger button.
 - **Second right-click closes it**: the Root is made controlled and tracks `open` in context. The Trigger listens in the capture phase, and when the menu is already open it `preventDefault()` / `stopPropagation()` and closes — so a second right-click dismisses instead of re-anchoring (which Radix handles unreliably).
 - **Auto-grouping**: by default (`autoGroup` on `ContextMenuContent`, default `true`) consecutive loose items (`ContextMenuItem`, `ContextMenuCheckboxItem`, `ContextMenuRadioItem`, and `ContextMenuSub`) are automatically wrapped in a `Boxed` `ContextMenuGroup`, so they render inside a boxed container like DropdownMenu even when you do not write a group. Labels and explicit groups act as boundaries and pass through unchanged. Set `autoGroup={false}` to render children verbatim.
+- **Max height & scrolling**: the surface caps its height at `min(maxHeight, available-height)` (where `maxHeight` defaults to `320`px and `available-height` is the space Radix has after collision handling). A taller menu scrolls vertically instead of overflowing off-screen — items and groups keep their full height rather than squishing. Pass `maxHeight={N}` to change the cap.
 - **Checkbox / radio keep the menu open**: `ContextMenuCheckboxItem` and `ContextMenuRadioItem` call `event.preventDefault()` inside `onSelect`, stopping Radix's default auto-close so users can toggle multiple options in one pass.
 - **Open-only animation**: only the open (enter) state animates (`fade-in`). There is intentionally no exit animation — holding the old DOM node during close breaks close/reposition on a second right-click, so it is omitted to keep repositioning reliable.
 - **Submenus and RTL**: nested `ContextMenuSub` / `ContextMenuSubTrigger` / `ContextMenuSubContent` are supported, and `dir="rtl"` on the Root mirrors the layout (including the submenu chevron).

package/docs/components/data-views-config-panel.md

@@ -148,7 +148,7 @@ render `DataViewsConfigPanel` yourself (example above) or extend the layout
 | Saved View | `savedViews` / `activeSavedView` | Radio list + "Save a New View" button. |
 | Table Columns | `config.tableColumns` | Green `Switch` per column toggles `visible`; rows are drag-reorderable (HTML5 DnD) and patch `order`. |
 | Default Sort | `config.sortBy` | Single-choice radio; selecting sets `sortBy`. Direction stays on `config.sortOrder`. |
-| Filters tab | `filterState` + `fields` | Renders `FilterPanel` restyled full-width/transparent. |
+| Filters tab | `filterState` + `fields` | Renders `FilterPanel` restyled full-width/transparent. Categorical fields render as checkbox/radio lists, or a `SearchableSelect` dropdown when a field sets `filterVariant: "searchable-select"`. |
 
 ## Internal: PanelControls
 
@@ -173,8 +173,8 @@ Common changes and where to make them:
 |---|---|
 | Make Saved View work through `DataViewsLayout` | Add `savedViews` / `activeSavedView` / `onSavedViewChange` / `onSaveNewView` to `DataViewsLayoutProps`, hold them in layout state (or accept from the host), and forward them to `<DataViewsConfigPanel>` at its render site in `DataViewsLayout.tsx`. |
 | Add a new Config section | Add a new block inside the Config. tab in `DataViewsConfigPanel.tsx`, backed by a `config.*` field so `onConfigChange` persists it. |
-| Restyle a radio/toggle | Edit `PanelControls.tsx`. Keep values matching the Figma spec; do not swap in the shared `Radio`/`Label` (they impose theming/layout that fights the dark panel — this was deliberate). |
-| Change the dark chrome | The root forces `data-theme="dark"` and uses hardcoded hex (`#1C1D1F`, `#252729`, `#005ECC`, `#626467`, `#0AC713`). These are intentional Figma values, not tokens. |
+| Restyle a radio/toggle | Edit the radio ring in `DataViewRadio.tsx` (the `RadioRow` in `PanelControls.tsx` just wraps it) or the switch in `PanelControls.tsx`. Keep the hardcoded hex matching the Figma spec; do not swap in the shared `Radio`/`Label` (they impose theming/layout that fights the dark panel — this was deliberate). |
+| Change the dark chrome | The root forces `data-theme="dark"` and uses hardcoded hex (`#1C1D1F`, `#252729`, `#005ECC`, `#0075FF`, `#626467`, `#0AC713`). These are intentional Figma values, not tokens — the radio/checkbox rings hardcode them (`#626467` border, `rgba(255,255,255,0.05)` fill, `#0075FF` selected) so the panel always renders dark regardless of host `data-theme`. |
 
 After any change to the panel docs or component, update this file and rebuild
 the MCP server (`cd mcp && pnpm build`) so the docs the server serves stay in

package/docs/components/data-views-layout.md

@@ -176,7 +176,11 @@ Inbox auto-detects `isRead`, `isStarred`, `hasAttachment`, `priority`. Override
 | `type` | `FieldType` | Renderer key (see below). Auto-inferred if omitted. |
 | `visible` | `boolean` | Show in cells. Default `true`. |
 | `order` | `number` | Display order. |
-| `filterable` | `boolean` | Surface this field in the filter panel. |
+| `filterable` | `boolean` | Surface this field in the filter panel. The control adapts to the field `type`: categorical fields render checkboxes/radios (or a searchable dropdown via `filterVariant`), numeric fields a range slider, and **date / date-format fields a From + To pair of Glare `DatePicker`s** (two single-date pickers bounding the range). Set `false` to explicitly exclude a field the panel would otherwise auto-detect (e.g. an `id` or `name` with few unique values). |
+| `filterLabel` | `string` | Override the label shown above this field's filter (defaults to `label`). |
+| `filterMode` | `"single" \| "multi"` | Categorical selection mode. `"multi"` (default) renders checkboxes; `"single"` renders radios. |
+| `filterVariant` | `"checkbox" \| "searchable-select"` | Categorical control style. `"checkbox"` (default) is the inline checkbox/radio list; `"searchable-select"` renders a single-select `SearchableSelect` dropdown — useful when a field has many options. Implies single-select. |
+| `filterOptions` | `string[] \| { label: string; value: string }[]` | Explicit option list for the categorical filter (otherwise options are collected from the data). |
 | `variants` | `Record<string, BadgeVariant>` | For `enum-badge`: per-value color map. |
 | `currency` | `string \| CurrencyOptions` | For `currency`: ISO code or `{ symbol, locale, decimals, code }`. |
 | `thresholds` | `[number, number]` | For `progress-bar`: warning/ok thresholds. |
@@ -188,6 +192,8 @@ Inbox auto-detects `isRead`, `isStarred`, `hasAttachment`, `priority`. Override
 
 `text` · `number` · `date` · `date-format` · `boolean` · `currency` · `number-format` · `enum-badge` · `badge-array` · `progress-bar` · `star-rating` · `icon-text` · `two-line` · `avatar` · `link` · `image` · `hidden`
 
+> **`hidden` vs `filterable: false`** — use `type: "hidden"` to drop a field from the UI **entirely** (no column, no column-toggle in the config panel, no filter) while it stays in the data for row identity — e.g. an `id` you key rows by but never want shown. Use `filterable: false` to keep a field as a **column** but remove only its **filter**.
+
 ### `BadgeVariant`
 
 `green` · `greenLight` · `cocktailGreen` · `yellow` · `redOrange` · `redLight` · `rose` · `purple` · `bluePurple` · `blue` · `navy` · `gray` · `highlight`
@@ -268,7 +274,7 @@ function CustomScreen({ data, fields }: Props) {
 
 ## Accessibility
 
-- The view-switcher uses `TabFormItem` (button-based, full keyboard support via Tab/Enter/Space).
+- The view-switcher uses [`TabSwitch`](./tab-switch.md) — a segmented `role="tablist"` control (each view a `role="tab"` button, full keyboard support via Tab/Enter/Space). Installing DataViews pulls in `TabSwitch` automatically.
 - Tree rows expose `role="treeitem"` with `aria-expanded` and `aria-selected`.
 - Filter checkboxes carry labels and `htmlFor` linkage.
 - Settings panel buttons have `aria-pressed` for sort direction.
@@ -284,4 +290,5 @@ The component uses only `*-presentation-*` design tokens. Wrap with `ThemeProvid
 - [`KanbanView`](./kanban-view.md) — standalone kanban
 - [`InboxView`](./inbox-view.md) — standalone inbox
 - [`TreeView`](./tree-view.md) — standalone tree
+- [`TabSwitch`](./tab-switch.md) — the segmented view-switcher in the header (reusable on its own)
 - [How-to: Render a backend response with DataViews](../how-to/data-views-from-backend-response.md) — recipes by data shape.

package/docs/components/dropdown-menu.md

@@ -299,6 +299,32 @@ function Example() {
 }
 ```
 
+### Long Menu (max height + scroll)
+
+Tall menus scroll instead of overflowing off-screen. The surface caps at `maxHeight` (default `320`px) and never exceeds the space available after collision handling. Pass `maxHeight` to change the cap.
+
+```typescript
+import { DropdownMenu, DropdownMenuTrigger, DropdownMenuContent, DropdownMenuItem, DropdownMenuLabel } from '@torch-ui/components'
+import { Button } from '@torch-ui/components'
+
+function LongMenu() {
+  return (
+    <DropdownMenu>
+      <DropdownMenuTrigger asChild>
+        <Button variant="BorderStyle">Jump to section</Button>
+      </DropdownMenuTrigger>
+      {/* Cap the surface at 240px — the rest scrolls. */}
+      <DropdownMenuContent align="start" maxHeight={240}>
+        <DropdownMenuLabel>Sections</DropdownMenuLabel>
+        {Array.from({ length: 20 }, (_, i) => (
+          <DropdownMenuItem key={i}>Section {i + 1}</DropdownMenuItem>
+        ))}
+      </DropdownMenuContent>
+    </DropdownMenu>
+  )
+}
+```
+
 ## API Reference
 
 ### DropdownMenu (Root)
@@ -326,6 +352,7 @@ function Example() {
 | `sideOffset` | `number` | `4` | Distance from trigger |
 | `collisionPadding` | `number` | `8` | Gap kept from viewport edges when flipping/shifting |
 | `align` | `'start' \| 'center' \| 'end'` | `'center'` | Alignment (inherited from Radix) |
+| `maxHeight` | `number` | `320` | Max height (px) of the surface before it scrolls. Capped at `min(maxHeight, available-height)` so the menu never overflows off-screen |
 | `autoGroup` | `boolean` | `true` | Auto-wrap loose items in boxed groups |
 
 ### DropdownMenuItem
@@ -426,6 +453,7 @@ interface DropdownMenuContentProps {
   sideOffset?: number
   collisionPadding?: number
   align?: 'start' | 'center' | 'end'
+  maxHeight?: number         // default 320 — surface scrolls past this
   autoGroup?: boolean
 }
 

package/docs/components/header-bar.md

@@ -0,0 +1,181 @@
+---
+title: HeaderBar
+description: Variant-driven page/form header chip pairing a colored emphasis pill with a plain title.
+component: true
+group: Layout
+keywords: [header, headerbar, page-header, form-header, title, badge, label, layout]
+---
+
+# HeaderBar
+
+A presentational header chip used at the top of a form, page, or drawer to communicate the current record context — for example "NEW sales invoice", "EDIT sales invoice", or "ORDER de-344". It pairs a colored emphasis pill (the `label`) with a plain `title`, and the `variant` controls both the pill color and which side the pill sits on. The surface is always a fixed dark container, and the component is non-interactive.
+
+## Installation
+
+```bash
+npx torch-glare@latest add HeaderBar
+```
+
+## Imports
+
+```typescript
+import HeaderBar from '@/components/HeaderBar'
+```
+
+```typescript
+import { HeaderBar } from '@/components/HeaderBar'
+```
+
+Both the default export and the named export resolve to the same component. The website convention is the default import.
+
+## Basic Usage
+
+```tsx
+import HeaderBar from '@/components/HeaderBar'
+
+export function BasicHeaderBar() {
+  return (
+    <HeaderBar
+      variant="new"
+      label="New"
+      title="sales iNVOICE"
+    />
+  )
+}
+```
+
+## Examples
+
+### New Invoice Header
+
+The `new` variant renders a blue emphasis pill on the left followed by the plain title on the right. Use it on create screens.
+
+```tsx
+import HeaderBar from '@/components/HeaderBar'
+
+export function NewInvoiceHeader() {
+  return (
+    <HeaderBar
+      variant="new"
+      label="New"
+      title="sales iNVOICE"
+    />
+  )
+}
+```
+
+### Edit Header
+
+The `edit` variant shares the exact same layout as `new` (pill left, title right) but uses an orange emphasis pill. Use it on edit screens.
+
+```tsx
+import HeaderBar from '@/components/HeaderBar'
+
+export function EditInvoiceHeader() {
+  return (
+    <HeaderBar
+      variant="edit"
+      label="edit"
+      title="sales iNVOICE"
+    />
+  )
+}
+```
+
+### Detail Header
+
+The `detail` variant swaps the positions: the plain title renders on the left and the colored (white-alpha) pill renders on the right. Use it for read-only record context such as an order reference.
+
+```tsx
+import HeaderBar from '@/components/HeaderBar'
+
+export function OrderDetailHeader() {
+  // Renders as:  SALES INVOICE  [ de-344 ]
+  // plain title on the LEFT, badge on the RIGHT
+  return (
+    <HeaderBar
+      variant="detail"
+      label="de-344"
+      title="sales iNVOICE"
+    />
+  )
+}
+```
+
+### Themed
+
+HeaderBar accepts a `theme` prop applied via `data-theme`. The surface is always a dark chip, so theming is most useful for keeping the component consistent with the surrounding `data-theme` scope.
+
+```tsx
+import HeaderBar from '@/components/HeaderBar'
+
+export function ThemedHeaderBars() {
+  return (
+    <div className="flex flex-col gap-4">
+      <HeaderBar variant="new" label="New" title="sales iNVOICE" theme="dark" />
+      <HeaderBar variant="edit" label="edit" title="sales iNVOICE" theme="light" />
+      <HeaderBar variant="detail" label="de-344" title="sales iNVOICE" theme="default" />
+    </div>
+  )
+}
+```
+
+## API Reference
+
+### HeaderBar Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| variant | `'new' \| 'edit' \| 'detail'` | `'new'` | Controls both the pill color and which side the pill sits on |
+| label | `string` | — (required) | Text rendered inside the colored emphasis pill |
+| title | `string` | — (required) | Plain text rendered alongside the pill |
+| theme | `Themes` | — | Theme variant applied via `data-theme` (`'dark' \| 'light' \| 'default'`) |
+| className | `string` | — | Additional CSS classes merged onto the root element |
+
+All standard `HTMLAttributes<HTMLDivElement>` (for example `id`, `aria-*`, `data-*`, `style`, `onClick`) pass through to the root `div`.
+
+## Variants
+
+| Variant | Pill color | Pill text | Layout (left → right) |
+|---------|-----------|-----------|------------------------|
+| `new` | `bg-blue-sparkle-alpha-50` | `text-blue-sparkle-200` | pill (`label`) → title |
+| `edit` | `bg-orange-alpha-50` | `text-orange-200` | pill (`label`) → title |
+| `detail` | `bg-white-alpha-30` | `text-white-00` | title → pill (`label`) — positions swapped |
+
+## Styling
+
+- **Fixed dark container**: `rounded-[14px]`, `border-black-600`, `bg-black-1000`, `p-1.5`, with a double soft shadow. The surface is always dark regardless of theme.
+- **Layout**: the root is `inline-flex`, so the chip hugs its content rather than stretching to fill its parent.
+- **Typography**: 28px, weight 510, uppercase, SF Pro with the `cv05` stylistic set. Both `label` and `title` render uppercase.
+- **Emphasis pill**: the colored badge background and text color are driven entirely by `variant` (see the Variants table). For `detail`, the pill also moves to the right side.
+
+## TypeScript Types
+
+```typescript
+import { HTMLAttributes } from 'react'
+import { Themes } from '@/utils/types'
+
+interface HeaderBarProps extends HTMLAttributes<HTMLDivElement> {
+  variant?: 'new' | 'edit' | 'detail'
+  label: string
+  title: string
+  theme?: Themes
+  className?: string
+}
+```
+
+## Accessibility
+
+- HeaderBar is purely presentational — it has no interactive behavior and is intended to label the surrounding content visually.
+- Because the text is rendered uppercase via styling (not the source string), screen readers receive the original casing of `label` and `title`.
+- Pass any `aria-*` attributes through the standard prop spread when the chip needs an explicit accessible role or label in its context.
+- HeaderBar does not render an HTML heading element. When this chip represents the page or section heading, ensure proper heading semantics exist in the surrounding layout (for example an `<h1>` / `<h2>` for the page) so document structure remains navigable.
+
+## Best Practices
+
+1. **Match the variant to the screen mode**: use `new` for create screens, `edit` for edit screens, and `detail` for read-only record context.
+2. **Keep `label` short**: it is the emphasis pill, so a concise token (a mode word like "New" / "edit" or a record reference like "de-344") reads best — text renders UPPERCASE automatically.
+3. **Use `title` for the record type**: the plain side should name the entity (for example "sales invoice", "Order"), not duplicate the label.
+4. **Expect the detail swap**: for `variant="detail"` the pill moves to the right and the title to the left — author content with that ordering in mind.
+5. **Don't rely on it for interactivity**: HeaderBar is a label, not a control; place buttons or actions in a separate toolbar.
+6. **Let it hug its content**: the chip is `inline-flex`; avoid forcing it to full width and keep it at the top of the form, page, or drawer it describes.