@ahrowe/ui 0.4.3 → 0.5.0

package/docs/SectionHeader.md

@@ -0,0 +1,90 @@
+# SectionHeader
+
+**When to use:** A reusable heading block for the top of a page, panel, card, or any section — a title with an optional subtitle, a leading icon or thumbnail, and a trailing actions area. Use it wherever you'd otherwise hand-roll a `<h2>` + subtitle + buttons row. Inside a `Card`, the card-scoped `CardHeader` remains available; `SectionHeader` is the standalone, fully slot-customisable version.
+
+**Import:** `import { SectionHeader, SectionHeaderSize } from '@ahrowe/ui'`
+**Types:** `import type { SectionHeaderProps, SectionHeaderAction } from '@ahrowe/ui'`
+
+**Style variants:** `SectionHeaderSize.Small` | `SectionHeaderSize.Medium` (default) | `SectionHeaderSize.Large`
+
+```tsx
+import { SectionHeader, SectionHeaderSize } from '@ahrowe/ui';
+import { faFolder, faPen, faTrash } from '@fortawesome/free-solid-svg-icons';
+
+// Title + subtitle
+<SectionHeader title="Account settings" subtitle="Manage your profile and preferences" />
+
+// Leading icon
+<SectionHeader icon={faFolder} title="Documents" subtitle="12 files" />
+
+// Leading thumbnail (URL → background image; any other ReactNode → rendered inside)
+<SectionHeader thumbnail="https://example.com/avatar.jpg" title="Jane Doe" subtitle="Designer" />
+
+// Trailing actions — array renders ActionIcons, or pass any ReactNode
+<SectionHeader
+  title="Integrations"
+  actions={[
+    { title: 'Edit', icon: faPen, onClick: handleEdit },
+    { title: 'Delete', icon: faTrash, onClick: handleDelete },
+  ]}
+/>
+<SectionHeader title="Reports" actions={<Button>Export</Button>} />
+
+// Larger scale, a bottom divider, and a semantic heading level for a11y
+<SectionHeader
+  size={SectionHeaderSize.Large}
+  level={1}
+  divider
+  title="Dashboard"
+  subtitle="Your workspace at a glance"
+/>
+
+// left / center — the title stays fixed to the left; everything else (left,
+// center, actions) lives in a separate trailing block laid out with
+// space-between, so `center` is centered within that block, not the whole header
+<SectionHeader
+  title="Team members"
+  left={<Chip text="12 active" />}
+  center={<SearchInput value={query} onChange={setQuery} />}
+  actions={[{ title: 'Invite', icon: faPlus, onClick: handleInvite }]}
+/>
+```
+
+**Enums:**
+
+- `SectionHeaderSize`: `Small` | `Medium` (default) | `Large`
+
+**Key props:**
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `title` | `ReactNode` | Main heading |
+| `subtitle` | `ReactNode` | Secondary text below the title |
+| `icon` | `IconDefinition` | FontAwesome icon shown on the left; ignored when `thumbnail` is set |
+| `thumbnail` | `string \| ReactNode` | URL → background image; any other ReactNode → rendered inside the leading circle |
+| `left` | `ReactNode` | Leftmost content of the trailing block (title stays fixed to the left of it) |
+| `center` | `ReactNode` | Center content of the trailing block, e.g. a search box or tabs |
+| `actions` | `SectionHeaderAction[] \| ReactNode` | Rightmost content of the trailing block: array → `ActionIcon`s; ReactNode → rendered as-is |
+| `level` | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | Semantic heading level for the title element (default `2`) |
+| `size` | `SectionHeaderSize` | Visual scale (default `Medium`) |
+| `divider` | `boolean` | Render a `Divider` below the header (default `false`) |
+
+**SectionHeaderAction:**
+
+```ts
+interface SectionHeaderAction {
+  title?: string;
+  icon: IconDefinition;
+  onClick?: (e: React.MouseEvent<HTMLDivElement>) => void;
+}
+```
+
+**Global defaults:** adopts `ConfigProvider` — set defaults app-wide via `defaultProps={{ SectionHeader: { size: SectionHeaderSize.Large } }}`. See [ConfigProvider.md](ConfigProvider.md).
+
+**Theming:** title size/weight per `size` variant come from the theme, with local fallbacks — `SectionHeaderSize.Large` uses `--header-font-size` (falls back `24px`), `Medium` uses `--header-medium-font-size` (falls back `18px`), `Small` uses `--header-small-font-size` (falls back `16px`); all three use `--header-font-weight` for the title's font weight (falls back `600`). The leading icon/thumbnail is sized at `2.2×` the title size, so it scales automatically with the theme; the subtitle size is fixed per `size` variant (not derived), since it doesn't track the title proportionally at the `Large` size. See [ThemeProvider.md](ThemeProvider.md).
+
+**Layout:** the title (with its leading icon/thumbnail) is fixed to the left and only takes the width its content needs. Everything after it — `left`, `center`, `actions` — lives in a separate `trailing` flex block laid out with `space-between`, so `center` is centered within that block (not the whole header) regardless of how wide `left`/`actions` are.
+
+**Responsive:** the header wraps — if `trailing` (`left`/`center`/`actions`) doesn't fit next to the title, it drops to its own row; if `trailing` itself doesn't fit as one row, its own children wrap too. Below `640px` viewport width, `center` additionally takes a full-width row of its own, so a wide `center` element (e.g. a `SearchInput`) isn't squeezed alongside `left`/`actions` on small screens.
+
+**Slots:** `root` `leading` `titles` `title` `subtitle` `trailing` `left` `center` `actions`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ahrowe/ui",
-  "version": "0.4.3",
+  "version": "0.5.0",
   "publishConfig": {
     "access": "public"
   },
@@ -55,6 +55,7 @@
     "preview": "vite preview",
     "gen-barrel": "tsx scripts/gen-barrel.ts",
     "gc": "bash src/scripts/generateComponent.sh $INIT_CWD process.argv",
+    "changeset": "changeset",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
     "format": "prettier --write .",
@@ -86,6 +87,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
+    "@changesets/cli": "^2.31.0",
     "@eslint/js": "^9.39.4",
     "@fortawesome/fontawesome-svg-core": "^7.2.0",
     "@fortawesome/free-solid-svg-icons": "^7.2.0",