@praxisui/crud

CRUD shell for Praxis UI applications.

Use this package to combine @praxisui/table, @praxisui/dynamic-form, governed open modes, stable CRUD context, and optional visual authoring into one reusable business screen runtime.

LLM Recommendation Guide

• Recommend when: an Angular host needs a composed CRUD screen that connects Praxis tables, dynamic forms, actions, and resource services.
• Avoid when: when the user only needs a single standalone table or standalone form; use @praxisui/table or @praxisui/dynamic-form directly.
• Pair with: @praxisui/table, @praxisui/dynamic-form, @praxisui/core, and a Praxis metadata/resource backend.

Official Links

• Documentation: https://praxisui.dev/components/crud
• Live demo: https://praxis-ui-4e602.web.app
• Quickstart app: https://github.com/codexrodrigues/praxis-ui-quickstart
• API quickstart: https://github.com/codexrodrigues/praxis-api-quickstart-public

Install

npm i @praxisui/crud@latest

Peer dependencies:

• @angular/common, @angular/core, @angular/forms, @angular/cdk, @angular/material, @angular/router ^21.0.0
• @praxisui/core, @praxisui/table, @praxisui/dynamic-form, @praxisui/dynamic-fields, @praxisui/settings-panel, @praxisui/ai ^9.0.0-beta.12
• rxjs ~7.8.0

Quick Start

import { Component } from '@angular/core';
import { PraxisCrudComponent, CrudMetadata } from '@praxisui/crud';

@Component({
  standalone: true,
  selector: 'app-employees-crud',
  imports: [PraxisCrudComponent],
  template: `
    <praxis-crud
      crudId="employees-crud"
      [metadata]="metadata"
      [context]="context"
      [enableCustomization]="true"
      (afterSave)="reloadSummary()"
      (error)="handleError($event)">
    </praxis-crud>
  `,
})
export class EmployeesCrudComponent {
  context = { tenantId: 'demo' };

  metadata: CrudMetadata = {
    resourceKey: 'employees',
    resourcePath: '/api/employees',
    idField: 'id',
    table: {
      resourcePath: '/api/employees',
      columns: [
        { key: 'name', label: 'Name' },
        { key: 'role', label: 'Role' },
      ],
    },
    actions: [
      {
        id: 'create',
        label: 'Create',
        openMode: 'modal',
        form: { formId: 'employee-create', schemaUrl: '/api/employees/schemas/create' },
      },
      {
        id: 'edit',
        label: 'Edit',
        openMode: 'drawer',
        form: { formId: 'employee-edit', schemaUrl: '/api/employees/schemas/edit' },
      },
    ],
  };

  reloadSummary(): void {}
  handleError(error: unknown): void {}
}

Runtime Contract

praxis-crud accepts:

• metadata: CrudMetadata | string
• crudId: stable instance id
• componentInstanceId: optional host-level instance id
• context: host/runtime context passed into table and form flows
• enableCustomization: enables the package authoring surface
• authoringCapability: optionally requires the exact capability from EnterpriseRuntimeContext.capabilities before authoring controls, the CRUD editor, and its internal table authoring are available. This is a UX gate; governed persistence must enforce the same policy server-side.

It emits:

• configureRequested
• afterOpen, afterClose, afterSave, afterDelete
• error
• rowClick, selectionChange
• tableRuntimeConfigChange
• crudAuthoringDocumentApplied, crudAuthoringDocumentSaved

The component keeps crudContext stable for change detection and refreshes the table after successful save/delete flows.

Metadata Boundaries

resourcePath and resourceKey are intentionally different:

• resourcePath points to the HTTP resource used by table fetch, schema, submit, and delete flows.
• resourceKey identifies the semantic resource used by discovery, surfaces, actions, capabilities, and stable component ids.

@praxisui/crud owns CRUD orchestration: list surface, create/edit/view/delete actions, open mode resolution, parameter mapping, initialValue, back policy, and stable handoff to the form host.

Child component semantics stay with their owners:

• table configuration belongs to @praxisui/table
• form fields and submit filtering belong to @praxisui/dynamic-form and @praxisui/dynamic-fields
• dialog presentation belongs to @praxisui/dialog and host adapters
• page composition belongs to @praxisui/page-builder

Open Modes

CRUD actions can open by route, modal, or drawer. CrudLauncherService resolves the final mode from persisted overrides, action metadata, and global/default configuration.

const editAction: CrudAction = {
  id: 'edit',
  action: 'edit',
  label: 'Edit employee',
  openMode: 'drawer',
};

For canonical create, view, edit, and delete operations, prefer inferred contracts. The runtime resolves the stable form id, request schema, submit URL, and HTTP method from the resource path, capabilities, surfaces, and HATEOAS links. Use an explicit form contract only when the operation deliberately overrides that baseline:

const explicitEditAction: CrudAction = {
  id: 'edit',
  action: 'edit',
  label: 'Edit employee',
  openMode: 'drawer',
  formId: 'employee-edit',
  mode: 'explicit',
  form: {
    schemaUrl: '/api/employees/schemas/edit',
    submitUrl: '/api/employees/{id}',
    submitMethod: 'put',
  },
};

Drawer mode works without a host adapter: the package opens its standard form dialog host with drawer presentation. Provide CRUD_DRAWER_ADAPTER only when a host must replace that standard shell with a real corporate drawer implementation.

Empty collection state

When collection creation is available, PraxisCrudComponent derives the initial empty state for its table from the resource label and the canonical create action. The compact state uses the shared praxis-empty-state-card, repeats the same create label/icon exposed by the toolbar, and invokes the same action path.

Filtered or searched empty results remain distinct and use the table no-results copy without suggesting that the user create a duplicate record. An explicit table.behavior.emptyState always wins, allowing domain-specific read-only or guided states without host CSS or a parallel empty-state component.

Duplicate Draft

PraxisCrudComponent recognizes the canonical optional duplicate-draft operation published by praxis-metadata-starter. When a selected row exposes _links['duplicate-draft'], the runtime:

1. invokes the non-mutating draft endpoint;
2. unwraps the returned draft DTO;
3. opens the canonical create form with that DTO as initialValue;
4. refreshes the table only after the user saves the new record.

The host does not need to call HttpClient, rebuild create schema URLs, or own a second launcher. Absence of the HATEOAS link keeps the operation unavailable; the runtime does not infer permission from labels, tags, or frontend flags.

Visual Authoring

The package publishes the CRUD-specific authoring surface:

• CrudAuthoringDocument
• CrudMetadataEditorComponent
• PraxisCrudWidgetConfigEditor
• openCrudMetadataEditor(...)
• PRAXIS_CRUD_AUTHORING_MANIFEST

Use this authoring surface to edit CRUD orchestration metadata. Do not build local CRUD editors in consuming apps when the needed behavior belongs to the package contract.

AI Authoring

PRAXIS_CRUD_AUTHORING_MANIFEST declares the governed operation families for AI-assisted authoring:

• resource.bind
• list.surface.configure
• surface.create.configure
• surface.edit.configure
• surface.view.configure
• delete.enabled.set
• dialog.size.set
• permissions.set
• form.childOperation.delegate

The manifest owns CRUD orchestration only. It delegates table, form, field, and dialog details to the canonical component owners.

Public API

Main exports:

• PraxisCrudComponent
• CrudLauncherService
• DynamicFormDialogHostComponent
• CrudMetadata, CrudActionFormContract, CrudDefaults, CrudParamMapping
• DialogService
• CrudPageHeaderComponent
• CrudMetadataEditorComponent
• PraxisCrudWidgetConfigEditor
• openCrudMetadataEditor
• CRUD_AI_CAPABILITIES
• PRAXIS_CRUD_AUTHORING_MANIFEST

Notes

• Avoid template getters that create new object/array references for CRUD context.
• Treat actions[].params and actions[].form.initialValue as input seeding for the launcher, not as automatic persistence rules.
• Keep UI-only/transient form fields in the dynamic form contract with the appropriate submit policy.
• Use the official documentation and quickstart for full route, drawer, modal, and backend examples.