---

## 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
- intent: danger, neutral, primary, secondary, success, warning
- size: lg, md, sm (default: md)
- dimmed: false, true
- fill: danger, neutral, primary, secondary, success, warning
- legendPlacement: bottom, left, 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. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| 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 small shares stay visible. Larger segments are shrunk proportionally so the total still adds up to 100%. |
| 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. Providing it makes the segments interactive (pointer cursor and click handling). |
| preset | `string` | no |  | Preset name (registered via `<BlocksProvider presets={{ CompositionBar: {...} }}>`). |
| showLegend | `boolean` | no | true | Show the legend. Position it with `legendPlacement`. |
| 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. Only segments wide enough (≥ 8% or ~40 px) show their value, so narrow ones do not overflow. Handy for print or PDF export, where there is no hover tooltip. |
| slotClasses | `Partial<Record<CompositionBarSlots, string>>` | no |  | Per-slot class overrides. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| 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: the sum of the item values. 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. |
| dimmed | `'false' | 'true'` | no |  | Controls the dimmed behavior and appearance of the CompositionBar component. Available options: false, true. |
| fill | `'danger' | 'neutral' | 'primary' | 'secondary' | 'success' | 'warning'` | no |  | Controls the fill behavior and appearance of the CompositionBar component. Available options: danger, neutral, primary, and 3 more. |
| legendPlacement | `'bottom' | 'left' | 'right' | 'top'` | no | bottom | Controls the legendPlacement behavior and appearance of the CompositionBar component. Available options: bottom, left, right, top. |
| 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)

### Types
```ts
type CompositionBarIntent = | 'primary'
  | 'secondary'
  | 'success'
  | 'warning'
  | 'danger'
  | 'neutral'
```

```ts
interface CompositionItem {
/** Stable ID for highlight synchronization and snippet identity. */
  id?: string | number;
  /** Display label in the legend and the default tooltip. */
  label: string;
  /** Numeric value, defines the segment width. */
  value: number;
  /** Overrides the default intent from the component palette. */
  intent?: CompositionBarIntent;
  /** Raw color value (CSS color), bypasses the token system. Takes precedence over `intent`. */
  color?: string;
  /** Arbitrary metadata — passed through to snippets. */
  meta?: Record<string, unknown>;
}
```

```ts
type SlotNames = keyof ReturnType<T> & string
```

```ts
type VariantProps = Omit<
  Exclude<Parameters<T>[0], undefined>,
  'class'
>
```

### Slots (slotClasses keys)
`wrapper`, `barWrapper`, `bar`, `segment`, `segmentRest`, `tooltip`, `tooltipLabel`, `tooltipDetail`, `legend`, `legendItem`, `legendDot`, `legendLabel`, `legendValue`, `total`, `totalLabel`