Merge pull request 'codex/promote-grouped-stock-view' (#7) from codex/promote-grouped-stock-view into main

Reviewed-on: #7

README.md

@@ -137,7 +137,7 @@ Project-specific operating conventions for future contributors and coding agents
 - Active kitchen selection and switching
 - Dashboard with quick actions
 - Label creation flow with item lookup, location loading, preview, and stock entry creation
-- Stock list with search and filters
+- Grouped-first stock review with search and overview filters
 - Stock detail page with stock adjustment workflow
 - PWA manifest, icons, service worker, and offline fallback
 
@@ -165,6 +165,8 @@ Expected shapes today:
   Returns item definitions for autocomplete.
 - `GET /{database}/kitchen/items`
   Returns the current stock review list.
+- `GET /{database}/kitchen/items/grouped?expanded=0|1`
+  Returns grouped stock data; grouped review uses summary-first loading and hydrates item children in background.
 - `GET /{database}/kitchen/items/{uuid_b64}`
   Returns one item detail payload.
 - `GET /{database}/kitchen/changes`

package.json

@@ -1,6 +1,6 @@
 {
   "name": "lonc-web",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "private": true,
   "type": "module",
   "scripts": {

src/api/stock.js

@@ -21,7 +21,24 @@ export async function searchItemDefinitions(store, query) {
 }
 
 export async function listStockEntries(store, filters = {}) {
-  const payload = await apiRequest(store, getPath('items'));
+  const query = {};
+  const searchName = filters.searchName || filters.search_name;
+  if (searchName) {
+    query.search_name = searchName;
+  }
+  if (filters.limit !== undefined && filters.limit !== null) {
+    query.limit = filters.limit;
+  }
+  if (filters.offset !== undefined && filters.offset !== null) {
+    query.offset = filters.offset;
+  }
+  if (filters.cursor) {
+    query.cursor = filters.cursor;
+  }
+
+  const payload = await apiRequest(store, getPath('items'), {
+    query,
+  });
 
   if (Array.isArray(payload)) {
     return payload;
@@ -30,9 +47,26 @@ export async function listStockEntries(store, filters = {}) {
   return payload?.data || payload?.entries || payload?.items || [];
 }
 
-export async function listGroupedStockEntries(store) {
+export async function listGroupedStockEntries(store, options = {}) {
+  const query = {};
+  const expanded = options.expanded ?? 1;
+  query.expanded = expanded;
+  const searchName = options.searchName || options.search_name;
+  if (searchName) {
+    query.search_name = searchName;
+  }
+  if (options.limit !== undefined && options.limit !== null) {
+    query.limit = options.limit;
+  }
+  if (options.offset !== undefined && options.offset !== null) {
+    query.offset = options.offset;
+  }
+  if (options.cursor) {
+    query.cursor = options.cursor;
+  }
+
   const payload = await apiRequest(store, `${getPath('items')}/grouped`, {
-    query: { expanded: 1 },
+    query,
   });
 
   if (Array.isArray(payload)) {

src/app/config.js

@@ -1,5 +1,5 @@
 export const APP_NAME = 'Lonc';
-export const APP_VERSION = typeof __APP_VERSION__ !== 'undefined' ? __APP_VERSION__ : '0.2.0';
+export const APP_VERSION = typeof __APP_VERSION__ !== 'undefined' ? __APP_VERSION__ : '0.2.1';
 export const TRYTON_APPLICATION = 'kitchen';
 
 export const CONNECTION_STATES = {
@@ -14,6 +14,7 @@ export const STORAGE_KEYS = {
   session: 'lonc.auth.session',
   activeKitchen: 'lonc.kitchen.active',
   labelDraft: 'lonc.labels.draft',
+  stockListContext: 'lonc.stock.list.context',
 };
 
 export const DEFAULT_CONFIG = {

src/styles/app.css

@@ -314,10 +314,112 @@ body {
   color: var(--lonc-primary);
 }
 
+.stock-filter-hub {
+  background:
+    linear-gradient(160deg, rgba(255, 255, 255, 0.94), rgba(245, 250, 255, 0.88)),
+    linear-gradient(135deg, rgba(93, 169, 255, 0.1), rgba(31, 75, 153, 0.06));
+}
+
+.stock-workspace {
+  align-items: flex-start;
+}
+
+.stock-results-pane {
+  min-width: 0;
+}
+
+.stock-filter-summary {
+  padding: 0.85rem 0.95rem;
+  border-radius: 0.9rem;
+  border: 1px dashed rgba(31, 75, 153, 0.24);
+  background: rgba(255, 255, 255, 0.7);
+  min-height: 100%;
+}
+
+.stock-filter-rail .overview-list-locations {
+  max-height: 18rem;
+}
+
+.stock-filter-rail .location-overview-columns {
+  grid-template-columns: 1fr;
+}
+
+@media (min-width: 768px) and (max-width: 1199.98px) {
+  .stock-filter-panels {
+    grid-template-columns: repeat(2, minmax(0, 1fr));
+    align-items: start;
+  }
+
+  .stock-filter-panels.stock-filter-panels-single-open {
+    grid-template-columns: 1fr;
+  }
+}
+
+@media (min-width: 1200px) {
+  .stock-filter-rail .stock-filter-hub {
+    position: sticky;
+    top: 1rem;
+  }
+}
+
 .stock-view-switch {
-  display: inline-flex;
+  display: grid;
-  flex-wrap: wrap;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
-  gap: 0.5rem;
+  gap: 0.65rem;
+}
+
+.stock-view-switch-wrap {
+  min-width: min(100%, 38rem);
+}
+
+.stock-view-tab {
+  display: grid;
+  align-content: start;
+  gap: 0.2rem;
+  text-align: left;
+  border: 1px solid var(--lonc-border);
+  border-radius: 0.9rem;
+  background: rgba(255, 255, 255, 0.66);
+  color: inherit;
+  padding: 0.65rem 0.85rem;
+  transition:
+    border-color 160ms ease,
+    box-shadow 160ms ease,
+    background-color 160ms ease,
+    transform 160ms ease;
+}
+
+.stock-view-tab:hover {
+  transform: translateY(-1px);
+  border-color: rgba(31, 75, 153, 0.24);
+  box-shadow: 0 8px 16px rgba(24, 42, 79, 0.08);
+}
+
+.stock-view-tab:focus-visible {
+  outline: 2px solid rgba(31, 75, 153, 0.4);
+  outline-offset: 2px;
+}
+
+.stock-view-tab-active {
+  border-color: rgba(31, 75, 153, 0.42);
+  background: rgba(31, 75, 153, 0.1);
+  box-shadow: inset 0 0 0 1px rgba(31, 75, 153, 0.18);
+}
+
+.stock-view-tab-title {
+  font-weight: 700;
+  font-size: 0.95rem;
+}
+
+.stock-view-tab-subtitle {
+  font-size: 0.78rem;
+  color: var(--lonc-muted);
+}
+
+@media (max-width: 767.98px) {
+  .stock-view-switch {
+    grid-template-columns: 1fr;
+  }
 }
 
 .overview-row-single-open > [class*='col-'] {
@@ -329,6 +431,16 @@ body {
   height: auto;
 }
 
+.stock-filter-panel-card {
+  border: 1px solid var(--lonc-border);
+  border-radius: 1rem;
+  background: rgba(255, 255, 255, 0.84);
+}
+
+.stock-filter-panel-card[open] {
+  box-shadow: 0 10px 24px rgba(24, 42, 79, 0.08);
+}
+
 .overview-summary {
   display: block;
   cursor: pointer;
@@ -592,21 +704,69 @@ button.legend-card:focus-visible {
   list-style: none;
 }
 
+.grouped-stock-summary-row {
+  min-height: 0;
+}
+
+.grouped-stock-summary-title {
+  font-size: 1.1rem;
+  line-height: 1.2;
+}
+
+.grouped-stock-summary-description {
+  margin: 0.12rem 0 0.35rem;
+}
+
 .grouped-stock-summary::-webkit-details-marker {
   display: none;
 }
 
 .grouped-stock-summary-meta {
   align-items: center;
+  align-content: flex-start;
+  column-gap: 0.95rem;
+  row-gap: 0.08rem;
+  line-height: 1.25;
+}
+
+.grouped-stock-summary-status {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  justify-content: flex-start;
+  gap: 0.4rem 0.75rem;
+}
+
+.grouped-stock-secondary-details {
+  border-top: 1px dashed rgba(31, 39, 64, 0.14);
+  padding-top: 0.75rem;
+}
+
+.grouped-stock-secondary-toggle {
+  border-radius: 0.85rem;
+  border: 1px solid var(--lonc-border);
+  padding: 0.5rem 0.75rem;
+  background: rgba(255, 255, 255, 0.66);
+}
+
+.grouped-stock-secondary-toggle > summary {
+  list-style: none;
+  cursor: pointer;
+}
+
+.grouped-stock-secondary-toggle > summary::-webkit-details-marker {
+  display: none;
 }
 
 .grouped-stock-toggle-label {
   color: var(--lonc-primary);
+  font-size: 0.8rem;
+  line-height: 1.1;
 }
 
 .grouped-stock-toggle-label::after {
   content: 'Expand';
-  margin-left: 0.35rem;
+  margin-left: 0.25rem;
 }
 
 .grouped-stock-card[open] .grouped-stock-toggle-label::after {
@@ -633,14 +793,20 @@ button.legend-card:focus-visible {
   border-left-color: #6c757d;
 }
 
+@media (min-width: 1200px) {
+  .grouped-stock-summary-status {
+    justify-content: flex-end;
+  }
+}
+
 .grouped-stock-items {
   display: grid;
-  gap: 0.75rem;
+  gap: 0.55rem;
 }
 
 .grouped-stock-item {
   display: block;
-  padding: 0.9rem 1rem;
+  padding: 0.65rem 0.8rem;
   border-radius: 0.95rem;
   border: 1px solid var(--lonc-border);
   background: rgba(255, 255, 255, 0.72);
@@ -677,12 +843,71 @@ button.legend-card:focus-visible {
   background: rgba(108, 117, 125, 0.08);
 }
 
-.grouped-stock-item-meta {
+.grouped-stock-item-row {
-  justify-content: flex-start;
+  display: grid;
+  grid-template-columns: minmax(0, 1fr) auto auto;
+  align-items: center;
+  gap: 0.75rem;
+}
+
+.grouped-stock-item-main {
+  min-width: 0;
+}
+
+.grouped-stock-item-title-line {
+  display: flex;
+  align-items: baseline;
+  justify-content: space-between;
+  gap: 0.6rem;
+}
+
+.grouped-stock-item-name {
+  font-size: 1rem;
+  line-height: 1.2;
+}
+
+.grouped-stock-item-id {
+  color: var(--lonc-muted);
+  font-size: 0.8rem;
+}
+
+.grouped-stock-item-aux {
+  display: grid;
+  gap: 0.2rem;
+  text-align: right;
+  justify-items: end;
+  white-space: nowrap;
+}
+
+.grouped-stock-item-actions {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  white-space: nowrap;
+}
+
+.grouped-stock-item-link {
+  font-size: 0.8rem;
+}
+
+.stock-item-link-disabled {
+  pointer-events: none;
+  opacity: 0.55;
+}
+
+.stock-item-refresh-indicator {
+  color: rgba(31, 39, 64, 0.78) !important;
+  font-weight: 600;
+  margin-top: 0.15rem;
+}
+
+.stock-item-refreshing {
+  opacity: 0.94;
 }
 
 .grouped-stock-mark-gone {
-  align-self: center;
+  padding: 0.2rem 0.55rem;
+  line-height: 1.2;
   white-space: nowrap;
 }
 
@@ -708,9 +933,62 @@ button.legend-card:focus-visible {
   font-weight: 700;
 }
 
-@media (min-width: 1200px) {
+.grouped-stock-close-row {
-  .grouped-stock-item-meta {
+  display: flex;
   justify-content: flex-end;
+  margin-top: 0.2rem;
+  padding-top: 0.2rem;
+  border-top: 1px dashed rgba(31, 39, 64, 0.12);
+}
+
+.grouped-stock-close {
+  padding: 0.1rem 0.2rem;
+  font-size: 0.78rem;
+  color: rgba(31, 39, 64, 0.82);
+  line-height: 1.1;
+}
+
+.grouped-stock-close:hover {
+  color: var(--lonc-primary-dark);
+}
+
+@media (max-width: 991.98px) {
+  .grouped-stock-item-row {
+    grid-template-columns: minmax(0, 1fr) auto;
+    align-items: start;
+  }
+
+  .grouped-stock-item-actions {
+    grid-column: 1 / -1;
+    justify-content: space-between;
+    padding-top: 0.15rem;
+  }
+
+  .grouped-stock-item-aux {
+    text-align: left;
+    justify-items: start;
+  }
+}
+
+@media (max-width: 575.98px) {
+  .grouped-stock-item {
+    padding: 0.6rem 0.7rem;
+  }
+
+  .grouped-stock-item-row {
+    grid-template-columns: 1fr;
+    gap: 0.4rem;
+  }
+
+  .grouped-stock-item-aux {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 0.5rem;
+    text-align: left;
+  }
+
+  .grouped-stock-item-title-line {
+    gap: 0.45rem;
   }
 }
 

tests/api/stock.test.js

@@ -15,6 +15,8 @@ vi.mock('../../src/api/client.js', () => ({
 
 const {
   applyItemUpsert,
+  listGroupedStockEntries,
+  listStockEntries,
   lookupItemByIdentifier,
   lookupItemDetails,
   listKitchenChanges,
@@ -28,6 +30,51 @@ describe('api/stock', () => {
     apiRequestMock.mockReset();
   });
 
+  it('listStockEntries forwards optional query filters', async () => {
+    apiRequestMock.mockResolvedValueOnce([]);
+
+    await listStockEntries(
+      { config: { database: 'db' } },
+      { searchName: 'Milk', limit: 20, offset: 40, cursor: 'cursor-1' },
+    );
+
+    expect(apiRequestMock).toHaveBeenCalledWith(
+      { config: { database: 'db' } },
+      'kitchen/items',
+      {
+        query: {
+          search_name: 'Milk',
+          limit: 20,
+          offset: 40,
+          cursor: 'cursor-1',
+        },
+      },
+    );
+  });
+
+  it('listGroupedStockEntries defaults to expanded=1 and forwards options', async () => {
+    apiRequestMock.mockResolvedValueOnce([]);
+
+    await listGroupedStockEntries(
+      { config: { database: 'db' } },
+      { expanded: 0, searchName: 'Rice', limit: 10, offset: 0, cursor: 'cursor-2' },
+    );
+
+    expect(apiRequestMock).toHaveBeenCalledWith(
+      { config: { database: 'db' } },
+      'kitchen/items/grouped',
+      {
+        query: {
+          expanded: 0,
+          search_name: 'Rice',
+          limit: 10,
+          offset: 0,
+          cursor: 'cursor-2',
+        },
+      },
+    );
+  });
+
   it('listKitchenChanges returns normalized changes payload', async () => {
     apiRequestMock.mockResolvedValueOnce({
       since: 'cursor-1',

tests/features/stock/mark-gone.test.js

@@ -70,4 +70,59 @@ describe('stock mark-gone behavior', () => {
       message: 'Flour was marked gone and removed from the list.',
     });
   });
+
+  it('stock list grouped markGone removes item from grouped and flat collections', async () => {
+    useStockItemMock.mockResolvedValueOnce({ status: 'used' });
+    const addAlert = vi.fn();
+    const data = stockListPageData({ addAlert, isConnected: false });
+
+    data.groupedEntries = [
+      {
+        id: 10,
+        uuid_b64: 'group-10',
+        name: 'Beans',
+        stock_type: 'measured',
+        location_initial_uuid_b64: null,
+        date: '2026-04-12',
+        expire_date: '2026-04-20',
+        items: [
+          {
+            id: 11,
+            uuid_b64: 'item-11',
+            name: 'Beans',
+            stock_type: 'measured',
+            quantity: 1,
+            location_initial_uuid_b64: null,
+            date: '2026-04-12',
+            expire_date: '2026-04-20',
+          },
+        ],
+      },
+    ].map((group) => data.indexGroup(group));
+    data.entries = [
+      data.indexEntry({
+        id: 11,
+        uuid_b64: 'item-11',
+        name: 'Beans',
+        stock_type: 'measured',
+        quantity: 1,
+        location_initial_uuid_b64: null,
+        date: '2026-04-12',
+        expire_date: '2026-04-20',
+      }),
+    ];
+    data.entriesVersion = 1;
+    data.groupedVersion = 1;
+    data.editForms = { 11: { level: 'plenty', quantity: 1 } };
+    data.editErrors = {};
+
+    await data.markGoneFromGroup(data.groupedEntries[0].items[0], data.groupedEntries[0]);
+
+    expect(data.entries).toEqual([]);
+    expect(data.groupedEntries).toEqual([]);
+    expect(addAlert).toHaveBeenCalledWith({
+      type: 'success',
+      message: 'Beans was marked gone and removed from the group.',
+    });
+  });
 });

tests/features/stock/stock-list-page-grouped.test.js

@@ -0,0 +1,418 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+const listStockEntriesMock = vi.fn();
+const listGroupedStockEntriesMock = vi.fn();
+const listKitchenChangesMock = vi.fn();
+const getStockEntryMock = vi.fn();
+const updateStockItemMock = vi.fn();
+const useStockItemMock = vi.fn();
+const fetchLocationsMock = vi.fn();
+
+vi.mock('../../../src/api/stock.js', () => ({
+  listStockEntries: (...args) => listStockEntriesMock(...args),
+  listGroupedStockEntries: (...args) => listGroupedStockEntriesMock(...args),
+  listKitchenChanges: (...args) => listKitchenChangesMock(...args),
+  getStockEntry: (...args) => getStockEntryMock(...args),
+  updateStockItem: (...args) => updateStockItemMock(...args),
+  useStockItem: (...args) => useStockItemMock(...args),
+}));
+
+vi.mock('../../../src/api/locations.js', () => ({
+  fetchLocations: (...args) => fetchLocationsMock(...args),
+}));
+
+const { stockListPageData } = await import('../../../src/features/stock/stock-list-page.js');
+
+function createGroupedSummary() {
+  return [
+    {
+      id: 10,
+      uuid_b64: 'group-10',
+      name: 'Rice',
+      description: 'Basmati',
+      stock_type: 'measured',
+      level: 'good',
+      quantity: 1,
+      uom_symbol: 'kg',
+      location_initial_uuid_b64: 'loc-root',
+      date: '2026-04-10',
+      expire_date: '2026-04-25',
+      first_expire_date: '2026-04-25',
+      first_production_date: '2026-04-10',
+      items_count: 1,
+      items: [],
+    },
+  ];
+}
+
+function createGroupedExpanded() {
+  return [
+    {
+      ...createGroupedSummary()[0],
+      items: [
+        {
+          id: 100,
+          uuid_b64: 'item-100',
+          name: 'Rice',
+          description: 'Open bag',
+          stock_type: 'measured',
+          level: 'good',
+          quantity: 1,
+          uom_symbol: 'kg',
+          location_initial_uuid_b64: 'loc-root',
+          date: '2026-04-10',
+          expire_date: '2026-04-25',
+          expire_in: 13,
+        },
+      ],
+    },
+  ];
+}
+
+function createWindowMock() {
+  const intervals = new Map();
+  let nextId = 1;
+  const storage = new Map();
+
+  return {
+    location: { hash: '#/stock' },
+    scrollY: 1,
+    setInterval: vi.fn((fn) => {
+      const id = nextId;
+      nextId += 1;
+      intervals.set(id, fn);
+      return id;
+    }),
+    clearInterval: vi.fn((id) => {
+      intervals.delete(id);
+    }),
+    addEventListener: vi.fn(),
+    removeEventListener: vi.fn(),
+    matchMedia: vi.fn(() => ({ matches: false })),
+    scrollTo: vi.fn(),
+    localStorage: {
+      getItem: vi.fn((key) => storage.get(key) ?? null),
+      setItem: vi.fn((key, value) => {
+        storage.set(key, value);
+      }),
+      removeItem: vi.fn((key) => {
+        storage.delete(key);
+      }),
+    },
+    __intervals: intervals,
+  };
+}
+
+describe('stock list grouped-first behavior', () => {
+  beforeEach(() => {
+    listStockEntriesMock.mockReset();
+    listGroupedStockEntriesMock.mockReset();
+    listKitchenChangesMock.mockReset();
+    getStockEntryMock.mockReset();
+    updateStockItemMock.mockReset();
+    useStockItemMock.mockReset();
+    fetchLocationsMock.mockReset();
+
+    globalThis.window = createWindowMock();
+    globalThis.requestAnimationFrame = (callback) => callback();
+    globalThis.HTMLDetailsElement = class MockDetailsElement {};
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    delete globalThis.window;
+    delete globalThis.requestAnimationFrame;
+    delete globalThis.HTMLDetailsElement;
+    delete globalThis.structuredClone;
+  });
+
+  it('defaults to grouped mode and loads grouped summary before lazy item list', async () => {
+    listGroupedStockEntriesMock
+      .mockResolvedValueOnce(createGroupedSummary())
+      .mockResolvedValueOnce(createGroupedExpanded());
+    listStockEntriesMock.mockResolvedValueOnce([]);
+    listKitchenChangesMock.mockResolvedValue({ since: null, nextCursor: null, changes: [] });
+    fetchLocationsMock.mockResolvedValue({ flat: [], tree: [] });
+
+    const store = { isConnected: true, addAlert: vi.fn() };
+    const data = stockListPageData(store);
+    data.$nextTick = vi.fn(async () => {});
+
+    await data.init();
+
+    expect(data.viewMode).toBe('grouped');
+    expect(listGroupedStockEntriesMock).toHaveBeenNthCalledWith(1, store, { expanded: 0 });
+    expect(listStockEntriesMock).not.toHaveBeenCalled();
+
+    await Promise.resolve();
+
+    expect(listGroupedStockEntriesMock).toHaveBeenNthCalledWith(2, store, { expanded: 1 });
+
+    await data.switchView('items');
+    expect(listStockEntriesMock).toHaveBeenCalledTimes(1);
+
+    await data.switchView('grouped');
+    await data.switchView('items');
+    expect(listStockEntriesMock).toHaveBeenCalledTimes(1);
+  });
+
+  it('hydrates grouped children in background and merges into existing groups', async () => {
+    listGroupedStockEntriesMock
+      .mockResolvedValueOnce(createGroupedSummary())
+      .mockResolvedValueOnce(createGroupedExpanded());
+
+    const data = stockListPageData({ isConnected: true, addAlert: vi.fn() });
+    await data.loadGroupedEntries({ expanded: 0, resetVisible: true });
+
+    expect(data.groupedEntries[0].items).toEqual([]);
+
+    await data.hydrateGroupedEntriesInBackground();
+
+    expect(data.groupedHydrated).toBe(true);
+    expect(data.groupedEntries[0].items).toHaveLength(1);
+  });
+
+  it('memoizes filtered results and invalidates when filters change', () => {
+    const data = stockListPageData({ isConnected: true, addAlert: vi.fn() });
+    data.entries = [
+      data.indexEntry({
+        id: 1,
+        uuid_b64: 'item-1',
+        name: 'Milk',
+        description: 'Fresh',
+        location_initial_uuid_b64: null,
+        stock_type: 'binary',
+        level: 'good',
+      }),
+    ];
+    data.entriesVersion = 1;
+
+    const first = data.filteredEntries;
+    const second = data.filteredEntries;
+
+    expect(second).toBe(first);
+
+    data.filters.search = 'milk';
+
+    const third = data.filteredEntries;
+    expect(third).not.toBe(first);
+    expect(third).toHaveLength(1);
+  });
+
+  it('keeps grouped data visible while background summary refresh is in progress', async () => {
+    let resolveRefresh;
+    const refreshPromise = new Promise((resolve) => {
+      resolveRefresh = resolve;
+    });
+
+    listGroupedStockEntriesMock.mockImplementationOnce(() => refreshPromise);
+
+    const data = stockListPageData({ isConnected: true, addAlert: vi.fn() });
+    data.groupedLoaded = true;
+    data.groupedEntries = createGroupedSummary().map((group) => data.indexGroup(group));
+
+    const pending = data.loadGroupedEntries({ expanded: 0, background: true });
+
+    expect(data.state.isRefreshing).toBe(true);
+    expect(data.groupedEntries).toHaveLength(1);
+
+    resolveRefresh(createGroupedSummary());
+    await pending;
+
+    expect(data.state.isRefreshing).toBe(false);
+    expect(data.groupedEntries).toHaveLength(1);
+  });
+
+  it('poll refreshes view only when new changes exist', async () => {
+    listKitchenChangesMock
+      .mockResolvedValueOnce({ since: 'a', nextCursor: 'b', changes: [] })
+      .mockResolvedValueOnce({
+        since: 'b',
+        nextCursor: 'c',
+        changes: [{ type: 'stock', action: 'use', timestamp: '2026-04-12T08:00:00Z' }],
+      });
+
+    const data = stockListPageData({ isConnected: true, addAlert: vi.fn() });
+    const refreshSpy = vi.fn(async () => {});
+    data.refreshCurrentView = refreshSpy;
+
+    await data.pollKitchenChanges();
+    expect(refreshSpy).not.toHaveBeenCalled();
+
+    await data.pollKitchenChanges();
+    expect(refreshSpy).toHaveBeenCalledTimes(1);
+    expect(refreshSpy).toHaveBeenCalledWith({ background: true });
+  });
+
+  it('tracks grouped card open state from details toggle events', () => {
+    const data = stockListPageData({ isConnected: true, addAlert: vi.fn() });
+
+    class MockDetails extends HTMLDetailsElement {
+      constructor() {
+        super();
+        this.open = true;
+        this.dataset = { groupId: '10' };
+      }
+
+      querySelector() {
+        return {
+          scrollIntoView: vi.fn(),
+        };
+      }
+    }
+
+    const details = new MockDetails();
+
+    data.handleGroupedToggle({ target: details });
+    expect(data.isGroupedCardOpen(10)).toBe(true);
+
+    details.open = false;
+    data.handleGroupedToggle({ target: details });
+    expect(data.isGroupedCardOpen(10)).toBe(false);
+  });
+
+  it('restores from runtime cache on back navigation and refreshes only focused item', async () => {
+    listKitchenChangesMock.mockResolvedValue({ since: null, nextCursor: null, changes: [] });
+    getStockEntryMock.mockResolvedValueOnce({
+      id: 100,
+      uuid_b64: 'item-100',
+      name: 'Rice',
+      description: 'Open bag',
+      stock_type: 'measured',
+      level: 'good',
+      quantity: 2,
+      uom_symbol: 'kg',
+      location_initial_uuid_b64: 'loc-root',
+      date: '2026-04-12',
+      expire_date: '2026-04-20',
+      expire_in: 8,
+    });
+
+    const store = {
+      isConnected: true,
+      addAlert: vi.fn(),
+      activeKitchen: { id: 1 },
+    };
+    const firstVisit = stockListPageData(store);
+    firstVisit.entries = [
+      firstVisit.indexEntry({
+        id: 100,
+        uuid_b64: 'item-100',
+        name: 'Rice',
+        description: 'Open bag',
+        stock_type: 'measured',
+        level: 'good',
+        quantity: 1,
+        uom_symbol: 'kg',
+        location_initial_uuid_b64: 'loc-root',
+        date: '2026-04-10',
+        expire_date: '2026-04-25',
+        expire_in: 13,
+      }),
+    ];
+    firstVisit.entriesVersion = 1;
+    firstVisit.itemsLoaded = true;
+    firstVisit.groupedEntries = createGroupedExpanded().map((group) => firstVisit.indexGroup(group));
+    firstVisit.groupedVersion = 1;
+    firstVisit.groupedLoaded = true;
+    firstVisit.groupedHydrated = true;
+    firstVisit.locations = [
+      {
+        id: 1,
+        uuid_b64: 'loc-root',
+        name: 'Pantry',
+        pathLabel: 'Pantry',
+        depth: 0,
+        type: 'storage',
+        lineage_uuid_b64: ['loc-root'],
+      },
+    ];
+    firstVisit.locationsVersion = 1;
+    firstVisit.locationMap = { 'loc-root': 'Pantry' };
+    firstVisit.locationDescendants = { 'loc-root': ['loc-root'] };
+    firstVisit.locationLineage = { 'loc-root': ['loc-root'] };
+    firstVisit.viewMode = 'grouped';
+    firstVisit.filters.search = 'rice';
+    firstVisit.rememberStockListContext('item-100');
+
+    const returnVisit = stockListPageData(store);
+    returnVisit.$nextTick = vi.fn(async () => {});
+
+    await returnVisit.init();
+    await Promise.resolve();
+    await Promise.resolve();
+
+    expect(listGroupedStockEntriesMock).not.toHaveBeenCalled();
+    expect(listStockEntriesMock).not.toHaveBeenCalled();
+    expect(fetchLocationsMock).not.toHaveBeenCalled();
+    expect(getStockEntryMock).toHaveBeenCalledWith(store, 'item-100');
+    expect(returnVisit.entries[0].quantity).toBe(2);
+    expect(returnVisit.groupedEntries[0].items[0].quantity).toBe(2);
+    expect(returnVisit.groupedEntries[0].quantity).toBe(2);
+    expect(returnVisit.groupedEntries[0].first_expire_date).toBe('2026-04-20');
+    expect(returnVisit.groupedEntries[0].date).toBe('2026-04-12');
+  });
+
+  it('tracks item-level refresh state while focused item refresh is in progress', async () => {
+    let resolveEntry;
+    getStockEntryMock.mockImplementationOnce(
+      () =>
+        new Promise((resolve) => {
+          resolveEntry = resolve;
+        }),
+    );
+
+    const data = stockListPageData({ isConnected: true, addAlert: vi.fn() });
+    data.entries = [
+      data.indexEntry({
+        id: 100,
+        uuid_b64: 'item-100',
+        name: 'Rice',
+        description: 'Open bag',
+        stock_type: 'measured',
+        level: 'good',
+        quantity: 1,
+        uom_symbol: 'kg',
+        location_initial_uuid_b64: 'loc-root',
+        date: '2026-04-10',
+        expire_date: '2026-04-25',
+      }),
+    ];
+    data.entriesVersion = 1;
+    data.itemsLoaded = true;
+
+    const pending = data.refreshFocusedItemInBackground('item-100');
+    expect(data.isItemRefreshing('item-100')).toBe(true);
+
+    resolveEntry({
+      ...data.entries[0],
+      quantity: 3,
+    });
+    await pending;
+
+    expect(data.isItemRefreshing('item-100')).toBe(false);
+    expect(data.entries[0].quantity).toBe(3);
+  });
+
+  it('falls back when structuredClone throws during runtime cache snapshot', async () => {
+    globalThis.structuredClone = vi.fn(() => {
+      throw new Error('The object can not be cloned.');
+    });
+
+    listGroupedStockEntriesMock
+      .mockResolvedValueOnce(createGroupedSummary())
+      .mockResolvedValueOnce(createGroupedExpanded());
+    listKitchenChangesMock.mockResolvedValue({ since: null, nextCursor: null, changes: [] });
+    fetchLocationsMock.mockResolvedValue({ flat: [], tree: [] });
+
+    const store = { isConnected: true, addAlert: vi.fn() };
+    const data = stockListPageData(store);
+    data.$nextTick = vi.fn(async () => {});
+
+    await data.init();
+    await Promise.resolve();
+
+    expect(data.state.error).toBe('');
+    expect(data.groupedEntries.length).toBeGreaterThan(0);
+  });
+});