torch-glare 2.3.0 → 2.4.1

package/docs/components/dropdown-menu.md

@@ -11,40 +11,31 @@ keywords: [dropdown-menu, menu, radix-ui, submenu, checkbox, radio, auto-group]
 
 ## Installation
 
+TORCH Glare is a copy-in library: the CLI copies this component's source into your project
+(you do **not** install it from the npm package). Run `init` once, then `add`:
+
 ```bash
-npm install @radix-ui/react-dropdown-menu
+npx torch-glare@latest init
+npx torch-glare@latest add DropdownMenu
 ```
 
+`add` also copies any components, hooks, and utilities that `DropdownMenu` depends on.
+
 ## Import
 
-```typescript
-import {
-  DropdownMenu,
-  DropdownMenuTrigger,
-  DropdownMenuContent,
-  DropdownMenuItem,
-  DropdownMenuCheckboxItem,
-  DropdownMenuRadioGroup,
-  DropdownMenuRadioItem,
-  DropdownMenuLabel,
-  DropdownMenuShortcut,
-  DropdownMenuSub,
-  DropdownMenuSubTrigger,
-  DropdownMenuSubContent,
-  DropdownMenuGroup,
-  DropdownMenuPortal,
-} from '@torch-ui/components'
-```
+Import from your project's local path — the alias configured in `glare.json` (e.g. `@/*`):
 
-> **Auto-grouping:** Loose items placed directly in `DropdownMenuContent` (or `DropdownMenuSubContent`) are automatically wrapped in a boxed group, so they render inside a rounded container without you writing `DropdownMenuGroup` yourself. A `DropdownMenuLabel`, an explicit `DropdownMenuGroup`, or a `DropdownMenuRadioGroup` acts as a boundary that starts a new box. Disable this with `autoGroup={false}` on the content. (There is no `DropdownMenuSeparator` — separation comes from labels and the boxed groups.)
+```tsx
+import { DropdownMenu } from "@/components/DropdownMenu";
+```
 
 ## Quick Examples
 
 ### Basic Menu
 
 ```typescript
-import { DropdownMenu, DropdownMenuTrigger, DropdownMenuContent, DropdownMenuItem } from '@torch-ui/components'
-import { Button } from '@torch-ui/components'
+import { DropdownMenu, DropdownMenuTrigger, DropdownMenuContent, DropdownMenuItem } from "@/components/DropdownMenu";
+import { Button } from "@/components/Button";
 
 function Example() {
   return (
@@ -65,7 +56,7 @@ function Example() {
 ### With Icons
 
 ```typescript
-import { DropdownMenu, DropdownMenuTrigger, DropdownMenuContent, DropdownMenuItem } from '@torch-ui/components'
+import { DropdownMenu, DropdownMenuTrigger, DropdownMenuContent, DropdownMenuItem } from "@/components/DropdownMenu";
 
 function IconMenu() {
   return (
@@ -97,7 +88,7 @@ function IconMenu() {
 ### With Keyboard Shortcuts
 
 ```typescript
-import { DropdownMenu, DropdownMenuTrigger, DropdownMenuContent, DropdownMenuItem, DropdownMenuShortcut } from '@torch-ui/components'
+import { DropdownMenu, DropdownMenuTrigger, DropdownMenuContent, DropdownMenuItem, DropdownMenuShortcut } from "@/components/DropdownMenu";
 
 function ShortcutMenu() {
   return (
@@ -129,7 +120,7 @@ function ShortcutMenu() {
 Labels act as section boundaries. The loose items between labels are automatically wrapped in boxed groups — no separator component needed.
 
 ```typescript
-import { DropdownMenu, DropdownMenuTrigger, DropdownMenuContent, DropdownMenuItem, DropdownMenuLabel } from '@torch-ui/components'
+import { DropdownMenu, DropdownMenuTrigger, DropdownMenuContent, DropdownMenuItem, DropdownMenuLabel } from "@/components/DropdownMenu";
 
 function OrganizedMenu() {
   return (
@@ -158,7 +149,7 @@ function OrganizedMenu() {
 Checkbox and radio items keep the menu **open** when toggled (the built-in `onSelect` calls `preventDefault`), so users can change several options without the menu closing each time.
 
 ```typescript
-import { DropdownMenu, DropdownMenuTrigger, DropdownMenuContent, DropdownMenuCheckboxItem } from '@torch-ui/components'
+import { DropdownMenu, DropdownMenuTrigger, DropdownMenuContent, DropdownMenuCheckboxItem } from "@/components/DropdownMenu";
 import { useState } from 'react'
 
 function CheckboxMenu() {
@@ -199,7 +190,7 @@ function CheckboxMenu() {
 ### With Radio Group
 
 ```typescript
-import { DropdownMenu, DropdownMenuTrigger, DropdownMenuContent, DropdownMenuRadioGroup, DropdownMenuRadioItem } from '@torch-ui/components'
+import { DropdownMenu, DropdownMenuTrigger, DropdownMenuContent, DropdownMenuRadioGroup, DropdownMenuRadioItem } from "@/components/DropdownMenu";
 import { useState } from 'react'
 
 function RadioMenu() {
@@ -225,7 +216,7 @@ function RadioMenu() {
 ### With Submenu
 
 ```typescript
-import { DropdownMenu, DropdownMenuTrigger, DropdownMenuContent, DropdownMenuItem, DropdownMenuSub, DropdownMenuSubTrigger, DropdownMenuSubContent } from '@torch-ui/components'
+import { DropdownMenu, DropdownMenuTrigger, DropdownMenuContent, DropdownMenuItem, DropdownMenuSub, DropdownMenuSubTrigger, DropdownMenuSubContent } from "@/components/DropdownMenu";
 
 function SubmenuExample() {
   return (
@@ -258,7 +249,7 @@ function SubmenuExample() {
 ### Disabled Items
 
 ```typescript
-import { DropdownMenu, DropdownMenuTrigger, DropdownMenuContent, DropdownMenuItem } from '@torch-ui/components'
+import { DropdownMenu, DropdownMenuTrigger, DropdownMenuContent, DropdownMenuItem } from "@/components/DropdownMenu";
 
 function DisabledMenu() {
   return (
@@ -281,7 +272,7 @@ function DisabledMenu() {
 For a true right-click (context) menu, use the dedicated [ContextMenu](./context-menu.md) component instead of DropdownMenu — it opens at the pointer on right-click / long-press.
 
 ```typescript
-import { ContextMenu, ContextMenuTrigger, ContextMenuContent, ContextMenuItem } from '@torch-ui/components'
+import { ContextMenu, ContextMenuTrigger, ContextMenuContent, ContextMenuItem } from "@/components/ContextMenu";
 
 function Example() {
   return (
@@ -299,6 +290,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 "@/components/DropdownMenu";
+import { Button } from "@/components/Button";
+
+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 +343,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 +444,7 @@ interface DropdownMenuContentProps {
   sideOffset?: number
   collisionPadding?: number
   align?: 'start' | 'center' | 'end'
+  maxHeight?: number         // default 320 — surface scrolls past this
   autoGroup?: boolean
 }
 
@@ -469,7 +488,7 @@ export const DropdownMenuRadioItem: React.ForwardRefExoticComponent<DropdownMenu
 ### With State Management
 
 ```typescript
-import { DropdownMenu, DropdownMenuTrigger, DropdownMenuContent, DropdownMenuItem } from '@torch-ui/components'
+import { DropdownMenu, DropdownMenuTrigger, DropdownMenuContent, DropdownMenuItem } from "@/components/DropdownMenu";
 import { useState } from 'react'
 
 function useDropdownMenu() {
@@ -508,7 +527,7 @@ function StatefulMenu() {
 
 ```typescript
 import { render, screen, fireEvent } from '@testing-library/react'
-import { DropdownMenu, DropdownMenuTrigger, DropdownMenuContent, DropdownMenuItem } from '@torch-ui/components'
+import { DropdownMenu, DropdownMenuTrigger, DropdownMenuContent, DropdownMenuItem } from "@/components/DropdownMenu";
 
 describe('DropdownMenu', () => {
   it('opens on trigger click', () => {

package/docs/components/field-hint.md

@@ -11,13 +11,22 @@ keywords: [field-hint, alert, validation, message, form, feedback, inline]
 
 ## Installation
 
-No external dependencies required.
+TORCH Glare is a copy-in library: the CLI copies this component's source into your project
+(you do **not** install it from the npm package). Run `init` once, then `add`:
+
+```bash
+npx torch-glare@latest init
+npx torch-glare@latest add FieldHint
+```
+
+`add` also copies any components, hooks, and utilities that `FieldHint` depends on.
 
 ## Import
 
-```typescript
-import { FieldHint } from '@torch-ui/components'
-import type { FieldHintProps } from '@torch-ui/components'
+Import from your project's local path — the alias configured in `glare.json` (e.g. `@/*`):
+
+```tsx
+import { FieldHint } from "@/components/FieldHint";
 ```
 
 ## Quick Examples
@@ -25,7 +34,7 @@ import type { FieldHintProps } from '@torch-ui/components'
 ### Basic Usage
 
 ```typescript
-import { FieldHint } from '@torch-ui/components'
+import { FieldHint } from "@/components/FieldHint";
 
 function Example() {
   return (
@@ -40,7 +49,7 @@ function Example() {
 ### All States
 
 ```typescript
-import { FieldHint } from '@torch-ui/components'
+import { FieldHint } from "@/components/FieldHint";
 
 function AllStates() {
   return (
@@ -72,8 +81,8 @@ function AllStates() {
 ### With Form Field
 
 ```typescript
-import { FieldHint } from '@torch-ui/components'
-import { InputField } from '@torch-ui/components'
+import { FieldHint } from "@/components/FieldHint";
+import { InputField } from "@/components/InputField";
 import { useState } from 'react'
 
 function WithFormField() {
@@ -115,7 +124,7 @@ function WithFormField() {
 ### Custom Icon
 
 ```typescript
-import { FieldHint } from '@torch-ui/components'
+import { FieldHint } from "@/components/FieldHint";
 
 function CustomIcon() {
   return (
@@ -145,8 +154,9 @@ function CustomIcon() {
 ### Password Validation
 
 ```typescript
-import { FieldHint } from '@torch-ui/components'
-import { InputField, PasswordLevel } from '@torch-ui/components'
+import { FieldHint } from "@/components/FieldHint";
+import { InputField } from "@/components/InputField";
+import { PasswordLevel } from "@/components/PasswordLevel";
 import { useState } from 'react'
 
 function PasswordValidation() {
@@ -199,8 +209,9 @@ function PasswordValidation() {
 ### Form Validation
 
 ```typescript
-import { FieldHint } from '@torch-ui/components'
-import { InputField, Button } from '@torch-ui/components'
+import { FieldHint } from "@/components/FieldHint";
+import { Button } from "@/components/Button";
+import { InputField } from "@/components/InputField";
 import { useState } from 'react'
 
 function FormValidation() {
@@ -289,8 +300,9 @@ function FormValidation() {
 ### API Response Feedback
 
 ```typescript
-import { FieldHint } from '@torch-ui/components'
-import { InputField, Button } from '@torch-ui/components'
+import { FieldHint } from "@/components/FieldHint";
+import { Button } from "@/components/Button";
+import { InputField } from "@/components/InputField";
 import { useState } from 'react'
 
 function APIFeedback() {
@@ -360,7 +372,7 @@ function APIFeedback() {
 ### File Upload Feedback
 
 ```typescript
-import { FieldHint } from '@torch-ui/components'
+import { FieldHint } from "@/components/FieldHint";
 import { useState } from 'react'
 
 function FileUploadFeedback() {
@@ -429,7 +441,7 @@ function FileUploadFeedback() {
 ### Multi-line Message
 
 ```typescript
-import { FieldHint } from '@torch-ui/components'
+import { FieldHint } from "@/components/FieldHint";
 
 function MultilineMessage() {
   return (
@@ -456,7 +468,7 @@ Please save your work before continuing.`}
 ### Dynamic Theme
 
 ```typescript
-import { FieldHint } from '@torch-ui/components'
+import { FieldHint } from "@/components/FieldHint";
 import { useState } from 'react'
 
 function DynamicTheme() {
@@ -488,8 +500,8 @@ function DynamicTheme() {
 ### Conditional Rendering
 
 ```typescript
-import { FieldHint } from '@torch-ui/components'
-import { InputField } from '@torch-ui/components'
+import { FieldHint } from "@/components/FieldHint";
+import { InputField } from "@/components/InputField";
 import { useState } from 'react'
 
 function ConditionalHints() {
@@ -579,7 +591,7 @@ export const FieldHint: React.FC<FieldHintProps>
 ### Usage with Types
 
 ```typescript
-import { FieldHint } from '@torch-ui/components'
+import { FieldHint } from "@/components/FieldHint";
 import { useState } from 'react'
 
 type ValidationState = {
@@ -607,7 +619,7 @@ function TypedExample() {
 ### Validation Hook
 
 ```typescript
-import { FieldHint } from '@torch-ui/components'
+import { FieldHint } from "@/components/FieldHint";
 import { useState, useCallback } from 'react'
 
 function useFieldValidation<T>(
@@ -665,8 +677,8 @@ function ValidatedField() {
 ### Form Field Wrapper
 
 ```typescript
-import { FieldHint } from '@torch-ui/components'
-import { InputField } from '@torch-ui/components'
+import { FieldHint } from "@/components/FieldHint";
+import { InputField } from "@/components/InputField";
 import { ReactNode } from 'react'
 
 interface FieldWrapperProps {
@@ -711,7 +723,7 @@ function FieldWrapper({
 
 ```typescript
 import { render, screen } from '@testing-library/react'
-import { FieldHint } from '@torch-ui/components'
+import { FieldHint } from "@/components/FieldHint";
 
 describe('FieldHint', () => {
   it('renders label text', () => {

package/docs/components/field-section.md

@@ -12,10 +12,16 @@ A structured form section component that provides consistent layout for form fie
 
 ## Installation
 
+TORCH Glare is a copy-in library: the CLI copies this component's source into your project
+(you do **not** install it from the npm package). Run `init` once, then `add`:
+
 ```bash
-npx torch-cli add field-section
+npx torch-glare@latest init
+npx torch-glare@latest add FieldSection
 ```
 
+`add` also copies any components, hooks, and utilities that `FieldSection` depends on.
+
 ## Imports
 
 ```typescript
@@ -346,7 +352,7 @@ export function ProfileSettingsForm() {
       >
         <div className="w-full flex items-center gap-4">
           <Avatar size="L" src="/default-avatar.jpg" />
-          <Button variant="SecStyle" size="M">
+          <Button variant="BluSecStyle" size="M">
             Upload New Photo
           </Button>
         </div>
@@ -490,7 +496,7 @@ export function AccountSettings() {
         }
       >
         <div className="w-full space-y-2">
-          <Button variant="DangerStyle" size="M">
+          <Button variant="RedSecStyle" size="M">
             Delete Account
           </Button>
         </div>

package/docs/components/form-stepper.md

@@ -14,10 +14,16 @@ The component is composed of `FormStepper`, `FormStep`, `FormStepIndicator`, and
 
 ## Installation
 
+TORCH Glare is a copy-in library: the CLI copies this component's source into your project
+(you do **not** install it from the npm package). Run `init` once, then `add`:
+
 ```bash
+npx torch-glare@latest init
 npx torch-glare@latest add FormStepper
 ```
 
+`add` also copies any components, hooks, and utilities that `FormStepper` depends on.
+
 ## Imports
 
 ```typescript

package/docs/components/form.md

@@ -1,6 +1,6 @@
 ---
 name: Form
-version: 1.1.15
+version: 2.4.0
 status: stable
 category: components/forms
 tags: [form, validation, react-hook-form, accessible, compound]
@@ -18,25 +18,22 @@ dependencies:
 
 ## Installation
 
+TORCH Glare is a copy-in library: the CLI copies this component's source into your project
+(you do **not** install it from the npm package). Run `init` once, then `add`:
+
 ```bash
-npm install torch-glare react-hook-form
+npx torch-glare@latest init
+npx torch-glare@latest add Form
 ```
 
+`add` also copies any components, hooks, and utilities that `Form` depends on.
+
 ## Import
 
-```typescript
-import {
-  Form,
-  FormField,
-  FormItem,
-  FormLabel,
-  FormControl,
-  FormDescription,
-  FormMessage
-} from 'torch-glare/lib/components/Form'
+Import from your project's local path — the alias configured in `glare.json` (e.g. `@/*`):
 
-// Also import from react-hook-form
-import { useForm } from 'react-hook-form'
+```tsx
+import { Form } from "@/components/Form";
 ```
 
 ## Quick Examples
@@ -52,9 +49,9 @@ import {
   FormLabel,
   FormControl,
   FormMessage
-} from 'torch-glare/lib/components/Form'
-import { Input } from 'torch-glare/lib/components/Input'
-import { Button } from 'torch-glare/lib/components/Button'
+} from '@/components/Form'
+import { Input } from '@/components/Input'
+import { Button } from '@/components/Button'
 
 function BasicForm() {
   const form = useForm({
@@ -213,9 +210,9 @@ function ValidatedForm() {
 ### With Multiple Field Types
 
 ```typescript
-import { Select, SelectTrigger, SelectContent, SelectItem, SelectValue } from 'torch-glare/lib/components/Select'
-import { Checkbox } from 'torch-glare/lib/components/Checkbox'
-import { RadioGroup, RadioGroupItem } from 'torch-glare/lib/components/Radio'
+import { Select, SelectTrigger, SelectContent, SelectItem, SelectValue } from '@/components/Select'
+import { Checkbox } from '@/components/Checkbox'
+import { RadioGroup, RadioGroupItem } from '@/components/Radio'
 
 function MultiFieldForm() {
   const form = useForm({

package/docs/components/header-bar.md

@@ -0,0 +1,187 @@
+---
+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
+
+TORCH Glare is a copy-in library: the CLI copies this component's source into your project
+(you do **not** install it from the npm package). Run `init` once, then `add`:
+
+```bash
+npx torch-glare@latest init
+npx torch-glare@latest add HeaderBar
+```
+
+`add` also copies any components, hooks, and utilities that `HeaderBar` depends on.
+
+## 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.