@globalbrain/sefirot 4.63.0 → 4.64.0

package/lib/blocks/lens/FieldData.ts

@@ -71,6 +71,23 @@ export interface FieldDataBase {
    * means a null blank.
    */
   emptyValue?: any
+  /**
+   * Whether the backend translates the valueless `empty` / `notEmpty`
+   * filter operators for this field. The operators are strictly opt-in:
+   * the filter UI offers them only when the backend's field definition
+   * declares support, so applications whose backends don't understand
+   * the operators see no change. Absent means unsupported.
+   *
+   * The object form also customizes the label of the pinned "empty"
+   * option in the column filter dropdown (e.g. "No assignees"); a plain
+   * `true` keeps the generic default label.
+   */
+  emptyOperators?: boolean | EmptyOperatorsDeclaration
+}
+
+export interface EmptyOperatorsDeclaration {
+  labelEn?: string
+  labelJa?: string
 }
 
 export interface AvatarFieldData extends FieldDataBase {

package/lib/blocks/lens/FilterOperator.ts

@@ -9,6 +9,8 @@ export type FilterOperator =
   | 'contains'
   | 'startsWith'
   | 'endsWith'
+  | 'empty'
+  | 'notEmpty'
 
 export const FilterOperatorLabelDict: Record<FilterOperator, string> = {
   '=': 'is',
@@ -20,5 +22,54 @@ export const FilterOperatorLabelDict: Record<FilterOperator, string> = {
   'in': 'in',
   'contains': 'contains',
   'startsWith': 'starts with',
-  'endsWith': 'ends with'
+  'endsWith': 'ends with',
+  'empty': 'is empty',
+  'notEmpty': 'is not empty'
+}
+
+/**
+ * Whether the operator forms a complete condition without a value (the
+ * condition value is always `null`). The filter UI renders no value input
+ * for such conditions.
+ */
+export function isValuelessFilterOperator(operator: string | null): boolean {
+  return operator === 'empty' || operator === 'notEmpty'
+}
+
+/**
+ * Whether the condition tuple `[field, operator, value]` no longer
+ * carries an effective filter and should be cleared. A condition clears
+ * when its value is nullish or an empty array — scalar operators (e.g. a
+ * boolean `=`) carry a single value, so `false` is a real value to keep;
+ * only `null` clears. Valueless operators are complete without a value,
+ * so they never count as cleared.
+ */
+export function isClearedFilterCondition(condition: any[]): boolean {
+  if (isValuelessFilterOperator(condition[1])) {
+    return false
+  }
+  return condition[2] == null || (Array.isArray(condition[2]) && condition[2].length === 0)
+}
+
+/**
+ * Normalizes the value of valueless operator conditions to `null` across
+ * a filters array, groups included. Filters can enter from outside the
+ * form UI — the `filters` prop or a hand-edited URL query — where a
+ * valueless condition may carry a stray value, so the catalog normalizes
+ * them before sending a search, preserving the `[field, operator, null]`
+ * wire shape.
+ */
+export function normalizeValuelessFilterConditions(filters: any[]): any[] {
+  return filters.map((f) => {
+    if (!Array.isArray(f)) {
+      return f
+    }
+    const entry = f as any[]
+    if (entry[0] === '$and' || entry[0] === '$or') {
+      return [entry[0], normalizeValuelessFilterConditions(entry[1] ?? [])]
+    }
+    return isValuelessFilterOperator(entry[1]) && entry[2] !== null
+      ? [entry[0], entry[1], null]
+      : f
+  })
 }

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

@@ -9,6 +9,7 @@ import { usePower } from '../../../composables/Power'
 import { useSnackbars } from '../../../stores/Snackbars'
 import { day } from '../../../support/Day'
 import { type FieldData } from '../FieldData'
+import { isClearedFilterCondition, normalizeValuelessFilterConditions } from '../FilterOperator'
 import { type LensQuery, type LensQuerySort } from '../LensQuery'
 import { type LensResult } from '../LensResult'
 import { useCatalogUrlQuerySync } from '../composables/CatalogUrlQuerySync'
@@ -676,13 +677,16 @@ function withoutIndexField(fields: string[]): string[] {
 }
 
 // Create lens filters option by combining query (free search) filters,
-// user selected filters, and fixed filters.
+// user selected filters, and fixed filters. Filters coming from outside
+// the form UI (the `filters` prop, a hand-edited URL query) may carry a
+// stray value on a valueless condition, so normalize those to `null`
+// before they reach the wire.
 function createInputFilters(queryFilters: any[], filters: any[]) {
-  return [
+  return normalizeValuelessFilterConditions([
     ...(props.fixedFilters ?? []),
     queryFilters,
     ...filters
-  ].filter((f) => f?.length > 0)
+  ].filter((f) => f?.length > 0))
 }
 
 // Re-run the search for the new query state, dropping any stashed
@@ -723,21 +727,14 @@ function onInlineFilterUpdated(filter: any[]) {
   emit('filters-updated', _filters.value)
 }
 
-// A filter value "clears" the filter when it's nullish or an empty
-// array. Scalar operators (e.g. a boolean `=`) carry a single value, so
-// `false` is a real value to keep — only `null` clears.
-function isEmptyFilterValue(value: any): boolean {
-  return value == null || (Array.isArray(value) && value.length === 0)
-}
-
 function applyNewFilter(filter: any[]) {
-  if (!isEmptyFilterValue(filter[2])) {
+  if (!isClearedFilterCondition(filter)) {
     _filters.value.push(filter)
   }
 }
 
 function replaceFilter(index: number, filter: any[]) {
-  if (isEmptyFilterValue(filter[2])) {
+  if (isClearedFilterCondition(filter)) {
     _filters.value.splice(index, 1)
     return
   }

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

@@ -2,7 +2,7 @@
 import { computedAsync } from '@vueuse/core'
 import { computed } from 'vue'
 import { type FieldData } from '../FieldData'
-import { type FilterOperator, FilterOperatorLabelDict } from '../FilterOperator'
+import { type FilterOperator, FilterOperatorLabelDict, isValuelessFilterOperator } from '../FilterOperator'
 import { useFieldFactory } from '../composables/FieldFactory'
 
 export interface Props {
@@ -29,7 +29,15 @@ const field = computed(() => {
   return fieldData ? fieldFactory.make(fieldData) : null
 })
 
+// A valueless condition (the `empty` / `notEmpty` operators) has no
+// value to show, so the chip hides the value segment entirely and never
+// resolves the input.
+const valueless = computed(() => isValuelessFilterOperator(props.condition.operator))
+
 const input = computed(() => {
+  if (valueless.value) {
+    return null
+  }
   return field.value?.filterInputByOperator(props.condition.operator) ?? null
 })
 
@@ -54,7 +62,7 @@ const valueText = computedAsync(async () => {
   <div class="LensCatalogStateFilterCondition">
     <div class="field">{{ fieldText }}</div>
     <div class="operator">{{ operatorText }}</div>
-    <div class="value">
+    <div v-if="!valueless" class="value">
       {{ valueText }}
     </div>
   </div>

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

@@ -11,6 +11,7 @@ import { useData } from '../../../composables/Data'
 import { useLang, useTrans } from '../../../composables/Lang'
 import { useValidation } from '../../../composables/Validation'
 import { type FieldData } from '../FieldData'
+import { isValuelessFilterOperator } from '../FilterOperator'
 import { useFieldFactory } from '../composables/FieldFactory'
 import { type FilterCondition } from './LensFormFilterCondition.vue'
 import LensFormFilterGroup, { type FilterGroup } from './LensFormFilterGroup.vue'
@@ -96,7 +97,7 @@ const fieldOptions = computed(() => {
 // }
 function lensFiltersToGroup() {
   const conditions = props.filters.length > 0
-    ? pruneMissingFields(props.filters.map(lensConditionToCondition))
+    ? pruneUneditableConditions(props.filters.map(lensConditionToCondition))
     : []
 
   return {
@@ -105,15 +106,32 @@ function lensFiltersToGroup() {
   }
 }
 
-// Drop conditions that reference a field absent from `props.fields` (for
-// example a stale saved filter pointing at a field that no longer
-// exists). Such a condition can't be rendered or edited, and would
-// otherwise pass validation with a null input and silently re-emit the
-// stale filter on Apply. Groups left empty by pruning are removed too.
-function pruneMissingFields(conditions: any[]): any[] {
+// Drop conditions the form cannot render or edit: ones referencing a
+// field absent from `props.fields` (a stale saved filter pointing at a
+// field that no longer exists), and ones whose operator the field does
+// not offer (e.g. a hand-edited URL pairing `empty` with a field that
+// doesn't declare support). Mounting such a condition would throw in its
+// input resolution, and it would otherwise pass validation with a null
+// input and silently re-emit the stale filter on Apply. Groups left
+// empty by pruning are removed too.
+function pruneUneditableConditions(conditions: any[]): any[] {
   return conditions
-    .map((c) => ('connector' in c ? { ...c, conditions: pruneMissingFields(c.conditions) } : c))
-    .filter((c) => ('connector' in c ? c.conditions.length > 0 : c.field === null || props.fields[c.field]))
+    .map((c) => ('connector' in c ? { ...c, conditions: pruneUneditableConditions(c.conditions) } : c))
+    .filter((c) => ('connector' in c ? c.conditions.length > 0 : isEditableCondition(c)))
+}
+
+function isEditableCondition(c: any): boolean {
+  if (c.field === null) {
+    return true
+  }
+  const fieldData = props.fields[c.field]
+  if (!fieldData) {
+    return false
+  }
+  if (c.operator === null) {
+    return true
+  }
+  return fieldFactory.make(fieldData).availableFilterOperators().includes(c.operator)
 }
 
 function lensConditionToCondition(filter: any[]) {
@@ -142,7 +160,10 @@ function groupToLensFilters(conditions: (FilterGroup | FilterCondition)[]): any[
     if ('connector' in c) {
       return [c.connector, groupToLensFilters(c.conditions)]
     }
-    return [c.field, c.operator, c.value]
+    // A valueless condition always emits `null`: an initially loaded
+    // condition may carry a stray value (e.g. from a hand-edited URL)
+    // that the operator-change cast never saw.
+    return [c.field, c.operator, isValuelessFilterOperator(c.operator) ? null : c.value]
   })
 }
 

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

@@ -9,7 +9,7 @@ import { useValidation } from '../../../composables/Validation'
 import { type Option } from '../../../support/InputDropdown'
 import { required } from '../../../validation/rules'
 import { type FieldData } from '../FieldData'
-import { type FilterOperator, FilterOperatorLabelDict } from '../FilterOperator'
+import { type FilterOperator, FilterOperatorLabelDict, isValuelessFilterOperator } from '../FilterOperator'
 import { useFieldFactory } from '../composables/FieldFactory'
 import { type FilterInput } from '../filter-inputs/FilterInput'
 
@@ -66,8 +66,12 @@ const operatorOptions = computed(() => {
 
 const input = ref(null) as Ref<FilterInput | null>
 
+// A valueless condition (the `empty` / `notEmpty` operators) has no
+// value control: the value cell renders nothing instead of an input.
+const valueless = computed(() => isValuelessFilterOperator(model.value.operator))
+
 const inputComponent = computed(() => {
-  return input.value ? markRaw(input.value.component()) : null
+  return input.value && !valueless.value ? markRaw(input.value.component()) : null
 })
 
 const { validation, reset: resetValidation } = useValidation(() => ({
@@ -160,7 +164,7 @@ async function resolveInput() {
     </div>
     <div class="value">
       <div v-if="input === null" class="skeleton" />
-      <Suspense v-else :key="model.field ?? '__empty__'">
+      <Suspense v-else-if="!valueless" :key="model.field ?? '__empty__'">
         <component :is="inputComponent" v-model="model.value" />
         <template #fallback>
           <div class="resolving">

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

@@ -17,6 +17,13 @@ import * as RuleMapper from '../validation/RuleMapper'
  */
 const DEFAULT_COLUMN_WIDTH = 168
 
+/**
+ * The option value of the pinned "empty" option in column filter
+ * dropdowns. A sentinel that can never collide with real option values
+ * coming from backend resources.
+ */
+export const EmptyFilterOption = Symbol('empty-filter-option')
+
 export abstract class Field<T extends FieldData> {
   /**
    * The field context, that holds global app context
@@ -163,6 +170,35 @@ export abstract class Field<T extends FieldData> {
     return null
   }
 
+  /**
+   * Whether an `empty` condition for the given key is present in the
+   * filters array.
+   */
+  protected emptyFilterActiveFor(key: string, filters: any[]): boolean {
+    return filters.some((f) => f[0] === key && f[1] === 'empty')
+  }
+
+  /**
+   * Whether the backend declares the valueless `empty` / `notEmpty`
+   * filter operators for this field. See `FieldDataBase.emptyOperators`.
+   */
+  protected emptyOperatorsEnabled(): boolean {
+    return !!this.data.emptyOperators
+  }
+
+  /**
+   * The label for the pinned "empty" option in the column filter
+   * dropdown. The backend's declaration may customize it per language
+   * (e.g. "No assignees"); the fallback is a generic localized "None".
+   */
+  protected emptyOptionLabel(): string {
+    const declaration = this.data.emptyOperators
+    const label = typeof declaration === 'object' && declaration !== null
+      ? (this.ctx.lang === 'ja' ? declaration.labelJa : declaration.labelEn)
+      : null
+    return label ?? (this.ctx.lang === 'ja' ? 'なし' : 'None')
+  }
+
   /**
    * Returns the table cell definition for the field.
    */

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

@@ -7,9 +7,10 @@ import { type TableCell } from '../../../composables/Table'
 import { type RelatedManyFieldData } from '../FieldData'
 import { type FilterOperator } from '../FilterOperator'
 import { type ResourceFetcher } from '../ResourceFetcher'
+import { EmptyFilterInput } from '../filter-inputs/EmptyFilterInput'
 import { type FilterInput } from '../filter-inputs/FilterInput'
 import { SelectFilterInput } from '../filter-inputs/SelectFilterInput'
-import { Field } from './Field'
+import { EmptyFilterOption, Field } from './Field'
 
 export class RelatedManyField extends Field<RelatedManyFieldData> {
   fetcher: ResourceFetcher
@@ -31,7 +32,11 @@ export class RelatedManyField extends Field<RelatedManyFieldData> {
       return null
     }
 
-    const selected = this.inFilterValueFor(this.data.key, filters)
+    const emptyActive = this.emptyFilterActiveFor(this.data.key, filters)
+
+    const selected = emptyActive
+      ? [EmptyFilterOption]
+      : this.inFilterValueFor(this.data.key, filters)
 
     const res = await this.fetcher(method, url, this.data.resourceEndpointBody)
     const data = key ? res[key] : res
@@ -50,12 +55,26 @@ export class RelatedManyField extends Field<RelatedManyFieldData> {
           value: this.resolveValue(item[this.data.filterKey])
         })
 
+    // The pinned "empty" option filters records with no related items at
+    // all. It is mutually exclusive with the value options: selecting it
+    // swaps the whole condition to a valueless `empty`, and selecting a
+    // value swaps back to `in`.
+    if (this.emptyOperatorsEnabled()) {
+      options.unshift({ label: this.emptyOptionLabel(), value: EmptyFilterOption })
+    }
+
     return {
       type: 'filter',
       search: true,
       selected,
       options,
-      onClick: (v) => { onFilterUpdated?.([this.data.key, 'in', xor(selected, [v])]) }
+      onClick: (v) => {
+        if (v === EmptyFilterOption) {
+          onFilterUpdated?.(emptyActive ? [this.data.key, 'in', []] : [this.data.key, 'empty', null])
+          return
+        }
+        onFilterUpdated?.([this.data.key, 'in', xor(emptyActive ? [] : selected, [v])])
+      }
     }
   }
 
@@ -105,11 +124,20 @@ export class RelatedManyField extends Field<RelatedManyFieldData> {
     const selectOne = new SelectFilterInput().options(optionsResolver)
     const selectMany = new SelectFilterInput().options(optionsResolver).multiple()
 
-    return {
+    const filters: Partial<Record<FilterOperator, FilterInput>> = {
       '=': selectOne,
       '!=': selectOne,
       'in': selectMany
     }
+
+    // The valueless operators are strictly opt-in via the backend's field
+    // definition — see `FieldDataBase.emptyOperators`.
+    if (this.data.emptyOperators) {
+      filters.empty = new EmptyFilterInput()
+      filters.notEmpty = new EmptyFilterInput()
+    }
+
+    return filters
   }
 
   // Lens id fields serialize as `{ value, display, path? }`; filters need the

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

@@ -6,9 +6,10 @@ import { type TableCell } from '../../../composables/Table'
 import { type RelatedOneFieldData } from '../FieldData'
 import { type FilterOperator } from '../FilterOperator'
 import { type ResourceFetcher } from '../ResourceFetcher'
+import { EmptyFilterInput } from '../filter-inputs/EmptyFilterInput'
 import { type FilterInput } from '../filter-inputs/FilterInput'
 import { SelectFilterInput } from '../filter-inputs/SelectFilterInput'
-import { Field } from './Field'
+import { EmptyFilterOption, Field } from './Field'
 
 export class RelatedOneField extends Field<RelatedOneFieldData> {
   fetcher: ResourceFetcher
@@ -30,7 +31,11 @@ export class RelatedOneField extends Field<RelatedOneFieldData> {
       return null
     }
 
-    const selected = this.inFilterValueFor(this.data.key, filters)
+    const emptyActive = this.emptyFilterActiveFor(this.data.key, filters)
+
+    const selected = emptyActive
+      ? [EmptyFilterOption]
+      : this.inFilterValueFor(this.data.key, filters)
 
     const res = await this.fetcher(method, url, this.data.resourceEndpointBody)
     const data = key ? res[key] : res
@@ -49,12 +54,26 @@ export class RelatedOneField extends Field<RelatedOneFieldData> {
           value: this.resolveValue(item[this.data.filterKey])
         })
 
+    // The pinned "empty" option filters records with no related record.
+    // It is mutually exclusive with the value options: selecting it swaps
+    // the whole condition to a valueless `empty`, and selecting a value
+    // swaps back to `in`.
+    if (this.emptyOperatorsEnabled()) {
+      options.unshift({ label: this.emptyOptionLabel(), value: EmptyFilterOption })
+    }
+
     return {
       type: 'filter',
       search: true,
       selected,
       options,
-      onClick: (v) => { onFilterUpdated?.([this.data.key, 'in', xor(selected, [v])]) }
+      onClick: (v) => {
+        if (v === EmptyFilterOption) {
+          onFilterUpdated?.(emptyActive ? [this.data.key, 'in', []] : [this.data.key, 'empty', null])
+          return
+        }
+        onFilterUpdated?.([this.data.key, 'in', xor(emptyActive ? [] : selected, [v])])
+      }
     }
   }
 
@@ -107,11 +126,20 @@ export class RelatedOneField extends Field<RelatedOneFieldData> {
     const selectOne = new SelectFilterInput().options(optionsResolver)
     const selectMany = new SelectFilterInput().options(optionsResolver).multiple()
 
-    return {
+    const filters: Partial<Record<FilterOperator, FilterInput>> = {
       '=': selectOne,
       '!=': selectOne,
       'in': selectMany
     }
+
+    // The valueless operators are strictly opt-in via the backend's field
+    // definition — see `FieldDataBase.emptyOperators`.
+    if (this.data.emptyOperators) {
+      filters.empty = new EmptyFilterInput()
+      filters.notEmpty = new EmptyFilterInput()
+    }
+
+    return filters
   }
 
   // Lens id fields serialize as `{ value, display, path? }`; filters need the

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

@@ -0,0 +1,26 @@
+import { type ValidationArgs } from '@vuelidate/core'
+import { FilterInput } from './FilterInput'
+
+/**
+ * The filter input for the valueless `empty` / `notEmpty` operators (see
+ * `isValuelessFilterOperator`). The condition is complete with just the
+ * field and the operator, so this input requires no value, renders no
+ * control, and always normalizes the condition value back to `null`.
+ */
+export class EmptyFilterInput extends FilterInput {
+  rules(): Record<string, ValidationArgs> {
+    return {}
+  }
+
+  castValue(_value: any): any {
+    return null
+  }
+
+  async valueToText(_value: any): Promise<string> {
+    return ''
+  }
+
+  component(): any {
+    return null
+  }
+}

package/package.json

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