@jxsuite/parser 4.1.2 → 4.3.0

package/src/content-rules.ts

@@ -1,6 +1,8 @@
 /**
- * Content rules — the two declarative filters a content type can carry: `exclude` (which files are
- * never read) and `where` (which entries are kept once their frontmatter is known).
+ * Content rules — the declarative filters a content type can carry: `exclude` (which files are
+ * never read), here, and `where` and `hold` (what is kept once frontmatter is known), which live in
+ * `@jxsuite/schema/content-query` because Studio has to answer them too and a core package may not
+ * import an extension.
  *
  * Both are **data, never code**. A `project.json` is read by Studio, by the dev server and by CI,
  * so a filter that needed `eval` or a function would make every one of those a place that executes
@@ -16,8 +18,10 @@
  * @docs framework/site/content-collections
  */
 
-import { isBoolean, isNumber, isString } from "@jxsuite/schema/guards";
-import type { ContentFieldValue, ContentLoaderEntry, JsonValue } from "@jxsuite/schema/types";
+import { isString } from "@jxsuite/schema/guards";
+
+export { compileHold, compileWhere, readField } from "@jxsuite/schema/content-query";
+export type { HoldPredicate, HoldRule, WherePredicate } from "@jxsuite/schema/content-query";
 
 // ─── exclude: globs relative to the source root ─────────────────────────────
 
@@ -267,219 +271,3 @@ export function compileExclude(patterns?: readonly string[]): ExcludeMatcher {
     excludedBy: (path) => files.find((f) => f.re.test(path))?.pattern,
   };
 }
-
-// ─── where: a declarative frontmatter filter ────────────────────────────────
-
-/** An entry's frontmatter as a filter reads it: field name → value, absent when it is not set. */
-type FieldData = ContentLoaderEntry["data"];
-
-/** A field value, or an operand, in the form a filter compares; `undefined` is a missing field. */
-type FieldValue = ContentFieldValue | undefined;
-
-/** Whether an entry's frontmatter passes a compiled `where`. */
-export interface WherePredicate {
-  (data: FieldData): boolean;
-  /**
-   * The first field whose condition `data` fails, for a message that says why an entry was left
-   * out.
-   */
-  why: (data: FieldData) => string | undefined;
-}
-
-/** The query operators. Closed on purpose: see the module comment. */
-const OPERATORS = new Set(["$eq", "$ne", "$in", "$nin", "$exists", "$gt", "$gte", "$lt", "$lte"]);
-
-function isPlainObject(value: FieldValue | FieldData): value is FieldData {
-  return (
-    typeof value === "object" && value !== null && !Array.isArray(value) && !(value instanceof Date)
-  );
-}
-
-/** A frontmatter value in the form a filter compares: YAML dates become RFC 3339 text. */
-function comparable(value: FieldValue): FieldValue {
-  if (value instanceof Date) {
-    if (Number.isNaN(value.getTime())) {
-      return undefined;
-    }
-    const iso = value.toISOString();
-    return iso.endsWith("T00:00:00.000Z") ? iso.slice(0, 10) : iso.replace(/\.\d{3}Z$/, "Z");
-  }
-  return value;
-}
-
-function deepEqual(a: FieldValue, b: FieldValue): boolean {
-  if (a === b) {
-    return true;
-  }
-  if (Array.isArray(a) && Array.isArray(b)) {
-    return (
-      a.length === b.length && a.every((item, i) => deepEqual(comparable(item), comparable(b[i])))
-    );
-  }
-  if (isPlainObject(a) && isPlainObject(b)) {
-    const keys = Object.keys(a);
-    return (
-      keys.length === Object.keys(b).length &&
-      keys.every((key) => key in b && deepEqual(comparable(a[key]), comparable(b[key])))
-    );
-  }
-  return false;
-}
-
-/**
- * Equality, with one convenience that earns its keep: a scalar matches an array field that CONTAINS
- * it, so `{"tags": "frappe"}` selects every entry tagged frappe without a second operator. An array
- * or object operand compares as a whole value.
- */
-function sameValue(actual: FieldValue, expected: JsonValue | undefined): boolean {
-  const a = comparable(actual);
-  if (Array.isArray(expected) || isPlainObject(expected)) {
-    return deepEqual(a, expected);
-  }
-  if (Array.isArray(a)) {
-    return a.some((item) => comparable(item) === expected);
-  }
-  return a === expected;
-}
-
-/** Read a frontmatter field: a literal key first, then a dotted path into nested data. */
-export function readField(data: FieldData, key: string): FieldValue {
-  // Own properties only: `constructor` and `toString` are not frontmatter, whatever `in` says.
-  if (Object.hasOwn(data, key)) {
-    return data[key];
-  }
-  if (!key.includes(".")) {
-    return undefined;
-  }
-  return readPath(data, key.split("."));
-}
-
-/** Follow a dotted path's parts through nested objects, own properties only like {@link readField}. */
-function readPath(holder: FieldValue | FieldData, [part, ...rest]: readonly string[]): FieldValue {
-  if (part === undefined || !isPlainObject(holder) || !Object.hasOwn(holder, part)) {
-    return undefined;
-  }
-  const value = holder[part];
-  return rest.length === 0 ? value : readPath(value, rest);
-}
-
-/** Order two comparable values; undefined when they are not the same kind of thing. */
-function order(actual: FieldValue, operand: string | number): number | undefined {
-  const a = comparable(actual);
-  if (isNumber(a) && isNumber(operand)) {
-    return a - operand;
-  }
-  if (isString(a) && isString(operand)) {
-    return a < operand ? -1 : a > operand ? 1 : 0;
-  }
-  return undefined;
-}
-
-type FieldTest = (actual: FieldValue) => boolean;
-
-function operatorTest(where: string, op: string, operand: JsonValue | undefined): FieldTest {
-  switch (op) {
-    case "$eq": {
-      return (actual) => sameValue(actual, operand);
-    }
-    case "$ne": {
-      return (actual) => !sameValue(actual, operand);
-    }
-    case "$in":
-    case "$nin": {
-      if (!Array.isArray(operand)) {
-        throw new TypeError(`${where}.${op}: expected an array, got ${JSON.stringify(operand)}`);
-      }
-      const hit: FieldTest = (actual) => operand.some((candidate) => sameValue(actual, candidate));
-      return op === "$in" ? hit : (actual) => !hit(actual);
-    }
-    case "$exists": {
-      if (!isBoolean(operand)) {
-        throw new TypeError(
-          `${where}.$exists: expected true or false, got ${JSON.stringify(operand)}`,
-        );
-      }
-      // An empty YAML key is null, and "set to nothing" is not a value an author means by "exists".
-      return (actual) => (actual !== undefined && actual !== null) === operand;
-    }
-    default: {
-      if (!isString(operand) && !isNumber(operand)) {
-        throw new TypeError(
-          `${where}.${op}: expected a string or number, got ${JSON.stringify(operand)}`,
-        );
-      }
-      const test = (diff: number) =>
-        op === "$gt" ? diff > 0 : op === "$gte" ? diff >= 0 : op === "$lt" ? diff < 0 : diff <= 0;
-      return (actual) => {
-        const diff = order(actual, operand);
-        return diff !== undefined && test(diff);
-      };
-    }
-  }
-}
-
-/** A condition object is an operator set when every key is `$`-prefixed. */
-function operatorKeys(condition: FieldData): string[] | null {
-  const keys = Object.keys(condition);
-  const dollars = keys.filter((key) => key.startsWith("$"));
-  if (dollars.length === 0) {
-    return null;
-  }
-  return dollars.length === keys.length ? keys : [];
-}
-
-function compileCondition(key: string, condition: JsonValue): FieldTest {
-  const where = `where.${key}`;
-  if (!isPlainObject(condition)) {
-    return (actual) => sameValue(actual, condition);
-  }
-  const ops = operatorKeys(condition);
-  if (ops === null) {
-    // A plain object with no operators is a literal value to compare whole.
-    return (actual) => deepEqual(comparable(actual), condition);
-  }
-  if (ops.length === 0) {
-    throw new TypeError(`${where}: cannot mix $operators with plain keys in one condition`);
-  }
-  const tests = ops.map((op) => {
-    if (!OPERATORS.has(op)) {
-      throw new TypeError(`${where}: unknown operator "${op}" (use ${[...OPERATORS].join(", ")})`);
-    }
-    return operatorTest(where, op, condition[op]);
-  });
-  return (actual) => tests.every((test) => test(actual));
-}
-
-/**
- * Compile a `where` filter into a predicate over an entry's frontmatter.
- *
- * Every key is a frontmatter field (a dotted path reaches into nested data), keys combine with AND,
- * and a value is either a literal to equal or an operator object (`$eq`, `$ne`, `$in`, `$nin`,
- * `$exists`, `$gt`, `$gte`, `$lt`, `$lte`; several in one object combine with AND too). There is no
- * OR and no evaluation of text: a project that needs "either" splits it into two content types.
- *
- * @param {JsonValue} [where]
- * @returns {WherePredicate}
- */
-export function compileWhere(where?: JsonValue): WherePredicate {
-  if (where === undefined) {
-    return Object.assign(() => true, { why: nothing });
-  }
-  if (!isPlainObject(where)) {
-    throw new TypeError(`"where" must be an object mapping frontmatter fields to conditions`);
-  }
-  const tests = Object.entries(where).map(([key, condition]) => {
-    if (key.startsWith("$")) {
-      throw new TypeError(
-        `where.${key}: top-level operators are not supported, conditions on different fields already combine with AND`,
-      );
-    }
-    return { key, test: compileCondition(key, condition) };
-  });
-  return Object.assign(
-    (data: FieldData) => tests.every(({ key, test }) => test(readField(data, key))),
-    {
-      why: (data: FieldData) => tests.find(({ key, test }) => !test(readField(data, key)))?.key,
-    },
-  );
-}

package/src/content.ts

@@ -6,7 +6,7 @@
  * queryContentType, findEntry) used by both the classes and the server endpoint.
  */
 
-import { isNonNullObject, isRef, isString } from "@jxsuite/schema/guards";
+import { isJsonObject, isNonNullObject, isRef, isString } from "@jxsuite/schema/guards";
 import { localeUrlPrefix, resolveI18n } from "@jxsuite/schema/locale";
 import type {
   ContentFieldValue,
@@ -23,7 +23,7 @@ import type { ContentLoaderEntry } from "./types.ts";
 export interface FilterRule {
   field: string;
   op: string;
-  value?: ContentFieldValue;
+  value?: ContentFieldValue | undefined;
 }
 
 /** One sort key, as `ContentCollection.class.json` declares an item of its `sort` parameter. */
@@ -50,12 +50,27 @@ interface ContentProjectContext {
   config?: ProjectConfig | null;
 }
 
+/** The route and resolved state of the page a class is resolving for. */
+interface DocumentContext {
+  route?: {
+    _pathParams?: Record<string, string>;
+    /** The concrete URL of the page being built (`/kb/frappe/bench-operations`). */
+    urlPattern?: string;
+    /** The language this route serves, when the project declares any (§13.4). */
+    locale?: string | null;
+  };
+  /** The page's state, its earlier class entries already replaced by what they resolved to. */
+  state?: JsonObject;
+}
+
 interface CollectionConfig {
-  contentType?: string;
+  /** One content type, or several whose entries are queried as one list. */
+  contentType?: string | string[];
   filter?: FilterRule[] | JsonObject | null;
   sort?: SortRule | SortRule[] | null;
   limit?: number | null;
   _project?: ContentProjectContext;
+  _document?: DocumentContext;
 }
 
 interface EntryConfig {
@@ -64,15 +79,7 @@ interface EntryConfig {
   id?: JsonValue;
   field?: string;
   _project?: ContentProjectContext;
-  _document?: {
-    route?: {
-      _pathParams?: Record<string, string>;
-      /** The concrete URL of the page being built (`/kb/frappe/bench-operations`). */
-      urlPattern?: string;
-      /** The language this route serves, when the project declares any (§13.4). */
-      locale?: string | null;
-    };
-  };
+  _document?: DocumentContext;
 }
 
 // ─── Query Functions ────────────────────────────────────────────────────────
@@ -85,6 +92,103 @@ function includesValue(
   return items.includes(value);
 }
 
+/**
+ * The value a rule's `field` names on an entry (site-architecture.md §6.4).
+ *
+ * `id` is the entry's id, and a key of the entry's data is that field, a dotted one included. Any
+ * other name with a dot is a path through the data: `terms.category.slug` reads `slug` in each item
+ * of `terms.category`. A path that crosses an array collects what it finds in every item, so its
+ * value is the list of those values (flattened one level, so a list of lists reads as one list),
+ * and `contains` then asks whether any item holds the value. A path that finds nothing is
+ * `undefined`.
+ *
+ * @param {ContentLoaderEntry} entry
+ * @param {string} field
+ * @returns {ContentFieldValue | undefined}
+ */
+export function fieldValue(
+  entry: ContentLoaderEntry,
+  field: string,
+): ContentFieldValue | undefined {
+  if (field === "id") {
+    return entry.id;
+  }
+  if (!field.includes(".") || Object.hasOwn(entry.data, field)) {
+    return entry.data[field];
+  }
+  /* SAFETY: an entry's data is a record of content values, absent keys aside, and only present
+     keys are read from it below. */
+  let found: ContentFieldValue[] = [entry.data as Record<string, ContentFieldValue>];
+  let crossed = false;
+  for (const key of field.split(".")) {
+    const next: ContentFieldValue[] = [];
+    for (const value of found) {
+      const items = Array.isArray(value) ? value : [value];
+      crossed ||= Array.isArray(value);
+      for (const item of items) {
+        if (isNonNullObject(item) && !Array.isArray(item) && Object.hasOwn(item, key)) {
+          /* SAFETY: an own key of a content value object is itself a content value. */
+          next.push((item as Record<string, ContentFieldValue>)[key] as ContentFieldValue);
+        }
+      }
+    }
+    found = next;
+  }
+  if (!crossed) {
+    return found[0];
+  }
+  return found.flatMap((value) => (Array.isArray(value) ? value : [value]));
+}
+
+/**
+ * A rule's value with a reference to the page resolved (site-architecture.md §6.4):
+ * `#/$params/<name>` is the route's parameter, and `#/state/<pointer>` a JSON Pointer into the
+ * page's state as it has resolved so far (an entry declared earlier in `state`). Anything else is
+ * the value as written; a reference that finds nothing is `undefined`.
+ *
+ * @param {ContentFieldValue | undefined} value
+ * @param {DocumentContext | undefined} document
+ * @returns {ContentFieldValue | undefined}
+ */
+export function resolveRuleValue(
+  value: ContentFieldValue | undefined,
+  document: DocumentContext | undefined,
+): ContentFieldValue | undefined {
+  if (!isRef(value)) {
+    return value;
+  }
+  const ref = value.$ref;
+  if (ref.startsWith("#/$params/")) {
+    return document?.route?._pathParams?.[ref.slice("#/$params/".length)];
+  }
+  if (!ref.startsWith("#/state/")) {
+    return value;
+  }
+  let current: JsonValue | undefined = document?.state;
+  for (const token of ref.slice("#/state/".length).split("/")) {
+    const key = token.replaceAll("~1", "/").replaceAll("~0", "~");
+    if (Array.isArray(current) && /^(0|[1-9]\d*)$/.test(key)) {
+      current = current[Number(key)];
+    } else if (isJsonObject(current) && Object.hasOwn(current, key)) {
+      current = current[key];
+    } else {
+      return undefined;
+    }
+  }
+  return current;
+}
+
+/**
+ * The rules a `filter` declares: explicit rules as written, or the `{ field: value }` shorthand as
+ * one `==` rule per key.
+ */
+function filterRules(filter: FilterRule[] | JsonObject): FilterRule[] {
+  if (Array.isArray(filter)) {
+    return filter;
+  }
+  return Object.entries(filter).map(([field, value]) => ({ field, op: "==", value }));
+}
+
 /**
  * Evaluate a single filter rule against an entry.
  *
@@ -93,7 +197,7 @@ function includesValue(
  * @returns {boolean}
  */
 export function evaluateFilterRule(rule: FilterRule, entry: ContentLoaderEntry) {
-  const actual = rule.field === "id" ? entry.id : entry.data[rule.field];
+  const actual = fieldValue(entry, rule.field);
   switch (rule.op) {
     case "==": {
       return actual === rule.value;
@@ -117,6 +221,10 @@ export function evaluateFilterRule(rule: FilterRule, entry: ContentLoaderEntry)
       if (Array.isArray(actual)) {
         return !includesValue(actual, rule.value);
       }
+      // A field with no value contains nothing, so an entry without tags is kept by "not contains".
+      if (actual == null) {
+        return true;
+      }
       return isString(actual) && !actual.includes(String(rule.value ?? ""));
     }
     /*
@@ -158,18 +266,7 @@ export function queryContentType(entries: ContentLoaderEntry[], query: ContentQu
 
   // Filter
   if (query.filter) {
-    let rules: FilterRule[];
-    if (Array.isArray(query.filter)) {
-      rules = query.filter;
-    } else if (isNonNullObject(query.filter)) {
-      rules = Object.entries(query.filter).map(([field, value]) => ({
-        field,
-        op: "==",
-        value,
-      }));
-    } else {
-      rules = [];
-    }
+    const rules = isNonNullObject(query.filter) ? filterRules(query.filter) : [];
     result = result.filter((entry) => rules.every((rule) => evaluateFilterRule(rule, entry)));
   }
 
@@ -178,8 +275,8 @@ export function queryContentType(entries: ContentLoaderEntry[], query: ContentQu
     const sortRules = Array.isArray(query.sort) ? query.sort : [query.sort];
     result.sort((a, b) => {
       for (const { field, order = "asc" } of sortRules) {
-        const aVal = field === "id" ? a.id : (a.data[field] ?? "");
-        const bVal = field === "id" ? b.id : (b.data[field] ?? "");
+        const aVal = fieldValue(a, field) ?? "";
+        const bVal = fieldValue(b, field) ?? "";
         if (aVal < bVal) {
           return order === "asc" ? -1 : 1;
         }
@@ -227,14 +324,23 @@ export class ContentCollection {
   }
 
   async resolve() {
-    const { contentType, filter, sort, limit, _project } = this.config;
-    const entries = await entriesOf(_project?.content, contentType ?? "");
-    if (!entries) {
+    const { contentType, filter, sort, limit, _project, _document } = this.config;
+    /* Several types are one list: each type's entries in turn, then filtered, sorted and cut
+       together, so a sort interleaves them. A type that does not exist adds nothing. */
+    const entries: ContentLoaderEntry[] = [];
+    for (const type of Array.isArray(contentType) ? contentType : [contentType ?? ""]) {
+      entries.push(...((await entriesOf(_project?.content, type)) ?? []));
+    }
+    if (entries.length === 0) {
       return [];
     }
     const query: ContentQuery = {};
-    if (filter != null) {
-      query.filter = filter;
+    if (isNonNullObject(filter)) {
+      query.filter = filterRules(filter).map((rule) => ({
+        field: rule.field,
+        op: rule.op,
+        value: resolveRuleValue(rule.value, _document),
+      }));
     }
     if (sort != null) {
       query.sort = sort;

package/src/serialize.ts

@@ -27,6 +27,7 @@ import {
   isNumber,
   isRef,
   isString,
+  isTemplateString,
   tagNameCandidates,
 } from "@jxsuite/schema/guards";
 import type { TagNameSlot } from "@jxsuite/schema/guards";
@@ -561,6 +562,10 @@ function normalizeAllowlist(allowlist?: ReadonlySet<string> | string[]): Readonl
 
 /** Check if a Jx element has properties beyond the mdast-compatible ones. */
 function hasJxProps(el: JxElement) {
+  // A computed-children template has no Markdown spelling, so even a `p` needs a directive to hold it.
+  if (isTemplateString(el.children)) {
+    return true;
+  }
   for (const key of Object.keys(el)) {
     if (
       key === "tagName" ||
@@ -923,7 +928,11 @@ function collectDirectiveAttrs(el: JxElement) {
       continue;
     }
     if (key === "children") {
-      if (isJsonObject(value)) {
+      /* An array is the directive's body. A legacy repeater object and a computed-children template
+         (spec.md §8.4) have no body to be, so the attribute is the only place they can survive a
+         save. Dropping the template wrote `::div` for `::div{children="${item.$children ?? []}"}`,
+         and the element lost what it draws with no error anywhere. */
+      if (isJsonObject(value) || isTemplateString(value)) {
         propsObj.children = value;
       }
       continue;

package/src/types.ts

@@ -44,6 +44,11 @@ export interface ContentTypeDef {
   exclude?: string[];
   /** Declarative frontmatter filter: only entries that satisfy it are kept. */
   where?: JsonObject;
+  /**
+   * What keeps an entry out of a production build and shows it to authors (site-architecture.md
+   * §7.6). Any rule matching holds the entry, and the first names why.
+   */
+  hold?: JsonObject[];
   /** Frontmatter field whose value is the entry id (the path-derived id when absent). */
   idField?: string;
   /** Route template giving each entry its URL. */