@escape-game-over/atlas 0.1.10 → 0.1.12

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@escape-game-over/atlas",
-    "version": "0.1.10",
+    "version": "0.1.12",
     "type": "module",
     "description": "Typed, data-driven machinery for static multi-locale, multi-deployment Astro sites.",
     "private": false,

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 {