@globalbrain/sefirot 4.55.0 → 4.57.0

package/lib/blocks/lens/LensCreateExtension.ts

@@ -0,0 +1,43 @@
+/**
+ * A create-form extension contributed by a sheet slot (`#before` / `#after`).
+ *
+ * The catalog's create form builds its payload from the entity's own Lens
+ * fields. A page may need to create related data that isn't a Lens field (e.g. a
+ * collaborator's social links, written server-side alongside the record). Such a
+ * slot registers an extension via the `registerCreateExtension` slot prop: on
+ * submit the sheet runs every registered extension to validate the slot's own
+ * inputs and merge its extra keys into the create payload.
+ */
+export interface LensCreateContribution {
+  /**
+   * Whether the slot's own inputs passed validation. When any registered
+   * extension reports `false`, the create is aborted (the sheet stays open so
+   * each slot can show its own errors).
+   */
+  valid: boolean
+
+  /**
+   * Extra key/value pairs merged into the create payload (e.g.
+   * `{ social_links: [...] }`). Ignored when `valid` is `false`.
+   */
+  values: Record<string, any>
+}
+
+/**
+ * A function the sheet calls on create-submit. It validates the slot's inputs
+ * and returns its contribution; it may be async (validation usually is). It
+ * should report `valid: false` rather than throw — a throw propagates to the
+ * sheet's submit handler as an unexpected error.
+ */
+export type LensCreateExtension = () =>
+  | LensCreateContribution
+  | Promise<LensCreateContribution>
+
+/**
+ * Register a {@link LensCreateExtension} with the sheet's create form. Returns a
+ * disposer that unregisters it — call it on unmount (the create slot content
+ * unmounts with the sheet, so a component-lifecycle cleanup suffices).
+ */
+export type RegisterLensCreateExtension = (
+  extension: LensCreateExtension
+) => () => void

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

@@ -0,0 +1,92 @@
+<script setup lang="ts">
+import SInputSelectSearch, { type Option } from '../../../components/SInputSelectSearch.vue'
+import { useMutation } from '../../../composables/Api'
+import { useLang } from '../../../composables/Lang'
+import { type LensQuerySettings, type LensQuerySort } from '../LensQuery'
+import { isAuthError } from '../validation/ServerErrors'
+
+export type { Color, Size } from '../../../components/SInputBase.vue'
+export type { Option }
+
+// A lens-backed search-select. Combines the search (a lens query), the fetch (no
+// repo needed), and the row → option mapping (no ops needed) into one component:
+// the consumer configures the entity and how a row becomes an option, and the
+// component searches the server as the user types via SInputSelectSearch.
+//
+// Selection UI props (multiple, nullable, disabled, placeholder, size, label,
+// validation, position, closeOnSelect, debounce, …) fall through to
+// SInputSelectSearch as attributes.
+export interface Props {
+  // The lens search endpoint (e.g. `/api/admin/lens/search`).
+  endpoint: string
+
+  // The entity to search.
+  entity: string
+
+  // Columns to fetch for each row, projected into an option by `toOption`.
+  select: string[]
+
+  // Columns matched against the typed query — OR-ed together with `contains`.
+  // An empty query fetches the initial (unfiltered) page. Named to match
+  // LensCatalog's `queryKeys`.
+  queryKeys: string[]
+
+  // Sort applied to the results (e.g. `[['name', 'asc']]`). Re-read on each fetch,
+  // so a locale-dependent sort stays current.
+  sort?: LensQuerySort[]
+
+  // Page size of each search. The server enforces its own perPage ceiling.
+  perPage?: number
+
+  // Per-request settings (e.g. language). Usually unneeded — the server negotiates
+  // language from the request headers.
+  settings?: LensQuerySettings
+
+  // Map a raw result row to an option. The selected option(s) are the model, so
+  // include everything the consumer needs back (e.g. a related record), plus the
+  // `value` / `label` (and `image` for an avatar option) the select renders.
+  toOption: (row: Record<string, any>) => Option
+}
+
+const props = defineProps<Props>()
+
+// Pass the selection through to SInputSelectSearch. Typed loosely so a consumer
+// can bind a ref of its own richer option type (see SInputSelectSearch).
+const model = defineModel<any>({ required: true })
+
+// Don't let lens-config attributes that happen to share a name leak onto the
+// child; only the explicitly-forwarded selection props (via `$attrs`) should.
+defineOptions({ inheritAttrs: false })
+
+// Default the request language to the active app language (like LensCatalog), so
+// server-localized fields come back in the right locale even when HttpConfig /
+// request headers differ; explicit `settings` (incl. `lang`) overrides it.
+const lang = useLang()
+
+const { execute } = useMutation((http, query: string) =>
+  http.post<{ data: Record<string, any>[] }>(props.endpoint, {
+    entity: props.entity,
+    select: props.select,
+    filters: query
+      ? [['$or', props.queryKeys.map((key) => [key, 'contains', query])]]
+      : [],
+    sort: props.sort ?? [],
+    page: 1,
+    perPage: props.perPage ?? 25,
+    settings: { lang, ...props.settings }
+  })
+)
+
+// Read every config field through `props` at call time so a reactive change
+// (e.g. a locale-dependent sort or label) takes effect on the next search.
+async function fetch(query: string): Promise<Option[]> {
+  const res = await execute(query)
+  return res.data.map(props.toOption)
+}
+</script>
+
+<template>
+  <SInputSelectSearch v-model="model" :fetch :rethrow="isAuthError" v-bind="$attrs">
+    <template v-if="$slots.info" #info><slot name="info" /></template>
+  </SInputSelectSearch>
+</template>

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

@@ -11,6 +11,7 @@ import { usePower } from '../../../composables/Power'
 import { useValidation } from '../../../composables/Validation'
 import { useSnackbars } from '../../../stores/Snackbars'
 import { type FieldData } from '../FieldData'
+import { type LensCreateExtension } from '../LensCreateExtension'
 import { useFieldFactory } from '../composables/FieldFactory'
 import { useLensEdit } from '../composables/LensEdit'
 import { extractServerErrors, extractServerMessage } from '../validation/ServerErrors'
@@ -177,6 +178,19 @@ watch(
   { immediate: true }
 )
 
+// Create-form extensions registered by sheet slots (`#before` / `#after`) — a
+// page's custom inputs that aren't Lens fields (e.g. social links written
+// server-side alongside the record). On submit each is run to validate its own
+// inputs and contribute extra keys to the create payload. Registered on mount and
+// disposed on unmount; the create slot content unmounts with the sheet, so a
+// component-lifecycle cleanup keeps this empty between creates.
+const createExtensions = new Set<LensCreateExtension>()
+
+function registerCreateExtension(extension: LensCreateExtension): () => void {
+  createExtensions.add(extension)
+  return () => { createExtensions.delete(extension) }
+}
+
 async function onCreate() {
   // Guard re-entry: set `saving` before the first await so a fast double-click on
   // Create can't start a second submission (and create a duplicate record) while
@@ -197,13 +211,32 @@ async function onCreate() {
   serverErrors.value = {}
 
   try {
-    if (!(await validate())) {
+    // Validate the built-in fields and every registered slot extension, running
+    // them all even when something already failed, so each section surfaces its
+    // own errors on a single submit rather than one at a time. A valid extension
+    // contributes extra keys to the payload; any failure aborts the create.
+    const fieldsValid = await validate()
+    const contributions: Record<string, any>[] = []
+    let extensionsValid = true
+    for (const extend of createExtensions) {
+      const { valid, values } = await extend()
+      if (valid) {
+        contributions.push(values)
+      } else {
+        extensionsValid = false
+      }
+    }
+    if (!fieldsValid || !extensionsValid) {
       return
     }
     const values: Record<string, any> = {}
     for (const { key, field } of createInputViews.value) {
       values[key] = field.inputToPayload(createModel[key])
     }
+    // Merge each extension's contribution (e.g. `social_links`) into the payload.
+    for (const extra of contributions) {
+      Object.assign(values, extra)
+    }
     // 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)
@@ -266,9 +299,11 @@ function requestClose() {
 // that hosts the catalog, so it cannot `inject` the edit context (which is
 // provided inside `LensCatalog`, a child of that page). Expose the pieces a
 // slot needs as slot props instead: the resolved record id, a record-bound
-// partial `save`, and the entity key. This keeps the generic sheet free of
-// one-off concerns (avatar upload, social links, linked records) while still
-// letting a page implement them.
+// partial `save`, the entity key, the sheet `mode` (so a slot can render
+// different content for create vs view), and `registerCreateExtension` (so a
+// create-mode slot can contribute extra keys to the create payload). This keeps
+// the generic sheet free of one-off concerns (avatar upload, social links,
+// linked records) while still letting a page implement them.
 
 const resolvedId = computed(() => (props.record && edit ? edit.resolveId(props.record) : null))
 
@@ -293,6 +328,9 @@ const slotProps = computed(() => ({
   record: props.record ?? null,
   id: resolvedId.value,
   entity: props.entity,
+  // The sheet's current mode, so a slot can branch its content (e.g. show
+  // editable inputs only while creating, and a read/edit view otherwise).
+  mode: props.mode,
   // Surfaced so custom editors can disable their save controls until the full
   // record has loaded; `save` also hard-refuses while loading/error as a guard.
   loading: props.loading ?? false,
@@ -301,7 +339,11 @@ const slotProps = computed(() => ({
   // editor can disable its own controls for a rejected row; `save` enforces it
   // regardless, but otherwise the refusal is only visible as a silent no-op.
   canEdit: !!props.record && !!edit?.canEdit(props.record),
-  save: saveRecord
+  save: saveRecord,
+  // Let a create-mode slot register inputs that contribute extra keys to the
+  // create payload (see LensCreateExtension). Stable identity; a no-op in view
+  // mode (a slot only registers while the create form is shown).
+  registerCreateExtension
 }))
 </script>
 

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

@@ -1,10 +1,11 @@
 <script setup lang="ts">
 import IconPencilSimple from '~icons/ph/pencil-simple'
-import { computed, ref, watch } from 'vue'
+import { computed, nextTick, ref, watch } from 'vue'
 import SButton from '../../../components/SButton.vue'
 import SDataListItem from '../../../components/SDataListItem.vue'
 import { useTrans } from '../../../composables/Lang'
 import { useValidation } from '../../../composables/Validation'
+import { dispatchEditorKeydown, focusFirstEditable } from '../../../support/Dom'
 import { type FieldData } from '../FieldData'
 import { useLensEdit } from '../composables/LensEdit'
 import { type Field } from '../fields/Field'
@@ -90,11 +91,17 @@ const { validation, validate, reset } = useValidation(
   () => ({ input: props.field.generateValidationRules() })
 )
 
+const formEl = ref<HTMLElement | null>(null)
+
 function start() {
   const raw = props.record[props.fieldKey]
   model.value = props.field.payloadToInput(raw ?? props.field.inputEmptyValue())
   reset()
   editing.value = true
+  // Focus the input on open (matching the inline table editor): better UX, and
+  // it routes the editor's keydowns — notably Escape — through the form handler
+  // so Escape cancels the edit rather than closing the sheet.
+  nextTick(() => focusFirstEditable(formEl.value))
 }
 
 function cancel() {
@@ -135,6 +142,12 @@ async function apply() {
   })
   editing.value = false
 }
+
+function onEditorKeydown(event: KeyboardEvent) {
+  // `shield` keeps Escape from reaching the surrounding sheet, which otherwise
+  // closes on it (via SSheet's window-level handler).
+  dispatchEditorKeydown(event, { cancel, submit: apply, shield: true })
+}
 </script>
 
 <template>
@@ -156,7 +169,7 @@ async function apply() {
       </button>
     </div>
 
-    <div v-else class="form">
+    <div v-else ref="formEl" class="form" @keydown="onEditorKeydown">
       <component :is="inputComponent" v-model="model" :validation="validation.input" />
       <div class="actions">
         <SButton size="mini" :label="t.cancel" @click="cancel" />

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

@@ -10,6 +10,7 @@ import { useManualDropdownPosition } from '../../../composables/Dropdown'
 import { useTrans } from '../../../composables/Lang'
 import { useValidation } from '../../../composables/Validation'
 import { useSnackbars } from '../../../stores/Snackbars'
+import { dispatchEditorKeydown, focusFirstEditable } from '../../../support/Dom'
 import { type FieldData } from '../FieldData'
 import { useLensEdit } from '../composables/LensEdit'
 import { useLensInlineEdit } from '../composables/LensInlineEdit'
@@ -198,8 +199,7 @@ function startNames() {
   inline?.start(myKey.value)
   nextTick(() => {
     update()
-    const el = editorEl.value?.querySelector('input, textarea, [contenteditable], [tabindex]') as HTMLElement | null
-    el?.focus()
+    focusFirstEditable(editorEl.value)
   })
 }
 
@@ -246,10 +246,7 @@ async function applyNames() {
 }
 
 function onEditorKeydown(event: KeyboardEvent) {
-  if (event.key === 'Escape') {
-    event.preventDefault()
-    cancelNames()
-  }
+  dispatchEditorKeydown(event, { cancel: cancelNames, submit: applyNames })
 }
 </script>
 

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

@@ -10,6 +10,7 @@ import { useManualDropdownPosition } from '../../../composables/Dropdown'
 import { useTrans } from '../../../composables/Lang'
 import { useValidation } from '../../../composables/Validation'
 import { day } from '../../../support/Day'
+import { dispatchEditorKeydown, focusFirstEditable } from '../../../support/Dom'
 import { type FieldData } from '../FieldData'
 import { useLensEdit } from '../composables/LensEdit'
 import { useLensInlineEdit } from '../composables/LensInlineEdit'
@@ -159,10 +160,7 @@ function start() {
   inline?.start(myKey.value)
   nextTick(() => {
     update()
-    const el = editorEl.value?.querySelector(
-      'input, textarea, [contenteditable], [tabindex]'
-    ) as HTMLElement | null
-    el?.focus()
+    focusFirstEditable(editorEl.value)
   })
 }
 
@@ -218,28 +216,7 @@ async function apply() {
 }
 
 function onEditorKeydown(event: KeyboardEvent) {
-  if (event.key === 'Escape') {
-    event.preventDefault()
-    cancel()
-    return
-  }
-  // Enter saves only from a plain text-like input. A textarea inserts a
-  // newline, and controls that handle Enter themselves (e.g. a dropdown that
-  // opens its menu on Enter) must keep it — otherwise a keyboard user submits
-  // the old value instead of choosing an option.
-  if (event.key === 'Enter' && isTextLikeInput(event.target)) {
-    event.preventDefault()
-    apply()
-  }
-}
-
-function isTextLikeInput(target: EventTarget | null): boolean {
-  const el = target as HTMLElement | null
-  if (!el || el.tagName !== 'INPUT') {
-    return false
-  }
-  const type = (el as HTMLInputElement).type
-  return ['text', 'search', 'url', 'email', 'tel', 'password', 'number'].includes(type)
+  dispatchEditorKeydown(event, { cancel, submit: apply })
 }
 </script>
 

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

@@ -273,6 +273,15 @@ export abstract class Field<T extends FieldData> {
 
   /**
    * Returns the form input component for the field.
+   *
+   * Several field types currently `throw new Error('Not implemented.')` here —
+   * they're shown read-only and have no inline/sheet editor yet. When making one
+   * editable, mind the inline editor's keyboard handling: if the input is a
+   * composite control with its own nested text input (e.g. a dropdown search
+   * filter), that nested input must keep Enter/Escape from bubbling to the
+   * editor (see `SDropdownSectionFilter` and `support/Dom`'s
+   * `dispatchEditorKeydown`), or typing a value and pressing Enter would
+   * submit/cancel the whole editor.
    */
   abstract formInputComponent(): any
 

package/lib/components/SDropdownSectionFilter.vue

@@ -70,7 +70,9 @@ function onClick(option: DropdownSectionFilterOption, value: any) {
 <template>
   <div class="SDropdownSectionFilter">
     <div v-if="search" class="search">
-      <input ref="input" v-model="query" class="input" :placeholder="t.i_ph">
+      <!-- Keep Enter inside the filter: it drives the dropdown, and must not
+           bubble to an enclosing editor/form as a submit. -->
+      <input ref="input" v-model="query" class="input" :placeholder="t.i_ph" @keydown.enter.stop>
     </div>
 
     <ul v-if="filteredOptions.length" class="list">

package/lib/components/SInputDropdownItem.vue

@@ -47,7 +47,7 @@ function emitRemove(value: any) {
       <template v-for="(el, i) in item" :key="i">
         <div v-if="el.type === undefined || el.type === 'text'" class="many-text">
           <div class="many-text-value">{{ el.label }}</div>
-          <button v-if="removable" class="many-text-close" @click.stop="emitRemove(el.value)">
+          <button v-if="removable" type="button" class="many-text-close" @click.stop="emitRemove(el.value)">
             <IconX class="many-text-close-icon" />
           </button>
         </div>
@@ -56,7 +56,7 @@ function emitRemove(value: any) {
             <div class="many-avatar-image"><SAvatar size="fill" :avatar="el.image" /></div>
             <div class="many-avatar-name">{{ el.label }}</div>
           </div>
-          <button v-if="removable" class="many-avatar-close" @click.stop="emitRemove(el.value)">
+          <button v-if="removable" type="button" class="many-avatar-close" @click.stop="emitRemove(el.value)">
             <IconX class="many-avatar-close-icon" />
           </button>
         </div>
@@ -70,7 +70,7 @@ function emitRemove(value: any) {
         <div class="one-avatar-image"><SAvatar size="fill" :avatar="item.image" /></div>
         <div class="one-avatar-name">{{ item.label }}</div>
       </div>
-      <button v-if="removable" class="one-close" @click.stop="emitRemove(item.value)">
+      <button v-if="removable" type="button" class="one-close" @click.stop="emitRemove(item.value)">
         <IconX class="one-close-icon" />
       </button>
     </div>

package/lib/components/SInputSelectSearch.vue

@@ -0,0 +1,753 @@
+<script setup lang="ts">
+import IconCaretDown from '~icons/ph/caret-down'
+import IconCaretUp from '~icons/ph/caret-up'
+import IconCheck from '~icons/ph/check'
+import { computed, nextTick, onUnmounted, ref, watch } from 'vue'
+import { useManualDropdownPosition } from '../composables/Dropdown'
+import { useFlyout } from '../composables/Flyout'
+import { useTrans } from '../composables/Lang'
+import SDropdownSectionFilterItem from './SDropdownSectionFilterItem.vue'
+import SInputBase, { type Props as BaseProps } from './SInputBase.vue'
+import SInputDropdownItem from './SInputDropdownItem.vue'
+import SSpinner from './SSpinner.vue'
+
+export type { Color, Size } from './SInputBase.vue'
+
+export type Option = OptionText | OptionAvatar
+
+export interface OptionBase {
+  type?: 'text' | 'avatar'
+  value: any
+  disabled?: boolean
+}
+
+export interface OptionText extends OptionBase {
+  type?: 'text'
+  label: string
+}
+
+export interface OptionAvatar extends OptionBase {
+  type: 'avatar'
+  label: string
+  image?: string | null
+}
+
+export interface Props extends BaseProps {
+  placeholder?: string
+  // Fetch the options matching `query` from the server. Called when the dropdown
+  // opens (with the current query, usually empty for the initial list) and again,
+  // debounced, on each keystroke. Out-of-order responses are discarded, so it does
+  // not need to guard against races itself.
+  fetch: (query: string) => Promise<Option[]>
+  // Decide whether a `fetch` rejection should propagate (be re-thrown) instead of
+  // being swallowed into an empty list — e.g. to let auth/session failures reach
+  // the app's re-auth flow. By default every rejection is swallowed.
+  rethrow?: (error: unknown) => boolean
+  // Whether multiple options can be selected. The model is then an array of the
+  // selected options; otherwise it is a single option or `null`.
+  multiple?: boolean
+  // Whether the (single) value can be cleared, or the (multiple) selection emptied.
+  nullable?: boolean
+  disabled?: boolean
+  position?: 'top' | 'bottom'
+  // Whether to keep the dropdown open after a selection. Defaults to closing in
+  // single mode and staying open in multiple mode.
+  closeOnSelect?: boolean
+  // Debounce window (ms) between a keystroke and the refetch.
+  debounce?: number
+}
+
+// `closeOnSelect` defaults to `undefined` (not Vue's usual absent-Boolean → false)
+// so the `?? !multiple` fallback in onSelect can tell "omitted" from an explicit
+// `false`, keeping the single-select-closes / multiple-stays-open default.
+const props = withDefaults(defineProps<Props>(), { closeOnSelect: undefined })
+
+// The selected option(s). A single `Option | null`, or an `Option[]` when
+// `multiple`. Typed loosely (like SInputDropdown) so a consumer can bind a ref of
+// its own richer option type without v-model variance friction.
+const model = defineModel<any>({ required: true })
+
+const { t } = useTrans({
+  en: {
+    ph: 'Search',
+    searching: 'Searching…',
+    not_found: 'No options found.'
+  },
+  ja: {
+    ph: '検索',
+    searching: '検索中…',
+    not_found: 'オプションが見つかりません。'
+  }
+})
+
+const container = ref<HTMLDivElement>()
+const input = ref<HTMLInputElement | null>(null)
+const list = ref<HTMLUListElement | null>(null)
+
+const { isOpen, open, close } = useFlyout(container)
+const { inset, update: updatePosition } = useManualDropdownPosition(
+  container,
+  () => props.position
+)
+
+const query = ref('')
+const options = ref<Option[]>([])
+const loading = ref(false)
+
+// Monotonic token so only the latest fetch may assign `options` / clear `loading`.
+// With a debounced, user-driven search several requests can overlap; an older one
+// resolving late must not clobber the newer result.
+let fetchSeq = 0
+
+const classes = computed(() => [
+  props.size ?? 'small',
+  { disabled: props.disabled }
+])
+
+const selected = computed<Option | Option[] | null>(() => {
+  if (props.multiple) {
+    return Array.isArray(model.value) ? (model.value as Option[]) : []
+  }
+  return (model.value as Option | null) ?? null
+})
+
+const hasSelected = computed(() =>
+  props.multiple ? (selected.value as Option[]).length > 0 : selected.value !== null
+)
+
+const removable = computed(() => {
+  if (props.multiple) {
+    return !!props.nullable || (selected.value as Option[]).length > 1
+  }
+  return !!props.nullable
+})
+
+async function runFetch(q: string): Promise<void> {
+  const seq = ++fetchSeq
+  loading.value = true
+  try {
+    const res = await props.fetch(q)
+    if (seq === fetchSeq) {
+      options.value = res
+    }
+  } catch (e) {
+    // A failed search yields no options (the empty state shows)…
+    if (seq === fetchSeq) {
+      options.value = []
+    }
+    // …unless the consumer wants this failure propagated (e.g. an auth/session
+    // error that must reach the app's re-auth flow rather than look like "no
+    // results"). Re-throw regardless of `seq`: the failure is real even if a
+    // newer search has since superseded this one.
+    if (props.rethrow?.(e)) {
+      throw e
+    }
+  } finally {
+    if (seq === fetchSeq) {
+      loading.value = false
+    }
+  }
+}
+
+// Debounce keystroke-driven refetches with a cancelable timer. The pending timer
+// is cancelled on close and before each immediate open-fetch, so a keystroke from
+// a previous open session can't fire (as the latest fetch) after a reopen and
+// clobber the fresh initial list.
+let debounceTimer: ReturnType<typeof setTimeout> | undefined
+
+function cancelPendingFetch(): void {
+  if (debounceTimer !== undefined) {
+    clearTimeout(debounceTimer)
+    debounceTimer = undefined
+  }
+}
+
+// Refetch as the user types, but only while open (the reset-on-close below also
+// writes `query`, and that shouldn't fire a fetch against a closed dropdown).
+watch(query, (q) => {
+  if (!isOpen.value) {
+    return
+  }
+  cancelPendingFetch()
+  // Supersede any in-flight fetch right away — not only once the timer fires. A
+  // previous query's request that resolves during the debounce window would
+  // otherwise still pass runFetch's `seq === fetchSeq` check and replace the
+  // options (and clear loading) for a query the input has already moved past.
+  // Bumping the token invalidates it; keep `loading` on so the pending search
+  // stays indicated until the new fetch resolves.
+  fetchSeq++
+  loading.value = true
+  debounceTimer = setTimeout(() => {
+    debounceTimer = undefined
+    runFetch(q)
+  }, props.debounce ?? 250)
+})
+
+function onOpen() {
+  if (props.disabled) {
+    return
+  }
+  updatePosition()
+  open()
+  // Fetch the current (initial) list immediately — dropping any keystroke timer
+  // left armed from a previous open — and focus the search input.
+  cancelPendingFetch()
+  runFetch(query.value)
+  nextTick(() => input.value?.focus())
+}
+
+watch(isOpen, (value) => {
+  // On close: drop any pending refetch, invalidate any in-flight fetch (so a late
+  // response can't repopulate the list while closed), and clear the query /
+  // options / loading. Reopening then starts fresh instead of briefly rendering
+  // the previous query's results (which would be selectable). The selected chips
+  // are unaffected — they render from the model, not from `options`.
+  if (!value) {
+    cancelPendingFetch()
+    fetchSeq++
+    query.value = ''
+    options.value = []
+    loading.value = false
+  }
+})
+
+onUnmounted(cancelPendingFetch)
+
+// Close the dropdown if the control becomes disabled while open (e.g. a form
+// submission starts), so its options can't be selected until it re-enables.
+// `onSelect` also re-checks `props.disabled` as a belt-and-braces guard.
+watch(() => props.disabled, (disabled) => {
+  if (disabled) {
+    close()
+  }
+})
+
+function isActive(value: any): boolean {
+  if (props.multiple) {
+    return (selected.value as Option[]).some((o) => o.value === value)
+  }
+  return (selected.value as Option | null)?.value === value
+}
+
+function onSelect(option: Option): void {
+  if (props.disabled || option.disabled) {
+    return
+  }
+
+  props.validation?.$touch()
+
+  if (props.multiple) {
+    const current = (model.value as Option[] | null) ?? []
+    const exists = current.some((o) => o.value === option.value)
+    const next = exists
+      ? current.filter((o) => o.value !== option.value)
+      : [...current, option]
+    // Keep at least one unless clearing is allowed (mirrors SInputDropdown).
+    if (next.length !== 0 || props.nullable) {
+      model.value = next
+    }
+  } else {
+    const currentValue = (model.value as Option | null)?.value
+    if (currentValue !== option.value) {
+      model.value = option
+    } else if (props.nullable) {
+      model.value = null
+    }
+  }
+
+  if (props.closeOnSelect ?? !props.multiple) {
+    close()
+  }
+}
+
+// Remove a selected chip from the box (the X on SInputDropdownItem).
+function onRemove(value: any): void {
+  props.validation?.$touch()
+
+  if (props.multiple) {
+    const current = (model.value as Option[] | null) ?? []
+    model.value = current.filter((o) => o.value !== value)
+  } else {
+    model.value = null
+  }
+}
+
+// Move focus from the search input into the first option (ArrowDown from the box).
+function focusFirstOption(): void {
+  list.value?.querySelector<HTMLElement>('.button:not([disabled])')?.focus()
+}
+
+// The next/previous enabled option button, skipping disabled ones (consistent
+// with focusFirstOption and the click guard).
+function enabledSibling(el: HTMLElement, forward: boolean): HTMLElement | null {
+  let li: Element | null | undefined = el.parentElement
+  for (;;) {
+    li = forward ? li?.nextElementSibling : li?.previousElementSibling
+    if (!li) {
+      return null
+    }
+    const button = li.querySelector<HTMLElement>('.button:not([disabled])')
+    if (button) {
+      return button
+    }
+  }
+}
+
+function focusPrev(event: any): void {
+  // ArrowUp from the first option returns focus to the search input.
+  const prev = enabledSibling(event.target as HTMLElement, false)
+  prev ? prev.focus() : input.value?.focus()
+}
+
+function focusNext(event: any): void {
+  enabledSibling(event.target as HTMLElement, true)?.focus()
+}
+</script>
+
+<template>
+  <SInputBase
+    class="SInputSelectSearch"
+    :class="classes"
+    :size
+    :name
+    :label
+    :note
+    :info
+    :help
+    :check-icon
+    :check-text
+    :check-color
+    :validation
+    :warning
+    :hide-error
+    :hide-warning
+  >
+    <div ref="container" class="container">
+      <div
+        class="box"
+        role="button"
+        tabindex="0"
+        @click="onOpen"
+        @keydown.down.prevent
+        @keyup.enter="onOpen"
+        @keyup.down="onOpen"
+      >
+        <div class="box-content">
+          <SInputDropdownItem
+            v-if="hasSelected"
+            :item="selected!"
+            :size="size ?? 'small'"
+            :removable
+            :disabled="disabled ?? false"
+            @remove="onRemove"
+          />
+
+          <div v-else class="box-placeholder">{{ placeholder ?? t.ph }}</div>
+        </div>
+
+        <div class="box-icon">
+          <IconCaretUp class="box-icon-svg up" />
+          <IconCaretDown class="box-icon-svg down" />
+        </div>
+      </div>
+
+      <div v-if="isOpen" class="dropdown" :style="inset">
+        <div class="dropdown-content">
+          <div class="search">
+            <!-- Keep Enter inside the search field: it drives the dropdown and
+                 must neither bubble to an enclosing form (`.stop`) nor trigger the
+                 browser's implicit form submission (`.prevent`). ArrowDown moves
+                 focus into the option list. -->
+            <input
+              ref="input"
+              v-model="query"
+              class="search-input"
+              :placeholder="t.ph"
+              @keydown.enter.stop.prevent
+              @keydown.down.prevent
+              @keyup.down.prevent="focusFirstOption"
+            >
+            <!-- A refetch while options are already shown keeps the (stale) list
+                 visible; this spinner signals that newer results are loading. -->
+            <SSpinner v-if="loading && options.length" class="search-spinner" />
+          </div>
+
+          <ul v-if="options.length" ref="list" class="list">
+            <li v-for="option in options" :key="option.value" class="item">
+              <button
+                class="button"
+                :class="{ active: isActive(option.value) }"
+                type="button"
+                :disabled="option.disabled"
+                tabindex="0"
+                @keyup.up.prevent="focusPrev"
+                @keyup.down.prevent="focusNext"
+                @click="onSelect(option)"
+              >
+                <span v-if="multiple" class="checkbox">
+                  <span class="checkbox-box">
+                    <IconCheck class="checkbox-icon" />
+                  </span>
+                </span>
+                <span v-else class="radio">
+                  <span class="radio-dot" />
+                </span>
+                <span class="option-item">
+                  <SDropdownSectionFilterItem :option />
+                </span>
+              </button>
+            </li>
+          </ul>
+
+          <div v-else-if="loading" class="state">
+            <SSpinner class="state-spinner" />
+            <span class="state-text">{{ t.searching }}</span>
+          </div>
+
+          <p v-else class="empty">{{ t.not_found }}</p>
+        </div>
+      </div>
+    </div>
+    <template v-if="$slots.info" #info><slot name="info" /></template>
+  </SInputBase>
+</template>
+
+<style scoped lang="postcss">
+.container {
+  position: relative;
+  width: 100%;
+}
+
+.box {
+  position: relative;
+  display: flex;
+  align-items: center;
+  border: 1px solid var(--input-border-color);
+  border-radius: 8px;
+  width: 100%;
+  color: var(--input-text);
+  background-color: var(--input-bg-color);
+  box-shadow: var(--input-box-shadow);
+  cursor: pointer;
+  transition: border-color 0.25s, background-color 0.25s;
+
+  &:hover {
+    border-color: var(--input-hover-border-color);
+  }
+}
+
+.box-content {
+  display: flex;
+  align-items: center;
+  flex-grow: 1;
+  max-width: 100%;
+}
+
+.box-placeholder {
+  line-height: 24px;
+  color: var(--input-placeholder-color);
+  overflow: hidden;
+  white-space: nowrap;
+}
+
+.box-icon {
+  position: absolute;
+  z-index: 10;
+  cursor: pointer;
+}
+
+.box-icon-svg {
+  display: block;
+  width: 14px;
+  height: 14px;
+  color: var(--c-text-2);
+}
+
+.box-icon-svg.up {
+  margin-bottom: -4px;
+}
+
+.dropdown {
+  position: fixed;
+  z-index: var(--z-index-dropdown);
+}
+
+.dropdown-content {
+  border: 1px solid var(--c-border-mute-1);
+  border-radius: 8px;
+  background-color: var(--c-bg-elv-3);
+  box-shadow: var(--shadow-depth-3);
+  overflow: hidden;
+}
+
+.search {
+  position: sticky;
+  top: 0;
+  z-index: 10;
+  border-bottom: 1px solid var(--c-gutter);
+  padding: 8px;
+  background-color: var(--c-bg-elv-3);
+}
+
+.search-spinner {
+  position: absolute;
+  top: 50%;
+  right: 16px;
+  width: 16px;
+  height: 16px;
+  transform: translateY(-50%);
+  color: var(--c-text-2);
+}
+
+.search-input {
+  border: 1px solid var(--c-divider);
+  border-radius: 6px;
+  padding: 0 8px;
+  width: 100%;
+  font-size: 14px;
+  font-family: var(--input-value-font-family);
+  line-height: 32px;
+  background-color: var(--input-bg-color);
+  transition: border-color 0.25s;
+
+  &::placeholder {
+    color: var(--input-placeholder-color);
+  }
+
+  &:hover { border-color: var(--input-hover-border-color); }
+  &:focus { border-color: var(--input-focus-border-color); }
+}
+
+.list {
+  max-height: 280px;
+  padding: 8px;
+  overflow-y: auto;
+}
+
+.button {
+  display: flex;
+  border-radius: 6px;
+  padding: 0 8px;
+  width: 100%;
+  text-align: left;
+  transition: color 0.25s, background-color 0.25s;
+
+  &:hover:not(:disabled) {
+    background-color: var(--c-bg-mute-1);
+  }
+
+  &:disabled {
+    cursor: not-allowed;
+    opacity: 0.5;
+  }
+}
+
+.checkbox {
+  display: block;
+  padding-top: 8px;
+  padding-bottom: 8px;
+}
+
+.checkbox-box {
+  display: flex;
+  justify-content: center;
+  align-items: center;
+  border: 1px solid var(--c-border-mute-1);
+  border-radius: 4px;
+  width: 16px;
+  height: 16px;
+  background-color: var(--input-bg-color);
+  transition: border-color 0.1s, background-color 0.1s;
+
+  .button.active & {
+    border-color: var(--c-fg-info-1);
+    background-color: var(--c-fg-info-1);
+  }
+}
+
+.checkbox-icon {
+  display: block;
+  width: 10px;
+  height: 10px;
+  color: var(--c-white);
+  opacity: 0;
+  transition: opacity 0.25s;
+
+  .button.active & {
+    opacity: 1;
+  }
+}
+
+.radio {
+  position: relative;
+  flex-shrink: 0;
+  border: 1px solid var(--c-border-mute-1);
+  border-radius: 50%;
+  margin-top: 8px;
+  margin-bottom: 8px;
+  width: 16px;
+  height: 16px;
+  background-color: var(--input-bg-color);
+  transition: border-color 0.25s;
+
+  .button.active & {
+    border-color: var(--c-border-info-1);
+  }
+}
+
+.radio-dot {
+  position: absolute;
+  top: 0;
+  right: 0;
+  bottom: 0;
+  left: 0;
+  display: flex;
+  justify-content: center;
+  align-items: center;
+  border-radius: 50%;
+  width: 100%;
+  background-color: var(--c-fg-info-1);
+  opacity: 0;
+  transform: scale(0);
+  transition: opacity 0.25s, transform 0.1s;
+
+  .button.active & {
+    opacity: 1;
+    transform: scale(0.6);
+  }
+}
+
+.option-item {
+  padding-left: 12px;
+  width: 100%;
+}
+
+.state {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 14px 16px;
+}
+
+.state-spinner {
+  width: 16px;
+  height: 16px;
+  color: var(--c-text-2);
+}
+
+.state-text {
+  font-size: 12px;
+  color: var(--c-text-2);
+}
+
+.empty {
+  padding: 14px 16px;
+  font-size: 12px;
+  color: var(--c-text-2);
+}
+
+.SInputSelectSearch.sm,
+.SInputSelectSearch.mini {
+  .box {
+    min-height: 32px;
+  }
+
+  .box-content {
+    padding: 0 30px 0 0;
+    line-height: 24px;
+    font-size: var(--input-font-size, var(--input-mini-font-size));
+  }
+
+  .box-placeholder {
+    padding-left: 10px;
+  }
+
+  .box-icon {
+    top: 3px;
+    right: 8px;
+  }
+}
+
+.SInputSelectSearch.md {
+  .box {
+    min-height: 36px;
+  }
+
+  .box-content {
+    padding: 0 30px 0 0;
+    line-height: 24px;
+    font-size: var(--input-font-size, 14px);
+  }
+
+  .box-placeholder {
+    padding-left: 10px;
+  }
+
+  .box-icon {
+    top: 5px;
+    right: 8px;
+  }
+}
+
+.SInputSelectSearch.small {
+  .box {
+    min-height: 40px;
+  }
+
+  .box-content {
+    padding: 0 30px 0 0;
+    line-height: 24px;
+    font-size: var(--input-font-size, var(--input-small-font-size));
+  }
+
+  .box-placeholder {
+    padding-left: 12px;
+  }
+
+  .box-icon {
+    top: 7px;
+    right: 8px;
+  }
+}
+
+.SInputSelectSearch.medium {
+  .box {
+    min-height: 48px;
+  }
+
+  .box-content {
+    padding: 0 40px 0 0;
+    line-height: 24px;
+    font-size: var(--input-font-size, var(--input-medium-font-size));
+  }
+
+  .box-placeholder {
+    padding-left: 16px;
+  }
+
+  .box-icon {
+    top: 11px;
+    right: 12px;
+  }
+}
+
+.SInputSelectSearch.disabled {
+  .box {
+    border-color: var(--input-disabled-border-color);
+    background-color: var(--input-disabled-bg-color);
+    cursor: not-allowed;
+
+    &:hover { border-color: var(--input-disabled-border-color); }
+  }
+
+  .box-icon {
+    cursor: not-allowed;
+  }
+}
+
+.SInputSelectSearch.has-error {
+  .box {
+    border-color: var(--input-error-border-color);
+  }
+}
+</style>

package/lib/support/Dom.ts

@@ -0,0 +1,109 @@
+/**
+ * Whether the event target is a plain text-like `<input>` — the controls where
+ * pressing Enter should submit an inline editor. Excludes textareas (Enter
+ * inserts a newline) and richer controls that handle Enter themselves (e.g. a
+ * dropdown that opens its menu on Enter), so a keyboard user isn't forced to
+ * submit instead of operating the control.
+ */
+export function isTextLikeInput(target: EventTarget | null): boolean {
+  const el = target as HTMLElement | null
+
+  if (!el || el.tagName !== 'INPUT') {
+    return false
+  }
+
+  const type = (el as HTMLInputElement).type
+
+  return ['text', 'search', 'url', 'email', 'tel', 'password', 'number'].includes(type)
+}
+
+/**
+ * Whether an Enter keydown should submit an inline editor. Ctrl/Cmd+Enter
+ * submits from any control — it's the near-universal "submit" gesture (GitHub,
+ * Gmail, Slack, …) and never clashes with a textarea's newline or a control that
+ * handles bare Enter itself (e.g. a dropdown opening its menu). Bare Enter
+ * submits only from a plain text-like input (see {@link isTextLikeInput}).
+ *
+ * Shift+Enter is left for newlines, and Alt/Option+Enter has no consistent
+ * submit meaning (Excel uses it for an in-cell newline), so neither submits.
+ * The Enter that commits an IME composition (e.g. CJK input) never submits.
+ */
+export function isEditorSubmitKeydown(event: KeyboardEvent): boolean {
+  if (event.key !== 'Enter') {
+    return false
+  }
+
+  // Ignore the Enter that commits an IME composition (e.g. CJK input): it
+  // confirms the candidate rather than submitting.
+  if (event.isComposing) {
+    return false
+  }
+
+  return event.ctrlKey || event.metaKey || isTextLikeInput(event.target)
+}
+
+/**
+ * Whether a keydown should cancel an inline editor: Escape, except the Escape
+ * that cancels an in-progress IME composition (which reverts the candidate and
+ * should leave the editor open).
+ */
+export function isEditorCancelKeydown(event: KeyboardEvent): boolean {
+  return event.key === 'Escape' && !event.isComposing
+}
+
+/**
+ * Dispatch a keydown for an inline editor (opened from a cell or sheet field):
+ * cancel on Escape, submit on Enter — using the IME- and modifier-aware rules
+ * in {@link isEditorCancelKeydown} / {@link isEditorSubmitKeydown}.
+ *
+ * `shield` is for an editor nested in a surface that itself closes on Escape
+ * (e.g. a sheet): Escape is always kept from propagating to that surface — even
+ * the Escape that only cancels an IME composition (where the edit stays open) —
+ * so the surface can't close underneath the editor.
+ *
+ * NOTE for future inline/sheet-editable fields: several field types currently
+ * throw on `formInputComponent()` (not yet editable). When making one editable,
+ * if its input is a composite control with its own nested text input (e.g. a
+ * dropdown's search filter), that nested input must keep Enter/Escape from
+ * bubbling to this handler — see `SDropdownSectionFilter` — otherwise typing a
+ * value and pressing Enter would submit/cancel the whole editor.
+ */
+export function dispatchEditorKeydown(
+  event: KeyboardEvent,
+  handlers: { cancel: () => void; submit: () => void; shield?: boolean }
+): void {
+  if (event.key === 'Escape') {
+    if (handlers.shield) {
+      event.stopPropagation()
+    }
+    if (isEditorCancelKeydown(event)) {
+      event.preventDefault()
+      handlers.cancel()
+    }
+    return
+  }
+
+  if (isEditorSubmitKeydown(event)) {
+    event.preventDefault()
+    handlers.submit()
+  }
+}
+
+/**
+ * Focus the first focusable editor control (an input, textarea, contenteditable,
+ * or any `[tabindex]`) inside the container — used to focus an inline editor when
+ * it opens.
+ *
+ * Candidates inside `skip` (default `.actions`, the editor's action row) are
+ * ignored, so focus never lands on a Cancel/Save button — those are `[tabindex]`
+ * elements too — when the field input has no focusable control of its own (e.g.
+ * a radio/checkbox group). In that case nothing is focused. Pass `skip: ''` to
+ * disable.
+ */
+export function focusFirstEditable(container: HTMLElement | null, skip = '.actions'): void {
+  const candidates = Array.from(
+    container?.querySelectorAll<HTMLElement>('input, textarea, [contenteditable], [tabindex]') ?? []
+  )
+
+  candidates.find((el) => !skip || !el.closest(skip))?.focus()
+}

package/package.json

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