@rse/specbook 1.2.3 → 1.2.4

package/dst/specbook-export-html.js

@@ -122,7 +122,7 @@ const templates = {
     "TocPanelEntries": textframe `
         <ul>
             {% for entry in Entries %}
-            <li><a href="#{{ entry.id }}"><span class="entry"><span class="object-kind"{% if entry.info %} data-info="{{ entry.info }}" data-info-path="{{ entry.infopath }}"{% endif %}>{{ entry.kind }}:</span> <span class="object-name"{% if entry.spec %} data-info-spec="{{ entry.spec }}" data-info-path="{{ entry.specpath }}"{% endif %}>{{ entry.name }}</span></span></a>{{ entry.childs }}</li>
+            <li><a href="#{{ entry.id }}"><span class="entry"><span class="object-kind"{% if entry.info %} data-info="{{ entry.info }}" data-info-path="{{ entry.infopath }}"{% endif %}>{{ entry.kind }}:</span> <span class="object-name"{% if entry.spec %} data-info-spec="{{ entry.spec }}" data-info-path="{{ entry.specpath }}"{% endif %}>{{ entry.name }}</span></span></a>{{ entry.children }}</li>
             {% endfor %}
         </ul>
     `,
@@ -146,7 +146,7 @@ const templates = {
             {{ Object.diagram }}
             {{ Object.properties }}
             {{ Object.description }}
-            {{ Object.childs }}
+            {{ Object.children }}
         </section>
     `,
     /*  <Properties/>  */
@@ -800,7 +800,7 @@ const collectInfo = (nodes, prefix, keys, info) => {
         }
         if (entry.d !== undefined || entry.p !== undefined)
             info[path] = entry;
-        collectInfo(schema.childs ?? [], path, keys, info);
+        collectInfo(schema.children ?? [], path, keys, info);
     }
 };
 /*  inject the description popup maps into their client-side script ("<"
@@ -888,7 +888,7 @@ const collectSpec = (objects, spec) => {
             .trim();
         if (text !== "")
             spec[anchorOf(object)] = scoped(object, () => block(text, true).toString().trim());
-        collectSpec(object.childs, spec);
+        collectSpec(object.children, spec);
     }
 };
 /*  the literal members of an "enum(...)"/"tags(...)" expression, or
@@ -913,7 +913,7 @@ const collectMembers = (nodes, result) => {
                 /*  an invalid expression is the concern of lint  */
             }
         }
-        collectMembers(schema.childs ?? [], result);
+        collectMembers(schema.children ?? [], result);
     }
     return result;
 };
@@ -976,20 +976,20 @@ const effectiveProperties = (object) => {
     order (unknown keys appended in occurrence order), with
     "withUnusedProps" injecting the defined but still unused schema
     properties as additional columns  */
-const tableShape = (childs) => {
-    const used = [...new Set(childs.flatMap((child) => child.properties.map((property) => property.key)))];
-    const schema = schemas?.get(childs[0]);
+const tableShape = (children) => {
+    const used = [...new Set(children.flatMap((child) => child.properties.map((property) => property.key)))];
+    const schema = schemas?.get(children[0]);
     const names = (schema?.props ?? []).map((prop) => prop.name);
     const known = schema?.format?.withUnusedProps === true ?
         names : names.filter((name) => used.includes(name));
     const keys = [...known, ...used.filter((key) => !names.includes(key))];
-    return { keys, desc: childs.some((child) => child.description !== undefined || child.childs.length > 0) };
+    return { keys, desc: children.some((child) => child.description !== undefined || child.children.length > 0) };
 };
-/*  provide the childs of an object taking part in the regular document
+/*  provide the children of an object taking part in the regular document
     flow: a nested title object leaves the flow, as it is rendered as the
     title page instead (a top-level one instead removes its whole artifact)  */
-const flowChilds = (object) => object.childs.filter((child) => !isTitleObject(child));
-/*  decide whether a single-kind group of childs collapses into the
+const flowChildren = (object) => object.children.filter((child) => !isTitleObject(child));
+/*  decide whether a single-kind group of children collapses into the
     concise (tabular) rendering: an explicit "format" type of the kind
     wins, "auto" collapses the deepest level only, and inside an already
     concise rendering context "auto" groups implicitly stay concise, too  */
@@ -997,12 +997,12 @@ const conciseGroup = (group, schemaMap, concise) => {
     const type = schemaMap?.get(group[0])?.format?.type ?? "auto";
     if (type !== "auto")
         return type === "concise";
-    return concise || group.every((child) => child.childs.length === 0);
+    return concise || group.every((child) => child.children.length === 0);
 };
-/*  group the childs of an object by their kind, preserving order  */
-const groupChilds = (childs) => {
+/*  group the children of an object by their kind, preserving order  */
+const groupChildren = (children) => {
     const groups = new Map();
-    for (const child of childs) {
+    for (const child of children) {
         const group = groups.get(child.kind);
         if (group === undefined)
             groups.set(child.kind, [child]);
@@ -1011,21 +1011,21 @@ const groupChilds = (childs) => {
     }
     return [...groups.values()];
 };
-/*  render the childs of an object group-wise by kind: a concise group
+/*  render the children of an object group-wise by kind: a concise group
     as one compact table, a complex group as regular nested object
     renderings  */
-const renderChilds = (object, level, concise) => groupChilds(flowChilds(object)).map((group) => conciseGroup(group, schemas, concise) ?
+const renderChildren = (object, level, concise) => groupChildren(flowChildren(object)).map((group) => conciseGroup(group, schemas, concise) ?
     renderTable(group, maxColumnsOf(group[0])) :
     group.map((child) => renderObject(child, level, concise)).join("")).join("");
 /*  render the description cell of a table row: the description of the
-    object followed by its recursively rendered childs (implicitly or
+    object followed by its recursively rendered children (implicitly or
     explicitly concise groups as nested sub-tables, explicitly complex
     ones as regular nested object renderings pressed into the cell);
     a cell left without any content renders as the absent marker,
     exactly like a property cell of a not given property  */
 const renderCell = (child) => {
     let html = child.description !== undefined ? renderDescription(child.description) : "";
-    html += renderChilds(child, 6, true);
+    html += renderChildren(child, 6, true);
     return html.trim() !== "" ? html : "<span class=\"value-absent\"></span>";
 };
 /*  the pre-rendered diagram of an object as an embeddable block
@@ -1034,27 +1034,27 @@ const diagramOf = (object) => {
     const diagram = diagrams?.get(object);
     return diagram !== undefined ? safe(`<div class="diagram">${diagram}</div>`) : "";
 };
-/*  render a single-kind group of childs into one compact table:
+/*  render a single-kind group of children into one compact table:
     the name first, then the property columns, then the description;
     a group wider than maxColumns, or carrying diagrams, instead chunks
     the property and description cells (and the leading diagram) of
     every object into an embedded per-object table, as a diagram is
     identifiable only under a header of its own, not under the column
     headers of a plain table  */
-const renderTable = (childs, maxColumns) => {
-    const { keys, desc } = tableShape(childs);
-    const diagrammed = childs.some((child) => diagramOf(child) !== "");
+const renderTable = (children, maxColumns) => {
+    const { keys, desc } = tableShape(children);
+    const diagrammed = children.some((child) => diagramOf(child) !== "");
     if (!diagrammed && 1 + keys.length + (desc ? 1 : 0) <= maxColumns)
         return render("Table", { Table: {
-                head: childs[0].kind !== "" ? childs[0].kind : "Name",
-                info: infoKeyOf(childs[0]),
-                infopath: infoPathOf(childs[0], false),
+                head: children[0].kind !== "" ? children[0].kind : "Name",
+                info: infoKeyOf(children[0]),
+                infopath: infoPathOf(children[0], false),
                 keys,
                 desc,
                 /*  under the fixed table layout the description column claims
                     twice the share of a regular column, compressing the others  */
                 width: Math.round(200 / (keys.length + 3)),
-                rows: childs.map((child, i) => scoped(child, () => ({
+                rows: children.map((child, i) => scoped(child, () => ({
                     id: anchorOf(child),
                     paren: child.paren,
                     primary: child.primary,
@@ -1071,11 +1071,11 @@ const renderTable = (childs, maxColumns) => {
         with the last cell spanning the leftover columns of the final row  */
     const size = Math.max(1, maxColumns - 1);
     return render("TableChunked", { Table: {
-            head: childs[0].kind !== "" ? childs[0].kind : "Name",
-            info: infoKeyOf(childs[0]),
-            infopath: infoPathOf(childs[0], false),
+            head: children[0].kind !== "" ? children[0].kind : "Name",
+            info: infoKeyOf(children[0]),
+            infopath: infoPathOf(children[0], false),
             width: Math.round(100 / maxColumns),
-            rows: childs.map((child, i) => scoped(child, () => {
+            rows: children.map((child, i) => scoped(child, () => {
                 const cells = keys.map((key) => ({ key, desc: false, span: 1,
                     value: inlineValue(child.kind, child.properties.find((property) => property.key === key)) }));
                 if (desc)
@@ -1125,7 +1125,7 @@ const renderObject = (object, level, concise) => {
                 safe(render("Properties", { Properties: inlineProperties(object, properties) })) : "",
             description: object.description !== undefined ?
                 safe(renderDescription(object.description)) : "",
-            childs: safe(renderChilds(object, level + 1, concise))
+            children: safe(renderChildren(object, level + 1, concise))
         } }));
 };
 /*  format a timestamp as its calendar date in local time (the
@@ -1167,10 +1167,10 @@ const renderTitlePage = (object, created, modified) => {
 const renderArtifact = (artifact) => render("Artifact", { Artifact: {
         objects: safe(artifact.objects.map((object) => renderObject(object, 1, false)).join(""))
     } });
-/*  provide the childs of an object rendered with headings of their own
+/*  provide the children of an object rendered with headings of their own
     (skipping the child groups collapsing into compact tables), which
     are the ones taking part in the table of contents and its side panel  */
-const headingChilds = (object) => groupChilds(flowChilds(object))
+const headingChildren = (object) => groupChildren(flowChildren(object))
     .filter((group) => !conciseGroup(group, schemas, false))
     .flat();
 /*  flatten the hierarchy of the rendered object headings (exactly like
@@ -1185,7 +1185,7 @@ const tocEntries = (objects, pages) => {
                 info: infoKeyOf(object), infopath: infoPathOf(object, false),
                 spec: infoParents !== null ? id : undefined, specpath: infoPathOf(object),
                 name: inline(object.name), level: Math.min(level, 6), page: pages?.get(id) });
-            collect(headingChilds(object), level + 1);
+            collect(headingChildren(object), level + 1);
         }
     };
     collect(objects, 1);
@@ -1205,7 +1205,7 @@ const renderTocPanel = (objects, title, doc) => {
             spec: infoParents !== null ? anchorOf(object) : undefined,
             specpath: infoPathOf(object),
             name: inline(object.name),
-            childs: safe(entries(headingChilds(object)))
+            children: safe(entries(headingChildren(object)))
         })) });
     return render("TocPanel", { TocPanel: { title, doc, entries: safe(entries(objects)) } });
 };
@@ -1217,7 +1217,7 @@ export const htmlOutline = (specification, config) => {
     const entry = (object) => ({
         title: (object.kind !== "" ? `${object.kind}: ` : "") + plainText(object.name),
         anchor: paths.get(object) ?? object.id,
-        childs: groupChilds(flowChilds(object))
+        children: groupChildren(flowChildren(object))
             .filter((group) => !conciseGroup(group, schemaMap, false))
             .flatMap((group) => group.map(entry))
     });

package/dst/specbook-export-md.js

@@ -39,11 +39,11 @@ const nameSuffixMd = (object) => (object.primary === true ? " (*)" : "") +
     code block, an ordered list, a blockquote, or multiple paragraphs) or
     one carrying a ";", as only a ";"-free description stays a single
     segment on re-parsing instead of splitting off a spurious property  */
-const complexBelowMd = (object) => object.childs.some((child) => child.name.includes(";")
+const complexBelowMd = (object) => object.children.some((child) => child.name.includes(";")
     || (child.description !== undefined
         && /[\n;]/.test(renderDescriptionMd(child.description))) || complexBelowMd(child));
 /*  render an object in the Concise Format as a list item of the
-    given nesting depth, with its childs as nested list items  */
+    given nesting depth, with its children as nested list items  */
 const renderConciseMd = (object, depth = 0) => {
     const indent = " ".repeat(depth * 4);
     const segments = [`${object.kind}: ${object.name}${nameSuffixMd(object)}`];
@@ -62,14 +62,14 @@ const renderConciseMd = (object, depth = 0) => {
         `${indent}-   ${segments.join("; ").replace(/\.?$/, ".")}` :
         `${indent}-   ${segments.join("; ")};`;
     return [item, renderKeyValuesMd(wrapped, `${indent}    `),
-        ...object.childs.map((child) => renderConciseMd(child, depth + 1))]
+        ...object.children.map((child) => renderConciseMd(child, depth + 1))]
         .filter((part) => part !== "").join("\n");
 };
-/*  render an object in the Complex Format (levels 1-3), with childs from
+/*  render an object in the Complex Format (levels 1-3), with children from
     level 4 upwards in the Concise Format -- unless a descendant carries
-    a description no concise item can carry, so all childs (as siblings
+    a description no concise item can carry, so all children (as siblings
     have to share the format) stay in the Complex Format down to heading
-    level 6, the deepest one Markdown knows, below which the childs are
+    level 6, the deepest one Markdown knows, below which the children are
     concise regardless -- and the optionally derived Gradia diagram spec
     embedded as a "gradia" fenced code block below the heading  */
 const renderObjectMd = (object, level, diagrams) => {
@@ -83,12 +83,12 @@ const renderObjectMd = (object, level, diagrams) => {
         parts.push(renderKeyValuesMd(object.properties));
     if (object.description !== undefined)
         parts.push(renderDescriptionMd(object.description));
-    /*  the childs share one format, as a concise item following
+    /*  the children share one format, as a concise item following
         a heading would attach to the heading's object instead  */
     if (level >= 6 || (level >= 3 && !complexBelowMd(object)))
-        parts.push(object.childs.map((child) => renderConciseMd(child)).join("\n"));
+        parts.push(object.children.map((child) => renderConciseMd(child)).join("\n"));
     else
-        parts.push(...object.childs.map((child) => renderObjectMd(child, level + 1, diagrams)));
+        parts.push(...object.children.map((child) => renderObjectMd(child, level + 1, diagrams)));
     return parts.filter((part) => part !== "").join("\n\n");
 };
 /*  render the entire specification into normalized Markdown  */

package/dst/specbook-export-pdf.js

@@ -28,7 +28,7 @@ const anchorPages = async (pdf) => {
 };
 /*  attach a hierarchical PDF outline (the "bookmarks" of the viewer
     side-bar) to a document, resolving the entry anchors against the
-    named destinations and hoisting the childs of an unresolvable entry  */
+    named destinations and hoisting the children of an unresolvable entry  */
 const addOutline = async (doc, entries) => {
     const { PDFName, PDFDict, PDFArray, PDFRef, PDFHexString } = await import("pdf-lib");
     const context = doc.context;
@@ -48,8 +48,8 @@ const addOutline = async (doc, entries) => {
     }
     const resolve = (entries) => entries.flatMap((entry) => {
         const dest = targets.get(entry.anchor);
-        const childs = resolve(entry.childs);
-        return dest !== undefined ? [{ title: entry.title, dest, childs }] : childs;
+        const children = resolve(entry.children);
+        return dest !== undefined ? [{ title: entry.title, dest, children }] : children;
     });
     const items = resolve(entries);
     if (items.length === 0)
@@ -59,16 +59,16 @@ const addOutline = async (doc, entries) => {
     const materialize = (items, parent) => {
         const refs = items.map(() => context.nextRef());
         items.forEach((item, i) => {
-            const childs = item.childs.length > 0 ? materialize(item.childs, refs[i]) : undefined;
+            const children = item.children.length > 0 ? materialize(item.children, refs[i]) : undefined;
             context.assign(refs[i], context.obj({
                 Title: PDFHexString.fromText(item.title),
                 Parent: parent,
                 Prev: i > 0 ? refs[i - 1] : undefined,
                 Next: i < refs.length - 1 ? refs[i + 1] : undefined,
-                First: childs?.first,
-                Last: childs?.last,
+                First: children?.first,
+                Last: children?.last,
                 /*  a negative count keeps the sub-tree initially collapsed  */
-                Count: childs !== undefined ? -item.childs.length : undefined,
+                Count: children !== undefined ? -item.children.length : undefined,
                 Dest: item.dest
             }));
         });

package/dst/specbook-format-schema.d.ts

@@ -14,7 +14,7 @@ export type SchemaObject = {
     diagram?: SchemaDiagram;
     format?: SchemaFormat;
     props?: SchemaProperty[];
-    childs?: SchemaObject[];
+    children?: SchemaObject[];
 };
 export type SchemaAutomaton = {
     nodes: string;

package/dst/specbook-format-schema.js

@@ -17,7 +17,7 @@ const GradiaConfigSchemas = Object.fromEntries(Object.entries(Gradia.config).map
 const SchemaDiagramConfig = v.partial(v.strictObject(GradiaConfigSchemas, (issue) => issue.expected === "never" ? "unknown Gradia rendering option" :
     "expected a map of Gradia rendering options"));
 /*  the Valibot schemas mirroring the types above, with the object
-    kind schema referencing itself lazily for the nested childs  */
+    kind schema referencing itself lazily for the nested children  */
 const SchemaProperty = v.strictObject({
     name: v.string(),
     desc: v.optional(v.string()),
@@ -87,6 +87,6 @@ const SchemaObject = v.strictObject({
     diagram: v.optional(SchemaDiagram),
     format: v.optional(SchemaFormat),
     props: v.optional(v.array(SchemaProperty)),
-    childs: v.optional(v.array(v.lazy(() => SchemaObject)))
+    children: v.optional(v.array(v.lazy(() => SchemaObject)))
 });
 export const Schema = v.pipe(v.array(SchemaObject), v.minLength(1));

package/dst/specbook-format-spec.d.ts

@@ -16,7 +16,7 @@ export type SpecObject = {
     primary?: boolean;
     description?: SpecDescription;
     properties: SpecProperty[];
-    childs: SpecObject[];
+    children: SpecObject[];
 };
 export type SpecDescription = {
     description: string;

package/dst/specbook-format-spec.js

@@ -6,7 +6,7 @@
 import * as v from "valibot";
 /*  ==== Schema ====  */
 /*  the Valibot schemas mirroring the types above, with the object
-    schema referencing itself lazily for the nested childs  */
+    schema referencing itself lazily for the nested children  */
 const SpecProperty = v.object({
     key: v.string(),
     value: v.string(),
@@ -26,7 +26,7 @@ const SpecObject = v.object({
     primary: v.optional(v.boolean()),
     description: v.optional(SpecDescription),
     properties: v.array(SpecProperty),
-    childs: v.array(v.lazy(() => SpecObject))
+    children: v.array(v.lazy(() => SpecObject))
 });
 const SpecArtifact = v.object({
     created: v.date(),

package/dst/specbook-format.md

@@ -78,7 +78,7 @@ type SchemaObject = {
     diagram?:          SchemaDiagram
     format?:           SchemaFormat
     props?:            SchemaProperty[]
-    childs?:           SchemaObject[]
+    children?:         SchemaObject[]
 }
 type SchemaAutomaton = {
     nodes:             string
@@ -251,7 +251,7 @@ type SchemaGradiaConfig = Partial<{
     properties allowed on objects of this kind,
     BECAUSE they carry the structured, machine-checkable content
 
--   `SchemaObject.childs?: SchemaObject[]`:
+-   `SchemaObject.children?: SchemaObject[]`:
     object kinds allowed one level below this object (RECURSION),
     BECAUSE the nesting defines and bounds the document structure
 
@@ -579,7 +579,7 @@ type SpecObject = {
     primary?:          boolean
     description?:      SpecDescription
     properties:        SpecProperty[]
-    childs:            SpecObject[]
+    children:          SpecObject[]
 }
 type SpecDescription = {
     description:       string
@@ -653,7 +653,7 @@ type SpecProperty = {
     key/value properties of the object, in canonical order,
     BECAUSE properties carry the structured, machine-checkable content
 
--   `SpecObject.childs: SpecObject[]`:
+-   `SpecObject.children: SpecObject[]`:
     child objects nested one level below this object (RECURSION),
     BECAUSE a specification is a tree, not a flat list of statements