npm package: @plumile/ui
Description: Shared React UI primitives and theme for Plumile applications
Author: Olivier Hardy
Latest version: 0.1.87

# @plumile/ui

Shared React UI primitives, layouts, and theme foundations for Plumile
applications.

## Status

Specialized public package. This package is intended for teams adopting the
Plumile design language and component conventions. It is not a generic UI kit
for arbitrary React applications.

## Purpose

`@plumile/ui` is the visual layer of the Plumile ecosystem. It provides:

- theme contracts and tokens
- low-level form and feedback primitives
- shared layouts and page shells
- data-heavy and admin-oriented widgets
- reusable backoffice visual components

It does not provide:

- application business logic
- GraphQL orchestration
- router orchestration beyond consuming router links where needed

## Installation

```bash
npm install @plumile/ui
```

Peer dependencies:

```bash
npm install react react-dom i18next react-i18next
```

If you use components that depend on router links, also install
`@plumile/router`.

## Main Public Surface

The package entry point groups exports by UI family instead of exposing a single
flat mental model.

### Theme and styling

- `ThemeProvider`
- `useTheme`
- theme contracts, tokens, and accessibility helpers

### Primitives and forms

- `Button`, `LinkButton`, `Input`, `Textarea`, `Checkbox`
- `Label`, `ErrorMessage`, `Form`, `FormField`, `FormGroup`
- `ToastProvider`, `ToastViewport`

### Layouts and shells

- `AppShell`, `PageShell`, `SidebarPageLayout`, `SettingsLayout`
- `ContentLayout`, `SplitViewLayout`, `PanelShell`, `ToolbarRow`

### Data-heavy and dashboard components

- `DataTable`, `VirtualizedConnectionTable`
- `MetricCard`, `MetricTileGroup`, `StatusSummaryPanel`
- `ActivityFeed`, `TimelineEventRow`, `InfoTile`

### Backoffice visual components

- badges, spinners, tags, skeletons
- filter bars and drawers
- backoffice data-table wrappers and list/detail visual helpers

For the complete export list, see [`src/index.ts`](./src/index.ts).

## Quick Start

```tsx
import { Button, ThemeProvider, ToolbarRow } from '@plumile/ui';

export function ExampleScreen(): JSX.Element {
  return (
    <ThemeProvider defaultMode="light">
      <ToolbarRow>
        <Button>Save</Button>
        <Button kind="secondary">Cancel</Button>
      </ToolbarRow>
    </ThemeProvider>
  );
}
```

## Package Layout

- `theme/*`
  canonical source of shared design tokens and theme primitives
- `atomic/*`
  low-level reusable React building blocks
- `components/*`
  generic cross-application layouts and widgets
- `backoffice/*`
  specialized data-heavy visual components for admin and backoffice screens

## Validation Notes

- public UI behavior should be covered by targeted tests for stable components
- visual breadth is large, so documentation and examples should stay organized by
  component families rather than exhaustive component-by-component prose
- Storybook stories are useful for visual review, but they do not replace
  behavioral tests for stable public components

## Limitations

- this package assumes Plumile theme tokens and styling conventions
- it is intentionally opinionated for backoffice and admin-style interfaces
- it does not try to be a framework-agnostic design system
- some components assume other Plumile packages, especially `@plumile/router`

## Related Docs

- [Repository README](../../README.md)
- [Documentation Index](../../docs/index.md)
- [Backoffice React README](../backoffice-react/README.md)