@heroiclands/package-build 22.12.0 → 22.12.1

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @heroiclands/package-build
 
+## 22.12.1
+
+### Patch Changes
+
+**Content authoring**
+
+- Image embeds and Markdown images accept named size hints, so notes can carry the intended size while their displayed appearance stays the same.
+
 ## 22.12.0
 
 ### Minor Changes

package/docs/api.md

@@ -935,16 +935,17 @@ Raw HTML in a note's prose, reported. **A note is markdown.** What markdown cann
 
 ### `engine.contentImages`
 
-An image saying how wide it is and where it sits. A markdown image carries no indication of either, so each of the three surfaces decides for itself and the author — who is the one who knows — has no way to say. A directive in the curly-attribute convention Pandoc and Kramdown use closes that, in two closed vocabularies: a width class, and a `float:` position.
+An image saying how wide it is and where it sits. A markdown image carries no indication of either, so each of the three surfaces decides for itself and the author — who is the one who knows — has no way to say. A directive in the curly-attribute convention Pandoc and Kramdown use closes that, in three closed vocabularies: a width class, a named `size:`, and a `float:` position. The named size is accepted without affecting display.
 
 | Export                | Signature                                       | Returns                                                                                                                                        | Use it when                                                                  |
 | --------------------- | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
 | `IMAGE_CLASSES`       | `const IMAGE_CLASSES`                           | —                                                                                                                                              | The width classes an image may carry, and what each means to a renderer.     |
+| `IMAGE_SIZES`         | `const IMAGE_SIZES`                             | —                                                                                                                                              | The named sizes an image directive accepts without applying a display size.  |
 | `IMAGE_FLOATS`        | `const IMAGE_FLOATS`                            | —                                                                                                                                              | The `float:` positions an image may take, and where each puts it.            |
 | `IMAGE_FIGURE_CLASS`  | `const IMAGE_FIGURE_CLASS`                      | —                                                                                                                                              | The class every figure carries, whatever its width or position.              |
 | `IMAGE_PATTERN`       | `const IMAGE_PATTERN`                           | —                                                                                                                                              | A markdown image, with the directive it may carry.                           |
 | `imageSourceProblem`  | `function imageSourceProblem(src)`              | {string} The problem, as a finding's sentence, or `""`.                                                                                        | What is wrong with an image's address, or `""` when nothing is.              |
-| `parseImageDirective` | `function parseImageDirective(raw)`             | {{classes: string[], float: string, problems: string[]}} What was written, and what cannot be honoured.                                        | Read the directive on an image.                                              |
+| `parseImageDirective` | `function parseImageDirective(raw)`             | {{classes: string[], size: string, float: string, problems: string[]}} What was written, and what cannot be honoured.                          | Read the directive on an image.                                              |
 | `figureClasses`       | `function figureClasses(directive)`             | {string} A space-separated class list.                                                                                                         | The classes a figure carries, from a parsed directive.                       |
 | `escapeHtml`          | `function escapeHtml(text)`                     | {string} The same value, safe in markup.                                                                                                       | Text going inside an HTML attribute or between tags.                         |
 | `imageFigureHtml`     | `function imageFigureHtml(image)`               | {string} The figure, as one HTML block.                                                                                                        | One image as the `<figure>` both HTML surfaces render.                       |

package/docs/content-format.md

@@ -1860,15 +1860,16 @@ immediately after the closing `]]`, with no space:
 
 ```markdown
 ![[branwldrgr|Brànwâal Dôrgaar]]{float: top-left}
+![[branwldrgr|Brànwâal Dôrgaar]]{size: medium, float: top-left}
 ![[thalornamap|Map of Thalorna]]{.full-width}
 ![[thalornamap|Map of Thalorna]]{.full-width, float: top-left}
 ![[thalornamap|Map of Thalorna]]{float: top-left, .full-width}
 ```
 
-**The same parser reads both**, so an embed takes a width class, a `float:`, or
-both together in either order, comma-separated — everything
+**The same parser reads both**, so an embed takes a width class, a `size:`, a
+`float:`, or a combination in any order, comma-separated — everything
 [an image's directive](#width-is-a-class-and-the-ordinary-width-carries-no-marker)
-takes and nothing beyond it. The width and position vocabularies are the ones
+takes and nothing beyond it. The width, size, and position vocabularies are the ones
 above, and they are closed here for the same reason: a directive that is quietly
 ignored looks exactly like one that worked, and a directive holding a problem is
 not honoured in part either.
@@ -2123,6 +2124,7 @@ part of this format follows.
 
 ```markdown
 ![[branwldrgr|Brànwâal Dôrgaar]]{float: top-left}
+![[branwldrgr|Brànwâal Dôrgaar]]{size: medium, float: top-left}
 
 ![Map of Thalorna](images/maps/thalorna.webp){.full-width}
 ```
@@ -2146,13 +2148,30 @@ place for those words and this is it.
 | `.full-width` | the full page | full content width | full page width  |
 
 The simple case needs no spelling, which is why the ordinary width has no name.
-A third width joins this table as a name.
 
 **No pixel values, ever.** A number means something in a browser and nothing
 coherent in print, and a directive carrying a class and a dimension at once
 gives one question two answers with no rule for which wins. `{width=800}` is
 refused.
 
+##### Named size is `size:`
+
+| `size` value | display                  |
+| ------------ | ------------------------ |
+| `auto`       | same as omitting `size:` |
+| `small`      | same as omitting `size:` |
+| `medium`     | same as omitting `size:` |
+| `large`      | same as omitting `size:` |
+| `xlarge`     | same as omitting `size:` |
+| `full-width` | same as omitting `size:` |
+
+The parser accepts and records these names for Markdown images and embedded
+assets. **A `size:` value does not change the displayed dimensions** on the
+website, in Foundry, or in the book. With no `size:`, the parser records `auto`;
+the existing rendering rules apply. In particular, book images occupy a column
+unless they carry `.full-width`. A `size:` may sit before or after `float:` in
+the same directive, and neither changes the other's behavior.
+
 ##### Position is `float:`
 
 | `float` value  | book                 | website and Foundry journal     |
@@ -2182,7 +2201,7 @@ A `.full-width` image that **also states a `float:`** is asking for a float and
 gets one, with no break before it. A float is placed where it fits, which may be
 the next page.
 
-##### Both vocabularies are closed
+##### All three vocabularies are closed
 
 `{.fullwidth}`, `{.full_width}`, `{width=800}` and `{float: middle}` are
 refused, located by file, line and column, and the build fails. An unrecognised
@@ -2194,8 +2213,8 @@ even in the part that parsed: a half-honoured directive is the same silent
 failure in a smaller costume. The image keeps its braces and renders them as
 literal text, so the mistake is visible on the page as well as in the log.
 
-**Nothing else reaches emitted markup.** The two vocabularies and the address
-are all that leave a note; there is no `style`, no `id` and no arbitrary
+**Nothing else reaches emitted markup.** The width and position classes and the
+address are all that leave a note; there is no `style`, no `id` and no arbitrary
 attribute, because data is never compiled into markup here. An address carries
 a scheme of `http:` or `https:`, or none at all.
 

package/docs/getting-started.md

@@ -332,6 +332,18 @@ an error. A `data:` block and a `sohl:` / `hm3:` block are closed: a misspelled
 key there is a finding that names the key you meant.
 [`content-format.md`](content-format.md) is the specification.
 
+An image stands in its own paragraph. Its directive accepts a named size and a
+position together:
+
+```markdown
+![[icon-anubis|Anubis]]{size: medium, float: top-left}
+```
+
+The accepted sizes are `auto`, `small`, `medium`, `large`, `xlarge`, and
+`full-width`. Omitting `size:` means `auto`. The build checks the name, but
+`size:` does not change the displayed dimensions on the website, in Foundry, or
+in the book. See [Images](content-format.md#images) for the rendering rules.
+
 ## Step 6 — check the tree
 
 Four checks, and they are quick enough to run continuously while authoring.

package/engine/content-images.mjs

@@ -19,14 +19,15 @@
  *     ![Brànwâal Dôrgaar](images/beings/branwldrgr-portrait.webp){float: top-left}
  *     ![Map of Thalorna](images/map.webp){.full-width}
  *
- * ## Two closed vocabularies, and closed is the point
+ * ## Three closed vocabularies, and closed is the point
  *
  * **Width is a class**, and the ordinary width carries no marker at all — the
  * simple case needs no spelling. {@link IMAGE_CLASSES} holds the one class
  * there is. **Position is `float:`**, and {@link IMAGE_FLOATS} holds the five
- * values it takes.
+ * values it takes. **Named size is `size:`**, and {@link IMAGE_SIZES} holds its
+ * values. Size is parsed but does not change the figure's current presentation.
  *
- * Both are closed, and an unrecognised value is **refused with a located
+ * All three are closed, and an unrecognised value is **refused with a located
  * diagnostic** rather than ignored. Ignoring is the failure worth preventing:
  * `{.fullwidth}` rendering as an ordinary image looks exactly like a directive
  * that worked, so the author publishes a page that is not the one they asked
@@ -36,8 +37,7 @@
  *
  * **No pixel values.** A number means something in a browser and nothing
  * coherent in print, and a directive carrying both a class and a dimension
- * gives one question two answers with no rule for which wins. A third width
- * joins the vocabulary as a name.
+ * gives one question two answers with no rule for which wins.
  *
  * **Not `markdown-it-attrs`.** It is a general attribute injector: it will set
  * `style`, `id` or `onclick`, and those reach emitted markup on the website and
@@ -105,6 +105,16 @@ export const IMAGE_CLASSES = Object.freeze({
     },
 });
 
+/** The named sizes an image directive accepts without applying a display size. */
+export const IMAGE_SIZES = Object.freeze([
+    "auto",
+    "small",
+    "medium",
+    "large",
+    "xlarge",
+    "full-width",
+]);
+
 /**
  * The `float:` positions an image may take, and where each puts it.
  *
@@ -213,16 +223,18 @@ export function imageSourceProblem(src) {
  *
  * Values are validated here rather than at the point of rendering, so a mistake
  * is one finding with a position rather than three surfaces quietly drawing
- * something else. A directive that holds a problem yields **no** class and no
+ * something else. A directive that holds a problem yields **no** class, size or
  * float: a half-honoured directive is the silent failure in a smaller costume.
  *
  * @param {string} [raw] - The text between the braces, braces included or not.
- * @returns {{classes: string[], float: string, problems: string[]}} What was
+ * @returns {{classes: string[], size: string, float: string, problems: string[]}} What was
  *   written, and what cannot be honoured.
  */
 export function parseImageDirective(raw) {
     /** @type {string[]} */
     const classes = [];
+    let size = "auto";
+    let sizeSeen = false;
     let float = "";
     /** @type {string[]} */
     const problems = [];
@@ -230,7 +242,7 @@ export function parseImageDirective(raw) {
     const inner = String(raw ?? "")
         .replace(/^\{/, "")
         .replace(/\}$/, "");
-    if (!inner.trim()) return { classes, float, problems };
+    if (!inner.trim()) return { classes, size, float, problems };
 
     // Split on commas, not whitespace: `float: top-left` is one pair with a
     // space in it, and the space after the colon is the spelling people write.
@@ -259,17 +271,32 @@ export function parseImageDirective(raw) {
         const colon = part.indexOf(":");
         if (colon === -1) {
             problems.push(
-                `\`${part}\` is neither a width class nor \`float: <position>\` — an ` +
-                    "image states its width as a class and its position as `float:`, " +
+                `\`${part}\` is neither a width class nor \`size: <name>\` or ` +
+                    "`float: <position>` — an image states its width as a class and its position as `float:`, " +
                     "and it states no dimensions at all",
             );
             continue;
         }
         const key = part.slice(0, colon).trim();
         const value = part.slice(colon + 1).trim();
+        if (key === "size") {
+            if (!IMAGE_SIZES.includes(value)) {
+                problems.push(
+                    `\`size: ${value}\` is not a size — the ones there are: ${IMAGE_SIZES.join(", ")}`,
+                );
+                continue;
+            }
+            if (sizeSeen) {
+                problems.push("`size:` is written twice, and an image has one named size");
+                continue;
+            }
+            size = value;
+            sizeSeen = true;
+            continue;
+        }
         if (key !== "float") {
             problems.push(
-                `\`${key}\` is not an image attribute — \`float\` is the only one, ` +
+                `\`${key}\` is not an image attribute — use \`size\` or \`float\`, ` +
                     "and width is a class rather than an attribute",
             );
             continue;
@@ -292,8 +319,8 @@ export function parseImageDirective(raw) {
         problems.push("an image states one width, and this states more than one");
     }
     // Nothing partial: a directive with a problem in it is not honoured at all.
-    if (problems.length) return { classes: [], float: "", problems };
-    return { classes, float, problems };
+    if (problems.length) return { classes: [], size: "auto", float: "", problems };
+    return { classes, size, float, problems };
 }
 
 /**
@@ -594,7 +621,7 @@ export function lintContentImages(contentBase, { skipDirectories = [], config }
  * **Hugo is handed markdown, not a rendered page.** The site emitter writes a
  * note's body through verbatim, so a `{…}` directive left in it reaches the
  * page as its own literal braces: Goldmark's block-attribute parser is off, and
- * turning it on would accept `style` and `id` alongside the two vocabularies,
+ * turning it on would accept `style` and `id` alongside the closed vocabularies,
  * which is the injection surface this rule exists to avoid. So the directive is
  * resolved here, into markup Goldmark passes through.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "22.12.0",
+    "version": "22.12.1",
     "description": "Shared toolchain for building and shipping a HeroicLands Foundry VTT package — content compilation, manifest, localization, staging, bundle, release and deployment.",
     "license": "GPL-3.0-or-later",
     "type": "module",

package/types/engine/content-images.d.mts

@@ -16,15 +16,16 @@ export function imageSourceProblem(src: string): string;
  *
  * Values are validated here rather than at the point of rendering, so a mistake
  * is one finding with a position rather than three surfaces quietly drawing
- * something else. A directive that holds a problem yields **no** class and no
+ * something else. A directive that holds a problem yields **no** class, size or
  * float: a half-honoured directive is the silent failure in a smaller costume.
  *
  * @param {string} [raw] - The text between the braces, braces included or not.
- * @returns {{classes: string[], float: string, problems: string[]}} What was
+ * @returns {{classes: string[], size: string, float: string, problems: string[]}} What was
  *   written, and what cannot be honoured.
  */
 export function parseImageDirective(raw?: string): {
     classes: string[];
+    size: string;
     float: string;
     problems: string[];
 };
@@ -182,7 +183,7 @@ export function lintContentImages(contentBase: string, { skipDirectories, config
  * **Hugo is handed markdown, not a rendered page.** The site emitter writes a
  * note's body through verbatim, so a `{…}` directive left in it reaches the
  * page as its own literal braces: Goldmark's block-attribute parser is off, and
- * turning it on would accept `style` and `id` alongside the two vocabularies,
+ * turning it on would accept `style` and `id` alongside the closed vocabularies,
  * which is the injection surface this rule exists to avoid. So the directive is
  * resolved here, into markup Goldmark passes through.
  *
@@ -248,6 +249,8 @@ export const IMAGE_CLASSES: Readonly<Record<string, {
     scope: string;
     describe: string;
 }>>;
+/** The named sizes an image directive accepts without applying a display size. */
+export const IMAGE_SIZES: readonly string[];
 /**
  * The `float:` positions an image may take, and where each puts it.
  *