[Local Catalog] Show items from GRDB in POS #16235

joshheald · 2025-10-10T14:01:02Z

Merge after: #16231

Description

This PR starts using the observable GRDB data source added in #16231 to show items from GRDB in the item list.

Note that there's nothing to enforce that GRDB actually has items in it at the moment... so you can definitely break this, but those guards are covered by other tickets and this is feature flagged.

Steps to reproduce

Check we're not breaking production...

Set the pointOfSaleLocalCatalogi1 feature flag to false
Open the POS
Observe that browsing and scrolling works as expected, and use WormHoly or a proxy tool to verify that products are loaded from the network.

Test the GRDB item controller

Reset the feature flag
Launch the app
Wait for console log messages to confirm the catalog sync status for your store
Open POS
Observe that products are shown, and that you can open variation lists
Scroll down, observe that subsequent pages are loaded
Turn on airplane mode, observe that you can still fully browse the catalog.

Example sync log messages:

📋 POSCatalogSyncCoordinator: Site 216335538 has catalog size 91, with 45 products and 46 variations
📋 POSCatalogSyncCoordinator: Last sync for site 216335538 was 16344s ago (max: 86400s), sync not needed

Optional: test with a larger site

Change the value for POSCatalogSyncCoordinator.Constants.defaultSizeLimitForPOSCatalog to 100000
Run the app and pick a store with a large catalog
Wait for the sync to complete (it will take some time and gives no progress info before completion)
Open POS
Observe that you can interact with the full catalog

Note that with larger catalogs, you start to hit scrolling performance issues. These are outside the scope of current work, but we may want to address them before too long. I don't think it's down to the mapping happening on the main thread, and it may even be that we're hitting some SwiftUI limitations.

Testing information

Note that Search and Barcode Scanning are still using the network-based controller, so have delays.

Screenshots

GRDB.items.mp4

I have considered if this change warrants user-facing release notes and have added them to RELEASE-NOTES.txt if necessary.

joshheald · 2025-10-10T14:04:03Z

@staskus Sorry it took longer than I thought it would, but here's the second PR as mentioned this morning.

I'm AFK next week – happy for you to merge them then if you prefer not to review this afternoon. As long as there's nothing major needed as changes!

joshheald · 2025-10-10T14:05:39Z

Modules/Sources/PointOfSale/Models/ItemListState.swift

 import enum Yosemite.POSItem

 enum ItemListState {
+    case initial


I added this state for more accurate modelling of what's happening.

My intention is to delay showing the loading indicators when we open variations with GRDB – it causes a slight flicker at the moment. This is some groundwork for that.

https://linear.app/a8c/issue/WOOMOB-1494/woo-poslocal-catalog-add-a-delay-before-showing-loading-indicators

wpmobilebot · 2025-10-10T14:10:29Z

📲 You can test the changes from this Pull Request in WooCommerce iOS Prototype by scanning the QR code below to install the corresponding build.

	App Name	WooCommerce iOS Prototype
	Build Number	`pr16235-9ef581f`
	Version	`23.5`
	Bundle ID	`com.automattic.alpha.woocommerce`
	Commit	`9ef581f`
	Installation URL	7gtcoidlalli8

Automatticians: You can use our internal self-serve MC tool to give yourself access to those builds if needed.

joshheald · 2025-10-10T16:46:42Z

@staskus I also tested that it observes changes: this branch adds an incremental sync button to the ... menu. I used that by editing products on the web and then syncing.

Trashing a product didn't remove it, which is probably down to how we request them or filter the products from the db... but I'll fix it in a separate PR. https://linear.app/a8c/issue/WOOMOB-1493/woo-poslocal-catalog-ensure-that-trashed-products-are-updated-to-not

Other changes and additions worked as expected.

staskus · 2025-10-15T12:35:08Z

Modules/Sources/PointOfSale/Controllers/PointOfSaleObservableItemsController.swift

+    func loadItems(base: ItemListBaseItem) async {
+        switch base {
+        case .root:
+            hasLoadedProducts = true


Should we delay it until the items are loaded? Same with other similar flags.

Done in 2bdf4ab

staskus · 2025-10-15T12:36:51Z

Modules/Sources/PointOfSale/Controllers/PointOfSaleObservableItemsController.swift

+    func refreshItems(base: ItemListBaseItem) async {
+        switch base {
+        case .root:
+            dataSource.refresh()


So, this is not implemented. Is the idea to trigger an incremental sync when refresh is called?

Yes, that's right

staskus · 2025-10-15T12:39:36Z

Modules/Sources/PointOfSale/Controllers/PointOfSaleObservableItemsController.swift

+        }
+
+        // Error state
+        if let error = dataSource.error, items.isEmpty {


What kind of errors can we expect here? Since this comes from database, only something super-unexpected I suppose?

It should be extremely rare – these are really simple select queries...

Database corruption

Programming errors during development, e.g. relationships missing, or incorrect query setup – but those shouldn't ever happen in production

Errors are more likely to appear when we sync the data, because we're relying on it coming down with the correct schema and logically consistent. These will happen when we write stuff to the DB, and will prevent the whole write transacion if they're not handled in other code... so they won't get as far as being shown here. It's primarily included for completeness with the existing code, and to make it easier to spot bugs in dev.

I noticed that we only have one error property, shared between variations and products, which could result in an error state being shown for the wrong screen. I've separated them out. 46b634a

staskus

Thank you, @joshheald, for work! It took some time to review and understand. I'm not yet that familiar with GRDB, plus there's complexity in clean state management and observability. We don't want the views to stuck in some "no man's land" state.

I think it's mostly good. The comments are in both PRs. I tested with smaller and larger stores. I think there are a couple of things that need to be addressed. I don't see much value in pushing this to trunk without addressing and understanding them properly. I will see if I find time to come back to this after finishing the synchronization work. Otherwise, we can discuss next week and fix things or move to other tasks and merge this work.

wpmobilebot · 2025-10-17T04:52:12Z

Version 23.5 has now entered code-freeze, so the milestone of this PR has been updated to 23.6.

Adds a new `.initial` case to `ItemListState` to represent "not yet loaded" state, distinct from "actively loading". Benefits: - More explicit state machine: initial → loading → loaded/empty/error - Foundation for delayed loading indicators (300ms threshold) - Better UX for instant GRDB loads (no flashing skeleton) Updated existing `PointOfSaleItemsController` to: - Start with `.initial` instead of `.loading([])` - Transition to `.loading([])` on first load - Preserve existing behavior for refreshes

Creates a new controller that wraps `POSObservableDataSourceProtocol` for GRDB-based item loading. Key features: - Conforms to `PointOfSaleItemsControllerProtocol` (same interface as existing controller) - Computed `itemsViewState` from observable data source properties - Automatic UI updates via observation (no manual state management) - Supports products and variations with `.initial` state - Tracks current parent for variation state mapping Implementation notes: - No pagination tracking needed (data source handles it) - No search support (out of scope for this PR)

Comprehensive test coverage for the new observable controller: - Initial state (loading container, initial root) - Product loading (loaded, empty, error states) - Variation loading (loaded, empty states) - Pagination (hasMoreItems flags) - Independence of products and variations - Parent switching behavior - Error handling - Loading state preservation Fix tests to use proper POSItem construction Use helper methods to create POSSimpleProduct and POSVariation structs instead of non-existent .fake() method, matching the pattern used in MockPOSItemProvider. Changes: - Added makeSimpleProduct() helper - Added makeVariation() helper - Updated all 12 tests to use proper construction

When grdbManager, catalogSyncCoordinator, and the pointOfSaleLocalCatalogi1 feature flag are all present, use the new PointOfSaleObservableItemsController backed by GRDBObservableDataSource instead of the standard PointOfSaleItemsController. This enables reactive database-driven item lists for stores with local catalog sync enabled.

staskus

I retested on Friday and today as well comparing the new version with the previous version and all the same products, including variable ones are loaded. The pagination works, including with large datasets.

As you mentioned, there are still ways to make it solid, and handle the cases where the catalog is not loaded yet but otherwise it works well and is super fast 👍

Previously, a single error property was shared between products and variations, which could cause errors to leak between the root and variation parent contexts. Now using separate productError and variationError properties so that: - Product loading errors only affect the root state - Variation loading errors only affect the parent item state - Errors don't interfere with each other Updated: - POSObservableDataSourceProtocol - GRDBObservableDataSource implementation - PointOfSaleObservableItemsController state computation - MockPOSObservableDataSource for tests

When loading variations for a new parent product, clear any previous variation error to prevent it from leaking to the new parent's context. This ensures each parent starts with a clean error state, matching the behavior of clearing variationItems.

joshheald added this to the 23.5 milestone Oct 10, 2025

joshheald requested a review from staskus October 10, 2025 14:01

joshheald added type: task An internally driven task. status: feature-flagged Behind a feature flag. Milestone is not strongly held. feature: POS labels Oct 10, 2025

joshheald commented Oct 10, 2025

View reviewed changes

staskus self-assigned this Oct 14, 2025

staskus reviewed Oct 15, 2025

View reviewed changes

wpmobilebot modified the milestones: 23.5, 23.6 Oct 17, 2025

staskus force-pushed the issue/woomob-1088-observable-itemcontroller-for-grdb branch from eba2394 to 5706749 Compare October 17, 2025 13:05

staskus mentioned this pull request Oct 17, 2025

[Local Catalog] Add GRDB data source for item list #16231

Merged

1 task

joshheald added 6 commits October 17, 2025 16:46

Periphery ignore

d199ffa

Fix periphery ignore

ee974cc

staskus force-pushed the issue/woomob-1088-observable-itemcontroller-for-grdb branch from 5706749 to ee974cc Compare October 17, 2025 13:46

Base automatically changed from issue/woomob-1088-use-GRDB-in-itemlist to trunk October 17, 2025 14:16

staskus approved these changes Oct 20, 2025

View reviewed changes

joshheald added 3 commits October 20, 2025 11:37

Set hasLoaded after we actually load

2bdf4ab

joshheald enabled auto-merge October 20, 2025 10:58

joshheald added 2 commits October 20, 2025 12:03

Fix tests

0a68b51

Fix test

9ef581f

joshheald merged commit 97ec53c into trunk Oct 20, 2025
13 checks passed

joshheald deleted the issue/woomob-1088-observable-itemcontroller-for-grdb branch October 20, 2025 11:42

[Local Catalog] Show items from GRDB in POS #16235

[Local Catalog] Show items from GRDB in POS #16235

Uh oh!

Conversation

joshheald commented Oct 10, 2025

Description

Steps to reproduce

Check we're not breaking production...

Test the GRDB item controller

Optional: test with a larger site

Testing information

Screenshots

Uh oh!

joshheald commented Oct 10, 2025

Uh oh!

joshheald Oct 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

wpmobilebot commented Oct 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

joshheald commented Oct 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

staskus Oct 15, 2025

Choose a reason for hiding this comment

Uh oh!

joshheald Oct 20, 2025

Choose a reason for hiding this comment

Uh oh!

staskus Oct 15, 2025

Choose a reason for hiding this comment

Uh oh!

joshheald Oct 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

staskus Oct 15, 2025

Choose a reason for hiding this comment

Uh oh!

joshheald Oct 20, 2025

Choose a reason for hiding this comment

Uh oh!

staskus left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

wpmobilebot commented Oct 17, 2025

Uh oh!

staskus left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

joshheald Oct 10, 2025 •

edited

Loading

wpmobilebot commented Oct 10, 2025 •

edited

Loading

joshheald commented Oct 10, 2025 •

edited

Loading

joshheald Oct 20, 2025 •

edited

Loading

staskus left a comment •

edited

Loading