@object-ui/data-objectstack 4.8.0 → 5.0.0

package/CHANGELOG.md

@@ -1,5 +1,40 @@
 # @object-ui/data-objectstack
 
+## 5.0.0
+
+### Minor Changes
+
+- c7561a7: **Unify per-user UI state storage onto `sys_user_preference`.**
+
+  `createObjectStackUserStateAdapter` previously wrote to a bespoke
+  `user_app_state` object using `(user_id, kind, payload)` columns. That
+  parallel KV table duplicated the canonical per-user preference store
+  shipped by `@objectstack/plugin-auth`, and pulled UI traces (favorites,
+  recent items, grid widths) out of the place users actually look for
+  their settings.
+
+  The adapter now defaults to:
+  - `resource`: `sys_user_preference`
+  - field shape: `(user_id, key, value)` instead of `(user_id, kind, payload)`
+  - option name: **`key`** instead of `kind`
+
+  `ConsoleShell` is updated to attach favorites/recent under the namespaced
+  keys `ui.favorites` and `ui.recent`. Recommended convention for new
+  adapters: keep machine-written UI traces under `ui.*` so they stay
+  distinguishable from user-facing preferences (`theme`, `locale`, ...).
+
+  **Migration**: callers passing `kind:` need to switch to `key:`. Callers
+  relying on the old `user_app_state` table can pin
+  `resource: 'user_app_state'` to keep the legacy behaviour, but no
+  backend ships that schema and the new default works against any
+  plugin-auth-enabled environment with zero extra setup.
+
+### Patch Changes
+
+- Updated dependencies [7213027]
+  - @object-ui/types@5.0.0
+  - @object-ui/core@5.0.0
+
 ## 4.8.0
 
 ### Patch Changes

package/README.md

@@ -283,10 +283,10 @@ import { createObjectStackUserStateAdapter } from '@object-ui/data-objectstack';
 import { useAttachUserStateAdapters } from '@object-ui/app-shell';
 
 const favoritesAdapter = createObjectStackUserStateAdapter({
-  dataSource,        // the ObjectStack DataSource
+  dataSource,             // the ObjectStack DataSource
   userId: user.id,
-  kind: 'favorites', // or 'recent'
-  // resource: 'user_app_state',  // default
+  key: 'ui.favorites',    // or 'ui.recent', 'ui.grid.account.state', ...
+  // resource: 'sys_user_preference',  // default — the unified per-user KV store
   // onError: (op, err) => console.warn(`[user-state] ${op} failed`, err),
 });
 
@@ -295,20 +295,26 @@ attach('favorites', favoritesAdapter);
 
 ### Backend contract
 
-A single object stores one row per `(user_id, kind)` pair:
+The adapter writes to the platform's unified per-user KV store —
+`sys_user_preference` — shipped by every `@objectstack/plugin-auth`
+environment. One row per `(user_id, key)` pair:
 
 ```yaml
-object: user_app_state
+object: sys_user_preference
 fields:
-  - { name: user_id,    type: string,   indexed: true }
-  - { name: kind,       type: string,   indexed: true }
-  - { name: payload,    type: json }
+  - { name: user_id,    type: lookup(sys_user), indexed: true }
+  - { name: key,        type: string,           indexed: true }
+  - { name: value,      type: json }
   - { name: updated_at, type: datetime }
-unique: [user_id, kind]
+unique: [user_id, key]
 ```
 
-If the object doesn't exist, every call 404s and the UI silently degrades to
-localStorage-only persistence. See
+By convention, namespace UI-trace keys under `ui.*` (e.g. `ui.favorites`,
+`ui.recent`, `ui.grid.<object>.state`, `ui.sidebar.collapsed`) so they
+stay easy to tell apart from user-facing preferences (`theme`, `locale`).
+
+If the backend doesn't yet expose `sys_user_preference`, every call
+404s and the UI silently degrades to localStorage-only persistence. See
 [User-Scoped State Persistence](../../content/docs/guide/user-state-persistence.md)
 for the full design.
 

package/dist/index.cjs

@@ -570,12 +570,12 @@ function generateContractManifest(contract) {
 }
 
 // src/userState.ts
-var DEFAULT_RESOURCE = "user_app_state";
+var DEFAULT_RESOURCE = "sys_user_preference";
 function createObjectStackUserStateAdapter(options) {
   const {
     dataSource,
     userId,
-    kind,
+    key,
     resource = DEFAULT_RESOURCE,
     onError = () => {
     }
@@ -585,7 +585,7 @@ function createObjectStackUserStateAdapter(options) {
     const params = {
       filter: {
         user_id: userId,
-        kind
+        key
       },
       limit: 1
     };
@@ -593,11 +593,11 @@ function createObjectStackUserStateAdapter(options) {
     const rows = result?.data ?? [];
     return rows.length > 0 ? rows[0] : null;
   };
-  const decodePayload = (payload) => {
-    if (Array.isArray(payload)) return payload;
-    if (typeof payload === "string") {
+  const decodeValue = (value) => {
+    if (Array.isArray(value)) return value;
+    if (typeof value === "string") {
       try {
-        const parsed = JSON.parse(payload);
+        const parsed = JSON.parse(value);
         return Array.isArray(parsed) ? parsed : [];
       } catch {
         return [];
@@ -614,7 +614,7 @@ function createObjectStackUserStateAdapter(options) {
           return [];
         }
         if (row.id !== void 0 && row.id !== null) cachedRowId = row.id;
-        return decodePayload(row.payload);
+        return decodeValue(row.value);
       } catch (error) {
         onError("load", error);
         return [];
@@ -626,7 +626,7 @@ function createObjectStackUserStateAdapter(options) {
         if (cachedRowId !== null) {
           try {
             await dataSource.update(resource, cachedRowId, {
-              payload: items,
+              value: items,
               updated_at: now
             });
             return;
@@ -639,15 +639,15 @@ function createObjectStackUserStateAdapter(options) {
         if (existing && existing.id !== void 0 && existing.id !== null) {
           cachedRowId = existing.id;
           await dataSource.update(resource, existing.id, {
-            payload: items,
+            value: items,
             updated_at: now
           });
           return;
         }
         const created = await dataSource.create(resource, {
           user_id: userId,
-          kind,
-          payload: items,
+          key,
+          value: items,
           updated_at: now
         });
         const newId = created?.id;

package/dist/index.d.cts

@@ -319,36 +319,45 @@ declare function generateContractManifest(contract: PluginContract): Record<stri
  * ObjectStack-backed `UserDataAdapter` factory.
  *
  * Persists arbitrary per-user UI state (favorites, recently-accessed items, …)
- * as a single JSON blob per `(user_id, kind)` row in an object named
- * `user_app_state`. The single-blob approach keeps round-trips down (one
- * `find` + one `update`/`create` per change) and matches the
- * "save the full list" semantics of `FavoritesProvider` / `RecentItemsProvider`.
+ * as a single JSON blob per `(user_id, key)` row in the **unified per-user
+ * KV store** — the `sys_user_preference` object shipped by every
+ * `@objectstack/plugin-auth`-enabled environment.
  *
- * ## Required object schema
+ * Using the existing `sys_user_preference` table (rather than a parallel
+ * `user_app_state` table) keeps things consistent with the platform's
+ * "one KV store per scope" pattern:
  *
- * Configure an object in ObjectStack with at least the following fields:
+ *   - `sys_setting`         ← tenant / env scope
+ *   - `sys_user_preference` ← per-user scope  ← we live here
+ *
+ * Callers are encouraged to namespace their keys (e.g. `ui.favorites`,
+ * `ui.recent`, `ui.grid.account.state`) so explicit settings (`theme`,
+ * `locale`) and machine-written UI traces stay easy to tell apart.
+ *
+ * ## Schema this adapter expects
+ *
+ * The canonical `sys_user_preference` schema (from
+ * `@objectstack/platform-objects`):
  *
  * ```yaml
- * object: user_app_state
+ * object: sys_user_preference
  * fields:
- *   user_id:    string   # indexed
- *   kind:       string   # indexed  (e.g. "favorites" | "recent")
- *   payload:    json     # the serialised list
- *   updated_at: datetime # (optional) auto-managed
- * unique: [user_id, kind]
+ *   user_id:    lookup(sys_user)  # indexed
+ *   key:        string            # indexed  (e.g. "ui.favorites")
+ *   value:      json              # the serialised list
+ *   updated_at: datetime          # auto-managed
+ * unique: [user_id, key]
  * ```
  *
  * ## Failure modes
  *
- * The adapter is designed to **degrade silently**. Any error — missing schema,
- * 4xx/5xx, network — is caught:
+ * The adapter is designed to **degrade silently**. Any error — missing
+ * schema, 4xx/5xx, network — is caught:
  *
  * - `load()` returns `[]`, so the hosting provider keeps its localStorage state.
  * - `save()` resolves without throwing, so UI mutations never surface a toast.
  *
- * This means an OSS user who hasn't yet provisioned the `user_app_state`
- * object still gets a perfectly working (localStorage-only) favorites /
- * recent-items experience. As soon as the object exists, persistence
+ * As soon as the backend supports `sys_user_preference`, persistence
  * "lights up" with no code change.
  *
  * @module
@@ -359,9 +368,13 @@ interface ObjectStackUserStateAdapterOptions {
     dataSource: DataSource<any>;
     /** Authenticated user id. */
     userId: string;
-    /** Logical bucket key, e.g. `"favorites"` or `"recent"`. */
-    kind: string;
-    /** Override the storage object name. Defaults to `"user_app_state"`. */
+    /**
+     * Storage key. Should be a dotted, namespaced string so UI traces
+     * don't collide with user-facing preferences. Examples:
+     * `ui.favorites`, `ui.recent`, `ui.grid.account.state`.
+     */
+    key: string;
+    /** Override the storage object name. Defaults to `"sys_user_preference"`. */
     resource?: string;
     /**
      * Optional console logger for development diagnostics. Defaults to noop so
@@ -376,8 +389,8 @@ interface UserDataAdapter<T> {
 /**
  * Build a `UserDataAdapter<T>` backed by ObjectStack.
  *
- * Each adapter instance is bound to a single `(user, kind)` pair; create one
- * per slot you want to persist.
+ * Each adapter instance is bound to a single `(user, key)` pair; create
+ * one per slot you want to persist.
  */
 declare function createObjectStackUserStateAdapter<T = unknown>(options: ObjectStackUserStateAdapterOptions): UserDataAdapter<T>;
 

package/dist/index.d.ts

@@ -319,36 +319,45 @@ declare function generateContractManifest(contract: PluginContract): Record<stri
  * ObjectStack-backed `UserDataAdapter` factory.
  *
  * Persists arbitrary per-user UI state (favorites, recently-accessed items, …)
- * as a single JSON blob per `(user_id, kind)` row in an object named
- * `user_app_state`. The single-blob approach keeps round-trips down (one
- * `find` + one `update`/`create` per change) and matches the
- * "save the full list" semantics of `FavoritesProvider` / `RecentItemsProvider`.
+ * as a single JSON blob per `(user_id, key)` row in the **unified per-user
+ * KV store** — the `sys_user_preference` object shipped by every
+ * `@objectstack/plugin-auth`-enabled environment.
  *
- * ## Required object schema
+ * Using the existing `sys_user_preference` table (rather than a parallel
+ * `user_app_state` table) keeps things consistent with the platform's
+ * "one KV store per scope" pattern:
  *
- * Configure an object in ObjectStack with at least the following fields:
+ *   - `sys_setting`         ← tenant / env scope
+ *   - `sys_user_preference` ← per-user scope  ← we live here
+ *
+ * Callers are encouraged to namespace their keys (e.g. `ui.favorites`,
+ * `ui.recent`, `ui.grid.account.state`) so explicit settings (`theme`,
+ * `locale`) and machine-written UI traces stay easy to tell apart.
+ *
+ * ## Schema this adapter expects
+ *
+ * The canonical `sys_user_preference` schema (from
+ * `@objectstack/platform-objects`):
  *
  * ```yaml
- * object: user_app_state
+ * object: sys_user_preference
  * fields:
- *   user_id:    string   # indexed
- *   kind:       string   # indexed  (e.g. "favorites" | "recent")
- *   payload:    json     # the serialised list
- *   updated_at: datetime # (optional) auto-managed
- * unique: [user_id, kind]
+ *   user_id:    lookup(sys_user)  # indexed
+ *   key:        string            # indexed  (e.g. "ui.favorites")
+ *   value:      json              # the serialised list
+ *   updated_at: datetime          # auto-managed
+ * unique: [user_id, key]
  * ```
  *
  * ## Failure modes
  *
- * The adapter is designed to **degrade silently**. Any error — missing schema,
- * 4xx/5xx, network — is caught:
+ * The adapter is designed to **degrade silently**. Any error — missing
+ * schema, 4xx/5xx, network — is caught:
  *
  * - `load()` returns `[]`, so the hosting provider keeps its localStorage state.
  * - `save()` resolves without throwing, so UI mutations never surface a toast.
  *
- * This means an OSS user who hasn't yet provisioned the `user_app_state`
- * object still gets a perfectly working (localStorage-only) favorites /
- * recent-items experience. As soon as the object exists, persistence
+ * As soon as the backend supports `sys_user_preference`, persistence
  * "lights up" with no code change.
  *
  * @module
@@ -359,9 +368,13 @@ interface ObjectStackUserStateAdapterOptions {
     dataSource: DataSource<any>;
     /** Authenticated user id. */
     userId: string;
-    /** Logical bucket key, e.g. `"favorites"` or `"recent"`. */
-    kind: string;
-    /** Override the storage object name. Defaults to `"user_app_state"`. */
+    /**
+     * Storage key. Should be a dotted, namespaced string so UI traces
+     * don't collide with user-facing preferences. Examples:
+     * `ui.favorites`, `ui.recent`, `ui.grid.account.state`.
+     */
+    key: string;
+    /** Override the storage object name. Defaults to `"sys_user_preference"`. */
     resource?: string;
     /**
      * Optional console logger for development diagnostics. Defaults to noop so
@@ -376,8 +389,8 @@ interface UserDataAdapter<T> {
 /**
  * Build a `UserDataAdapter<T>` backed by ObjectStack.
  *
- * Each adapter instance is bound to a single `(user, kind)` pair; create one
- * per slot you want to persist.
+ * Each adapter instance is bound to a single `(user, key)` pair; create
+ * one per slot you want to persist.
  */
 declare function createObjectStackUserStateAdapter<T = unknown>(options: ObjectStackUserStateAdapterOptions): UserDataAdapter<T>;
 

package/dist/index.js

@@ -526,12 +526,12 @@ function generateContractManifest(contract) {
 }
 
 // src/userState.ts
-var DEFAULT_RESOURCE = "user_app_state";
+var DEFAULT_RESOURCE = "sys_user_preference";
 function createObjectStackUserStateAdapter(options) {
   const {
     dataSource,
     userId,
-    kind,
+    key,
     resource = DEFAULT_RESOURCE,
     onError = () => {
     }
@@ -541,7 +541,7 @@ function createObjectStackUserStateAdapter(options) {
     const params = {
       filter: {
         user_id: userId,
-        kind
+        key
       },
       limit: 1
     };
@@ -549,11 +549,11 @@ function createObjectStackUserStateAdapter(options) {
     const rows = result?.data ?? [];
     return rows.length > 0 ? rows[0] : null;
   };
-  const decodePayload = (payload) => {
-    if (Array.isArray(payload)) return payload;
-    if (typeof payload === "string") {
+  const decodeValue = (value) => {
+    if (Array.isArray(value)) return value;
+    if (typeof value === "string") {
       try {
-        const parsed = JSON.parse(payload);
+        const parsed = JSON.parse(value);
         return Array.isArray(parsed) ? parsed : [];
       } catch {
         return [];
@@ -570,7 +570,7 @@ function createObjectStackUserStateAdapter(options) {
           return [];
         }
         if (row.id !== void 0 && row.id !== null) cachedRowId = row.id;
-        return decodePayload(row.payload);
+        return decodeValue(row.value);
       } catch (error) {
         onError("load", error);
         return [];
@@ -582,7 +582,7 @@ function createObjectStackUserStateAdapter(options) {
         if (cachedRowId !== null) {
           try {
             await dataSource.update(resource, cachedRowId, {
-              payload: items,
+              value: items,
               updated_at: now
             });
             return;
@@ -595,15 +595,15 @@ function createObjectStackUserStateAdapter(options) {
         if (existing && existing.id !== void 0 && existing.id !== null) {
           cachedRowId = existing.id;
           await dataSource.update(resource, existing.id, {
-            payload: items,
+            value: items,
             updated_at: now
           });
           return;
         }
         const created = await dataSource.create(resource, {
           user_id: userId,
-          kind,
-          payload: items,
+          key,
+          value: items,
           updated_at: now
         });
         const newId = created?.id;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@object-ui/data-objectstack",
-  "version": "4.8.0",
+  "version": "5.0.0",
   "description": "ObjectStack Data Adapter for Object UI",
   "license": "MIT",
   "type": "module",
@@ -23,8 +23,8 @@
   ],
   "dependencies": {
     "@objectstack/client": "^4.0.5",
-    "@object-ui/core": "4.8.0",
-    "@object-ui/types": "4.8.0"
+    "@object-ui/core": "5.0.0",
+    "@object-ui/types": "5.0.0"
   },
   "devDependencies": {
     "tsup": "^8.5.1",

package/src/userState.test.ts

@@ -27,67 +27,67 @@ describe('createObjectStackUserStateAdapter', () => {
   });
 
   describe('load', () => {
-    it('returns [] when no row exists for the (user, kind) pair', async () => {
+    it('returns [] when no row exists for the (user, key) pair', async () => {
       const ds = mockDataSource();
       const adapter = createObjectStackUserStateAdapter({
         dataSource: ds,
         userId: 'u1',
-        kind: 'favorites',
+        key: 'ui.favorites',
       });
 
       const items = await adapter.load();
 
       expect(items).toEqual([]);
-      expect(ds.find).toHaveBeenCalledWith('user_app_state', {
-        filter: { user_id: 'u1', kind: 'favorites' },
+      expect(ds.find).toHaveBeenCalledWith('sys_user_preference', {
+        filter: { user_id: 'u1', key: 'ui.favorites' },
         limit: 1,
       });
     });
 
-    it('returns parsed payload when row exists (array payload)', async () => {
-      const payload = [{ id: 'object:contact', label: 'Contact' }];
+    it('returns parsed value when row exists (array value)', async () => {
+      const value = [{ id: 'object:contact', label: 'Contact' }];
       const ds = mockDataSource({
         find: vi.fn().mockResolvedValue({
-          data: [{ id: 'row-1', user_id: 'u1', kind: 'recent', payload }],
+          data: [{ id: 'row-1', user_id: 'u1', key: 'ui.recent', value }],
         }) as any,
       });
 
       const adapter = createObjectStackUserStateAdapter({
         dataSource: ds,
         userId: 'u1',
-        kind: 'recent',
+        key: 'ui.recent',
       });
 
-      await expect(adapter.load()).resolves.toEqual(payload);
+      await expect(adapter.load()).resolves.toEqual(value);
     });
 
-    it('parses string-encoded JSON payloads', async () => {
+    it('parses string-encoded JSON values', async () => {
       const items = [{ id: 'a' }, { id: 'b' }];
       const ds = mockDataSource({
         find: vi.fn().mockResolvedValue({
-          data: [{ id: 1, payload: JSON.stringify(items) }],
+          data: [{ id: 1, value: JSON.stringify(items) }],
         }) as any,
       });
 
       const adapter = createObjectStackUserStateAdapter({
         dataSource: ds,
         userId: 'u',
-        kind: 'k',
+        key: 'k',
       });
 
       await expect(adapter.load()).resolves.toEqual(items);
     });
 
-    it('returns [] when payload is malformed JSON', async () => {
+    it('returns [] when value is malformed JSON', async () => {
       const ds = mockDataSource({
         find: vi.fn().mockResolvedValue({
-          data: [{ id: 1, payload: '{not json' }],
+          data: [{ id: 1, value: '{not json' }],
         }) as any,
       });
       const adapter = createObjectStackUserStateAdapter({
         dataSource: ds,
         userId: 'u',
-        kind: 'k',
+        key: 'k',
       });
 
       await expect(adapter.load()).resolves.toEqual([]);
@@ -102,7 +102,7 @@ describe('createObjectStackUserStateAdapter', () => {
       const adapter = createObjectStackUserStateAdapter({
         dataSource: ds,
         userId: 'u',
-        kind: 'k',
+        key: 'k',
         onError,
       });
 
@@ -115,7 +115,7 @@ describe('createObjectStackUserStateAdapter', () => {
       const adapter = createObjectStackUserStateAdapter({
         dataSource: ds,
         userId: 'u',
-        kind: 'k',
+        key: 'k',
         resource: 'my_prefs',
       });
 
@@ -135,15 +135,15 @@ describe('createObjectStackUserStateAdapter', () => {
       const adapter = createObjectStackUserStateAdapter({
         dataSource: ds,
         userId: 'u1',
-        kind: 'favorites',
+        key: 'ui.favorites',
       });
 
       await adapter.save([{ id: 'a' } as any]);
 
-      expect(ds.create).toHaveBeenCalledWith('user_app_state', {
+      expect(ds.create).toHaveBeenCalledWith('sys_user_preference', {
         user_id: 'u1',
-        kind: 'favorites',
-        payload: [{ id: 'a' }],
+        key: 'ui.favorites',
+        value: [{ id: 'a' }],
         updated_at: expect.any(String),
       });
     });
@@ -151,20 +151,20 @@ describe('createObjectStackUserStateAdapter', () => {
     it('updates the existing row when one exists', async () => {
       const ds = mockDataSource({
         find: vi.fn().mockResolvedValue({
-          data: [{ id: 'row-99', user_id: 'u', kind: 'k', payload: [] }],
+          data: [{ id: 'row-99', user_id: 'u', key: 'k', value: [] }],
         }) as any,
       });
 
       const adapter = createObjectStackUserStateAdapter({
         dataSource: ds,
         userId: 'u',
-        kind: 'k',
+        key: 'k',
       });
 
       await adapter.save([{ id: 'x' } as any]);
 
-      expect(ds.update).toHaveBeenCalledWith('user_app_state', 'row-99', {
-        payload: [{ id: 'x' }],
+      expect(ds.update).toHaveBeenCalledWith('sys_user_preference', 'row-99', {
+        value: [{ id: 'x' }],
         updated_at: expect.any(String),
       });
       expect(ds.create).not.toHaveBeenCalled();
@@ -173,14 +173,14 @@ describe('createObjectStackUserStateAdapter', () => {
     it('uses the cached row id from a previous load on subsequent saves', async () => {
       const ds = mockDataSource({
         find: vi.fn().mockResolvedValue({
-          data: [{ id: 'row-42', payload: [] }],
+          data: [{ id: 'row-42', value: [] }],
         }) as any,
       });
 
       const adapter = createObjectStackUserStateAdapter({
         dataSource: ds,
         userId: 'u',
-        kind: 'k',
+        key: 'k',
       });
 
       await adapter.load();
@@ -190,13 +190,13 @@ describe('createObjectStackUserStateAdapter', () => {
 
       // No second find() — went straight to update via cached id.
       expect(ds.find).not.toHaveBeenCalled();
-      expect(ds.update).toHaveBeenCalledWith('user_app_state', 'row-42', expect.any(Object));
+      expect(ds.update).toHaveBeenCalledWith('sys_user_preference', 'row-42', expect.any(Object));
     });
 
     it('falls back to insert when cached row update fails (row deleted server-side)', async () => {
       const ds = mockDataSource({
         find: vi.fn()
-          .mockResolvedValueOnce({ data: [{ id: 'stale', payload: [] }] })
+          .mockResolvedValueOnce({ data: [{ id: 'stale', value: [] }] })
           .mockResolvedValueOnce({ data: [] }) as any,
         update: vi.fn().mockRejectedValue(new Error('not found')) as any,
         create: vi.fn().mockResolvedValue({ id: 'new' }) as any,
@@ -206,7 +206,7 @@ describe('createObjectStackUserStateAdapter', () => {
       const adapter = createObjectStackUserStateAdapter({
         dataSource: ds,
         userId: 'u',
-        kind: 'k',
+        key: 'k',
         onError,
       });
 
@@ -214,10 +214,10 @@ describe('createObjectStackUserStateAdapter', () => {
       await adapter.save([{ id: 'z' } as any]);
 
       expect(ds.update).toHaveBeenCalledTimes(1);
-      expect(ds.create).toHaveBeenCalledWith('user_app_state', expect.objectContaining({
+      expect(ds.create).toHaveBeenCalledWith('sys_user_preference', expect.objectContaining({
         user_id: 'u',
-        kind: 'k',
-        payload: [{ id: 'z' }],
+        key: 'k',
+        value: [{ id: 'z' }],
       }));
     });
 
@@ -230,7 +230,7 @@ describe('createObjectStackUserStateAdapter', () => {
       const adapter = createObjectStackUserStateAdapter({
         dataSource: ds,
         userId: 'u',
-        kind: 'k',
+        key: 'k',
         onError,
       });
 

package/src/userState.ts

@@ -2,36 +2,45 @@
  * ObjectStack-backed `UserDataAdapter` factory.
  *
  * Persists arbitrary per-user UI state (favorites, recently-accessed items, …)
- * as a single JSON blob per `(user_id, kind)` row in an object named
- * `user_app_state`. The single-blob approach keeps round-trips down (one
- * `find` + one `update`/`create` per change) and matches the
- * "save the full list" semantics of `FavoritesProvider` / `RecentItemsProvider`.
+ * as a single JSON blob per `(user_id, key)` row in the **unified per-user
+ * KV store** — the `sys_user_preference` object shipped by every
+ * `@objectstack/plugin-auth`-enabled environment.
  *
- * ## Required object schema
+ * Using the existing `sys_user_preference` table (rather than a parallel
+ * `user_app_state` table) keeps things consistent with the platform's
+ * "one KV store per scope" pattern:
  *
- * Configure an object in ObjectStack with at least the following fields:
+ *   - `sys_setting`         ← tenant / env scope
+ *   - `sys_user_preference` ← per-user scope  ← we live here
+ *
+ * Callers are encouraged to namespace their keys (e.g. `ui.favorites`,
+ * `ui.recent`, `ui.grid.account.state`) so explicit settings (`theme`,
+ * `locale`) and machine-written UI traces stay easy to tell apart.
+ *
+ * ## Schema this adapter expects
+ *
+ * The canonical `sys_user_preference` schema (from
+ * `@objectstack/platform-objects`):
  *
  * ```yaml
- * object: user_app_state
+ * object: sys_user_preference
  * fields:
- *   user_id:    string   # indexed
- *   kind:       string   # indexed  (e.g. "favorites" | "recent")
- *   payload:    json     # the serialised list
- *   updated_at: datetime # (optional) auto-managed
- * unique: [user_id, kind]
+ *   user_id:    lookup(sys_user)  # indexed
+ *   key:        string            # indexed  (e.g. "ui.favorites")
+ *   value:      json              # the serialised list
+ *   updated_at: datetime          # auto-managed
+ * unique: [user_id, key]
  * ```
  *
  * ## Failure modes
  *
- * The adapter is designed to **degrade silently**. Any error — missing schema,
- * 4xx/5xx, network — is caught:
+ * The adapter is designed to **degrade silently**. Any error — missing
+ * schema, 4xx/5xx, network — is caught:
  *
  * - `load()` returns `[]`, so the hosting provider keeps its localStorage state.
  * - `save()` resolves without throwing, so UI mutations never surface a toast.
  *
- * This means an OSS user who hasn't yet provisioned the `user_app_state`
- * object still gets a perfectly working (localStorage-only) favorites /
- * recent-items experience. As soon as the object exists, persistence
+ * As soon as the backend supports `sys_user_preference`, persistence
  * "lights up" with no code change.
  *
  * @module
@@ -44,9 +53,13 @@ export interface ObjectStackUserStateAdapterOptions {
   dataSource: DataSource<any>;
   /** Authenticated user id. */
   userId: string;
-  /** Logical bucket key, e.g. `"favorites"` or `"recent"`. */
-  kind: string;
-  /** Override the storage object name. Defaults to `"user_app_state"`. */
+  /**
+   * Storage key. Should be a dotted, namespaced string so UI traces
+   * don't collide with user-facing preferences. Examples:
+   * `ui.favorites`, `ui.recent`, `ui.grid.account.state`.
+   */
+  key: string;
+  /** Override the storage object name. Defaults to `"sys_user_preference"`. */
   resource?: string;
   /**
    * Optional console logger for development diagnostics. Defaults to noop so
@@ -60,21 +73,21 @@ export interface UserDataAdapter<T> {
   save(items: T[]): Promise<void>;
 }
 
-interface UserStateRecord {
+interface UserPreferenceRecord {
   id?: string | number;
   user_id: string;
-  kind: string;
-  payload: unknown;
+  key: string;
+  value: unknown;
   updated_at?: string;
 }
 
-const DEFAULT_RESOURCE = 'user_app_state';
+const DEFAULT_RESOURCE = 'sys_user_preference';
 
 /**
  * Build a `UserDataAdapter<T>` backed by ObjectStack.
  *
- * Each adapter instance is bound to a single `(user, kind)` pair; create one
- * per slot you want to persist.
+ * Each adapter instance is bound to a single `(user, key)` pair; create
+ * one per slot you want to persist.
  */
 export function createObjectStackUserStateAdapter<T = unknown>(
   options: ObjectStackUserStateAdapterOptions,
@@ -82,7 +95,7 @@ export function createObjectStackUserStateAdapter<T = unknown>(
   const {
     dataSource,
     userId,
-    kind,
+    key,
     resource = DEFAULT_RESOURCE,
     onError = () => {},
   } = options;
@@ -91,25 +104,25 @@ export function createObjectStackUserStateAdapter<T = unknown>(
   // without re-querying. Reset on every successful load.
   let cachedRowId: string | number | null = null;
 
-  const findExisting = async (): Promise<UserStateRecord | null> => {
+  const findExisting = async (): Promise<UserPreferenceRecord | null> => {
     const params: QueryParams = {
       filter: {
         user_id: userId,
-        kind,
+        key,
       },
       limit: 1,
     };
     const result = await dataSource.find(resource, params);
-    const rows = (result?.data ?? []) as UserStateRecord[];
+    const rows = (result?.data ?? []) as UserPreferenceRecord[];
     return rows.length > 0 ? rows[0] : null;
   };
 
-  const decodePayload = (payload: unknown): T[] => {
+  const decodeValue = (value: unknown): T[] => {
     // The server may return the JSON column already parsed, or as a string.
-    if (Array.isArray(payload)) return payload as T[];
-    if (typeof payload === 'string') {
+    if (Array.isArray(value)) return value as T[];
+    if (typeof value === 'string') {
       try {
-        const parsed = JSON.parse(payload);
+        const parsed = JSON.parse(value);
         return Array.isArray(parsed) ? (parsed as T[]) : [];
       } catch {
         return [];
@@ -127,7 +140,7 @@ export function createObjectStackUserStateAdapter<T = unknown>(
           return [];
         }
         if (row.id !== undefined && row.id !== null) cachedRowId = row.id;
-        return decodePayload(row.payload);
+        return decodeValue(row.value);
       } catch (error) {
         onError('load', error);
         return [];
@@ -141,7 +154,7 @@ export function createObjectStackUserStateAdapter<T = unknown>(
         if (cachedRowId !== null) {
           try {
             await dataSource.update(resource, cachedRowId, {
-              payload: items,
+              value: items,
               updated_at: now,
             });
             return;
@@ -156,7 +169,7 @@ export function createObjectStackUserStateAdapter<T = unknown>(
         if (existing && existing.id !== undefined && existing.id !== null) {
           cachedRowId = existing.id;
           await dataSource.update(resource, existing.id, {
-            payload: items,
+            value: items,
             updated_at: now,
           });
           return;
@@ -164,11 +177,11 @@ export function createObjectStackUserStateAdapter<T = unknown>(
 
         const created = await dataSource.create(resource, {
           user_id: userId,
-          kind,
-          payload: items,
+          key,
+          value: items,
           updated_at: now,
         });
-        const newId = (created as UserStateRecord | undefined)?.id;
+        const newId = (created as UserPreferenceRecord | undefined)?.id;
         if (newId !== undefined && newId !== null) cachedRowId = newId;
       } catch (error) {
         onError('save', error);