---

## CompositionBar
Stacked bar with legend that breaks an aggregate value down into
its components. Suited for budget splits, pool composition, resource
allocation, token vesting — anywhere `pool = a + b + c` should be visible
at a glance.

Small segments (< 2% of the total width) are kept minimally visible;
hovering/focusing the bar or the legend highlights the counterpart in
sync. Tooltip content is fully overridable via the `tooltip` snippet.

**Import:** `import { CompositionBar } from '@urbicon-ui/blocks';`

### Examples
```svelte
<CompositionBar
  items={[
    { label: 'Gas',         value: 220609, intent: 'primary' },
    { label: 'Power',       value: 112731, intent: 'secondary' },
    { label: 'Maintenance', value:  36102, intent: 'success' }
  ]}
  formatValue={(v) => formatCurrency(v)}
  size="lg"
  legendPlacement="right"
  showTotal
/>
```

### Variants
- size: lg, md, sm (default: md)
- legendPlacement: bottom, left, none, right, top (default: bottom)
- orientation: horizontal, vertical (default: horizontal)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| items | `CompositionItem[]` | yes |  | Composition shares in the order they should appear in the bar. |
| ...CompositionBarVariants | `VariantProps` | no |  | Styling variants from CompositionBarVariants |
| ...HTMLAttributes<HTMLDivElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children') |
| class | `string` | no |  | Extra classes merged onto the wrapper. |
| formatPercent | `(percent: number) => string` | no |  | Format function for percentages. Default: 1 fraction digit, formatted with the active locale (e.g. `12.3 %`). |
| formatValue | `(value: number) => string` | no |  | Format function for values (tooltip, legend, total). |
| intent | `CompositionBarIntent` | no | 'primary' | Default intent for items without their own `intent`/`color`. |
| legendItem | `Snippet<[item: CompositionItem, percent: number]>` | no |  | Custom rendering of a legend entry. Receives the item and its percentage. Fully replaces the default rendering (dot + label + value/percent). |
| minSegmentPercent | `number` | no | 1.5 | Minimum segment width in percent. Values below it are raised to this width so they stay visible in the bar (nothing gets swallowed). Larger segments are shrunk proportionally so the sum still adds up to 100%. |
| mint | `MintProp` | no | 'none' | Micro-interaction preset. |
| onItemSelect | `(item: CompositionItem, index: number) => void` | no |  | Selection callback fired when a bar segment or legend entry is clicked. Receives the item and its index. Makes the bar interactive (cursor + click handler). |
| preset | `string` | no |  | Preset name (registered via `<BlocksProvider presets={{ CompositionBar: {...} }}>`). |
| showLegend | `boolean` | no | true | ShowLegend property for the CompositionBar component |
| showPercentages | `boolean` | no | true | Show percentages in legend and tooltip. |
| showTotal | `boolean` | no | false | Render the total value after the legend. |
| showValues | `boolean` | no | false | Render the value directly inside the bar segment (in addition to the legend). Narrow segments are skipped automatically to prevent overflow — only segments with sufficient width (≥ 8% or ~40 px) show their value. Useful for print, PDF attachments, or dense dashboards where hover tooltips are not enough. |
| slotClasses | `Partial<Record<CompositionBarSlots, string>>` | no |  | Per-slot class overrides. |
| tooltip | `Snippet<[item: CompositionItem, percent: number]>` | no |  | Custom tooltip content. Replaces the default layout (label, value, percent). |
| total | `number` | no |  | Optional fixed total value. Default: Σ items.value. If the explicit total exceeds the sum, the remaining area is rendered neutrally ("unaccounted share"). If it is below the sum, segments are scaled to 100% and a console warning is emitted. |
| totalLabel | `string` | no |  | Label rendered before the total. Defaults to the localized "Total" label from the blocks i18n bundle. |
| unstyled | `boolean` | no |  | Remove all default classes; only the layout structure remains. |
| size | `'lg' | 'md' | 'sm'` | no | md | Controls the dimensions, padding, and text size of the CompositionBar. Affects the component's physical footprint. Available options: lg, md, sm. |
| legendPlacement | `'bottom' | 'left' | 'none' | 'right' | 'top'` | no | bottom | Controls the legendPlacement behavior and appearance of the CompositionBar component. Available options: bottom, left, none, and 2 more. |
| orientation | `'horizontal' | 'vertical'` | no | horizontal | Controls the orientation behavior and appearance of the CompositionBar component. Available options: horizontal, vertical. |

Inherited from:
- Omit<CompositionBarVariants, 'isHovered'> (omit-pattern)
- Omit<HTMLAttributes<HTMLDivElement>, 'children'> (omit-pattern)