<!-- source-hash: 07ba5865678ee01e8867762d1e641327 -->
A reusable React selector component that renders options as push-button cards with checkbox indicators, supporting single/multi-select, grouped sections, loading skeletons, and error states.

## Key Components

| Export | Type | Description |
|--------|------|-------------|
| `PushButtonSelector` | Component | Main selector rendered as interactive card list |
| `SelectableOption` | Interface | Shape of each selectable item (id, name, icon, section, etc.) |
| `SectionDefinition` | Interface | Defines a named group to bucket options under |
| `PushButtonSelectorSkeleton` | Internal | Animated skeleton shown during `isLoading` |
| `PushButtonSelectorError` | Internal | Error panel using ODS error tokens |

## Key Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `options` | `SelectableOption[]` | — | All available options |
| `selectedIds` | `string[]` | — | Controlled selected IDs |
| `onSelectionChange` | `(ids: string[]) => void` | — | Fires on toggle |
| `multiSelect` | `boolean` | `true` | Allow multiple selections |
| `sections` | `SectionDefinition[]` | — | Groups options under labeled headers |
| `selectionSummary` | `boolean` | `false` | Shows badge summary of selected items |
| `optional` | `boolean` | `false` | Suppresses empty-state warning |
| `isLoading` | `boolean` | `false` | Renders skeleton UI |
| `error` | `string \| null` | `null` | Renders error panel |

## Usage Example

```typescript
import { PushButtonSelector, SelectableOption, SectionDefinition } from './push-button-selector';

const platforms: SelectableOption[] = [
  { id: 'uuid-1', name: 'connectwise', displayName: 'ConnectWise', description: 'PSA platform', section: 'psa' },
  { id: 'uuid-2', name: 'halo',        displayName: 'HaloPSA',     description: 'PSA platform', section: 'psa' },
  { id: 'uuid-3', name: 'ninja',       displayName: 'NinjaRMM',    description: 'RMM platform', section: 'rmm' },
];

const sections: SectionDefinition[] = [
  { id: 'psa', label: 'PSA Tools' },
  { id: 'rmm', label: 'RMM Tools' },
];

function IntegrationPicker() {
  const [selected, setSelected] = React.useState<string[]>([]);

  return (
    <PushButtonSelector
      options={platforms}
      selectedIds={selected}
      onSelectionChange={setSelected}
      sections={sections}
      title="Select Integrations"
      helpText="Choose the platforms to connect."
      selectionSummary
      multiSelect
    />
  );
}
```

> **Note:** Invalid `selectedIds` (IDs not present in `options`) are silently filtered once `options` has loaded. A `console.warn` is emitted in `development` mode to aid debugging.