Files
frappe/ui/CONTEXT.md
shariquerik 803a7c97e7 refactor(ListView): host owns persistence via reactive snapshot
Replace useListView.serialize() with a reactive `snapshot` computed and
defer all saving to the host: persist by watching it
(`watch(view.snapshot, save)`), which covers filter, sort, and every
column add/remove/resize. The library owns no ViewStorage/autosave/dirty
(ADR-0007); it tops out at an identity-less View Snapshot, with restore()
staying rich-only.

QuickFilter: field edits are already live via v-model:fields, so the
customize "Save" button only left edit mode. Relabel it "Done" and rename
the @save emit to @done so it no longer pretends to persist.

Also fix applyQuick to return the same array on an empty no-op, so
clearing an already-empty input doesn't churn snapshot identity into a
phantom autosave.

Add ADR-0007, the View Snapshot glossary term, and rewrite the saving
docs; rename serialize.test -> snapshot.test.
2026-06-30 13:27:04 +05:30

4.3 KiB

List View (shared @framework/ui)

The domain of the reusable doctype list-view experience being extracted from CRM into @framework/ui: the toolbar controls a user manipulates to shape a list (sort, filter, columns, quick filters) and the composite that assembles them.

Language

List View Controls: The four toolbar pieces a user manipulates to shape a doctype list — SortBy, Filter, Column Settings, and Quick Filter. Each is an independent, controlled component that owns one slice of view state. Avoid: "view controls" (CRM's name; it carries the CRM-specific Views concept).

Sort: A single ordering rule: a fieldname plus a direction (asc/desc). A list's ordering is an ordered list of Sorts. Avoid: order, ordering rule.

order_by: The Frappe wire form of an ordering — a comma-joined string like "modified desc, name asc". The serialized form of a list of Sorts. Avoid: sort string.

Filter: A precise, fieldtype-aware condition on a doctype field, set through the Filter control's popover. The full/advanced way to narrow a list.

Quick Filter: A pre-chosen field surfaced inline in the toolbar for one-tap narrowing. A convenience projection over Filters — a Quick Filter and its matching Filter describe the same underlying condition and stay in sync. Avoid: inline filter.

Column: One shown column in the list: a fieldname, a (user-overridable) label, and an optional CSS width ("11rem", "120px"). The Column Settings control's state is an ordered list of Columns — presence means shown, array order is display order, and width is the slice a column resize co-writes. A column's align/type/options are not stored here; they are derived from Meta at render/serialize time. Avoid: field, column setting (the control, not the datum), key (CRM's key ≙ fieldname).

Field Options: The list of a doctype's fields a control offers (e.g. SortBy's sortable fields). Derived client-side from doctype Meta, not from a CRM endpoint. Avoid: sort_options, filterable fields (CRM endpoint names).

Meta: A doctype's field definitions, fetched via the shared useDoctypeMeta composable. The single source from which Field Options are derived.

Controlled component: A control that owns only its own state slice via v-model plus a doctype, emits changes, and never touches a data-fetching resource or persistence. The host wires fetching, persistence, and cross-control sync. Avoid: connected component, smart component.

View Snapshot: The serialized, persist-able capture of a List View's state — its Filters, Sorts, Columns, and surfaced Quick Filter fields. The unit a host's persistence layer is handed. It carries no identity, ownership, or named-View concept — whether this is a "standard", public, pinned, or named View, and who owns it, belongs entirely to the consuming app. The library tops out here and never owns a saved View entity; the host wires when and where to save it (ADR-0007). Avoid: view, saved view, view settings (all carry CRM's Views concept).

Composite List View: The shared module that assembles the controls (and, later, the table, footer, selection banner, and a useListView state composable) into a full list view. The home of the integration "shell" story used to chase pixel parity with CRM.

Shell story: The combined story in the Composite List View module that mounts the controls together against a real doctype to verify pixel parity with CRM's list view. Distinct from each control's own isolated story.

Example dialogue

— "When I change the SortBy chip, does it write order_by back to the resource?" — "No. SortBy is a controlled component — its v-model is a list of Sorts. It just emits the new array; the host serializes it to order_by and refetches." — "And where do the sortable fields come from — the sort_options endpoint?" — "No CRM endpoint. Field Options are derived from the doctype's Meta." — "If I set a Quick Filter for Status, does the Status Filter update too?" — "Yes — a Quick Filter is a projection over Filters; they describe the same condition and stay in sync once the shared composable lands."