better-filter-bar

A generic, schema-driven structured filter bar built on CodeMirror 6. Supports a typed query language with boolean logic, comparison operators, autocomplete, inline validation, and structured AST output.

Think GitHub filter bars — status:open author:alice priority>=2 — as a drop-in component.

Features

• Schema-driven — declare fields and types, get autocomplete, validation, and parsing for free
• Filter Query Language (FQL) — field:value, field>=value, AND/OR/NOT, grouping with ()
• Field types — text, enum, number, date, boolean with type-appropriate operators
• Autocomplete — context-aware suggestions for field names, operators, and values (sync and async)
• Inline validation — unknown fields, invalid operators, type mismatches, bad enum values
• Token highlighting — color-coded fields, operators, values, and boolean keywords via CSS custom properties
• Structured AST output — parsed query emitted as JSON on every change
• Single-line input — enforced via keymap and transaction filter
• Accessible — role="search", keyboard navigation, screen-reader-friendly mark decorations
• Two entry points — core CodeMirror extensions (better-filter-bar) and React wrapper (better-filter-bar/react)

Installation

npm install better-filter-bar

React is an optional peer dependency — only needed if you use better-filter-bar/react.

Quick Start (React)

import { FilterBar } from "better-filter-bar/react";

const schema = {
  fields: [
    {
      name: "status",
      label: "Status",
      type: "enum",
      options: [
        { value: "open" },
        { value: "closed" },
        { value: "in_progress", label: "In Progress" },
      ],
    },
    { name: "author", label: "Author", type: "text" },
    { name: "priority", label: "Priority", type: "number", min: 0, max: 5 },
    {
      name: "created",
      label: "Created",
      type: "date",
      relativeDates: ["today", "yesterday", "-7d", "-30d"],
    },
    { name: "is_blocked", label: "Blocked", type: "boolean" },
  ],
};

function App() {
  return (
    <FilterBar
      schema={schema}
      placeholder="Filter issues..."
      onChange={(ast, raw) => console.log(ast)}
      onSubmit={(ast, raw) => applyFilter(ast)}
    />
  );
}

Quick Start (Vanilla CodeMirror)

import { EditorView } from "@codemirror/view";
import { EditorState } from "@codemirror/state";
import { filterBarExtensions, parseQuery } from "better-filter-bar";

const state = EditorState.create({
  doc: "",
  extensions: filterBarExtensions(schema, {
    onChange: (ast, raw) => console.log(ast),
  }),
});

const view = new EditorView({ state, parent: document.body });

Query Syntax

status:open                          # exact match
status:(open,closed)                 # multi-value (OR within list)
status:open author:alice             # implicit AND
status:open AND author:alice         # explicit AND
status:open OR status:closed         # OR
NOT status:closed                    # negation
priority>=2                          # comparison (=, !=, >, >=, <, <=)
created:>2024-01-01                  # date comparison
label:"needs review"                 # quoted value (required for spaces)
(status:open OR status:draft) AND priority>=3  # grouping

Precedence (high to low): () > NOT > AND > OR

API

FilterSchema

interface FilterSchema {
  fields: FieldDef[];
  allowUnknownFields?: boolean; // default: false
  implicitOperator?: "AND" | "OR"; // default: "AND"
}

Field Types

Type	Operators	Notes
text	:	Static or async suggestions
enum	:	Declared options, multi-value via :(a,b)
number	: = != > >= < <=	Optional min/max
date	: = != > >= < <=	Relative dates supported
boolean	:	true/false/yes/no/1/0

FilterBarProps (React)

Prop	Type	Description
schema	FilterSchema	Field definitions (required)
initialValue	string	Starting query
placeholder	string	Placeholder text
onChange	(ast, raw) => void	Fires on every change
onSubmit	(ast, raw) => void	Fires on Enter
readOnly	boolean	Disable editing
className	string	CSS class on container

useFilterBar(schema)

Imperative hook for programmatic control:

const { viewRef, setValue, getValue, getAST, clear, focus } = useFilterBar(schema);

parseQuery(raw, schema)

Standalone parser — converts a query string to a FilterAST:

parseQuery("status:open AND priority>=2", schema);
// => { type: "boolean", operator: "AND", left: {...}, right: {...} }

AST Node Types

Type	Shape
filter	{ field, operator, value }
boolean	{ operator: "AND"|"OR", left, right }
not	{ operand }
free_text	{ value }
empty	{}

Theming

All colors are CSS custom properties:

Property	Default	Purpose
--fql-bg	#ffffff	Background
--fql-border	#d0d7de	Border
--fql-focus-border	#0969da	Focus ring
--fql-field-color	#0550ae	Field name
--fql-op-color	#953800	Operator
--fql-value-color	#116329	Value
--fql-bool-color	#8250df	AND/OR/NOT

Core Exports

Export	Entry Point	Description
filterBarExtensions(schema, opts)	better-filter-bar	CM6 extension bundle
parseQuery(raw, schema)	better-filter-bar	String to AST
fql(schema)	better-filter-bar	Language + autocomplete + linter
fqlLanguage	better-filter-bar	Raw LRLanguage
fqlLinter(schema)	better-filter-bar	Standalone linter extension
fqlCompletion(schema)	better-filter-bar	Standalone autocomplete extension
FilterBar	better-filter-bar/react	React component
useFilterBar(schema)	better-filter-bar/react	Imperative hook

Future Feature Considerations

• Controlled value prop — value + onChange with CM6 transaction reconciliation
• Saved/named filters — persist and recall named filter presets
• Negation shorthand — -field:value as shorthand for NOT field:value
• Relative date expansion — resolve -7d to actual dates in AST output
• Custom operators — allow schemas to define domain-specific operators
• Mobile optimization — virtual keyboard hints and touch-friendly autocomplete
• Drag-and-drop token reordering — rearrange filter tokens visually
• Filter validation callbacks — schema-level async validation (e.g. "does this user exist?")
• Serialization helpers — built-in AST-to-SQL, AST-to-Elasticsearch, AST-to-URL-params

Development

vp install          # install dependencies
vp run demo         # interactive demo at localhost:5173
vp test             # run tests
vp check            # lint + format + typecheck
vp run build        # build library

License

MIT