@intellihr/blueberry 1.0.0-beta.112 → 1.0.0-beta.113

package/.claude-dist/skills/bb-blueberry/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: bb-blueberry
-description: Overview of Blueberry and Mango UI — what they are, how they relate, and which skills to use for React component work
+description: Use when building or modifying UI in this project — adding components, forms, buttons, inputs, layouts, icons, styling, or anything visual. This project uses @intellihr/blueberry (Mango* React components). Load this skill before touching any UI code.
 allowed-tools: Read, Glob, Grep
 ---
 
@@ -21,8 +21,9 @@ When building UI, follow this order strictly:
 
 1. **Mango wrapper component** — if a `Mango*` component does the job, use it
 2. **Mango utility classes** — for layout, typography, spacing, and colour reach for `mgo-*` classes via `className` before writing any CSS (see `/bb-mango-utility-classes`)
-3. **Inline styles** — only if no utility class covers the need
-4. **No other design systems or UI libraries** — do not introduce Tailwind, MUI, Chakra, Ant Design, or any other component/CSS library
+3. **Design token CSS variables** — when utility classes don't cover the need, use `--mgo-*` tokens in Vanilla Extract styles (see `/bb-mango-styling`)
+4. **Custom CSS** — Vanilla Extract only, last resort when tokens genuinely can't do the job
+5. **No other design systems or UI libraries** — do not introduce Tailwind, MUI, Chakra, Ant Design, or any other component/CSS library
 
 ---
 
@@ -34,7 +35,10 @@ When building UI, follow this order strictly:
 | Picking the right component | `/bb-mango-components` |
 | Full props + JSX examples for a specific component | `/bb-mango-<name>` (e.g. `/bb-mango-button`) |
 | Icon names and `MangoIcon` usage | `/bb-icons` |
+| Illustration names and usage | `/bb-mango-illustrations` |
 | Layout, typography, and colour utility classes | `/bb-mango-utility-classes` |
+| Design tokens, CSS variables, borders, colours, typography | `/bb-mango-styling` |
+| Form component best practices (labelling, validation, status) | `/bb-mango-forms` |
 
 ---
 

package/.claude-dist/skills/bb-icons/SKILL.md

@@ -123,6 +123,7 @@ Icons render with `fill="currentColor"` — they inherit the text colour of thei
 - `brand-onboarding` — Onboarding product mark
 - `brand-analytics` — Analytics product mark
 - `brand-talent` — Talent product mark
+- `brand-lms` — Learning Management System product mark
 
 ---
 

package/.claude-dist/skills/bb-mango-combobox/SKILL.md

@@ -35,6 +35,7 @@ Source: `src/MangoCombobox/MangoCombobox.tsx`
 | `loading` | `boolean` | — | Show loading state in dropdown |
 | `listPlaceholder` | `string` | — | Text shown when no items match |
 | `searchCharacterMinimum` | `string` | — | Min characters before search triggers |
+| `trigger` | `ReactNode` | — | Custom trigger element. Replaces the default button, label, clear button, and chevron. `label` slot is suppressed when set. |
 | `name` | `string` | `id` | HTML name attribute |
 | `testId` | `string` | — | Test identifier |
 
@@ -147,9 +148,28 @@ import { MangoCombobox, MangoComboboxChip } from '@intellihr/blueberry'
 />
 ```
 
+### Custom trigger
+
+```tsx
+// Replace the default button with any element (e.g. a MangoButton or MangoIconButton)
+<MangoCombobox
+  id="filter"
+  value={value}
+  onChange={(e) => setValue(e.target.value as string)}
+  trigger={<MangoButton variant="secondary" icon="filter">Filter</MangoButton>}
+  items={filterOptions}
+/>
+```
+
+When `trigger` is provided:
+- The default field button, label, clear button, and chevron are all replaced
+- The `label` prop/slot is suppressed — do not pass `label` alongside `trigger`
+- ARIA is applied automatically by mango-ui
+
 ### Notes
 
 - `items` is an array prop — do not use children for options
 - `onChange` receives `MgoInputEvent` — read `event.target.value` for the selected value (string or string[])
 - `valueDisplay` is used to customise multi-select chip rendering; use `MangoComboboxChip` for person-like chips
 - Always hoists the dropdown to avoid z-index clipping
+- `trigger` replaces the entire default trigger — do not combine with `label`

package/.claude-dist/skills/bb-mango-components/SKILL.md

@@ -80,6 +80,7 @@ Use this skill to pick the right component. Then load the component-specific ski
 | `MangoWizardModal` | Multi-step wizard modal. `currentStep` is 1-indexed. |
 | `MangoDropdownMenu` | Trigger + action menu. `trigger` + `items[]` required. |
 | `MangoTooltip` | Hover tooltip. `trigger` + `content` required. |
+| `MangoPopover` | Click-triggered floating panel. `trigger` + `children` required. Optional `header`/`footer`. `ref` gives imperative `show()`/`hide()`. |
 
 ---
 
@@ -94,7 +95,9 @@ Use this skill to pick the right component. Then load the component-specific ski
 | `MangoProgressRing` | Circular progress. `value` (0–100) required. |
 | `MangoEmptyState` | Empty state placeholder. `title` required. |
 | `MangoBadge` | Notification badge. Passed as `badge` prop to Button/IconButton/Navigation items. |
-| `MangoTag` | Status tag. 12 tone options. |
+| `MangoTag` | Status tag. 14 tone options. Optional `icon` prop. |
+| `MangoPipeline` | Filter bar with stage/status counts. `items[]` + `onChange` required. `variant`: tile or compact. |
+| `MangoCopyButton` | Clipboard icon button. `value` required. Auto success/error feedback. |
 | `MangoSplash` | Full-screen loading spinner. Requires parent with defined height. |
 
 ---
@@ -117,7 +120,8 @@ Every component exports a type alias: `TMangoButton`, `TMangoTextField`, etc.
 Import: `import type { TMangoButton } from '@intellihr/blueberry'`
 
 Exceptions:
-- `MangoBadge`, `MangoCallout`, `MangoHeading`, `MangoTag`, `MangoToast`, `MangoToastStack`, `MangoTurnBack` — no exported type alias
+- `MangoBadge`, `MangoCallout`, `MangoHeading`, `MangoToast`, `MangoToastStack`, `MangoTurnBack` — no exported type alias
 - `MangoTooltip` — exports `IMangoTooltip` (not `TMangoTooltip`)
 - `MangoWizardModal` — exports 4 types: `TMangoWizardModal`, `TMangoWizardModalStepItem`, `TMangoWizardModalStep`, `TMangoWizardModalStepLabel`
 - `MangoAppShell` — exports `TMangoAppShell` + `TMangoAppShellRef`
+- `MangoPopover` — exports `TMangoPopover` + `TMangoPopoverRef`

package/.claude-dist/skills/bb-mango-copy-button/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: bb-mango-copy-button
+description: MangoCopyButton React component — clipboard button with automatic success/error feedback states and tooltip
+allowed-tools: Read, Glob, Grep
+---
+
+## `MangoCopyButton`
+
+Import: `import { MangoCopyButton } from '@intellihr/blueberry'`
+Source: `src/MangoCopyButton/MangoCopyButton.tsx`
+
+### Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `value` | `string` | — | Text to copy to clipboard |
+| `from` | `string` | — | ID of another DOM element to copy from. Supports `id` (text content), `id.property`, or `id[attribute]` |
+| `disabled` | `boolean` | — | Disabled state |
+| `copyLabel` | `string` | — | Tooltip label in default state (default: i18n "Copy") |
+| `successLabel` | `string` | — | Tooltip label after successful copy (default: i18n "Copied") |
+| `errorLabel` | `string` | — | Tooltip label on copy failure (default: i18n "Error") |
+| `tooltipPlacement` | `'top' \| 'right' \| 'bottom' \| 'left'` | `'top'` | Tooltip position |
+| `onCopy` | `(event: MgoCopyEvent) => void` | — | Called when text is successfully copied |
+| `onError` | `(event: MgoErrorEvent) => void` | — | Called when copy fails |
+| `testId` | `string` | — | Test identifier |
+
+### Exported type
+
+```ts
+import type { TMangoCopyButton } from '@intellihr/blueberry'
+```
+
+### JSX Examples
+
+```tsx
+import { MangoCopyButton } from '@intellihr/blueberry'
+
+// Basic
+<MangoCopyButton value="Text to copy" />
+
+// With custom labels
+<MangoCopyButton
+  value="user@example.com"
+  copyLabel="Copy email"
+  successLabel="Copied!"
+  errorLabel="Failed to copy"
+/>
+
+// Copy from another DOM element by ID (text content)
+<code id="install-cmd">npm install @intellihr/blueberry</code>
+<MangoCopyButton from="install-cmd" copyLabel="Copy command" />
+
+// Copy a property of another element
+<MangoCopyButton from="my-input.value" copyLabel="Copy" />
+
+// With copy callback
+<MangoCopyButton
+  value={apiKey}
+  copyLabel="Copy API key"
+  onCopy={(e) => console.log('Copied:', e.detail.value)}
+/>
+```
+
+### Notes
+
+- Renders as an icon button — no label text is shown; use `copyLabel` for the tooltip
+- Either `value` or `from` must be provided
+- `from` supports: plain `id` (copies text content), `id.property` (property access), `id[attribute]` (attribute access)
+- `onCopy` event detail contains `{ value: string }` — the copied text
+- Feedback state (success/error icon) reverts automatically after a short time

package/.claude-dist/skills/bb-mango-forms/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: bb-mango-forms
+description: Best practices for Blueberry Mango form components — labelling, validation status, help text, required/disabled, form methods. Read this before implementing any form field.
+allowed-tools: Read, Glob, Grep
+---
+
+## Blueberry Mango Form Best Practices
+
+> **Derived from `mango-forms`** — when that skill is updated, sync the relevant parts here, replacing web component/Angular patterns with React/Blueberry equivalents.
+
+Applies to: `MangoTextField`, `MangoTextarea`, `MangoDateField`, `MangoCombobox`, `MangoCheckbox`, `MangoRadioGroup`
+
+---
+
+### Labelling
+
+**Always provide a `label` prop. Never add a native `<label>` element.**
+
+Every Mango wrapper renders its own label internally. Adding a separate native `<label>` will produce a duplicate and break accessibility.
+
+```tsx
+// ❌ WRONG — do not do this
+<label htmlFor="name">Full name</label>
+<MangoTextField id="name" />
+
+// ✅ CORRECT
+<MangoTextField label="Full name" />
+```
+
+---
+
+### Validation Status
+
+All form components share the same `status` / `statusText` props.
+
+| Prop         | Type     | Values                                          | Description                                        |
+| ------------ | -------- | ----------------------------------------------- | -------------------------------------------------- |
+| `status`     | `string` | `'critical'` \| `'caution'` \| `'positive'` \| `''` | Visual validation state                        |
+| `statusText` | `string` | any                                             | Message shown below the field with a status icon   |
+
+**When to use each value:**
+
+- `critical` — validation error, field is invalid
+- `caution` — warning, field is valid but needs attention
+- `positive` — explicit confirmation the value is valid
+- `''` (empty, default) — neutral, no validation state shown
+
+**Always pair `status` with `statusText`** so the user knows what to fix:
+
+```tsx
+// ❌ WRONG — status with no explanation
+<MangoTextField label="Email" status="critical" />
+
+// ✅ CORRECT
+<MangoTextField
+  label="Email"
+  status="critical"
+  statusText="Enter a valid email address."
+/>
+```
+
+---
+
+### Help Text
+
+Use `helpText` for persistent instructional text shown below the field. It is always visible, unlike `statusText` which only shows when a status is set.
+
+```tsx
+<MangoTextField
+  label="Username"
+  helpText="Must be 3–20 characters. Letters, numbers, and underscores only."
+/>
+```
+
+Do not use `helpText` for validation errors — use `status` + `statusText` for that.
+
+---
+
+### Event Handling
+
+Form components expose React-style event props. For components that wrap `mgo-*` web components, events are prefixed with `onMgo`:
+
+```tsx
+// MangoTextField
+<MangoTextField
+  label="Name"
+  onChange={(value: string) => setName(value)}
+/>
+
+// MangoDateField
+<MangoDateField
+  label="Start date"
+  onChange={(isoValue: string) => setDate(isoValue)}
+/>
+
+// MangoCombobox
+<MangoCombobox
+  label="Status"
+  options={options}
+  onChange={(value) => setValue(value)}
+/>
+```
+
+Check each component's own skill (`/bb-mango-text-field`, `/bb-mango-date-field`, etc.) for the exact event prop signature.
+
+---
+
+### Icon Props
+
+Some form components accept `leadingIcon` / `trailingIcon` props. These always expect an **icon name string** from the Mango icon set — not a component or element.
+
+```tsx
+// ✅ CORRECT — pass an icon name string
+<MangoTextField label="Search" leadingIcon="search" />
+
+// ❌ WRONG — do not pass a component
+<MangoTextField label="Search" leadingIcon={<MangoIcon name="search" />} />
+```
+
+For valid icon names, see the `/bb-icons` skill.
+
+---
+
+### Required, Disabled, Readonly
+
+| Prop       | Behaviour                                                                    |
+| ---------- | ---------------------------------------------------------------------------- |
+| `required` | Marks the field as required (shown visually and enforced in form submission) |
+| `disabled` | Field is non-interactive and excluded from form submission                   |
+| `readonly` | Field is non-interactive but included in form submission                     |
+
+---
+
+### Form Validation Methods
+
+Mango form components implement the Constraint Validation API. Access them via a React ref:
+
+```tsx
+import { useRef } from 'react'
+import { MangoTextField } from '@intellihr/blueberry'
+
+const fieldRef = useRef<HTMLElement>(null)
+
+// After a server-side error
+fieldRef.current?.setCustomValidity('This username is already taken.')
+fieldRef.current?.reportValidity()
+
+// To clear
+fieldRef.current?.setCustomValidity('')
+```
+
+| Method                       | Description                                                    |
+| ---------------------------- | -------------------------------------------------------------- |
+| `checkValidity()`            | Returns `true` if valid, `false` if not (no UI shown)          |
+| `reportValidity()`           | Like `checkValidity()` but also shows browser validation UI    |
+| `setCustomValidity(message)` | Set a custom validation message. Pass `''` to clear.           |

package/.claude-dist/skills/bb-mango-illustrations/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: bb-mango-illustrations
+description: Illustration names and the illustration system for Blueberry React apps — finding available illustrations, complete illustration list, how illustrations work
+allowed-tools: Read, Glob, Grep
+---
+
+## Illustrations in Blueberry
+
+> **Derived from `mango-illustrations`** — when that skill is updated with new illustration names or system changes, update this skill to match.
+
+Mango UI has a built-in illustration system with full-colour SVG illustrations for common empty and error states.
+
+---
+
+### How to use illustrations
+
+There is no `MangoIllustration` React wrapper component. Illustrations surface in two ways in Blueberry:
+
+**1. Via `MangoEmptyState` — preferred for empty/no-data states**
+
+```tsx
+import { MangoEmptyState } from '@intellihr/blueberry'
+
+<MangoEmptyState
+  variant="no-data"
+  title="No results"
+  description="Try adjusting your filters."
+/>
+```
+
+**2. Via `MangoTurnBack` — for error/dead-end pages**
+
+```tsx
+import { MangoTurnBack } from '@intellihr/blueberry'
+
+<MangoTurnBack
+  variant="page-not-found"
+  title="Page not found"
+  description="The page you're looking for doesn't exist."
+  actions={[{ label: 'Go home', href: '/' }]}
+/>
+```
+
+**3. Directly via the `mgo-illustration` web component** — use only when the above wrappers don't fit
+
+```tsx
+// Blueberry loads mango-ui, so web components can be used directly
+<mgo-illustration name="no-data" label="No data available" />
+
+// Decorative (no label, aria-hidden applied automatically)
+<mgo-illustration name="form-complete" />
+```
+
+Never set a `library` attribute — the default library is used automatically.
+
+---
+
+### All available illustration names
+
+#### Error States
+
+- `page-not-found` — 404 / page not found
+- `generic-error` — General or unexpected application error
+- `connection-error` — Network or connection failure
+- `identity-error` — Authentication or identity problem
+- `permission-error` — Authorisation / access denied
+
+#### Empty & Completion States
+
+- `no-data` — No results or empty data set
+- `form-complete` — Form or task successfully completed
+
+#### Internal / Component Use
+
+- `turnback-background` — Background graphic used internally by `MangoTurnBack`. Do not use as a general illustration.
+
+---
+
+### How the illustration system works
+
+1. You provide a `name` (e.g. `"no-data"`)
+2. The default library resolver returns a data URL: `data:image/svg+xml,${encodeURIComponent(svg)}`
+3. The illustration is safely embedded — no network requests, all bundled
+
+**Important differences from icons:**
+
+- Illustrations are fixed-colour SVGs — they do **not** inherit text colour via `currentColor`
+- All built-in illustrations are 256×256px except `turnback-background` (448×94px)

package/.claude-dist/skills/bb-mango-navigation/SKILL.md

@@ -84,7 +84,7 @@ import type { TMangoNavigation } from '@intellihr/blueberry'
 productSwitcher={{
   currentProduct: {
     label: 'Workforce Management',
-    type: 'workforceManagement'  // 'workforceManagement'|'coreHr'|'financialWellbeing'|'payroll'|'analytics'|'talent'|'benefits'|'generic'
+    type: 'workforceManagement'  // 'workforceManagement'|'coreHr'|'financialWellbeing'|'payroll'|'analytics'|'talent'|'lms'|'benefits'|'generic'
   },
   apps: [
     { href: 'https://corehr.example.com', label: 'Core HR', type: 'coreHr' },

package/.claude-dist/skills/bb-mango-pipeline/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: bb-mango-pipeline
+description: MangoPipeline React component — filter bar showing stage/status counts; mutually exclusive selection; tile and compact variants
+allowed-tools: Read, Glob, Grep
+---
+
+## `MangoPipeline`
+
+Import: `import { MangoPipeline } from '@intellihr/blueberry'`
+Source: `src/MangoPipeline/MangoPipeline.tsx`
+
+### Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `items` | `IMangoPipelineItem[]` | **required** | Pipeline stage items |
+| `value` | `string` | — | Currently selected value. Empty string = All (no filter). |
+| `onChange` | `(event: MgoPipelineChangeEvent) => void` | — | Called when selection changes |
+| `variant` | `'tile' \| 'compact'` | `'tile'` | `tile`: large count above label. `compact`: label with inline count badge. |
+| `totalLabel` | `string` | `'All'` | Label for the auto-generated All/Total item |
+| `totalCount` | `number` | — | Count shown on the Total item (omit to hide count) |
+| `fill` | `boolean` | — | Stretch items to fill the full container width equally |
+| `testId` | `string` | — | Test identifier |
+
+### `IMangoPipelineItem`
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `value` | `string` | **required** | Value emitted when this item is selected |
+| `label` | `string` | **required** | Stage label text |
+| `count` | `number` | — | Number of items in this stage (omit to hide count) |
+| `tone` | `'blue' \| 'purple' \| 'red' \| 'green' \| 'yellow' \| 'pink' \| 'teal' \| 'grey'` | — | Colour tone for the active state |
+| `disabled` | `boolean` | — | Prevents selection |
+
+### Exported type
+
+```ts
+import type { TMangoPipeline } from '@intellihr/blueberry'
+```
+
+### Event type
+
+```typescript
+import type { MgoPipelineChangeEvent } from '@humanforce/mango-ui'
+
+// Read selected value from onChange
+onChange={(event: MgoPipelineChangeEvent) => {
+  const selected = event.detail.value // string — empty string means All
+}}
+```
+
+### JSX Examples
+
+```tsx
+import { MangoPipeline } from '@intellihr/blueberry'
+
+const [filter, setFilter] = React.useState('')
+
+<MangoPipeline
+  value={filter}
+  onChange={(e) => setFilter(e.detail.value)}
+  totalLabel="All employees"
+  totalCount={24}
+  items={[
+    { value: 'active', label: 'Active', count: 12, tone: 'green' },
+    { value: 'on-leave', label: 'On leave', count: 4, tone: 'yellow' },
+    { value: 'terminated', label: 'Terminated', count: 8, tone: 'red' },
+  ]}
+/>
+
+// Compact variant
+<MangoPipeline
+  variant="compact"
+  value={filter}
+  onChange={(e) => setFilter(e.detail.value)}
+  items={[
+    { value: 'active', label: 'Active', count: 12, tone: 'green' },
+    { value: 'pending', label: 'Pending', count: 4, tone: 'yellow' },
+  ]}
+/>
+```
+
+### Notes
+
+- `value` empty string means the All/Total item is selected (no filter active)
+- The All/Total item is auto-generated by mango-ui — do not add it to `items`
+- `active` state on items is managed by `mgo-pipeline` based on `value` — do not set it manually
+- Read the new value from `event.detail.value` (not `event.target.value`)
+- Setting `value` programmatically syncs active state but does NOT fire `onChange`
+- Clicking an already-active non-Total item deselects it and returns to All
+- `tone` controls the colour of an item's active/selected state only
+- `tile` variant is designed around displaying a large count — omitting `count` leaves an empty gap. Use `compact` when counts are not available

package/.claude-dist/skills/bb-mango-popover/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: bb-mango-popover
+description: MangoPopover React component — click-triggered floating panel with trigger, body, optional header/footer, and imperative show/hide via ref
+allowed-tools: Read, Glob, Grep
+---
+
+## `MangoPopover`
+
+Import: `import { MangoPopover } from '@intellihr/blueberry'`
+Source: `src/MangoPopover/MangoPopover.tsx`
+
+### Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `trigger` | `ReactNode` | **required** | Element that opens the popover (button, icon-button, etc.) |
+| `children` | `ReactNode` | **required** | Body content of the popover |
+| `header` | `ReactNode` | — | Content rendered in the panel header |
+| `footer` | `ReactNode` | — | Content rendered in the panel footer |
+| `open` | `boolean` | — | Controlled open state |
+| `placement` | `TPopoverPlacement` | `'bottom-start'` | Preferred placement of the panel |
+| `disabled` | `boolean` | — | Prevents the popover from opening |
+| `distance` | `number` | `6` | Distance in px from trigger to panel |
+| `skidding` | `number` | `0` | Offset in px along the trigger axis |
+| `hoist` | `boolean` | `true` | Use fixed positioning to prevent clipping |
+| `onShow` | `(event: Event) => void` | — | Called when the panel opens |
+| `onAfterShow` | `(event: Event) => void` | — | Called after open animation completes |
+| `onHide` | `(event: Event) => void` | — | Called when the panel closes |
+| `onAfterHide` | `(event: Event) => void` | — | Called after close animation completes |
+| `testId` | `string` | — | Test identifier |
+
+### Placement values
+
+`'top' | 'top-start' | 'top-end' | 'bottom' | 'bottom-start' | 'bottom-end' | 'right' | 'right-start' | 'right-end' | 'left' | 'left-start' | 'left-end'`
+
+### Exported types
+
+```ts
+import type { TMangoPopover, TMangoPopoverRef } from '@intellihr/blueberry'
+```
+
+### Imperative ref
+
+```tsx
+const popoverRef = React.useRef<TMangoPopoverRef>(null)
+
+<MangoPopover ref={popoverRef} trigger={...}>...</MangoPopover>
+
+// Methods
+popoverRef.current?.show()
+popoverRef.current?.hide()
+popoverRef.current?.reposition()
+```
+
+### JSX Examples
+
+```tsx
+import { MangoPopover, MangoButton, MangoIconButton } from '@intellihr/blueberry'
+
+// Basic
+<MangoPopover
+  trigger={<MangoButton variant="secondary">Open</MangoButton>}
+>
+  <p className="mgo-text-m">Popover content goes here.</p>
+</MangoPopover>
+
+// With header and footer
+<MangoPopover
+  trigger={<MangoIconButton icon="settings" label="Settings" />}
+  header={<span className="mgo-text-m mgo-weight-strong">Settings</span>}
+  footer={
+    <div className="mgo-cluster mgo-justify-end">
+      <MangoButton variant="secondary" size="small">Cancel</MangoButton>
+      <MangoButton size="small">Save</MangoButton>
+    </div>
+  }
+>
+  <div className="mgo-stack">
+    <p className="mgo-text-s">Adjust your preferences.</p>
+  </div>
+</MangoPopover>
+
+// Custom placement
+<MangoPopover placement="top-start" trigger={<MangoButton>Open</MangoButton>}>
+  Content above.
+</MangoPopover>
+```
+
+### CSS custom properties
+
+| Property | Default | Description |
+|---|---|---|
+| `--min-width` | `14rem` | Minimum width of the panel |
+| `--max-width` | `25rem` | Maximum width of the panel |
+
+### Notes
+
+- `trigger` is required and must be a clickable element (button, icon-button) for accessibility
+- The popover closes when the user clicks outside or presses Escape
+- `hoist` defaults to `true` — use `hoist={false}` to opt out of fixed positioning
+- For action menus use `MangoDropdownMenu` instead — `MangoPopover` is for richer non-menu content (info panels, filter widgets, notifications)
+- Prefer MangoPopover over MangoTooltip when content is interactive or requires persistent display