List View Component

GitHub Ticket: https://github.com/Arda-cards/management/issues/565

Summary

Extract a reusable, generic List View (data grid) component from the existing ArdaItemsDataGrid and ArdaSupplierDataGrid organisms in the UX Prototype. The two organisms are ~95% structurally identical — the only genuine differences are the entity type, the ID field name, and domain-specific column definitions and cell renderers. This project eliminates the duplication and establishes a pattern for creating new entity grids with minimal boilerplate.

Motivation

Every new entity grid (Orders, Locations, Purchase Orders, etc.) currently requires copying ~250 lines of boilerplate that only differs in the entity type, ID field, and column definitions. The refactoring produces a factory function that lets new entity grids be defined in under 30 lines.

Current State

The Items and Suppliers data grids share:

Identical forwardRef component structure with the same 7 hooks
Identical interface shapes (StaticConfig, RuntimeConfig, Ref) — differing only in entity type
Identical dirty-tracking logic (unsaved changes, save/discard via ref API)
Identical four-step column pipeline (base defs → visibility → ordering → editing)
Identical ArdaDataGrid<T> render props
Identical column preset export shapes and default column definitions
Identical test structure (8 test cases) and story structure (7 stories)

Key differences are limited to:

Entity type (Item vs BusinessAffiliate) and identity field (entityId vs eId)
Domain-specific column definitions (25 columns for Items, 12 for Suppliers)
Domain-specific cell renderers and editable field sets

Target State

A createArdaEntityDataGrid<T>() factory function encapsulating all shared logic
ArdaItemsDataGrid and ArdaSupplierDataGrid become thin wrappers (~20–30 lines each) supplying entity-specific configuration
Shared cell renderers (select column, notes icon, quick-actions placeholder) extracted to a common presets module
Common column utilities (COMMON_DEFAULT_COL_DEF, createSelectColumn, createNotesColumn, createQuickActionsColumn)
A documented pattern for creating new entity grids

Design Decisions

Decision	Choice	Rationale
Factory function vs generic component	Factory function	Matches existing `createSelectCellEditor` / `createTypeaheadCellEditor` patterns; produces concrete types for Storybook `Meta<typeof>`
Factory module placement	Organisms layer (`organisms/shared/`)	Factory produces organism-level components
Common cell renderers	Extract generic versions, entity wrappers for divergence	Generic accepts `notes?: string` directly; entity-specific wrappers can diverge later
Entity-specific prop names	Preserve (`items`, `onItemUpdated`)	Factory uses generic names internally; thin wrappers re-map for call-site clarity
Breaking changes	Allowed (prototype stage)	No external consumers; maximize abstraction cleanliness

Additional Requirements

Create component classification guidelines (Atom, Molecule, Organism) with examples and edge cases
Create organisms/shared/ structure for cross-entity shared components, and use-case-specific structure following the Reference/Resources domain grouping
Separate component configuration properties into Domain/Data concerns vs Layout/View/Controller concerns across all lifecycle phases (Design, Initialization, Runtime) — refactor all existing components to follow this convention

Scope

In scope: Extract shared logic, shared cell renderers, shared column utilities; refactor both existing organisms; migrate tests and stories; update exports.

Out of scope: Changes to the underlying ArdaDataGrid<T> molecule, domain-specific column/renderer changes, new grid features, AG Grid configuration or theming changes.

References

Analysis: /workspace/projects/ad-hoc/ux-prototype/list-view-component/previous-work/analysis.md
Refactoring plan: /workspace/projects/ad-hoc/ux-prototype/list-view-component/previous-work/plan.md
Design session: /workspace/projects/ad-hoc/ux-prototype/list-view-component/design-session-1.md
Use cases: GEN::LST heading in /documentation/src/content/docs/product/use-cases/