# Plasma Design System — Full LLM Documentation

Plasma is Coveo's design system built on top of Mantine. It provides a curated set of React components, a custom Mantine theme, design tokens, and icons for use in Coveo Cloud products.

## Quick Start

```bash
pnpm add @coveord/plasma-mantine @mantine/core @mantine/hooks react react-dom
```

```tsx
import '@mantine/core/styles.css';
import '@mantine/notifications/styles.css';
import {Plasmantine} from '@coveord/plasma-mantine/plasmantine';

function App() {
    return <Plasmantine>{/* your app */}</Plasmantine>;
}
```

## Components

### Accordion

Collapsible content panels with an additional disabled control variant.

#### Props

_No additional props beyond the Mantine base component._

#### Sub-components

Plasma provides pre-configured sub-components as convenience wrappers. You SHOULD use these over setting props manually.

- `Accordion.Control`
- `Accordion.ControlDisabled`
- `Accordion.Panel`
- `Accordion.Item`

`Accordion.ControlDisabled` renders a control with no chevron and disabled pointer events. You SHOULD use it for accordion items that are always expanded and cannot be collapsed by the user.

#### Usage

```tsx
import {Accordion} from '@coveord/plasma-mantine';

function Example() {
    return (
        <Accordion defaultValue="details">
            <Accordion.Item value="details">
                <Accordion.Control>Project details</Accordion.Control>
                <Accordion.Panel>Configure the project name, description, and visibility settings.</Accordion.Panel>
            </Accordion.Item>

            <Accordion.Item value="readonly">
                <Accordion.ControlDisabled>Always visible section</Accordion.ControlDisabled>
                <Accordion.Panel>This content is always visible and cannot be collapsed.</Accordion.Panel>
            </Accordion.Item>
        </Accordion>
    );
}
```

────────────────────────────────────────────────────────────────────────────────

### ActionIcon

Icon-only button that can trigger actions and can show a disabled-state tooltip.

#### Props

> Extends: `MantineActionIconProps`. Only Plasma-specific props are listed below; refer to Mantine documentation for inherited props.

**`onClick`** `ClickHandler<HTMLButtonElement>` · optional · default: `undefined` — Handler executed on click. Supports standard, async, and parameterless handlers. Async handlers MAY be provided; the button shows a loading state while the promise resolves.
**`disabledTooltip`** `string` · optional · default: `undefined` — Tooltip message displayed when `disabled` is `true`.
**`disabledTooltipProps`** `Omit<TooltipProps, 'disabled' | 'label' | 'children'>` · optional · default: `undefined` — Additional tooltip props that MAY be set on the disabled button tooltip.

#### Sub-components

Plasma provides pre-configured sub-components as convenience wrappers. You SHOULD use these over setting props manually.

- `ActionIcon.Group`
- `ActionIcon.Primary`
- `ActionIcon.Secondary`
- `ActionIcon.Tertiary`
- `ActionIcon.Quaternary`
- `ActionIcon.DestructivePrimary`
- `ActionIcon.DestructiveSecondary`
- `ActionIcon.DestructiveTertiary`
- `ActionIcon.DestructiveQuaternary`

#### Usage

```tsx
import {ActionIcon} from '@coveord/plasma-mantine';
import {IconTrash} from '@coveord/plasma-react-icons';

const removeItem = () => {};
const deleteItem = async () => {};

// Common pattern: use a sub-component for the intended emphasis.
<ActionIcon.Quaternary onClick={removeItem}>
    <IconTrash aria-label="Remove" />
</ActionIcon.Quaternary>;

// Async handlers automatically show a loading state while pending.
<ActionIcon.DestructivePrimary onClick={deleteItem}>
    <IconTrash aria-label="Delete" />
</ActionIcon.DestructivePrimary>;

// Disabled actions MAY explain why they are unavailable.
<ActionIcon.Primary disabled disabledTooltip="You do not have permission to remove this item">
    <IconTrash aria-label="Remove" />
</ActionIcon.Primary>;
```

────────────────────────────────────────────────────────────────────────────────

### Alert

Alert callout for contextual information, advice, warnings, critical errors, and success states.

#### Props

_No additional props beyond the Mantine base component._

#### Sub-components

Plasma provides pre-configured sub-components as convenience wrappers. You SHOULD use these over setting props manually.

- `Alert.Information`
- `Alert.Advice`
- `Alert.Warning`
- `Alert.Critical`
- `Alert.Success`

#### Usage

```tsx
import {Alert} from '@coveord/plasma-mantine';

<Alert.Information title="Note">This is an informational message.</Alert.Information>
<Alert.Warning title="Warning">Proceed with caution.</Alert.Warning>
<Alert.Critical title="Error">Something went wrong.</Alert.Critical>
```

────────────────────────────────────────────────────────────────────────────────

### AppShell

Application layout shell with a scrollable main content area.

#### Props

_No additional props beyond the Mantine base component._

#### Sub-components

Plasma provides pre-configured sub-components as convenience wrappers. You SHOULD use these over setting props manually.

- `AppShell.Header`
- `AppShell.Navbar`
- `AppShell.Main`
- `AppShell.Aside`
- `AppShell.Footer`
- `AppShell.Section`

`AppShell.Main` wraps its children in a scrollable container that fills the available height. This ensures the main content area scrolls independently from the rest of the shell.

#### Usage

```tsx
import {AppShell} from '@coveord/plasma-mantine';

function Example() {
    return (
        <AppShell header={{height: 60}} navbar={{width: 250, breakpoint: 'sm'}}>
            <AppShell.Header>Header</AppShell.Header>
            <AppShell.Navbar>Navigation</AppShell.Navbar>
            <AppShell.Main>Main content scrolls independently within this area.</AppShell.Main>
        </AppShell>
    );
}
```

────────────────────────────────────────────────────────────────────────────────

### Badge

Status label that can display short text, counts, or metadata tags.

#### Props

> Extends: `BadgeProps` (sub-components use `SemanticBadgeProps`, a restricted subset). Only Plasma-specific props are listed below; inherited props MUST be referenced in Mantine documentation.

**`size`** `'small' | 'large'` · optional · default: `'small'` — Controls the badge height and text size.
**`on`** `'light' | 'dark'` · optional · default: current colour scheme — Forces the light or dark colour variant.

#### Sub-components

Plasma provides pre-configured sub-components as convenience wrappers. You SHOULD use these over setting props manually.

- `Badge.Primary`
- `Badge.Secondary`
- `Badge.Success`
- `Badge.Warning`
- `Badge.Critical`
- `Badge.Disabled`

#### Usage

```tsx
import {Badge} from '@coveord/plasma-mantine';

<Badge.Primary>Active</Badge.Primary>
<Badge.Success>Enabled</Badge.Success>
<Badge.Critical>Error</Badge.Critical>
```

────────────────────────────────────────────────────────────────────────────────

### BlankSlate

Empty state container for views with no content to display.

#### Props

**`withBorder`** `boolean` · optional · default: `true` — Renders a border when this prop is `true` and omits it when this prop is `false`.

#### Usage

The most common use case is rendering a table empty state, often with an action to clear filters.

```tsx
import {BlankSlate, Button, Table, Title} from '@coveord/plasma-mantine';

const NoData = ({clearFilters}: {clearFilters: () => void}) => (
    <BlankSlate>
        <Title order={4}>No data found for those filters</Title>
        <Button.Tertiary onClick={clearFilters}>Clear filters</Button.Tertiary>
    </BlankSlate>
);

const Example = () => (
    <Table.NoData>
        <NoData clearFilters={() => {}} />
    </Table.NoData>
);
```

You can also use `BlankSlate` for simpler empty states.

```tsx
import {BlankSlate, Title} from '@coveord/plasma-mantine';

const EmptyState = () => (
    <BlankSlate>
        <Title order={4}>No data</Title>
    </BlankSlate>
);
```

If the surrounding layout already has its own border, disable the `BlankSlate` border.

```tsx
import {BlankSlate, Title} from '@coveord/plasma-mantine';

const EmptyState = () => (
    <BlankSlate withBorder={false}>
        <Title order={4}>Empty state</Title>
        This view has no content yet.
    </BlankSlate>
);
```

────────────────────────────────────────────────────────────────────────────────

### BrowserPreview

Renders a simulated browser chrome frame around preview content.

#### Props

> Extends: `StackProps`. Only Plasma-specific props are listed below; refer to Mantine documentation for inherited props.

**`headerTooltip`** `string` · optional · default: `undefined` — Text displayed in a tooltip in the header.
**`title`** `string` · optional · default: `undefined` — Custom title displayed at the center of the header.

#### Usage

```tsx
import {useState} from 'react';
import {BrowserPreview, Flex, Pagination, Stack, Text} from '@coveord/plasma-mantine';

const products = [
    {name: 'Wireless Mouse', department: 'Accessories', price: '$29'},
    {name: 'Mechanical Keyboard', department: 'Accessories', price: '$99'},
    {name: 'USB-C Dock', department: 'Peripherals', price: '$149'},
    {name: 'Noise-Cancelling Headphones', department: 'Audio', price: '$199'},
    {name: '4K Monitor', department: 'Displays', price: '$399'},
    {name: 'Laptop Stand', department: 'Workspace', price: '$59'},
];

const pageSize = 3;

export function Example() {
    const [page, setPage] = useState(1);
    const total = Math.ceil(products.length / pageSize);
    const currentPageProducts = products.slice((page - 1) * pageSize, page * pageSize);

    return (
        <BrowserPreview title="Product catalog" headerTooltip="Preview the content exactly as users will see it.">
            <Stack flex={1}>
                <Stack gap="xl" pb="sm">
                    {currentPageProducts.map((product) => (
                        <Stack key={product.name} gap={0}>
                            <Text>{product.name}</Text>
                            <Text size="xs" c="dimmed">
                                {product.department} • {product.price}
                            </Text>
                        </Stack>
                    ))}
                </Stack>

                <Flex justify="center" mt="auto">
                    <Pagination value={page} total={total} onChange={setPage} />
                </Flex>
            </Stack>
        </BrowserPreview>
    );
}
```

────────────────────────────────────────────────────────────────────────────────

### Button

Action button that triggers tasks and provides async loading and disabled-tooltip feedback.

#### Props

> Extends: `ButtonProps`, `ButtonWithDisabledTooltipProps`. Only Plasma-specific props are listed below; refer to Mantine documentation for inherited props.

**`onClick`** `ClickHandler<HTMLButtonElement>` · optional · default: `undefined` — Handler executed on click. Async handlers MAY be used; the button shows a loading state while the promise resolves.
**`disabledTooltip`** `string` · optional · default: `undefined` — The tooltip message displayed when the button is disabled.
**`disabled`** `boolean` · optional · default: `undefined` — Indicates whether the button underneath the tooltip is disabled.
**`disabledTooltipProps`** `Omit<TooltipProps, 'disabled' | 'label' | 'children'>` · optional · default: `undefined` — Additional tooltip props MAY be set on the disabled button tooltip.
**`fullWidth`** `boolean` · optional · default: `undefined` — When provided, sets the button width to 100% of the parent element.

#### Sub-components

Plasma provides pre-configured sub-components as convenience wrappers. You SHOULD use these over setting props manually.

- `Button.Group`
- `Button.Primary`
- `Button.Secondary`
- `Button.Tertiary`
- `Button.Quaternary`
- `Button.DestructivePrimary`
- `Button.DestructiveSecondary`
- `Button.DestructiveTertiary`
- `Button.DestructiveQuaternary`

#### Usage

```tsx
import {Button} from '@coveord/plasma-mantine';

function Example() {
    return (
        <Button.Group>
            <Button.Secondary>Cancel</Button.Secondary>
            <Button.Primary>Save</Button.Primary>
        </Button.Group>
    );
}

async function handlePublish() {
    await new Promise((resolve) => setTimeout(resolve, 1000));
}

function AsyncExample() {
    return <Button.Primary onClick={handlePublish}>Publish</Button.Primary>;
}

function DisabledExample() {
    return (
        <Button.Primary disabled disabledTooltip="You need edit permission to publish">
            Publish
        </Button.Primary>
    );
}
```

- Use sub-components (`Button.Primary`, `Button.Secondary`, etc.) for semantic variants instead of passing `variant` manually.
- Async `onClick` handlers automatically show a loading state until the promise settles.
- Pair `disabled` with `disabledTooltip` to explain why an action is unavailable.

────────────────────────────────────────────────────────────────────────────────

### ChildForm

Expandable nested sub-form within a parent form context.

#### Props

> Extends: `CollapseProps`, `StylesApiProps`. Only Plasma-specific props are listed below; refer to Mantine documentation for inherited props.

**`title`** `string` · optional · default: `undefined` — MAY define the title of the child form.
**`description`** `ReactNode` · optional · default: `undefined` — MAY define the description of the child form.

#### Usage

```tsx
import {Checkbox, ChildForm, Stack, TextInput} from '@coveord/plasma-mantine';
import {useState} from 'react';

function Example() {
    const [hasSecondaryContact, setHasSecondaryContact] = useState(false);

    return (
        <Stack>
            <Checkbox
                label="Add a secondary contact"
                checked={hasSecondaryContact}
                onChange={(event) => setHasSecondaryContact(event.currentTarget.checked)}
            />
            <ChildForm
                in={hasSecondaryContact}
                title="Secondary contact"
                description="Collect backup contact details only when they are needed."
            >
                <TextInput label="Full name" placeholder="Taylor Smith" />
                <TextInput label="Email" placeholder="taylor@example.com" />
            </ChildForm>
        </Stack>
    );
}
```

`ChildForm` SHOULD be used to reveal optional nested fields within a larger parent form while keeping related inputs visually grouped.

────────────────────────────────────────────────────────────────────────────────

### Chip

Selectable pill-shaped control that strips the Mantine variant prop to enforce Plasma styling.

#### Props

_No additional props beyond the Mantine base component. The `variant` prop is stripped and has no effect._

#### Sub-components

Plasma provides pre-configured sub-components as convenience wrappers. You SHOULD use these over setting props manually.

- `Chip.Group`

#### Usage

```tsx
import {Chip} from '@coveord/plasma-mantine';

function Example() {
    return (
        <Chip.Group multiple defaultValue={['react']}>
            <Chip value="react">React</Chip>
            <Chip value="vue">Vue</Chip>
            <Chip value="angular">Angular</Chip>
        </Chip.Group>
    );
}
```

────────────────────────────────────────────────────────────────────────────────

### CodeEditor

Monaco-based code editor that supports syntax highlighting, validation, search, and copy actions.

#### Props

> Extends: `InputWrapperProps`, `StackProps`. Only Plasma-specific props are listed below; refer to Mantine documentation for inherited props.

**`language`** `'plaintext' | 'json' | 'markdown' | 'python' | 'xml' | (string & unknown)` · optional · default: `plaintext` — Defines the language syntax of the editor.
**`defaultValue`** `string` · optional · default: `''` — For uncontrolled input, this prop MAY provide the default value.
**`value`** `string` · optional · default: `undefined` — For controlled input, this prop MUST provide the value.
**`onChange`** `(value: string) => void` · optional · default: `undefined` — For controlled input, this callback receives the updated value.
**`onSearch`** `() => void` · optional · default: `undefined` — If provided, this callback is called whenever the search icon is clicked.
**`onCopy`** `() => void` · optional · default: `undefined` — If provided, this callback is called whenever the copy icon is clicked.
**`onFocus`** `() => void` · optional · default: `undefined` — If provided, this callback is called whenever the code editor gets focus.
**`editorHandle`** `React.MutableRefObject<monacoEditor.IStandaloneCodeEditor | null>` · optional · default: `undefined` — This ref MAY provide access to the editor's functionality.
**`minHeight`** `number` · optional · default: `300` — The CodeEditor height, including label and description, is never smaller than this value. By default, the CodeEditor adjusts to fill its parent height. If the parent height is too short, the component uses this value as its minimum height.
**`maxHeight`** `number` · optional · default: `undefined` — The CodeEditor height, including label and description, is never larger than this value. By default, the CodeEditor adjusts to fill its parent height. This prop can set the maximum height when the parent height would otherwise be too high.
**`disabled`** `boolean` · optional · default: `undefined` — When set, the editor is read-only and uses disabled styling.
**`monacoLoader`** `'cdn' | 'local'` · optional · default: `local` — Defines how the Monaco editor files are loaded. When `local` is used, the required [additional configuration](https://github.com/suren-atoyan/monaco-react#use-monaco-editor-as-an-npm-package) MUST be provided.
**`options`** `Pick<monacoEditor.IStandaloneEditorConstructionOptions, 'tabSize'>` · optional · default: `undefined` — This prop MAY pass options to the Monaco editor. It currently supports only [`tabSize`](https://microsoft.github.io/monaco-editor/typedoc/interfaces/editor.IStandaloneEditorConstructionOptions.html#tabSize).

#### Usage

```tsx
import {useState} from 'react';
import {CodeEditor} from '@coveord/plasma-mantine';

export function JsonEditor() {
    const [value, setValue] = useState(`{
  "name": "Plasma",
  "enabled": true
}`);

    return (
        <CodeEditor
            label="Payload"
            description="Edit the JSON payload before saving."
            language="json"
            value={value}
            onChange={setValue}
            monacoLoader="cdn"
            minHeight={320}
        />
    );
}
```

────────────────────────────────────────────────────────────────────────────────

### Collection

Dynamic list input that can render items with column-based layouts or a legacy children render prop.

#### Props

> Extends: `__InputWrapperProps`, `BoxProps`, `StylesApiProps`. Only Plasma-specific props are listed below; refer to Mantine documentation for inherited props.

**`columns`** `Array<CollectionColumnDef<T>>` · optional · default: `undefined` — MAY provide column definitions for the collection. This prop is REQUIRED when using the column-based pattern.
**`layout`** `CollectionLayout` · optional · default: `CollectionLayouts.Horizontal` — MAY define the layout component to use for rendering. This prop MUST only be used with `columns`.
**`children`** `(item: T, index: number) => ReactNode` · optional · default: `undefined` — MAY provide a render function called for each item passed in the `value` prop. `columns` and `layout` MUST NOT be used with this pattern.
**`newItem`** `T | (() => T)` · required · default: `undefined` — REQUIRED. MUST define the default value each new item SHOULD have.
**`value`** `T[]` · optional · default: `[]` — MAY provide the list of items to display inside the collection.
**`getItemId`** `(originalItem: T, itemIndex: number) => string` · optional · default: `({id}) => id` — MAY define how each item is uniquely identified. It is RECOMMENDED that you specify this prop to an ID that makes sense. This method is REQUIRED when using this component with ReactHookForm.
**`onFocus`** `() => void` · optional · default: `undefined` — Optional. Unused and has no effect.
**`onChange`** `(value: T[]) => void` · optional · default: `undefined` — MAY be used to receive the whole list of items after the change whenever the value needs to be updated.
**`onRemoveItem`** `(itemIndex: number) => void` · optional · default: `undefined` — MAY be used to receive the index of the item removed from the collection using the remove button.
**`onReorderItem`** `(payload: {from: number; to: number}) => void` · optional · default: `undefined` — MAY be used to receive the origin and destination index whenever a collection item needs to be reordered.
**`onInsertItem`** `(value: T, index: number) => void` · optional · default: `undefined` — MAY be used to receive the value of the item to insert and the index of the new item to insert when a new item needs to be added to the collection.
**`draggable`** `boolean` · optional · default: `false` — MAY enable drag and drop behavior for the collection.
**`disabled`** `boolean` · optional · default: `false` — Can disable the collection; in other words, it can put the collection in read-only mode.
**`readOnly`** `boolean` · optional · default: `false` — MAY mark the collection as readOnly. If true, the collection prevents adding or removing items.
**`allowAdd`** `boolean | ((values: T[]) => boolean)` · optional · default: `undefined` — MAY determine if the add item button SHOULD be enabled given the current items of the collection. The button remains enabled if this prop is undefined.
**`addLabel`** `ReactNode` · optional · default: `"Add item"` — MAY define the label of the add item button.
**`addDisabledTooltip`** `string` · optional · default: `'There is already an empty item'` — MAY define the tooltip text displayed when hovering over the disabled add item button.
**`gap`** `MantineSpacing` · optional · default: `'md'` — MAY define the gap between the collection items.
**`required`** `boolean` · optional · default: `false` — MAY mark the collection as required. When true, the collection hides the remove button if there is only one item.

#### Sub-components

Plasma provides pre-configured sub-components as convenience wrappers. You SHOULD use these over setting props manually.

- `Collection.Layouts`

#### Usage

```tsx
import {useState} from 'react';
import {Collection, TextInput} from '@coveord/plasma-mantine';

interface Contact {
    id: string;
    name: string;
    email: string;
}

function Example() {
    const [contacts, setContacts] = useState<Contact[]>([{id: '1', name: 'Alice Smith', email: 'alice@example.com'}]);

    return (
        <Collection<Contact>
            label="Contacts"
            value={contacts}
            onChange={setContacts}
            getItemId={(contact) => contact.id}
            newItem={() => ({id: crypto.randomUUID(), name: '', email: ''})}
            columns={[
                {
                    header: 'Name',
                    cell: (contact, index) => (
                        <TextInput
                            value={contact.name}
                            onChange={(event) => {
                                const nextContacts = [...contacts];
                                nextContacts[index] = {...contact, name: event.currentTarget.value};
                                setContacts(nextContacts);
                            }}
                        />
                    ),
                    maxSize: 200,
                },
                {
                    header: 'Email',
                    cell: (contact, index) => (
                        <TextInput
                            value={contact.email}
                            onChange={(event) => {
                                const nextContacts = [...contacts];
                                nextContacts[index] = {...contact, email: event.currentTarget.value};
                                setContacts(nextContacts);
                            }}
                        />
                    ),
                },
            ]}
        />
    );
}
```

- The column-based pattern is the RECOMMENDED option for editable lists such as contacts, recipients, or rules.
- Import `Collection` and related inputs from `@coveord/plasma-mantine`.
- Pass `getItemId` when items have stable IDs, especially when the list is updated from form state.

────────────────────────────────────────────────────────────────────────────────

### CopyToClipboard

Action icon that copies a string value to the clipboard and shows tooltip feedback.

#### Props

> Extends: `ActionIconProps`. Only Plasma-specific props are listed below; refer to Mantine documentation for inherited props.

**`value`** `string` · required · default: `undefined` — The value copied to the clipboard.
**`withLabel`** `boolean` · optional · default: `false` — Deprecated. You SHOULD place the `CopyToClipboard` component inside the `rightSection` of input components instead. When used, this prop displays the string to be copied alongside the button.
**`onCopy`** `MouseEventHandler<HTMLButtonElement>` · optional · default: `undefined` — If provided, this callback is called each time the value is copied to the clipboard.
**`color`** `MantineColor | (string & {})` · optional · default: `gray` — The icon uses this color when idle.
**`tooltipLabelCopy`** `string` · optional · default: `Copy to clipboard` — The tooltip displays this text when hovering over the button.
**`tooltipLabelCopied`** `string` · optional · default: `Copied` — The tooltip displays this text when the value is copied to the clipboard.

#### Usage

Use `CopyToClipboard` in the `rightSection` of a read-only input when users need to quickly copy values like API keys, tokens, or IDs.

```tsx
import {CopyToClipboard, TextInput} from '@coveord/plasma-mantine';

export function ApiKeyField() {
    const apiKey = 'sk_live_1234567890abcdef';

    return <TextInput label="API key" value={apiKey} readOnly rightSection={<CopyToClipboard value={apiKey} />} />;
}
```

────────────────────────────────────────────────────────────────────────────────

### EllipsisText

Text component that truncates overflowing content and can show the full value in a tooltip.

#### Props

> Extends: `BoxProps`, `StylesApiProps<EllipsisTextFactory>`. Only Plasma-specific props are listed below; refer to Mantine documentation for inherited props.

**`children`** `ReactNode` · required · default: `undefined` — Consumers MUST provide the content rendered inside the truncated text, and that value can also be used as the tooltip label when overflow occurs.
**`variant`** `TextProps['variant']` · optional · default: `undefined` — Consumers MAY use this text variant to align the truncated content with surrounding typography.
**`lineClamp`** `TextProps['lineClamp']` · optional · default: `undefined` — Consumers MAY set this line clamp for multi-line truncation; when omitted, the component uses single-line ellipsis behavior.
**`tooltipProps`** `Partial<Omit<TooltipProps, 'label' | 'opened' | 'children'>>` · optional · default: `{}` — Consumers MAY customize the internal Mantine `Tooltip`, but MUST NOT provide `label`, `opened`, or `children`.

#### Usage

Use `EllipsisText` to truncate long text inside a constrained container. The most common use case is a single-line label that shows the full value on hover when it overflows.

```tsx
import {EllipsisText} from '@coveord/plasma-mantine';

function Example() {
    return <EllipsisText maw={250}>This is a very long text that is truncated with an ellipsis.</EllipsisText>;
}
```

────────────────────────────────────────────────────────────────────────────────

### Facet

Facet renders a searchable list of selectable filter options with optional counts and grouping.

#### Props

> Extends: `BoxProps`, `StylesApiProps<FacetFactory>`. Only Plasma-specific props are listed below; refer to Mantine documentation for inherited props.

**`data`** `FacetData` · required · default: `undefined` — The data to render in the component.
**`onChange`** `(values: string[]) => void` · optional · default: `undefined` — Function called when an item is selected or unselected. `values` contains the selected items.
**`onRemove`** `() => void` · optional · default: `undefined` — Called when the remove button is clicked. Only relevant when `removable` is `true`.
**`removable`** `boolean` · optional · default: `false` — When `true`, displays a close button in the facet header to allow removal.
**`initialSelection`** `string[]` · optional · default: `[]` — Initial items selection.
**`selection`** `string[]` · optional · default: `[]` — Determined items selection.
**`itemComponent`** `FacetItemComponent` · optional · default: `a checkbox with the label of the item` — Custom item component.
**`itemCountFormatter`** `(value: number) => string` · optional · default: `(count) => count.toString()` — Function to format the facet item count. `count` is the facet item count.
**`searchPlaceholder`** `string` · optional · default: `Search` — Search input placeholder.
**`onSearch`** `(value: string) => void` · optional · default: `undefined` — Called when the search query changes. `value` MUST be the search query.
**`filter`** `(query: string, item: FacetItem) => boolean` · optional · default: `function that compare the query with the label and value, case-insensitive` — Function to filter search results. `query` is the value of the search input. `item` is the current item.
**`query`** `string` · optional · default: `undefined` — Value of the search input.
**`nothingFound`** `ReactNode` · optional · default: `No matching items` — Nothing found message.
**`placeholder`** `ReactNode` · optional · default: `No items` — Displayed when a list is empty and there is no search query.
**`title`** `ReactNode` · optional · default: `undefined` — Facet title.
**`height`** `number | 'auto'` · optional · default: `200` — Maximum height. This prop SHOULD only be used when there are more than 7 values.
**`radius`** `number | string` · optional · default: `md` — Predefined border-radius value from `theme.radius` or number for border-radius in px.
**`listComponent`** `FunctionComponent<any>` · optional · default: `FacetScrollArea` — Change list component. This prop MAY be used to add custom scrollbars.
**`limit`** `number` · optional · default: `Infinity` — Limit amount of items showed at a time.
**`hideSearch`** `boolean` · optional · default: `data.length <= 7` — This prop controls whether the search input is displayed.

#### Usage

```tsx
import {Facet} from '@coveord/plasma-mantine';
import {useState} from 'react';

const sourceOptions = [
    {value: 'documentation', label: 'Documentation', count: 128, group: 'Content type'},
    {value: 'community', label: 'Community posts', count: 42, group: 'Content type'},
    {value: 'support', label: 'Support cases', count: 17, group: 'Content type'},
    {value: 'english', label: 'English', count: 156, group: 'Language'},
    {value: 'french', label: 'French', count: 23, group: 'Language'},
    {value: 'spanish', label: 'Spanish', count: 8, group: 'Language'},
];

function Example() {
    const [selection, setSelection] = useState(['documentation', 'english']);

    return (
        <Facet
            title="Sources"
            data={sourceOptions}
            selection={selection}
            onChange={setSelection}
            searchPlaceholder="Search sources"
        />
    );
}
```

────────────────────────────────────────────────────────────────────────────────

### Header

Page-level header with a title and optional breadcrumbs, actions, and a documentation link.

#### Props

> Extends: `GroupProps`, `StylesApiProps`. Only Plasma-specific props are listed below; refer to Mantine documentation for inherited props.

**`description`** `ReactNode` · optional · default: `undefined` — Optional description text displayed inside the header underneath the title.
**`borderBottom`** `boolean` · optional · default: `undefined` — Adds a bottom border to the header when set.
**`variant`** `'primary' | 'secondary'` · optional · default: `'primary'` — You SHOULD use the `primary` variant for page headers and the `secondary` variant elsewhere.
**`children`** `ReactNode` · required · default: `undefined` — The title of the header MUST be provided.
**`titleComponent`** `ElementType` · optional · default: `Title` — The component used to render the title MAY be customized.

#### Sub-components

Plasma provides pre-configured sub-components as convenience wrappers. You SHOULD use these instead of setting props manually.

- `Header.Breadcrumbs`
- `Header.BreadcrumbAnchor`
- `Header.BreadcrumbText`
- `Header.Right`
- `Header.DocAnchor`

#### Usage

```tsx
import {Button, Header} from '@coveord/plasma-mantine';

function SearchPageHeader() {
    return (
        <Header description="Review search performance, analytics, and recent query trends." borderBottom>
            <Header.Breadcrumbs>
                <Header.BreadcrumbAnchor href="/admin">Administration</Header.BreadcrumbAnchor>
                <Header.BreadcrumbText>Search</Header.BreadcrumbText>
            </Header.Breadcrumbs>
            Query dashboard
            <Header.Right>
                <Button.Secondary>Share</Button.Secondary>
                <Button.Primary>Create report</Button.Primary>
            </Header.Right>
        </Header>
    );
}
```

────────────────────────────────────────────────────────────────────────────────

### InfoToken

Inline token for displaying semantic metadata with a predefined icon.

#### Props

> Extends: `BoxProps`, `StylesApiProps`. Only Plasma-specific props are listed below; refer to Mantine documentation for inherited props.

**`variant`** `InfoTokenVariant` · optional · default: `'outline'` — The variant of the token MAY be set to control its visual treatment.
**`size`** `InfoTokenSizes` · optional · default: `'xs'` — The size of the info token MAY be set to control its rendered size.

#### Sub-components

Plasma provides pre-configured sub-components as convenience wrappers, and you MUST use these wrappers to select the semantic type because `type` is not part of the public `InfoTokenProps` API.

- `InfoToken.Information`
- `InfoToken.Advice`
- `InfoToken.Warning`
- `InfoToken.Error`
- `InfoToken.Question`
- `InfoToken.Success`

#### Usage

Use the semantic sub-components to render the most common token types.

```tsx
import {InfoToken} from '@coveord/plasma-mantine';

function Example() {
    return (
        <>
            <InfoToken.Information />
            <InfoToken.Advice />
            <InfoToken.Success />
            <InfoToken.Warning />
            <InfoToken.Error />
            <InfoToken.Question />
        </>
    );
}
```

Use `variant` to switch between the default outlined appearance and the light style.

```tsx
import {InfoToken} from '@coveord/plasma-mantine';

function Variants() {
    return (
        <>
            <InfoToken.Information variant="outline" />
            <InfoToken.Information variant="light" />
        </>
    );
}
```

────────────────────────────────────────────────────────────────────────────────

### Input

Base input wrapper extended with a LabelInfo tooltip sub-component for contextual help.

#### Props

_No additional props beyond the Mantine base component._

#### Sub-components

Plasma provides pre-configured sub-components as convenience wrappers. You SHOULD use these over setting props manually.

- `Input.Label`
- `Input.Description`
- `Input.Error`
- `Input.Wrapper`
- `Input.Placeholder`
- `Input.LabelInfo`

`Input.LabelInfo` renders an info icon next to an input label that displays a tooltip on hover. You SHOULD use it to provide additional context about a field without cluttering the label.

##### Input.LabelInfo props

> Extends: `Omit<TooltipProps, 'label' | 'classNames' | 'attributes' | 'styles' | 'vars'>`, `StylesApiProps<InputLabelInfoFactory>`. Only Plasma-specific props are listed below; refer to Mantine documentation for inherited props.

**`children`** `ReactNode` · required · default: `undefined` — The tooltip content to display.

#### Usage

```tsx
import {Input, TextInput} from '@coveord/plasma-mantine';

function Example() {
    return (
        <TextInput
            label={
                <>
                    API key <Input.LabelInfo>The secret key used to authenticate API requests.</Input.LabelInfo>
                </>
            }
            placeholder="sk_live_..."
        />
    );
}
```

────────────────────────────────────────────────────────────────────────────────

### LastUpdated

Component that displays a human-readable last-updated timestamp with default or custom formatting.

#### Props

> Extends: `BoxProps`, `Pick<GroupProps, 'justify'>`, `StylesApiProps<LastUpdatedFactory>`. Only Plasma-specific props are listed below; refer to Mantine documentation for inherited props.

**`formatter`** `(time: dayjs.ConfigType) => string` · optional · default: `(time) => dayjs(time).format('h:mm:ss A')` — Optional formatter function to format the time value. Receives the `time` prop and MUST return a string.
**`time`** `dayjs.ConfigType` · optional · default: `dayjs().valueOf()` — The unformatted time to display, parsed by dayjs when possible.
**`label`** `string` · optional · default: `'Last update:'` — Label that SHOULD contextualize the time.

#### Usage

```tsx
import {LastUpdated} from '@coveord/plasma-mantine';

export function Example() {
    return <LastUpdated time={Date.now()} />;
}
```

────────────────────────────────────────────────────────────────────────────────

### Menu

Dropdown menu with transparent support for disabled-state tooltips on `Menu.Item`.

#### Props

_No additional props beyond the Mantine base component._

#### Sub-components

Plasma overrides `Menu.Item` transparently to add disabled tooltip support. All other sub-components are standard Mantine.

- `Menu.Item` — extends Mantine's `Menu.Item` with `disabledTooltip` and `disabledTooltipProps`

##### Menu.Item additional props

**`disabledTooltip`** `string` · optional · default: `undefined` — Tooltip text MAY be provided to explain why a disabled item cannot be activated.
**`disabledTooltipProps`** `TooltipProps` · optional · default: `undefined` — Additional tooltip configuration MAY be provided for the disabled-state tooltip and SHOULD complement Plasma-managed fields.

#### Usage

```tsx
import {Button, Menu} from '@coveord/plasma-mantine';

function Example() {
    return (
        <Menu shadow="md" width={220}>
            <Menu.Target>
                <Button.Secondary>Bulk actions</Button.Secondary>
            </Menu.Target>

            <Menu.Dropdown>
                <Menu.Label>Records</Menu.Label>
                <Menu.Item onClick={() => {}}>Archive selected</Menu.Item>
                <Menu.Item
                    disabled
                    disabledTooltip="You MUST select at least one record before exporting"
                    disabledTooltipProps={{multiline: true, w: 240}}
                >
                    Export selected
                </Menu.Item>
                <Menu.Divider />
                <Menu.Item color="red" onClick={() => {}}>
                    Delete selected
                </Menu.Item>
            </Menu.Dropdown>
        </Menu>
    );
}
```

────────────────────────────────────────────────────────────────────────────────

### Modal

Overlay dialog that focuses user attention and can render a description, help link, and footer actions.

#### Props

> Extends: `MantineModalProps`. Only Plasma-specific props are listed below; refer to Mantine documentation for inherited props.

**`description`** `HeaderProps['description']` · optional · default: `undefined` — Description of the modal, displayed below the title, MAY be provided.
**`help`** `HeaderDocAnchorProps` · optional · default: `undefined` — Help link for the modal, displayed in the header, MAY be provided. It SHOULD provide a link to external documentation or help resources.

#### Sub-components

Plasma provides pre-configured sub-components as convenience wrappers. You SHOULD use these over setting props manually.

- `Modal.Root`
- `Modal.Body`
- `Modal.Overlay`
- `Modal.Content`
- `Modal.Header`
- `Modal.Title`
- `Modal.CloseButton`
- `Modal.Stack`
- `Modal.Footer`

#### Usage

```tsx
import {Button, Modal, Text} from '@coveord/plasma-mantine';
import {useState} from 'react';

function Example() {
    const [opened, setOpened] = useState(false);

    return (
        <>
            <Button.Primary onClick={() => setOpened(true)}>Archive project</Button.Primary>
            <Modal
                opened={opened}
                onClose={() => setOpened(false)}
                title="Archive project"
                description="Review the impact before confirming this change."
            >
                <Text>
                    Archiving this project removes it from active dashboards and prevents new content from being added.
                </Text>
                <Text>You can restore it later from project settings if needed.</Text>
                <Modal.Footer>
                    <Button.Tertiary onClick={() => setOpened(false)}>Cancel</Button.Tertiary>
                    <Button.Primary onClick={() => setOpened(false)}>Archive project</Button.Primary>
                </Modal.Footer>
            </Modal>
        </>
    );
}
```

────────────────────────────────────────────────────────────────────────────────

### PasswordInput

Password input with support for a read-only visual state.

#### Props

_No additional props beyond the Mantine base component._

#### Usage

```tsx
import {PasswordInput} from '@coveord/plasma-mantine';

function Example() {
    return <PasswordInput label="Database password" />;
}
```

When `readOnly` is set (and `disabled` is not), Plasma applies a distinct read-only visual style — use this instead of `disabled` when the value is informational and not interactive.

────────────────────────────────────────────────────────────────────────────────

### PrerequisitesList

Displays a list of prerequisites with status indicators (complete, incomplete).

#### Props

> Extends: `BoxProps`, `StylesApiProps`, `ElementProps<'ul'>`. Only Plasma-specific props are listed below; inherited props MUST be referenced in Mantine documentation.

**`children`** `ReactNode` · required — The `PrerequisitesList.Item` elements to render.

#### Sub-components

- `PrerequisitesList.Item` — A single prerequisite entry with a status icon and label.

##### PrerequisitesList.Item Props

**`status`** `'complete' | 'incomplete'` · required — Determines the icon and color displayed. `complete` shows a green checkmark, `incomplete` shows a grey dot.
**`label`** `string` · required — The text content of the prerequisite.
**`description`** `string` · optional · default: `undefined` — Optional description text displayed below the label in a smaller, dimmed font.

#### Usage

```tsx
import {PrerequisitesList} from '@coveord/plasma-mantine';

<PrerequisitesList>
    <PrerequisitesList.Item
        label="Completed Prerequisite"
        status="complete"
        description="Optional description of the item."
    />
    <PrerequisitesList.Item
        label="Incomplete Prerequisite"
        status="incomplete"
        description="Optional description of the item."
    />
</PrerequisitesList>;
```

────────────────────────────────────────────────────────────────────────────────

### Prompt

Confirmation modal with semantic variants and optional footer actions.

#### Props

> Extends: `Omit<ModalRootProps, 'classNames' | 'styles' | 'vars' | 'attributes' | 'variant'>`, `Omit<StylesApiProps<PromptFactory>, 'variant'>`. Only Plasma-specific props are listed below; refer to Mantine documentation for inherited props.

**`children`** `ReactNode` · required · default: `undefined` — Prompt body content MUST be provided. It MAY include `Prompt.Footer` for action buttons.
**`title`** `ReactNode` · required · default: `undefined` — Prompt title content MUST be provided and is rendered in the header.

#### Sub-components

Plasma provides pre-configured sub-components as convenience wrappers. You SHOULD use these over setting props manually.

- `Prompt.Information`
- `Prompt.Success`
- `Prompt.Warning`
- `Prompt.Critical`
- `Prompt.Footer`
- `Prompt.CancelButton`
- `Prompt.ConfirmButton`

#### Usage

```tsx
import {Prompt} from '@coveord/plasma-mantine';

function DeleteSourcePrompt({opened, onClose, onConfirm}) {
    return (
        <Prompt.Warning opened={opened} onClose={onClose} title="Delete this source?">
            Deleting this source permanently removes its configuration and stops all scheduled crawls. This action
            cannot be undone.
            <Prompt.Footer>
                <Prompt.CancelButton onClick={onClose}>Keep source</Prompt.CancelButton>
                <Prompt.ConfirmButton onClick={onConfirm}>Delete source</Prompt.ConfirmButton>
            </Prompt.Footer>
        </Prompt.Warning>
    );
}
```

────────────────────────────────────────────────────────────────────────────────

### RadioCard

Selectable card control that presents a radio option with a label and can include supporting text.

#### Props

> Extends: `RadioCardProps`, `StylesApiProps`. Only Plasma-specific props are listed below; refer to Mantine documentation for inherited props.

**`label`** `ReactNode` · required · default: `undefined` — Content rendered as the primary label next to the radio indicator.
**`description`** `ReactNode` · optional · default: `undefined` — Content rendered below the label as supporting text.
**`readOnly`** `boolean` · optional · default: `undefined` — When `true`, the card appears read-only and prevents users from changing its value through direct interaction.
**`disabledTooltip`** `string` · optional · default: `undefined` — When the card is disabled, this message can be shown in a tooltip to explain why selection is unavailable.

#### Usage

```tsx
import {Radio, RadioCard} from '@coveord/plasma-mantine';

function Example() {
    return (
        <Radio.Group defaultValue="team" label="Visibility">
            <RadioCard value="team" label="Team access" description="All team members can use this configuration." />
            <RadioCard
                value="private"
                label="Private access"
                description="Only you can use this configuration."
                disabled
                disabledTooltip="You MUST upgrade your plan to use private access."
            />
        </Radio.Group>
    );
}
```

────────────────────────────────────────────────────────────────────────────────

### Select

Select input for choosing a single option with support for a read-only visual state.

#### Props

_No additional props beyond the Mantine base component._

#### Usage

```tsx
import {Select} from '@coveord/plasma-mantine';
import {useState} from 'react';

function Example() {
    const [value, setValue] = useState<string | null>('apple');

    return (
        <Select
            label="Favorite fruit"
            data={[
                {value: 'apple', label: 'Apple'},
                {value: 'orange', label: 'Orange'},
                {value: 'banana', label: 'Banana'},
            ]}
            value={value}
            onChange={setValue}
            placeholder="Pick a fruit"
        />
    );
}
```

When `readOnly` is set (and `disabled` is not), Plasma applies a distinct read-only visual style — use this instead of `disabled` when the value is informational and not interactive.

────────────────────────────────────────────────────────────────────────────────

### StatusToken

Status indicator with semantic color coding.

#### Props

> Extends: `BoxProps`, `StylesApiProps<StatusTokenFactory>`. Only Plasma-specific props are listed below; refer to Mantine documentation for inherited props.

**`size`** `'sm' | 'lg'` · optional · default: `'lg'` — The size of the token MAY be set to control the rendered icon dimensions.
**`variant`** `'info' | 'success' | 'caution' | 'error' | 'disabled' | 'waiting' | 'edited' | 'new'` · optional · default: `'info'` — The variant of the token MUST match the status semantics you need to communicate.

#### Usage

Use `success` for healthy or completed states, `caution` for warnings, `error` for failures, `waiting` for in-progress work, and `edited` or `new` for recently changed items.

```tsx
import {StatusToken} from '@coveord/plasma-mantine';

<StatusToken variant="success" />
<StatusToken variant="caution" />
<StatusToken variant="error" />
<StatusToken variant="waiting" />
<StatusToken variant="edited" />
<StatusToken variant="new" />
```

────────────────────────────────────────────────────────────────────────────────

### StickyFooter

Action footer that remains fixed to the bottom of the viewport.

#### Props

> Extends: `Omit<GroupProps, 'classNames' | 'styles' | 'vars' | 'variant'>`, `StylesApiProps<StickyFooterFactory>`. Only Plasma-specific props are listed below; refer to Mantine documentation for inherited props.

**`borderTop`** `boolean` · optional · default: `undefined` — When `true`, a border is rendered on top of the footer.
**`children`** `ReactNode` · optional · default: `undefined` — Footer children SHOULD usually be buttons.
**`variant`** `'default' | 'modal-footer'` · optional · default: `undefined` — The `modal-footer` variant SHOULD be used when rendering the `StickyFooter` inside `Modal`. The `modal-footer` variant removes the modal's default padding so that the footer properly hugs the bottom of the modal. It also adds a border on top of the footer. Deprecated: You SHOULD use `Modal.Footer` from `@coveord/plasma-mantine/Modal` for modal footers. For other cases, the `default` variant SHOULD suffice.

#### Usage

```tsx
import {Button, StickyFooter} from '@coveord/plasma-mantine';

export const SettingsPage = () => (
    <>
        <main>{/* Form fields and page content */}</main>

        <StickyFooter borderTop>
            <Button.Secondary>Cancel</Button.Secondary>
            <Button.Secondary>Preview</Button.Secondary>
            <Button.Primary>Save changes</Button.Primary>
        </StickyFooter>
    </>
);
```

────────────────────────────────────────────────────────────────────────────────

### Table

Table for displaying tabular data with optional filtering, pagination, row actions, and layout switching.

#### Props

> Extends: `BoxProps & StylesApiProps<PlasmaTableFactory>`. Only Plasma-specific props are listed below; refer to Mantine documentation for inherited props.

**`store`** `TableStore<TData>` · required · default: `undefined` — You MUST pass the table store returned by `useTable`.
**`data`** `TData[] | null` · required · default: `undefined` — Data to display in the table. You MUST use `null` when the table is initially loading.
**`getRowId`** `CoreOptions<TData>['getRowId']` · optional · default: `undefined` — Defines how each row is uniquely identified. You SHOULD specify this prop with an ID that makes sense.
**`getRowAttributes`** `(datum: TData, index: number, row: Row<TData>) => Record<string, unknown>` · optional · default: `undefined` — HTML attributes MAY be defined for each row with this prop.
**`getRowExpandedContent`** `(datum: TData, index: number, row: Row<TData>) => ReactNode` · optional · default: `undefined` — Function that generates the expandable content of a row. You MUST return `null` for rows that do not need to be expandable.
**`getRowActions`** `(data: TData[]) => TableAction[]` · optional · default: `() => []` — Function that generates the actions for the selected rows. If the table does not support multi selection, you MUST access `data[0]`. You MUST return an empty array for rows that do not have actions.
**`columns`** `Array<ColumnDef<TData>>` · required · default: `undefined` — Columns to display in the table. This prop MUST define the rendered columns.
**`layouts`** `TableLayout[]` · optional · default: `[Table.Layouts.Rows]` — Available layouts. This prop MAY be used to expose layout switching.
**`layoutProps`** `{onRowDoubleClick?: (selectedRow: TData, index: number, row: Row<TData>) => void} & Record<string, unknown>` · optional · default: `{}` — Props passed down to the active layout Header and Body components.
**`loading`** `boolean` · optional · default: `false` — Whether the table is loading or not. This prop MAY be used to show loading states.
**`children`** `ReactNode` · optional · default: `undefined` — Children to display in the table. They MUST be wrapped in either `Table.Header` or `Table.Footer`.
**`additionalRootNodes`** `HTMLElement[]` · optional · default: `[]` — Nodes that are considered inside the table. Rows normally get unselected when clicking outside the table, but the component can have difficulty guessing what is inside or outside, for example when using modals. You MAY use this prop to force the table to consider some nodes to be inside the table.
**`options`** `Omit<Partial<TableOptions<TData>>, 'initialState' | 'data' | 'columns' | 'manualPagination' | 'enableMultiRowSelection' | 'getRowId' | 'getRowCanExpand' | 'enableRowSelection' | 'onRowSelectionChange'>` · optional · default: `{}` — Additional options MAY be passed to the table with this prop.

#### Sub-components

Plasma provides pre-configured sub-components as convenience wrappers. You SHOULD use these over setting props manually.

- `Table.AccordionColumn`
- `Table.ActionsColumn`
- `Table.ActionItem`
- `Table.CollapsibleColumn`
- `Table.DateRangePicker`
- `Table.Filter`
- `Table.Footer`
- `Table.Header`
- `Table.LastUpdated`
- `Table.Layouts`
- `Table.Loading`
- `Table.NoData`
- `Table.Pagination`
- `Table.PerPage`
- `Table.Predicate`

#### Usage

```tsx
import {createColumnHelper, Table, useTable} from '@coveord/plasma-mantine';
import {useMemo} from 'react';

type TData = {
    id: string;
    firstName: string;
    lastName: string;
    age: number;
};

const columnHelper = createColumnHelper<TData>();

const columns = [
    columnHelper.accessor('firstName', {header: 'First name'}),
    columnHelper.accessor('lastName', {header: 'Last name'}),
    columnHelper.accessor('age', {header: 'Age'}),
];

export function Example() {
    const data = useMemo<TData[]>(
        () => [
            {id: '1', firstName: 'Ada', lastName: 'Lovelace', age: 36},
            {id: '2', firstName: 'Grace', lastName: 'Hopper', age: 85},
        ],
        [],
    );

    const store = useTable<TData>({
        initialState: {
            totalEntries: data.length,
            pagination: {page: 0, perPage: 10},
        },
    });

    return <Table<TData> store={store} columns={columns} data={data} getRowId={({id}) => id} />;
}
```