model-list-filters

Adds period, reference, select, and text filters to list and report screens via schema annotations.

1|Updated Jun 25, 2026
One-click install
npx skills add https://github.com/IgorAIvanov/altera03 --skill model-list-filters-igoraivanov
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: model-list-filters
Source: https://github.com/IgorAIvanov/altera03/tree/main/skills/src/model-list-filters
Command: npx skills add https://github.com/IgorAIvanov/altera03 --skill model-list-filters-igoraivanov

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? List and report screens need filters (period, reference picker, select, checkbox, free text) wired consistently across three places: the TypeBox schema annotation, the generated SQL, and the screen markup. Doing this by hand causes silent failures — filters that are set but never applied, badge counts that are wrong, and Reset buttons that leave stale values behind. ## Core Features & Use Cases - Schema-driven filter generation: Declare x-filter on a model field and regenerate SQL with deno task sql:gen; the parsing, WHERE clauses, and mirrored response are produced automatically. - Reference filter contract: Enforces the one-key-object rule ({"counterparty": {"id": "4", "name": "Fierst"}}) so the badge count and clearing behavior stay correct. - Period handling: Distinguishes range filters (dateFrom/dateTo) from whole-unit periods (month, quarter, year) using <ui-period>, and covers the < to + 1 upper-bound rule for timestamp columns. - Use Case: Add a counterparty picker, a posted-state select, and a period filter to an invoice list screen by annotating the schema, regenerating SQL, and writing one renderFilters() method. ## Quick Start Ask the AI to add a period filter and a counterparty reference filter to the invoice list screen, wiring the schema annotation, generated SQL, and renderFilters markup together.

Frequently Asked Questions about model-list-filters

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I add a filter to a list screen with a generated model?

Add one line of `x-filter` annotation to the field in the model's schema file, then regenerate the SQL with `deno task sql:gen`. The parsing, WHERE conditions, and mirrored response are generated; you only write the controls in `renderFilters()`.

How should a reference filter be structured in the filters payload?

A reference filter is one key holding an object with id and display label, such as `{"counterparty": {"id": "4", "name": "Fierst"}}`. Never split it into an id key plus a label key, which breaks the badge count and leaves stale labels after clearing.

When should a period filter use a range versus a single date?

Use `{ op: "range" }` when the user picks arbitrary start and end dates. Use the plain scalar form with `<ui-period>` when the question is asked in whole units like a month, quarter, or year, where the value is the first day of the unit.

Why is my filter set but not applied to the query?

The most common cause is a key mismatch: jsonb silently ignores unknown keys, so a typo in the filter name fails without any error. The key in renderFilters(), the payload, and the SQL must be the exact same string.

How do filters work differently on report screens versus lists?

Reports use the same filter contract but do not rebuild on filter change; Refresh builds the report and the base blurs stale output with a Rebuild notice. Reports also draw filters under the toolbar instead of the collapsible right panel, and their SQL is hand-written.

How do I write filter SQL by hand for a non-generated model?

Read `payload->'filters'`, extract only the id from reference objects, and rebuild the key with the label from the database. Use `< to + 1` for timestamp upper bounds, wrap search conditions in brackets before adding filter ANDs, and apply jsonb_strip_nulls when rebuilding references.