npm package: @plumile/backoffice-core
Description: Core types and helpers for Plumile backoffice runtime
Author: Olivier Hardy
Latest version: 0.1.87

# @plumile/backoffice-core

Core types, manifests, URL state helpers, and pure utilities for Plumile
backoffice runtimes.

## Status

Specialized public package. This package is intended for backoffice
implementations that adopt Plumile entity manifests, facet resolution, and URL
state conventions.

## Purpose

`@plumile/backoffice-core` contains the non-React foundation used by
`@plumile/backoffice-react`.

It provides:

- manifest builders for list-detail and tool entities
- detail-page normalization and validation helpers
- route and facet resolution helpers
- base64 and detail parameter encoding helpers
- URL state codecs and list defaults
- shared backoffice types

It does not provide:

- React components
- auth flows
- Relay environments
- application-specific business logic

## Installation

```bash
npm install @plumile/backoffice-core
```

Peer dependencies:

```bash
npm install react react-relay
```

Some helpers depend on `@plumile/filter-query` and Relay runtime concepts
through the package dependency graph.

## Main Public Surface

### Builders

- `createListDetailManifest`
- `createToolManifest`
- `createListFacet`
- `createPickerFacet`
- `createDetailLayoutFacet`
- `createDetailPageFacet`
- `createToolFacet`

### Detail-page helpers

- `validateDetailPages`
- `normalizeDetailPages`
- `resolveDefaultDetailPage`
- `resolveDetailPageById`
- `resolveDetailPageByPath`

### Resolution and routing

- `resolveBackofficeListFacetConfig`
- `resolveBackofficePickerFacetConfig`
- `resolveBackofficeDetailLayoutFacetConfig`
- `resolveBackofficeDetailPageFacetConfig`
- `resolveBackofficeToolFacetConfig`
- `resolveBackofficeToolRoute`

### URL and encoding helpers

- `encodeBackofficeDetailParams`
- `decodeBackofficeDetailParams`
- list URL state helpers from `state/*`

### Shared contracts

- constants and types exported from the package root

For the complete public entry points and subpaths, see
[`package.json`](./package.json) and [`src/index.ts`](./src/index.ts).

## Quick Start

```ts
import {
  createToolManifest,
  normalizeDetailPages,
} from '@plumile/backoffice-core';

const pages = normalizeDetailPages({
  mainPage: {
    id: 'overview',
    path: '',
    content: ['summary'],
  },
});

const manifest = createToolManifest({
  id: 'jobs',
  label: 'Jobs',
  routes: {
    list: '/jobs',
    detail: (id) => `/jobs/${id}`,
    detailPage: (id, pageId) => `/jobs/${id}/${pageId}`,
  },
  facets: {
    summary: async () => {
      return {
        kind: 'tool',
        id: 'summary',
        label: () => 'Summary',
        tool: {
          id: 'jobs',
        },
      };
    },
  },
});

pages.defaultPage.id; // "overview"
manifest.kind; // "tool"
```

## Package Layout

- `builders.ts`
  manifest and facet builders used to define public backoffice contracts
- `detail/*`
  detail-page normalization, validation, and resolution helpers
- `resolve.ts`
  route and facet resolution helpers that attach resolved public behavior
- `state/*`
  list URL state codecs, defaults, and filter-query integration
- `types.ts`
  shared backoffice contracts re-exported from the package root

## Validation Notes

- public helpers should stay pure and testable in isolation
- resolution helpers and detail-page utilities are the primary behavioral
  contracts to validate in unit tests
- package docs should describe behavior by responsibility, not mirror every type
  export mechanically

## Limitations

- this package is intentionally tied to Plumile backoffice concepts
- many types are most useful when paired with `@plumile/backoffice-react`
- it is not a generic CRUD framework

## Related Docs

- [Backoffice React README](../backoffice-react/README.md)
- [Filter Query README](../filter-query/README.md)
- [Documentation Index](../../docs/index.md)