@humanforest/nuxt-layer 0.1.0

package/packages/ui/src/filter/FFilterChip.vue

@@ -0,0 +1,362 @@
+<script setup lang="ts">
+// One clause, as a joined segment bar: field · operator · value · dismiss.
+//
+// UFieldGroup's `-space-x-px` overlap is what makes this read as one slab — adjacent inset rings
+// collapse to a single line, and the group pins its own outer corners to rounded-md in every context,
+// so the mobile cut's rounded-full cannot dome the ends. Segments are neutral `subtle`: a soft grey
+// resting chip that stays out of the data's way, its fills butting together at each seam.
+//
+// The chip owns no state. It emits a patch and the bar applies it through updateClause, which is
+// where the is/is-any-of promotion lives.
+import { computed, onMounted, ref, shallowRef } from 'vue';
+import { CalendarDate } from '@internationalized/date';
+import { filterTheme, type FilterSlot } from './filter.theme';
+import { OPERATOR_LABEL, operatorsFor, type FilterSchema, type Operator } from './filterSchema';
+import { isComplete, summariseClause, type Clause, type RelativeUnit } from './filterClause';
+
+const props = defineProps<{
+  clause: Clause;
+  schema: FilterSchema;
+  /** Fields the other chips already hold, so this one's field menu does not offer a duplicate. */
+  usedFields?: string[];
+  ui?: Partial<Record<FilterSlot, string>>;
+}>();
+
+const emit = defineEmits<{
+  update: [patch: Partial<Omit<Clause, 'id'>>];
+  remove: [];
+}>();
+
+const theme = computed(() => filterTheme());
+
+const field = computed(() => props.schema[props.clause.field]);
+const kind = computed(() => field.value?.kind);
+const summary = computed(() => summariseClause(props.clause, props.schema));
+
+/** A single-operator kind has nothing to choose, so the chip drops that segment entirely. */
+const operators = computed<Operator[]>(() => (field.value ? [...operatorsFor(field.value)] : []));
+const showOperator = computed(() => operators.value.length > 1);
+
+const operatorItems = computed(() =>
+  operators.value.map((operator) => ({
+    label: OPERATOR_LABEL[operator],
+    onSelect: () => emit('update', { operator }),
+  })),
+);
+
+/**
+ * The field segment swaps the field the clause filters, which is what makes it worth pressing. It
+ * offers every field except this clause's own and the ones other chips already hold — two clauses on
+ * one field would AND to nothing on an equality operator, and every other path in the bar avoids it.
+ */
+const fieldItems = computed(() =>
+  Object.entries(props.schema)
+    .filter(([key]) => key !== props.clause.field && !(props.usedFields ?? []).includes(key))
+    .map(([key, declared]) => ({
+      label: declared.label,
+      icon: declared.icon,
+      onSelect: () => emit('update', { field: key }),
+    })),
+);
+
+const enumItems = computed(() =>
+  (field.value?.values ?? []).map((v) => ({ label: v.label, value: v.value, icon: v.icon, avatar: v.avatar })),
+);
+
+/** USelectMenu speaks arrays of its own item objects; the clause stores the value keys. */
+const selected = computed({
+  get: () => enumItems.value.filter((item) => (props.clause.value as string[]).includes(item.value)),
+  set: (items: { value: string }[]) => emit('update', { value: items.map((i) => i.value) }),
+});
+
+// One computed per kind rather than one cast at the binding: `v-model="scalar as string"` is not
+// valid template syntax, so the narrowing has to happen in the getter.
+const textValue = computed({
+  get: () => (typeof props.clause.value === 'string' ? props.clause.value : ''),
+  set: (value: string) => emit('update', { value }),
+});
+
+const numberValue = computed({
+  get: () => (typeof props.clause.value === 'number' ? props.clause.value : null),
+  set: (value: number | null) => emit('update', { value }),
+});
+
+// UInputDate speaks CalendarDate and the clause holds an ISO string, so the conversion sits here —
+// the UI boundary — rather than in the pure modules, which must not take a date dependency.
+const isoToCalendar = (iso: unknown): CalendarDate | null => {
+  if (typeof iso !== 'string') return null;
+  const at = new Date(iso);
+  return Number.isNaN(at.getTime())
+    ? null
+    : new CalendarDate(at.getUTCFullYear(), at.getUTCMonth() + 1, at.getUTCDate());
+};
+
+const calendarToIso = (d: CalendarDate): string => d.toDate('UTC').toISOString();
+
+const dateValue = computed({
+  get: () => isoToCalendar(props.clause.value),
+  set: (d: CalendarDate | null) => emit('update', { value: d ? calendarToIso(d) : null }),
+});
+
+// The value segment follows the OPERATOR, not just the kind: a range wants two ends, and a relative
+// window wants a count and a unit. updateClause reshapes the stored value when the operator changes,
+// so each of these reads whichever half of the pair it owns and writes the pair back whole.
+const isRange = computed(() => props.clause.operator === 'isBetween');
+const isWindow = computed(() => props.clause.operator === 'inTheLast');
+
+const pair = computed<[unknown, unknown]>(() =>
+  Array.isArray(props.clause.value) ? [props.clause.value[0], props.clause.value[1]] : [null, null],
+);
+
+const numberAt = (index: 0 | 1) =>
+  computed({
+    get: () => (typeof pair.value[index] === 'number' ? (pair.value[index] as number) : null),
+    set: (n: number | null) => {
+      const ends = [...pair.value];
+      ends[index] = n;
+      emit('update', { value: ends as [number | null, number | null] });
+    },
+  });
+
+const numberLo = numberAt(0);
+const numberHi = numberAt(1);
+
+/**
+ * UCalendar speaks a { start, end } of CalendarDates; the clause stores a pair of ISO strings.
+ *
+ * Picking a range takes two clicks, and the half-picked state stays LOCAL: the calendar runs its own
+ * selection while the popover is open, and only a complete range reaches the clause. Feeding the
+ * half-picked value back through the model would reset the calendar's own selection between the two
+ * clicks — the range would restart on every second click and the applied filter would clear on the
+ * first. The draft is re-seeded from the clause each time the popover opens, so abandoning a pick
+ * leaves the applied range untouched.
+ */
+const dateOpen = ref(false);
+
+/** Seeds the calendar when it mounts. The `dateKey` remount re-reads it on every open. */
+const clauseRange = computed(() => {
+  const start = isoToCalendar(pair.value[0]);
+  const end = isoToCalendar(pair.value[1]);
+  return start ? { start, end: end ?? undefined } : undefined;
+});
+
+// A fresh calendar per opening: seeded from the clause, then left alone until it hands back a
+// finished selection. Binding the half-picked value back would reset the calendar's own selection
+// between the two clicks of a range, so the second click restarts the range instead of closing it.
+const dateKey = ref(0);
+const onDateOpen = (open: boolean) => {
+  dateOpen.value = open;
+  if (open) dateKey.value += 1;
+};
+
+const onRangePicked = (range: { start?: CalendarDate; end?: CalendarDate } | undefined) => {
+  if (!range?.start || !range.end) return;
+  emit('update', {
+    value: [calendarToIso(range.start), calendarToIso(range.end)] as [string | null, string | null],
+  });
+  dateOpen.value = false;
+};
+
+/** A single date is complete the moment it is picked, so the calendar closes behind it. */
+const onDatePicked = (picked: CalendarDate | undefined) => {
+  if (!picked) return;
+  emit('update', { value: calendarToIso(picked) });
+  dateOpen.value = false;
+};
+
+const RELATIVE_UNITS = [
+  { label: 'days', value: 'day' },
+  { label: 'weeks', value: 'week' },
+  { label: 'months', value: 'month' },
+];
+
+const windowValue = computed(() => {
+  const { value } = props.clause;
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+    ? (value as { n: number; unit: RelativeUnit })
+    : null;
+});
+
+const windowCount = computed({
+  get: () => (windowValue.value && windowValue.value.n > 0 ? windowValue.value.n : null),
+  set: (n: number | null) =>
+    emit('update', { value: { n: n ?? 0, unit: windowValue.value?.unit ?? 'day' } }),
+});
+
+const windowUnit = computed({
+  get: () => windowValue.value?.unit ?? 'day',
+  set: (unit: RelativeUnit) => emit('update', { value: { n: windowValue.value?.n ?? 0, unit } }),
+});
+
+/** What the date trigger reads before a date is picked. */
+const datePlaceholder = computed(() => (isRange.value ? 'Pick dates…' : 'Pick a date…'));
+
+const valueRef = ref<{ $el?: HTMLElement } | null>(null);
+
+/**
+ * Put the caret in the value segment. Called from outside when an author picks a field that is
+ * already filtered, and by the chip itself when it appears empty.
+ *
+ * The segment is either a control in its own right — a date or boolean button — or a wrapper around
+ * one, so try the root element before looking inside it.
+ */
+const openValues = () => {
+  const el = valueRef.value?.$el ?? (valueRef.value as unknown as HTMLElement | null);
+  const control = el?.matches?.('button, input') ? el : el?.querySelector<HTMLElement>('button, input');
+  control?.focus();
+};
+
+// A chip that appears EMPTY takes the caret itself.
+//
+// An empty clause is inert — the predicate skips it — so a scalar field picked from the menu filters
+// nothing until someone types a value. The chip is the only thing that knows it has appeared with
+// nothing in it, and it is the thing being focused, so it claims the caret rather than waiting to be
+// handed it. That holds however the clause was created: from a trigger in this bar, from one in a
+// different bar, or from a consumer's own code.
+//
+// Only on APPEARANCE. An existing chip emptied by clearing its input must not snatch focus back while
+// someone is deleting characters.
+// Deferred, and that is not a guess about timing. A chip picked from the field menu mounts while the
+// menu is STILL OPEN and still trapping focus, so a caret placed during mount is pulled straight back
+// inside the menu and lost when it unmounts. Claiming on the next task puts it after the menu has
+// gone. (<FFilterTrigger> stops the menu handing the caret back to itself; this is the other half.)
+onMounted(() => {
+  if (isComplete(props.clause)) return;
+  setTimeout(openValues, 0);
+});
+
+defineExpose({ openValues });
+</script>
+
+<template>
+  <UFieldGroup v-if="field" size="sm">
+    <UDropdownMenu :items="fieldItems" :disabled="!fieldItems.length" :content="{ align: 'start' }">
+      <UButton color="neutral" variant="subtle" :class="theme.field({ class: props.ui?.field })">
+        <UIcon v-if="field.icon" :name="field.icon" />
+        {{ field.label }}
+      </UButton>
+    </UDropdownMenu>
+
+    <UDropdownMenu v-if="showOperator" :items="operatorItems" :content="{ align: 'start' }">
+      <UButton color="neutral" variant="subtle" :label="OPERATOR_LABEL[props.clause.operator]" />
+    </UDropdownMenu>
+
+    <USelectMenu
+      v-if="kind === 'enum'"
+      ref="valueRef"
+      v-model="selected"
+      multiple
+      :items="enumItems"
+      color="neutral" variant="outline"
+      :content="{ align: 'start' }"
+      :class="theme.count({ class: props.ui?.count })"
+    >
+      <span v-if="summary" :class="theme.value()">{{ summary }}</span>
+      <span v-else :class="[theme.value(), theme.placeholder({ class: props.ui?.placeholder })]">Select…</span>
+    </USelectMenu>
+
+    <UInput
+      v-else-if="kind === 'text'"
+      ref="valueRef"
+      v-model="textValue"
+      color="neutral" variant="outline"
+      placeholder="Type…"
+    />
+
+    <!-- A number range is two ends, so the segment splits in two rather than asking for a pair in
+         one field. Either end alone leaves the clause inert. -->
+    <template v-else-if="kind === 'number' && isRange">
+      <UInputNumber
+        ref="valueRef"
+        v-model="numberLo"
+        color="neutral" variant="outline"
+        class="w-20"
+        :placeholder="field.unit ? `From ${field.unit}` : 'From'"
+      />
+      <UInputNumber
+        v-model="numberHi"
+        color="neutral" variant="outline"
+        class="w-20"
+        :placeholder="field.unit ? `To ${field.unit}` : 'To'"
+      />
+    </template>
+
+    <UInputNumber
+      v-else-if="kind === 'number'"
+      ref="valueRef"
+      v-model="numberValue"
+      color="neutral" variant="outline"
+      class="w-24"
+      :placeholder="field.unit ?? 'Value'"
+    />
+
+    <!-- "in the last 7 days" — the operator segment already says "in the last", so the value is the
+         count and its unit. -->
+    <template v-else-if="kind === 'date' && isWindow">
+      <UInputNumber
+        ref="valueRef"
+        v-model="windowCount"
+        :min="1"
+        color="neutral" variant="outline"
+        class="w-20"
+        placeholder="7"
+      />
+      <USelect
+        v-model="windowUnit"
+        :items="RELATIVE_UNITS"
+        value-key="value"
+        color="neutral" variant="outline"
+      />
+    </template>
+
+    <!-- A date is picked on a calendar, not typed: one popover, a range calendar or a single one. -->
+    <UPopover
+      v-else-if="kind === 'date'"
+      :open="dateOpen"
+      :content="{ align: 'start' }"
+      @update:open="onDateOpen"
+    >
+      <UButton
+        ref="valueRef"
+        color="neutral" variant="outline"
+        icon="i-lucide-calendar"
+        :label="summary || datePlaceholder"
+        :class="summary ? undefined : theme.placeholder({ class: props.ui?.placeholder })"
+      />
+      <template #content>
+        <UCalendar
+          v-if="isRange"
+          :key="`range-${dateKey}`"
+          range
+          :default-value="clauseRange"
+          :number-of-months="2"
+          class="p-2"
+          @update:model-value="onRangePicked"
+        />
+        <UCalendar
+          v-else
+          :key="`single-${dateKey}`"
+          :default-value="dateValue ?? undefined"
+          class="p-2"
+          @update:model-value="onDatePicked"
+        />
+      </template>
+    </UPopover>
+
+    <UButton
+      v-else-if="kind === 'boolean'"
+      ref="valueRef"
+      color="neutral" variant="outline"
+      :label="props.clause.value ? 'Yes' : 'No'"
+      @click="emit('update', { value: !props.clause.value })"
+    />
+
+    <UButton
+      color="neutral"
+      variant="subtle"
+      icon="i-lucide-x"
+      :aria-label="`Remove ${field.label} filter`"
+      @click="emit('remove')"
+    />
+  </UFieldGroup>
+</template>

package/packages/ui/src/filter/FFilterClauses.vue

@@ -0,0 +1,104 @@
+<script setup lang="ts">
+// The applied clauses: a wrapping row of chips, plus clear-all once there is more than one.
+//
+// Split out of <FFilterBar> so it can sit in a row of its own. The row WRAPS rather than scrolls — a
+// horizontal scroller hides applied filters, which is the worse failure — and that is exactly why it
+// cannot share a row with navigation. Given its own bar it can wrap as far as it needs to.
+//
+// Controlled: the whole contract is a Clause[] in and out, so this and <FFilterTrigger> stay in step
+// through the same v-model with nothing passed between them.
+import { computed, useTemplateRef } from 'vue';
+import FFilterChip from './FFilterChip.vue';
+import { filterTheme, type FilterSlot } from './filter.theme';
+import type { FilterSchema } from './filterSchema';
+import { removeClause, updateClause, type Clause } from './filterClause';
+
+const props = defineProps<{
+  modelValue: Clause[];
+  schema: FilterSchema;
+  /**
+   * The <FFilterTrigger> that creates these clauses, so focus can return to it when the last chip
+   * goes. Optional — without it, dismissing the last chip leaves focus on the document, which is
+   * survivable but not good. <FFilterBar> wires this for the single-row case.
+   */
+  trigger?: { focus: () => void } | null;
+  ui?: Partial<Record<FilterSlot, string>>;
+}>();
+
+const emit = defineEmits<{ 'update:modelValue': [clauses: Clause[]] }>();
+
+const theme = computed(() => filterTheme());
+
+const chips = useTemplateRef<InstanceType<typeof FFilterChip>[]>('chips');
+
+/**
+ * Put the caret in a clause's value control. The handle <FFilterTrigger> calls through when an
+ * author picks a field that is already filtered AND already filled — the only case where no chip
+ * appears, so nothing claims the caret on its own.
+ */
+const openClause = (id: string) => {
+  // Read the index inside the frame: the id may have only just been emitted, so props.modelValue
+  // (and the chip refs) reflect it only after the update flushes.
+  requestAnimationFrame(() => {
+    const index = props.modelValue.findIndex((c) => c.id === id);
+    chips.value?.[index]?.openValues();
+  });
+};
+
+const patch = (id: string, p: Partial<Omit<Clause, 'id'>>) =>
+  emit('update:modelValue', updateClause(props.modelValue, id, p, props.schema));
+
+/** What every OTHER chip is filtering, so a chip's field menu cannot land on a field twice. */
+const usedFieldsExcept = (id: string) =>
+  props.modelValue.filter((clause) => clause.id !== id).map((clause) => clause.field);
+
+/** After a dismissal, focus lands on the next chip, or back on the trigger if that was the last. */
+const drop = (id: string) => {
+  const index = props.modelValue.findIndex((c) => c.id === id);
+  const next = removeClause(props.modelValue, id);
+  emit('update:modelValue', next);
+  requestAnimationFrame(() => {
+    if (!next.length) props.trigger?.focus();
+    else chips.value?.[Math.min(index, next.length - 1)]?.openValues();
+  });
+};
+
+const count = computed(() => props.modelValue.length);
+
+defineExpose({ openClause });
+</script>
+
+<template>
+  <div role="group" aria-label="Filters" :class="theme.bar({ class: props.ui?.bar })">
+    <!-- Where <FFilterBar> puts the trigger, so the one-row case is a single flex flow: trigger and
+         chips wrap together rather than the chips wrapping inside a box of their own. Empty when the
+         trigger lives in another bar. -->
+    <slot name="trigger" />
+
+    <FFilterChip
+      v-for="clause in props.modelValue"
+      ref="chips"
+      :key="clause.id"
+      :clause="clause"
+      :schema="props.schema"
+      :used-fields="usedFieldsExcept(clause.id)"
+      :ui="props.ui"
+      @update="patch(clause.id, $event)"
+      @remove="drop(clause.id)"
+    />
+
+    <UButton
+      v-if="count > 1"
+      color="error"
+      variant="ghost"
+      size="sm"
+      label="Clear all"
+      :class="theme.clear({ class: props.ui?.clear })"
+      @click="emit('update:modelValue', [])"
+    />
+
+    <span class="sr-only" aria-live="polite">
+      {{ count ? `${count} ${count === 1 ? 'filter' : 'filters'} applied` : '' }}
+    </span>
+  </div>
+</template>

package/packages/ui/src/filter/FFilterTrigger.vue

@@ -0,0 +1,183 @@
+<script setup lang="ts">
+// The add-filter control: one dropdown of the schema's fields.
+//
+// Split out of <FFilterBar> so it can sit in a different row from the clauses it creates. The clause
+// row wraps rather than scrolls, which is why it cannot share a row with navigation; this button is
+// one control and never wraps, so it can. A console puts this in the navigation row and gives the
+// clauses a row of their own.
+//
+// Controlled, like everything else here: the whole contract is a Clause[] in and out. Two components
+// bound to the same v-model already share state, so nothing is teleported or injected between them.
+//
+// Fields are the top level; each enum field opens a submenu of its values as checkbox items
+// (multi-select, the menu stays open while toggling). A scalar field has no values to enumerate, so
+// selecting it creates the clause and hands the value to its chip.
+import { computed, ref, useId } from 'vue';
+import { filterTheme, type FilterSlot } from './filter.theme';
+import type { FilterSchema } from './filterSchema';
+import { addClause, findClauseByField, updateClause, type Clause } from './filterClause';
+
+const props = defineProps<{
+  modelValue: Clause[];
+  schema: FilterSchema;
+  /**
+   * The clause row these clauses land in.
+   *
+   * Optional, and worth understanding what it does and does not buy. A NEW scalar clause opens its
+   * value control either way — the row opens any clause that arrives incomplete, which needs no
+   * wiring. This covers the other path: picking a field whose clause already exists AND is already
+   * filled, where nothing about the clause list changes and the row has nothing to react to.
+   */
+  clauses?: { openClause: (id: string) => void } | null;
+  /**
+   * Text beside the icon. Off by default — the control reads as a funnel wherever it sits, and this
+   * one is usually sharing a navigation row where a word competes with the tabs. Pass a label on a
+   * surface where filtering is the page's whole job and the extra affordance is worth the width.
+   */
+  label?: string;
+  ui?: Partial<Record<FilterSlot, string>>;
+}>();
+
+const emit = defineEmits<{ 'update:modelValue': [clauses: Clause[]] }>();
+
+const theme = computed(() => filterTheme());
+
+const open = ref(false);
+
+// A UButton, so the ref is a component instance and focus goes through its root element.
+const triggerRef = ref<{ $el?: HTMLElement } | null>(null);
+const focus = () =>
+  triggerRef.value?.$el?.querySelector?.('button')?.focus() ?? triggerRef.value?.$el?.focus?.();
+
+// useId() may only run during setup, never inside a handler — so this takes one prefix and counts off
+// it. Ids only have to be unique within one filter's clause list.
+const idPrefix = useId();
+let seq = 0;
+const nextId = () => `${idPrefix}-${++seq}`;
+
+const fields = computed(() => Object.entries(props.schema));
+
+const clauseFor = (fieldKey: string) => findClauseByField(props.modelValue, fieldKey);
+
+const isValueSelected = (fieldKey: string, value: string) => {
+  const held = clauseFor(fieldKey)?.value;
+  return Array.isArray(held) && (held as string[]).includes(value);
+};
+
+// One dropdown item per field. Enum fields carry a submenu of checkbox items; scalar fields select
+// straight through to a new clause. `checked` reads off the clauses so the ticks reflect current state.
+const menuItems = computed(() =>
+  fields.value.map(([key, field]) => {
+    if (field.kind === 'enum') {
+      return {
+        label: field.label,
+        icon: field.icon,
+        children: (field.values ?? []).map((v) => ({
+          label: v.label,
+          icon: v.icon,
+          avatar: v.avatar,
+          type: 'checkbox' as const,
+          checked: isValueSelected(key, v.value),
+          // Keep the menu open so several values can be ticked in one visit.
+          onSelect: (event: Event) => event.preventDefault(),
+          onUpdateChecked: () => toggleValue(key, v.value),
+        })),
+      };
+    }
+    return {
+      label: field.label,
+      icon: field.icon,
+      onSelect: () => pickScalarField(key),
+    };
+  }),
+);
+
+// Set for the one close that hands the caret to a chip. See `content` below.
+let handingOver = false;
+
+/**
+ * A scalar field (text/number/date/boolean): edit the existing chip, or create one — a new one
+ * appears empty and takes the caret itself, which is why nothing here focuses anything.
+ */
+const pickScalarField = (fieldKey: string) => {
+  const existing = clauseFor(fieldKey);
+  if (existing) {
+    // Already filtered AND already filled, so no chip appears and nothing self-focuses. Only claim
+    // the hand-off when there is something on the other end to receive it: with no clause row wired
+    // up, suppressing the menu's restore would drop the caret on the floor.
+    if (props.clauses) {
+      handingOver = true;
+      props.clauses.openClause(existing.id);
+    }
+    return;
+  }
+  handingOver = true;
+  emit('update:modelValue', addClause(props.modelValue, fieldKey, props.schema, nextId()));
+};
+
+// Aligned to the trigger's leading edge, not centred on it: the menu is far wider than the icon it
+// hangs off, and a centred panel drifts left of the bar it belongs to.
+const content = {
+  align: 'start' as const,
+  // A dismissable layer returns the caret to its own trigger when it closes, and that runs AFTER the
+  // clause is created — so the empty chip is focused and then instantly unfocused, leaving an inert
+  // filter behind with the caret back on this button. Suppress the restore for that close only.
+  //
+  // Every other close keeps it: Escape, clicking away, or finishing with enum checkboxes all return
+  // the caret here, which is what a keyboard user needs when no chip has claimed it.
+  onCloseAutoFocus: (event: Event) => {
+    if (handingOver) event.preventDefault();
+    handingOver = false;
+  },
+};
+
+const toggleValue = (fieldKey: string, value: string) => {
+  const existing = clauseFor(fieldKey);
+  const id = existing?.id ?? nextId();
+  const base = existing ? props.modelValue : addClause(props.modelValue, fieldKey, props.schema, id);
+  const held = (existing?.value as string[]) ?? [];
+  const next = held.includes(value) ? held.filter((v) => v !== value) : [...held, value];
+  emit('update:modelValue', updateClause(base, id, { value: next }, props.schema));
+};
+
+const count = computed(() => props.modelValue.length);
+
+/**
+ * Carries the count, because the dot cannot.
+ *
+ * The applied clauses usually sit in plain sight beside or below this button, but not always — a
+ * clause row rendered behind a `v-if` on a narrow surface leaves the dot as the only sign anything
+ * is filtered, and a dot is invisible to a screen reader. Naming the count here means the control
+ * describes its own state wherever it is, without depending on the clause row being mounted.
+ */
+const ariaLabel = computed(() =>
+  count.value ? `Filter — ${count.value} applied` : 'Filter',
+);
+
+defineExpose({ open: () => { open.value = true; }, focus });
+</script>
+
+<template>
+  <!-- A dot rather than a number: how MANY filters are applied is already legible from the chips
+       themselves, and duplicating it here would go stale in the corner of the eye. What the chips
+       cannot say is that something is applied when they are not on screen — which is the whole job of
+       the dot, and why it appears with the FIRST clause rather than at some threshold. `inset` pulls
+       it inside the button's corner so it does not enlarge the control's box.
+       OUTSIDE the menu, not between it and the button: the menu's trigger is `asChild`, so it merges
+       its click handling and aria-expanded into whatever element it wraps — put the chip in between
+       and all of that lands on the chip's positioning span instead of the button. -->
+  <UChip :show="count > 0" color="primary" size="sm" inset>
+    <UDropdownMenu v-model:open="open" :items="menuItems" :content="content">
+      <UButton
+        ref="triggerRef"
+        color="neutral"
+        variant="subtle"
+        size="sm"
+        icon="i-lucide-filter"
+        :label="props.label"
+        :aria-label="ariaLabel"
+        :class="theme.trigger({ class: props.ui?.trigger })"
+      />
+    </UDropdownMenu>
+  </UChip>
+</template>

package/packages/ui/src/filter/filter.theme.ts

@@ -0,0 +1,27 @@
+// Presentation for FFilterBar and FFilterChip. Layout only — colour, radius, ring, halo and the
+// coarse-pointer step-up all arrive with UButton and USelectMenu, so a chip follows --ui-radius and
+// the control tokens without restating them.
+import { tv } from 'tailwind-variants';
+
+export const filterTheme = tv({
+  slots: {
+    // Wraps rather than scrolls: a horizontal scroller hides applied filters, which is the worse
+    // failure. Five clauses on a phone is a three-line bar.
+    bar: 'flex flex-wrap items-center gap-2',
+    // The chip's first segment: icon and field name.
+    field: 'inline-flex items-center gap-1.5',
+    // The enum value segment, which sizes to whatever its summary reads ("Active", "3 statuses").
+    // A floor keeps the chip still as the summary shortens and lengthens under it; a ceiling gives
+    // the summary something to truncate against, so one long label cannot wrap the segment to three
+    // lines and drag the whole chip out of shape.
+    count: 'min-w-24 max-w-40 whitespace-nowrap',
+    // A value that outgrows its segment is clipped to one line rather than wrapped.
+    value: 'min-w-0 truncate',
+    trigger: '',
+    clear: 'ms-auto',
+    // Stands in for the value summary while a clause is incomplete.
+    placeholder: 'text-dimmed',
+  },
+});
+
+export type FilterSlot = keyof typeof filterTheme.slots;