@leavepulse/ui 0.74.2 → 0.75.0

package/dist/assets/{LpTable-DHvorDiU.css → LpTable-Bv-EcQs7.css}

@@ -11,17 +11,17 @@
  * fade before closing the gap and the whole list lurches at the end instead of
  * gliding.
  */
-.lp-row-enter-active[data-v-c1911001],
-.lp-row-leave-active[data-v-c1911001] {
+.lp-row-enter-active[data-v-d2bafc29],
+.lp-row-leave-active[data-v-d2bafc29] {
   transition:
     opacity var(--duration-fast) var(--ease-emphasized),
     transform var(--duration-fast) var(--ease-emphasized);
 }
-.lp-row-move[data-v-c1911001] {
+.lp-row-move[data-v-d2bafc29] {
   transition: transform var(--duration-medium) var(--ease-emphasized);
 }
-.lp-row-enter-from[data-v-c1911001],
-.lp-row-leave-to[data-v-c1911001] {
+.lp-row-enter-from[data-v-d2bafc29],
+.lp-row-leave-to[data-v-d2bafc29] {
   opacity: 0;
   transform: translateX(-0.5rem);
 }
@@ -35,7 +35,7 @@
  * drops out of the table layout entirely. Nothing sits below this row to be
  * dragged around, so simply not animating its exit costs nothing.
  */
-.lp-row-empty.lp-row-leave-active[data-v-c1911001] {
+.lp-row-empty.lp-row-leave-active[data-v-d2bafc29] {
   display: none;
 }
 
@@ -54,7 +54,7 @@
  * once anything is selected. An earlier version collapsed the column to nothing
  * and floated the hover box over the first cell, where it sat on the text.
  */
-.lp-tick[data-v-c1911001] {
+.lp-tick[data-v-d2bafc29] {
   display: flex;
   align-items: center;
   max-width: 0;
@@ -66,17 +66,17 @@
     padding var(--duration-medium) var(--ease-emphasized),
     opacity var(--duration-fast) ease;
 }
-.lp-tick-open[data-v-c1911001] {
+.lp-tick-open[data-v-d2bafc29] {
   max-width: 3.25rem;
   padding-inline: 1rem;
   opacity: 1;
 }
-.lp-tick-hidden[data-v-c1911001],
-.lp-tick-cue[data-v-c1911001] {
+.lp-tick-hidden[data-v-d2bafc29],
+.lp-tick-cue[data-v-d2bafc29] {
   opacity: 0;
 }
-tr:hover .lp-tick-cue[data-v-c1911001],
-.lp-tick-cue[data-v-c1911001]:focus-within {
+tr:hover .lp-tick-cue[data-v-d2bafc29],
+.lp-tick-cue[data-v-d2bafc29]:focus-within {
   opacity: 1;
 }
 
@@ -84,24 +84,24 @@ tr:hover .lp-tick-cue[data-v-c1911001],
    turned down the rows change without animating rather than not changing. */
 /* Only where there is a hover to reveal it; a finger long-presses instead. */
 @media (hover: none) {
-tr:hover .lp-tick-cue[data-v-c1911001] {
+tr:hover .lp-tick-cue[data-v-d2bafc29] {
     opacity: 0;
 }
 
   /* Nor is there anything for the column's width to hold until then: on a
      touch screen it stays closed until a long press starts selecting, and
      eases open like the rest of the column. */
-.lp-tick-hidden[data-v-c1911001],
-  .lp-tick-cue[data-v-c1911001] {
+.lp-tick-hidden[data-v-d2bafc29],
+  .lp-tick-cue[data-v-d2bafc29] {
     max-width: 0;
     padding-inline: 0;
 }
 }
 @media (prefers-reduced-motion: reduce) {
-.lp-row-enter-active[data-v-c1911001],
-  .lp-row-leave-active[data-v-c1911001],
-  .lp-row-move[data-v-c1911001],
-  .lp-tick[data-v-c1911001] {
+.lp-row-enter-active[data-v-d2bafc29],
+  .lp-row-leave-active[data-v-d2bafc29],
+  .lp-row-move[data-v-d2bafc29],
+  .lp-tick[data-v-d2bafc29] {
     transition: none;
 }
 }

package/dist/components/LpTable.vue.d.ts

@@ -1,4 +1,5 @@
 import { type CsvOptions } from "./exportData";
+import { type TableFilters } from "./tableFilter";
 import { type TableRowMenuResult } from "./tableRowMenu";
 export interface TableColumn<Row> {
     key: string;
@@ -29,6 +30,21 @@ export interface TableColumn<Row> {
      * vocabulary; the menu should say what the column itself says.
      */
     valueLabel?: (value: unknown) => string;
+    /**
+     * The column's whole vocabulary, when it is known apart from the rows. The
+     * funnel lists these first and then anything else the rows hold, so a value
+     * is offered even while nothing on the page has it: the rows may already be
+     * narrowed by the same column upstream (a control above the table, a server
+     * query), and a funnel built only from what arrived could not widen it again.
+     */
+    filterValues?: readonly unknown[];
+    /**
+     * Show how many rows hold each value in the funnel (the default). Turn off
+     * when the rows are already narrowed by this column before they reach the
+     * table: the counts would then claim that the values filtered out upstream
+     * hold no rows at all.
+     */
+    filterCounts?: boolean;
     /** The value a CSV export writes for this column; the raw cell by default. */
     exportValue?: (row: Row) => unknown;
     /** Keep this column out of the show/hide list — an actions column has no
@@ -171,6 +187,23 @@ declare const __VLS_export: <T extends Record<string, unknown>>(__VLS_props: Non
         /** Active sort (v-model:sort). When set, the parent owns ordering (server
          *  side); otherwise the table sorts its own rows client-side. */
         sort?: SortState | null;
+        /**
+         * The header filters (v-model:filters): per column key, the values hidden.
+         * When set, the parent owns them, so a control above the table that
+         * filters the same column (see `useTableFilterChoice`) and the column's
+         * funnel are one state: each shows what the other picked, and the table's
+         * resets clear both. Left unset, the table keeps them itself. With
+         * `persist`, remembered filters fill only the columns the parent leaves
+         * unfiltered, and arrive through `update:filters`.
+         */
+        filters?: TableFilters;
+        /**
+         * The rows are narrowed by filters outside the table (a search, a period).
+         * An empty table then says nothing matches rather than that there is
+         * nothing at all, and its reset button also emits `resetFilters`, for the
+         * parent to clear its own.
+         */
+        filtered?: boolean;
         /** Pin the header while the body scrolls. Pair with a height on the wrapper. */
         stickyHeader?: boolean;
         /** Per-row right-click menu. Return [] (or omit the prop) to disable it for
@@ -213,7 +246,9 @@ declare const __VLS_export: <T extends Record<string, unknown>>(__VLS_props: Non
         allMatching?: boolean;
     } & {
         "onUpdate:selected"?: ((value: (string | number)[]) => any) | undefined;
+        onResetFilters?: (() => any) | undefined;
         "onUpdate:sort"?: ((value: SortState | null) => any) | undefined;
+        "onUpdate:filters"?: ((value: TableFilters) => any) | undefined;
         "onUpdate:allMatching"?: ((value: boolean) => any) | undefined;
         onRowClick?: ((row: T) => any) | undefined;
     }> & (typeof globalThis extends {
@@ -240,6 +275,8 @@ declare const __VLS_export: <T extends Record<string, unknown>>(__VLS_props: Non
     emit: {
         (e: "update:selected", value: (string | number)[]): void;
         (e: "update:sort", value: SortState | null): void;
+        (e: "update:filters", value: TableFilters): void;
+        (e: "resetFilters"): void;
         (e: "update:allMatching", value: boolean): void;
         (e: "rowClick", row: T): void;
     };

package/dist/components/LpTable.vue.js

@@ -25,10 +25,10 @@ import { useResizeObserver } from "../composables/useResizeObserver.js";
 import { compareValues } from "./tableSort.js";
 import { _ as _sfc_main$2 } from "../chunks/LpButton-CFb44IjC.js";
 import { toCsv, downloadFile, fileStem } from "./exportData.js";
-import { summarizeShown, parseTableState, serializeTableState } from "./tableFilter.js";
+import { toHiddenSets, sameHidden, summarizeShown, parseTableState, mergeRestored, serializeTableState, fromHiddenSets } from "./tableFilter.js";
 import { resolveRowMenu } from "./tableRowMenu.js";
 import { _ as _export_sfc } from "../chunks/_plugin-vue_export-helper-1tPrXgE0.js";
-import '../assets/LpTable-DHvorDiU.css';const _hoisted_1 = {
+import '../assets/LpTable-Bv-EcQs7.css';const _hoisted_1 = {
   key: 0,
   class: "flex justify-end"
 };
@@ -89,6 +89,8 @@ const _sfc_main = /* @__PURE__ */ defineComponent({
     selectable: { type: [Boolean, String], default: false },
     selected: { default: () => [] },
     sort: { default: void 0 },
+    filters: { default: void 0 },
+    filtered: { type: Boolean, default: false },
     stickyHeader: { type: Boolean },
     rowMenu: {},
     sortAscLabel: {},
@@ -105,7 +107,7 @@ const _sfc_main = /* @__PURE__ */ defineComponent({
     persist: {},
     allMatching: { type: Boolean, default: false }
   },
-  emits: ["update:selected", "update:sort", "update:allMatching", "rowClick"],
+  emits: ["update:selected", "update:sort", "update:filters", "resetFilters", "update:allMatching", "rowClick"],
   setup(__props, { expose: __expose, emit: __emit }) {
     const props = __props;
     const labelSet = useLabels(
@@ -221,7 +223,19 @@ const _sfc_main = /* @__PURE__ */ defineComponent({
       const height = frameEl.value?.querySelector("table")?.offsetHeight ?? 0;
       if (height > floor.value) floor.value = height;
     }
-    const hiddenValues = ref({});
+    const ownHidden = ref({});
+    let lastHidden = {};
+    const hiddenValues = computed(() => {
+      const next = props.filters !== void 0 ? toHiddenSets(props.filters) : ownHidden.value;
+      if (sameHidden(next, lastHidden)) return lastHidden;
+      lastHidden = next;
+      return next;
+    });
+    function writeHidden(next) {
+      if (sameHidden(next, hiddenValues.value)) return;
+      ownHidden.value = next;
+      emit("update:filters", fromHiddenSets(next));
+    }
     const animating = ref(false);
     let motionTimer;
     function withMotion(change) {
@@ -252,21 +266,23 @@ const _sfc_main = /* @__PURE__ */ defineComponent({
       hidden: () => hiddenValues.value
     });
     function valuesOf(col) {
-      if (props.load) return facets.value[col.key] ?? [...new Set(sourceRows.value.map((row) => row[col.key]))];
-      return localFacets.distinct(col.key);
+      const found = props.load ? facets.value[col.key] ?? [...new Set(sourceRows.value.map((row) => row[col.key]))] : localFacets.distinct(col.key);
+      return col.filterValues ? [.../* @__PURE__ */ new Set([...col.filterValues, ...found])] : found;
     }
     function showAllValues(key) {
-      withMotion(() => hiddenValues.value = { ...hiddenValues.value, [key]: /* @__PURE__ */ new Set() });
+      writeHidden({ ...hiddenValues.value, [key]: /* @__PURE__ */ new Set() });
     }
     function setHidden(key, next) {
-      withMotion(() => hiddenValues.value = { ...hiddenValues.value, [key]: next });
+      writeHidden({ ...hiddenValues.value, [key]: next });
     }
+    watch(hiddenValues, () => withMotion(() => {
+    }));
     function labelOf(col, value) {
       return col.valueLabel?.(value) ?? String(value ?? "—");
     }
     const facetOptions = computed(() => new Map(props.columns.filter((col) => col.filterable).map((col) => {
       return [col.key, computed(() => {
-        const counts = props.load ? void 0 : localFacets.counts(col.key);
+        const counts = props.load || col.filterCounts === false ? void 0 : localFacets.counts(col.key);
         return valuesOf(col).map((value) => ({
           value,
           label: labelOf(col, value),
@@ -282,7 +298,11 @@ const _sfc_main = /* @__PURE__ */ defineComponent({
       })
     );
     function clearAllFilters() {
-      withMotion(() => hiddenValues.value = {});
+      writeHidden({});
+    }
+    function resetFilters() {
+      clearAllFilters();
+      emit("resetFilters");
     }
     function filterLabels() {
       const t = text.value;
@@ -459,9 +479,7 @@ const _sfc_main = /* @__PURE__ */ defineComponent({
             ownSort.value = state.sort;
             emit("update:sort", state.sort);
           }
-          if (state.hidden) {
-            hiddenValues.value = Object.fromEntries(Object.entries(state.hidden).map(([k, v]) => [k, new Set(v)]));
-          }
+          if (state.hidden) writeHidden(mergeRestored(hiddenValues.value, state.hidden));
           if (state.columns) hiddenColumns.value = new Set(state.columns);
         }
       }
@@ -583,6 +601,7 @@ const _sfc_main = /* @__PURE__ */ defineComponent({
     );
     const filteredOut = computed(() => {
       if (busy.value || failed.value || displayRows.value.length) return false;
+      if (props.filtered) return true;
       if (props.load) return Object.values(hiddenValues.value).some((set) => set.size);
       return props.rows.length > 0;
     });
@@ -946,7 +965,7 @@ const _sfc_main = /* @__PURE__ */ defineComponent({
                                 key: 0,
                                 variant: "outline",
                                 size: "sm",
-                                onClick: clearAllFilters
+                                onClick: resetFilters
                               }, {
                                 default: withCtx(() => [
                                   createTextVNode(toDisplayString(text.value.resetFilters), 1)
@@ -1024,7 +1043,7 @@ const _sfc_main = /* @__PURE__ */ defineComponent({
     };
   }
 });
-const LpTable = /* @__PURE__ */ _export_sfc(_sfc_main, [["__scopeId", "data-v-c1911001"]]);
+const LpTable = /* @__PURE__ */ _export_sfc(_sfc_main, [["__scopeId", "data-v-d2bafc29"]]);
 export {
   LpTable as default
 };

package/dist/components/tableFilter.d.ts

@@ -6,6 +6,34 @@ export declare function hideAllValues(values: readonly unknown[]): Set<unknown>;
 export declare function invertHidden(values: readonly unknown[], hidden: ReadonlySet<unknown>): Set<unknown>;
 /** Show these values again, leaving the rest of the filter as it was. */
 export declare function unhideValues(hidden: ReadonlySet<unknown>, values: readonly unknown[]): Set<unknown>;
+/**
+ * A table's header filters as a consumer holds them (v-model:filters on
+ * LpTable): per column key, the values hidden. A column that is absent or has
+ * an empty list is not filtered. Hidden rather than shown for the same reason
+ * as inside the table: a value nobody has seen before shows up.
+ */
+export type TableFilters = Record<string, unknown[]>;
+/** The hidden list that leaves only `keep` of `values` showing. */
+export declare function showOnly(values: readonly unknown[], keep: readonly unknown[]): unknown[];
+/** Which of `values` a column's filter still shows. */
+export declare function shownValues(values: readonly unknown[], hidden: readonly unknown[] | undefined): unknown[];
+/**
+ * The rows a set of header filters leaves, for the same data drawn somewhere
+ * the table is not (cards on a phone, a CSV built by the page).
+ */
+export declare function filterRows<Row extends Record<string, unknown>>(rows: readonly Row[], filters: TableFilters): Row[];
+/** Sets per column, from the plain lists a consumer writes. */
+export declare function toHiddenSets(filters: TableFilters): Record<string, Set<unknown>>;
+/** The plain lists a consumer reads, empty columns left out. */
+export declare function fromHiddenSets(hidden: Record<string, ReadonlySet<unknown>>): TableFilters;
+/** Whether two filter states hide the same values, empty columns counting as absent. */
+export declare function sameHidden(a: Record<string, ReadonlySet<unknown>>, b: Record<string, ReadonlySet<unknown>>): boolean;
+/**
+ * Persisted filters meeting the ones a parent already set: the parent's
+ * explicit state (a deep link, a control above the table) wins per column,
+ * and what was remembered fills only the columns it leaves alone.
+ */
+export declare function mergeRestored(current: Record<string, ReadonlySet<unknown>>, restored: Record<string, unknown[]>): Record<string, Set<unknown>>;
 /** Lower-cased and stripped of accents, so "cafe" finds "Café". */
 export declare function foldText(text: string): string;
 /** Every word of the query appears somewhere in the label, in any order. */

package/dist/components/tableFilter.js

@@ -13,6 +13,42 @@ function unhideValues(hidden, values) {
   for (const v of values) next.delete(v);
   return next;
 }
+function showOnly(values, keep) {
+  return [...onlyValues(values, keep)];
+}
+function shownValues(values, hidden) {
+  if (!hidden?.length) return [...values];
+  const out = new Set(hidden);
+  return values.filter((v) => !out.has(v));
+}
+function filterRows(rows, filters) {
+  const active = Object.entries(filters).filter(([, hidden]) => hidden.length).map(([key, hidden]) => [key, new Set(hidden)]);
+  if (!active.length) return [...rows];
+  return rows.filter((row) => active.every(([key, hidden]) => !hidden.has(row[key])));
+}
+function toHiddenSets(filters) {
+  return Object.fromEntries(Object.entries(filters).map(([key, values]) => [key, new Set(values)]));
+}
+function fromHiddenSets(hidden) {
+  return Object.fromEntries(Object.entries(hidden).filter(([, set]) => set.size).map(([key, set]) => [key, [...set]]));
+}
+function sameHidden(a, b) {
+  const keys = /* @__PURE__ */ new Set([...Object.keys(a), ...Object.keys(b)]);
+  for (const key of keys) {
+    const x = a[key];
+    const y = b[key];
+    if ((x?.size ?? 0) !== (y?.size ?? 0)) return false;
+    if (x && y) {
+      for (const v of x) if (!y.has(v)) return false;
+    }
+  }
+  return true;
+}
+function mergeRestored(current, restored) {
+  const out = Object.fromEntries(Object.entries(current).map(([k, v]) => [k, new Set(v)]));
+  for (const [key, values] of Object.entries(restored)) if (!out[key]?.size) out[key] = new Set(values);
+  return out;
+}
 function foldText(text) {
   return text.normalize("NFKD").replace(new RegExp("\\p{M}", "gu"), "").toLocaleLowerCase();
 }
@@ -72,13 +108,20 @@ function parseTableState(raw, columnKeys) {
 }
 export {
   countValues,
+  filterRows,
   foldText,
+  fromHiddenSets,
   hideAllValues,
   invertHidden,
   matchesQuery,
+  mergeRestored,
   onlyValues,
   parseTableState,
+  sameHidden,
   serializeTableState,
+  showOnly,
+  shownValues,
   summarizeShown,
+  toHiddenSets,
   unhideValues
 };

package/dist/composables/useTableFilterChoice.d.ts

@@ -0,0 +1,16 @@
+import { type MaybeRefOrGetter, type Ref, type WritableComputedRef } from "vue";
+import { type TableFilters } from "../components/tableFilter";
+/**
+ * One column of LpTable's header filters as a single choice, for a control
+ * above the table (LpSegmented, LpSelect, a row of stat tiles) that filters
+ * the same thing as the column's funnel. Both then read and write one state:
+ * picking a choice sets the funnel, and narrowing the funnel to a choice's
+ * values lights that choice up.
+ *
+ * `choices` maps each choice to the values it shows; `null` is the choice
+ * that shows everything. `values` is the column's vocabulary, by default every
+ * value the choices name. The ref reads `undefined` while the funnel holds a
+ * mix no choice describes, so the control shows nothing picked rather than a
+ * choice that is not what the table shows.
+ */
+export declare function useTableFilterChoice<C extends string>(filters: Ref<TableFilters>, column: string, choices: Record<C, readonly unknown[] | null>, values?: MaybeRefOrGetter<readonly unknown[]>): WritableComputedRef<C | undefined>;

package/dist/composables/useTableFilterChoice.js

@@ -0,0 +1,34 @@
+import { computed, toValue } from "vue";
+import { showOnly, shownValues } from "../components/tableFilter.js";
+function useTableFilterChoice(filters, column, choices, values) {
+  const entries = Object.entries(choices);
+  const vocabulary = computed(() => {
+    const own = values === void 0 ? void 0 : toValue(values);
+    return own ?? [...new Set(entries.flatMap(([, shown]) => shown ?? []))];
+  });
+  return computed({
+    get: () => {
+      const all = vocabulary.value;
+      const shown = new Set(shownValues(all, filters.value[column]));
+      for (const [choice, keep] of entries) {
+        if (keep === null) {
+          if (shown.size === all.length) return choice;
+          continue;
+        }
+        if (keep.length === shown.size && keep.every((v) => shown.has(v))) return choice;
+      }
+      return void 0;
+    },
+    set: (choice) => {
+      const keep = choice === void 0 ? null : choices[choice];
+      const hidden = keep === null ? [] : showOnly(vocabulary.value, keep);
+      const next = { ...filters.value };
+      delete next[column];
+      if (hidden.length) next[column] = hidden;
+      filters.value = next;
+    }
+  });
+}
+export {
+  useTableFilterChoice
+};

package/dist/index.d.ts

@@ -155,6 +155,9 @@ export type { SortState, TableColumn, TablePage, TableQuery } from "./components
 export type { TableLabels } from "./components/LpTable.vue";
 export type { TableExportOptions } from "./components/LpTable.vue";
 export { compareValues } from "./components/tableSort";
+export { filterRows, showOnly, shownValues } from "./components/tableFilter";
+export type { TableFilters } from "./components/tableFilter";
+export { useTableFilterChoice } from "./composables/useTableFilterChoice";
 export { resolveRowMenu } from "./components/tableRowMenu";
 export type { TableRowMenu, TableRowMenuResult } from "./components/tableRowMenu";
 export { default as LpTableOfContents } from "./components/LpTableOfContents.vue";

package/dist/index.js

@@ -99,6 +99,8 @@ import { _ as _71 } from "./chunks/LpStepper-DpsocBNJ.js";
 import { _ as _72 } from "./chunks/LpSwitch-BnXd1llc.js";
 import { default as default12 } from "./components/LpTable.vue.js";
 import { compareValues } from "./components/tableSort.js";
+import { filterRows, showOnly, shownValues } from "./components/tableFilter.js";
+import { useTableFilterChoice } from "./composables/useTableFilterChoice.js";
 import { resolveRowMenu } from "./components/tableRowMenu.js";
 import { _ as _73 } from "./chunks/LpTableOfContents-BN5zvpnx.js";
 import { default as default13 } from "./components/LpTabs.vue.js";
@@ -469,6 +471,7 @@ export {
   fileNameOf,
   fileStem,
   filterCountries,
+  filterRows,
   findHotkeyConflicts,
   fitChips,
   flagEmoji,
@@ -609,6 +612,8 @@ export {
   setActiveTab,
   s as setGlassBackdrop,
   settledCells,
+  showOnly,
+  shownValues,
   sortNodes,
   splitTags,
   splitTime,
@@ -680,6 +685,7 @@ export {
   useSettled,
   useShift,
   useSpotlight,
+  useTableFilterChoice,
   u as useTheme,
   u2 as useThemeStudio,
   useTilt,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@leavepulse/ui",
-  "version": "0.74.2",
+  "version": "0.75.0",
   "type": "module",
   "description": "LeavePulse token-driven Vue component kit.",
   "repository": {

package/src/components/LpTable.vue

@@ -32,7 +32,16 @@ import { useResizeObserver } from "../composables/useResizeObserver"
 import { compareValues } from "./tableSort"
 import LpButton from "./LpButton.vue"
 import { downloadFile, fileStem, toCsv, type CsvOptions } from "./exportData"
-import { parseTableState, serializeTableState, summarizeShown } from "./tableFilter"
+import {
+  fromHiddenSets,
+  mergeRestored,
+  parseTableState,
+  sameHidden,
+  serializeTableState,
+  summarizeShown,
+  toHiddenSets,
+  type TableFilters,
+} from "./tableFilter"
 import { resolveRowMenu, type TableRowMenuResult } from "./tableRowMenu"
 
 export interface TableColumn<Row> {
@@ -64,6 +73,21 @@ export interface TableColumn<Row> {
    * vocabulary; the menu should say what the column itself says.
    */
   valueLabel?: (value: unknown) => string
+  /**
+   * The column's whole vocabulary, when it is known apart from the rows. The
+   * funnel lists these first and then anything else the rows hold, so a value
+   * is offered even while nothing on the page has it: the rows may already be
+   * narrowed by the same column upstream (a control above the table, a server
+   * query), and a funnel built only from what arrived could not widen it again.
+   */
+  filterValues?: readonly unknown[]
+  /**
+   * Show how many rows hold each value in the funnel (the default). Turn off
+   * when the rows are already narrowed by this column before they reach the
+   * table: the counts would then claim that the values filtered out upstream
+   * hold no rows at all.
+   */
+  filterCounts?: boolean
   /** The value a CSV export writes for this column; the raw cell by default. */
   exportValue?: (row: Row) => unknown
   /** Keep this column out of the show/hide list — an actions column has no
@@ -209,6 +233,23 @@ const props = withDefaults(
     /** Active sort (v-model:sort). When set, the parent owns ordering (server
      *  side); otherwise the table sorts its own rows client-side. */
     sort?: SortState | null
+    /**
+     * The header filters (v-model:filters): per column key, the values hidden.
+     * When set, the parent owns them, so a control above the table that
+     * filters the same column (see `useTableFilterChoice`) and the column's
+     * funnel are one state: each shows what the other picked, and the table's
+     * resets clear both. Left unset, the table keeps them itself. With
+     * `persist`, remembered filters fill only the columns the parent leaves
+     * unfiltered, and arrive through `update:filters`.
+     */
+    filters?: TableFilters
+    /**
+     * The rows are narrowed by filters outside the table (a search, a period).
+     * An empty table then says nothing matches rather than that there is
+     * nothing at all, and its reset button also emits `resetFilters`, for the
+     * parent to clear its own.
+     */
+    filtered?: boolean
     /** Pin the header while the body scrolls. Pair with a height on the wrapper. */
     stickyHeader?: boolean
     /** Per-row right-click menu. Return [] (or omit the prop) to disable it for
@@ -264,6 +305,8 @@ const props = withDefaults(
     // undefined, not null: null is a parent saying "unsorted", undefined is no
     // parent at all, and only the latter lets the table keep its own sort.
     sort: undefined,
+    filters: undefined,
+    filtered: false,
   },
 )
 
@@ -337,6 +380,9 @@ const scrollAttrs = computed(() => {
 const emit = defineEmits<{
   (e: "update:selected", value: RowKey[]): void
   (e: "update:sort", value: SortState | null): void
+  (e: "update:filters", value: TableFilters): void
+  /** The empty table's reset was pressed: clear the filters kept outside it. */
+  (e: "resetFilters"): void
   (e: "update:allMatching", value: boolean): void
   (e: "rowClick", row: T): void
 }>()
@@ -474,7 +520,25 @@ async function holdHeight() {
  * being invisible until someone notices the list has an unticked entry they
  * never saw.
  */
-const hiddenValues = ref<Record<string, Set<unknown>>>({})
+const ownHidden = ref<Record<string, Set<unknown>>>({})
+let lastHidden: Record<string, Set<unknown>> = {}
+/*
+ * The parent's lists become sets once per real change: a parent handing back
+ * an equal state as a new object (its v-model echo, a computed that rebuilt)
+ * must not refetch a server page or replay the rows' motion.
+ */
+const hiddenValues = computed<Record<string, Set<unknown>>>(() => {
+  const next = props.filters !== undefined ? toHiddenSets(props.filters) : ownHidden.value
+  if (sameHidden(next, lastHidden)) return lastHidden
+  lastHidden = next
+  return next
+})
+
+function writeHidden(next: Record<string, Set<unknown>>) {
+  if (sameHidden(next, hiddenValues.value)) return
+  ownHidden.value = next
+  emit("update:filters", fromHiddenSets(next))
+}
 
 /*
  * Rows animate only when the table itself reshuffles them — a header filter or
@@ -520,33 +584,28 @@ const localFacets = useTableFacets({
 })
 
 function valuesOf(col: TableColumn<T>): unknown[] {
-  if (props.load) return facets.value[col.key] ?? [...new Set(sourceRows.value.map((row) => row[col.key]))]
-  return localFacets.distinct(col.key)
+  const found = props.load
+    ? facets.value[col.key] ?? [...new Set(sourceRows.value.map((row) => row[col.key]))]
+    : localFacets.distinct(col.key)
+  return col.filterValues ? [...new Set([...col.filterValues, ...found])] : found
 }
 
 function isValueHidden(key: string, value: unknown): boolean {
   return hiddenValues.value[key]?.has(value) ?? false
 }
 
-function toggleValue(key: string, value: unknown) {
-  withMotion(() => applyToggle(key, value))
-}
-
-function applyToggle(key: string, value: unknown) {
-  const next = new Set(hiddenValues.value[key] ?? [])
-  if (next.has(value)) next.delete(value)
-  else next.add(value)
-  hiddenValues.value = { ...hiddenValues.value, [key]: next }
-}
-
 function showAllValues(key: string) {
-  withMotion(() => (hiddenValues.value = { ...hiddenValues.value, [key]: new Set() }))
+  writeHidden({ ...hiddenValues.value, [key]: new Set() })
 }
 
 function setHidden(key: string, next: Set<unknown>) {
-  withMotion(() => (hiddenValues.value = { ...hiddenValues.value, [key]: next }))
+  writeHidden({ ...hiddenValues.value, [key]: next })
 }
 
+// Whoever changed the filters, the funnel or a control of the parent's, the
+// rows they hide and reveal move the same way.
+watch(hiddenValues, () => withMotion(() => {}))
+
 function labelOf(col: TableColumn<T>, value: unknown): string {
   return col.valueLabel?.(value) ?? String(value ?? "—")
 }
@@ -558,7 +617,7 @@ function labelOf(col: TableColumn<T>, value: unknown): string {
  */
 const facetOptions = computed(() => new Map(props.columns.filter((col) => col.filterable).map((col) => {
   return [col.key, computed(() => {
-    const counts = props.load ? undefined : localFacets.counts(col.key)
+    const counts = props.load || col.filterCounts === false ? undefined : localFacets.counts(col.key)
     return valuesOf(col).map((value) => ({
       value,
       label: labelOf(col, value),
@@ -579,7 +638,12 @@ const activeFilters = computed(() =>
 )
 
 function clearAllFilters() {
-  withMotion(() => (hiddenValues.value = {}))
+  writeHidden({})
+}
+
+function resetFilters() {
+  clearAllFilters()
+  emit("resetFilters")
 }
 
 function filterLabels() {
@@ -816,9 +880,7 @@ onMounted(() => {
         ownSort.value = state.sort
         emit("update:sort", state.sort)
       }
-      if (state.hidden) {
-        hiddenValues.value = Object.fromEntries(Object.entries(state.hidden).map(([k, v]) => [k, new Set(v)]))
-      }
+      if (state.hidden) writeHidden(mergeRestored(hiddenValues.value, state.hidden))
       if (state.columns) hiddenColumns.value = new Set(state.columns)
     }
   }
@@ -991,6 +1053,7 @@ const showBar = computed(
 )
 const filteredOut = computed(() => {
   if (busy.value || failed.value || displayRows.value.length) return false
+  if (props.filtered) return true
   if (props.load) return Object.values(hiddenValues.value).some((set) => set.size)
   return props.rows.length > 0
 })
@@ -1364,7 +1427,7 @@ usePaletteCommands(() => {
               :icon="failed ? 'lucide:circle-alert' : filteredOut ? 'lucide:filter-x' : emptyIcon"
               :title="failed ? text.error : filteredOut ? text.noMatches : text.empty"
             >
-              <LpButton v-if="filteredOut" variant="outline" size="sm" @click="clearAllFilters">
+              <LpButton v-if="filteredOut" variant="outline" size="sm" @click="resetFilters">
                 {{ text.resetFilters }}
               </LpButton>
             </LpEmptyState>

package/src/components/tableFilter.ts

@@ -27,6 +27,72 @@ export function unhideValues(hidden: ReadonlySet<unknown>, values: readonly unkn
   return next
 }
 
+/**
+ * A table's header filters as a consumer holds them (v-model:filters on
+ * LpTable): per column key, the values hidden. A column that is absent or has
+ * an empty list is not filtered. Hidden rather than shown for the same reason
+ * as inside the table: a value nobody has seen before shows up.
+ */
+export type TableFilters = Record<string, unknown[]>
+
+/** The hidden list that leaves only `keep` of `values` showing. */
+export function showOnly(values: readonly unknown[], keep: readonly unknown[]): unknown[] {
+  return [...onlyValues(values, keep)]
+}
+
+/** Which of `values` a column's filter still shows. */
+export function shownValues(values: readonly unknown[], hidden: readonly unknown[] | undefined): unknown[] {
+  if (!hidden?.length) return [...values]
+  const out = new Set(hidden)
+  return values.filter((v) => !out.has(v))
+}
+
+/**
+ * The rows a set of header filters leaves, for the same data drawn somewhere
+ * the table is not (cards on a phone, a CSV built by the page).
+ */
+export function filterRows<Row extends Record<string, unknown>>(rows: readonly Row[], filters: TableFilters): Row[] {
+  const active = Object.entries(filters).filter(([, hidden]) => hidden.length).map(([key, hidden]) => [key, new Set(hidden)] as const)
+  if (!active.length) return [...rows]
+  return rows.filter((row) => active.every(([key, hidden]) => !hidden.has(row[key])))
+}
+
+/** Sets per column, from the plain lists a consumer writes. */
+export function toHiddenSets(filters: TableFilters): Record<string, Set<unknown>> {
+  return Object.fromEntries(Object.entries(filters).map(([key, values]) => [key, new Set(values)]))
+}
+
+/** The plain lists a consumer reads, empty columns left out. */
+export function fromHiddenSets(hidden: Record<string, ReadonlySet<unknown>>): TableFilters {
+  return Object.fromEntries(Object.entries(hidden).filter(([, set]) => set.size).map(([key, set]) => [key, [...set]]))
+}
+
+/** Whether two filter states hide the same values, empty columns counting as absent. */
+export function sameHidden(a: Record<string, ReadonlySet<unknown>>, b: Record<string, ReadonlySet<unknown>>): boolean {
+  const keys = new Set([...Object.keys(a), ...Object.keys(b)])
+  for (const key of keys) {
+    const x = a[key]
+    const y = b[key]
+    if ((x?.size ?? 0) !== (y?.size ?? 0)) return false
+    if (x && y) for (const v of x) if (!y.has(v)) return false
+  }
+  return true
+}
+
+/**
+ * Persisted filters meeting the ones a parent already set: the parent's
+ * explicit state (a deep link, a control above the table) wins per column,
+ * and what was remembered fills only the columns it leaves alone.
+ */
+export function mergeRestored(
+  current: Record<string, ReadonlySet<unknown>>,
+  restored: Record<string, unknown[]>,
+): Record<string, Set<unknown>> {
+  const out: Record<string, Set<unknown>> = Object.fromEntries(Object.entries(current).map(([k, v]) => [k, new Set(v)]))
+  for (const [key, values] of Object.entries(restored)) if (!out[key]?.size) out[key] = new Set(values)
+  return out
+}
+
 /** Lower-cased and stripped of accents, so "cafe" finds "Café". */
 export function foldText(text: string): string {
   return text.normalize("NFKD").replace(/\p{M}/gu, "").toLocaleLowerCase()

package/src/composables/useTableFilterChoice.ts

@@ -0,0 +1,51 @@
+import { computed, toValue, type MaybeRefOrGetter, type Ref, type WritableComputedRef } from "vue"
+import { shownValues, showOnly, type TableFilters } from "../components/tableFilter"
+
+/**
+ * One column of LpTable's header filters as a single choice, for a control
+ * above the table (LpSegmented, LpSelect, a row of stat tiles) that filters
+ * the same thing as the column's funnel. Both then read and write one state:
+ * picking a choice sets the funnel, and narrowing the funnel to a choice's
+ * values lights that choice up.
+ *
+ * `choices` maps each choice to the values it shows; `null` is the choice
+ * that shows everything. `values` is the column's vocabulary, by default every
+ * value the choices name. The ref reads `undefined` while the funnel holds a
+ * mix no choice describes, so the control shows nothing picked rather than a
+ * choice that is not what the table shows.
+ */
+export function useTableFilterChoice<C extends string>(
+  filters: Ref<TableFilters>,
+  column: string,
+  choices: Record<C, readonly unknown[] | null>,
+  values?: MaybeRefOrGetter<readonly unknown[]>,
+): WritableComputedRef<C | undefined> {
+  const entries = Object.entries(choices) as [C, readonly unknown[] | null][]
+  const vocabulary = computed(() => {
+    const own = values === undefined ? undefined : toValue(values)
+    return own ?? [...new Set(entries.flatMap(([, shown]) => shown ?? []))]
+  })
+
+  return computed({
+    get: () => {
+      const all = vocabulary.value
+      const shown = new Set(shownValues(all, filters.value[column]))
+      for (const [choice, keep] of entries) {
+        if (keep === null) {
+          if (shown.size === all.length) return choice
+          continue
+        }
+        if (keep.length === shown.size && keep.every((v) => shown.has(v))) return choice
+      }
+      return undefined
+    },
+    set: (choice) => {
+      const keep = choice === undefined ? null : choices[choice]
+      const hidden = keep === null ? [] : showOnly(vocabulary.value, keep)
+      const next = { ...filters.value }
+      delete next[column]
+      if (hidden.length) next[column] = hidden
+      filters.value = next
+    },
+  })
+}

package/src/index.ts

@@ -220,6 +220,9 @@ export type { SortState, TableColumn, TablePage, TableQuery } from "./components
 export type { TableLabels } from "./components/LpTable.vue"
 export type { TableExportOptions } from "./components/LpTable.vue"
 export { compareValues } from "./components/tableSort"
+export { filterRows, showOnly, shownValues } from "./components/tableFilter"
+export type { TableFilters } from "./components/tableFilter"
+export { useTableFilterChoice } from "./composables/useTableFilterChoice"
 export { resolveRowMenu } from "./components/tableRowMenu"
 export type { TableRowMenu, TableRowMenuResult } from "./components/tableRowMenu"
 export { default as LpTableOfContents } from "./components/LpTableOfContents.vue"