Basic

Use cases and scenarios for the GEN::LST (List Views) area. These behaviors define the cross-cutting interaction contract shared by all entity list views in the application — Items, Purchase Orders, Kanban Cards, and every other entity grid. Any list view that departs from these patterns must document the deviation explicitly in its own domain area.

Standard user story: As a user, I want to be able to list all entities of a particular type (e.g. Items, Orders, Cards) so that I can act on one or multiple of them.

GEN::LST::0001 — Navigate to Entity List

Display a list of entities from a given context with initial column configuration applied. The context determines which records are in scope; preferences determine which columns are visible.

Persona	Irene Itemsworth (Inventory Manager), Sam Scansworth (Shop Floor Worker), David Dealsworth (Purchasing Manager), Keisha Clerkson (Receiving Clerk), Owen Ownerton (Business Principal), Alan Adminson (Account Admin)
Depends	OAM::CFG (preference storage)
Priority	MVP2-A
Status	Covered

GEN::LST::0001::0001.US — Navigate from Top-Level Navigation

The user navigates to an entity list from the application’s main navigation — for example, the Items List or Purchase Orders page in the sidebar. The full set of entity instances visible to the user’s tenant is in scope.

GEN::LST::0001::0002.US — Navigate from Local Context

The user navigates to a contextual subset of entities. The context constrains the result set to a logical grouping — for example, the Order Lines belonging to a specific Purchase Order, or the Kanban Cards in a given lifecycle state within the Order Queue. The list column configuration and available actions may differ from the top-level view of the same entity type.

GEN::LST::0001::0003.FS — Apply Initial Display Preferences

On list load, the system retrieves the active tenant or user preference for this entity type and applies the stored column visibility and column order. When no stored preference exists, the system falls back to the entity-specific business-requirement-driven default column set and order. The default is defined per entity type based on frequency of use. This scenario crosses OAM::CFG for preference storage and retrieval.

GEN::LST::0002 — Configure List Column Display

The user manages which columns are shown in the list and their left-to-right order. Column configuration is persisted so that it survives page reloads and cross-session returns.

Persona	Irene Itemsworth (Inventory Manager)
Depends	OAM::CFG (preference persistence)
Priority	High
Status	Covered

GEN::LST::0002::0001.US — Show or Hide Columns

The user opens the column selector and toggles individual columns on or off. The set of available columns is defined per entity type and includes all columns that the application supports for that entity, whether or not they are currently visible. Only the columns the user enables are rendered in the grid.

GEN::LST::0002::0002.US — Reorder Columns

The user drags a column header to a new horizontal position. The column moves to the target position after the drag completes. The drag ghost image has opacity: 0, so there is no visible drag preview during the drag operation; the new order is visible once the drag is released. The updated column order is saved to localStorage under a key specific to the active tab (e.g., Published, Draft, Recently Uploaded) and persists across page reloads.

GEN::LST::0002::0003.FS — Persist Column Configuration

The system persists column visibility, column order, and column widths per tab via AG Grid’s onColumnVisible, onColumnMoved, onColumnResized, and onSortChanged events. The localStorage key is specific to each tab so that changes on one tab do not affect another tab’s column state. State is restored automatically the next time the user visits the list. Column widths are adjusted by dragging the right edge of a column header; the updated width is saved by the same persistence mechanism.

GEN::LST::0002::0004.FS — Apply Default Column Order

When no stored preference exists for a given tab and entity type, the system applies the business-requirement-driven default column order. Defaults are determined per entity type based on frequency of use and are not user-configurable at the individual-column level without triggering a preference save.

GEN::LST::0002::0005.US — Resize Column Width

The user drags the right edge of a column header to resize it. The new width is persisted alongside other column preferences via GEN::LST::0002::0003. Double-clicking the column edge auto-sizes the column to fit its widest visible cell value.

GEN::LST::0002::0006.US — Pin Column Left or Right

The user pins a column to the left or right edge of the grid via the column menu or by dragging. Pinned columns remain visible while horizontal scrolling affects only unpinned columns. This is valuable for keeping identifier columns (e.g., Item Name, PO Number) in view. Pinned state is persisted via GEN::LST::0002::0003.

GEN::LST::0002::0007.US — Auto-Size All Columns

The user triggers “Auto-Size All Columns” from the column menu or toolbar. Each column width is adjusted to fit the widest visible cell value plus header text, using the rendered content from GEN::LST::0010 to measure pixel widths. This provides a one-click layout reset.

GEN::LST::0003 — Filter Entity List

Reduce the rows displayed in the list based on filter criteria. Three independent filter mechanisms are available: a global text filter, per-column filters, and an advanced compound filter. The final result set is the AND composition of all three.

Priority	MVP2-A
Status	Covered

GEN::LST::0003::0001.US — Apply Global Text Filter

The user types into the global filter input. The system matches the input value case-insensitively against a predefined subset of columns for the entity type. Only rows where at least one of those columns matches are shown. The global filter input is always accessible regardless of which columns are currently visible.

GEN::LST::0003::0002.FS — Apply Column Filter — Text

A text column filter matches the regular expression ($i).*{input}.*, which is a case-insensitive match of the input value anywhere within the field. The filter is accessible via the AG Grid column menu. Multiple text column filters across different columns combine using AND logic — a row must satisfy all active column filters to appear. Clearing a filter restores the full row set for that column’s contribution.

GEN::LST::0003::0003.FS — Apply Column Filter — Numeric

A numeric column filter matches rows where the column value equals the entered number with a precision tolerance of 1e-18. This accommodates floating-point representation without requiring exact binary equality.

GEN::LST::0003::0004.FS — Apply Column Filter — Boolean

A boolean column filter uses strict equality. The filter presents two options (true / false) and matches only rows where the column value equals the selected option exactly.

GEN::LST::0003::0005.FS — Apply Column Filter — Date

A date column filter matches rows where the stored date falls within plus or minus 12 hours of the entered date value, evaluated in the record’s timezone. This window accommodates date-only inputs where the time component is ambiguous.

GEN::LST::0003::0006.FS — Apply Column Filter — Enumeration

An enumeration column filter uses strict string equality with the canonical values published by the backend for each enumeration type. The filter presents the set of valid enum values as selectable options. Matching is case-sensitive and must use the exact backend-published string.

GEN::LST::0003::0007.FS — Apply Column Filter — String-like Types

URL, UUID, email, and phone column filters use strict string equality. These types look like strings but carry semantic constraints; therefore partial matching or regex matching is not applied. The user must enter the exact value to match.

GEN::LST::0003::0008.US — Apply Advanced Filter with Conditions

The user opens the advanced filter panel and builds compound filter conditions. Available operators depend on the column data type: equality, greater-than, greater-than-or-equal, less-than, less-than-or-equal, ranges, and case-insensitive regex for text columns. Conditions are composed using AND and OR logic. The advanced filter operates independently from the global filter and column filters; its result contributes to the final AND composition.

GEN::LST::0003::0009.FS — Compose Final Filter

The system computes the final visible row set as the AND of three independent filter contributions: the global text filter result, the combined column filter result, and the advanced filter result. A row is displayed only when it satisfies all three contributions simultaneously. Clearing any one filter contribution does not affect the others.

GEN::LST::0004 — Sort Entity List

Order the displayed rows by column values. Sorting applies to the result set after filtering; the sort does not alter which rows are visible, only their order.

Priority	MVP2-A
Status	Covered

GEN::LST::0004::0001.US — Sort by Single Column

The user clicks a column header to sort the list by that column. The first click sets ascending order; a second click on the same header reverses to descending order; a third click removes the sort. Sort direction arrows are hidden by CSS (display: none !important) — there is no visual sort indicator in the column header. Sorting is functional despite the absence of the visual indicator. Tests must verify sort order by inspecting the data values in the grid, not by checking for sort-direction icons.

GEN::LST::0004::0002.US — Sort by Multiple Columns

The user defines a multi-column sort with precedence ordering. The primary sort column is applied first; the secondary column is used to break ties among rows that share the same primary value. Additional sort levels follow the same precedence rule.

GEN::LST::0004::0003.FS — Sort Order Rules

Sorting follows these type-specific rules: lexicographic order (Unicode code point comparison) for text and string-like properties; numerical order for numeric types; true before false for boolean properties; epoch order (timestamps converted to UTC) for date and datetime properties. Null values are ordered last regardless of sort direction.

GEN::LST::0004::0004.FS — Persist Sort State

The system persists the current sort column(s) and direction(s) as part of the column preference state defined in GEN::LST::0002::0003. Sort state is stored per tab alongside column visibility and order, and is restored on subsequent visits.

GEN::LST::0005 — Paginate Entity List

Present large datasets progressively without requiring the user to navigate between discrete pages.

Priority	High
Status	Covered

GEN::LST::0005::0001.US — Infinite Scroll

The user scrolls through the list. As the user approaches the bottom of the currently loaded rows, the system makes an additional API call to the backend to retrieve the next page of results and appends the new rows to the grid. The user experiences a continuous scroll without explicit page-turn controls. The scroll position is maintained during page append operations.

GEN::LST::0005::0002.FS — Display Loading Indicator During Scroll Fetch

While the system fetches the next page of results during infinite scroll, a loading indicator (skeleton rows or spinner) is displayed in the area where new rows will appear. This provides visual feedback that data is being loaded rather than absent. The indicator is removed and replaced with the actual rows once the API response is received.

GEN::LST::0006 — Select Rows and Trigger Actions

Select rows and invoke actions based on selection state. Domain-specific action semantics — for example, “Convert Cards to PO” in the Order Queue — are defined in their respective domain areas. This use case owns the generic interaction mechanism: how rows are selected, how action enablement is computed, and how actions are accessed.

Priority	MVP2-A
Status	Covered

GEN::LST::0006::0001.US — Trigger No-Row Action

The user triggers an action that requires no row selection or that acts on all rows regardless of selection state. The prototypical example is “New Entity,” which opens a creation form. No-row actions are always enabled. They are accessible via global buttons or menus in the list toolbar.

GEN::LST::0006::0002.US — Trigger Single-Row Action

The user triggers an action on exactly one selected row. Examples include “View Details” and “Edit.” Single-row actions are enabled only when exactly one row is selected. They are accessible via in-row controls (buttons, dropdowns, right-click context menus) or via the global toolbar when one row is selected.

GEN::LST::0006::0003.US — Trigger Multi-Row Action

The user triggers an action on multiple selected rows, where the system processes each row independently. The prototypical example is “Delete Selected,” which sends one delete request per selected row. Multi-row actions are enabled when one or more rows are selected. They are accessible via the global toolbar.

GEN::LST::0006::0004.US — Trigger Row-Set Action

The user triggers an action on multiple selected rows treated as a unit. Examples include computing a total across selected rows or creating a Purchase Order from a set of Kanban Cards. Row-set actions require at least two rows selected (or the specific minimum defined by the action) and are accessible via the global toolbar.

GEN::LST::0006::0005.FS — Enable/Disable Actions by Selection State

Action elements (buttons, menu items) display enabled or disabled state based on the current selection count and the action’s type requirement. A delete button is disabled when no row is selected; a row-set action button is disabled until the minimum required number of rows is selected. Disabled state is recalculated immediately on every selection change.

GEN::LST::0006::0006.FS — Action Tooltips

When an action element is enabled, hovering over it displays a tooltip that explains what the action does. When an action element is disabled, hovering displays a tooltip that explains why the action is disabled — for example, “Select at least one row to delete.” Tooltips are required for all action elements regardless of enabled state.

GEN::LST::0006::0007.FS — In-Row Action Access

Single-row actions are accessible without requiring the user to select the row first. In-row action controls (icon buttons, dropdown menus, right-click context menus within the row) trigger actions on the row they belong to. Clicking an in-row action stops event propagation so that the row is not selected as a side effect of triggering the action. In-row actions are restricted to the subset of actions applicable to the specific row’s data state.

GEN::LST::0006::0008.FS — Global Action Access

No-row, multi-row, and row-set actions are accessible via global buttons, dropdown menus, or toolbars positioned outside the row area. The global toolbar reflects the complete set of actions available for the entity type, with each action’s enabled state determined by the current selection.

GEN::LST::0006::0009.US — Shift-Click Row Range Selection

The user holds Shift and clicks a row to select all rows between the previously selected row and the newly clicked row. This uses a custom implementation with a module-level lastSelectedRowIndex tracker rather than AG Grid’s built-in range selection. The selection count indicator updates immediately to reflect all newly selected rows.

GEN::LST::0006::0010.US — Select All Rows

The user clicks a “Select All” checkbox in the header row. All rows matching the current filter are selected, including rows not yet loaded via infinite scroll. A “Deselect All” click clears the selection. The selection count in the status bar updates accordingly.

GEN::LST::0007 — Edit Entity In Place

Edit row data inline within the list without navigating to a separate edit page. Inline editing follows a two-phase commit pattern: a draft-creation call captures the pending change, and a publish call commits it when the user exits the row.

Depends	GEN::INT (cancel/confirm pattern)
Priority	High
Status	Covered

GEN::LST::0007::0001.US — Enter Edit Mode

The user double-clicks a cell in an editable row. A 300ms click-discrimination timer distinguishes a double-click (which enters edit mode) from a single click (which opens the item detail panel or triggers the row selection). Alternatively, the user clicks an explicit edit action button. The row enters edit mode, rendering editable widgets in each editable cell. Read-only cells remain display-only.

GEN::LST::0007::0002.FS — Navigate Editable Cells

While a row is in edit mode, the user navigates between editable cells using Tab (forward), Shift+Tab (backward), and arrow keys. The keyboard navigation wraps within the editable cells of the current row and does not inadvertently commit or cancel the edit.

GEN::LST::0007::0003.US — Accept Changes

The user presses Enter to commit the changes to the row. On cell blur, a draft-creation API call stores the updated value for the cell. On row exit (the user moves focus to a different row), a publish API call commits all pending draft values for the row to the entity service. The row exits edit mode and displays the persisted values.

GEN::LST::0007::0004.US — Cancel Changes

The user presses Escape while the row is in edit mode. The isCancelAfterEnd() method returns true and the wasCancelled flag is set. The cell exits edit mode with the typed value discarded. The cell reverts to the original pre-edit value. No draft-creation API call is made.

GEN::LST::0007::0005.FS — Navigate Away with Unsaved Changes

If the user navigates away from the row while it is in edit mode and changes have been made, the system prompts the user with three options: accept the changes (commit), cancel the changes (discard), or return to the editing position. This implements the cancel/confirm pattern defined in GEN::INT.

GEN::LST::0008 — Edit Through Reference

Create or edit referenced entities from within a lookup column without leaving the list context. This allows users to resolve missing references or correct incorrect references inline.

Priority	Medium
Status	Covered

GEN::LST::0008::0001.US — Create Referenced Entity via Overlay

From a lookup column cell in edit mode, the user activates the “create new” option. An overlay interaction opens for the referenced entity type. The user completes the creation flow. On completion, the overlay closes, the new entity is available in the lookup dropdown, and the cell is populated with the newly created reference. The user is returned to the list in edit mode.

GEN::LST::0008::0002.US — Edit Referenced Entity via Overlay

From a lookup column cell in edit mode, the user activates the “edit existing” option on a currently selected reference. An overlay interaction opens for that referenced entity instance. The user edits and saves the entity. On completion, the overlay closes and the cell reflects any display changes resulting from the update. The user is returned to the list in edit mode.

GEN::LST::0009 — Validate Edited Data

Provide real-time validation feedback during inline editing. Validation runs as the user types so that errors are surfaced before the user attempts to commit.

Priority	High
Status	Covered

GEN::LST::0009::0001.FS — Cell-Level Validation

Each editable column carries a boolean validation expression. The system evaluates the expression against the current cell value as soon as feasible during editing — typically on each keystroke or on blur. When the expression evaluates to false, the cell displays the error widget (a visual indicator such as a red border or error icon accompanied by a descriptive message). Validation clears when the value satisfies the expression.

GEN::LST::0009::0002.FS — Required Field Validation

Required-field constraints are a special case of cell-level validation. When a required cell is empty or cleared, the validation expression evaluates to false and the cell displays the required-field error widget. The row cannot be committed while any required cell is in error state.

GEN::LST::0010 — Render and Edit Cell Values

Cell display, editing, and error presentation behaviors by column type. Each scenario specifies the display widget (how the value is rendered in a read-only cell), the edit widget (the control used when the cell is in edit mode), and the error widget (the indicator shown when validation fails). Column types are inspired by Coda’s supported Column Types. Each type also contributes specific keys to filtering and sorting as described per scenario.

Priority	High
Status	Covered

Basic Column Types

GEN::LST::0010::0001.FS — Open Text Cell

A single-line unformatted text field. Display widget: plain text label. Edit widget: single-line text input (<input type="text">). Error widget: red border with inline error message. Contributes a text filter key (case-insensitive regex) and a lexicographic sort key.

GEN::LST::0010::0002.FS — Extended Text (Canvas) Cell

A multi-line text field with potential formatting (details to be determined). Display widget: truncated single-line preview with ellipsis, expandable to full content. Edit widget: multi-line text area or rich text editor (TBD). Error widget: border and inline message. Contributes a text filter key and a lexicographic sort key.

GEN::LST::0010::0003.FS — Number Cell

A numeric-only field. Display widget: locale-formatted number. Edit widget: numeric input that rejects non-numeric characters. Error widget: border and inline message. Contributes a numeric filter key (equality with 1e-18 precision) and a numerical sort key.

GEN::LST::0010::0004.FS — Date Cell

A date value without a time component, displayed in the user’s locale format. The field may optionally require a timezone. Display widget: locale-formatted date string. Edit widget: date picker with locale formatting. Error widget: border and inline message. Contributes a date filter key (plus or minus 12 hours window) and an epoch sort key (UTC).

GEN::LST::0010::0005.FS — DateTime Cell

A combined date, time, and timezone value displayed in the user’s locale format. Display widget: locale-formatted date-time string with timezone indicator. Edit widget: date-time picker with locale formatting and timezone selector. Error widget: border and inline message. Contributes a date filter key and an epoch sort key.

GEN::LST::0010::0006.FS — Time Cell

A time value with optional timezone, displayed in the user’s locale format. Display widget: locale-formatted time string. Edit widget: time picker with locale formatting and optional timezone selector. Error widget: border and inline message. Contributes a date filter key and an epoch sort key.

GEN::LST::0010::0007.FS — Boolean Cell

A true/false value. Display widget: checkbox or toggle rendered in its checked/unchecked state (read-only). Edit widget: checkbox or toggle that the user clicks to flip the value. Error widget: border and inline message. Contributes a boolean filter key (strict equality) and a boolean sort key (true before false).

GEN::LST::0010::0008.FS — Enum Cell

A value selected from a short predefined list (fewer than approximately 10 elements). Display widget: the selected value’s display label. Edit widget: a popup <select> dropdown that opens immediately on double-click; the five concrete editors (ColorCellEditor, OrderMechanismCellEditor, CardSizeCellEditor, LabelSizeCellEditor, BreadcrumbSizeCellEditor) are class-based components using afterGuiAttached() to attach event listeners. Error widget: border and inline message. Contributes an enumeration filter key (strict string equality) and a lexicographic sort key.

GEN::LST::0010::0009.FS — Dynamic Enum Cell

A value selected from a long predefined list (more than approximately 10 elements), accessed via a search/typeahead interface. Display widget: the selected value’s display label. Edit widget: typeahead dropdown that begins filtering after the first character is typed; results are fetched asynchronously from GET /api/arda/items/lookup-{type}?name={searchText}. Keyboard navigation: Arrow Down / Up moves through options, Enter selects, Escape cancels without committing. The nine concrete typeahead editors are: SupplierCellEditor, UnitCellEditor, TypeCellEditor, SubTypeCellEditor, UseCaseCellEditor, FacilityCellEditor, DepartmentCellEditor, LocationCellEditor, SublocationCellEditor. Error widget: border and inline message. Contributes an enumeration filter key and a lexicographic sort key.

GEN::LST::0010::0010.FS — Lookup Cell

A reference to another entity instance. Display widget: the referenced entity’s display name rendered as a link or label. Edit widget: typeahead or search control that queries the referenced entity’s endpoint; supports reference edit-through per GEN::LST::0008. Error widget: border and inline message. Contributes a text filter key on the referenced entity’s display name and a lexicographic sort key.

GEN::LST::0010::0011.FS — Money Cell

A monetary value with an associated currency code. Display widget: locale-formatted currency amount with currency symbol. Edit widget: numeric input for the amount plus a currency selector. Error widget: border and inline message. Contributes a numeric filter key and a numerical sort key on the amount.

GEN::LST::0010::0012.FS — URL/Link Cell

A URL that opens a destination in a new browser tab, window, overlay, or external application. Display widget: a clickable link label. Edit widget: text input accepting a URL string. Error widget: border and inline message. Contributes a string filter key (strict equality) and a lexicographic sort key.

GEN::LST::0010::0013.FS — Image Cell

An image hosted internally within the system or externally via a URL. Display widget: inline thumbnail with a fallback placeholder when the image cannot be loaded. Edit widget: URL input for externally hosted images or file upload for internally hosted images. Error widget: border and inline message. Image cells are not filterable or sortable by default.

GEN::LST::0010::0014.FS — Attachment Cell

An opaque data blob stored internally or externally via URL. Supported attachment types are to be determined. Display widget: a download link or icon with a filename or type indicator. Edit widget: file upload or URL input. Error widget: border and inline message. Attachment cells are not filterable or sortable by default.

GEN::LST::0010::0015.FS — Email Cell

An email address. Display widget: a mailto: link. Edit widget: text input with email format validation. Error widget: border and inline message. Contributes a string filter key (strict equality) and a lexicographic sort key.

GEN::LST::0010::0016.FS — Phone Cell

A phone number. Display widget: formatted phone number string. Edit widget: text input with phone format validation. Error widget: border and inline message. Contributes a string filter key (strict equality) and a lexicographic sort key.

Advanced Column Types

GEN::LST::0010::0017.FS — Quantity Cell

An inventory amount consisting of a numeric value and a unit of measurement. Display widget: formatted number with unit label (e.g., “24 EA”). Edit widget: composite editor with a numeric input for the amount and a unit selector. Error widget: per-subfield border and inline message. Contributes a numeric filter key on the amount and a numerical sort key on the amount.

GEN::LST::0010::0018.FS — Date Range Cell

A range defined by an ordered start date and an end date, both with timezone. The end date must be on or after the start date. Display widget: formatted date range string (e.g., “Jan 1, 2025 — Mar 31, 2025”). Edit widget: composite editor with two date pickers and temporal ordering validation. Error widget: border and inline message on the violating field. Contributes filter and sort keys on the start date.

GEN::LST::0010::0019.FS — Address Cell

A structured postal address comprising street, city, state, country, and zip code. Display widget: single-line formatted address string. Edit widget: group editor with individual inputs for each address component. Error widget: per-component border and inline message. Contributes filter keys on the street and city components and a lexicographic sort key on the full formatted address.

GEN::LST::0010::0020.FS — Physical Quantity Cell

A measurement value with a physical unit — lengths, weights, volumes, areas, and similar quantities. Display widget: formatted number with unit label (e.g., “5.0 kg”). Edit widget: composite editor with a numeric input for the value and a physical unit selector. Error widget: border and inline message. Contributes a numeric filter key on the value and a numerical sort key on the value.

GEN::LST::0010::0021.FS — GeoLocation Cell

A geographic location defined by longitude, latitude, and elevation with associated length units. Display widget: formatted coordinate string. Edit widget: composite editor with numeric inputs for longitude, latitude, and elevation, plus a length unit selector. Error widget: per-component border and inline message. Contributes filter and sort keys on latitude and longitude.

Summary

Use Case	Scenarios	US	FS	UC	Priority
GEN::LST::0001 Navigate to Entity List	3	2	1	0	High
GEN::LST::0002 Configure List Column Display	7	5	2	0	High
GEN::LST::0003 Filter Entity List	9	2	7	0	High
GEN::LST::0004 Sort Entity List	4	2	2	0	High
GEN::LST::0005 Paginate Entity List	2	1	1	0	High
GEN::LST::0006 Select Rows and Trigger Actions	10	6	4	0	High
GEN::LST::0007 Edit Entity In Place	5	3	2	0	High
GEN::LST::0008 Edit Through Reference	2	2	0	0	Medium
GEN::LST::0009 Validate Edited Data	2	0	2	0	High
GEN::LST::0010 Render and Edit Cell Values	21	0	21	0	High
Total	65	23	42	0

Additional enterprise use cases are defined in List View Behaviors — Advanced.

---