feat(loops): filter and order data-row loops by a cell value

[mostafasadeghidev]

What

Lets a base.loop on the data.rows source pick which rows it lists, and which cell it sorts by:

• Filter (Filter by + Condition): one condition on a row's own cell: is, is not, is checked, is unchecked, has any value, has no value.
• Order by a field: the table's own fields join the Order by list as Field: <Label>, alongside the existing row columns.

Both are configured in the loop's properties panel and take effect in the canvas preview, in published pages, and in the "load more" endpoint.

Why

A loop could pick a table, an order, and a limit, but not a subset. So a page meant to show the four team members flagged for the About page showed the four most recently updated rows instead, and a list meant to follow the source CMS's own publish date followed our updated_at column. The only workarounds were reordering rows by hand or duplicating a table, and both drift the moment someone edits an item.

This is deliberately one condition rather than a query builder: it covers the real cases (a "featured" checkbox, a category, a "show on homepage" flag) without inventing an AND/OR grammar the editor can't express and future maintainers would have to keep sound in two dialects.

How

New pure module src/core/loops/cellFilter.ts owns the whole contract: parsing, the closed operator set, the SQL fragments, and the rule for which fields a single condition can address.

• The field name is a bound parameter, never SQL text. Postgres reads cells_json #>> array[$n], SQLite json_extract(cells_json, '$.' || ?). A hostile field id cannot reach the statement (covered by a test).
• The JSON read appears exactly once per fragment. coalesce(…, '') folds the missing-field case into the comparison instead of needing a second is null branch; repeating the expression would repeat its placeholder while the caller binds the field once.
• SQLite casts the read to text. json_extract returns INTEGER 1/0 for JSON booleans, and SQLite compares by storage class first, so 1 = '1' is false without the cast. The checked/unchecked operators accept both spellings.
• Ordering rides on orderBy as cell:<fieldId> rather than a new prop, so every caller that already threads orderBy (publisher, canvas preview endpoint, imported data-order-by) gets it for free. Values compare as text: ISO dates sort chronologically, which is the case this exists for.
• COUNT applies the same filter on both the post-type and data-kind paths, so pagination never advertises rows the page query drops.

Touched: loops/cellFilter.ts (new), loops/sources/dataRows.ts, LoopPropertiesView.tsx, useLoopPreviewItems.ts, server/handlers/cms/data/tables.ts, core/persistence/cmsData.ts.

User impact

Additive. A loop with no cell field configured behaves exactly as before, and a half-configured filter (field picked, operator not yet) keeps listing everything rather than silently emptying the list.

Verification

bun test          # 6661 pass, 0 fail
bun run build     # exit 0
bun run lint      # exit 0

# and the same loop suites against a real Postgres 16:
DB=postgres TEST_POSTGRES_URL=... bun test src/__tests__/loops/   # 38 pass

Two new files: src/__tests__/loops/cellFilter.test.ts (parsing, parameter binding, dialect shapes, which fields a condition may address) and src/__tests__/loops/dataRowsCellFilter.test.ts (behaviour against a real migrated SQLite database, both table kinds, filtered counts, pagination).

Also exercised end-to-end on a real site migrated from another CMS: an About page list that needed 4 of 30 rows, and an index page that had to follow the source CMS's publish date rather than ours.

Review changes

Three defects found in review, fixed on this branch:

• The filter outlived its table. Switching the loop's table left cellField naming a column the new table does not have. The field picker falls back to its first option when the stored value is not among its own, so the panel read "no filter" while the query still filtered and returned nothing. Changing the table now clears the cell filter and any cell: sort.
• Unfilterable fields were on offer. A multiSelect, repeater, or multi-value relation stores a collection; the SQL reads one cell as text, so the comparison ran against ["cat_impact"] and no picked value could match. isCellComparableField keeps those, plus media ids and page-tree refs, out of both pickers.
• The suite never ran on Postgres. It seeded cells_json pre-stringified, which lands as a jsonb string rather than an object, so 12 of 16 assertions failed on Postgres whatever the feature did. Seeding the way production writes fixes that, and the #>> array[$n] half is now covered: 16 green on SQLite, 16 green against a real Postgres 16.

Also: clearer control labels (Filter by / No filter, has any value / has no value, Field: <name> sorts), loop-source-sql-safety.test.ts widened to the whole src/core/loops/ tree so the gate covers cellFilter.ts, the unused cellFilterMatches export removed, and a CHANGELOG.md entry plus docs/features/loops.md brought up to date.