@praxisui/table 8.0.0-beta.2 → 8.0.0-beta.20

package/docs/column-resize-reorder-implementation-plan.md

@@ -0,0 +1,338 @@
+# Column Resize + Reorder Implementation Plan
+
+## Objective
+
+Allow users to resize and move columns in `praxis-table` without conflicting with sorting, while keeping behavior predictable, accessible, and persistent.
+
+## Guiding Principles
+
+- `sort` belongs to a dedicated sortable label/container, not to the entire `th`
+- `reorder` belongs to a dedicated drag handle
+- `resize` belongs to a dedicated handle on the right edge of the header cell
+- runtime mutations should reuse the existing persistence pipeline through a shared column-mutation coordinator
+- width persistence should normalize to `px`
+- keep the existing config model and avoid introducing parallel API knobs
+
+## Current Architecture Notes
+
+Today the table header combines multiple behaviors on the same `th`:
+
+- `mat-sort-header`
+- `cdkDrag`
+- reorder affordance/indicator
+- sticky start/end support
+- horizontal scroll modes already used in production
+
+Relevant files:
+
+- `/mnt/d/Developer/praxis-plataform/praxis-ui-angular/projects/praxis-table/src/lib/praxis-table.html`
+- `/mnt/d/Developer/praxis-plataform/praxis-ui-angular/projects/praxis-table/src/lib/praxis-table.scss`
+- `/mnt/d/Developer/praxis-plataform/praxis-ui-angular/projects/praxis-table/src/lib/praxis-table.ts`
+
+This is the main reason resize must not be introduced as another gesture on the same interaction zone. It also means sticky and horizontal scroll behavior must be treated as first-order implementation concerns, not deferred work.
+
+Additional constraints from the current implementation:
+
+- reorder keyboard parity is attached to the `th`, not to a standalone handle
+- reorder aria-label and tooltip are currently attached to the `th`
+- persistence currently saves the full `config` snapshot for each runtime mutation
+- width styling may already come from `column.width`, `headerStyle`, or `style`
+
+Current reorder affordance note:
+
+- the drag handle is rendered before the header text in draggable headers so the grip appears first visually without changing the current `cdkDrag` root on the `th`
+- this is a visual/layout choice only in the current implementation slice; the handle is still non-interactive and the full draggable header remains the active drag target
+
+The plan must explicitly unwind those couplings instead of treating them as incidental details.
+
+## Implementation Phases
+
+### Phase 1: Split Header Interaction Zones
+
+Refactor the header so each interaction has an explicit zone:
+
+- sortable label container: sort
+- drag icon/handle: reorder
+- right-edge handle: resize
+
+Changes in `praxis-table.html`:
+
+- keep `.praxis-header-label-text`
+- keep the drag handle rendered before the label text while the current reorder UX still relies on the full `th` as drag root
+- add a sortable wrapper such as `.praxis-header-sort-trigger`
+- keep `.praxis-column-drag-handle`
+- add `.praxis-column-resize-handle`
+- keep `cdkDrag` on the `th`
+- add `cdkDragHandle` to the reorder handle so the existing drag root, preview, placeholder sizing, and index semantics stay intact
+- move reorder `aria-label`, tooltip, and keyboard listeners from the `th` to the reorder handle
+- ensure the resize handle and reorder handle both stop `click`, `pointerdown`, and keyboard bubbling into the sort trigger
+
+Changes in `praxis-table.scss`:
+
+- make the sortable label container the only area that shows sort cursor/hover treatment
+- keep drag handle aligned next to the label text
+- add resize handle positioned at the far right edge
+- use `cursor: grab` for reorder
+- use `cursor: col-resize` for resize
+- use a hit area around `8px` to `12px` for resize
+- remove `pointer-events: none` from the drag handle and make it a real interactive control
+
+Sorting strategy:
+
+- do not keep the full `th` as the primary sort interaction target
+- move the sort trigger to the label/container inside the header cell
+- preserve keyboard sort semantics on that dedicated sort target
+- treat suppression of `click` on reorder/resize handles as a hard requirement, not a best-effort safeguard
+
+### Phase 2: Add Runtime Resize State
+
+Add state to `praxis-table.ts`:
+
+- `activeResizeColumnField: string | null`
+- `resizeStartX: number`
+- `resizeStartWidthPx: number`
+- `isResizingColumn: boolean`
+- `resizePointerId: number | null`
+
+Add internal defaults:
+
+- derive defaults from the existing config model first
+- use `behavior.resizing.minColumnWidth` and `behavior.resizing.maxColumnWidth` when present
+- fall back to sane internal defaults only when config is absent
+
+Add handlers:
+
+- `onColumnResizePointerDown(event, column)`
+- `onColumnResizePointerMove(event)`
+- `onColumnResizePointerUp(event)`
+- `onColumnResizePointerCancel(event)`
+- `cancelColumnResize()`
+
+Add runtime width state:
+
+- keep transient width changes separate from persisted `config.columns[]` until commit
+- resolve whether a column is resizable from both `behavior.resizing.enabled` and `column.resizable !== false`
+- exclude non-data columns (`_select`, `_expander`, `_actions`) from resize by design
+
+### Phase 3: Prevent Interaction Conflicts
+
+On resize start:
+
+- call `preventDefault()`
+- call `stopPropagation()`
+- capture the active pointer
+- temporarily block sort and reorder while `isResizingColumn === true`
+
+Behavioral rule:
+
+- dragging only starts from the reorder handle
+- sorting only starts from the dedicated sortable label/container
+- resizing only starts from the right-edge resize handle
+
+During resize:
+
+- apply a class such as `pfx-column-resizing`
+- temporarily disable `cdkDropList`
+- ignore sort triggers from the header
+- ensure sticky columns and resize handles preserve usable hit areas and z-index ordering
+- preserve horizontal scroll behavior while pointer capture is active
+- support abort paths: `Escape`, `pointercancel`, lost capture, and pointerup outside the viewport
+
+### Phase 4: Normalize and Apply Widths
+
+Add width utilities to `praxis-table.ts`:
+
+- `resolveColumnWidthPx(column, headerEl): number`
+- `clampColumnWidthPx(width: number): number`
+- `formatColumnWidthPx(width: number): string`
+
+Width rules:
+
+- if `column.width` is already in `px`, use it directly
+- if width is `%`, `auto`, or empty, measure the current header width at first resize and convert to `px`
+- persist resized widths as `px`
+- explicitly define precedence when `headerStyle` or `style` also carry width declarations
+- document that first user resize converts responsive width intent into fixed runtime width intent
+- validate width behavior under sticky start/end columns and horizontal scroll mode
+
+Keep `getColumnWidthStyle(column)` as the main rendering output, now backed by updated runtime values.
+
+### Phase 5: Persistence
+
+Reuse the existing runtime mutation persistence flow in `praxis-table.ts`, but do not let resize and reorder persist independently against unrelated config snapshots.
+
+Add a shared column runtime mutation coordinator:
+
+- monotonic `columnMutationOperationId`
+- mutation kind: `column-reorder` | `column-resize`
+- per-operation snapshot merge before `saveConfig`
+- stale-callback rejection shared by reorder and resize
+- serialized commit semantics when reorder and resize overlap in time
+
+Refactor `persistTableConfigAfterRuntimeMutation(...)` usage behind a narrower helper such as:
+
+- `persistColumnRuntimeMutation(trigger, mutateConfig, options)`
+
+Add a new trigger:
+
+- `column-resize`
+
+Persist width by updating the matching entry in `config.columns[]`:
+
+- locate by `field`
+- set `width: "${px}px"`
+
+Resize persistence policy:
+
+- persist on commit only, not continuously during pointer move
+- commit point is `pointerup` for pointer interactions
+- keyboard resize is not part of the first delivery slice
+- when keyboard resize is added later, commit semantics must be explicit (`Enter`, `blur`, or stepwise save), not implied
+- define stale-callback protection for resize and reorder through the same shared coordinator
+- do not add undo in the first slice unless a concrete UX requirement appears, but keep the runtime contract compatible with future undo support
+
+Emit a resize event after persistence:
+
+- `columnResize`
+
+Suggested payload:
+
+- `tableId`
+- `field`
+- `header`
+- `previousWidth`
+- `currentWidth`
+- `persisted`
+
+### Phase 6: Public Configuration API
+
+Align strictly with the existing config model. Do not introduce a second naming scheme.
+
+Use the existing behavior flags in the core model:
+
+- `behavior.dragging.columns`
+- `behavior.resizing.enabled`
+- `behavior.resizing.minColumnWidth`
+- `behavior.resizing.maxColumnWidth`
+- `behavior.resizing.persistWidths`
+- `ColumnDefinition.resizable`
+
+Optional future additions should only happen if the current model proves insufficient.
+
+Recommended rollout:
+
+- keep `dragging.columns = true`
+- ship resize behind `behavior.resizing.enabled`
+- honor `behavior.resizing.persistWidths` when deciding whether to save width runtime mutations
+- keep `column.resizable !== false` as the per-column opt-out
+- do not add new public API until the current model proves insufficient under real usage
+
+### Phase 7: Accessibility
+
+Resize handle:
+
+- `role="separator"`
+- `aria-orientation="vertical"`
+- `aria-label="Resize column X"`
+- `tabindex="0"`
+- expose current/min/max width semantics explicitly when implemented
+- announce committed width changes through the existing live-region pattern or an equivalent status channel
+
+Keyboard behavior for resize handle:
+
+- defer keyboard resize to a follow-up slice after pointer behavior and persistence are stable
+- when implemented, define `ArrowLeft`, `ArrowRight`, `Shift + Arrow`, `Home`, `End`, and `Escape`
+- define exactly when the resize is committed and when it is cancelled
+
+Reorder handle:
+
+- make the reorder handle a real focusable control
+- move existing Alt/Ctrl+Arrow reorder behavior onto the handle
+- move existing reorder aria-label and tooltip onto the handle
+- preserve visible focus styling and screen-reader parity after removing those affordances from the `th`
+
+### Phase 8: Testing
+
+Add focused tests for interaction conflicts:
+
+- resize does not trigger reorder
+- resize does not trigger sort
+- resize handle click does not bubble into sort click
+- reorder does not alter width
+- clicking the sortable label still sorts
+- reorder still works through the dedicated `cdkDragHandle`
+- keyboard reorder still works after moving intent to the handle
+- sort keyboard interaction still works after sort leaves the `th`
+
+Add persistence tests:
+
+- width updates `config.columns`
+- width persists through the shared column mutation coordinator
+- width survives rerender/reload flow
+- width persistence respects `behavior.resizing.persistWidths`
+- resize persists only on commit, not on every pointer move
+- concurrent resize/reorder persistence does not leave stale width/order state
+- out-of-order async persistence callbacks do not overwrite the latest width/order snapshot
+
+Add limit tests:
+
+- `minWidthPx` is respected
+- `maxWidthPx` is respected
+
+Add pointer/cancel coverage:
+
+- resize aborts cleanly on `Escape`
+- resize aborts cleanly on `pointercancel`
+- resize completes correctly when pointerup happens outside the immediate handle area
+
+Add visual/e2e coverage later:
+
+- resize with horizontal scroll enabled
+- resize under `scroll-auto`
+- resize under `scroll-wrap`
+- reorder still works after resize
+- sticky start column resize
+- sticky end column resize
+- sticky columns do not produce overlap/z-index regression while resizing
+- adjacent non-data columns (`_select`, `_expander`, `_actions`) do not regress
+- responsive scroll modes remain aligned between header and body
+
+## Recommended Delivery Sequence
+
+1. Refactor header structure so sort is isolated to a dedicated sortable label/container
+2. Move reorder affordance, keyboard handling, aria-label, and tooltip to a real drag handle
+3. Add resize handle with runtime-only pointer support and explicit cancel paths
+4. Validate sticky and horizontal-scroll behavior in the same slice
+5. Introduce shared column runtime mutation coordination for reorder + resize persistence
+6. Persist column width on commit only
+7. Add focused conflict and persistence tests
+8. Add keyboard resize and final resize a11y semantics in a follow-up slice
+9. Enable only through config/feature flag
+
+## Definition of Done
+
+- users can reorder only from the drag handle
+- users can resize only from the right-edge handle
+- clicking the sortable label still sorts
+- reorder, resize, and sort do not interfere with each other
+- width and order persist correctly
+- stale async persistence callbacks cannot revert the latest width/order mutation
+- existing horizontal scroll and sticky behavior remain intact after first resize
+
+## Risk Notes
+
+- gesture ambiguity is not solved by event suppression alone; sort must be structurally isolated from reorder/resize handles
+- supporting `%` and `auto` widths requires careful first-resize normalization
+- first resize may intentionally convert responsive width behavior into fixed pixel width behavior
+- sticky start/end columns and horizontal scroll are immediate implementation concerns
+- resize and reorder mutations need a shared commit/stale-callback policy, not parallel ad hoc logic
+
+## Suggested Follow-Up
+
+After review, break this plan into small implementation tasks by file:
+
+- `praxis-table.html`
+- `praxis-table.scss`
+- `praxis-table.ts`
+- relevant core config model files
+- dedicated unit/integration specs

package/docs/column-resize-reorder-review-prompt.md

@@ -0,0 +1,34 @@
+# Review Prompt For Another Agent
+
+Review the implementation plan in:
+
+- `/mnt/d/Developer/praxis-plataform/praxis-ui-angular/projects/praxis-table/docs/column-resize-reorder-implementation-plan.md`
+
+Context:
+
+- The goal is to support both column resizing and column reordering in `praxis-table`.
+- The current table header already combines `mat-sort-header`, `cdkDrag`, and reorder UI.
+- We want a robust solution where `sort`, `reorder`, and `resize` do not conflict.
+- The plan assumes:
+  - sorting stays on the header text/content area
+  - reordering moves to a dedicated drag handle
+  - resizing uses a dedicated right-edge handle
+  - width persistence reuses the existing runtime mutation persistence flow
+
+What to review:
+
+1. Validate whether the interaction model is robust and aligned with mature grid implementations.
+2. Identify technical risks in the proposed architecture, especially around Angular Material, CDK drag-drop, and pointer events.
+3. Check whether the persistence strategy is coherent with the current `praxis-table` runtime mutation model.
+4. Evaluate whether the accessibility plan is sufficient or missing critical keyboard/screen-reader behaviors.
+5. Point out any missing test scenarios, especially conflict cases between resize, reorder, sort, sticky columns, and horizontal scroll.
+6. Flag any assumptions that are too optimistic or likely to create regressions.
+7. Suggest simplifications if the plan is over-engineered for the current codebase.
+
+Expected output:
+
+- Findings first, ordered by severity
+- Then open questions or assumptions
+- Then concrete recommendations
+
+Please be critical. Focus on bugs, regressions, architectural risk, and implementation traps rather than rewriting the plan stylistically.

package/docs/dynamic-filter-architecture-overview.md

@@ -0,0 +1,207 @@
+---
+title: "Dynamic Filter Architecture Overview"
+slug: "dynamic-filter-architecture-overview"
+description: "Visao arquitetural do filtro dinamico no ecossistema Praxis, cobrindo runtime Angular, campos inline, payload enviado e normalizacao no metadata-starter."
+doc_type: "concept"
+document_kind: "host-guide"
+component: "table"
+category: "architecture"
+audience:
+  - "host"
+  - "frontend"
+  - "backend"
+  - "architect"
+level: "advanced"
+status: "active"
+owner: "praxis-ui"
+tags:
+  - "table"
+  - "dynamic-filter"
+  - "dynamic-fields"
+  - "metadata-starter"
+  - "range"
+order: 26
+icon: "account_tree"
+toc: true
+sidebar: true
+search_boost: 1.15
+reading_time: 16
+estimated_setup_time: 35
+version: "1.0"
+related_docs:
+  - "table-overview"
+  - "dynamic-filter-payload-contract"
+  - "dynamic-filter-range-filters-guide"
+  - "dynamic-fields-inline-components-guide"
+keywords:
+  - "praxis-filter"
+  - "GenericFilterDTO"
+  - "RangePayloadNormalizer"
+  - "filter settings"
+source_of_truth:
+  - "projects/praxis-table/src/lib/components/praxis-filter/praxis-filter.component.ts"
+  - "projects/praxis-table/src/lib/services/filter-config.service.ts"
+  - "projects/praxis-table/src/lib/filter-settings/filter-settings.component.ts"
+  - "../praxis-metadata-starter/src/main/java/org/praxisplatform/uischema/filter/web/FilterRequestBodyAdvice.java"
+  - "../praxis-metadata-starter/src/main/java/org/praxisplatform/uischema/filter/range/RangePayloadNormalizer.java"
+  - "../praxis-metadata-starter/src/main/java/org/praxisplatform/uischema/filter/specification/GenericSpecificationsBuilder.java"
+last_updated: "2026-03-07"
+---
+
+# Dynamic Filter Architecture Overview
+
+## Objetivo
+
+Explicar o filtro dinâmico como uma feature transversal do ecossistema Praxis, não como um componente isolado, deixando claro como metadata, UI inline, editor/configuração, payload HTTP e interpretação backend trabalham juntos.
+
+## Pré-requisitos
+
+- Conhecimento básico de `@praxisui/table`, `@praxisui/dynamic-fields` e contratos de `FilterDTO`.
+- Host Angular já integrado com `praxis-filter` e endpoints resource-oriented de filtro do backend.
+- Familiaridade com metadados `controlType`, `@Filterable` e `@UISchema`.
+
+## Quando usar
+
+Use este documento quando precisar:
+
+- entender o fluxo completo do filtro da tabela;
+- planejar documentação funcional para hosts e squads backend;
+- decidir onde documentar variantes inline, settings editor e contratos de range;
+- investigar por que um payload válido na UI vira filtro inválido no backend.
+
+## Visão geral da feature
+
+No Praxis, o filtro dinâmico é uma pipeline de seis etapas:
+
+1. O backend publica um `FilterDTO` anotado com `@Filterable` e `@UISchema`.
+2. O host ou a tabela obtém schema/metadata para montar os campos do filtro.
+3. O `PraxisFilter` decide o layout visível, a variante inline e o modo avançado.
+4. O usuário interage com os campos, e o runtime emite `change`, `submit`, `clear`, `tagsChange` e eventos auxiliares.
+5. O host envia o payload para endpoints como `POST /filter`, `POST /filter/cursor`, `POST /locate` ou `POST /options/filter`.
+6. O `praxis-metadata-starter` normaliza ranges e constrói as predicates JPA a partir do `GenericFilterDTO`.
+
+## Mapa de responsabilidades
+
+### 1. `praxis-table`: runtime de orquestração
+
+`PraxisFilter` é o núcleo do runtime na UI. Ele concentra:
+
+- inputs de configuração e layout, como `alwaysVisibleFields`, `selectedFieldIds`, `allowSaveTags`, `changeDebounceMs` e variantes `useInline*Variant`;
+- outputs que materializam o contrato com o host, principalmente `submit` e `change`;
+- persistência local do estado do DTO e das preferências de exibição com chaves `filter-dto:<key>` e `filter-config:<key>`;
+- heurísticas que convertem `controlType` genérico para inline canônico quando a feature pede experiência compacta.
+
+Esse acoplamento existe em `projects/praxis-table/src/lib/components/praxis-filter/praxis-filter.component.ts` e `projects/praxis-table/src/lib/services/filter-config.service.ts`.
+
+### 2. `praxis-dynamic-fields`: superfície dos controles
+
+Os componentes `filter-*-inline` pertencem ao catálogo de `dynamic-fields`. Eles não definem sozinhos a jornada do filtro; eles implementam o comportamento visual e semântico de cada campo compacto:
+
+- selects inline;
+- async/searchable/entity lookup;
+- intervalos numéricos, monetários, data e hora;
+- controles especializados como rating, radius, pipeline status e score priority.
+
+O contrato corporativo desses campos está em `projects/praxis-dynamic-fields/docs/dynamic-fields-inline-components-guide.md` (slug publicado: `dynamic-fields-inline-components-guide`).
+
+### 3. `filter-settings`: governança editorial e operacional
+
+`filter-settings.component.ts` é a ponte entre metadata, seleção de campos e overrides de UX. É onde o ecossistema define:
+
+- quais campos ficam sempre visíveis;
+- que `controlType` efetivo será usado na toolbar compacta;
+- se a fonte da metadata vem do `filter-dto` ou de `columns`;
+- quais conversões são aceitas para `rangeSlider`, `priceRange`, `dateRange`, `timeRange` e afins.
+
+Em termos de documentação, isso significa que o editor do filtro precisa ser tratado como parte da feature, não como “extra”.
+
+### 4. `praxis-metadata-starter`: normalização e interpretação
+
+No backend, o payload recebido pelo controller não vai direto para a specification.
+
+Antes disso:
+
+- `FilterRequestBodyAdvice` intercepta qualquer request body compatível com `GenericFilterDTO`;
+- `RangePayloadNormalizer` converte objetos e aliases em formato canônico de lista;
+- `GenericSpecificationsBuilder` transforma o valor normalizado em predicates como `BETWEEN`, `BETWEEN_EXCLUSIVE`, `NOT_BETWEEN` e `OUTSIDE_RANGE`.
+
+Isso é o motivo de a documentação do filtro precisar citar explicitamente o `praxis-metadata-starter`.
+
+## Fluxo ponta a ponta
+
+### Etapa 1. Schema e metadata
+
+O backend descreve o filtro com:
+
+- `@Filterable` para a operação semântica;
+- `@UISchema` para `label`, `controlType`, `endpoint`, `numericFormat`, ordem e outras pistas visuais.
+
+### Etapa 2. Resolução da UI
+
+O `PraxisFilter` e o catálogo `dynamic-fields` decidem:
+
+- se o campo vai para a barra compacta ou para a grade;
+- se a variante será inline, dedicada ou avançada;
+- se haverá clear button corporativo, tooltip contextual e presets rápidos.
+
+### Etapa 3. Estado local
+
+O runtime persiste:
+
+- o DTO de filtro em `filter-dto:<key>`;
+- a configuração de layout do filtro em `filter-config:<key>`.
+
+Isso permite restaurar seleção de campos, preferências visuais e estado operacional do filtro.
+
+### Etapa 4. Emissão de payload
+
+No modo avançado, `onAdvancedChange(event)` trabalha sobre `event.formData`. Os eventos `change` e `submit` são o contrato que o host normalmente observa para disparar integração com a API.
+
+Há uma nuance importante já coberta em teste: objeto de range vazio deve ser limpo antes de poluir o payload emitido.
+
+### Etapa 5. Request HTTP
+
+O host envia o DTO para endpoints como:
+
+- `POST /filter`
+- `POST /filter/cursor`
+- `POST /locate`
+- `POST /options/filter`
+
+Todos eles fazem parte da superfície resource-oriented de filtro do metadata-starter.
+
+### Etapa 6. Normalização backend
+
+O backend aceita mais de um shape para intervalos, mas canonicaliza tudo para a lista esperada pelo `FilterDTO` tipado.
+
+Exemplos:
+
+- `{ minPrice: 10, maxPrice: 20 }` vira `[10, 20]`;
+- `{ startDate: "2026-03-01", endDate: "2026-03-31" }` vira `["2026-03-01", "2026-03-31"]`;
+- `[null, 100]` continua representando “somente teto superior”.
+
+## Regras arquiteturais que a doc precisa preservar
+
+1. O filtro é metadata-driven, mas não schema-only.
+   Runtime Angular, overrides do host e normalização backend influenciam o comportamento final.
+
+2. O payload não é só responsabilidade do frontend.
+   O backend canonicaliza ranges aceitos pela plataforma e rejeita payloads inválidos.
+
+3. O editor/configuração faz parte do contrato da feature.
+   Sempre documente `alwaysVisibleFields`, metadata overrides e variantes inline quando o componente depender deles.
+
+4. A documentação deve separar duas perspectivas:
+   - experiência de uso do filtro no contexto da tabela;
+   - contrato técnico dos campos inline e do payload.
+
+## Escopo da trilha documental recomendada
+
+Para documentação extensa e didática, a feature deve ser desdobrada em pelo menos quatro documentos:
+
+- arquitetura geral;
+- contrato de payload;
+- ranges e normalização;
+- catálogo de campos inline e settings editor.
+
+Os três primeiros já passam a existir nesta trilha. O quarto permanece ancorado no guia canônico de inline em `dynamic-fields`.