# @plumile/ui

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

## Status

Specialized public package. This package is intended for teams adopting the
Kronex 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 Kronex 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`
- `BackofficeThemeProvider`
- `useTheme`
- theme contracts, tokens, and accessibility helpers
- `sprinkles`, `stateSprinkles`, and shared style recipes such as `focusRing`,
  `controlFocusRing`, `disabledControl`, `surfaceInteractive`,
  `interactiveControlSurface`, `interactiveLinkSurface`, `ghostIconButton`,
  `pillLink`, `entityReferenceLink`, `insetFocusRing`, `truncate`,
  `iconBox`, `iconBoxCompact`, `loadingShimmer`, and `visuallyHidden`

### 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`

### Formatting helpers

- `MoneyAmount` renders a currency amount from `amount` and `currency`
  props with fixed two-decimal formatting.
- `formatCurrencyAmount({ amount, currency })` provides the same formatting
  for plain-text usage such as charts, table configs, and tooltips.

### Backoffice visual components

- badges, spinners, tags, skeletons
- filter bars and drawers
- backoffice data-table wrappers and list/detail visual helpers
- `AdminSidebar` and `SidebarNavSection`, including optional sortable sections
  for backoffice navigation groups

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>
  );
}
```

`ThemeProvider` stores the public shell preference in `plumile-theme-mode`.
`BackofficeThemeProvider` stores the backoffice preference separately in
`plumile-backoffice-theme-mode`, so a backoffice can resolve light, dark, or
system mode independently inside a public page.

## 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
- styling should prefer shared sprinkles and theme style recipes; raw
  vanilla-extract `style()` is reserved for selectors, pseudo-elements,
  keyframes, container queries, CSS variables, `calc()`, `color-mix()`, or
  highly specific grid/layout cases
- shared UI styling is sprinkles-first: add recurring token-sized values and
  reusable interactive/link/icon classes to `theme/styleRecipes.css.ts` before
  creating local one-off `style()` blocks

## Limitations

- this package assumes Kronex 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 Kronex packages, especially `@plumile/router`

## Related Docs

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