@bendyline/squisq 1.2.2 → 1.4.0

package/src/jsonForm/pointer.ts

@@ -0,0 +1,109 @@
+/**
+ * JSON Pointer helpers (RFC 6901) plus immutable get/set, plus a tiny
+ * dotted-path normalizer so hosts can write `user.role` instead of
+ * `/user/role`. `$ref` resolution is local-only (`#/$defs/Foo`).
+ */
+
+import type { SquisqAnnotatedSchema } from './types.js';
+
+/** Normalize a path to a JSON Pointer string. Accepts both forms. */
+export function toPointer(path: string): string {
+  if (path === '' || path === '/') return '';
+  if (path.startsWith('/')) return path;
+  // Dotted form: split on `.` and escape per RFC 6901.
+  return (
+    '/' +
+    path
+      .split('.')
+      .map((seg) => seg.replace(/~/g, '~0').replace(/\//g, '~1'))
+      .join('/')
+  );
+}
+
+/** Split a JSON Pointer into decoded segments. Empty string → []. */
+export function pointerSegments(pointer: string): string[] {
+  if (pointer === '') return [];
+  return pointer
+    .slice(1)
+    .split('/')
+    .map((seg) => seg.replace(/~1/g, '/').replace(/~0/g, '~'));
+}
+
+/** Read a value from data by path (dotted or pointer). Returns undefined if missing. */
+export function getByPointer(data: unknown, path: string): unknown {
+  const segments = pointerSegments(toPointer(path));
+  let cur: unknown = data;
+  for (const seg of segments) {
+    if (cur === null || cur === undefined) return undefined;
+    if (Array.isArray(cur)) {
+      const idx = Number(seg);
+      if (!Number.isInteger(idx) || idx < 0 || idx >= cur.length) return undefined;
+      cur = cur[idx];
+    } else if (typeof cur === 'object') {
+      cur = (cur as Record<string, unknown>)[seg];
+    } else {
+      return undefined;
+    }
+  }
+  return cur;
+}
+
+/**
+ * Return a structurally-shared copy of `data` with the value at `path`
+ * replaced. Intermediate objects/arrays are cloned along the path; the
+ * rest is shared by reference. Creates intermediate objects if missing.
+ */
+export function setByPointer<T>(data: T, path: string, value: unknown): T {
+  const segments = pointerSegments(toPointer(path));
+  if (segments.length === 0) return value as T;
+  return setRec(data, segments, 0, value) as T;
+}
+
+function setRec(node: unknown, segments: string[], i: number, value: unknown): unknown {
+  const seg = segments[i];
+  const isLast = i === segments.length - 1;
+
+  // Decide whether the slot we're about to write into is an array index.
+  const nextSeg = isLast ? undefined : segments[i + 1];
+  const writingArrayChild = nextSeg !== undefined && /^\d+$/.test(nextSeg);
+
+  if (Array.isArray(node)) {
+    const idx = Number(seg);
+    const next = node.slice();
+    next[idx] = isLast
+      ? value
+      : setRec(node[idx] ?? (writingArrayChild ? [] : {}), segments, i + 1, value);
+    return next;
+  }
+
+  const obj = (node && typeof node === 'object' ? { ...(node as object) } : {}) as Record<
+    string,
+    unknown
+  >;
+  obj[seg] = isLast
+    ? value
+    : setRec(obj[seg] ?? (writingArrayChild ? [] : {}), segments, i + 1, value);
+  return obj;
+}
+
+/**
+ * Resolve a local `$ref` (e.g. `#/$defs/Foo`) against the root schema.
+ * Returns the original schema if no `$ref` is present, or `undefined`
+ * if the reference cannot be resolved. Cross-document refs are not
+ * supported.
+ */
+export function resolveRef(
+  schema: SquisqAnnotatedSchema,
+  root: SquisqAnnotatedSchema,
+): SquisqAnnotatedSchema | undefined {
+  if (!schema.$ref) return schema;
+  const ref = schema.$ref;
+  if (!ref.startsWith('#/')) return undefined;
+  const segments = pointerSegments(ref.slice(1));
+  let cur: unknown = root;
+  for (const seg of segments) {
+    if (cur === null || cur === undefined || typeof cur !== 'object') return undefined;
+    cur = (cur as Record<string, unknown>)[seg];
+  }
+  return (cur as SquisqAnnotatedSchema | undefined) ?? undefined;
+}

package/src/jsonForm/types.ts

@@ -0,0 +1,167 @@
+/**
+ * JSON Form types — Squisq's hint vocabulary layered on JSON Schema.
+ *
+ * Hints live inline on a JSON Schema under a single `squisq` key. The
+ * schema remains a valid JSON Schema; the extra key is ignored by
+ * standard validators. Renderers consult the hints to pick a control
+ * and tune its presentation.
+ */
+
+/**
+ * Every concrete control rendered by `<JsonView>` and `<JsonEditor>`.
+ *
+ * Auto-defaults pick one based on schema shape; hosts override via
+ * `squisq.control` when they want something specific (e.g. radio over
+ * segmented for a long, descriptive enum).
+ */
+export type ControlKind =
+  | 'text'
+  | 'multiline'
+  | 'richtext'
+  | 'color'
+  | 'date'
+  | 'time'
+  | 'datetime'
+  | 'slider'
+  | 'stepper'
+  | 'segmented'
+  | 'radio'
+  | 'combobox'
+  | 'toggle'
+  | 'checkbox'
+  | 'card'
+  | 'card-stack'
+  | 'chip-bin'
+  | 'tabs'
+  | 'group';
+
+/**
+ * Conditional rule: looked up by field path against the root data and
+ * compared with one of the operators. The first defined operator wins
+ * (in declaration order: equals, oneOf, matches, truthy).
+ */
+export interface SquisqWhen {
+  /**
+   * Path to the controlling field, relative to the root data.
+   * Accepts dotted-path (`user.role`) or JSON Pointer (`/user/role`).
+   */
+  field: string;
+  equals?: unknown;
+  oneOf?: readonly unknown[];
+  /** ECMAScript regex source; matched against the string value. */
+  matches?: string;
+  /** When true, condition holds if value is truthy; when false, if falsy. */
+  truthy?: boolean;
+}
+
+/**
+ * Hints for a single schema node. Attach via `squisq` on any JSON
+ * Schema object — properties, items, the root, or sub-schemas inside
+ * `oneOf`/`anyOf`.
+ */
+export interface SquisqHints {
+  /** Force a specific control. If omitted, picked from type/format/enum cardinality. */
+  control?: ControlKind;
+
+  /** Override schema `title` for display. */
+  label?: string;
+  /** Override schema `description` for the inline helper text. */
+  help?: string;
+  /** Placeholder text for empty fields. */
+  placeholder?: string;
+
+  /** Suggested layout sizing in a parent grid. Renderers may ignore on narrow viewports. */
+  width?: 'full' | 'half' | 'third' | 'auto';
+
+  /** Hide the field — literal, or a `SquisqWhen` evaluated against root data. */
+  hidden?: boolean | SquisqWhen;
+  /** Disable the field — literal, or a `SquisqWhen` evaluated against root data. */
+  disabled?: boolean | SquisqWhen;
+
+  /** Override schema's required-ness for the UI only. */
+  required?: boolean;
+
+  /** For arrays of objects: how to label each card in a `card-stack`. */
+  itemLabel?: string | { fromField: string };
+  /** Label for the "+ Add" button on arrays. */
+  addLabel?: string;
+  /** Label for the remove button on arrays. */
+  removeLabel?: string;
+
+  /** Slider/stepper visual step. Falls back to schema `multipleOf`. */
+  step?: number;
+
+  /** Optional human-readable labels for enum values. */
+  enumLabels?: Record<string, string>;
+}
+
+/**
+ * The subset of JSON Schema we understand, with an optional `squisq`
+ * key. We deliberately keep this as a structural type so any JSON
+ * Schema authored elsewhere can be passed in without conversion.
+ */
+export interface SquisqAnnotatedSchema {
+  type?: string | readonly string[];
+  format?: string;
+  title?: string;
+  description?: string;
+  default?: unknown;
+  examples?: readonly unknown[];
+
+  enum?: readonly unknown[];
+  const?: unknown;
+
+  // Object
+  properties?: Record<string, SquisqAnnotatedSchema>;
+  required?: readonly string[];
+  additionalProperties?: boolean | SquisqAnnotatedSchema;
+
+  // Array
+  items?: SquisqAnnotatedSchema | readonly SquisqAnnotatedSchema[];
+  minItems?: number;
+  maxItems?: number;
+
+  // Number
+  minimum?: number;
+  maximum?: number;
+  exclusiveMinimum?: number;
+  exclusiveMaximum?: number;
+  multipleOf?: number;
+
+  // String
+  minLength?: number;
+  maxLength?: number;
+  pattern?: string;
+
+  // Combinators
+  oneOf?: readonly SquisqAnnotatedSchema[];
+  anyOf?: readonly SquisqAnnotatedSchema[];
+  allOf?: readonly SquisqAnnotatedSchema[];
+
+  // References
+  $ref?: string;
+  $defs?: Record<string, SquisqAnnotatedSchema>;
+  definitions?: Record<string, SquisqAnnotatedSchema>;
+
+  // Squisq-native UI hints
+  squisq?: SquisqHints;
+}
+
+/**
+ * A validation error reported by the consumer-supplied `validate` prop.
+ * Matches the shape of common validators (ajv, etc.) without depending
+ * on any specific one.
+ */
+export interface JsonFormValidationError {
+  /** JSON Pointer to the failing value, e.g. `/sections/0/heading`. */
+  path: string;
+  /** Human-readable message. */
+  message: string;
+  /** Optional schema keyword that failed (e.g. "required", "minimum"). */
+  keyword?: string;
+}
+
+export type JsonFormValidator = (
+  value: unknown,
+  schema: SquisqAnnotatedSchema,
+) => readonly JsonFormValidationError[];

package/src/markdown/convert.ts

@@ -20,8 +20,10 @@ import type {
   MarkdownSourcePosition,
   HeadingTemplateAnnotation,
   MarkdownHeading,
+  MarkdownInlineIcon,
 } from './types.js';
 import { parseHtmlToNodes } from './htmlParse.js';
+import { resolveIcon } from '../icons/resolve.js';
 
 // ============================================
 // Generic mdast node shape
@@ -132,8 +134,13 @@ function extractText(node: MdastNode): string {
 /**
  * Regex matching a trailing `{[templateName key=value …]}` annotation.
  * Captures the content between `{[` and `]}`.
+ *
+ * The trailing `[\s\]\}]*` tolerates accidental doubled `]}` that users
+ * sometimes type when learning the syntax (e.g. `{[foo]}]}`). It does
+ * not allow trailing word characters, so a non-trailing annotation like
+ * `## The {[chart]} section` still doesn't match.
  */
-const TEMPLATE_ANNOTATION_RE = /\s*\{\[([^\]]+)\]\}\s*$/;
+const TEMPLATE_ANNOTATION_RE = /\s*\{\[([^\]]+)\]\}[\s\]}]*$/;
 
 /**
  * Extract a `{[templateName key=value …]}` annotation from a heading's
@@ -247,13 +254,187 @@ function convertBlockChildren(children: MdastNode[], parseHtml: boolean): Markdo
   return result;
 }
 
-function convertInlineChildren(children: MdastNode[], parseHtml: boolean): MarkdownInlineNode[] {
+function convertInlineChildren(
+  children: MdastNode[],
+  parseHtml: boolean,
+  /** When false, skip the inline-icon split. Headings opt out so the
+   *  `extractTemplateAnnotation` pass still sees the trailing
+   *  `{[…]}` in raw text form; the caller runs `splitInlineIcons`
+   *  itself afterward on the remaining children. */
+  applyIconSplit: boolean = true,
+): MarkdownInlineNode[] {
   const result: MarkdownInlineNode[] = [];
   for (const child of children) {
     const node = convertInlineNode(child, parseHtml);
     if (node) result.push(node);
   }
-  return result;
+  const mentioned = coalesceMentions(result);
+  return applyIconSplit ? splitInlineIcons(mentioned) : mentioned;
+}
+
+/**
+ * Walk an inline-children list and split each text node on `{[token]}`
+ * occurrences whose tokens resolve to known FontAwesome icons. Returns
+ * a new array — unresolved tokens are left as literal text so authors
+ * can write `{[notathing]}` verbatim if they really mean to.
+ *
+ * Exposed for the heading code path, which first strips the trailing
+ * template annotation and then runs this on what remains.
+ */
+export function splitInlineIcons(nodes: MarkdownInlineNode[]): MarkdownInlineNode[] {
+  // First pass: reassemble `text + textDirective + text` patterns
+  // formed when a qualified token like `{[fa-solid:user]}` was split
+  // by remark-directive's colon recognition. We collapse those triples
+  // back into a single text node containing the original token so the
+  // regex below can match.
+  const recombined = recombineDirectiveTokens(nodes);
+
+  const out: MarkdownInlineNode[] = [];
+  for (const node of recombined) {
+    if (node.type !== 'text') {
+      out.push(node);
+      continue;
+    }
+    out.push(...splitTextOnIcons(node.value, node.position));
+  }
+  return out;
+}
+
+/**
+ * When the user types `{[fa-solid:user]}`, remark's directive plugin
+ * sees `:user` and emits a `textDirective` node. The result is a
+ * three-node sequence `text("…{[fa-solid") + textDirective("user") +
+ * text("]}…")`. This helper detects that shape and stitches the three
+ * back into one text node so downstream icon detection works on the
+ * authored token.
+ */
+function recombineDirectiveTokens(nodes: MarkdownInlineNode[]): MarkdownInlineNode[] {
+  const out: MarkdownInlineNode[] = [];
+  for (let i = 0; i < nodes.length; i++) {
+    const cur = nodes[i];
+    const next = nodes[i + 1];
+    const after = nodes[i + 2];
+    if (
+      cur?.type === 'text' &&
+      next?.type === 'textDirective' &&
+      after?.type === 'text' &&
+      /\{\[[a-zA-Z0-9_-]+$/.test(cur.value) &&
+      /^\]\}/.test(after.value)
+    ) {
+      const directive = next as unknown as { name?: string };
+      const directiveName = directive.name ?? '';
+      const merged: MarkdownInlineNode = {
+        type: 'text',
+        value: cur.value + ':' + directiveName + after.value,
+        ...(cur.position ? { position: cur.position } : {}),
+      };
+      out.push(merged);
+      i += 2;
+      continue;
+    }
+    out.push(cur);
+  }
+  return out;
+}
+
+const ICON_TOKEN_RE = /\{\[([a-zA-Z0-9_:-]+)\]\}/g;
+
+function splitTextOnIcons(value: string, position?: MarkdownSourcePosition): MarkdownInlineNode[] {
+  if (!value) return [];
+  ICON_TOKEN_RE.lastIndex = 0;
+  let lastIndex = 0;
+  let match: RegExpExecArray | null;
+  const out: MarkdownInlineNode[] = [];
+  while ((match = ICON_TOKEN_RE.exec(value)) !== null) {
+    const token = match[1];
+    const icon = resolveIcon(token);
+    if (!icon) continue; // leave the literal `{[…]}` in place
+    if (match.index > lastIndex) {
+      out.push({
+        type: 'text',
+        value: value.slice(lastIndex, match.index),
+        ...(position ? { position } : {}),
+      });
+    }
+    const iconNode: MarkdownInlineIcon = {
+      type: 'inlineIcon',
+      token,
+      family: icon.family,
+      name: icon.name,
+      ...(position ? { position } : {}),
+    };
+    out.push(iconNode);
+    lastIndex = match.index + match[0].length;
+  }
+  if (lastIndex === 0) {
+    // No matches — return the original text node unchanged.
+    return [{ type: 'text', value, ...(position ? { position } : {}) }];
+  }
+  if (lastIndex < value.length) {
+    out.push({
+      type: 'text',
+      value: value.slice(lastIndex),
+      ...(position ? { position } : {}),
+    });
+  }
+  return out;
+}
+
+/**
+ * Post-process an inline-children list to collapse `text('@') + link(scheme:id)`
+ * pairs into a single `mention` node. The wire format `@[Display](scheme:id)`
+ * comes back from remark as two adjacent nodes — we merge them so consumers
+ * see a single atomic mention. A plain link whose URL doesn't have `scheme:id`
+ * shape, or that isn't immediately preceded by `@`, is left alone so ordinary
+ * links keep working.
+ */
+function coalesceMentions(inlines: MarkdownInlineNode[]): MarkdownInlineNode[] {
+  const out: MarkdownInlineNode[] = [];
+  for (const cur of inlines) {
+    const prev = out[out.length - 1];
+    if (
+      cur.type === 'link' &&
+      typeof cur.url === 'string' &&
+      prev &&
+      prev.type === 'text' &&
+      prev.value.endsWith('@')
+    ) {
+      const schemeMatch = cur.url.match(/^([a-z][a-z0-9+.-]*):(.+)$/i);
+      if (schemeMatch && schemeMatch[1] && schemeMatch[2]) {
+        const targetKind = schemeMatch[1];
+        const targetId = schemeMatch[2];
+        const displayName = extractInlineText(cur.children);
+        if (prev.value === '@') {
+          out.pop();
+        } else {
+          prev.value = prev.value.slice(0, -1);
+        }
+        out.push({
+          type: 'mention',
+          targetKind,
+          targetId,
+          displayName,
+          ...(cur.position ? { position: cur.position } : {}),
+        });
+        continue;
+      }
+    }
+    out.push(cur);
+  }
+  return out;
+}
+
+/** Plain-text of an inline children list — used to pull the display name
+ * out of a mention link's children. */
+function extractInlineText(nodes: MarkdownInlineNode[]): string {
+  let out = '';
+  for (const n of nodes) {
+    if (n.type === 'text' || n.type === 'inlineCode') out += n.value;
+    else if ('children' in n && Array.isArray(n.children)) {
+      out += extractInlineText(n.children as MarkdownInlineNode[]);
+    }
+  }
+  return out;
 }
 
 function convertBlockNode(node: MdastNode, parseHtml: boolean): MarkdownBlockNode | null {
@@ -261,12 +442,18 @@ function convertBlockNode(node: MdastNode, parseHtml: boolean): MarkdownBlockNod
 
   switch (node.type) {
     case 'heading': {
-      const headingChildren = convertInlineChildren(node.children ?? [], parseHtml);
+      // Defer icon splitting so `extractTemplateAnnotation` sees the
+      // trailing `{[name]}` as plain text and can decide whether it's
+      // a template annotation. Anything that's NOT the template still
+      // needs to become an icon node, so we run `splitInlineIcons` on
+      // what's left after the template extraction.
+      const headingChildren = convertInlineChildren(node.children ?? [], parseHtml, false);
       const annotation = extractTemplateAnnotation(headingChildren);
+      const finalChildren = splitInlineIcons(headingChildren);
       const result: MarkdownHeading = {
         type: 'heading',
         depth: (node.depth ?? 1) as 1 | 2 | 3 | 4 | 5 | 6,
-        children: headingChildren,
+        children: finalChildren,
         ...posField(pos),
       };
       if (annotation) {
@@ -590,7 +777,7 @@ export function toMdast(doc: MarkdownDocument): MdastNode {
 function blockToMdast(node: MarkdownBlockNode): MdastNode {
   switch (node.type) {
     case 'heading': {
-      const mdastChildren = node.children.map(inlineToMdast);
+      const mdastChildren = inlineChildrenToMdast(node.children);
       if (node.templateAnnotation) {
         const suffix = serializeTemplateAnnotation(node.templateAnnotation);
         // Append to last text node, or create a new one
@@ -612,7 +799,7 @@ function blockToMdast(node: MarkdownBlockNode): MdastNode {
     case 'paragraph':
       return {
         type: 'paragraph',
-        children: node.children.map(inlineToMdast),
+        children: inlineChildrenToMdast(node.children),
         ...mdastPosField(node.position),
       };
 
@@ -718,7 +905,7 @@ function blockToMdast(node: MarkdownBlockNode): MdastNode {
         type: 'leafDirective',
         name: node.name,
         ...(node.attributes ? { attributes: node.attributes } : {}),
-        children: node.children.map(inlineToMdast),
+        children: inlineChildrenToMdast(node.children),
         ...mdastPosField(node.position),
       };
 
@@ -757,11 +944,34 @@ function tableRowToMdast(row: MarkdownTableRow): MdastNode {
 function tableCellToMdast(cell: MarkdownTableCell): MdastNode {
   return {
     type: 'tableCell',
-    children: cell.children.map(inlineToMdast),
+    children: inlineChildrenToMdast(cell.children),
     ...mdastPosField(cell.position),
   };
 }
 
+/**
+ * Serialize an array of inline nodes to mdast, flat-mapping the result so
+ * a single `mention` expands to two mdast nodes (`text('@')` + `link`).
+ * Use in place of `.map(inlineToMdast)` wherever we walk a children array.
+ */
+function inlineChildrenToMdast(nodes: MarkdownInlineNode[]): MdastNode[] {
+  const out: MdastNode[] = [];
+  for (const n of nodes) {
+    if (n.type === 'mention') {
+      out.push({ type: 'text', value: '@' });
+      out.push({
+        type: 'link',
+        url: `${n.targetKind}:${n.targetId}`,
+        children: [{ type: 'text', value: n.displayName }],
+        ...mdastPosField(n.position),
+      });
+    } else {
+      out.push(inlineToMdast(n));
+    }
+  }
+  return out;
+}
+
 function inlineToMdast(node: MarkdownInlineNode): MdastNode {
   switch (node.type) {
     case 'text':
@@ -774,21 +984,21 @@ function inlineToMdast(node: MarkdownInlineNode): MdastNode {
     case 'emphasis':
       return {
         type: 'emphasis',
-        children: node.children.map(inlineToMdast),
+        children: inlineChildrenToMdast(node.children),
         ...mdastPosField(node.position),
       };
 
     case 'strong':
       return {
         type: 'strong',
-        children: node.children.map(inlineToMdast),
+        children: inlineChildrenToMdast(node.children),
         ...mdastPosField(node.position),
       };
 
     case 'delete':
       return {
         type: 'delete',
-        children: node.children.map(inlineToMdast),
+        children: inlineChildrenToMdast(node.children),
         ...mdastPosField(node.position),
       };
 
@@ -804,7 +1014,7 @@ function inlineToMdast(node: MarkdownInlineNode): MdastNode {
         type: 'link',
         url: node.url,
         ...(node.title != null ? { title: node.title } : {}),
-        children: node.children.map(inlineToMdast),
+        children: inlineChildrenToMdast(node.children),
         ...mdastPosField(node.position),
       };
 
@@ -851,7 +1061,7 @@ function inlineToMdast(node: MarkdownInlineNode): MdastNode {
         identifier: node.identifier,
         ...(node.label != null ? { label: node.label } : {}),
         referenceType: node.referenceType,
-        children: node.children.map(inlineToMdast),
+        children: inlineChildrenToMdast(node.children),
         ...mdastPosField(node.position),
       };
 
@@ -870,7 +1080,30 @@ function inlineToMdast(node: MarkdownInlineNode): MdastNode {
         type: 'textDirective',
         name: node.name,
         ...(node.attributes ? { attributes: node.attributes } : {}),
-        children: node.children.map(inlineToMdast),
+        children: inlineChildrenToMdast(node.children),
+        ...mdastPosField(node.position),
+      };
+
+    case 'mention':
+      // Fallback: when `inlineToMdast` is called directly (not via
+      // `inlineChildrenToMdast`), collapse the mention to just the link
+      // form. The `@` prefix is lost, but the id+name still round-trip.
+      // Normal call sites go through `inlineChildrenToMdast` and get
+      // the proper text('@') + link pair.
+      return {
+        type: 'link',
+        url: `${node.targetKind}:${node.targetId}`,
+        children: [{ type: 'text', value: node.displayName }],
+        ...mdastPosField(node.position),
+      };
+
+    case 'inlineIcon':
+      // Serialize back to the authored token so source round-trips
+      // byte-stable. The token already carries the qualified form when
+      // required (the parser preserved it verbatim).
+      return {
+        type: 'text',
+        value: `{[${node.token}]}`,
         ...mdastPosField(node.position),
       };
 

package/src/markdown/index.ts

@@ -77,6 +77,7 @@ export type {
   MarkdownLinkReference,
   MarkdownImageReference,
   MarkdownTextDirective,
+  MarkdownMention,
 
   // Union types
   MarkdownBlockNode,
@@ -107,4 +108,7 @@ export {
   countNodes,
   createDocument,
   parseFrontmatter,
+  setFrontmatterValues,
+  inferDocumentTitle,
+  readFrontmatterThemeId,
 } from './utils.js';