@praxisui/crud 1.0.0-beta.5 → 1.0.0-beta.52

package/README.md

@@ -1,6 +1,107 @@
-# PraxisCrud
+---
+title: "CRUD"
+slug: "crud-overview"
+description: "Visao geral do @praxisui/crud com fluxo table+form, open modes governados, estabilidade de contexto e orientacoes de integracao."
+doc_type: "reference"
+document_kind: "component-overview"
+component: "crud"
+category: "data-crud"
+audience:
+  - "frontend"
+  - "host"
+  - "architect"
+level: "intermediate"
+status: "active"
+owner: "praxis-ui"
+tags:
+  - "crud"
+  - "table"
+  - "form"
+  - "open-mode"
+  - "integration"
+order: 20
+icon: "database"
+toc: true
+sidebar: true
+search_boost: 1.0
+reading_time: 12
+estimated_setup_time: 20
+version: "1.0"
+related_docs:
+  - "host-crud-integration"
+  - "host-integration-guide"
+keywords:
+  - "crud context"
+  - "open mode"
+  - "drawer"
+  - "modal"
+last_updated: "2026-03-07"
+---
+
+# @praxisui/crud
+
+> Componentes e utilitários para telas CRUD no Praxis UI.
+
+## 🎨 Tema M3 (tokens mínimos)
+
+Para garantir que cabeçalhos e ações reflitam o tema do app host:
+
+- Superfícies: `--md-sys-color-surface`, `--md-sys-color-surface-container`
+- Texto/contorno: `--md-sys-color-on-surface`, `--md-sys-color-on-surface-variant`, `--md-sys-color-outline-variant`
+- Semânticos: `--md-sys-color-primary`, `--md-sys-color-error`
+- Elevação: `--md-sys-elevation-level1`–`--md-sys-elevation-level2`
+Nota: a classe de tema é decisão do host (`.dark-theme` ou `.theme-dark`/`.theme-light`); mantenha tokens e componentes no mesmo escopo.
+
+## 🔰 Exemplos / Quickstart
+
+Para ver esta biblioteca em funcionamento em uma aplicação completa, utilize o projeto de exemplo (Quickstart):
+
+- Repositório: https://github.com/codexrodrigues/praxis-ui-quickstart
+- O Quickstart demonstra a integração das bibliotecas `@praxisui/*` em um app Angular, incluindo instalação, configuração e uso em telas reais.
+
+## Estabilidade de Change Detection
+
+Para evitar regressoes de performance no fluxo CRUD, o `PraxisCrudComponent` mantem `crudContext` estavel em memoria.
+
+Problema evitado:
+- getters que retornam objetos novos a cada ciclo de CD provocam re-render constante no `PraxisTable`
+- sintoma tipico: warnings de frame lento e UI \"pesada\" em rotas CRUD
+
+Padrao recomendado:
+- calcular o contexto uma vez por mudanca relevante (`ngOnChanges`)
+- reutilizar a mesma referencia no template
+
+Anti-pattern:
+```ts
+get tableCrudContext() {
+  return { tableId: 'x', actions: [] };
+}
+```
+
+Padrao aplicado:
+```ts
+tableCrudContext?: CrudContext;
+
+ngOnChanges(changes: SimpleChanges): void {
+  if (changes['metadata']) {
+    this.tableCrudContext = this.buildTableCrudContext(this.resolvedMetadata);
+  }
+}
+```
+
+Checklist rapido para PR:
+- evitar metodos/getters no template que criem objeto/array
+- preferir memoizacao por ciclo de vida/signal
+- manter `trackBy` em listas dinamicas
+
+## Documentacao Tecnica da Lib
+
+- `projects/praxis-crud/docs/host-crud-runtime-and-openmode.md`
+- `projects/praxis-crud/docs/adr/2026-03-drawer-adapter-light-entrypoint.md`
+
+---
 
-This project was generated using [Angular CLI](https://github.com/angular/angular-cli) version 20.1.0.
+Este projeto foi gerado com [Angular CLI](https://github.com/angular/angular-cli) versão 20.1.0.
 
 ## Code scaffolding
 

package/drawer-adapter/index.d.ts

@@ -0,0 +1,81 @@
+import { InjectionToken } from '@angular/core';
+import { MatDialogConfig } from '@angular/material/dialog';
+import { RowAction, ToolbarAction, BackConfig, ApiEndpoint, TableConfig, FormConfig } from '@praxisui/core';
+
+type FormOpenMode = 'route' | 'modal' | 'drawer';
+interface CrudParamMapping {
+    from: string;
+    to: 'routeParam' | 'query' | 'input';
+    name: string;
+}
+type CrudAction = (RowAction | ToolbarAction) & {
+    openMode?: FormOpenMode;
+    route?: string;
+    formId?: string;
+    params?: CrudParamMapping[];
+    back?: BackConfig;
+};
+interface CrudHeaderConfig {
+    showBack?: boolean;
+    backLabel?: string;
+    variant?: 'ghost' | 'tonal' | 'outlined';
+    sticky?: boolean;
+    breadcrumbs?: boolean;
+    divider?: boolean;
+}
+interface CrudDefaults {
+    openMode?: FormOpenMode;
+    modal?: DialogConfig;
+    back?: BackConfig;
+    header?: CrudHeaderConfig;
+}
+interface CrudResource {
+    path: string;
+    idField?: string | number;
+    endpointKey?: ApiEndpoint;
+}
+interface CrudMetadata {
+    component: 'praxis-crud';
+    resource?: CrudResource;
+    data?: any[] | null;
+    table: TableConfig;
+    form?: FormConfig;
+    defaults?: CrudDefaults;
+    actions?: CrudAction[];
+    i18n?: {
+        crudDialog?: Record<string, string>;
+    };
+}
+type CrudDrawerResultType = 'save' | 'delete' | 'close';
+interface CrudDrawerResult {
+    type: CrudDrawerResultType;
+    data?: Record<string, unknown>;
+}
+interface CrudDrawerOpenConfig {
+    action: CrudAction;
+    metadata: CrudMetadata;
+    inputs: Record<string, unknown>;
+    /**
+     * Notifica fechamento do drawer (cancelamento/fechamento externo/resultado finalizado).
+     */
+    onClose?: () => void;
+    /**
+     * Notifica resultado semântico do fluxo em drawer.
+     * Hosts podem propagar `save/delete/close` para sincronizar telemetria/eventos.
+     */
+    onResult?: (result: CrudDrawerResult) => void;
+}
+interface CrudDrawerAdapter {
+    open(config: CrudDrawerOpenConfig): Promise<void> | void;
+}
+interface DialogConfig<D = any> extends MatDialogConfig<D> {
+    disableCloseOnBackdrop?: boolean;
+    disableCloseOnEsc?: boolean;
+    canMaximize?: boolean;
+    startMaximized?: boolean;
+    fullscreenBreakpoint?: number;
+}
+declare const CRUD_DRAWER_ADAPTER: InjectionToken<CrudDrawerAdapter>;
+
+export { CRUD_DRAWER_ADAPTER };
+export type { CrudAction, CrudDefaults, CrudDrawerAdapter, CrudDrawerOpenConfig, CrudDrawerResult, CrudDrawerResultType, CrudHeaderConfig, CrudMetadata, CrudParamMapping, CrudResource, DialogConfig, FormOpenMode };

package/drawer-adapter/package.json

@@ -0,0 +1,3 @@
+{
+  "module": "../fesm2022/praxisui-crud-drawer-adapter.mjs"
+}

package/fesm2022/praxisui-crud-drawer-adapter.mjs

@@ -0,0 +1,18 @@
+import { InjectionToken } from '@angular/core';
+
+function getCrudDrawerAdapterToken() {
+    const registryKey = '__PAX_CRUD_DRAWER_ADAPTER_TOKEN__';
+    const globalRegistry = globalThis;
+    if (!globalRegistry[registryKey]) {
+        globalRegistry[registryKey] = new InjectionToken('CRUD_DRAWER_ADAPTER');
+    }
+    return globalRegistry[registryKey];
+}
+const CRUD_DRAWER_ADAPTER = getCrudDrawerAdapterToken();
+
+/**
+ * Generated bundle index. Do not edit.
+ */
+
+export { CRUD_DRAWER_ADAPTER };
+//# sourceMappingURL=praxisui-crud-drawer-adapter.mjs.map

package/fesm2022/praxisui-crud-drawer-adapter.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"praxisui-crud-drawer-adapter.mjs","sources":["../../../projects/praxis-crud/drawer-adapter/src/drawer-adapter.ts","../../../projects/praxis-crud/drawer-adapter/praxisui-crud-drawer-adapter.ts"],"sourcesContent":["import { InjectionToken } from '@angular/core';\nimport type { MatDialogConfig } from '@angular/material/dialog';\nimport type {\n  ApiEndpoint,\n  BackConfig,\n  FormConfig,\n  RowAction,\n  TableConfig,\n  ToolbarAction,\n} from '@praxisui/core';\n\nexport type FormOpenMode = 'route' | 'modal' | 'drawer';\n\nexport interface CrudParamMapping {\n  from: string;\n  to: 'routeParam' | 'query' | 'input';\n  name: string;\n}\n\nexport type CrudAction = (RowAction | ToolbarAction) & {\n  openMode?: FormOpenMode;\n  route?: string;\n  formId?: string;\n  params?: CrudParamMapping[];\n  back?: BackConfig;\n};\n\nexport interface CrudHeaderConfig {\n  showBack?: boolean;\n  backLabel?: string;\n  variant?: 'ghost' | 'tonal' | 'outlined';\n  sticky?: boolean;\n  breadcrumbs?: boolean;\n  divider?: boolean;\n}\n\nexport interface CrudDefaults {\n  openMode?: FormOpenMode;\n  modal?: DialogConfig;\n  back?: BackConfig;\n  header?: CrudHeaderConfig;\n}\n\nexport interface CrudResource {\n  path: string;\n  idField?: string | number;\n  endpointKey?: ApiEndpoint;\n}\n\nexport interface CrudMetadata {\n  component: 'praxis-crud';\n  resource?: CrudResource;\n  data?: any[] | null;\n  table: TableConfig;\n  form?: FormConfig;\n  defaults?: CrudDefaults;\n  actions?: CrudAction[];\n  i18n?: { crudDialog?: Record<string, string> };\n}\n\nexport type CrudDrawerResultType = 'save' | 'delete' | 'close';\n\nexport interface CrudDrawerResult {\n  type: CrudDrawerResultType;\n  data?: Record<string, unknown>;\n}\n\nexport interface CrudDrawerOpenConfig {\n  action: CrudAction;\n  metadata: CrudMetadata;\n  inputs: Record<string, unknown>;\n  /**\n   * Notifica fechamento do drawer (cancelamento/fechamento externo/resultado finalizado).\n   */\n  onClose?: () => void;\n  /**\n   * Notifica resultado semântico do fluxo em drawer.\n   * Hosts podem propagar `save/delete/close` para sincronizar telemetria/eventos.\n   */\n  onResult?: (result: CrudDrawerResult) => void;\n}\n\nexport interface CrudDrawerAdapter {\n  open(config: CrudDrawerOpenConfig): Promise<void> | void;\n}\n\nexport interface DialogConfig<D = any> extends MatDialogConfig<D> {\n  disableCloseOnBackdrop?: boolean;\n  disableCloseOnEsc?: boolean;\n  canMaximize?: boolean;\n  startMaximized?: boolean;\n  fullscreenBreakpoint?: number;\n}\n\nfunction getCrudDrawerAdapterToken(): InjectionToken<CrudDrawerAdapter> {\n  const registryKey = '__PAX_CRUD_DRAWER_ADAPTER_TOKEN__';\n  const globalRegistry = globalThis as typeof globalThis & {\n    [registryKey]?: InjectionToken<CrudDrawerAdapter>;\n  };\n  if (!globalRegistry[registryKey]) {\n    globalRegistry[registryKey] = new InjectionToken<CrudDrawerAdapter>('CRUD_DRAWER_ADAPTER');\n  }\n  return globalRegistry[registryKey];\n}\n\nexport const CRUD_DRAWER_ADAPTER = getCrudDrawerAdapterToken();\n","/**\n * Generated bundle index. Do not edit.\n */\n\nexport * from './public-api';\n"],"names":[],"mappings":";;AA8FA,SAAS,yBAAyB,GAAA;IAChC,MAAM,WAAW,GAAG,mCAAmC;IACvD,MAAM,cAAc,GAAG,UAEtB;AACD,IAAA,IAAI,CAAC,cAAc,CAAC,WAAW,CAAC,EAAE;QAChC,cAAc,CAAC,WAAW,CAAC,GAAG,IAAI,cAAc,CAAoB,qBAAqB,CAAC;IAC5F;AACA,IAAA,OAAO,cAAc,CAAC,WAAW,CAAC;AACpC;AAEO,MAAM,mBAAmB,GAAG,yBAAyB;;ACzG5D;;AAEG;;;;"}