@heroiclands/package-build 23.13.0 → 24.0.1

package/engine/site-theme-banner.mjs

@@ -0,0 +1,154 @@
+/*
+ * This file is part of the Song of Heroic Lands (SoHL) system for Foundry VTT.
+ * Copyright (c) 2024-2026 Tom Rodriguez ("Toasty") — <toasty@heroiclands.org>
+ *
+ * This work is licensed under the GNU General Public License v3.0 (GPLv3).
+ * You may copy, modify, and distribute it under the terms of that license.
+ *
+ * For full terms, see the LICENSE.md file in the project root or visit:
+ * https://www.gnu.org/licenses/gpl-3.0.html
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+/**
+ * **A page's banner image.** {@link bannerUrl} turns a note's banner fields into
+ * the address of the hero image, or into `""` when the page has none.
+ *
+ * Resolution, in order:
+ *
+ * 1. `data.banner` — a note's own hero image, which the content build resolved
+ *    from an asset address. It is used as given; a blank one declines an image.
+ * 2. `banner` — a hand-authored page's value. `none` or `false` declines an
+ *    image, a full URL is used as written, and anything else is a fragment
+ *    under `images/`.
+ * 3. `<dir>/<name>.webp` — the default for the page's kind: the banner
+ *    `banner-kinds.yaml` maps its `type` and `subType` to, or its `category`
+ *    for the types the mapping lists as taking theirs from there.
+ * 4. `<dir>/<fallback>` — whenever the name step 2 or 3 picked is not in the
+ *    declared inventory of `banners.yaml`. An asset host cannot be asked
+ *    whether a name exists, so the inventory stands in for the test, and each
+ *    name that misses is reported once.
+ *
+ * The inventory is checked only for a relative path directly inside the banner
+ * directory; an absolute URL, a step 1 address and a fragment elsewhere under
+ * `images/` pass through.
+ *
+ * @module
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import YAML from "yaml";
+
+import { cdnUrl } from "./site-theme-urls.mjs";
+
+/** The directory holding the banner inventory and the kind mapping. */
+export const BANNER_DATA_DIR = path.resolve(
+    path.dirname(fileURLToPath(import.meta.url)),
+    "..",
+    "site-theme",
+    "data",
+);
+
+/** @type {{banners: object, kinds: object}|undefined} */
+let shipped;
+
+/**
+ * The banner data the theme ships.
+ *
+ * @returns {{banners: object, kinds: object}} The inventory and the kind mapping.
+ */
+export function shippedBannerData() {
+    shipped ??= {
+        banners: YAML.parse(fs.readFileSync(path.join(BANNER_DATA_DIR, "banners.yaml"), "utf8")),
+        kinds: YAML.parse(fs.readFileSync(path.join(BANNER_DATA_DIR, "banner-kinds.yaml"), "utf8")),
+    };
+    return shipped;
+}
+
+/** The text of a value as a template prints it, with an unset value as `<nil>`. */
+const printed = (value) => (value === undefined || value === null ? "<nil>" : String(value));
+
+/**
+ * The address of a page's banner.
+ *
+ * @param {object} site - The site: `params.cdnBaseURL` and `basePath`.
+ * @param {object} fields - What the page states.
+ * @param {object} [fields.data] - The page's `data`, read for the resolved `banner`.
+ * @param {unknown} [fields.banner] - The hand-authored `banner` value.
+ * @param {string} [fields.type] - The note `type`.
+ * @param {string} [fields.subType] - The note `subType`.
+ * @param {string} [fields.category] - The page's `category`.
+ * @param {string} [fields.subtype] - The name to default to when no `type` is given.
+ * @param {string} [fields.context] - The page address, named in a report.
+ * @param {object} [options] - Options.
+ * @param {{banners: object, kinds: object}} [options.data] - The inventory and the
+ *   kind mapping. The shipped ones by default.
+ * @param {(finding: {severity: string, message: string, page?: string}) => void} [options.report] -
+ *   Receives each name that misses the inventory, once.
+ * @param {Set<string>} [options.reported] - The names already reported.
+ * @returns {string} The address, or `""` when the page has no banner.
+ */
+export function bannerUrl(site, fields, { data = shippedBannerData(), report, reported } = {}) {
+    const banners = data.banners ?? {};
+    const kinds = data.kinds ?? {};
+    const dir = banners.dir || "images/banners";
+    const fallback = banners.fallback || "default.webp";
+    const available = banners.available ?? [];
+
+    let subtype = fields.subtype ?? "";
+    if (fields.type) {
+        const entry = (kinds.kinds ?? {})[fields.type];
+        if ((kinds.categoryTypes ?? []).includes(fields.type)) {
+            subtype = fields.category || "default";
+        } else if (entry && typeof entry === "object") {
+            subtype = entry[String(fields.subType ?? "").toLowerCase()] || fields.type;
+        } else {
+            subtype = entry || fields.type;
+        }
+    }
+
+    const raw = printed(fields.banner);
+    const declined = raw.toLowerCase() === "none" || raw === "false";
+    const resolved = fields.data ? fields.data.banner : undefined;
+    const fromBuild = resolved !== undefined && resolved !== null;
+
+    let banner = "";
+    let absolute = false;
+    if (fromBuild) {
+        banner = String(resolved);
+        absolute = true;
+    } else if (!declined) {
+        if (fields.banner) {
+            const value = String(fields.banner);
+            banner = `images/${value.replace(/^\//, "")}`;
+            if (/^(?:https?:)?\/\//.test(value)) {
+                banner = value;
+                absolute = true;
+            }
+        } else if (subtype) {
+            banner = `${dir}/${subtype}.webp`;
+        }
+        if (banner && !absolute && path.posix.dirname(banner) === dir) {
+            const name = path.posix.basename(banner, path.posix.extname(banner));
+            if (!available.includes(name)) {
+                if (!reported?.has(name)) {
+                    reported?.add(name);
+                    report?.({
+                        severity: "warning",
+                        page: fields.context || undefined,
+                        message:
+                            `hero-banner: no banner named "${name}" in the shared artwork set; ` +
+                            `falling back to ${dir}/${fallback}. Draw it and add "${name}" to ` +
+                            "data/banners.yaml, or name a hero image with `data.banner`. " +
+                            "Write `data.banner: none` to decline a hero image.",
+                    });
+                }
+                banner = `${dir}/${fallback}`;
+            }
+        }
+    }
+    return banner ? cdnUrl(site, banner) : "";
+}

package/engine/site-theme-urls.mjs

@@ -0,0 +1,125 @@
+/*
+ * This file is part of the Song of Heroic Lands (SoHL) system for Foundry VTT.
+ * Copyright (c) 2024-2026 Tom Rodriguez ("Toasty") — <toasty@heroiclands.org>
+ *
+ * This work is licensed under the GNU General Public License v3.0 (GPLv3).
+ * You may copy, modify, and distribute it under the terms of that license.
+ *
+ * For full terms, see the LICENSE.md file in the project root or visit:
+ * https://www.gnu.org/licenses/gpl-3.0.html
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+/**
+ * **Addresses in the site layouts.** The layouts carry no address of their own:
+ * every URL they write comes from the site's configuration or from a page's
+ * data, and a site served under a path prefix such as `/thalorna/` needs its own
+ * links to carry the prefix without writing it down anywhere.
+ *
+ * | Function | Resolves |
+ * | -------- | -------- |
+ * | {@link relUrl} | a path inside the site, under its base path |
+ * | {@link cdnUrl} | an asset path, against `params.cdnBaseURL` when the site has one |
+ * | {@link siteUrl} | a consumer-supplied link: absolute, a fragment, or a path in the site |
+ * | {@link safeUrl} | a link from data, refused when its scheme could run script |
+ *
+ * @module
+ */
+
+import { slugify } from "./content-slug.mjs";
+
+/** Whether an address names a host: `http://`, `https://` or `//`. */
+export function isAbsoluteUrl(url) {
+    return /^(?:https?:)?\/\//.test(String(url ?? ""));
+}
+
+/**
+ * The path a site is served under, with a leading and a trailing slash.
+ *
+ * @param {object} site - The site; `baseURL` is its address.
+ * @returns {string} `/` for a site at its origin's root, `/thalorna/` for one under a prefix.
+ */
+export function basePath(site) {
+    if (!site.baseURL) return "/";
+    const { pathname } = new URL(site.baseURL, "https://site.invalid");
+    return pathname.endsWith("/") ? pathname : `${pathname}/`;
+}
+
+/**
+ * A path inside the site, under its base path.
+ *
+ * A leading slash is dropped first: it would otherwise read as "from the
+ * origin" and leave the base path off.
+ *
+ * @param {object} site - The site.
+ * @param {string} [target] - The path; empty for the site's root.
+ * @returns {string} The address.
+ */
+export function relUrl(site, target = "") {
+    return `${basePath(site)}${String(target).replace(/^\/+/, "")}`;
+}
+
+/**
+ * An asset path, resolved against the site's asset host.
+ *
+ * An absolute address is returned as written. Otherwise the path is joined onto
+ * `params.cdnBaseURL`, and with none set it is a path inside the site.
+ *
+ * @param {object} site - The site; `params.cdnBaseURL` is the asset root.
+ * @param {string} target - The asset path.
+ * @returns {string} The address.
+ */
+export function cdnUrl(site, target) {
+    if (isAbsoluteUrl(target)) return target;
+    const rel = String(target).replace(/^\/+/, "");
+    const root = site.params?.cdnBaseURL;
+    return root ? `${String(root).replace(/\/+$/, "")}/${rel}` : relUrl(site, rel);
+}
+
+/**
+ * A link a consuming site supplied, resolved against the site it is rendered on.
+ *
+ * An absolute address, a fragment and a query are returned as written; anything
+ * else is a path inside the site.
+ *
+ * @param {object} site - The site.
+ * @param {string} [url] - The link; empty for the site's root.
+ * @returns {string} The address.
+ */
+export function siteUrl(site, url = "") {
+    const value = String(url ?? "");
+    return isAbsoluteUrl(value) || value.startsWith("#") || value.startsWith("?") ?
+            value
+        :   relUrl(site, value);
+}
+
+/** A scheme that can run script or load a document of the page's own origin. */
+const UNSAFE_SCHEME = /^\s*(?:javascript|vbscript|data):/i;
+
+/**
+ * A link from a page's data, with a scheme that could run script refused.
+ *
+ * @param {unknown} url - The link as the data states it.
+ * @returns {string} The link, or `#` when its scheme is not one a reader should follow.
+ */
+export function safeUrl(url) {
+    const value = String(url ?? "");
+    // Control characters and spaces are dropped by a browser inside a scheme.
+    const bare = value.replace(/[\u0000- ]/g, "");
+    return UNSAFE_SCHEME.test(bare) ? "#" : value;
+}
+
+/**
+ * The address of a tag's listing page.
+ *
+ * One function writes it for the link in a page's tag row and for the page the
+ * site build writes, so the two cannot disagree.
+ *
+ * @param {object} site - The site.
+ * @param {string} tag - The tag.
+ * @returns {string} The address.
+ */
+export function tagUrl(site, tag) {
+    return relUrl(site, `tags/${slugify(tag)}/`);
+}