@praxisui/table 9.0.0-beta.27 → 9.0.0-beta.29

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

@@ -7,7 +7,7 @@ Allow users to resize and move columns in `praxis-table` without conflicting wit
 ## Guiding Principles
 
 - `sort` belongs to a dedicated sortable label/container, not to the entire `th`
-- `reorder` belongs to a dedicated drag handle
+- `reorder` belongs to the draggable header cell, without a permanent move icon
 - `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`
@@ -33,15 +33,17 @@ This is the main reason resize must not be introduced as another gesture on the
 
 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`
+- reorder keyboard parity is attached to the dedicated header sort trigger through Ctrl/Alt + arrows
+- runtime reorder does not render a visible move icon/handle, matching SAP Fiori and MUI Data Grid patterns
 - 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
+- reorder is implicit on the draggable header cell, matching enterprise grids such as SAP Fiori and MUI Data Grid
+- the current `cdkDrag` root remains on the `th` so preview, placeholder sizing, and index semantics stay stable
+- `mat-sort-header` is mounted on `.praxis-header-sort-trigger`, not on the full `th`, so sort remains a focused label interaction while header drag remains available
+- keyboard reorder belongs to the focused header sort trigger via Ctrl/Alt + arrow keys
 
 The plan must explicitly unwind those couplings instead of treating them as incidental details.
 
@@ -52,37 +54,32 @@ The plan must explicitly unwind those couplings instead of treating them as inci
 Refactor the header so each interaction has an explicit zone:
 
 - sortable label container: sort
-- drag icon/handle: reorder
+- draggable header cell: reorder, with no permanent move icon
 - 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`
+- add a sortable wrapper `.praxis-header-sort-trigger`
 - 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
+- do not render a visible reorder icon/handle in the runtime header
+- add `.praxis-column-resize-handle`
+- keep keyboard reorder on the header sort trigger without blocking sort Enter/Space behavior
+- ensure the resize handle stops `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
+- treat suppression of `click` on resize handles as a hard requirement, not a best-effort safeguard
 
 ### Phase 2: Add Runtime Resize State
 
@@ -125,7 +122,7 @@ On resize start:
 
 Behavioral rule:
 
-- dragging only starts from the reorder handle
+- dragging starts from the header cell, except the resize handle and sortable label interactions
 - sorting only starts from the dedicated sortable label/container
 - resizing only starts from the right-edge resize handle
 
@@ -151,6 +148,12 @@ 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`
+- resizing changes the internal table content width, not the host/card/viewport width
+- when the summed column widths exceed the viewport, the scroll container owns horizontal overflow
+- when the summed column widths are smaller than the viewport, empty space may remain after the last column instead of redistributing widths implicitly
+- do not resize neighboring columns in `px` mode; the resized column changes and following columns move accordingly
+- when resize is enabled, persisted `px` widths below the effective readable minimum are normalized back into `config.columns[]`, not only corrected during rendering
+- the effective readable minimum includes the column header text, the resize separator gutter, and the sort gutter only when that concrete column is sortable
 - 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
@@ -186,9 +189,10 @@ 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
+- keyboard resize commits stepwise on each handled key event
+- keyboard resize uses `ArrowLeft`, `ArrowRight`, `Shift + Arrow`, `Home`, and `End`
 - define stale-callback protection for resize and reorder through the same shared coordinator
+- derived table width used during/after resize must be cleared when the visible column contract changes externally
 - 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:
@@ -240,16 +244,18 @@ Resize handle:
 
 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
+- `ArrowLeft` and `ArrowRight` resize by the default step
+- `Shift + ArrowLeft` and `Shift + ArrowRight` resize by the larger step
+- `Home` applies the configured minimum width
+- `End` applies the configured maximum width when one is configured
+- `Escape` cancels an active pointer resize before commit
+- keyboard resize commits stepwise on each handled key event
 
-Reorder handle:
+Reorder accessibility:
 
-- 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`
+- keep keyboard reorder on the focused header sort trigger with Alt/Ctrl + arrow keys
+- do not add a permanent focusable move icon unless a future accessibility review proves the header-trigger model insufficient
+- preserve visible focus styling and screen-reader parity on the header label/sort trigger
 
 ### Phase 8: Testing
 
@@ -260,7 +266,7 @@ Add focused tests for interaction conflicts:
 - 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`
+- reorder still works through the draggable header cell
 - keyboard reorder still works after moving intent to the handle
 - sort keyboard interaction still works after sort leaves the `th`
 
@@ -300,18 +306,18 @@ Add visual/e2e coverage later:
 ## 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
+2. Keep reorder implicit on the header and remove stale move-icon guidance from docs/editor copy
+3. Add resize handle with pointer support, keyboard support, and explicit cancel paths
+4. Validate sticky and horizontal-scroll behavior in a follow-up hardening 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
+8. Add broader sticky, horizontal-scroll, and non-data-column E2E coverage
 9. Enable only through config/feature flag
 
 ## Definition of Done
 
-- users can reorder only from the drag handle
+- users can reorder from the header without a permanent move icon
 - 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
@@ -326,6 +332,8 @@ Add visual/e2e coverage later:
 - 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
+- table-level width is runtime-derived state; it must not outlive the column contract that produced it
+- the canonical enterprise default follows the SAP/MUI model for fixed-width columns: resize the column and the internal content width, keep the outer viewport stable, and use horizontal overflow when needed
 
 ## Suggested Follow-Up