@globalbrain/sefirot 4.52.1 → 4.54.0

package/lib/blocks/lens/FieldData.ts

@@ -70,9 +70,23 @@ export interface AvatarFieldData extends FieldDataBase {
    * avatar uses the name (resolved against the active language) for the
    * initials fallback / tooltip when the image is unavailable. The field
    * value itself is the image URL.
+   *
+   * When the field is editable, these companion keys also become editable from
+   * the inline cell (the pencil affordance beside the avatar edits both names),
+   * so the avatar and its names can be updated together.
    */
   nameEn?: string | null
   nameJa?: string | null
+  /**
+   * The `accept` attribute for the file picker (e.g. `image/jpeg,image/png`).
+   * Defaults to `image/*`.
+   */
+  accept?: string | null
+  /** Help text shown beneath the picker, per language. */
+  helpEn?: string | null
+  helpJa?: string | null
+  /** Picker preview shape. Defaults to `circle` (avatars are round). */
+  imageType?: 'circle' | 'rectangle' | null
 }
 
 export interface BooleanFieldData extends FieldDataBase {

package/lib/blocks/lens/Rule.ts

@@ -20,6 +20,8 @@ export type Rule =
   | BeforeOrEqualRule
   | AfterRule
   | AfterOrEqualRule
+  | FileExtensionRule
+  | MaxFileSizeRule
   | EachRule
 
 export interface MaxLengthRule {
@@ -115,6 +117,16 @@ export interface AfterOrEqualRule {
   date: string
 }
 
+export interface FileExtensionRule {
+  type: 'file_extension'
+  extensions: string[]
+}
+
+export interface MaxFileSizeRule {
+  type: 'max_file_size'
+  size: string
+}
+
 /**
  * Applies the nested `rules` to every element of an array value, mirroring
  * Laravel's `field.*` wildcard on the backend.

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

@@ -0,0 +1,44 @@
+<script setup lang="ts">
+import SInputImage, { type ImageType, type Size } from '../../../components/SInputImage.vue'
+import { useTrans } from '../../../composables/Lang'
+import { type Validatable } from '../../../composables/Validation'
+
+withDefaults(defineProps<{
+  label?: string
+  help?: string
+  accept?: string
+  imageType?: ImageType
+  size?: Size
+  disabled?: boolean
+  validation?: Validatable
+}>(), {
+  imageType: 'circle',
+  size: 'small'
+})
+
+// The model is the raw `File` the user just picked, the existing image URL
+// (a string), or `null` when there is no image / it was removed. `SInputImage`
+// renders a preview from any of these via `useImageSrcFromFile`.
+const model = defineModel<File | string | null>()
+
+const { t } = useTrans({
+  en: { select: 'Select image', remove: 'Remove image' },
+  ja: { select: '画像を選択', remove: '画像を削除' }
+})
+</script>
+
+<template>
+  <SInputImage
+    v-model="model"
+    class="LensAvatarInput"
+    :label
+    :help
+    :accept
+    :image-type
+    :size
+    :disabled
+    :select-text="t.select"
+    :remove-text="t.remove"
+    :validation
+  />
+</template>

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

@@ -839,7 +839,7 @@ function resolveLabel(record: Record<string, any>): string | null {
 }
 
 const { execute: executeUpdate } = useMutation((http, id: any, values: Record<string, any>) =>
-  http.post(`${endpointBase.value}/update`, {
+  http.post<LensResult & { data: Record<string, any> }>(`${endpointBase.value}/update`, {
     entity: entityName.value, id, values, settings: { lang }
   })
 )
@@ -1196,6 +1196,103 @@ function save(record: Record<string, any>, values: Record<string, any>): void {
   trackWrite(id, key, 'save', resolveLabel(record), () => gate.then(() => executeUpdate(id, values)))
 }
 
+// Reflect a change on the in-memory record. Pure in-memory mutation: the caller
+// (`saveBlocking`) owns the write accounting (invalidation, reconcile). The
+// catalog row and any open sheet share the object, so the change shows
+// immediately. The row identifier is stripped so it can never re-key.
+function patch(record: Record<string, any>, values: Record<string, any>): void {
+  const indexField = idField.value
+  if (indexField in values) {
+    values = { ...values }
+    delete values[indexField]
+  }
+  if (Object.keys(values).length === 0) { return }
+  Object.assign(record, values)
+}
+
+// Update — blocking. For a field whose input value can't be shown optimistically
+// (a file input holds a raw `File`, not the displayed URL), the write must finish
+// before the row can reflect it. Awaits the Lens update (sent multipart when a
+// `File` is present) and patches the submitted columns from the canonical
+// response, with the same accounting as an optimistic write so it stays
+// consistent with concurrent reads/writes:
+//   - the invalidation preamble (mirroring `trackWrite`) supersedes any stashed /
+//     in-flight reconcile or search, so a request that predates the write can't
+//     reassign stale rows mid-flight;
+//   - `pendingWrites` locks the query controls while it's in flight, and
+//     `pendingByRecord` arms `openSheet`'s `/show` stale-read guard;
+//   - writes to the same record+columns serialize on `writeChains` (last issued
+//     wins, and a delete gates on them);
+//   - only the submitted columns are patched — not the whole row, so a concurrent
+//     optimistic edit to another column isn't reverted — onto the live displayed
+//     row (resolved by id), not only the passed `record` (an orphan after a
+//     create refetched);
+//   - a reconcile resyncs once the batch settles.
+// Rejects if the write fails: nothing was patched, so the row keeps its previous
+// value and the caller need only surface the error.
+async function saveBlocking(record: Record<string, any>, values: Record<string, any>): Promise<void> {
+  const id = resolveId(record)
+  // Never let an update re-key the row (mirrors save()).
+  const indexField = idField.value
+  if (indexField in values) {
+    values = { ...values }
+    delete values[indexField]
+  }
+  if (Object.keys(values).length === 0) { return }
+
+  latestState.value = null
+  reconcileToken++
+  searchToken++
+  reconciling.value = false
+  pendingWrites.value++
+  pendingByRecord.set(id, (pendingByRecord.get(id) ?? 0) + 1)
+
+  // Serialize writes to the same record+columns: chain after any in-flight one so
+  // its request is sent (and patched) only once the earlier resolves. Keyed like
+  // save() so the delete gate (which scans writeChains) waits for it too.
+  const key = `${id}:${Object.keys(values).sort().join(',')}`
+  const prev = writeChains.get(key) ?? Promise.resolve()
+  const run = prev.catch(() => {}).then(() => executeUpdate(id, values))
+  writeChains.set(key, run)
+
+  try {
+    const res = await run
+    // Patch only the submitted columns the canonical row actually carries — a
+    // withheld (write-only) response mustn't null a column we can't read back —
+    // plus the server timestamp (falling back to ~now) like save(); the reconcile
+    // ignores updated_at, so it never surfaces the banner just for this.
+    const data = res.data ?? {}
+    const patched: Record<string, any> = {}
+    for (const k of Object.keys(values)) {
+      if (k in data) { patched[k] = data[k] }
+    }
+    if (UPDATED_AT_KEY in record) {
+      patched[UPDATED_AT_KEY] = data[UPDATED_AT_KEY] ?? day().toISOString()
+    }
+    patch(record, patched)
+    const row = result.value?.data.find((r) => resolveId(r) === id)
+    if (row && row !== record) {
+      patch(row, patched)
+    }
+  } finally {
+    if (writeChains.get(key) === run) {
+      writeChains.delete(key)
+    }
+    const remaining = (pendingByRecord.get(id) ?? 1) - 1
+    remaining > 0 ? pendingByRecord.set(id, remaining) : pendingByRecord.delete(id)
+    pendingWrites.value--
+    if (pendingWrites.value === 0) {
+      // Drive the post-batch reconcile like trackWrite does — this write shares
+      // the `pendingWrites` batch, so when it settles last it must forward (and
+      // reset) `batchErrored` so a concurrent failed write's diverged row still
+      // gets the recovery banner, and the flag doesn't leak into the next batch.
+      const errored = batchErrored
+      batchErrored = false
+      reconcile(errored)
+    }
+  }
+}
+
 // Create — blocking. The slow POST runs to completion, then the catalog is
 // refreshed with the now-synced canonical state (preserving the active query).
 // The create sheet shows a button spinner meanwhile.
@@ -1290,7 +1387,9 @@ function remove(record: Record<string, any>): void {
     .filter(([key]) => key.startsWith(`${id}:`))
     .map(([, chain]) => chain)
   // `Promise.allSettled([])` resolves immediately, so this is a no-op gate when
-  // the record has no in-flight writes.
+  // the record has no in-flight writes. Blocking avatar writes share writeChains,
+  // so they're gated too — a delete can't race an in-flight avatar write, which
+  // would otherwise fail against a removed row or write after the delete.
   const gate = Promise.allSettled(pendingForRecord)
   trackWrite(id, `${id}:__delete__`, 'delete', resolveLabel(record), () => gate.then(() => executeDelete(id)))
 }
@@ -1407,10 +1506,12 @@ provideLensEdit({
   canDelete,
   resolveId,
   save,
+  saveBlocking,
   create,
   remove,
   openSheet,
-  openCreate
+  openCreate,
+  refresh: refreshCatalog
 })
 
 // Warn the user (native prompt) if they try to leave while a write is still

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

@@ -39,9 +39,17 @@ const orderTextDict = {
 }
 
 function getFieldName(sort: LensQuerySort): string {
-  return lang === 'ja'
-    ? props.fields[sort[0]].labelJa
-    : props.fields[sort[0]].labelEn
+  // A still-applied sort can reference a field that's not in the field set — a
+  // stale saved/URL sort, or a sort emitted under a companion key (e.g. an
+  // avatar sorting by its display-name field). Fall back to the raw key rather
+  // than crash, mirroring how the filter chip handles an unknown field.
+  const field = props.fields[sort[0]]
+
+  if (!field) {
+    return sort[0]
+  }
+
+  return lang === 'ja' ? field.labelJa : field.labelEn
 }
 
 function getOrderText(sort: LensQuerySort): string {

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

@@ -87,6 +87,8 @@ const selectOptions = ref(createSelectOptions())
 
 const selectedOption = ref<SelectOption | null>(null)
 
+const hasSelection = computed(() => selectOptions.value.some((s) => s.value))
+
 useDraggable(el, selectOptions, {
   handle: '.handle'
 })
@@ -262,6 +264,7 @@ async function onApply() {
         size="md"
         mode="info"
         :label="t.a_apply"
+        :disabled="!hasSelection"
         @click="onApply"
       />
     </SCardFooter>

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

@@ -14,6 +14,7 @@ import { type FieldData } from '../FieldData'
 import { useFieldFactory } from '../composables/FieldFactory'
 import { useLensEdit } from '../composables/LensEdit'
 import { extractServerErrors, extractServerMessage } from '../validation/ServerErrors'
+import LensSheetAvatarField from './LensSheetAvatarField.vue'
 import LensSheetField from './LensSheetField.vue'
 
 const props = withDefaults(defineProps<{
@@ -97,7 +98,9 @@ const createFieldViews = computed(() =>
 // The subset of create views that actually contribute a value. Display-only
 // fields (e.g. a `content` field showing instructions) still render, but
 // `formInputComponent()` returns static markup with no value, so they must not
-// be seeded, validated, or submitted.
+// be seeded, validated, or submitted. An avatar field is submittable (its `File`
+// rides the create payload as a multipart part), so it's seeded and validated
+// here like any other input.
 const createInputViews = computed(() =>
   createFieldViews.value.filter((v) => v.field.isSubmittable())
 )
@@ -201,6 +204,8 @@ async function onCreate() {
     for (const { key, field } of createInputViews.value) {
       values[key] = field.inputToPayload(createModel[key])
     }
+    // A picked avatar `File` rides `values`; `edit.create` sends the payload
+    // multipart when one is present, so the avatar persists with the new record.
     await edit!.create(values)
     emit('close')
   } catch (e) {
@@ -327,13 +332,20 @@ const slotProps = computed(() => ({
             {{ t.load_error }}
           </div>
           <div v-else class="sheet-rows">
-            <LensSheetField
-              v-for="entry in detailFields"
-              :key="entry.key"
-              :field="entry.field"
-              :field-key="entry.key"
-              :record
-            />
+            <template v-for="entry in detailFields" :key="entry.key">
+              <LensSheetAvatarField
+                v-if="entry.fieldData.type === 'avatar'"
+                :field="entry.field"
+                :field-key="entry.key"
+                :record
+              />
+              <LensSheetField
+                v-else
+                :field="entry.field"
+                :field-key="entry.key"
+                :record
+              />
+            </template>
           </div>
         </template>
 

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

@@ -0,0 +1,138 @@
+<script setup lang="ts">
+import { computed, reactive, ref, watch } from 'vue'
+import SDataListItem from '../../../components/SDataListItem.vue'
+import { useTrans } from '../../../composables/Lang'
+import { useValidation } from '../../../composables/Validation'
+import { useSnackbars } from '../../../stores/Snackbars'
+import { type FieldData } from '../FieldData'
+import { useLensEdit } from '../composables/LensEdit'
+import { type AvatarField } from '../fields/AvatarField'
+import { type Field } from '../fields/Field'
+import LensAvatarInput from './LensAvatarInput.vue'
+
+const props = defineProps<{
+  field: Field<FieldData>
+  fieldKey: string
+  record: Record<string, any>
+}>()
+
+// The table only renders this component for `avatar` fields, so the field is
+// always an `AvatarField` — narrow it for the avatar-specific config getters.
+const avatarField = computed(() => props.field as AvatarField)
+
+const { t } = useTrans({
+  en: { save_error: 'We couldn’t save the image. Please try again.' },
+  ja: { save_error: '画像を保存できませんでした。もう一度お試しください。' }
+})
+
+const edit = useLensEdit()
+const snackbars = useSnackbars()
+
+// Editable only when the row passes the edit gate and the field is marked
+// editable; the image is written through the Lens update (a blocking save).
+const editable = computed(() =>
+  !!edit?.canEdit(props.record)
+  && (props.field as any).data?.showOnUpdate === true
+)
+
+// Materialize the read-only display component once (computed off `props.field`):
+// `dataListItemComponent()` mints a fresh definition each call, so resolving it
+// inline in the template would unmount/remount the avatar on every reactive row
+// update (e.g. a write's `patch`), causing flicker.
+const displayComponent = computed(() => props.field.dataListItemComponent())
+
+const saving = ref(false)
+
+// The value the picker shows: the row's current image URL, except while a save
+// is in flight (then the local file preview the change handler set).
+const model = ref<File | string | null>(props.record[props.fieldKey] ?? null)
+
+watch(
+  () => props.record[props.fieldKey],
+  (value) => { if (!saving.value) { model.value = value ?? null } }
+)
+
+// Validate the picked value (a File, or null on removal) against the field rules
+// before the blocking save. The model usually holds the existing image URL — a
+// string the file rules reject — so validation runs on what's submitted, here,
+// rather than inline on the input (which would flag the unchanged URL).
+const pending = reactive<{ value: File | null }>({ value: null })
+const { validation, validate } = useValidation(
+  () => pending,
+  () => ({ value: avatarField.value.generateValidationRules() })
+)
+
+async function onChange(value: File | string | null | undefined) {
+  // A string is the existing URL still selected — nothing to save.
+  if (typeof value === 'string') {
+    model.value = value
+    return
+  }
+  const file = value ?? null
+  // Capture the record being edited: the sheet can be closed and reopened on
+  // another row while this save is in flight (only the input is disabled, not
+  // the sheet), so `props.record` may point elsewhere by the time we resolve.
+  const record = props.record
+  // Show the picked file (or the cleared empty state) immediately.
+  model.value = file
+
+  pending.value = file
+  if (!(await validate())) {
+    const message = validation.value.$errors[0]?.$message
+    snackbars.push({ mode: 'danger', text: message ? String(message) : t.save_error })
+    if (props.record === record) {
+      model.value = record[props.fieldKey] ?? null
+    }
+    return
+  }
+
+  saving.value = true
+  try {
+    // The catalog writes through the Lens update and patches the captured
+    // record's column itself (with write accounting); reflect the canonical
+    // value on this picker if it still shows the same record.
+    await edit?.saveBlocking(record, { [props.fieldKey]: file })
+    if (props.record === record) {
+      model.value = record[props.fieldKey] ?? null
+    }
+  } catch {
+    if (props.record === record) {
+      model.value = record[props.fieldKey] ?? null
+    }
+    snackbars.push({ mode: 'danger', text: t.save_error })
+  } finally {
+    saving.value = false
+    // If the sheet rebound to another row mid-save, resync the picker to it
+    // (the `props.record` watcher skipped re-seeding while `saving` was true).
+    if (props.record !== record) {
+      model.value = props.record[props.fieldKey] ?? null
+    }
+  }
+}
+</script>
+
+<template>
+  <div class="LensSheetAvatarField">
+    <SDataListItem v-if="editable">
+      <template #label>{{ field.label() }}</template>
+      <template #value>
+        <LensAvatarInput
+          :model-value="model"
+          :accept="avatarField.accept()"
+          :image-type="avatarField.imageType()"
+          :help="field.help() || undefined"
+          :disabled="saving"
+          @update:model-value="onChange"
+        />
+      </template>
+    </SDataListItem>
+    <component :is="displayComponent" v-else :value="record[fieldKey]" />
+  </div>
+</template>
+
+<style scoped lang="postcss">
+.LensSheetAvatarField {
+  position: relative;
+  border-bottom: 1px dashed var(--c-divider);
+}
+</style>

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

@@ -5,13 +5,14 @@ import { computed, markRaw } from 'vue'
 import STable from '../../../components/STable.vue'
 import { type DropdownSection } from '../../../composables/Dropdown'
 import { type TableCell, type TableColumns, useTable } from '../../../composables/Table'
-import { type FieldData } from '../FieldData'
+import { type AvatarFieldData, type FieldData } from '../FieldData'
 import { type LensQuerySort } from '../LensQuery'
 import { type LensResult } from '../LensResult'
 import { useFieldFactory } from '../composables/FieldFactory'
 import { useLensEdit } from '../composables/LensEdit'
 import { provideLensInlineEdit } from '../composables/LensInlineEdit'
 import { type Field } from '../fields/Field'
+import LensTableAvatarCell from './LensTableAvatarCell.vue'
 import LensTableEditableCell from './LensTableEditableCell.vue'
 
 const props = defineProps<{
@@ -44,6 +45,7 @@ const edit = useLensEdit()
 provideLensInlineEdit()
 
 const editableCellComponent = markRaw(LensTableEditableCell)
+const avatarCellComponent = markRaw(LensTableAvatarCell)
 
 const records = computed(() => props.result?.data ?? [])
 
@@ -146,6 +148,31 @@ const columns = computedAsync(async () => {
           onClick: () => edit.openSheet(r)
         }
       }
+    } else if (
+      props.inlineEditable
+      && edit?.editable
+      && key !== edit.indexField
+      && overriddenFieldData.type === 'avatar'
+      && overriddenFieldData.showOnUpdate === true
+    ) {
+      // Avatars get a dedicated cell: a hover overlay to change the image
+      // (written through a blocking Lens update) plus an optional pencil that
+      // edits the display-name companions inline (optimistic). The image and
+      // names are persisted differently, so the generic editable cell (a single
+      // optimistic field write) can't serve them.
+      const avatarData = overriddenFieldData as AvatarFieldData
+      column.cell = {
+        type: 'component',
+        component: avatarCellComponent,
+        props: {
+          field,
+          fieldKey: key,
+          nameEnKey: avatarData.nameEn ?? null,
+          nameJaKey: avatarData.nameJa ?? null,
+          nameFieldEn: makeEditableField(r, avatarData.nameEn),
+          nameFieldJa: makeEditableField(r, avatarData.nameJa)
+        }
+      }
     } else if (
       props.inlineEditable
       && edit?.editable
@@ -237,6 +264,29 @@ function hasFormInput(field: Field<FieldData>): boolean {
     return false
   }
 }
+
+// Build a sibling field instance for inline editing from the current result's
+// field set — but only when it's editable (`showOnUpdate`) and safe to edit the
+// same way the generic inline cell requires: submittable, optimistically
+// patchable, and with a real form input. Used by the avatar cell to edit its
+// display-name companions; this omits a companion that is non-editable, display
+// only (`content`), holds raw files (`file_upload`), or has no input (`id` /
+// `slack_message`), so the name editor can't send an unsafe value or crash.
+function makeEditableField(r: LensResult, key?: string | null): Field<FieldData> | null {
+  if (!key) {
+    return null
+  }
+  const fieldData = r.fields[key]
+  if (!fieldData || fieldData.showOnUpdate !== true) {
+    return null
+  }
+  const data = Object.assign(cloneDeep(fieldData), props.overrides?.[key] ?? {})
+  const field = fieldFactory.make(data)
+  if (!field.isSubmittable() || !field.supportsOptimisticUpdate() || !hasFormInput(field)) {
+    return null
+  }
+  return field
+}
 </script>
 
 <template>

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

@@ -0,0 +1,442 @@
+<script setup lang="ts">
+import IconCamera from '~icons/ph/camera'
+import IconPencilSimple from '~icons/ph/pencil-simple'
+import { useElementBounding } from '@vueuse/core'
+import { computed, nextTick, onUnmounted, reactive, ref, watch } from 'vue'
+import SAvatar from '../../../components/SAvatar.vue'
+import SButton from '../../../components/SButton.vue'
+import SSpinner from '../../../components/SSpinner.vue'
+import { useManualDropdownPosition } from '../../../composables/Dropdown'
+import { useTrans } from '../../../composables/Lang'
+import { useValidation } from '../../../composables/Validation'
+import { useSnackbars } from '../../../stores/Snackbars'
+import { type FieldData } from '../FieldData'
+import { useLensEdit } from '../composables/LensEdit'
+import { useLensInlineEdit } from '../composables/LensInlineEdit'
+import { type AvatarField } from '../fields/AvatarField'
+import { type Field } from '../fields/Field'
+
+const props = defineProps<{
+  field: AvatarField
+  fieldKey: string
+  // The English / Japanese display-name companion fields, resolved by the table
+  // from the avatar field's `nameEn` / `nameJa` keys. Present only when the
+  // avatar declares them, so the names can be edited alongside the image.
+  nameEnKey?: string | null
+  nameJaKey?: string | null
+  nameFieldEn?: Field<FieldData> | null
+  nameFieldJa?: Field<FieldData> | null
+  // Injected by STable for a `component` cell: the cell value (image URL) and
+  // the full row record.
+  value: any
+  record: Record<string, any>
+}>()
+
+const { t } = useTrans({
+  en: { cancel: 'Cancel', save: 'Save', edit_image: 'Change image', edit_names: 'Edit name', upload_error: 'We couldn’t upload the image. Please try again.' },
+  ja: { cancel: 'キャンセル', save: '保存', edit_image: '画像を変更', edit_names: '名前を編集', upload_error: '画像をアップロードできませんでした。もう一度お試しください。' }
+})
+
+const edit = useLensEdit()
+const inline = useLensInlineEdit()
+const snackbars = useSnackbars()
+
+const canEdit = computed(() => !!edit?.canEdit(props.record))
+
+// The image is written through the Lens update (a blocking save); the overlay
+// affordance is shown whenever the row is editable.
+const canEditImage = computed(() => canEdit.value)
+
+const nameEntries = computed(() => {
+  const entries: { key: string; field: Field<FieldData> }[] = []
+  const seen = new Set<string>()
+  const add = (key: string | null | undefined, field: Field<FieldData> | null | undefined): void => {
+    // Skip a companion that isn't fetched on this row — editing the visible name
+    // would otherwise send an empty value for the unfetched sibling and clear it
+    // (e.g. `loadSelectable` exposes `name_ja` in `fields` while the select omits
+    // it). De-duplicate too: both languages may point at one shared name column.
+    if (!key || !field || seen.has(key) || !(key in props.record)) {
+      return
+    }
+    seen.add(key)
+    entries.push({ key, field })
+  }
+  add(props.nameEnKey, props.nameFieldEn)
+  add(props.nameJaKey, props.nameFieldJa)
+  return entries
+})
+
+const canEditNames = computed(() => canEdit.value && nameEntries.value.length > 0)
+
+// --- Display (mirrors STableCellAvatar) -------------------------------------
+
+const base = computed<any>(() => props.field.tableCell(props.value, props.record))
+
+// While an upload is in flight, show a local preview of the picked file so the
+// new image appears immediately instead of waiting on the round-trip.
+const previewSrc = ref<string | null>(null)
+const displayImage = computed(() => previewSrc.value ?? base.value.image ?? null)
+const displayName = computed(() => base.value.name || null)
+
+// --- Image edit (file picker -> blocking Lens update) -----------------------
+
+const fileInput = ref<HTMLInputElement | null>(null)
+const uploading = ref(false)
+
+// Validate the picked image against the field rules before the blocking save.
+// The picked value is a raw `File` (or null), so the file rules apply directly.
+const imagePending = reactive<{ value: File | null }>({ value: null })
+const { validation: imageValidation, validate: validateImage } = useValidation(
+  () => imagePending,
+  () => ({ value: props.field.generateValidationRules() })
+)
+
+function pickImage() {
+  if (!canEditImage.value || uploading.value) {
+    return
+  }
+  fileInput.value?.click()
+}
+
+async function onFilePicked(event: Event) {
+  const input = event.target as HTMLInputElement
+  const file = (input.files ?? [])[0] ?? null
+  // Reset the input so picking the same file again still fires `change`.
+  input.value = ''
+  if (!file) {
+    return
+  }
+  await upload(file)
+}
+
+async function upload(file: File | null) {
+  if (!canEditImage.value) {
+    return
+  }
+  imagePending.value = file
+  if (!(await validateImage())) {
+    const message = imageValidation.value.$errors[0]?.$message
+    snackbars.push({ mode: 'danger', text: message ? String(message) : t.upload_error })
+    return
+  }
+  uploading.value = true
+  previewSrc.value = file ? URL.createObjectURL(file) : null
+  try {
+    // The catalog writes through the Lens update and patches the row's column
+    // itself, with write accounting so a concurrent query change can't land
+    // stale rows over it; the patched value is the URL, never the raw file.
+    await edit?.saveBlocking(props.record, { [props.fieldKey]: file })
+  } catch {
+    // saveBlocking rejects on a failed write; guard with a generic message so a
+    // failure never goes unreported.
+    snackbars.push({ mode: 'danger', text: t.upload_error })
+  } finally {
+    if (previewSrc.value) {
+      URL.revokeObjectURL(previewSrc.value)
+      previewSrc.value = null
+    }
+    uploading.value = false
+  }
+}
+
+// --- Name edit (floating editor anchored to the cell) -----------------------
+
+const myKey = computed(() => `${edit?.resolveId(props.record)}:${props.fieldKey}`)
+const editingNames = computed(() => inline?.activeKey.value === myKey.value)
+
+const anchor = ref<HTMLElement | null>(null)
+const editorEl = ref<HTMLElement | null>(null)
+const bounds = useElementBounding(anchor)
+const { inset, update } = useManualDropdownPosition(anchor)
+
+const nameModel = reactive<Record<string, any>>({})
+
+// Materialize the name inputs once so the editor doesn't mint a fresh component
+// definition each render (which breaks Vue's patching).
+const nameInputs = computed(() =>
+  nameEntries.value.map((entry) => ({
+    key: entry.key,
+    field: entry.field,
+    component: entry.field.formInputComponent()
+  }))
+)
+
+const { validation, validate, reset } = useValidation(
+  () => nameModel,
+  () => Object.fromEntries(nameEntries.value.map((e) => [e.key, e.field.generateValidationRules()]))
+)
+
+const editorStyle = computed(() => ({
+  ...inset.value,
+  width: `${Math.max(bounds.width.value, 280)}px`
+}))
+
+// If the backing record is replaced while the name editor is open (a refresh
+// apply, a parent refresh, a requery), close it so a stale model can't be saved.
+watch(
+  () => nameEntries.value.map((e) => props.record[e.key]),
+  () => { if (editingNames.value) { inline?.stop() } },
+  { deep: true }
+)
+
+// STable virtualization can unmount this row while scrolling; clear the shared
+// active key on unmount so a remount doesn't reopen a blank editor.
+onUnmounted(() => {
+  if (inline?.activeKey.value === myKey.value) {
+    inline.stop()
+  }
+})
+
+function startNames() {
+  if (!canEditNames.value) {
+    return
+  }
+  for (const entry of nameEntries.value) {
+    nameModel[entry.key] = entry.field.payloadToInput(props.record[entry.key] ?? entry.field.inputEmptyValue())
+  }
+  reset()
+  inline?.start(myKey.value)
+  nextTick(() => {
+    update()
+    const el = editorEl.value?.querySelector('input, textarea, [contenteditable], [tabindex]') as HTMLElement | null
+    el?.focus()
+  })
+}
+
+function cancelNames() {
+  inline?.stop()
+}
+
+async function applyNames() {
+  // Snapshot the companion values we're editing so we can detect the backing row
+  // being replaced (a refresh apply, a parent refresh, a requery, or a sibling
+  // save) during the async validate, and avoid clobbering the fresh state.
+  const edited = nameEntries.value.map((entry) => props.record[entry.key])
+
+  if (!(await validate())) {
+    return
+  }
+
+  // A refresh / requery can swap a companion value during the validate microtask;
+  // the watcher above closes the editor but flushes asynchronously and can't abort
+  // this running apply, so re-check against the snapshot. If any changed, `model`
+  // predates the fresh value — bail rather than overwrite it.
+  if (nameEntries.value.some((entry, i) => props.record[entry.key] !== edited[i])) {
+    if (inline?.activeKey.value === myKey.value) {
+      inline.stop()
+    }
+    return
+  }
+
+  // The editable predicate can flip to reject this row while the editor is open.
+  if (!canEditNames.value) {
+    if (inline?.activeKey.value === myKey.value) {
+      inline.stop()
+    }
+    return
+  }
+  const values: Record<string, any> = {}
+  for (const entry of nameEntries.value) {
+    values[entry.key] = entry.field.inputToPayload(nameModel[entry.key])
+  }
+  edit!.save(props.record, values)
+  if (inline?.activeKey.value === myKey.value) {
+    inline.stop()
+  }
+}
+
+function onEditorKeydown(event: KeyboardEvent) {
+  if (event.key === 'Escape') {
+    event.preventDefault()
+    cancelNames()
+  }
+}
+</script>
+
+<template>
+  <div ref="anchor" class="LensTableAvatarCell" :class="{ editing: editingNames }">
+    <div v-if="displayImage || displayName || canEditImage" class="avatar">
+      <button
+        class="image"
+        type="button"
+        :class="{ editable: canEditImage }"
+        :disabled="!canEditImage || uploading"
+        :aria-label="`${t.edit_image} ${field.label()}`"
+        @click="pickImage"
+      >
+        <SAvatar size="mini" :avatar="displayImage" :name="displayName" />
+        <span v-if="canEditImage" class="image-overlay">
+          <SSpinner v-if="uploading" class="image-spinner" />
+          <IconCamera v-else class="image-icon" />
+        </span>
+      </button>
+      <span v-if="displayName" class="name">{{ displayName }}</span>
+    </div>
+
+    <input
+      v-if="canEditImage"
+      ref="fileInput"
+      class="file-input"
+      type="file"
+      :accept="field.accept()"
+      @change="onFilePicked"
+    >
+
+    <button
+      v-if="canEditNames"
+      class="edit"
+      type="button"
+      :aria-label="`${t.edit_names} ${field.label()}`"
+      @click="startNames"
+    >
+      <IconPencilSimple class="edit-icon" />
+    </button>
+
+    <Teleport v-if="editingNames" to="#sefirot-modals">
+      <div
+        ref="editorEl"
+        class="LensTableAvatarCellEditor"
+        :style="editorStyle"
+        @keydown="onEditorKeydown"
+      >
+        <component
+          :is="input.component"
+          v-for="input in nameInputs"
+          :key="input.key"
+          v-model="nameModel[input.key]"
+          :validation="validation[input.key]"
+        />
+        <div class="actions">
+          <SButton size="mini" :label="t.cancel" @click="cancelNames" />
+          <SButton size="mini" mode="info" :label="t.save" @click="applyNames" />
+        </div>
+      </div>
+    </Teleport>
+  </div>
+</template>
+
+<style scoped lang="postcss">
+.LensTableAvatarCell {
+  position: relative;
+  display: flex;
+  align-items: center;
+  min-width: 0;
+  min-height: 40px;
+  padding: 8px 36px 8px 16px;
+}
+
+.avatar {
+  display: flex;
+  align-items: center;
+  min-width: 0;
+}
+
+.image {
+  position: relative;
+  display: flex;
+  flex-shrink: 0;
+  border-radius: 50%;
+}
+
+.image.editable {
+  cursor: pointer;
+}
+
+.image:disabled {
+  cursor: default;
+}
+
+.image-overlay {
+  position: absolute;
+  inset: 0;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  border-radius: 50%;
+  background-color: rgba(0, 0, 0, 0.5);
+  color: #fff;
+  opacity: 0;
+  transition: opacity 0.1s;
+}
+
+.image.editable:hover .image-overlay,
+.image:disabled .image-overlay {
+  opacity: 1;
+}
+
+.image-icon {
+  width: 12px;
+  height: 12px;
+}
+
+.image-spinner {
+  width: 12px;
+  height: 12px;
+}
+
+.name {
+  display: inline-block;
+  margin-left: 8px;
+  line-height: 24px;
+  font-size: var(--table-cell-font-size);
+  font-weight: var(--table-cell-font-weight);
+  color: var(--c-text-1);
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.file-input {
+  display: none;
+}
+
+.edit {
+  position: absolute;
+  top: 50%;
+  right: 8px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 24px;
+  height: 24px;
+  transform: translateY(-50%);
+  border-radius: 6px;
+  color: var(--c-text-2);
+  opacity: 0;
+  transition: opacity 0.1s, background-color 0.1s, color 0.1s;
+}
+
+.LensTableAvatarCell:hover .edit,
+.LensTableAvatarCell.editing .edit {
+  opacity: 1;
+}
+
+.edit:hover {
+  background-color: var(--c-bg-mute-1);
+  color: var(--c-text-1);
+}
+
+.edit-icon {
+  width: 14px;
+  height: 14px;
+}
+
+.LensTableAvatarCellEditor {
+  position: fixed;
+  z-index: var(--z-index-sheet, 2000);
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  padding: 8px;
+  border: 1px solid var(--c-border);
+  border-radius: 8px;
+  background-color: var(--c-bg-1);
+  box-shadow: var(--shadow-depth-3);
+}
+
+.actions {
+  display: flex;
+  justify-content: flex-end;
+  gap: 8px;
+}
+</style>

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

@@ -35,6 +35,21 @@ export interface LensEditContext {
    */
   save: (record: Record<string, any>, values: Record<string, any>) => void
 
+  /**
+   * Apply an update that can't be shown optimistically and wait for it. Some
+   * fields hold a value whose shape differs from what the row renders — a file
+   * input holds a raw `File`, not the displayed image URL — so the row can only
+   * reflect the change once the write returns the canonical value. Awaits the
+   * Lens update (sent multipart when a `File` is present) and patches the
+   * submitted columns from the response. Accounted for like an optimistic write
+   * (the query controls lock while it's in flight and a reconcile resyncs once it
+   * settles), so a concurrent refetch can't land stale rows over it. Patches the
+   * live displayed row (resolved by id) as well as the `record` passed at call
+   * time. Rejects if the write fails (the caller surfaces it and keeps the
+   * previous value).
+   */
+  saveBlocking: (record: Record<string, any>, values: Record<string, any>) => Promise<void>
+
   /**
    * Create a new record. Blocking: resolves once the record is persisted and
    * the catalog has been refreshed with the canonical state.
@@ -52,6 +67,13 @@ export interface LensEditContext {
 
   /** Open the record sheet in create mode. */
   openCreate: () => void
+
+  /**
+   * Re-run the current query against the server, preserving the catalog's
+   * in-memory state. Used to reflect an external change once it has settled.
+   * No-ops while a write or create is in flight.
+   */
+  refresh: () => Promise<void>
 }
 
 const LensEditKey: InjectionKey<LensEditContext> = Symbol('LensEdit')

package/lib/blocks/lens/fields/AvatarField.ts

@@ -3,6 +3,7 @@ import SAvatar from '../../../components/SAvatar.vue'
 import { type TableCell } from '../../../composables/Table'
 import { type AvatarFieldData } from '../FieldData'
 import { type FilterOperator } from '../FilterOperator'
+import LensAvatarInput from '../components/LensAvatarInput.vue'
 import { type FilterInput } from '../filter-inputs/FilterInput'
 import { Field } from './Field'
 
@@ -10,7 +11,7 @@ export class AvatarField extends Field<AvatarFieldData> {
   override tableCell(v: any, r: any): TableCell {
     // The display name lives on a sibling key of the record (resolved by the
     // active language), not on the field value, which is the image URL.
-    const nameKey = this.ctx.lang === 'ja' ? this.data.nameJa : this.data.nameEn
+    const nameKey = this.nameKey()
     return {
       type: 'avatar',
       // The field value is the image URL itself. A missing value renders an
@@ -28,6 +29,13 @@ export class AvatarField extends Field<AvatarFieldData> {
     return {}
   }
 
+  // Sort by the display-name companion (resolved by the active language), since
+  // the field value itself is the image URL. With no companion configured there's
+  // nothing meaningful to sort on, so the field stays unsortable (no sort menu).
+  protected override sortKey(): string | null {
+    return this.nameKey()
+  }
+
   override dataListItemComponent(): any {
     return this.defineDataListItemComponent((value) => {
       // Render nothing for a missing image so SDataListItem shows its empty
@@ -37,7 +45,54 @@ export class AvatarField extends Field<AvatarFieldData> {
     })
   }
 
+  // The avatar value is a raw `File` on edit (or null on removal), submitted
+  // through the Lens create/update write as a multipart part — so it stays
+  // submittable (the base default). On read it's the image URL, a different
+  // shape that can't be shown optimistically: the write must complete before the
+  // row can reflect the new URL. So editing routes through the dedicated avatar
+  // cell / sheet field (a blocking save), never the generic optimistic cell/field
+  // editors, which would patch the row with a raw `File` and crash the URL renderer.
+  override supportsOptimisticUpdate(): boolean {
+    return false
+  }
+
+  override inputEmptyValue(): any {
+    return null
+  }
+
   override formInputComponent(): any {
-    throw new Error('Not implemented.')
+    return this.defineFormInputComponent((props, { emit }) => {
+      return () => h(LensAvatarInput, {
+        'label': this.formInputLabel(),
+        'help': this.help() || undefined,
+        'accept': this.accept(),
+        'imageType': this.imageType(),
+        'modelValue': props.modelValue,
+        'validation': props.validation,
+        'onUpdate:modelValue': (value: any) => {
+          emit('update:modelValue', value)
+        }
+      })
+    })
+  }
+
+  /** The `accept` attribute for the file picker. */
+  accept(): string {
+    return this.data.accept || 'image/*'
+  }
+
+  /** The picker preview shape. */
+  imageType(): 'circle' | 'rectangle' {
+    return this.data.imageType || 'circle'
+  }
+
+  /** The companion name key resolved against the active language, if any. */
+  nameKey(): string | null {
+    return (this.ctx.lang === 'ja' ? this.data.nameJa : this.data.nameEn) ?? null
+  }
+
+  /** The configured English / Japanese display-name keys. */
+  nameKeys(): { en: string | null; ja: string | null } {
+    return { en: this.data.nameEn ?? null, ja: this.data.nameJa ?? null }
   }
 }

package/lib/blocks/lens/fields/Field.ts

@@ -81,12 +81,25 @@ export abstract class Field<T extends FieldData> {
     }
   }
 
+  /**
+   * The field key sorts are emitted under — the catalog sends it to the backend,
+   * which orders by that field's column. Defaults to the field's own key; a
+   * subtype whose own value isn't meaningful to sort on can redirect it (e.g. an
+   * avatar sorts by its display-name companion). A `null` makes the field
+   * unsortable, so no sort menu is shown.
+   */
+  protected sortKey(): string | null {
+    return this.data.key
+  }
+
   /**
    * Renders the table sort menu for the field. The sort maybe null when
-   * the field `sortable` option is false.
+   * the field `sortable` option is false (or it has no sortable key).
    */
   tableSortMenu(onSortUpdated: (sort: LensQuerySort) => void): DropdownSection | null {
-    if (!this.data.sortable) {
+    const sortKey = this.sortKey()
+
+    if (!this.data.sortable || sortKey === null) {
       return null
     }
 
@@ -100,8 +113,8 @@ export abstract class Field<T extends FieldData> {
     return {
       type: 'menu',
       options: [
-        { label: t.sort_asc, onClick: () => onSortUpdated?.([this.data.key, 'asc']) },
-        { label: t.sort_desc, onClick: () => onSortUpdated?.([this.data.key, 'desc']) }
+        { label: t.sort_asc, onClick: () => onSortUpdated?.([sortKey, 'asc']) },
+        { label: t.sort_desc, onClick: () => onSortUpdated?.([sortKey, 'desc']) }
       ]
     }
   }

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

@@ -9,6 +9,8 @@ import {
   decimal,
   decimalOrHyphen,
   email,
+  fileExtension,
+  maxFileSize,
   maxLength,
   maxValue,
   minLength,
@@ -126,6 +128,10 @@ function mapRule(rule: Exclude<Rule, EachRule>): ValidationRuleWithParams | null
       return after(resolveDate(rule.date))
     case 'after_or_equal':
       return afterOrEqual(resolveDate(rule.date))
+    case 'file_extension':
+      return fileExtension(rule.extensions)
+    case 'max_file_size':
+      return maxFileSize(rule.size)
     default: {
       const _exhaustive: never = rule
       throw new Error(`Unsupported rule type: ${(_exhaustive as Rule).type}`)

package/lib/components/SInputImage.vue

@@ -63,12 +63,20 @@ function openFileSelect() {
 }
 
 function onFileSelect(e: Event) {
-  const file = ((e.target as HTMLInputElement).files ?? [])[0]
+  const input = e.target as HTMLInputElement
+  const file = (input.files ?? [])[0]
 
   emit('update:model-value', file ?? null)
   emit('change', file ?? null)
 
   file && props.validation?.$touch()
+
+  // Clear the native input after capturing the file, so re-selecting the *same*
+  // file fires `change` again (the browser suppresses it when the value is
+  // unchanged). Matters when a consumer rejects/undoes a pick (e.g. a failed
+  // upload) and the user re-picks the same image. The preview reads the model,
+  // not the input, so clearing it is safe.
+  input.value = ''
 }
 
 function onFileDelete() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@globalbrain/sefirot",
-  "version": "4.52.1",
+  "version": "4.54.0",
   "description": "Vue Components for Global Brain Design System.",
   "keywords": [
     "components",
@@ -59,8 +59,8 @@
     "@iconify-json/ph": "^1.2.2",
     "@iconify-json/ri": "^1.2.10",
     "@popperjs/core": "^2.11.8",
-    "@sentry/browser": "^10.58.0",
-    "@sentry/vue": "^10.58.0",
+    "@sentry/browser": "^10.62.0",
+    "@sentry/vue": "^10.62.0",
     "@tanstack/vue-virtual": "3.0.0-beta.62",
     "@tinyhttp/content-disposition": "^2.2.4",
     "@tinyhttp/cookie": "^2.1.1",
@@ -71,7 +71,7 @@
     "@types/markdown-it": "^14.1.2",
     "@types/qs": "^6.15.1",
     "@vitejs/plugin-vue": "^6.0.7",
-    "@vue/reactivity": "^3.5.38",
+    "@vue/reactivity": "^3.5.39",
     "@vuelidate/core": "^2.0.3",
     "@vuelidate/validators": "^2.0.4",
     "@vueuse/core": "^14.3.0",
@@ -91,11 +91,11 @@
     "postcss": "^8.5.15",
     "postcss-nested": "^7.0.2",
     "punycode": "^2.3.1",
-    "qs": "^6.15.2",
+    "qs": "^6.15.3",
     "unplugin-icons": "^23.0.1",
     "v-calendar": "3.0.1",
-    "vite": "^7.3.5",
-    "vue": "^3.5.38",
+    "vite": "^7.3.6",
+    "vue": "^3.5.39",
     "vue-draggable-plus": "^0.6.1",
     "vue-router": "^5.1.0"
   },
@@ -104,18 +104,18 @@
     "@histoire/plugin-vue": "1.0.0-beta.1",
     "@release-it/conventional-changelog": "^11.0.1",
     "@types/jsdom": "^28.0.3",
-    "@types/node": "^26.0.0",
-    "@typescript-eslint/rule-tester": "^8.61.1",
+    "@types/node": "^26.0.1",
+    "@typescript-eslint/rule-tester": "^8.62.0",
     "@vitest/coverage-v8": "^4.1.9",
     "@vue/test-utils": "^2.4.11",
     "eslint": "^9.39.4",
-    "happy-dom": "^20.10.5",
+    "happy-dom": "^20.10.6",
     "histoire": "1.0.0-beta.1",
-    "release-it": "^20.2.0",
+    "release-it": "^20.2.1",
     "typescript": "~6.0.3",
     "vitepress": "^2.0.0-alpha.17",
     "vitest": "^4.1.9",
     "vue-tsc": "^3.3.5"
   },
-  "packageManager": "pnpm@11.7.0"
+  "packageManager": "pnpm@11.9.0"
 }