Skip to content

feat(line-items): LineItems component - #710

Draft
IzumiSy wants to merge 5 commits into
mainfrom
feat/line-items-2427
Draft

IzumiSy wants to merge 5 commits into
mainfrom
feat/line-items-2427

Conversation

@IzumiSy

@IzumiSy IzumiSy commented Nov 11, 2026 •

Copy link
Copy Markdown
Contributor

Motivation

Transactional documents need a reusable line editor with consistent local editing and net change tracking, rather than a separate implementation in each application. Consumers should retain ownership of domain rules, document-wide validation, data loading, and persistence.

This is the integration feature PR for the initial LineItems milestone, targeting main. Requirements: platform-planning #2427. The issue's scope takes precedence over earlier LineItems explorations.

Summary

  • Carry forward shared value renderers and DataTable compatibility adapters, with no new implementation changes for this integration branch.
  • Include the existing LineItems table and hook, row identity, local field/add/remove commands, dirty-state inspection, discard, and drag/keyboard ordering groundwork.
  • Include built-in text, number, fixed-choice, and date cell editing, async consumer validation, retained cell drafts, and readonly/editable composition.
  • Include the existing public exports, showcase, and regression/type tests.
  • Use the linked issue to track the complete initial milestone. Remaining milestone work, consumer documentation, and release preparation are not completed by opening this Draft PR.

Included PRs

Initial milestone coverage

Copied from platform-planning #2427 and assessed against 5915625 (the current PR head). Requirement wording and nested acceptance criteria are preserved; the added Coverage bullets describe this branch rather than changing the source requirements. The issue's scope boundaries remain authoritative.

11 / 43 implemented; 17 partial; 15 not implemented. Partial requirements stay unchecked. A checked standalone requirement does not imply that the entire save/changeset flow is complete. In particular, isDirty is not a consumer-readable changeset.

Primary implementation evidence: public hook contract, document model/baseline, cell commit/validation, closed editor catalog, ordering UI, and numeric blur behavior.

Assessment validation: focused LineItems/shared-table-core tests passed (33 files, 413 tests; no reported type errors) locally at 9556c1f. The subsequent merge into PR head 5915625 changes documentation/docs tooling only, not package or showcase implementation. Browser/device interactions, the full repository suite, and an end-to-end save flow were not run. This is an implementation-coverage audit, not a claim that every acceptance scenario has a dedicated test.

Remaining feature areas

  • Editing: boolean/custom editors, server-backed cell selection, complete rejected-input retention, and precision-safe validation.
  • Filtering and bulk actions: per-column text search, selection/select-all, filter-aware selection, and consumer action execution.
  • Changesets: custom column equality and a read-only net diff of additions, field updates/clears, removals, and order changes.
  • Ordering: business sorting, filter/save restrictions, and touch-accessible manual ordering (including a non-drag alternative).
  • Save lifecycle: confirm/validate all drafts before save, prevent user mutations during saving, replace the complete collection/baseline with confirmed data, transition temporary IDs, and verify failure/retry behavior.
  • Composition/integration: complete header/multi-collection save coordination and preservation/change inspection for filtered-out rows using the APIs above.

1. Display and Cell Editing

  • LI-01 Display application-defined line-item fields and calculated values in a table, without procurement, sales, or other domain-specific assumptions.

    • Coverage — Implemented: Generic property, computed-value, and custom display columns are available; no domain-specific row model is imposed.
  • LI-02 Support text, number, fixed-choice, and date editing. Text editing includes free-form fields such as notes.

    • Coverage — Implemented: Built-in text, number, fixed-choice combobox, and date editors are implemented. Text fields use the same editing lifecycle regardless of their business meaning.
  • LI-03 Support boolean editing.

    • Coverage — Missing: No integrated boolean editor is registered.
  • LI-32 Support consumer-provided custom cell editors.

    • Coverage — Missing: Custom display renderers are supported, but a consumer-provided editor contract is not public; the editor catalog is closed.
  • LI-33 Support server-backed option lookup when selecting a value within an existing line.

    • Coverage — Missing: Combobox options are a fixed array. There is no server-backed option lookup/fetcher contract.
  • LI-34 Integrate custom editors with the same commit, validation, editability, save preparation, and change-tracking rules as built-in editors.

    • Coverage — Missing: Requires the public custom-editor integration plus the pending save-preparation and changeset APIs.
  • LI-05 Reject invalid cell input, preserve the rejected input, show validation feedback, and allow correction and retry.

    • Coverage — Partial: Consumer validation failures retain drafts and support feedback/retry. However, malformed numeric input is canceled on blur, so rejected input is not always preserved.
  • LI-35 Keep a server-backed selector's search query separate from its committed cell value.

    • Typing a query and loading candidates do not change the committed value or produce a field change.
    • Change the value only after a selection is successfully committed and validated.
    • Preserve the existing value when the user cancels or the search fails.
    • Do not clear the existing value merely because it is absent from the current search results.
    • Coverage — Partial: The fixed-choice editor separates its query from the committed value. Server-backed loading, failure, cancellation, and changing-result behavior remain unimplemented.

2. Local Editing, Equality, and Permissions

  • LI-04 Let consumers add and remove lines, reflecting those operations in the local document and its change tracking.

    • Coverage — Implemented: addLine/removeLine update the in-memory document and net dirty state. Distinct addition/removal reporting remains tracked by LI-08.
  • LI-06 Discard unsaved field edits, additions, removals, and order changes, restoring the saved baseline. Discard pending cell drafts as part of this operation.

    • Coverage — Implemented: revert restores persisted baseline values, membership, and order; it also cancels pending cell sessions, including in-flight validation adoption.
  • LI-11 Allow consumers to provide custom equality logic at the column level.

    • Use the same equality rules for change detection and changeset generation.
    • Compare saved baseline values with current committed values.
    • Equality checks do not modify, normalize, or round the stored values.
    • Do not infer equality solely from formatted display text.
    • Coverage — Missing: Column-level equality configuration is absent. Current dirty detection uses Object.is; no changeset API exists yet.
  • LI-26 Support consumer-supplied currency- and unit-of-measure-specific decimal precision constraints.

    • Keep display precision separate from input constraints.
    • Reject input that exceeds the applicable precision, preserving it with validation feedback.
    • Do not silently round an out-of-precision value to make it valid.
    • Coverage — Partial: Display formatting is separate from editing, and onValueCommitted can reject consumer-defined numeric values. Raw-draft precision constraints are not provided: conversion to a JavaScript number happens before validation, so excess precision can be lost. Precision-specific rejection/retention still needs implementation and verification.
  • LI-14 Let consumers provide predicates controlling column editability, sorting, and actions.

    • Do not encode document-specific lifecycle states such as draft, ordered, or posted in LineItems.
    • Apply these permissions alongside the restrictions for active filtering and in-progress saves.
    • Changing availability does not discard committed values or tracked changes.
    • Treat these controls as UI policy, not a substitute for backend authorization.
    • Coverage — Partial: Per-column canEdit(row), the orderer boolean, and consumer-owned action controls exist. Business sorting and the combined filtering/save restrictions do not.
  • LI-07 Allow consumers to compose readonly, editable, and restricted-editing views through those controls. Keep locked fields visible for reference rather than hiding them solely because they cannot be edited.

    • Coverage — Implemented: Consumers can compose readonly/editable/restricted fields with edit/canEdit, orderer, and their own action UI; locked fields stay visible and committed edits survive mode changes. The additional policy integration is tracked by LI-14/31/40.

3. Existing-Line Filtering

  • LI-29 Filter existing lines incrementally using a single text query.
    • Configure participation through each column's search property; the detailed signature remains unspecified.
    • Exclude columns without search configuration.
    • Display a row when any participating column matches the query: OR across columns.
    • Update the displayed items as the query changes.
    • An empty query means no filtering and displays all items.
    • A query with no matches displays no items.
    • Preserve the current document order within the filtered results.
    • Filtering itself is not a document edit and does not change the saved baseline.
    • Coverage — Missing: No per-column search configuration, query state, or existing-line filtering is exposed.

4. Selection and Consumer-Defined Actions

  • LI-21 Support optional multi-row selection and consumer-defined bulk updates.

    • Coverage — Missing: No multi-row selection state or bulk-action entry point is implemented.
  • LI-22 Support consumer-defined deletion of multiple selected rows. Let consumers enable or disable bulk operations according to their workflow.

    • Coverage — Missing: Single-row removal exists; selected-row deletion and bulk-operation controls do not.
  • LI-36 Deselect rows that no longer match the active filter. Bulk operations apply only to the remaining selected rows.

    • Coverage — Missing: Depends on the unimplemented selection and existing-line filtering features.
  • LI-37 Select all items in the current result set, not just rows currently rendered or inside the viewport.

    • With an active query, select all matching items held by LineItems.
    • With no query, select all items held by LineItems.
    • If no items match, select nothing.
    • Coverage — Missing: No select-all/result-set selection API or UI exists.
  • LI-38 Let consumers define the behavior of actions on selected rows.

    • LineItems provides selection and an execution entry point, not domain-specific action implementations.
    • Track resulting line changes through the normal changeset mechanism.
    • Executing a bulk action does not automatically persist changes.
    • Coverage — Missing: Consumers can invoke individual row commands, but there is no selected-row action execution contract. Resulting changeset reporting is also pending.

5. Document Order

  • LI-17 Support manual reordering through dragging and keyboard controls.

    • Coverage — Partial: Native desktop dragging and ArrowUp/ArrowDown reordering are implemented with stable identity/focus handling. The issue's LI-17 follow-up also requires touch dragging, a touch-accessible non-drag alternative, shared restrictions, and browser/representative-device verification; those remain open. See the touch-reordering follow-up.
  • LI-19 Support consumer-defined business sorting, including ordering that differs from alphabetical labels, such as XS → S → M → L.

    • Coverage — Missing: No consumer-defined business sort/comparator operation is exposed.
  • LI-39 Treat sorting and manual reordering as operations on the same document order.

    • Sorting changes the order once; it is not continuously reapplied.
    • Subsequent field edits do not automatically reorder rows.
    • Do not maintain a separate temporary display order.
    • Include net order changes in the changeset regardless of how they were made.
    • A sort performed only for inspection still contributes an order change; the consumer decides whether to persist it.
    • Coverage — Partial: Manual movement changes the actual document order and contributes to net isDirty. Business sorting and inspectable net order changes in a changeset remain missing.
  • LI-40 Disable sorting and manual reordering while a search query is active.

    • Apply the restriction to drag and keyboard reordering as well as sorting controls.
    • Filtering does not undo a previous sort or manual reorder.
    • Clearing the query reveals all items in the current document order, including unsaved order changes, and restores ordering controls subject to consumer permissions.
    • Coverage — Missing: Manual movement respects orderer, but active-query filtering and its ordering restrictions do not exist; sorting is also absent.
  • LI-18 Make the final document order available for persistence and restoration, including the placement of newly added lines.

    • Coverage — Implemented: The public lines array exposes the current complete document order, including newly added rows, for consumer persistence and initialization/restoration. Post-save in-place baseline replacement is tracked separately by LI-12.

6. Changeset Inspection

  • LI-08 Make additions, field updates, removals, and order changes available to the consumer as distinct changes. Exclude unchanged lines, unchanged fields, and empty updates.

    • Coverage — Missing: The public API exposes current lines and isDirty only, not distinct additions, field updates, removals, or order changes.
  • LI-09 Distinguish an untouched field from an explicitly cleared value when reporting changes.

    • Coverage — Partial: Clears can adopt explicit null/undefined or a configured clear value. There is no field-change report distinguishing a clear from an untouched/omitted field.
  • LI-10 Report no field change when the user only focuses a cell, re-enters an equivalent value, or restores the original value. Let consumers skip unnecessary line persistence when there are no net line changes.

    • Coverage — Partial: Focus/unconfirmed drafts do not dirty committed rows, and equivalent/restored values can return isDirty to false. Per-field change reporting and consumer-defined equality are still missing.
  • LI-41 Expose current changes independently of any save action, using committed cell values only.

    • Do not include unconfirmed drafts or values whose commit failed.
    • Reading changes does not commit input, run validation, persist data, clear changes, or advance the baseline.
    • Change inspection neither triggers nor requires successful document-wide validation.
    • Committed changes remain inspectable even when the document as a whole is not valid for saving.
    • An empty changeset does not imply that there are no pending cell drafts.
    • Coverage — Partial: Reading lines/isDirty is side-effect-free and excludes pending/rejected drafts. A consumer-readable current changeset is not implemented.
  • LI-42 Make the complete consumer-provided data available for added lines, including readonly and non-displayed fields. The consumer selects and maps the data needed for persistence.

    • Coverage — Implemented: addLine retains the complete supplied row, including readonly/non-displayed fields, except the persisted identity deliberately removed for a new creation. Full data is available through lines; a separate additions payload remains LI-08.
  • LI-43 Produce the net difference between the saved baseline and current committed state, rather than an operation history.

    • Changing a value from 10 → 20 → 30 reports only the change to 30.
    • Changing a value from 10 → 20 → 10 reports no change.
    • Adding and then removing a new line reports no change.
    • Editing and then removing an existing line reports a removal only.
    • Restoring the original line order reports no order change.
    • Coverage — Partial: Net dirty detection already cancels restored values, add/remove pairs, and restored order. It does not expose the requested net-difference payload.
  • LI-44 Treat notes and other editable fields under the same change-tracking rules. LineItems does not assign them an independent persistence lifecycle; the consumer decides how to handle their changes.

    • Coverage — Implemented: Notes have no special persistence lifecycle: ordinary text/property fields share the same commit, validation, and dirty-tracking path. Structured change output for all fields remains LI-08/43.

7. Save Preparation and Save Results

  • LI-30 Confirm and validate pending cell edits before saving.

    • Start persistence only after cell confirmation and validation succeed and the consumer's document-wide checks allow saving.
    • If confirmation or validation fails, do not start persistence; preserve the input with feedback for correction.
    • Keep this save-preparation behavior separate from read-only changeset inspection.
    • Coverage — Partial: Individual cells confirm/validate before adoption, including async checks. There is no public operation to confirm all pending drafts, await them, and report readiness/failure before a document save.
  • LI-31 Prevent user changes to line items while a document save is in progress.

    • Disable field editing, line addition, line removal, sorting, and manual reordering.
    • On completion, allow editing again subject to consumer permissions.
    • Coverage — Partial: Consumers can compose canEdit, orderer, and disabled action buttons with external save state. A complete save-in-progress restriction across supported/future operations, including pending validation and sorting, is not implemented or verified.
  • LI-12 Let the consumer replace the full line collection with confirmed data after a successful save.

    • Adopt that data as both the current state and the new saved baseline.
    • Subsequent change inspection and discarding use the new baseline.
    • The consumer may obtain the confirmed collection from the save response, a refetch, or its own reconstruction; the save endpoint need not return the full collection.
    • Coverage — Missing: defaultLines is initialization-only and the baseline is fixed for the hook lifetime. No full-collection replacement/new-baseline method exists.
  • LI-13 Transition newly saved lines from temporary client identity to their confirmed server identity through the full-collection replacement.

    • Do not treat temporary identity as a confirmed server ID.
    • Subsequent edits and removals target the saved line rather than producing another addition.
    • Coverage — Partial: New rows have separate temporary client keys and supplied persisted IDs are removed. Adopting confirmed server identities through full-collection replacement is not implemented.
  • LI-45 On a failed save, retain unsaved changes and the existing saved baseline. Allow the user to edit and retry.

    • Coverage — Partial: There is no automatic persistence or baseline advancement, so an external request failure alone does not reset local state. The coordinated save/failure/unlock/retry flow is not yet implemented and verified.
  • LI-46 Keep persistence timing, transport, mutation mapping, and result handling in the consumer. Neither changeset inspection nor local editing automatically performs backend persistence.

    • Coverage — Implemented: Editing and inspection are local-only. Consumers own loading/persistence, request timing, transport, mutation mapping, and result handling.

8. Document-Level Composition

  • LI-23 Let consumers combine line changes with header changes for a document-level save. Header state, cross-field business rules, transaction execution, and backend validation remain consumer/backend responsibilities.

    • Coverage — Partial: The local hook is composable with consumer-owned header state and transport. Combining an inspectable line changeset with header changes and preparing pending drafts for save are blocked by LI-08/30.
  • LI-24 Let consumers compose multiple LineItems instances under one document, such as debits and credits or components and operations.

    • Each instance manages one line collection.
    • The consumer coordinates saving, no-change detection, discarding, and post-save baseline updates across collections.
    • Cross-collection and header-level validation belongs to the consumer.
    • A dedicated grouping API is not required by this checklist.
    • Coverage — Partial: Independent hook/store instances already support separate collections with no grouping API. Full consumer coordination of changesets, save preparation, and post-save baseline replacement still depends on LI-08/30/12.

9. Data Ownership and Scale

  • LI-47 Keep the full consumer-provided line collection in memory. The consumer obtains the complete collection before providing it to LineItems.

    • Coverage — Implemented: All consumer-provided rows are retained in the in-memory document; no server paging or incremental line loader is introduced.
  • LI-25 Never interpret filtering or the absence of rendered rows as deletion. Preserve values and pending changes for hidden rows and include their committed changes in changeset inspection.

    • Coverage — Partial: Complete rows and non-displayed fields are retained and display-column reconfiguration does not delete rows. Hidden filtered-row preservation and inclusion in change inspection need the missing filtering/changeset features.
  • LI-48 Do not impose a fixed maximum line count. Revisit data-volume and rendering optimizations when practical usage demonstrates a need.

    • Coverage — Implemented: No fixed row-count cap is enforced. This is not a large-document performance guarantee.

No fixed performance guarantee at 500 or 10,000 rows is part of the initial acceptance criteria. The absence of a row-count cap does not imply guaranteed performance for arbitrarily large documents.

@IzumiSy
IzumiSy force-pushed the feat/line-items-2427 branch from 7bcf578 to f627936 Compare November 11, 2026 03:15
@github-actions

Copy link
Copy Markdown
Contributor

Code Metrics Report

main (e2240e3) #710 (23c8131) +/-
Coverage 90.3% 90.3% 0.0%
Test Execution Time 3m41s 2m48s -53s
Details
  |                     | main (e2240e3) | #710 (23c8131) | +/-  |
  |---------------------|----------------|----------------|------|
  | Coverage            |          90.3% |          90.3% | 0.0% |
  |   Files             |            284 |            284 |    0 |
  |   Lines             |           8333 |           8333 |    0 |
  |   Covered           |           7529 |           7529 |    0 |
+ | Test Execution Time |          3m41s |          2m48s | -53s |

Reported by octocov

)

* refactor(table-core): extract neutral value renderers

* feat(line-items): add internal readonly display

* feat(line-items): add document commands and manual ordering (#679)

* feat(line-items): add internal readonly display

* feat(line-items): add document state and manual ordering

* docs(line-items): clarify the document store contract

* refactor(line-items): separate document model and store concerns

* feat(line-items): expose reorderable table and showcase

* feat(examples): demonstrate line-item row commands

* Fix document drift

* fix(line-items): move example actions below the table

* refactor(line-items): group document model and types

* Move function

* refactor(line-items): remove reorder announcements

* fix(line-items): make document identity types explicit

* fix(line-items): preserve stable client keys in row interactions
@IzumiSy IzumiSy changed the title feat(line-items): integrate the initial LineItems milestone feat(line-items): LineItems component Nov 11, 2026
* feat(line-items): add cell editing with shared table core

* feat(line-items): configure column widths and enable editable showcase

* feat(line-items): add date and readonly modes to showcase

* feat(line-items): demonstrate validation and computed totals

* refactor(data-table): import shared table helpers directly

* test(table-core): colocate input value helper coverage

* perf(line-items): cache row lookups by document snapshot

* fix(line-items): preserve links in readonly editable cells

* refactor(line-items): drop live editor replacement handling

* refactor(table-core): separate cell presentation from editor controls

* refactor(line-items): separate column validation from reconciliation

* refactor(table-core): inject editors and prepare renderers by column

* refactor(line-items): derive editor contracts and dispatch from adapters

* test(line-items): align editing fixture with optional identity

* refactor(table-core): bind display and editor dependencies in adapters

* refactor(table-core): colocate date-time draft with date editor

* refactor(line-items): make headless editor definitions the source of truth

* refactor(line-items): group editor settings under editorOptions

* fix(line-items): retain cell sessions when rebinding columns

* test(table-core): colocate cell editing session hook tests

* feat(line-items): unify renderers and expose calendar restrictions

* fix(showcase): use an icon button for line item deletion

* fix(line-items): remove drag handle column padding

* refactor(table-core): align display adapter contracts

* refactor(data-table): remove date-time draft compatibility exports

* feat(line-items): add column presentation props

* fix(line-items): retain editing handle across copied hook values

* fix(data-table): restore DateTimeDraft type exports

* fix(line-items): present retained drafts and remember error dismissal

* fix(line-items): correlate fixed choices with property enums

* fix(line-items): preserve raw values for typed choice displays

* fix(line-items): reject current edits refused during adoption

* feat(line-items): define property-safe clear value policies

* fix(line-items): always check confirmed values before adoption

* fix(table-core): separate error messages from accessible hints

* fix(line-items): make badge label ownership exclusive

* fix(line-items): align readonly cells in icon-bearing columns

* fix(line-items): normalize choice label lookup consistently

* fix(line-items): call custom renderers with only their row

* fix(showcase): display fractional line item quantities

* fix(line-items): keep editing handles opaque in public declarations

* fix(showcase): use consumer utilities for line item styling

* fix(line-items): reduce draft status noise while typing

* docs(data-table): restore DateTimeDraft export documentation
@IzumiSy

IzumiSy commented Nov 18, 2026

Copy link
Copy Markdown
Contributor Author

@copilot resolve the merge conflicts in this pull request

# Conflicts:
#	docs-manifest.json

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>

Copilot AI commented Nov 18, 2026

Copy link
Copy Markdown
Contributor

@copilot resolve the merge conflicts in this pull request

Resolved the conflict and merged main in 9556c1f. The docs sync/check and workspace type-check passed.

@IzumiSy

IzumiSy commented Nov 18, 2026

Copy link
Copy Markdown
Contributor Author

@copilot resolve the merge conflicts in this pull request

# Conflicts:
#	docs-manifest.json

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>

Copilot AI commented Nov 18, 2026

Copy link
Copy Markdown
Contributor

@copilot resolve the merge conflicts in this pull request

Resolved the conflict and merged the latest main in 5915625. The docs check and workspace type-check passed.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants