[Local catalog] Add configurable search debounce strategies

[joshheald]

Part of: WOOMOB-1112

Description

This PR fixes the flickering when we do a local search, while retaining the debounce approach used in existing places

Implements configurable debouncing strategies for search to optimize the user experience for both local and remote searches. Different search types have different performance characteristics and benefit from different debounce behaviors.

Changes include:

• New SearchDebounceStrategy enum with three strategies:
  • .smart: Skip debounce on first keystroke after search completes, then debounce subsequent keystrokes (optimized for slow network searches)
  • .simple: Always debounce every keystroke with optional loading delay threshold (optimized for fast local searches to prevent flicker)
  • .immediate: No debouncing, execute search on every keystroke
• Added debounceStrategy property to fetch strategy protocols
• Updated search UI to implement strategy-based debouncing logic
• Applied simple debouncing (150ms) to local product search with 300ms loading delay threshold
• Comprehensive test coverage for all three strategies

This ensures responsive UI for fast local searches while preventing loading indicator flicker, and optimized behavior for slower network searches.

This PR is stacked on #16376 and is the fifth and final PR in the series implementing local catalog search.

Test Steps

N.B. – the remote feature flag now requires WCiOS 23.8 – change it in the project file when you want to use a local catalog store.

Debouncing

• With the feature flag enabled, launch the app and open POS
• Search for an item, typing the term quickly with an external keyboard
• Observe that there aren't intermediate results, when you type quickly
• Observe that there's no flickering, and results update quickly (we'll animate it later, if needed)

Repeat this slower with the software keyboard and observe that there's no flicker (but there will be intermediate results)

Test with the feature flag disabled – observe that loading indicators are still shown and work as expected
Check Coupons and Order History as well.

General search testing

• Launch the app with the feature flag enabled
• Search for a product by name, SKU, or GTIN
• Observe that results are shown, without a loading state
• Search for a non-matching term
• Observe that the "no results found" screen is shown

Remaining issues

Note that there are two issues still to tackle in future PRs

• Occasionally errors show briefly for intermediate results
• Trashed products aren't filtered, because that PR wasn't in trunk when I branched

Screenshots

Search.-.01.mp4

---

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

[wpmobilebot]

📲 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	pr16377-6efe96f
	Version	23.7
	Bundle ID	com.automattic.alpha.woocommerce
	Commit	6efe96f
	Installation URL	7cfl29esk1jjg

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

[joshheald]

@iamgabrielma I think you're best off starting by testing here, then reviewing down the stack... but it's hard to say for sure. Let me know whether you find this breakdown more helpful, or if you'd prefer the whole story in one.

I spent most of today just wrangling the stack, and getting the tiny details right around loading indicators and other searches working correctly...

Note that there's a pre-existing behaviour where there's a loading indicator for popular products if you open search too soon after opening POS – this is just how popular products works, we try to load it on POS opening, but don't want to delay using POS, so if we need to, we show the loading indicators

[iamgabrielma]

👋 @joshheald is this one ready for review as stand-alone PR?

[joshheald]

👋 @joshheald is this one ready for review as stand-alone PR?

Yeah, absolutely – I don't want to merge any the stack until this one's reviewed, because of all the periphery nonsense further down. This is the leaf PR though, so go for it.

[iamgabrielma]

LGTM! 🚀

[iamgabrielma]

Since all cases seem to use the same default, perhaps we can pass it here so we don't need to add it on each instance:

Suggested change

	case smart(duration: UInt64, loadingDelayThreshold: UInt64? = nil)
	case smart(duration: UInt64 = 500 * NSEC_PER_MSEC, loadingDelayThreshold: UInt64? = nil)

[iamgabrielma]

I'm not specially opinionated about it, but would you say extracting this onChange logic into a switch first for its selection, and then separate each into private functions for its implementation, would make it more readable?

.onChange { 
await performSearchWithStrategy(term: newValue, strategy: debounceStrategy)

... 

private func performSearchWithStrategy(term: String, strategy: SearchDebounceStrategy) async {
        switch strategy {
        case .smart(let duration, let loadingDelayThreshold):
            await executeSmartSearch(term: term, duration: duration, threshold: loadingDelayThreshold)
        case .simple(let duration, let loadingDelayThreshold):
            await executeSimpleSearch(term: term, duration: duration, threshold: loadingDelayThreshold)
        case .immediate:
            await executeImmediateSearch(term: term)
        }
    }

...

[dangermattic]

	1 Warning
⚠️	This PR is larger than 300 lines of changes. Please consider splitting it into smaller PRs for easier and faster reviews.

Generated by 🚫 Danger