@es-joy/jsoe 0.24.2 → 0.25.0

package/src/utils/schemaMeta.js

@@ -0,0 +1,257 @@
+import {jml} from '../vendor-imports.js';
+
+/**
+ * @typedef {import('../formats/schema.js').ZodexSchema} ZodexSchema
+ */
+
+/**
+ * Metadata keys with dedicated handling; everything else on `meta` (other than
+ *   the reserved `jsoe` directive namespace) is treated as custom metadata.
+ * @type {Set<string>}
+ */
+const RESERVED = new Set(['title', 'description', 'id', 'deprecated']);
+
+/**
+ * @param {unknown} val
+ * @returns {string}
+ */
+function stringifyMetaValue (val) {
+  return typeof val === 'string' ? val : JSON.stringify(val);
+}
+
+/**
+ * Normalize the metadata carried on a serialized (zerialized) schema object,
+ *   merging the legacy top-level `description` into the `meta` bag and applying
+ *   jsoe's precedence rules.
+ *
+ * Precedence for the visible label is `meta.title` then `meta.description`
+ *   then the top-level `description` (the last kept only while `.description`
+ *   directly on a schema remains supported). `meta.description` is treated as
+ *   tooltip-only long-form text only when `meta.title` is also present;
+ *   otherwise it is already serving as the label.
+ * @param {ZodexSchema} [schemaObject]
+ * @returns {{
+ *   label: string|undefined,
+ *   longText: string|undefined,
+ *   id: string|undefined,
+ *   deprecated: boolean|string|undefined,
+ *   custom: [string, unknown][],
+ *   jsoe: {[key: string]: unknown}|undefined,
+ *   rows: [string, string][],
+ *   hasAny: boolean
+ * }}
+ */
+export function resolveSchemaMeta (schemaObject) {
+  const obj = schemaObject && typeof schemaObject === 'object'
+    ? /** @type {{[key: string]: any}} */ (schemaObject)
+    : undefined;
+  const metaObj = obj && obj.meta && typeof obj.meta === 'object'
+    ? /** @type {{[key: string]: any}} */ (obj.meta)
+    : undefined;
+
+  const topDescription = typeof obj?.description === 'string'
+    ? obj.description
+    : undefined;
+  const metaTitle = typeof metaObj?.title === 'string'
+    ? metaObj.title
+    : undefined;
+  const metaDescription = typeof metaObj?.description === 'string'
+    ? metaObj.description
+    : undefined;
+  const id = typeof metaObj?.id === 'string' ? metaObj.id : undefined;
+  const deprecated = typeof metaObj?.deprecated === 'boolean' ||
+    typeof metaObj?.deprecated === 'string'
+    ? metaObj.deprecated
+    : undefined;
+  const jsoe = metaObj && metaObj.jsoe && typeof metaObj.jsoe === 'object'
+    ? /** @type {{[key: string]: unknown}} */ (metaObj.jsoe)
+    : undefined;
+
+  /** @type {[string, unknown][]} */
+  const custom = metaObj
+    ? Object.entries(metaObj).filter(([key]) => {
+      return !RESERVED.has(key) && key !== 'jsoe';
+    })
+    : [];
+
+  const label = metaTitle ?? metaDescription ?? topDescription;
+  const longText = metaTitle ? metaDescription : undefined;
+
+  /** @type {[string, string][]} */
+  const rows = [];
+  if (metaTitle) {
+    rows.push(['Title', metaTitle]);
+  }
+  // Keep the table self-describing even when the description doubles as the
+  //   label (no `meta.title`).
+  const rowDescription = metaDescription ?? topDescription;
+  if (rowDescription) {
+    rows.push(['Description', rowDescription]);
+  }
+  if (id !== undefined) {
+    rows.push(['ID', id]);
+  }
+  if (deprecated !== undefined && deprecated !== false) {
+    rows.push([
+      'Deprecated', deprecated === true ? 'yes' : String(deprecated)
+    ]);
+  }
+  for (const [key, val] of custom) {
+    rows.push([key, stringifyMetaValue(val)]);
+  }
+  if (jsoe) {
+    for (const [key, val] of Object.entries(jsoe)) {
+      rows.push([`jsoe.${key}`, stringifyMetaValue(val)]);
+    }
+  }
+
+  return {
+    label, longText, id, deprecated, custom, jsoe, rows,
+    hasAny: rows.length > 0
+  };
+}
+
+/**
+ * Terse call-site sugar for the visible label of a (sub)schema. Returns
+ *   `undefined` when the schema carries no usable metadata, so callers keep
+ *   their own `?? fallback`.
+ * @param {ZodexSchema} [schemaObject]
+ * @returns {string|undefined}
+ */
+export function schemaLabel (schemaObject) {
+  return resolveSchemaMeta(schemaObject).label;
+}
+
+/**
+ * Whether a (sub)schema is marked deprecated via `meta.deprecated`.
+ * @param {ZodexSchema} [schemaObject]
+ * @returns {boolean}
+ */
+export function isDeprecated (schemaObject) {
+  const {deprecated} = resolveSchemaMeta(schemaObject);
+  return deprecated !== undefined && deprecated !== false;
+}
+
+/**
+ * ` schema-deprecated` (leading space) when the schema is deprecated, else `''`
+ * — for appending to an existing `class` string.
+ * @param {ZodexSchema} [schemaObject]
+ * @returns {string}
+ */
+export function deprecatedClassSuffix (schemaObject) {
+  return isDeprecated(schemaObject) ? ' schema-deprecated' : '';
+}
+
+/**
+ * The last element child of `el` that is not the appended schema-metadata
+ * affordance. Use this in place of `el.lastElementChild` wherever a type root
+ * is walked from its end, since `appendSchemaMeta` adds a trailing
+ * `span.schema-meta`.
+ * @param {Element} el
+ * @returns {Element|null}
+ */
+export function lastTypeChild (el) {
+  let child = el.lastElementChild;
+  while (child && child.classList.contains('schema-meta')) {
+    child = child.previousElementSibling;
+  }
+  return child;
+}
+
+/**
+ * @param {[string, string][]} rows
+ * @returns {string}
+ */
+export function metaTooltipText (rows) {
+  return rows.map(([key, val]) => {
+    return `${key}: ${val}`;
+  }).join('\n');
+}
+
+/**
+ * @param {[string, string][]} rows
+ * @returns {import('jamilih').JamilihArray}
+ */
+export function metaTable (rows) {
+  return ['table', {class: 'schema-meta-table'}, [
+    ['tbody', rows.map(([key, val]) => {
+      return ['tr', [['th', [key]], ['td', [val]]]];
+    })]
+  ]];
+}
+
+/**
+ * Build the read-only metadata affordance (an info toggle that reveals a
+ *   key/value table) and append it to a type's root element. A no-op when the
+ *   schema carries no surfaced metadata.
+ *
+ * The table is created lazily on first toggle, so an untouched affordance adds
+ *   no text to the root (the marker glyph comes from CSS, not a text node),
+ *   keeping the DOM stable for tests and assistive tech.
+ *
+ * Rendered in both view and edit mode; it never mutates the schema (jsoe edits
+ *   data conforming to a schema, not the schema guiding the session).
+ * @param {HTMLElement} root
+ * @param {ZodexSchema} [schemaObject]
+ * @returns {void}
+ */
+export function appendSchemaMeta (root, schemaObject) {
+  const meta = resolveSchemaMeta(schemaObject);
+  if (!meta.hasAny) {
+    return;
+  }
+  if (meta.deprecated !== undefined && meta.deprecated !== false) {
+    root.classList.add('schema-deprecated');
+  }
+  /**
+   * @param {Event} e
+   * @returns {void}
+   */
+  const onToggle = (e) => {
+    e.preventDefault();
+    const toggle = /** @type {HTMLElement} */ (
+      /** @type {HTMLElement} */ (e.target).closest('.schema-meta-toggle')
+    );
+    let tbl = /** @type {HTMLElement|null} */ (toggle.nextElementSibling);
+    const show = !tbl || tbl.hidden;
+    if (!tbl) {
+      tbl = /** @type {HTMLElement} */ (jml(...metaTable(meta.rows)));
+      /** @type {HTMLElement} */ (toggle.parentElement).append(tbl);
+    }
+    tbl.hidden = !show;
+    toggle.setAttribute('aria-expanded', String(show));
+  };
+
+  /**
+   * @param {KeyboardEvent} e
+   * @returns {void}
+   */
+  const onKeydown = (e) => {
+    if (e.key === 'Enter' || e.key === ' ') {
+      onToggle(e);
+    }
+  };
+
+  // A `span[role=button]` rather than a real `<button>` so bare `getInput`
+  //   selectors (`$e(root, 'button')` in `arrayType`/`noneditable`) never
+  //   mistake the toggle for the type's own form control.
+  const affordanceSpec = /** @type {import('jamilih').JamilihArray} */ ([
+    'span', {class: 'schema-meta'}, [
+      ['span', {
+        class: 'schema-meta-toggle',
+        role: 'button',
+        tabindex: '0',
+        'aria-expanded': 'false',
+        'aria-label': 'Schema metadata',
+        title: metaTooltipText(meta.rows),
+        $on: {click: onToggle, keydown: onKeydown}
+      }]
+    ]
+  ]);
+  // Appended last (not prepended): tests and internal code select the type's
+  //   label via `root > span` / `root > *:first-child`, so the affordance must
+  //   not become the first child. The few `arrayType` helpers that walk
+  //   `root.lastElementChild` use `lastTypeChild()` to skip a trailing
+  //   `.schema-meta`.
+  root.append(/** @type {HTMLElement} */ (jml(...affordanceSpec)));
+}

package/src/utils/templateUtils.js

@@ -1,6 +1,6 @@
-const nbsp = '\u00A0';
-const upArrow = '\u2191';
-const downArrow = '\u2193';
+const nbsp = '\u{A0}';
+const upArrow = '\u{2191}';
+const downArrow = '\u{2193}';
 const U = {nbsp, upArrow, downArrow};
 
 /**

package/src/utils/timing.js

@@ -0,0 +1,12 @@
+/* eslint-disable promise/avoid-new -- Primitive timing helper */
+
+/**
+ * Resolves after a macrotask, letting the browser flush pending DOM work
+ *   scheduled with `setTimeout(fn, 0)` (element insertion, layout-dependent
+ *   building, etc.). Used to replace bare `setTimeout` deferrals with an
+ *   awaitable form so callers can know when the deferred work has completed.
+ * @returns {Promise<void>}
+ */
+export const tick = () => new Promise((resolve) => {
+  setTimeout(resolve, 0);
+});

package/src/utils/types.js

@@ -4,3 +4,22 @@
 export const isNullish = (obj) => {
   return obj === null || typeof obj === 'undefined';
 };
+
+/**
+ * Zodex schema types which jsoe expands into a flat set of candidate leaf
+ * types and drives from a single type-choices control: `union` (anyOf), `xor`
+ * (exactly one), and `discriminatedUnion` (keyed by a literal field). They
+ * share `options` and, downstream, the same option-indexing logic.
+ * @type {readonly ['union', 'xor', 'discriminatedUnion']}
+ */
+const unionLikeTypes = ['union', 'xor', 'discriminatedUnion'];
+
+/**
+ * @param {string|undefined} type
+ * @returns {boolean}
+ */
+export const isUnionLike = (type) => {
+  return unionLikeTypes.includes(
+    /** @type {typeof unionLikeTypes[number]} */ (type)
+  );
+};

package/src/vendor-imports.js

@@ -1,8 +1,11 @@
+/* eslint-disable unicorn/no-barrel-files -- Convenient to toggle */
+
 export {jml, body, nbsp, $} from 'jamilih';
-// export {jml, body, nbsp, $} from '../node_modules/jamilih/dist/jml-es.js';
+// export {jml, body, nbsp, $} from '../node_modules/jamilih/dist/jml.mjs';
 
 export {
-  getJSONType, Typeson, unescapeKeyPathComponent, structuredCloningThrowing,
+  getJSONType, Typeson, unescapeKeyPathComponent,
+  structuredCloningForStorage,
   resurrectable, toStringTag, hasConstructorOf, symbol, promise
 } from 'typeson-registry';
 // } from '../node_modules/typeson-registry/dist/index.js';
@@ -11,3 +14,8 @@ export {
   parse as parseAcorn
 } from 'acorn';
 // } from '../node_modules/acorn/dist/acorn.mjs';
+
+export {default as mimeStandardTypes} from 'mime/types/standard.js';
+export {default as mimeOtherTypes} from 'mime/types/other.js';
+// } from '../node_modules/mime/dist/types/standard.js';
+// } from '../node_modules/mime/dist/types/other.js';

package/tsconfig.json

@@ -1,6 +1,7 @@
 {
   "compilerOptions": {
     "lib": ["es2023", "DOM"],
+    "skipLibCheck": true,
     "moduleResolution": "nodenext",
     "module": "NodeNext",
     "allowJs": true,
@@ -11,6 +12,7 @@
     "emitDeclarationOnly": true,
     "strict": true,
     "target": "es2020",
+    "rootDir": "src",
     "outDir": "dist"
   },
   "include": ["src/**/*.js", "typings/sceditor.d.ts"],

package/vendor/acorn/dist/acorn.d.mts

@@ -169,7 +169,7 @@ export interface FunctionDeclaration extends Function {
 export interface VariableDeclaration extends Node {
   type: "VariableDeclaration"
   declarations: Array<VariableDeclarator>
-  kind: "var" | "let" | "const"
+  kind: "var" | "let" | "const" | "using" | "await using"
 }
 
 export interface VariableDeclarator extends Node {
@@ -403,6 +403,7 @@ export interface ImportDeclaration extends Node {
   type: "ImportDeclaration"
   specifiers: Array<ImportSpecifier | ImportDefaultSpecifier | ImportNamespaceSpecifier>
   source: Literal
+  attributes: Array<ImportAttribute>
 }
 
 export interface ImportSpecifier extends Node {
@@ -421,11 +422,18 @@ export interface ImportNamespaceSpecifier extends Node {
   local: Identifier
 }
 
+export interface ImportAttribute extends Node {
+  type: "ImportAttribute"
+  key: Identifier | Literal
+  value: Literal
+}
+
 export interface ExportNamedDeclaration extends Node {
   type: "ExportNamedDeclaration"
   declaration?: Declaration | null
   specifiers: Array<ExportSpecifier>
   source?: Literal | null
+  attributes: Array<ImportAttribute>
 }
 
 export interface ExportSpecifier extends Node {
@@ -454,6 +462,7 @@ export interface ExportAllDeclaration extends Node {
   type: "ExportAllDeclaration"
   source: Literal
   exported?: Identifier | Literal | null
+  attributes: Array<ImportAttribute>
 }
 
 export interface AwaitExpression extends Node {
@@ -469,6 +478,7 @@ export interface ChainExpression extends Node {
 export interface ImportExpression extends Node {
   type: "ImportExpression"
   source: Expression
+  options: Expression | null
 }
 
 export interface ParenthesizedExpression extends Node {
@@ -562,7 +572,24 @@ export type ModuleDeclaration =
 | ExportDefaultDeclaration
 | ExportAllDeclaration
 
-export type AnyNode = Statement | Expression | Declaration | ModuleDeclaration | Literal | Program | SwitchCase | CatchClause | Property | Super | SpreadElement | TemplateElement | AssignmentProperty | ObjectPattern | ArrayPattern | RestElement | AssignmentPattern | ClassBody | MethodDefinition | MetaProperty | ImportSpecifier | ImportDefaultSpecifier | ImportNamespaceSpecifier | ExportSpecifier | AnonymousFunctionDeclaration | AnonymousClassDeclaration | PropertyDefinition | PrivateIdentifier | StaticBlock | VariableDeclarator
+/**
+  * This interface is only used for defining {@link AnyNode}.
+  * It exists so that it can be extended by plugins:
+  *
+  * @example
+  * ```typescript
+  * declare module 'acorn' {
+  *   interface NodeTypes {
+  *     pluginName: FirstNode | SecondNode | ThirdNode | ... | LastNode
+  *   }
+  * }
+  * ```
+  */
+interface NodeTypes {
+  core: Statement | Expression | Declaration | ModuleDeclaration | Literal | Program | SwitchCase | CatchClause | Property | Super | SpreadElement | TemplateElement | AssignmentProperty | ObjectPattern | ArrayPattern | RestElement | AssignmentPattern | ClassBody | MethodDefinition | MetaProperty | ImportAttribute | ImportSpecifier | ImportDefaultSpecifier | ImportNamespaceSpecifier | ExportSpecifier | AnonymousFunctionDeclaration | AnonymousClassDeclaration | PropertyDefinition | PrivateIdentifier | StaticBlock | VariableDeclarator
+}
+
+export type AnyNode = NodeTypes[keyof NodeTypes]
 
 export function parse(input: string, options: Options): Program
 
@@ -573,7 +600,7 @@ export function tokenizer(input: string, options: Options): {
   [Symbol.iterator](): Iterator<Token>
 }
 
-export type ecmaVersion = 3 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 2015 | 2016 | 2017 | 2018 | 2019 | 2020 | 2021 | 2022 | 2023 | 2024 | 2025 | "latest"
+export type ecmaVersion = 3 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 2015 | 2016 | 2017 | 2018 | 2019 | 2020 | 2021 | 2022 | 2023 | 2024 | 2025 | 2026 | "latest"
 
 export interface Options {
   /**
@@ -587,10 +614,16 @@ export interface Options {
 
   /**
    * `sourceType` indicates the mode the code should be parsed in.
-   * Can be either `"script"` or `"module"`. This influences global
+   * Can be either `"script"`, `"module"` or `"commonjs"`. This influences global
    * strict mode and parsing of `import` and `export` declarations.
    */
-  sourceType?: "script" | "module"
+  sourceType?: "script" | "module" | "commonjs"
+
+  /**
+   * When set to true, enable strict parsing mode even if `sourceType`
+   * is `"script"`.
+   */
+  strict?: boolean
 
   /**
    * a callback that will be called when a semicolon is automatically inserted.
@@ -660,6 +693,14 @@ export interface Options {
    */
   locations?: boolean
 
+  /**
+   * Pass an optional `{line, column}` object to use for the start of
+   * the parse. This is mostly useful when using `parseExpressionAt`
+   * with `locations: true`, to prevent the parser from having to
+   * determine the line position at the start position.
+   */
+  startLocation?: {line: number, column: number}
+
   /**
    * a callback that will cause Acorn to call that export function with object in the same
    * format as tokens returned from `tokenizer().getToken()`. Note

package/vendor/acorn/dist/acorn.d.ts

@@ -169,7 +169,7 @@ export interface FunctionDeclaration extends Function {
 export interface VariableDeclaration extends Node {
   type: "VariableDeclaration"
   declarations: Array<VariableDeclarator>
-  kind: "var" | "let" | "const"
+  kind: "var" | "let" | "const" | "using" | "await using"
 }
 
 export interface VariableDeclarator extends Node {
@@ -403,6 +403,7 @@ export interface ImportDeclaration extends Node {
   type: "ImportDeclaration"
   specifiers: Array<ImportSpecifier | ImportDefaultSpecifier | ImportNamespaceSpecifier>
   source: Literal
+  attributes: Array<ImportAttribute>
 }
 
 export interface ImportSpecifier extends Node {
@@ -421,11 +422,18 @@ export interface ImportNamespaceSpecifier extends Node {
   local: Identifier
 }
 
+export interface ImportAttribute extends Node {
+  type: "ImportAttribute"
+  key: Identifier | Literal
+  value: Literal
+}
+
 export interface ExportNamedDeclaration extends Node {
   type: "ExportNamedDeclaration"
   declaration?: Declaration | null
   specifiers: Array<ExportSpecifier>
   source?: Literal | null
+  attributes: Array<ImportAttribute>
 }
 
 export interface ExportSpecifier extends Node {
@@ -454,6 +462,7 @@ export interface ExportAllDeclaration extends Node {
   type: "ExportAllDeclaration"
   source: Literal
   exported?: Identifier | Literal | null
+  attributes: Array<ImportAttribute>
 }
 
 export interface AwaitExpression extends Node {
@@ -469,6 +478,7 @@ export interface ChainExpression extends Node {
 export interface ImportExpression extends Node {
   type: "ImportExpression"
   source: Expression
+  options: Expression | null
 }
 
 export interface ParenthesizedExpression extends Node {
@@ -562,7 +572,24 @@ export type ModuleDeclaration =
 | ExportDefaultDeclaration
 | ExportAllDeclaration
 
-export type AnyNode = Statement | Expression | Declaration | ModuleDeclaration | Literal | Program | SwitchCase | CatchClause | Property | Super | SpreadElement | TemplateElement | AssignmentProperty | ObjectPattern | ArrayPattern | RestElement | AssignmentPattern | ClassBody | MethodDefinition | MetaProperty | ImportSpecifier | ImportDefaultSpecifier | ImportNamespaceSpecifier | ExportSpecifier | AnonymousFunctionDeclaration | AnonymousClassDeclaration | PropertyDefinition | PrivateIdentifier | StaticBlock | VariableDeclarator
+/**
+  * This interface is only used for defining {@link AnyNode}.
+  * It exists so that it can be extended by plugins:
+  *
+  * @example
+  * ```typescript
+  * declare module 'acorn' {
+  *   interface NodeTypes {
+  *     pluginName: FirstNode | SecondNode | ThirdNode | ... | LastNode
+  *   }
+  * }
+  * ```
+  */
+interface NodeTypes {
+  core: Statement | Expression | Declaration | ModuleDeclaration | Literal | Program | SwitchCase | CatchClause | Property | Super | SpreadElement | TemplateElement | AssignmentProperty | ObjectPattern | ArrayPattern | RestElement | AssignmentPattern | ClassBody | MethodDefinition | MetaProperty | ImportAttribute | ImportSpecifier | ImportDefaultSpecifier | ImportNamespaceSpecifier | ExportSpecifier | AnonymousFunctionDeclaration | AnonymousClassDeclaration | PropertyDefinition | PrivateIdentifier | StaticBlock | VariableDeclarator
+}
+
+export type AnyNode = NodeTypes[keyof NodeTypes]
 
 export function parse(input: string, options: Options): Program
 
@@ -573,7 +600,7 @@ export function tokenizer(input: string, options: Options): {
   [Symbol.iterator](): Iterator<Token>
 }
 
-export type ecmaVersion = 3 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 2015 | 2016 | 2017 | 2018 | 2019 | 2020 | 2021 | 2022 | 2023 | 2024 | 2025 | "latest"
+export type ecmaVersion = 3 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 2015 | 2016 | 2017 | 2018 | 2019 | 2020 | 2021 | 2022 | 2023 | 2024 | 2025 | 2026 | "latest"
 
 export interface Options {
   /**
@@ -587,10 +614,16 @@ export interface Options {
 
   /**
    * `sourceType` indicates the mode the code should be parsed in.
-   * Can be either `"script"` or `"module"`. This influences global
+   * Can be either `"script"`, `"module"` or `"commonjs"`. This influences global
    * strict mode and parsing of `import` and `export` declarations.
    */
-  sourceType?: "script" | "module"
+  sourceType?: "script" | "module" | "commonjs"
+
+  /**
+   * When set to true, enable strict parsing mode even if `sourceType`
+   * is `"script"`.
+   */
+  strict?: boolean
 
   /**
    * a callback that will be called when a semicolon is automatically inserted.
@@ -660,6 +693,14 @@ export interface Options {
    */
   locations?: boolean
 
+  /**
+   * Pass an optional `{line, column}` object to use for the start of
+   * the parse. This is mostly useful when using `parseExpressionAt`
+   * with `locations: true`, to prevent the parser from having to
+   * determine the line position at the start position.
+   */
+  startLocation?: {line: number, column: number}
+
   /**
    * a callback that will cause Acorn to call that export function with object in the same
    * format as tokens returned from `tokenizer().getToken()`. Note