@globalbrain/sefirot 4.51.0 → 4.52.1

package/lib/blocks/lens/components/LensCatalog.vue

@@ -7,11 +7,13 @@ import { useMutation, useQuery } from '../../../composables/Api'
 import { useLang, useTrans } from '../../../composables/Lang'
 import { usePower } from '../../../composables/Power'
 import { useSnackbars } from '../../../stores/Snackbars'
+import { day } from '../../../support/Day'
 import { type FieldData } from '../FieldData'
 import { type LensQuery, type LensQuerySort } from '../LensQuery'
 import { type LensResult } from '../LensResult'
 import { useCatalogUrlQuerySync } from '../composables/CatalogUrlQuerySync'
 import { provideLensEdit } from '../composables/LensEdit'
+import { extractServerMessage, isAuthError } from '../validation/ServerErrors'
 import LensCatalogControl, { type FilterPresets } from './LensCatalogControl.vue'
 import LensCatalogFooter from './LensCatalogFooter.vue'
 import LensCatalogStateFilter from './LensCatalogStateFilter.vue'
@@ -205,16 +207,32 @@ const emit = defineEmits<{
 
 const { t } = useTrans({
   en: {
-    write_error: 'Your latest changes might not be saved. Please reload the page, and contact support if the problem persists.',
-    busy_warning: 'A save is still in progress — changes you make now may not be saved.',
+    save_failed: (label: string) => `We couldn’t save “${label}”.`,
+    save_failed_anon: 'We couldn’t save your change.',
+    delete_failed: (label: string) => `We couldn’t delete “${label}”.`,
+    delete_failed_anon: 'We couldn’t delete this record.',
+    write_error_reload: 'Please reload and try again.',
+    write_error_recover: 'Please reload to see the latest data.',
+    busy_warning: 'Still saving — please wait a moment before changing the view.',
     refresh_text: 'Newer results are available.',
-    refresh_action: 'Refresh'
+    refresh_failed_text: 'Some changes couldn’t be saved. Refresh to restore the latest values.',
+    refresh_action: 'Refresh',
+    search_error: 'We couldn’t load the records.',
+    search_retry: 'Try again'
   },
   ja: {
-    write_error: '最新の変更が保存されていない可能性があります。ページを再読み込みし、問題が解決しない場合はサポートにお問い合わせください。',
-    busy_warning: '保存処理中です。ここでの変更は保存されない可能性があります。',
+    save_failed: (label: string) => `「${label}」を保存できませんでした。`,
+    save_failed_anon: '変更を保存できませんでした。',
+    delete_failed: (label: string) => `「${label}」を削除できませんでした。`,
+    delete_failed_anon: 'レコードを削除できませんでした。',
+    write_error_reload: 'ページを再読み込みして、もう一度お試しください。',
+    write_error_recover: 'ページを再読み込みして最新の状態をご確認ください。',
+    busy_warning: '保存中です。表示を変更する前に少しお待ちください。',
     refresh_text: '新しい結果があります。',
-    refresh_action: '更新'
+    refresh_failed_text: '保存できなかった変更があります。更新して最新の値に戻してください。',
+    refresh_action: '更新',
+    search_error: 'レコードを読み込めませんでした。',
+    search_retry: '再試行'
   }
 })
 
@@ -234,9 +252,12 @@ const hasInitialResults = ref(false)
 
 // A fresher server result fetched after the optimistic writes settled, awaiting
 // the user's explicit opt-in via the refresh button — never auto-applied (that
-// would momentarily revert the optimistic edits to stale data). Declared here
-// (ahead of the query handlers that clear it) so they can reference it.
-const latestState = ref<LensResult | null>(null)
+// would momentarily revert the optimistic edits to stale data). `fromError` marks
+// a stash produced by a *failed* write (the optimistic value diverged from the
+// canonical one), so the banner can explain it's a recovery rather than just
+// newer data. Declared here (ahead of the query handlers that clear it) so they
+// can reference it.
+const latestState = ref<{ result: LensResult; fromError: boolean } | null>(null)
 
 // Count of optimistic background writes currently in flight. Declared here
 // (ahead of the debounced refetch that consults it) so a queued refetch can bail
@@ -341,13 +362,79 @@ const { data: result, execute: refresh, loading } = useQuery(async (http) => {
   prevFetchResult = res
 
   return res
-})
+}, { immediate: false })
 
 // Keep `currentResult` pointing at the shown result. The reference changes only
 // on a wholesale replace; optimistic in-place edits keep the same object, so this
 // mirror always reflects them.
 watch(result, (r) => { currentResult = r ?? undefined }, { immediate: true })
 
+// Whether the most recent table search (initial load or a user-driven re-search)
+// failed. A failed fetch otherwise leaves the previous rows on screen with the
+// controls re-enabled — indistinguishable from the new query legitimately
+// returning them — so the list shows an inline error + retry instead.
+const searchError = ref(false)
+
+// Monotonic token so only the latest search may raise the error flag: with the
+// slow backend two searches can overlap, and an older one failing *after* a newer
+// one succeeded must not flash an error over the good rows now on screen.
+let searchRunSeq = 0
+
+// Run the main table search, tracking whether it failed. Drives the initial load
+// (the query's `immediate` is off so this owns it) and every `doRefresh`.
+async function runSearch(): Promise<void> {
+  const seq = ++searchRunSeq
+  // Snapshot `searchToken` too: a write / create / forced refresh / index-field
+  // change bumps it to supersede an in-flight search (so even on success the
+  // fetcher discards that search's rows and returns the current result instead).
+  // Such a superseded run must neither raise the error (its rejection is for a
+  // request we already decided to drop) nor clear it (its "success" is the stale
+  // current result, not the requested rows) — the follow-up (the write's
+  // reconcile, the forced result) settles the state instead.
+  const token = searchToken
+  try {
+    await refresh()
+    // Clear only on the latest, non-superseded run's success — an older run
+    // resolving late must not wipe a newer run's error, and a write-invalidated
+    // run resolving with the current result must not dismiss the error over rows
+    // that aren't the requested ones. Not cleared up front either: keeping the
+    // error visible until a retry actually succeeds avoids flashing the previous
+    // query's (interactable) rows back on screen mid-retry.
+    if (seq === searchRunSeq && token === searchToken) {
+      searchError.value = false
+      // These fresh rows for the current query supersede any pending recovery
+      // banner (a reconcile stash), so its button can't later overwrite them with
+      // an older snapshot. Query-change refetches already drop it; the retry path
+      // (doRefresh, which keeps the banner for a failed retry) doesn't, so a
+      // successful retry must clear it here.
+      latestState.value = null
+    }
+  } catch (e) {
+    // Auth / session-expiry (401 / 419) must reach the app's re-auth flow, not be
+    // parked on the inline retry state — matches the download / filter paths and
+    // the ServerErrors contract. Rethrow so the rejection propagates to the global
+    // handler as it did before this wrapper caught it.
+    if (isAuthError(e)) {
+      throw e
+    }
+    if (seq === searchRunSeq && token === searchToken) {
+      searchError.value = true
+    }
+  }
+}
+
+onMounted(runSearch)
+
+// When a search fails, the error state replaces the table but the control bar —
+// including its selected-actions (bulk) slot — stays mounted. Clear any selection
+// on entering the error so the user can't act on now-hidden rows from the previous
+// result while the UI says the current query failed.
+watch(searchError, (err) => {
+  if (err && selected.value?.length) {
+    selected.value = []
+  }
+})
+
 const doRefresh = useDebounceFn(() => {
   // A write or a blocking create may have started during the debounce window: the
   // busy lock guards the query handlers at click time, but not this deferred
@@ -357,7 +444,7 @@ const doRefresh = useDebounceFn(() => {
   // (Deliberate refreshes go through `forceRefresh`, which calls `refresh`
   // directly to bypass this guard.)
   if (pendingWrites.value > 0 || creating.value) { return }
-  return refresh()
+  return runSearch()
 }, 50)
 
 if (props.urlSync) {
@@ -376,7 +463,14 @@ if (props.urlSync) {
 }
 
 const _showEmptyState = computed(() => {
-  return props.showEmptyState && !hasInitialResults.value && result.value?.data.length === 0
+  // Exclude `searchError`: when a re-search fails the result still holds the
+  // previous (possibly zero-row) data, which would otherwise keep the empty-state
+  // slot showing — and it sits in this branch's `v-else`, so the inline error +
+  // retry would never render. Yield to the error state instead.
+  return props.showEmptyState
+    && !searchError.value
+    && !hasInitialResults.value
+    && result.value?.data.length === 0
 })
 
 const hasConditions = computed(() => {
@@ -481,6 +575,13 @@ const tableSelect = computed(() => {
   return withoutIndexField(result.value?.query.select ?? [])
 })
 
+// The effective row identifier when resolving / editing a row: the configured
+// `indexField`, or `id` by default. Distinct from the raw `props.indexField`,
+// whose `undefined` means "no index field configured" — `withIndexField` /
+// `withoutIndexField` rely on that to leave a non-editable catalog's columns
+// alone, so they deliberately keep using the prop directly rather than this.
+const idField = computed(() => props.indexField ?? 'id')
+
 // Whether the currently loaded rows actually carry the effective row identifier.
 // Editing / opening a row needs it (`resolveId`), but rows fetched while
 // `editable` was still false — or before an `indexField` change settled — won't
@@ -490,7 +591,7 @@ const tableSelect = computed(() => {
 const rowsCarryIndexField = computed(() => {
   const rows = result.value?.data
   if (!rows || rows.length === 0) { return true }
-  return (props.indexField ?? 'id') in rows[0]
+  return idField.value in rows[0]
 })
 
 // The row-identifier the table uses as its selection key. An explicit
@@ -549,6 +650,12 @@ function createInputFilters(queryFilters: any[], filters: any[]) {
 // reconcile result (the refreshed state supersedes it).
 function refetch(): void {
   latestState.value = null
+  // Supersede any in-flight search now, not only once the debounced run starts:
+  // a retry/search still loading for the previous query state would otherwise
+  // remain "latest" through the debounce window and, on resolving, clear the error
+  // or assign its rows after the query has already moved on. The next run captures
+  // the bumped token, so it isn't self-suppressed.
+  searchToken++
   doRefresh()
 }
 
@@ -690,8 +797,9 @@ const sheetError = ref(false)
 const reconciling = ref(false)
 const busy = computed(() => pendingWrites.value > 0 || reconciling.value)
 
-// Whether any write in the current in-flight batch failed; when so the reconcile
-// is skipped (the snackbar already told the user to reload).
+// Whether any write in the current in-flight batch failed; passed to the
+// post-batch reconcile so the refresh banner can label itself as a recovery for
+// the failed write's diverged row rather than just "newer data".
 let batchErrored = false
 
 // In-flight write chains keyed by record+field, so repeated writes to the same
@@ -716,10 +824,20 @@ let reconcileToken = 0
 // Resolve a record's identifier, unwrapping the id field's object shape
 // (`{ value, display, path }`) when present.
 function resolveId(record: Record<string, any>): any {
-  const v = record?.[props.indexField ?? 'id']
+  const v = record?.[idField.value]
   return v !== null && typeof v === 'object' ? v.value : v
 }
 
+// Resolve a human-facing label for a record — the index field's display value
+// (the id object's `{ value, display, path }` shape) falling back to the bare
+// identifier — to name the affected row in a write-failure snackbar. Null when
+// no usable label exists, so the snackbar can fall back to anonymous copy.
+function resolveLabel(record: Record<string, any>): string | null {
+  const v = record?.[idField.value]
+  const label = v !== null && typeof v === 'object' ? (v.display ?? v.value) : v
+  return label != null && label !== '' ? String(label) : null
+}
+
 const { execute: executeUpdate } = useMutation((http, id: any, values: Record<string, any>) =>
   http.post(`${endpointBase.value}/update`, {
     entity: entityName.value, id, values, settings: { lang }
@@ -760,6 +878,14 @@ function guardBusy(): boolean {
   return false
 }
 
+// `updated_at` is a server-managed timestamp that bumps on every write, so a
+// reconciled row's value always differs from the optimistic one even when nothing
+// else changed. It's excluded from the diff below (and patched to ~now on save) so
+// an edit never surfaces the refresh banner just for its own timestamp — the user
+// shouldn't be asked to reload the whole view over a change that obviously follows
+// from their edit. Always a datetime column, never user-editable.
+const UPDATED_AT_KEY = 'updated_at'
+
 // Value-level comparison (rows in order + total) deciding whether a reconcile
 // surfaced anything newer than the optimistic state on screen. `fresh` is the
 // canonical search-shaped result; `shown` is what's displayed, which may carry
@@ -774,6 +900,9 @@ function isSameResult(fresh: LensResult | null, shown: LensResult | null): boole
     const freshRow = fresh.data[i]
     const shownRow = shown.data[i]
     for (const key of Object.keys(freshRow)) {
+      // The always-bumped timestamp would make every edited row look "changed";
+      // skip it so it alone can't surface the refresh banner (see UPDATED_AT_KEY).
+      if (key === UPDATED_AT_KEY) { continue }
       if (JSON.stringify(freshRow[key]) !== JSON.stringify(shownRow?.[key])) {
         return false
       }
@@ -784,8 +913,11 @@ function isSameResult(fresh: LensResult | null, shown: LensResult | null): boole
 
 // After the last in-flight write settles, fetch the canonical state for the
 // current query and, only if it differs from what's shown, stash it behind the
-// refresh button. The server is fresh by now (the write completed).
-async function reconcile(): Promise<void> {
+// refresh button. The server is fresh by now (the write completed). `afterError`
+// is set when a write in the batch *failed*: its optimistic edit wasn't rolled
+// back, so the canonical state diverges and the stash becomes the user's one-click
+// path to restore it — the banner labels it accordingly.
+async function reconcile(afterError = false): Promise<void> {
   const token = ++reconcileToken
   reconciling.value = true
   try {
@@ -798,9 +930,13 @@ async function reconcile(): Promise<void> {
     // Authoritative: stash the canonical result when it differs from what's
     // shown, otherwise clear any (possibly stale) stash — an earlier overlapping
     // reconcile may have left a pre-edit result behind.
-    latestState.value = result.value && !isSameResult(fresh, result.value) ? fresh : null
+    latestState.value = result.value && !isSameResult(fresh, result.value)
+      ? { result: fresh, fromError: afterError }
+      : null
   } catch {
-    // Ignore — keep the optimistic state, offer no refresh.
+    // Ignore — keep the optimistic state, offer no refresh. After a failed write
+    // this means no recovery banner, so the failure snackbar's reload guidance is
+    // the fallback.
   } finally {
     if (token === reconcileToken) {
       reconciling.value = false
@@ -810,8 +946,15 @@ async function reconcile(): Promise<void> {
 
 function applyLatest(): void {
   if (!latestState.value) { return }
-  result.value = latestState.value
+  result.value = latestState.value.result
   latestState.value = null
+  // These are fresh authoritative rows for the current query, so drop any
+  // search-error state — e.g. a search failed, then a sheet save's reconcile
+  // surfaced this banner; applying it must reveal the rows, not stay on the retry.
+  searchError.value = false
+  // Supersede any in-flight retry started from that error state, so it can't
+  // assign over these rows or re-raise the error after they've been applied.
+  searchToken++
   prevFetchInput = null
   rebindOpenSheet()
 }
@@ -853,9 +996,19 @@ async function forceRefresh(): Promise<void> {
   // fresh result when it resolves — same token mechanism as the write/create
   // races. This refetch captures the bumped token, so it isn't self-suppressed.
   searchToken++
+  const token = searchToken
   prevFetchInput = null
   latestState.value = null
   await refresh()
+  // A deliberate reload landed fresh rows — clear any prior search-error state so
+  // the list shows them instead of a stale error. But only if this reload wasn't
+  // itself invalidated mid-flight (a write bumping `searchToken` makes the fetcher
+  // return the current result, not freshly-assigned rows) — otherwise we'd dismiss
+  // the error over the previous query's rows. (On failure this rethrows and the
+  // flag is left untouched; the create path handles its own fallback.)
+  if (token === searchToken) {
+    searchError.value = false
+  }
   rebindOpenSheet()
 }
 
@@ -890,7 +1043,7 @@ async function refreshCatalog(): Promise<void> {
 // `resolveId` would be `undefined`), which would let a delete/save act on the
 // wrong — or no — id during and after the refetch.
 watch(
-  () => (props.editable ? (props.indexField ?? 'id') : null),
+  () => (props.editable ? idField.value : null),
   (field, prev) => {
     if (!field || field === prev) { return }
     if (sheet.state.value && sheetMode.value === 'view') { sheet.off() }
@@ -905,14 +1058,40 @@ watch(
 )
 
 // Track an optimistic background write: count it as pending, surface a snackbar
-// on failure, and once the whole batch settles (with no failures) reconcile.
+// on failure, and once the whole batch settles reconcile (so a failed write's
+// diverged row can be restored via the refresh banner).
 function hasPendingWrite(recordId: any): boolean {
   return pendingByRecord.has(recordId)
 }
 
+// Compose the failure snackbar: name the affected row when we have a label, then
+// the server's reason (a policy / business-rule / validation message) when
+// present, and always a recovery hint. The optimistic value isn't rolled back, so
+// the user needs a way back to canonical state — the refresh banner offers a
+// one-click path when it appears, but it can't always (a failed recovery reconcile
+// shows none, and `isSameResult` can't see detail-only sheet fields absent from
+// the search), so the reload hint stays as the guaranteed fallback. With a reason
+// present, "reload to see the latest data" (the change didn't take; reload to
+// resync); without one (network / 5xx / opaque), "reload and try again".
+function writeErrorText(op: 'save' | 'delete', label: string | null, reason: string | null): string {
+  const subject = op === 'delete'
+    ? (label != null ? t.delete_failed(label) : t.delete_failed_anon)
+    : (label != null ? t.save_failed(label) : t.save_failed_anon)
+  return reason
+    ? `${subject} ${reason} ${t.write_error_recover}`
+    : `${subject} ${t.write_error_reload}`
+}
+
 // Track an optimistic background write for `recordId`, serialized per `key` so
-// writes to the same cell reach the server in edit order.
-function trackWrite(recordId: any, key: string, run: () => Promise<unknown>): void {
+// writes to the same cell reach the server in edit order. `op` / `label` name the
+// affected row in the failure snackbar.
+function trackWrite(
+  recordId: any,
+  key: string,
+  op: 'save' | 'delete',
+  label: string | null,
+  run: () => Promise<unknown>
+): void {
   // A new write changes the displayed state. Clear any stashed reconcile result
   // and invalidate an in-flight reconcile (advance the token so its result is
   // dropped; clear its busy flag — `pendingWrites` keeps us busy), so neither
@@ -934,9 +1113,17 @@ function trackWrite(recordId: any, key: string, run: () => Promise<unknown>): vo
   writeChains.set(key, current)
 
   current
-    .catch(() => {
+    .catch((e) => {
       batchErrored = true
-      snackbars.push({ mode: 'danger', text: t.write_error })
+      // Name the affected row and prefer a server-provided reason (a policy /
+      // business-rule deny, a validation message) so a rejected write explains
+      // itself and the user can tell which edit failed when several are in flight.
+      // The optimistic edit isn't rolled back here; the post-batch reconcile
+      // surfaces the refresh banner to restore it.
+      snackbars.push({
+        mode: 'danger',
+        text: writeErrorText(op, label, extractServerMessage(e))
+      })
     })
     .finally(() => {
       // Only drop the chain entry if a newer write hasn't replaced it.
@@ -953,9 +1140,12 @@ function trackWrite(recordId: any, key: string, run: () => Promise<unknown>): vo
       if (pendingWrites.value === 0) {
         const errored = batchErrored
         batchErrored = false
-        if (!errored) {
-          reconcile()
-        }
+        // Reconcile on error too: a failed write left its optimistic edit on the
+        // row, so the canonical state now diverges and the refresh banner becomes
+        // the user's one-click path to restore it (labelled as a recovery). If the
+        // reconcile itself fails, no banner shows and the snackbar's reload
+        // guidance is the fallback.
+        reconcile(errored)
       }
     })
 }
@@ -971,13 +1161,21 @@ function save(record: Record<string, any>, values: Record<string, any>): void {
   // row, so a follow-up save / delete would resolve to the new, not-yet-synced id
   // and miss the in-flight record. Strip it so the invariant holds for every
   // caller. (The identifier is still settable on create, which uses `create()`.)
-  const indexField = props.indexField ?? 'id'
+  const indexField = idField.value
   if (indexField in values) {
     values = { ...values }
     delete values[indexField]
   }
   if (Object.keys(values).length === 0) { return }
   Object.assign(record, values)
+  // Optimistically advance the row's `updated_at` to ~now so the displayed
+  // timestamp reflects the edit immediately. The server sets the authoritative
+  // value; a little skew is fine and never surfaces the refresh banner, since the
+  // reconcile diff ignores this column. Display-only — deliberately not added to
+  // the persisted `values` (the server owns its own timestamping).
+  if (UPDATED_AT_KEY in record) {
+    record[UPDATED_AT_KEY] = day().toISOString()
+  }
   // Serialize per record+field so two quick edits to the same cell apply in
   // order; edits to disjoint fields run concurrently.
   const fields = Object.keys(values)
@@ -995,7 +1193,7 @@ function save(record: Record<string, any>, values: Record<string, any>): void {
       && k.slice(prefix.length).split(',').some((f) => fieldSet.has(f)))
     .map(([, chain]) => chain)
   const gate = Promise.allSettled(overlapping)
-  trackWrite(id, key, () => gate.then(() => executeUpdate(id, values)))
+  trackWrite(id, key, 'save', resolveLabel(record), () => gate.then(() => executeUpdate(id, values)))
 }
 
 // Create — blocking. The slow POST runs to completion, then the catalog is
@@ -1023,6 +1221,11 @@ async function create(values: Record<string, any>): Promise<Record<string, any>>
     // during the create (doRefresh bails on `creating`); create's own forceRefresh
     // bypasses that by calling refresh directly.
     searchToken++
+    // Don't clear `searchError` here: only a successful current-query refresh
+    // should (forceRefresh does so on success). The fallbacks below show the
+    // previous query's rows plus the new record — not the requested query — so
+    // dismissing the error there would present stale rows as if they matched.
+    //
     // From here a refresh failure must not reject (the caller would treat the
     // create as failed and re-submit a duplicate); fall back to showing the new
     // record optimistically.
@@ -1089,7 +1292,7 @@ function remove(record: Record<string, any>): void {
   // `Promise.allSettled([])` resolves immediately, so this is a no-op gate when
   // the record has no in-flight writes.
   const gate = Promise.allSettled(pendingForRecord)
-  trackWrite(id, `${id}:__delete__`, () => gate.then(() => executeDelete(id)))
+  trackWrite(id, `${id}:__delete__`, 'delete', resolveLabel(record), () => gate.then(() => executeDelete(id)))
 }
 
 async function openSheet(record: Record<string, any>): Promise<void> {
@@ -1199,7 +1402,7 @@ provideLensEdit({
   // sheet opener and to block identifier edits, so it must track a prop that
   // resolves (or changes) after mount — otherwise the new identifier column stays
   // non-clickable while the old field is still treated as the id.
-  get indexField() { return props.indexField ?? 'id' },
+  get indexField() { return idField.value },
   canEdit,
   canDelete,
   resolveId,
@@ -1323,32 +1526,48 @@ defineExpose({
       </div>
       <SDivider />
       <div v-if="latestState && !busy" class="refresh-banner">
-        <span class="refresh-banner-text">{{ t.refresh_text }}</span>
+        <span class="refresh-banner-text">{{ latestState.fromError ? t.refresh_failed_text : t.refresh_text }}</span>
         <SButton size="mini" mode="info" :label="t.refresh_action" @click="applyLatest" />
       </div>
       <div class="list" :style="tableMaxHeight">
-        <LensTable
-          :result
-          :loading
-          :overrides="_overrides"
-          :select="tableSelect"
-          :index-field="tableIndexField"
-          :selected
-          :clickable-fields
-          :inline-editable
-          @filter-updated="onInlineFilterUpdated"
-          @sort-updated="onSortUpdated"
-          @update:selected="onUpdateSelected"
-          @cell-clicked="(v, r) => emit('cell-clicked', v, r)"
-        />
-        <LensCatalogFooter
-          v-if="result && result?.pagination.total > 0"
-          :class="{ 'is-busy': busy }"
-          :result
-          :loading
-          @prev="onPrev"
-          @next="onNext"
-        />
+        <div v-if="searchError" class="list-error">
+          <p class="list-error-text">{{ t.search_error }}</p>
+          <!-- Retry the same query via the busy-guarded `doRefresh` (not `refetch`,
+               which would clear a `latestState` recovery banner before the retry
+               resolves — a failed retry would then lose that known-good stash). -->
+          <SButton
+            size="small"
+            mode="info"
+            :label="t.search_retry"
+            :loading
+            :disabled="busy"
+            @click="doRefresh"
+          />
+        </div>
+        <template v-else>
+          <LensTable
+            :result
+            :loading
+            :overrides="_overrides"
+            :select="tableSelect"
+            :index-field="tableIndexField"
+            :selected
+            :clickable-fields
+            :inline-editable
+            @filter-updated="onInlineFilterUpdated"
+            @sort-updated="onSortUpdated"
+            @update:selected="onUpdateSelected"
+            @cell-clicked="(v, r) => emit('cell-clicked', v, r)"
+          />
+          <LensCatalogFooter
+            v-if="result && result?.pagination.total > 0"
+            :class="{ 'is-busy': busy }"
+            :result
+            :loading
+            @prev="onPrev"
+            @next="onNext"
+          />
+        </template>
       </div>
     </div>
 
@@ -1384,7 +1603,7 @@ defineExpose({
       :loading="sheetLoading"
       :error="sheetError"
       :fields="result.fields"
-      :index-field="indexField ?? 'id'"
+      :index-field="idField"
       :width="sheetWidth"
       @close="sheet.off"
     >
@@ -1461,6 +1680,23 @@ defineExpose({
   flex-grow: 1;
 }
 
+.list-error {
+  display: flex;
+  flex-direction: column;
+  flex-grow: 1;
+  align-items: center;
+  justify-content: center;
+  gap: 12px;
+  padding: 48px 16px;
+  text-align: center;
+}
+
+.list-error-text {
+  font-size: 14px;
+  line-height: 1.6;
+  color: var(--c-text-2);
+}
+
 .control-skeleton {
   height: 56px;
   background-color: var(--c-bg-1);

package/lib/blocks/lens/components/LensSheet.vue

@@ -9,10 +9,11 @@ import { provideDataListState } from '../../../composables/DataList'
 import { useTrans } from '../../../composables/Lang'
 import { usePower } from '../../../composables/Power'
 import { useValidation } from '../../../composables/Validation'
+import { useSnackbars } from '../../../stores/Snackbars'
 import { type FieldData } from '../FieldData'
 import { useFieldFactory } from '../composables/FieldFactory'
 import { useLensEdit } from '../composables/LensEdit'
-import { extractServerErrors } from '../validation/ServerErrors'
+import { extractServerErrors, extractServerMessage } from '../validation/ServerErrors'
 import LensSheetField from './LensSheetField.vue'
 
 const props = withDefaults(defineProps<{
@@ -46,7 +47,7 @@ const { t } = useTrans({
     confirm_delete: 'Delete this record?',
     new_record: 'New record',
     load_error:
-      'Couldn’t load this record. Please reload the page, and contact support if the problem persists.'
+      'We couldn’t load this record. Please reload the page and try again.'
   },
   ja: {
     create: '作成',
@@ -55,12 +56,13 @@ const { t } = useTrans({
     confirm_delete: 'このレコードを削除しますか？',
     new_record: '新規作成',
     load_error:
-      'このレコードを読み込めませんでした。ページを再読み込みし、問題が解決しない場合はサポートにお問い合わせください。'
+      'このレコードを読み込めませんでした。ページを再読み込みして、もう一度お試しください。'
   }
 })
 
 const edit = useLensEdit()
 const factory = useFieldFactory()
+const snackbars = useSnackbars()
 
 // Provide the data-list label width directly (instead of wrapping rows in
 // SDataList) so each LensSheetField wrapper doesn't make its SDataListItem a
@@ -202,13 +204,24 @@ async function onCreate() {
     await edit!.create(values)
     emit('close')
   } catch (e) {
-    // Surface backend validation errors (e.g. a duplicate `unique` value) on
-    // the offending fields; rethrow anything that isn't a 422.
+    // Surface backend validation errors (e.g. a duplicate `unique` value) on the
+    // offending fields. Failing that, surface a server-provided message (a policy
+    // / business-rule deny, or a form-level 422) as a snackbar and keep the sheet
+    // open with the input intact — rather than rethrowing into the global
+    // full-page error handler. Failures without a displayable message — network,
+    // 5xx, opaque, and auth / session expiry (which extractServerMessage excludes
+    // so the app can prompt re-auth) — still propagate.
     const errors = extractServerErrors(e)
-    if (!errors) {
-      throw e
+    if (errors) {
+      serverErrors.value = errors
+      return
+    }
+    const message = extractServerMessage(e)
+    if (message) {
+      snackbars.push({ mode: 'danger', text: message })
+      return
     }
-    serverErrors.value = errors
+    throw e
   } finally {
     saving.value = false
   }

package/lib/blocks/lens/components/LensTable.vue

@@ -68,11 +68,6 @@ const columnKeys = computed(() => {
   return visible.map((k) => (k === '__empty__' ? `__empty__::${emptyIndex++}` : k))
 })
 
-const orders = computed(() => [
-  ...columnKeys.value,
-  '__last_empty__'
-])
-
 const columns = computedAsync(async () => {
   const r = props.result
 
@@ -125,6 +120,13 @@ const columns = computedAsync(async () => {
     // off the configured index field for any field type — a slug/code identifier
     // opens the sheet just like an `id` — so other id-type columns (e.g. a
     // `company_id` reference link) keep their own navigation.
+    //
+    // Exception: an `id` field whose server value carries a `path` renders that
+    // path as a link; respect it so those rows navigate to the details page instead
+    // of opening the sheet (decided per row, so id's without a path still open it).
+    // Scoped to `id` fields — a custom index field that itself renders a link (e.g.
+    // a `link` / `slack_message` identifier) is still turned into the sheet opener,
+    // as is a column whose `cell` is undefined (falls straight through to the opener).
     if (
       edit?.editable
       && key === edit.indexField
@@ -132,12 +134,17 @@ const columns = computedAsync(async () => {
       const original = column.cell
       column.cell = (v: any, r: any): TableCell<any, any> => {
         const cell = typeof original === 'function' ? original(v, r) : original
+        if (overriddenFieldData.type === 'id' && cell && 'link' in cell && cell.link) {
+          return cell
+        }
         return {
-          ...(cell as TableCell<any, any>),
+          ...cell,
           link: null,
+          // @ts-expect-error avatar and day cells don't have info as color,
+          // but we don't use those for the index field anyway, so it's safe to force it here
           color: 'info',
           onClick: () => edit.openSheet(r)
-        } as TableCell<any, any>
+        }
       }
     } else if (
       props.inlineEditable
@@ -182,6 +189,18 @@ const columns = computedAsync(async () => {
   return columns
 }, {})
 
+// Render a column only once its definition exists. `columns` resolves
+// asynchronously (computedAsync), so when a column is toggled back on its key
+// lands in `columnKeys` a tick before `columns` rebuilds to include it. Emitting
+// that key in `orders` during the gap makes STable render the column with no cell
+// definition — STableCell then falls back to STableCellText with the raw value
+// (e.g. the `id` field's `{ value, display, path }` object), tripping a Vue
+// prop-type warning. Gating on presence in `columns` keeps the two in lockstep.
+const orders = computed(() => [
+  ...columnKeys.value.filter((key) => key in columns.value),
+  '__last_empty__'
+])
+
 const table = useTable({
   records,
   orders,

package/lib/blocks/lens/composables/FileDownloader.ts

@@ -1,10 +1,37 @@
 import { useGet } from '../../../composables/Api'
+import { useTrans } from '../../../composables/Lang'
+import { useSnackbars } from '../../../stores/Snackbars'
 import { type FileDownloader } from '../FileDownloader'
+import { isAuthError } from '../validation/ServerErrors'
 
 export function useFileDownloader(): FileDownloader {
+  const snackbars = useSnackbars()
+
+  const { t } = useTrans({
+    en: { download_error: 'We couldn’t download this file. Please try again.' },
+    ja: { download_error: 'ファイルをダウンロードできませんでした。もう一度お試しください。' }
+  })
+
   const { execute: fileDownloader } = useGet<any, [url: string]>(async (http, url) => {
     return http.download(url)
   })
 
-  return fileDownloader
+  // The click binding (e.g. SDescFile's `@click`) doesn't await the returned
+  // promise, so a failed download would otherwise be an unhandled rejection with
+  // no feedback — the click just appears to do nothing. Catch and surface a
+  // snackbar. The response is a blob, so the server's message isn't readily
+  // decodable here; generic copy is the right level.
+  return async (url) => {
+    try {
+      return await fileDownloader(url)
+    } catch (e) {
+      // Let auth / session-expiry failures (401 / 419) propagate to the app's
+      // error flow so it can prompt re-authentication — the click path doesn't
+      // await this, so the rejection reaches the global handler as it did before.
+      if (isAuthError(e)) {
+        throw e
+      }
+      snackbars.push({ mode: 'danger', text: t.download_error })
+    }
+  }
 }

package/lib/blocks/lens/composables/ResourceFetcher.ts

@@ -33,6 +33,12 @@ export function useResourceFetcher(): ResourceFetcher {
         data.value[key] = response
         delete pendingList[key]
         return response
+      },
+      (error) => {
+        // Clear the pending entry on failure too — otherwise the rejected promise
+        // stays cached under `key` and every retry returns the same rejection.
+        delete pendingList[key]
+        throw error
       }
     )
 

package/lib/blocks/lens/filter-inputs/SelectFilterInput.ts

@@ -2,6 +2,7 @@ import { type ValidationArgs } from '@vuelidate/core'
 import { defineAsyncComponent } from 'vue'
 import SInputDropdown, { type Option } from '../../../components/SInputDropdown.vue'
 import { required } from '../../../validation/rules'
+import { isAuthError } from '../validation/ServerErrors'
 import { FilterInput } from './FilterInput'
 
 export class SelectFilterInput extends FilterInput {
@@ -53,10 +54,25 @@ export class SelectFilterInput extends FilterInput {
   }
 
   async valueToText(value: any): Promise<string> {
-    const options = await this.resolveOptions()
+    // Degrade gracefully: if the options can't be fetched, or the applied filter
+    // value isn't among them (the option set changed, or the referenced record was
+    // deleted), fall back to the raw value instead of asserting — a throw here
+    // leaves the filter chip stuck on its loading placeholder forever.
+    let options: Option[] = []
+    try {
+      options = await this.resolveOptions()
+    } catch (e) {
+      // Let auth / session-expiry failures reach the app's error / re-auth flow
+      // instead of silently degrading to raw values. Other failures — an option
+      // miss or a non-auth fetch error — fall back so the chip stays readable.
+      if (isAuthError(e)) {
+        throw e
+      }
+      options = []
+    }
 
     return this.valueAsArray(value)
-      .map((v) => options.find((o) => o.value === v)!.label)
+      .map((v) => options.find((o) => o.value === v)?.label ?? String(v))
       .join(', ')
   }
 

package/lib/blocks/lens/validation/ServerErrors.ts

@@ -23,3 +23,41 @@ export function extractServerErrors(error: unknown): Record<string, string[]> |
 
   return errors
 }
+
+/**
+ * Auth / session-expiry statuses (Laravel: 401 unauthenticated, 419 session /
+ * CSRF token expired). These need the app-level error flow — e.g. to prompt
+ * re-authentication — so Lens never surfaces them inline or swallows them into a
+ * snackbar; callers let them propagate to the global handler instead.
+ */
+const AUTH_STATUSES = new Set([401, 419])
+
+export function isAuthError(error: unknown): boolean {
+  return isFetchError(error) && error.status != null && AUTH_STATUSES.has(error.status)
+}
+
+/**
+ * Extract a human-readable top-level message from a failed request, when the
+ * server provides one worth showing the user. Laravel includes a `message` on
+ * most error responses — policy denials (`Response::deny('…')`), business-rule
+ * rejections, and 422 summaries. Limited to 4xx so internal 5xx detail never
+ * leaks to the UI, and excludes auth / session statuses (see `isAuthError`) so
+ * those reach the app's re-auth flow rather than being shown inline. 5xx /
+ * network / opaque / auth failures return `null` so the caller can fall back to
+ * its own generic copy or rethrow.
+ */
+export function extractServerMessage(error: unknown): string | null {
+  if (
+    !isFetchError(error)
+    || error.status == null
+    || error.status < 400
+    || error.status >= 500
+    || AUTH_STATUSES.has(error.status)
+  ) {
+    return null
+  }
+
+  const message = (error.data as any)?.message
+
+  return typeof message === 'string' && message.trim() !== '' ? message : null
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@globalbrain/sefirot",
-  "version": "4.51.0",
+  "version": "4.52.1",
   "description": "Vue Components for Global Brain Design System.",
   "keywords": [
     "components",