Skip to content

feat(pos): add storage.latest subscribable types to Storage interface#4235

Draft
vctrchu wants to merge 5 commits into2026-04-rcfrom
vchu/storage-keys-subscribable-types
Draft

feat(pos): add storage.latest subscribable types to Storage interface#4235
vctrchu wants to merge 5 commits into2026-04-rcfrom
vchu/storage-keys-subscribable-types

Conversation

@vctrchu
Copy link
Copy Markdown
Contributor

@vctrchu vctrchu commented Mar 27, 2026 •
edited
Loading

What

Add StorageKeys type and latest property to the POS Storage interface for reactive cross-target communication.

Why

Extensions running across multiple targets (tile, modal, background) need to share state reactively. The storage.latest subscribable enables one target to subscribe to a key and react when another target updates it via set() or delete().

TAG PR: ui-api-design#1416
Issue: shop/issues-retail#26020

How

Changes to packages/ui-extensions/src/surfaces/point-of-sale/types/storage.ts:

  • StorageKeys<T> — mapped type where each key maps to ReadonlySignalLike<T | undefined>, reusing the existing signal type from shared.ts (consistent with cart, connectivity, scanner, locale APIs)
  • latest: StorageKeys<BaseStorageTypes> — required property on Storage interface exposing each storage key as a subscribable
// Synchronous access to the current value:
const status = shopify.storage.latest.syncStatus.value;

// Subscribe to changes from another target:
const unsubscribe = shopify.storage.latest.syncStatus.subscribe((value) => {
  console.log('syncStatus changed:', value);
});

Also updates ui-extensions-tester mock (createStorage()) with a Proxy-based latest implementation.

Companion PR

  • pos-mobile runtime: shop/world#554969 — signal registry + proxy + storageApi integration

Base Branch

2026-04-rc — ships with the 2026-04 API version.

@github-actions
Copy link
Copy Markdown
Contributor

github-actions bot commented Mar 27, 2026

🚨🚨🚨 Docs migration in progress 🚨🚨🚨

We are actively migrating UI extension reference docs to MDX in the areas/platforms/shopify-dev zone of the monorepo. This impacts docs for the following surfaces:

During this migration, please be aware of the following:

.doc.ts files are being deprecated. Changes to .doc.ts files in this repo will not be reflected in the new MDX-based docs. If you need to update docs for a reference that has already been migrated, make your changes directly in the areas/platforms/shopify-dev zone of the monorepo instead.

Doc comments in .ts source files (the comment blocks above types and functions) are also affected. Generating docs from these comments currently requires a newer version of the @shopify/generate-docs library that isn't yet available. Updates to doc comments may not produce the expected output until the migration is complete.

Examples that previously lived in this repo are being moved to the areas/platforms/shopify-dev zone of the monorepo and should be authored there going forward.

What should I do?

  • If your PR includes changes to .doc.ts files, doc comments, or examples, please reach out to us in #devtools-proj-templated-refs so we can help ensure your updates are captured correctly.
  • If your PR is limited to source code changes (non-docs), you can ignore this notice.

Thanks for your patience while we complete the migration! 🙏

@vctrchu vctrchu requested review from a team and NathanJolly March 31, 2026 01:15
@vctrchu vctrchu self-assigned this Mar 31, 2026
@vctrchu vctrchu force-pushed the vchu/storage-keys-subscribable-types branch 2 times, most recently from 5a42408 to 36bfa6a Compare March 31, 2026 02:10
@vctrchu vctrchu marked this pull request as ready for review March 31, 2026 02:12
@vctrchu vctrchu marked this pull request as draft March 31, 2026 23:27
@vctrchu vctrchu changed the title feat(pos): add storage.keys subscribable types to Storage interface feat(pos): add storage.latest subscribable types to Storage interface Apr 2, 2026
vctrchu and others added 3 commits April 2, 2026 11:30
@vctrchu @claude
feat(pos): add storage.keys subscribable types to Storage interface
0ae5f58 
Add Subscribable, StorageKeys types and optional keys property to the
POS Storage interface. Each key is exposed as Subscribable<T | undefined>
for reactive cross-target communication within the same extension.

Available on API version 2026-04 and later.

Part of: shop/issues-retail#26020
TAG PR: Shopify/ui-api-design#1416

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@vctrchu
refactor(pos): use ReadonlySignalLike instead of duplicate Subscribab…
75228d5 
…le type

Replace custom Subscribable interface with the existing ReadonlySignalLike
from shared.ts — identical shape, already used by cart, connectivity,
scanner, and locale APIs. Fix @example to use api.storage instead of
shopify.storage.
@vctrchu
refactor(pos): rename storage.keys to storage.latest per TAG feedback
a384c73 
Aligns with ui-api-design#1416 rename. Updates JSDoc with cross-target
reactivity example and .value/.subscribe() documentation. Updates
tester mock with Proxy-based latest implementation.
@vctrchu vctrchu force-pushed the vchu/storage-keys-subscribable-types branch from 5a8ffb8 to a384c73 Compare April 2, 2026 18:30
vctrchu added 2 commits April 2, 2026 11:31
@vctrchu
test(pos): add createStorage and createCartLineItem factory tests
a17b71f 
Covers set/get/delete/clear/entries, storage.latest subscribable access,
createCartLineItem defaults and overrides, and createResult mock.
@vctrchu
test(pos): add createStorage factory tests
f914706 
Covers set/get/delete/clear/entries and storage.latest subscribable
access (value reads, reflects updates via set, undefined for missing
keys, unsubscribe function).
vctrchu
vctrchu commented Apr 2, 2026
View reviewed changes
packages/ui-extensions-tester/src/point-of-sale/index.ts
Comment on lines +51 to +55
const latestProxy = new Proxy({} as StorageKeys<T>, {
get(_target, prop) {
return createSubscribable(prop as string);
},
});
Copy link
Copy Markdown
Contributor Author

@vctrchu vctrchu Apr 2, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Proxy()

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@aaronschubert0 aaronschubert0 aaronschubert0 approved these changes

@js-goupil js-goupil js-goupil approved these changes

@NathanJolly NathanJolly Awaiting requested review from NathanJolly

Assignees

@vctrchu vctrchu

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@vctrchu @aaronschubert0 @js-goupil