@escape-game-over/atlas 0.1.12 → 0.1.14

package/docs/client-scripts.md

@@ -112,9 +112,27 @@ than an item that silently never matches.
 | Kind     | State           | Item value      | Matches when                                     | In the URL                      | History |
 | -------- | --------------- | --------------- | ------------------------------------------------ | ------------------------------- | ------- |
 | `text`   | the query       | searchable text | folded query is a substring; empty keeps all     | `?q=…`, dropped if empty        | replace |
-| `choice` | one value, `""` | the item's one  | exact; `""` keeps all                            | `?category=…`, dropped if empty | push    |
+| `choice` | one value, `""` | one, or several | the item holds the chosen one; `""` keeps all    | `?category=…`, dropped if empty | push    |
 | `flag`   | boolean         | boolean         | off keeps all; on keeps only items that carry it | `?featured=1`, absent when off  | push    |
 
+**A `choice` item may hold several values.** The state stays one — the tab strip
+picks one category, the URL carries one — but an item can sit in more than one
+and then answers to any of them:
+
+```ts
+items: [
+    { key: "burgos", values: { category: "city" } },
+    { key: "avila",  values: { category: ["walk", "city"] } },
+]
+```
+
+An escape room is adventure *and* sci-fi; a film is a comedy *and* a drama. This
+is a widening of `choice` rather than a fourth kind, because a kind for it would
+carry the same state, the same parameter, the same `set` semantics and the same
+control, and differ by one operator — two kinds doing one job, which is what the
+`flag` note below refuses. A list whose items each sit in one category writes a
+bare string and is untouched.
+
 **`text` folds both sides** — `NFD`, drop the combining marks, lowercase, trim.
 This is the piece that is missing nearly everywhere, and it is not cosmetic: a
 reader who types `malaga` is otherwise told there is no *Málaga*, and every

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@escape-game-over/atlas",
-    "version": "0.1.12",
+    "version": "0.1.14",
     "type": "module",
     "description": "Typed, data-driven machinery for static multi-locale, multi-deployment Astro sites.",
     "private": false,
@@ -54,7 +54,7 @@
     },
     "devDependencies": {
         "@biomejs/biome": "2.5.12",
-        "@types/node": "26.4.1",
+        "@types/node": "26.5.0",
         "@vitest/coverage-istanbul": "5.0.0",
         "astro": "7.3.1",
         "typescript": "6.0.3",

package/src/astro/filters.ts

@@ -61,7 +61,9 @@
  * The kinds are closed, and deliberately few:
  *
  * - `text` — free entry, folded and substring-matched. The search box.
- * - `choice` — one of a set, or none. Tabs, a `<select>`, a radio group.
+ * - `choice` — one of a set, or none. Tabs, a `<select>`, a radio group. The
+ *   control picks one; an item may hold several and answer to any — see
+ *   `ItemValue`.
  * - `flag` — a narrowing toggle: off matches everything, on keeps only the
  *   items that carry it. "In stock", "Step-free access".
  *
@@ -78,26 +80,58 @@ export type Field =
 export type FieldMap = Readonly<Record<string, Field>>;
 
 /**
- * What one field contributes, on an item and in the state.
+ * What one field contributes, in the state.
  *
- * One type for both roles because per kind they genuinely coincide, though they
- * mean different things: on an item a `text` value is everything that field
- * searches — a name and a blurb joined — while in the state it is what someone
- * typed. A `flag` is what the item is on one side and what was asked for on the
- * other.
+ * Always one value per field, whatever the kind: a `choice` is the one category
+ * asked for, a `text` is what someone typed, a `flag` is whether the toggle is
+ * on. This is what `set` takes and what reaches the address bar.
  */
-export type FieldValue<F extends Field> = F["kind"] extends "flag"
+export type StateValue<F extends Field> = F["kind"] extends "flag"
     ? boolean
     : string;
 
+/**
+ * What one field contributes, on an item.
+ *
+ * The two roles read alike but are not the same, and `choice` is where they part
+ * company. On an item a `text` value is everything that field searches — a name
+ * and a blurb joined — while in the state it is what someone typed; a `flag` is
+ * what the item *is* on one side and what was *asked for* on the other.
+ *
+ * **A `choice` item may hold several values, and then it answers to any of
+ * them.** The asymmetry is the point: an escape room is adventure *and* sci-fi,
+ * a film is a comedy *and* a drama, but the tab strip above them still picks
+ * one, and the URL still carries one. Widened here rather than given a kind of
+ * its own, because a second kind would carry the same state, the same
+ * parameter, the same `set` semantics and the same control, and differ by one
+ * operator — two kinds doing one job, which is exactly what `Field` refuses
+ * when it declines to let `flag` become a tri-state.
+ *
+ * A list whose items each sit in one category writes a bare string and is
+ * untouched by this.
+ */
+export type ItemValue<F extends Field> = F["kind"] extends "flag"
+    ? boolean
+    : F["kind"] extends "choice"
+      ? string | readonly string[]
+      : string;
+
+/**
+ * What one field contributes.
+ *
+ * @deprecated Say which side you are on: `StateValue` or `ItemValue`. This
+ * named both while they were the same type, and is `StateValue` now.
+ */
+export type FieldValue<F extends Field> = StateValue<F>;
+
 /** Every field's value for one item, derived from the field declaration. */
 export type ItemValues<F extends FieldMap> = {
-    readonly [K in keyof F]: FieldValue<F[K]>;
+    readonly [K in keyof F]: ItemValue<F[K]>;
 };
 
 /** What the list is filtered to right now. */
 export type FilterState<F extends FieldMap> = {
-    readonly [K in keyof F]: FieldValue<F[K]>;
+    readonly [K in keyof F]: StateValue<F[K]>;
 };
 
 export interface FilterItem<F extends FieldMap> {
@@ -168,7 +202,7 @@ export interface Filters<F extends FieldMap> {
     readonly matched: ReadonlySet<string>;
     set<K extends keyof F>(
         field: K,
-        value: FieldValue<F[K]>,
+        value: StateValue<F[K]>,
         options?: SetOptions
     ): void;
     /** Clears one field, or all of them. Always a push: clearing is deliberate. */
@@ -268,8 +302,8 @@ export function filters<const F extends FieldMap>(
         haystacks.set(item.key, perField);
     }
 
-    const empty = (name: keyof F & string): FieldValue<F[typeof name]> =>
-        (fields[name]?.kind === "flag" ? false : "") as FieldValue<
+    const empty = (name: keyof F & string): StateValue<F[typeof name]> =>
+        (fields[name]?.kind === "flag" ? false : "") as StateValue<
             F[typeof name]
         >;
 
@@ -323,7 +357,14 @@ export function filters<const F extends FieldMap>(
                 } else if (kind === "choice") {
                     const wanted = state[name] as string;
                     if (wanted === "") continue;
-                    if (item.values[name] !== wanted) {
+                    // An item may sit in several categories while the control
+                    // still picks one — see `ItemValue`. One value is the same
+                    // question asked of a set of one.
+                    const held = item.values[name];
+                    const holds = Array.isArray(held)
+                        ? held.includes(wanted)
+                        : held === wanted;
+                    if (!holds) {
                         hit = false;
                         break;
                     }