@escape-game-over/atlas 0.1.10 → 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.10",
+    "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;
                     }

package/src/index.ts

@@ -125,6 +125,9 @@ export {
     breadcrumbList,
     businessId,
     type CatalogEntry,
+    type CreativeWorkInput,
+    type CreativeWorkProperty,
+    creativeWork,
     type FaqEntry,
     faqPage,
     geoCoordinates,
@@ -188,6 +191,8 @@ export {
     formatQuantities,
     type Price,
     type PriceTier,
+    type Quantity,
+    type QuantityRange,
     type TieredPrice,
     tierRange,
 } from "./money.ts";

package/src/jsonld/creative-work.ts

@@ -0,0 +1,125 @@
+import type { Quantity } from "../money.ts";
+import type { HttpsUrl } from "../url.ts";
+import type { BusinessId, OrganizationId } from "./ids.ts";
+import { type JsonLdNode, schemaType } from "./node.ts";
+import { quantitativeValue } from "./quantity.ts";
+
+/**
+ * One measured fact about the work, as `additionalProperty` states one.
+ *
+ * schema.org has a named property for a few of these — `timeRequired` on a
+ * `CreativeWork`, `numberOfPlayers` on a `Game` — and nothing at all for most:
+ * how many puzzles a room holds, how much floor it needs, how hard it is. A
+ * `PropertyValue` is the vocabulary's own answer for exactly that, and using it
+ * for the whole set keeps one list rather than splitting a spec table across
+ * named properties and a leftovers bag by whichever half the vocabulary
+ * happened to name.
+ *
+ * The two unit properties are not alternatives to taste. `unitCode` is the
+ * standard one — a UN/CEFACT Common Code, `MIN` for minutes, `MTK` for square
+ * metres — and is what a consumer reads without parsing anything. `unitText` is
+ * free text, and schema.org states its purpose exactly: for when you *cannot*
+ * provide a standard code. Putting a code in `unitText` publishes `"MIN"` as a
+ * word rather than as a unit, which is the mistake this note exists to stop.
+ *
+ * Both may be given — a code for machines and a symbol for a reader — and
+ * neither need be: a count of puzzles is a number of nothing.
+ *
+ * Neither is checked against the code list, matching `LocalBusinessInput.type`:
+ * lib does not carry a copy of someone else's vocabulary to fall behind it.
+ */
+export interface CreativeWorkProperty {
+    /** In the reader's language: lib does not translate, see `genre`. */
+    readonly name: string;
+    readonly value: Quantity;
+    /**
+     * UN/CEFACT Common Code — `"MIN"`, `"MTK"` — a URL, or `prefix:code` for
+     * another scheme. Two or three alphanumerics, despite schema.org saying
+     * three: the list holds hundreds of two-character codes.
+     */
+    readonly unitCode?: string;
+    /** A symbol a reader sees, e.g. `"m²"`. */
+    readonly unitText?: string;
+}
+
+export interface CreativeWorkInput {
+    readonly name: string;
+    /** This work's own page. */
+    readonly url: HttpsUrl;
+    readonly description?: string;
+    /** A picture of it, absolute. */
+    readonly image?: HttpsUrl;
+    /**
+     * What kind of thing it is, in words a reader would use.
+     *
+     * Already translated. lib holds no catalog and cannot turn a consumer's
+     * internal ids into names — a site passing its own slugs publishes
+     * `"sci-fi"` and `"live-act"` to a crawler, which is a fact about that
+     * site's database rather than about the work.
+     */
+    readonly genre?: readonly string[];
+    /** The `@id` of whoever made it. See `ProductInput.seller`. */
+    readonly creator?: BusinessId | OrganizationId;
+    /**
+     * The spec table, if the work has one.
+     *
+     * Omitted entirely rather than emitted empty when a work has no measured
+     * facts yet — an unbuilt room with a name and a picture. An empty
+     * `additionalProperty` claims a table exists and is blank.
+     */
+    readonly properties?: readonly CreativeWorkProperty[];
+    /** Further types alongside `CreativeWork`. See `ProductInput.alsoA`. */
+    readonly alsoA?: readonly string[];
+}
+
+/**
+ * Something the site made, described but not sold.
+ *
+ * The counterpart to `product`, and the distinction is the price: a `Product`
+ * exists in the graph to carry an `Offer`, so a thing with no price published
+ * as one is a product nobody can buy — an offer with no number is read as
+ * unknown availability rather than as "ask us". A room licensed to operators,
+ * a course, a film: `CreativeWork` says what it is and stops there.
+ *
+ * No `@id`. Nothing in the graph refers to a work — see the note in `ids.ts`
+ * for the test, and for why minting one before something points at it is a
+ * cost rather than a courtesy.
+ *
+ * Reference: <https://schema.org/CreativeWork>
+ */
+export function creativeWork(work: CreativeWorkInput): JsonLdNode {
+    return {
+        "@type": schemaType(["CreativeWork", ...(work.alsoA ?? [])]),
+        name: work.name,
+        url: work.url,
+        ...(work.description === undefined
+            ? {}
+            : { description: work.description }),
+        ...(work.image === undefined ? {} : { image: work.image }),
+        ...(work.genre === undefined || work.genre.length === 0
+            ? {}
+            : { genre: work.genre }),
+        ...(work.creator === undefined
+            ? {}
+            : { creator: { "@id": work.creator } }),
+        ...(work.properties === undefined || work.properties.length === 0
+            ? {}
+            : { additionalProperty: work.properties.map(propertyValue) }),
+    };
+}
+
+function propertyValue(property: CreativeWorkProperty): JsonLdNode {
+    return {
+        "@type": "PropertyValue",
+        name: property.name,
+        value: {
+            ...quantitativeValue(property.value),
+            ...(property.unitCode === undefined
+                ? {}
+                : { unitCode: property.unitCode }),
+            ...(property.unitText === undefined
+                ? {}
+                : { unitText: property.unitText }),
+        },
+    };
+}

package/src/jsonld/index.ts

@@ -32,6 +32,11 @@
 export { type ArticleInput, article } from "./article.ts";
 export { type BreadcrumbStep, breadcrumbList } from "./breadcrumb.ts";
 export { type LocalBusinessInput, localBusiness } from "./business.ts";
+export {
+    type CreativeWorkInput,
+    type CreativeWorkProperty,
+    creativeWork,
+} from "./creative-work.ts";
 export { type FaqEntry, faqPage } from "./faq.ts";
 export {
     type BusinessId,

package/src/jsonld/quantity.ts

@@ -1,6 +1,7 @@
 import {
     isContiguous,
     type PriceTier,
+    type Quantity,
     quantitiesOf,
     quantityRange,
 } from "../money.ts";
@@ -20,9 +21,7 @@ import type { JsonLdNode } from "./node.ts";
  *
  * Reference: <https://schema.org/QuantitativeValue>
  */
-export function quantitativeValue(
-    quantity: number | { readonly min: number; readonly max: number }
-): JsonLdNode {
+export function quantitativeValue(quantity: Quantity): JsonLdNode {
     return typeof quantity === "number"
         ? { "@type": "QuantitativeValue", value: quantity }
         : {

package/src/money.ts

@@ -26,16 +26,32 @@ export interface Price {
     readonly currency: CurrencyCode;
 }
 
+/** A span between two counts, both ends included. */
+export interface QuantityRange {
+    readonly min: number;
+    readonly max: number;
+}
+
 /**
- * What one quantity band costs.
+ * How many of something: an exact count, or a range.
+ *
+ * A scalar for the common case and an object when it genuinely varies, the same
+ * bargain `ThemeColor` strikes — the range alone would make the ordinary case
+ * noisy, and `{ min: 2, max: 2 }` five times over says nothing `2, 3, 4, 5, 6`
+ * does not.
  *
- * `quantity` takes a count or a range, because both occur and the range alone
- * would make the ordinary case noisy: `{ min: 2, max: 2 }` five times over says
- * nothing `2, 3, 4, 5, 6` does not. Same shape as `ThemeColor` — a scalar for
- * the common case, an object when it genuinely varies.
+ * Named here, in the lowest module that needs it, because three unrelated
+ * things measure in it: a price band, a `QuantitativeValue`, and a spec on a
+ * `CreativeWork`. Spelled out at each it is three shapes that happen to match,
+ * and a caller moving a figure between them has to check that they still do.
+ */
+export type Quantity = number | QuantityRange;
+
+/**
+ * What one quantity band costs.
  */
 export interface PriceTier {
-    readonly quantity: number | { readonly min: number; readonly max: number };
+    readonly quantity: Quantity;
     /**
      * What one unit costs at this quantity — not the total for the band.
      *
@@ -70,10 +86,7 @@ export interface TieredPrice {
 }
 
 /** The band a tier covers, with a bare count widened to a range of one. */
-export function tierRange(tier: PriceTier): {
-    readonly min: number;
-    readonly max: number;
-} {
+export function tierRange(tier: PriceTier): QuantityRange {
     return typeof tier.quantity === "number"
         ? { min: tier.quantity, max: tier.quantity }
         : tier.quantity;
@@ -91,10 +104,9 @@ export function tierRange(tier: PriceTier): {
  * a caller wants is `formatQuantities` or `quantitiesFor`, which pick between
  * this and `quantitiesOf` by reading the tiers.
  */
-export function quantityRange(tiers: readonly [PriceTier, ...PriceTier[]]): {
-    readonly min: number;
-    readonly max: number;
-} {
+export function quantityRange(
+    tiers: readonly [PriceTier, ...PriceTier[]]
+): QuantityRange {
     const first = tierRange(tiers[0]);
     const last = tiers.at(-1);
     return {