@plumile/backoffice-core

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

Status

Specialized public package. This package is intended for backoffice implementations that adopt Kronex 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
• synchronous, destination-aware list navigation contracts and URL codecs
• shared backoffice types

It does not provide:

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

Installation

npm install @plumile/backoffice-core

Peer dependencies:

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

createListDetailManifest requires a non-empty detail-page manifest, one matching default page, and both detail facet loaders. When hasList is true, the list loader is required as well. The builder validates the same invariants at runtime so JavaScript consumers and unsafe casts fail during manifest construction instead of during navigation.

Detail-page helpers

• validateDetailPages
• normalizeDetailPages
• resolveDefaultDetailPage
• resolveDetailPageById
• resolveDetailPageByPath

Resolution and routing

• resolveBackofficeListFacetConfig
• resolveBackofficePickerFacetConfig
• resolveBackofficeDetailLayoutFacetConfig
• resolveBackofficeDetailPageFacetConfig
• resolveBackofficeToolFacetConfig
• resolveBackofficeToolRoute

URL and encoding helpers

• encodeBackofficeDetailParams
• decodeBackofficeDetailParams(value, decoder) parses the transport payload as unknown and returns a value only when the caller-provided decoder validates it
• createBackofficeListNavigation
• defineBackofficeListNavigation
• createBackofficeListUrlCodec

Shared contracts

• constants and types exported from the package root
• BackofficeListNavigation converts list state to structured router { filters, query } values through encode, and converts them back through decode
• list-detail manifests with hasList: true must expose listNavigation; the resolved list config exposes the same synchronous contract
• list-detail manifests may provide detailLabel so React integrations can render a stable detail shell before the detail layout facet has loaded

For the complete public entry points and subpaths, see package.json and src/index.ts.

List navigation

Define the URL contract next to the lightweight entity manifest so destination links can serialize filters before the lazy list facet has loaded:

const listNavigation = defineBackofficeListNavigation<JobsListQuery>()({
  defaults: { where: null, sort: 'CREATED_AT_DESC' },
  filterSchema: jobsFilterSchema,
  sortIds: ['CREATED_AT_DESC', 'CREATED_AT_ASC'],
});

const destination = listNavigation.encode({
  where: { status: 'RUNNING' },
});
// destination.filters -> { status: { eq: 'RUNNING' } }
// destination.query -> { sort: 'CREATED_AT_DESC' }

listNavigation.decode(destination);
// -> { where: { status: 'RUNNING' }, sort: 'CREATED_AT_DESC' }

Pass listNavigation.querySchema to the list route and pass the encoded filters and query to @plumile/router links. Raw URL strings are not part of this contract.

Quick Start

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 Kronex 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
• Filter Query README
• Documentation Index