From 5fba6187ce9839b97246f4bd6327fc3c5638e18c Mon Sep 17 00:00:00 2001 From: Timothy Date: Thu, 23 Jul 2026 22:08:41 +0200 Subject: [PATCH] feat(437): inline RuleBuilder smart-query authoring in Channel Builder MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adopt the reusable RuleBuilder (#176) for inline query authoring in the Channel Builder (/app/new-channel). Extract CollectionsScreen's smart-collection dialog into a shared, self-contained component (SmartCollectionDialog) and consume it in both screens; the Channel Builder's Collections source gains a "New smart query" action that persists the authored query as a real SmartCollection and adds it to the lineup by smartCollectionId. Pure frontend — no REST/MCP surface change (the MCP already exposes ersatztv_create_smart_collection). The Auto-Tune half of #437 is a different primitive (group-by, not single-query filtering) and a backend epic; it is designed separately in docs/superpowers/specs/2026-07-23-auto-tune-arbitrary-field-design.md and filed as its own issue rather than wired here. Verification: web typecheck + lint clean; full vitest suite green (981, incl. a new inline-smart-query test); cold-context review clean; live-E2E on a real instance (query authored in the SPA persisted as SmartCollection "Action Picks" and added to the lineup, 0 console errors). Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/spa-conventions.md | 20 +- ...-07-23-auto-tune-arbitrary-field-design.md | 607 ++++++++++++++++++ web/src/builder/ChannelBuilder.test.tsx | 52 ++ web/src/builder/ChannelBuilder.tsx | 72 +++ web/src/builder/SmartCollectionDialog.tsx | 221 +++++++ web/src/screens/CollectionsScreen.tsx | 213 +----- 6 files changed, 969 insertions(+), 216 deletions(-) create mode 100644 docs/superpowers/specs/2026-07-23-auto-tune-arbitrary-field-design.md create mode 100644 web/src/builder/SmartCollectionDialog.tsx diff --git a/docs/spa-conventions.md b/docs/spa-conventions.md index 6b95569d4..b729107a2 100644 --- a/docs/spa-conventions.md +++ b/docs/spa-conventions.md @@ -501,12 +501,22 @@ screen concern — so it can be embedded by later screens without duplicating th **Usage pattern**: a screen owns two things — the raw `query` string (what actually gets saved) and the parsed `Group | null` (what the builder edits). Toggling between "Builder" and raw-text modes is just switching which of the two is the source of truth for that render, re-deriving the other via -`compile`/`parse` at the toggle boundary. See the SmartCollection dialog for the reference -integration. +`compile`/`parse` at the toggle boundary. See `SmartCollectionDialog` for the reference integration. -This module is intentionally reusable beyond SmartCollections — ChannelBuilder and Auto-Tune's -inline query editing (#69) are candidate future consumers, tracked as separate follow-up issues -rather than wired in #176. +- **`SmartCollectionDialog.tsx`** (`web/src/builder/`) — the name + query authoring dialog wrapping + `RuleBuilder` (Builder/Advanced toggle + a live preview count), extracted from CollectionsScreen so + it is a **shared, self-contained editor** (#437). Its only coupling to a host is the interface + `{ open, busy, error, initial, onCancel, onSubmit({name, query}) }` — the parent owns the `onSubmit` + side effect (persist, add to a lineup, …). Consumed by **CollectionsScreen** (create/edit) and the + **ChannelBuilder** (`/app/new-channel`, "New smart query" in the Collections source): the Builder + authors an ad-hoc query, `createSmartCollection` persists it as a real named SmartCollection, and the + new collection is added to the lineup by its `smartCollectionId` — no new REST/MCP surface (the MCP + already exposes `ersatztv_create_smart_collection`). + +Generalizing **Auto-Tune's** fixed axis picker into an arbitrary-field builder is a *different* +primitive (group-by, not single-query filtering) and a backend epic — designed separately in +`docs/superpowers/specs/2026-07-23-auto-tune-arbitrary-field-design.md`, tracked as its own issue, +not wired here. - **Relative-date operators** (#435, `rulebuilder.relative-date-macros`) — `release_date`/`added_date` gain `inLast`/`notInLast` alongside `before`/`after`/`between`, each with a numeric value plus a diff --git a/docs/superpowers/specs/2026-07-23-auto-tune-arbitrary-field-design.md b/docs/superpowers/specs/2026-07-23-auto-tune-arbitrary-field-design.md new file mode 100644 index 000000000..875ccc836 --- /dev/null +++ b/docs/superpowers/specs/2026-07-23-auto-tune-arbitrary-field-design.md @@ -0,0 +1,607 @@ +# Auto-Tune over an arbitrary group-by field — backend design spec + +- **Date:** 2026-07-23 +- **Issue:** ersatztv#437 (RuleBuilder / Auto-Tune generalization) +- **Status:** Design proposal — no code changes. Backend-first. +- **Scope:** Generalize the fixed 3-axis Auto-Tune picker (`TvShow | TvGenre | MovieGenre`) into an + arbitrary **group-by field** builder drawn from the shared `GET /api/v1/search/fields` catalog, so + "one channel per distinct value of field _F_, filtered to media type _M_" works for genre, studio, + director, network, content rating, tag, decade-from-date, etc. + +--- + +## 1. Summary + +Auto-Tune today hard-codes three axes end to end: an `AutoTuneAxis` enum, three bespoke EF +enumerations in `PreviewAutoTuneChannelsHandler`, and a per-axis `switch` in `AutoTuneAxisMap` for +query / name / playback-order / per-source-weight generation. This spec proposes replacing the +closed axis with an open **`(field, mediaType)` group-by** keyed on the **same field vocabulary** the +RuleBuilder (#176), the facet typeahead (#434), and MCP `ersatztv_search` already speak — the +`SearchFieldCatalog`. The field names in that catalog **are** the Lucene index field names, which is +the throughline that makes generic query generation clean. + +Recommended shape, in one paragraph: keep the `axis` path frozen and populated (deprecate-in-place +per the `/api/v1` additive-only rule), add an **optional `groupBy { field, mediaType }`** selection to +the preview and create request DTOs, resolve **either** an axis **or** a `groupBy` to one internal +`AutoTuneGroupBy` value object, and drive enumeration off a **generic per-field distinct-value + count +DB query** (an extension of the #434 `GetSource` map) rather than faceting the Lucene index — because +the index exposes **no faceting API today** (`ISearchIndex` has only `Search`). Membership queries, +channel names, and default playback orders all become pure functions of `AutoTuneGroupBy` instead of +the enum. New MCP tools `ersatztv_preview_auto_tune` / `ersatztv_create_auto_tuned_channels` (plus +`ersatztv_list_search_fields`) expose the capability to machine clients on the shared vocabulary. + +The two hard, genuinely-uncertain parts are flagged as open questions, not designed away: (a) how much +of the per-source **weights/remainder** machinery (#425) can generalize beyond "sources = shows or +movies", and (b) whether **derived fields** like `decade` belong in the shared catalog or in an +Auto-Tune-only extension. + +--- + +## 2. Problem / Motivation + +The 3-axis picker is a small, fixed slice of an obviously-general capability. A user who wants "one +channel per studio", "one channel per director", "one channel per decade", or "one channel per tag" +has to build each SmartCollection + channel by hand, even though: + +- The RuleBuilder already presents the full filterable field set (`SearchFieldCatalog`, 26 fields + across General/TV/Movie/Music/Technical/Dates groups) as a first-class vocabulary. +- The facet typeahead (#434) already enumerates **distinct whole values per field** from the DB for a + useful subset of those fields. +- Auto-Tune already knows how to turn `(query → SmartCollection → channel)` with number allocation, + name-length guards, per-channel template/logo/advanced overrides, and per-source weights. + +The missing piece is purely the **generalization of the axis** — everything downstream of "here is a +distinct value and a membership query" is already generic. Unifying on the shared field catalog turns +three special cases into one open mechanism and removes the enum as the thing that must be edited every +time a new grouping is wanted. + +--- + +## 3. Current architecture (exact references) + +### 3.1 The closed axis + +- **`ErsatzTV.Core/Domain/AutoTuneAxis.cs`** — `enum AutoTuneAxis { TvShow = 0, TvGenre = 1, MovieGenre = 2 }`. + +### 3.2 Per-axis logic — `ErsatzTV.Application/Channels/AutoTuneAxisMap.cs` + +A static class of pure functions, each a `switch (axis)`: + +| Function | TvShow | TvGenre | MovieGenre | +|---|---|---|---| +| `GenerateQuery(axis, value)` | `type:episode AND show_title:"v"` | `type:episode AND genre:"v"` | `type:movie AND genre:"v"` | +| `GenerateName(axis, value)` | `v` | `v` | `v Movies` (disambiguating suffix) | +| `PlaybackOrderFor(axis)` | `SeasonEpisode` | `Shuffle` | `Shuffle` | +| `GenerateSourceQuery(axis, disc)` | `type:episode AND show_title:"disc"` | (same as TvShow) | `type:movie AND id:disc` | +| `SourceDiscriminatorClause(axis, disc)` | `show_title:"disc"` | (same) | `id:disc` | +| `GenerateRemainderQuery(...)` | `(base) AND NOT (d1 OR d2 …)` — partitions base set across member sources + remainder | +| `EscapeLuceneValue(v)` | backslash then double-quote escaping for a Lucene phrase | + +Note the field names in these templates (`show_title`, `genre`, `id`, `type`) are exactly the Lucene +index field constants (`LuceneSearchIndex.ShowTitleField`, `GenreField`, `IdField`, `TypeField`). + +### 3.3 Enumeration — `ErsatzTV.Application/Channels/PreviewAutoTuneChannelsHandler.cs` + +Three **bespoke EF queries**, each hand-written against a specific navigation path: + +- `EnumerateTvShows` — groups `Episodes` by `Season.ShowId`, then **collapses shows that share a + title** into one entry (because the generated `show_title:"…"` query matches them together); + count = episodes per title. +- `EnumerateEpisodeGenres` — `EpisodeMetadata.SelectMany(m => m.Genres).GroupBy(g => g.Name)`. +- `EnumerateMovieGenres` — `MovieMetadata.SelectMany(m => m.Genres).GroupBy(g => g.Name)`. + +Each returns `(axis, value, count)` triples filtered by `count >= minItems`, ordered case-insensitively. +The handler then: generates names via `AutoTuneAxisMap.GenerateName`, drops proposals whose name would +exceed the Channel-name 50-char limit **before** number allocation (so numbers aren't wasted), +allocates sequential numbers skipping existing ones (`AutoTuneNumberAllocator.Allocate`), and flags +`AlreadyExists` against existing channel names (case-insensitive). + +**These three queries share no column.** `show_title` is a denormalized string on episodes, `genre` is +a joined `Genre` table via metadata, movie-genre is the same join off a different metadata table. This +is the crux of the generalization problem. + +### 3.4 Creation — `ErsatzTV.Application/Channels/CreateAutoTunedChannelsHandler.cs` + +Turns a proposal into a real channel. Two shapes: + +- **Single SmartCollection** (`CreateSingleSmartCollectionChannel`): `CreateSmartCollection(query, + name)` then `CreateChannelFromLineup` referencing it; axis-default playback order unless overridden; + rolls back the SmartCollection on channel-create failure. +- **Weighted MultiCollection** (`CreateWeightedChannel` + `BuildWeightedPlan` / `BuildTvPlan` / + `BuildMoviePlan`, #425): when the caller customized any per-source weight/exclusion/addition, builds + a system-owned `MultiCollection` of per-source `SmartCollection`s with `WeightedShuffle` plus a + catch-all **remainder** SmartCollection; stamps `OwnedByChannelId` for cleanup. + +### 3.5 Members enumeration — `ErsatzTV.Application/Channels/GetAutoTuneChannelMembersHandler.cs` + +`GET /api/v1/channels/auto-tune/members?axis=&value=&pageNum=&pageSize=` runs +`AutoTuneAxisMap.GenerateQuery` through **`ISearchIndex.Search`** (capped at 10k leaf items), then +rolls matches up to distinct content **sources**: parent shows for the TV axes (item count = matching +episodes, not the show total), movies for the movie-genre axis. Decision `sched.autotune-detailpanel-members` +(#384): live search-index roll-up, **not** EF, so the preview matches exactly what the built channel's +SmartCollection resolves to. + +### 3.6 DTOs & controller + +- **Request:** `ErsatzTV/Controllers/Api/Requests/AutoTuneRequests.cs` + - `PreviewAutoTuneChannelsRequest(List Axes, int MinItems, int StartingNumber)` + - `CreateAutoTunedChannelsRequest(int TemplateId, string Group, List Channels)` + - `AutoTunedChannelRequest(AutoTuneAxis Axis, string Value, string Name, string Number, int? + TemplateId, ArtworkContentTypeModel Logo, CreateChannelFromLineupAdvancedOptionsRequest Advanced, + List Sources)` — the last four optional (#385/#425). + - `AutoTuneSourceWeightRequest(int SourceId, int Weight = 1, bool Excluded = false)` +- **Commands:** `ErsatzTV.Application/Channels/PreviewAutoTuneChannels.cs`, + `CreateAutoTunedChannels.cs`, `GetAutoTuneChannelMembers.cs`. +- **Response:** `ErsatzTV.Core/Api/Channels/AutoTuneResponseModels.cs` — + `AutoTuneProposalResponseModel(string Axis, string Value, string Name, string Number, int ItemCount, + bool AlreadyExists)`, `AutoTuneChannelResultModel`, `AutoTuneResultResponseModel`. Note `Axis` is + already serialized as a **string** on the wire. +- **Controller:** `ErsatzTV/Controllers/Api/ChannelController.cs` — `PreviewAutoTune`, + `CreateAutoTuned`, `GetAutoTuneChannelMembers`. Standard session-or-key credential (no + `[RequiresAuthentication]`), per `docs/api-conventions.md` §1/§9 and the #69/#384 endpoint inventory. + +### 3.7 The shared field vocabulary + +- **`ErsatzTV.Application/Search/SearchFieldCatalog.cs`** — `List`. `Type ∈ {text, fulltext, number, date, + enum}`; `Values` populated only for `enum` (only `type` today, with the 10 item-type tokens). **Field + `Name` == Lucene field name.** +- **`GET /api/v1/search/fields`** → `GetSearchFieldCatalogHandler` (returns the catalog). +- **`GET /api/v1/search/fields/{name}/values?q=&limit=`** → `GetSearchFieldValuesHandler` (#434). Its + private `GetSource(dbContext, name)` maps a field name to an `IQueryable` of distinct whole + values (genre/show_genre → `Genre.Name`, studio → `Studio.Name`, director → `Director.Name`, writer, + actor, artist, tag/network → `Tag.Name` filtered by `ExternalTypeId`, collection, video_codec, album, + plus in-memory `state`/`video_dynamic_range`/`content_rating`). **This is the closest thing to a + generic distinct-value backbone already in the codebase** — but it returns values only, **no counts**, + and applies no media-type scope. +- SPA consumer: `web/src/builder/rules/fieldCatalog.ts` (`useSearchFields`), which coerces the + all-nullable generated `SearchField` into a clean `RuleField`. + +### 3.8 The index has no faceting API + +**`ErsatzTV.Core/Interfaces/Search/ISearchIndex.cs`** exposes only `Search(query, smartCollectionName, +skip, limit, [defaultFields], ct)` returning `SearchResult(List Items, int TotalCount)` +(+ a `SearchPageMap` jump-letter map). There is **no** `Facet` / `GroupBy` / term-enumeration method. +`LuceneSearchIndex` indexes text fields as analyzed `TextField`s (lowercased word tokens) and dates as +`yyyyMMdd` `StringField`s. This is decisive for Area 1 below. + +--- + +## 4. Proposed design + +### 4.1 The unifying value object + +Introduce an internal group-by descriptor (Application layer, alongside `AutoTuneAxisMap`): + +```csharp +// ErsatzTV.Application/Channels/AutoTuneGroupBy.cs (new) +public record AutoTuneGroupBy( + string Field, // a SearchFieldCatalog.Name (Lucene field name), OR a derived key (see 4.4) + AutoTuneMediaType MediaType); // Episode | Movie | MusicVideo | OtherVideo | Song | Any (see open Q) + +public enum AutoTuneMediaType { Episode, Movie, /* … */ Any } +``` + +`AutoTuneAxisMap` becomes a **resolver + generic generator** rather than a per-axis switch: + +- `AutoTuneGroupBy Resolve(AutoTuneAxis axis)` maps the three legacy axes to their group-by: + - `TvShow` → `("show_title", Episode)` (special enumeration, see 4.2) + - `TvGenre` → `("genre", Episode)` + - `MovieGenre` → `("genre", Movie)` +- The `GenerateQuery` / `GenerateName` / `PlaybackOrderFor` / member-query functions take an + `AutoTuneGroupBy` and become field-generic (4.3). The existing `AutoTuneAxis` overloads stay as thin + wrappers `=> Resolve(axis)`-then-delegate, so every current caller and test keeps compiling and + behaving byte-identically. + +### 4.2 Area 1 — Generic distinct-value enumeration + +**Recommendation: enumerate via the database (an extended #434 `GetSource` + count), NOT by faceting +the Lucene index.** + +Rationale — faceting the index is **not the clean path here**, despite the index powering `search/fields`: + +- `ISearchIndex` exposes no faceting/term-enumeration API (3.8). Adding one means new Lucene facet + fields (`SortedSetDocValuesFacetField`) or a `MultiFields.GetTerms` walk in `LuceneSearchIndex`, a + full **reindex**, and a cross-cutting change to a shared search primitive — large blast radius for a + scheduling feature. (See MEMORY: "Verify a shared primitive covers ALL variants.") +- Analyzed `TextField`s store **lowercased word tokens**, not whole values — the exact reason #434 + sourced typeahead from the DB, not the Lucene term dictionary. Faceting `genre` would yield + `science` / `fiction`, not `Science Fiction`. So even with a facet API, counts/labels would be wrong + for the multi-word values that matter most. +- The DB already has the exact joins, and #434 already curates the per-field distinct-value source. + +**Proposed generic enumeration:** a new Application service `IAutoTuneFieldEnumerator` / +`AutoTuneFieldEnumerator` with + +```csharp +Task> Enumerate(AutoTuneGroupBy groupBy, int minItems, CancellationToken ct); +public record AutoTuneFieldValue(string Value, int Count); +``` + +It reuses the **shape** of `GetSearchFieldValuesHandler.GetSource` but returns `(value, count)` scoped +to `groupBy.MediaType`, via three strategy families keyed on how the field is stored: + +1. **Joined-table / metadata-collection fields** (genre, tag, network, studio, director, writer, actor, + content_rating, collection, video_codec, album, artist, style, mood, …): a `GroupBy(name).Count()` + over the metadata rows for the target media type. E.g. `genre` + `Episode` reproduces today's + `EnumerateEpisodeGenres` exactly; `genre` + `Movie` reproduces `EnumerateMovieGenres`; `studio` + + `Movie` is `MovieMetadata.SelectMany(m => m.Studios).GroupBy(s => s.Name)`. The per-`(field, + mediaType)` navigation path is the one piece that stays a lookup table — but it is a **data table** + (field → metadata set + collection selector), not scattered bespoke handlers, and it is unit-testable + as pure query composition. +2. **Denormalized scalar fields** (`show_title` for the TV-show axis — a scalar on the show, counted by + episodes): the existing `EnumerateTvShows` special case (title collapse + episode count) is preserved + as the `("show_title", Episode)` strategy. This is why the legacy `TvShow` axis stays a named preset: + its "collapse shared titles" semantics are worth keeping explicit. +3. **Derived fields** (decade from `release_date`, year, added-year): see 4.4 — an extra strategy that + buckets a date/number column. + +`minItems` filters, ordering is case-insensitive by value (matching today). Media-type scope is +**required** and comes from `AutoTuneGroupBy.MediaType`, resolving the "genre exists for both TV and +movies" ambiguity that `GenerateName`'s "Movies" suffix papers over today. + +**Limits to state honestly:** this keeps a per-`(field, mediaType)` navigation table — it is *not* +zero-config for a brand-new field. A field in the catalog with no enumeration strategy (e.g. `plot` +fulltext, `minutes` raw number without bucketing) simply isn't offer-able as a group-by; the API must +**allow-list** group-by-able fields (mirroring #434's 404-for-unsupported-field contract) rather than +accept any catalog field and fail late. + +**Count exactness vs. the members roll-up.** Preview counts come from the DB (exact, cheap, matches +#69's `sched.auto-tune-foundation` decision), while the **members** endpoint (4.5) stays on the live +`ISearchIndex.Search` roll-up (matches #384). Keep that split: DB for the "how many channels / how big" +preview, index for "exactly what will this one channel contain." + +### 4.3 Area 2 — Generic query / name / playback-order generation + +**Membership query.** Because catalog field name == Lucene field name, the generic membership query is: + +``` +type:{luceneType(mediaType)} AND {field}:"{EscapeLuceneValue(value)}" +``` + +`GenerateQuery(AutoTuneGroupBy, value)` produces this directly; the three legacy templates fall out as +special cases (`show_title`/`genre` + `episode`/`movie`). `EscapeLuceneValue` is unchanged. Fields that +are analyzed `TextField`s already work as double-quoted phrase queries today (`genre:"Science Fiction"`, +`studio:"Warner Bros"`), which is exactly how the RuleBuilder emits them — so we inherit the +RuleBuilder's proven grammar subset (`spa.smartcollection-rule-builder`, #176) rather than inventing a +new one. + +**Channel name.** Default = the raw `value`. To keep the anti-collision property `GenerateName` has +today (TV "Comedy" vs movie "Comedy Movies"), derive the suffix from **media type**, not a hard-coded +axis: `Episode → value`, `Movie → "{value} Movies"`, others → a per-media-type suffix (`"{value} +Music"`, etc.), configurable. The user can already override per channel via the DetailPanel's `Name` +field, so this is only the default. The 50-char guard and pre-allocation drop stay. + +**Default playback order.** Generalize the "single item plays in order, a group shuffles" heuristic: + +- If the group-by is a **single-parent** grouping (today: `show_title`, where every value is one show's + episodes) → `SeasonEpisode`. +- Every other field (genre, studio, director, decade, …) → `Shuffle`. + +Encode this as a property of the strategy (`bool IsSingleParentGrouping`) rather than another `switch`. +The user override path is **unchanged**: `AutoTunedChannelRequest.Advanced.PlaybackOrder` already wins +over the axis/field default (see `CreateAutoTunedChannelsHandler` — `selection.Advanced?.PlaybackOrder +?? axisOrder`), and `WeightedShuffle` still overrides everything when a weighted plan is built. + +### 4.4 Area 2b — Derived fields (decade) + +`decade` is **not** a stored column and **not** in `SearchFieldCatalog`. It is a bucketing of +`release_date` (indexed as `yyyyMMdd` `StringField`; the query parser already supports range queries and +`released_inthelast` macros — `CustomMultiFieldQueryParser`). Proposal: + +- **Enumeration:** an EF query over the target metadata's `ReleaseDate`, `GroupBy(d => d.Year / 10 * 10)`, + producing values like `"2000s"` / `"1990s"` with counts. +- **Membership query:** a range query, e.g. `type:movie AND release_date:[20000101 TO 20091231]` — valid + classic Lucene the parser already handles (`base.GetRangeQuery`), and safe against the ParseException + literal-fallback trap `AutoTuneAxisMap` already documents. +- **Name:** the bucket label directly (`"2000s"`), no media-type suffix needed (decades don't collide + across TV/movie the way genre does — though the same suffix rule can apply if desired). + +This is the concrete example proving derived fields need **their own strategy** on all three axes +(enumerate / query / name), not just a field-name passthrough — hence the strategy interface in 4.2 +rather than a single generic query string builder. **Open question 4.4-a:** does `decade` (and friends +like `release_year`) get added to the shared `SearchFieldCatalog` (so the RuleBuilder gets it too — but +the RuleBuilder would then need to compile it, which today it cannot), or does Auto-Tune carry an +**extension catalog** of derived group-by fields that is a superset of `search/fields`? Recommend the +latter for the first cut (Auto-Tune-only `GET …/auto-tune/fields`, §4.6) to avoid forcing a RuleBuilder +grammar change, and revisit unifying once the RuleBuilder can compile range/bucket operators. + +### 4.5 Area 3 — API shape (additive-only) + +Per `docs/api-conventions.md` (§2 "evolving a frozen DTO: deprecate-in-place, add the richer field, +never remove"; `/api/v1` frozen-additive since #286), **nothing is removed**. Changes: + +**Preview request** — add an optional parallel selection; keep `Axes`: + +```csharp +public record PreviewAutoTuneChannelsRequest( + List Axes, // DEPRECATED-in-place: legacy 3-axis presets, still honored + int MinItems, + int StartingNumber, + List GroupBy = null); // NEW, optional + +public record AutoTuneGroupBySelection(string Field, string MediaType); +// Field = a group-by-able catalog/derived field name; MediaType = enum name ("Episode"/"Movie"/…). +``` + +Handler resolves the union of `Axes` (via `Resolve`) and `GroupBy`, de-duplicated, preserving order. +An empty union stays the existing "at least one axis is required" 422. An unknown/`non-group-by-able` +field is a **422** (`BaseError.New`) — same fail-closed posture as #434's 404, but 422 here because it +rides a POST body, not a `{name}` route segment. + +**Proposal response** — `AutoTuneProposalResponseModel` currently carries `Axis` (string). Add the +richer fields, keep `Axis` populated for legacy proposals (deprecate-in-place): + +```csharp +public record AutoTuneProposalResponseModel( + string Axis, // DEPRECATED: "TvShow"/"TvGenre"/"MovieGenre" for legacy-axis proposals; "" for field-based + string Value, + string Name, + string Number, + int ItemCount, + bool AlreadyExists, + string Field = "", // NEW: the group-by field name + string MediaType = ""); // NEW: the resolved media type enum name +``` + +**Create request** — `AutoTunedChannelRequest` currently keys each channel on `Axis`. Add optional +`Field`/`MediaType`; when present they supersede `Axis` (which may be sent as a legacy default). Keep +`Axis` required-in-shape but treated as ignored when `Field` is set, OR — cleaner — make `Field` +present ⇒ the server ignores `Axis`. All other per-channel overrides (`TemplateId`, `Logo`, `Advanced`, +`Sources`) are unchanged: + +```csharp +public record AutoTunedChannelRequest( + AutoTuneAxis Axis, // still first (positional back-compat); ignored when Field is set + string Value, + string Name, + string Number, + int? TemplateId = null, + ArtworkContentTypeModel Logo = null, + CreateChannelFromLineupAdvancedOptionsRequest Advanced = null, + List Sources = null, + string Field = null, // NEW: when set, drives generation via AutoTuneGroupBy + string MediaType = null); // NEW +``` + +Internally, `AutoTuneChannelSelection` (command) gains the same optional `Field`/`MediaType` (or, better, +a resolved `AutoTuneGroupBy? GroupBy`), and `CreateAutoTunedChannelsHandler` resolves +`selection.GroupBy ?? Resolve(selection.Axis)` at the top of `CreateOne`, then feeds the generic +`AutoTuneAxisMap` overloads. **No new endpoints, no route changes** for preview/create — schema-only +additions, so regenerate the OpenAPI trio (`v1.json` / `v1.d.ts` / `endpoint-index.md`) per §5, but no +`blazor-route-parity`/`domain-model` route rows change. + +**Members endpoint** — `GET /api/v1/channels/auto-tune/members` currently binds `axis`. Add optional +`field`/`mediaType` query params (bind `[FromQuery] string field`, `[FromQuery] string mediaType`); +when `field` is present it supersedes `axis`. Same paging clamp. This keeps the DetailPanel working for +field-based proposals. (See Area 4b open question on whether "sources/weights" generalize.) + +**New surface for the field list** (additive GET, mirrors `search/fields`): + +| Method | Path | Operation | Summary | +|---|---|---|---| +| GET | `/api/v1/channels/auto-tune/fields` | `GetAutoTuneFields` | List group-by-able fields (catalog subset + derived) with their supported media types | + +Returns `List` where `Kind ∈ {catalog, derived}`. This is the field-picker's data source and is +MCP-introspectable. It is the honest expression of the 4.2 "allow-list" — the SPA/MCP only offer what +the enumerator actually supports, instead of offering all 26 catalog fields and failing on `plot`. + +### 4.6 Area 4 — MCP tools + +`ErsatzTV.Mcp/ToolCatalog.cs` currently exposes **no auto-tune tools** (a pre-existing parity gap) but +already exposes `ersatztv_create_smart_collection`, `ersatztv_search`, `ersatztv_create_channel`. Add, +in the existing declarative style (flat args over `/api/v1`, writes gated on `ERSATZTV_ALLOW_WRITES`): + +**Read — the vocabulary (so the model can discover valid fields before calling preview):** + +```csharp +Get( + "ersatztv_list_search_fields", + "List the filterable search fields (name, label, type, group, enum values) — the shared vocabulary for search, the rule builder, and auto-tune.", + "/api/v1/search/fields"), +Get( + "ersatztv_list_auto_tune_fields", + "List the fields you can group auto-tuned channels by, with each field's supported media types. Call this first to discover valid {field, mediaType} pairs.", + "/api/v1/channels/auto-tune/fields"), +Get( + "ersatztv_get_search_field_values", + "List distinct values for one text search field (typeahead), optionally prefix-filtered.", + "/api/v1/search/fields/{name}/values", + [Str("name", "Field name from ersatztv_list_search_fields.", required: true, arg: In.Path)], + [Str("q", "Optional case-insensitive prefix filter.", arg: In.Query), + Int("limit", "Max values (1..50, default 50).", arg: In.Query)]), +``` + +**Read — preview (no writes; safe to run to plan a batch):** + +```csharp +Get( // note: the API is POST; MCP wrapper posts a body. If ToolCatalog only wraps GET-as-read, + // expose as a Post but document it as non-mutating (it creates nothing). + // Recommended: Post(...) with a clear "previews only, creates nothing" description. + "ersatztv_preview_auto_tune", + "Preview auto-tuned channels: one channel per distinct value of a group-by field, filtered to a media type. Creates nothing — returns proposed {name, number, itemCount, alreadyExists}. Discover fields via ersatztv_list_auto_tune_fields.", + "/api/v1/channels/auto-tune/preview", + ObjArray("groupBy", "Group-by selections; each { field: string, mediaType: string }.", required: true), + Int("minItems", "Minimum items for a value to become a channel.", required: true), + Int("startingNumber", "First channel number to allocate.", required: true)), +``` + +**Write — create (gated):** + +```csharp +Post( + "ersatztv_create_auto_tuned_channels", + "Bulk-create auto-tuned channels from previewed selections. Each channel is independent (per-channel Created/Skipped/Failed). Get proposals from ersatztv_preview_auto_tune first, then pass the ones to create.", + "/api/v1/channels/auto-tune", + Int("templateId", "Batch channel template id (per-channel override allowed).", required: true), + Str("group", "Channel group name (default \"Auto-Tuned\")."), + ObjArray( + "channels", + "Channels to create; each { field: string, mediaType: string, value: string, name: string, number: string, templateId?: number }. Advanced/logo/per-source weights are omitted here (use the SPA/API for those).", + required: true)), +``` + +Notes: (1) the create tool deliberately exposes the **field-based** shape (`field`/`mediaType`), not +the legacy `axis`, keying MCP on the shared vocabulary. (2) Complex per-channel overrides +(`advanced`/`logo`/`sources`) are intentionally out of the MCP body for v1 (same "deferred complex +writes" posture the ToolCatalog header already documents for schedule-item/playout writes). (3) These +tools require the OpenAPI/route additions in 4.5 to exist first (phased below). (4) Preview is +non-mutating; expose it as a read even though the HTTP verb is POST, and say so in the description so +the model doesn't gate it behind writes. + +### 4.7 Field-catalog throughline (explicit) + +The single unifying fact: **`SearchFieldCatalog.Name == Lucene field name == RuleBuilder field == +`search/fields` field == the Auto-Tune group-by key**. One vocabulary now spans: Lucene index → +`search/fields` (#176) → facet typeahead `search/fields/{name}/values` (#434) → RuleBuilder +(`fieldCatalog.ts`) → MCP `ersatztv_search` → **Auto-Tune group-by (this spec)**. Generalizing Auto-Tune +onto it means a user picks a group-by field from the *same* dropdown they filter a SmartCollection by, +and a membership query generated by Auto-Tune is the *same* grammar a hand-written SmartCollection uses. +Derived fields (decade) are the one place this throughline stretches — handled as an Auto-Tune extension +(4.4) until the RuleBuilder can compile bucket/range operators. + +--- + +## 5. Concrete API DTOs (collected) + +See 4.5 for context; consolidated for implementers: + +- `PreviewAutoTuneChannelsRequest` + new optional `List GroupBy`. +- `AutoTuneGroupBySelection(string Field, string MediaType)` — request DTO, `ErsatzTV/Controllers/Api/Requests/`. +- `AutoTuneProposalResponseModel` + new `Field`, `MediaType` (`#nullable enable`, defaults `""`). +- `AutoTunedChannelRequest` + new optional `string Field`, `string MediaType`. +- `AutoTuneFieldResponseModel(string Field, string Label, string[] MediaTypes, string Kind)` — new, + `ErsatzTV.Core/Api/Channels/`, `#nullable enable`, for `GET …/auto-tune/fields`. +- Command layer: `AutoTuneGroupBy(string Field, AutoTuneMediaType MediaType)`; + `PreviewAutoTuneChannels` gains the resolved group-by list; `AutoTuneChannelSelection` gains the + resolved `AutoTuneGroupBy? GroupBy`. +- `AutoTuneMediaType` enum — **define in `ErsatzTV.Core`** (not the Application command) so + `Startup.UseStringEnumSchemas` renders it as a string enum in the spec (per §2 "clear-to-none" note: + an Application-layer enum shows as bare `integer`). +- `AutoTuneAxis` stays; mark it deprecated in an XML comment. **Do not** remove or renumber it. + +Every change above is schema-only ⇒ regenerate `ErsatzTV/wwwroot/openapi/v1.json`, +`web/src/api/generated/v1.d.ts`, `docs/endpoint-index.md` via `./scripts/update-openapi.sh` + +`npm run generate:api`, and add the `GET …/auto-tune/fields` row to `docs/api-conventions.md`'s +endpoint inventory (blocking `api-docs` CI job fires on `Controllers/Api/**` + `Core/Api/**`). + +--- + +## 6. Backward compatibility + +- **Wire:** `Axes` and the positional `AutoTunedChannelRequest(Axis, Value, Name, Number, …)` are + preserved; every new field is optional with a back-compat default. An existing client sending only + the 3-axis form gets byte-identical behavior (the `Resolve(axis)` wrappers reproduce today's exact + query/name/order for `show_title`+Episode / `genre`+Episode / `genre`+Movie). +- **Response:** new `Field`/`MediaType` members default to `""` for legacy-axis proposals; `Axis` stays + populated. Deprecate-in-place, never remove (`/api/v1` freeze). +- **Handlers/tests:** the internal `AutoTuneAxisMap` axis overloads remain as delegating wrappers, so + existing handler and controller-route tests compile unchanged; the weights/remainder machinery + (#425) is untouched for the axis path. +- **DB / migrations:** **none required** — no `TvContext` model change. `channel.origin-marker` + (`ChannelOrigin.AutoTuned`) already stamps provenance and is orthogonal. + +--- + +## 7. Testing strategy + +- **Enumeration parity (characterization first):** before touching `PreviewAutoTuneChannelsHandler`, + add golden tests asserting the 3 legacy axes' current `(value, count)` output on a seeded + `InMemoryTvContext` fixture; then prove the generic `AutoTuneFieldEnumerator` reproduces them + bit-for-bit via `Resolve`. (MEMORY: "Modernize with test-before/after guardrail.") +- **New strategies:** unit tests per `(field, mediaType)` strategy — `studio`+Movie, `director`+Movie, + `network`+Episode, `tag`+Episode, and the derived `decade`+Movie (bucketing + range membership query). +- **Query generation goldens:** assert `GenerateQuery(groupBy, value)` for a set of fields incl. values + with embedded quotes/backslashes (Lucene escaping) and a decade range query; assert the ParseException + literal-fallback trap is avoided (parse the generated string through `SearchQueryParser`). +- **Name / order defaults:** genre TV vs movie suffix disambiguation; single-parent (`show_title`) → + `SeasonEpisode`, others → `Shuffle`; Advanced override still wins; weighted plan forces + `WeightedShuffle`. +- **API:** controller route-table test (`ShouldHaveActionRoute`) for the new `GET …/auto-tune/fields`; + round-trip a field-based preview→create; assert unknown/non-group-by-able field → 422; assert legacy + axis body still works. +- **Members:** field-based `members` returns a coherent source roll-up (or the documented "no + weighting" behavior per open Q 4b). +- **MCP:** the ToolCatalog has a shape/registration test pattern — assert the new tools' schemas and + that preview is not write-gated while create is. +- **OpenAPI sync:** `npm run check:api` + the `api-docs` job (mechanical, blocking). +- **Live E2E:** on `ersatztv-test`, preview + create "one channel per studio" and "one channel per + decade"; verify each channel's SmartCollection resolves to the expected items (MEMORY: per-task + reviews miss whole-feature defects; capture a real result). + +--- + +## 8. Risks & open questions + +1. **Per-source weights / remainder do not obviously generalize (highest risk).** The #425 + weights+remainder machinery (`BuildTvPlan`/`BuildMoviePlan`, `GenerateSourceQuery`, + `SourceDiscriminatorClause`, `GenerateRemainderQuery`) is built entirely around "a source is a show + (discriminator = `show_title`) or a movie (discriminator = `id`)." For a group-by on `studio` or + `director`, what is a "source" within one channel, and does it have a stable rename-proof + discriminator? For `decade`, the members are individual movies again (like MovieGenre), so it may + generalize there; for `studio`/`network` there is no per-source id the way a show/movie has one. + **Open question:** does field-based Auto-Tune ship **without** per-source weighting in v1 (single + SmartCollection only, `Sources` rejected as 422 for field-based channels), deferring weights to a + follow-up? Recommend **yes** — ship the generalization first, keep weights on the axis path only, + and design a generic "source" model separately. +2. **Membership-query fidelity for arbitrary analyzed fields.** Catalog `text` fields are analyzed + `TextField`s; a phrase query `field:"Some Value"` matches on tokenized terms and may mis-match values + with punctuation, or values whose DB whole-form differs from the indexed tokens (the exact class #434 + avoided by sourcing typeahead from the DB, not the term dictionary). Enumeration (DB) and membership + (Lucene) can therefore **disagree on the boundary** for some values — a channel could include + slightly more/fewer items than its preview count. Needs a fidelity pass per field family; may force + some fields (e.g. `content_rating`, which is split on `/`) to be excluded from group-by v1. Which + fields are safe is an empirical open question. +3. **Derived-field catalog placement (decade).** 4.4-a: add `decade`/`release_year` to the shared + `SearchFieldCatalog` (forces a RuleBuilder compile change it can't do today) vs. an Auto-Tune-only + extension catalog (`GET …/auto-tune/fields`). Recommend the extension for v1; flag that this means + the "one vocabulary" throughline has a documented seam until the RuleBuilder gains bucket/range + operators. + +**Lower-order open questions:** (a) `AutoTuneMediaType` granularity — do we support Music/OtherVideo/Song +group-bys in v1 or only Episode/Movie? (b) Should preview counts be capped/paged for a very +high-cardinality field (e.g. `actor` → thousands of proposals) before number allocation? (c) MCP: expose +preview as read (POST-but-non-mutating) vs. write — recommend read. + +--- + +## 9. Phased delivery plan + +**Phase 1 — Backend enumeration + generic generation + API (no SPA, no weights).** +`AutoTuneGroupBy` + `AutoTuneMediaType` (Core), `AutoTuneFieldEnumerator` with the joined-table + +denormalized + derived strategies, `AutoTuneAxisMap` generalized (axis overloads become wrappers), the +additive request/response DTO fields, `GET …/auto-tune/fields`, characterization + parity tests, OpenAPI +regen + doc updates + a `decisions.md` record (`sched.auto-tune-arbitrary-field`, supersedes/extends +`sched.auto-tune-foundation`). Field-based channels are single-SmartCollection only; `Sources` on a +field-based channel → 422 (open Q 8.1). **Shippable and testable via curl/MCP without any UI.** + +**Phase 2 — SPA field-picker.** Replace the 3-axis picker with a field + media-type selector sourced +from `GET …/auto-tune/fields`, reusing the RuleBuilder's field-catalog UI patterns +(`web/src/builder/rules/fieldCatalog.ts`); DetailPanel/members wired for field-based proposals per +`spa.autotune-detailpanel-slideover`. Update `docs/spa-conventions.md`. + +**Phase 3 — MCP tools.** `ersatztv_list_search_fields`, `ersatztv_list_auto_tune_fields`, +`ersatztv_get_search_field_values`, `ersatztv_preview_auto_tune` (read), `ersatztv_create_auto_tuned_channels` +(write-gated) in `ToolCatalog.cs`; update `docs/mcp.md`. + +**Phase 4 (follow-up, separate issue) — generalized per-source weighting** for field-based channels, +once a generic "source + discriminator" model is designed (open Q 8.1). + +--- + +## 10. Decision-record stub (for `docs/decisions.md` when Phase 1 lands) + +``` +key: sched.auto-tune-arbitrary-field +status: proposed +since: 2026-07-23 +supersedes: (extends) sched.auto-tune-foundation +summary: Auto-Tune generalizes from the fixed 3-axis enum to an arbitrary (field, mediaType) group-by + keyed on the shared SearchFieldCatalog vocabulary. Distinct-value+count enumeration is DB-sourced + (extended #434 GetSource), NOT Lucene faceting (ISearchIndex has no facet API; analyzed text fields + store tokens not whole values). Membership queries are generic `type:M AND field:"value"` reusing the + RuleBuilder grammar; derived fields (decade) carry their own enumerate/query/name strategy via an + Auto-Tune extension field list. The legacy AutoTuneAxis path is deprecated-in-place (additive-only), + resolving to a group-by internally. Per-source weights (#425) stay on the axis path in v1. +``` diff --git a/web/src/builder/ChannelBuilder.test.tsx b/web/src/builder/ChannelBuilder.test.tsx index 97daca0a7..790f65021 100644 --- a/web/src/builder/ChannelBuilder.test.tsx +++ b/web/src/builder/ChannelBuilder.test.tsx @@ -177,6 +177,17 @@ function mockBuilderApi({ return Promise.resolve(jsonResponse([])); } + // Rule-builder field catalog (SmartCollectionDialog → useSearchFields). + if (path === '/api/v1/search/fields') { + return Promise.resolve(jsonResponse([{ name: 'genre', label: 'Genre', type: 'text', group: 'Metadata', values: [] }])); + } + + // Inline "new smart query" persistence (#437): echo the posted name/query with an id. + if (path === '/api/v1/smart-collections' && (init?.method ?? 'GET') === 'POST') { + const posted = JSON.parse(init?.body as string) as { name: string; query: string }; + return Promise.resolve(jsonResponse({ id: 42, name: posted.name, query: posted.query }, 201)); + } + if (path === '/api/v1/artwork/uploads') { if (artworkUploadFailure) { return Promise.resolve(new Response(null, { status: artworkUploadFailure.status })); @@ -826,6 +837,47 @@ describe('Channel Builder (#89)', () => { expect(lineup[0].playlistId).toBeUndefined(); }); + it('authors an inline smart query, persists it, and adds the created smart collection to the lineup (#437)', async () => { + mockBuilderApi({ ...builderDefaults(), browseItems: [browseItem()] }); + + const { container } = await renderBuilder(); + + // The "New smart query" affordance lives in the Collections source. + fireEvent.click(screen.getByRole('button', { name: 'Collections' })); + fireEvent.click(await screen.findByRole('button', { name: 'New smart query' })); + + // Author the query as raw text (Advanced mode), scoped to the dialog. + const dialog = within(await screen.findByRole('dialog')); + fireEvent.click(dialog.getByRole('button', { name: 'Advanced' })); + fireEvent.change(dialog.getByLabelText('Name'), { target: { value: 'Action Picks' } }); + fireEvent.change(dialog.getByLabelText('Search query'), { target: { value: 'genre:"Action"' } }); + fireEvent.click(dialog.getByRole('button', { name: 'Create' })); + + // The dialog closes and the created smart collection is now a lineup row. + await waitFor(() => expect(screen.queryByRole('dialog')).not.toBeInTheDocument()); + expect(container.querySelector('.ctv-builder-summary')?.textContent).toContain('1 in lineup'); + expect(screen.getByText('Action Picks', { selector: '.ctv-builder-row-title' })).toBeInTheDocument(); + + // It was persisted with the authored name + query. + const smartBody = requestBodyFor('/api/v1/smart-collections'); + expect(smartBody.name).toBe('Action Picks'); + expect(smartBody.query).toBe('genre:"Action"'); + + // Creating the channel sends the smart collection by its typed id only. + fireEvent.change(screen.getByLabelText('Channel name'), { target: { value: 'Action' } }); + fireEvent.click(createBtn()); + await waitFor(() => expect(window.location.pathname).toBe('/app/channels')); + + const lineup = requestBodyFor('/api/v1/channels/from-lineup').lineup as Array>; + expect(lineup).toHaveLength(1); + expect(lineup[0].mediaType).toBe('SmartCollection'); + expect(lineup[0].smartCollectionId).toBe(42); + // The other typed-id buckets are not populated (null ≡ absent; the backend keys off + // the single populated smartCollectionId). + expect(lineup[0].collectionId).toBeNull(); + expect(lineup[0].mediaItemId).toBeNull(); + }); + it('renders the builder under the cool and dual design themes', async () => { mockBuilderApi({ ...builderDefaults(), browseItems: [browseItem()] }); diff --git a/web/src/builder/ChannelBuilder.tsx b/web/src/builder/ChannelBuilder.tsx index fc856b1e4..1d50dbee8 100644 --- a/web/src/builder/ChannelBuilder.tsx +++ b/web/src/builder/ChannelBuilder.tsx @@ -31,6 +31,7 @@ import { Search, Shuffle, SlidersHorizontal, + Sparkles, SquarePen, X } from 'lucide-react'; @@ -40,6 +41,7 @@ import { ApiError, createChannelFromLineup, createChannelTemplate, + createSmartCollection, getChannelTemplates, getChannels, getDefaultChannelTemplate, @@ -105,6 +107,7 @@ import { type SubtitleMode, type TranscodeMode } from './advancedOptions'; +import { SmartCollectionDialog } from './SmartCollectionDialog'; // Advanced-options model (enum unions, INHERIT/omit semantics, the override hook) // is shared with the Auto-Tune DetailPanel — see ./advancedOptions. @@ -723,6 +726,13 @@ function ChannelBuilder({ // Show whose seasons are being browsed in the drill-in dialog (issue #180). const [seasonsShow, setSeasonsShow] = useState(null); + // Inline "new smart query" authoring (#437): the shared SmartCollectionDialog persists the + // authored query as a real SmartCollection (the lineup references it by smartCollectionId), then + // it is added to the lineup like any browsed collection. + const [smartOpen, setSmartOpen] = useState(false); + const [smartBusy, setSmartBusy] = useState(false); + const [smartError, setSmartError] = useState(null); + // debounce search input -> query useEffect(() => { const timer = window.setTimeout(() => setQuery(searchInput.trim()), 280); @@ -814,6 +824,43 @@ function ChannelBuilder({ setLineup((current) => (current.some((existing) => lineupKey(existing) === lineupKey(item)) ? current : [...current, item])); }; + // Create the authored query as a SmartCollection, then add it to the lineup as a + // SmartCollection browse item. The constructed item mirrors exactly what the library-browse + // endpoint returns for a smart collection (id = smartCollectionId, kind "Smart"; see + // GetLibraryBrowseItemsHandler.AppendSmartCollections), so lineupKey and the create-request + // mapping treat it identically to a browsed one — no refetch needed. + const handleCreateSmart = (values: { name: string; query: string }) => { + if (smartBusy) { + return; + } + setSmartBusy(true); + setSmartError(null); + createSmartCollection(values) + .then((created) => { + addItem({ + id: created.id, + mediaType: 'SmartCollection', + title: created.name, + libraryId: null, + libraryName: null, + artwork: '', + duration: null, + itemCount: null, + collectionKind: 'Smart', + collectionType: 'SmartCollection', + collectionId: null, + multiCollectionId: null, + smartCollectionId: created.id, + rerunCollectionId: null, + mediaItemId: null, + playlistId: null + }); + setSmartOpen(false); + }) + .catch((error: unknown) => setSmartError(messageFromError(error))) + .finally(() => setSmartBusy(false)); + }; + const removeAt = (index: number) => { clearLineupError(); setLineup((current) => current.filter((_, position) => position !== index)); @@ -1168,6 +1215,21 @@ function ChannelBuilder({ ))} )} + {source === 'collections' && ( +
+ +
+ )}
@@ -1631,6 +1693,16 @@ function ChannelBuilder({ /> )} + setSmartOpen(false)} + onSubmit={handleCreateSmart} + open={smartOpen} + /> + void; + onSubmit: (values: { name: string; query: string }) => void; + open: boolean; +}) { + // Parent remounts this via `key` on each open, so `initial` seeds fresh state. + const [name, setName] = useState(initial?.name ?? ''); + const [query, setQuery] = useState(initial?.query ?? ''); + const [preview, setPreview] = useState<{ count: number; sample: LibraryBrowseItem[] } | null>(null); + const [previewing, setPreviewing] = useState(false); + const [previewError, setPreviewError] = useState(null); + + const { fields, fieldTypes, status: fieldsStatus } = useSearchFields(); + const [mode, setMode] = useState<'builder' | 'advanced'>(() => + initial?.query && !parse(initial.query, fieldTypes) ? 'advanced' : 'builder' + ); + const [group, setGroup] = useState( + () => parse(initial?.query ?? '', fieldTypes) ?? { match: 'all', children: [] } + ); + + // `fieldTypes` is empty on first render (catalog still loading), so the useState initializers + // above see it empty and `parse` returns null — the dialog opens in advanced mode until the + // catalog arrives. Re-seed once `fieldsStatus` flips to 'success', using React's documented + // "adjust state during render" pattern (comparing against a previous-render value held in state) + // instead of a `useEffect` — a synchronous `setState` in an effect body trips + // react-hooks/set-state-in-effect, and reading a ref during render trips react-hooks/refs. + const [seededFieldsStatus, setSeededFieldsStatus] = useState(fieldsStatus); + if (fieldsStatus !== seededFieldsStatus) { + setSeededFieldsStatus(fieldsStatus); + if (fieldsStatus === 'success' && initial?.query) { + const parsed = parse(initial.query, fieldTypes); + if (parsed) { + setGroup(parsed); + setQuery(compile(parsed)); + setMode('builder'); + } else { + setMode('advanced'); + } + } + } + + // Builder-mode edits flow through this handler (a React event handler, not an effect) so the + // compiled string is always what `query` — the single value submitted/previewed — holds. + const handleGroupChange = (next: Group) => { + setGroup(next); + // Skip compiling an errored tree — a partial rule can still compile to a non-empty (but + // meaningless) query, which would otherwise satisfy the Save button's non-empty check. + if (!groupHasErrors(next)) { + setQuery(compile(next)); + } + }; + + const runPreview = async () => { + const trimmed = query.trim(); + + if (!trimmed) { + return; + } + + setPreviewing(true); + setPreviewError(null); + + try { + const result = await getLibraryBrowseItems({ pageSize: 24, query: trimmed }); + setPreview({ count: result.totalCount ?? result.page?.length ?? 0, sample: result.page ?? [] }); + } catch (error) { + setPreviewError(messageFromCollectionError(error, 'Unable to preview query')); + } finally { + setPreviewing(false); + } + }; + + const trimmedName = name.trim(); + const trimmedQuery = query.trim(); + const builderUnavailable = query.trim().length > 0 && parse(query, fieldTypes) === null; + const groupInvalid = mode === 'builder' && groupHasErrors(group); + + return ( + + + + + } + onClose={onCancel} + open={open} + title={initial ? 'Edit smart collection' : 'New smart collection'} + width={560} + > + setName(event.target.value)} placeholder="Smart collection name" value={name} /> + +
+ + +
+ + {mode === 'builder' ? ( + fieldsStatus === 'success' ? ( + + ) : ( + + ) + ) : ( +
+ setQuery(event.target.value)} + placeholder='e.g. genre:"action" AND released:2000-2010' + style={{ fontFamily: 'var(--font-mono)' }} + value={query} + /> + {parse(query, fieldTypes) === null && query.trim().length > 0 && ( + This query is too advanced to show in the builder. + )} +
+ )} + +
+ +
+ {previewError && ( + + {previewError} + + )} + {preview && ( +
+
+ {preview.count} matches +
+
    + {preview.sample.slice(0, 12).map((item) => ( +
  • + {item.title} + {TYPE_LABEL[item.mediaType]} +
  • + ))} + {preview.sample.length === 0 &&
  • No matches
  • } +
+
+ )} + {error && ( + + {error} + + )} +
+ ); +} diff --git a/web/src/screens/CollectionsScreen.tsx b/web/src/screens/CollectionsScreen.tsx index 01eac32dc..8b726e1f4 100644 --- a/web/src/screens/CollectionsScreen.tsx +++ b/web/src/screens/CollectionsScreen.tsx @@ -48,12 +48,7 @@ import { type SmartCollection } from '../api'; import { TYPE_LABEL } from '../media/mediaKinds'; -import { compile } from '../builder/rules/compile'; -import { useSearchFields } from '../builder/rules/fieldCatalog'; -import { parse } from '../builder/rules/parse'; -import { RuleBuilder } from '../builder/rules/RuleBuilder'; -import type { Group } from '../builder/rules/types'; -import { groupHasErrors } from '../builder/rules/validation'; +import { SmartCollectionDialog } from '../builder/SmartCollectionDialog'; type Tab = 'manual' | 'smart'; @@ -207,210 +202,6 @@ function NameDialog({ ); } -function SmartDialog({ - busy, - error, - initial, - onCancel, - onSubmit, - open -}: { - busy: boolean; - error: string | null; - initial: { name: string; query: string } | null; - onCancel: () => void; - onSubmit: (values: { name: string; query: string }) => void; - open: boolean; -}) { - // Parent remounts this via `key` on each open, so `initial` seeds fresh state. - const [name, setName] = useState(initial?.name ?? ''); - const [query, setQuery] = useState(initial?.query ?? ''); - const [preview, setPreview] = useState<{ count: number; sample: LibraryBrowseItem[] } | null>(null); - const [previewing, setPreviewing] = useState(false); - const [previewError, setPreviewError] = useState(null); - - const { fields, fieldTypes, status: fieldsStatus } = useSearchFields(); - const [mode, setMode] = useState<'builder' | 'advanced'>(() => - initial?.query && !parse(initial.query, fieldTypes) ? 'advanced' : 'builder' - ); - const [group, setGroup] = useState( - () => parse(initial?.query ?? '', fieldTypes) ?? { match: 'all', children: [] } - ); - - // `fieldTypes` is empty on first render (catalog still loading), so the useState initializers - // above see it empty and `parse` returns null — the dialog opens in advanced mode until the - // catalog arrives. Re-seed once `fieldsStatus` flips to 'success', using React's documented - // "adjust state during render" pattern (comparing against a previous-render value held in state) - // instead of a `useEffect` — a synchronous `setState` in an effect body trips - // react-hooks/set-state-in-effect, and reading a ref during render trips react-hooks/refs. - const [seededFieldsStatus, setSeededFieldsStatus] = useState(fieldsStatus); - if (fieldsStatus !== seededFieldsStatus) { - setSeededFieldsStatus(fieldsStatus); - if (fieldsStatus === 'success' && initial?.query) { - const parsed = parse(initial.query, fieldTypes); - if (parsed) { - setGroup(parsed); - setQuery(compile(parsed)); - setMode('builder'); - } else { - setMode('advanced'); - } - } - } - - // Builder-mode edits flow through this handler (a React event handler, not an effect) so the - // compiled string is always what `query` — the single value submitted/previewed — holds. - const handleGroupChange = (next: Group) => { - setGroup(next); - // Skip compiling an errored tree — a partial rule can still compile to a non-empty (but - // meaningless) query, which would otherwise satisfy the Save button's non-empty check. - if (!groupHasErrors(next)) { - setQuery(compile(next)); - } - }; - - const runPreview = async () => { - const trimmed = query.trim(); - - if (!trimmed) { - return; - } - - setPreviewing(true); - setPreviewError(null); - - try { - const result = await getLibraryBrowseItems({ pageSize: 24, query: trimmed }); - setPreview({ count: result.totalCount ?? result.page?.length ?? 0, sample: result.page ?? [] }); - } catch (error) { - setPreviewError(messageFromCollectionError(error, 'Unable to preview query')); - } finally { - setPreviewing(false); - } - }; - - const trimmedName = name.trim(); - const trimmedQuery = query.trim(); - const builderUnavailable = query.trim().length > 0 && parse(query, fieldTypes) === null; - const groupInvalid = mode === 'builder' && groupHasErrors(group); - - return ( - - - - - } - onClose={onCancel} - open={open} - title={initial ? 'Edit smart collection' : 'New smart collection'} - width={560} - > - setName(event.target.value)} placeholder="Smart collection name" value={name} /> - -
- - -
- - {mode === 'builder' ? ( - fieldsStatus === 'success' ? ( - - ) : ( - - ) - ) : ( -
- setQuery(event.target.value)} - placeholder='e.g. genre:"action" AND released:2000-2010' - style={{ fontFamily: 'var(--font-mono)' }} - value={query} - /> - {parse(query, fieldTypes) === null && query.trim().length > 0 && ( - This query is too advanced to show in the builder. - )} -
- )} - -
- -
- {previewError && ( - - {previewError} - - )} - {preview && ( -
-
- {preview.count} matches -
-
    - {preview.sample.slice(0, 12).map((item) => ( -
  • - {item.title} - {TYPE_LABEL[item.mediaType]} -
  • - ))} - {preview.sample.length === 0 &&
  • No matches
  • } -
-
- )} - {error && ( - - {error} - - )} -
- ); -} - /* ---------- add-items picker ---------- */ function AddItemsDialog({ @@ -1214,7 +1005,7 @@ export function CollectionsScreen() { /> {/* create / edit smart */} -