@dgck81lnn/satori-element-input 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,46 @@
-# Temporary Holding Version
+# @dgck81lnn/satori-element-input
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm](https://img.shields.io/npm/v/@dgck81lnn/satori-element-input?style=flat-square)](https://www.npmjs.com/package/@dgck81lnn/satori-element-input)
+
+Utilities for parsing and processing Satori element markup without discarding whitespace around tags.
+
+## Why
+
+Whitespace around an element can be meaningful when markup represents a user's message, not source code written for readability. [koishijs/koishi#1561](https://github.com/koishijs/koishi/issues/1561) documents how trimming newlines around tags can erroneously join command tokens or remove line breaks around inline elements when user content is serialized and parsed again.
+
+This package parses text and tags into the same `Element` class from Satori, while keeping the surrounding text intact. For example, the newline before and after an emoji remains part of the neighboring text nodes:
+
+```js
+import { parse } from '@dgck81lnn/satori-element-input'
+
+const elements = parse('First line <emoji id="297"/>\nSecond line')
+/*
+  [
+    Element {
+      type: 'text',
+      attrs: { content: 'First line ' },
+      children: []
+    },
+    Element { type: 'emoji', attrs: { id: '297' }, children: [] },
+    Element {
+      type: 'text',
+      attrs: { content: '\nSecond line' }, // <- '\n' preserved!
+      children: []
+    }
+  ]
+*/
+```
+
+The parsed array contains text nodes ending in `\n` before the image and beginning with `\n` after it. Use this when whitespace from user input must survive parsing; use the standard Satori parser when its whitespace normalization is desired.
+
+## API
+
+- `parse(source)` parses markup into `@satorijs/element` elements and preserves text whitespace around tags.
+- `normalize(source)` converts a string by parsing it, or converts an existing fragment to an element array.
+- `stringify(source)` serializes a fragment to a string. An omitted or empty source produces an empty string.
+- `escape(source, inline?)` and `unescape(source)` escape and unescape Satori text.
+- `select(source, query)` selects elements from either a markup string or an element array using CSS-like selectors.
+- `transform(source, rules, session?)` transforms a string or element array. It returns a string for string input and an element array for array input.
+- `transformAsync(source, rules, session?)` is the asynchronous equivalent of `transform` and returns a promise of the corresponding result.
+
+The transform functions accept the same rule and session shapes as `@satorijs/element`'s `transform` and `transformAsync` APIs.

package/lib/index.d.ts

@@ -0,0 +1,17 @@
+import Element from '@satorijs/element';
+import { Awaitable, type Dict } from 'cosmokit';
+export declare function parse(source: string): any[];
+export declare function parseSelector(input: string): Element.Selector[][];
+export declare function normalize(source: Element.Fragment): any[];
+export declare function stringify(source?: Element.Fragment): string;
+export declare function escape(source: string, inline?: boolean): string;
+export declare function unescape(source: string): string;
+export declare function select(source: string | Element[], query: string | Element.Selector[][]): Element[];
+type SyncVisitor<S> = Dict<Element.SyncTransformer<S>> | Element.Visit<boolean | Element.Fragment, S>;
+type Visitor<S> = Dict<Element.Transformer<S>> | Element.Visit<Awaitable<boolean | Element.Fragment>, S>;
+type Rest<T> = [T] extends [never] ? [session?: T] : [session: T];
+export declare function transform<S = never>(source: string, rules: SyncVisitor<S>, ...rest: Rest<S>): string;
+export declare function transform<S = never>(source: Element[], rules: SyncVisitor<S>, ...rest: Rest<S>): Element[];
+export declare function transformAsync<S = never>(source: string, rules: Visitor<S>, ...rest: Rest<S>): Promise<string>;
+export declare function transformAsync<S = never>(source: Element[], rules: Visitor<S>, ...rest: Rest<S>): Promise<Element[]>;
+export {};

package/lib/index.js

@@ -0,0 +1,200 @@
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  escape: () => escape,
+  normalize: () => normalize,
+  parse: () => parse,
+  parseSelector: () => parseSelector,
+  select: () => select,
+  stringify: () => stringify,
+  transform: () => transform,
+  transformAsync: () => transformAsync,
+  unescape: () => unescape
+});
+module.exports = __toCommonJS(index_exports);
+var import_element = __toESM(require("@satorijs/element"));
+var import_cosmokit = require("cosmokit");
+var tagRegExp1 = /(?<comment><!--[\s\S]*?-->)|(?<tag><(\/?)([^!\s>/]*)([^>]*?)\s*(\/?)>)/;
+var attrRegExp1 = /([^\s=]+)(?:="(?<value1>[^"]*)"|='(?<value2>[^']*)')?/g;
+function parse(source) {
+  const tokens = [];
+  function pushText(content) {
+    if (content) tokens.push(content);
+  }
+  __name(pushText, "pushText");
+  let tagCap;
+  while (tagCap = tagRegExp1.exec(source)) {
+    parseContent(source.slice(0, tagCap.index));
+    source = source.slice(tagCap.index + tagCap[0].length);
+    const [_, , , close, type, extra, empty] = tagCap;
+    if (tagCap.groups.comment) continue;
+    tokens.push({
+      type: "angle",
+      source: _,
+      name: type || "",
+      position: close ? 1 /* CLOSE */ : empty ? 2 /* EMPTY */ : 0 /* OPEN */,
+      extra
+    });
+  }
+  parseContent(source);
+  return parseTokens(foldTokens(tokens));
+  function parseContent(source2) {
+    source2 = unescape(source2);
+    pushText(source2);
+  }
+  __name(parseContent, "parseContent");
+}
+__name(parse, "parse");
+function foldTokens(tokens) {
+  const stack = [[{
+    type: "angle",
+    name: import_element.default.Fragment,
+    position: 0 /* OPEN */,
+    source: "",
+    extra: "",
+    children: { default: [] }
+  }, "default"]];
+  function pushToken(...items) {
+    const [token, slot] = stack[0];
+    token.children[slot].push(...items);
+  }
+  __name(pushToken, "pushToken");
+  for (const token of tokens) {
+    if (typeof token === "string") {
+      pushToken(token);
+      continue;
+    }
+    const { name, position } = token;
+    if (position === 1 /* CLOSE */) {
+      if (stack[0][0].name === name) {
+        stack.shift();
+      }
+    } else if (position === 0 /* OPEN */) {
+      pushToken(token);
+      token.children = { default: [] };
+      stack.unshift([token, "default"]);
+    } else {
+      pushToken(token);
+    }
+  }
+  return stack[stack.length - 1][0].children.default;
+}
+__name(foldTokens, "foldTokens");
+function parseTokens(tokens) {
+  const result = [];
+  for (const token of tokens) {
+    if (typeof token === "string") {
+      result.push((0, import_element.default)("text", { content: token }));
+    } else {
+      const attrs = {};
+      let attrCap;
+      attrRegExp1.lastIndex = 0;
+      while (attrCap = attrRegExp1.exec(token.extra)) {
+        const [, key, v1, v2 = v1] = attrCap;
+        if (!(0, import_cosmokit.isNullable)(v2)) {
+          attrs[key] = unescape(v2);
+        } else if (key.startsWith("no-")) {
+          attrs[key.slice(3)] = false;
+        } else {
+          attrs[key] = true;
+        }
+      }
+      result.push((0, import_element.default)(token.name, attrs, token.children && parseTokens(token.children.default)));
+    }
+  }
+  return result;
+}
+__name(parseTokens, "parseTokens");
+var combRegExp = / *([ >+~]) */;
+function parseSelector(input) {
+  return input.split(",").map((query) => {
+    const selectors = [];
+    query = query.trim();
+    let combCap, combinator = " ";
+    while (combCap = combRegExp.exec(query)) {
+      selectors.push({ type: query.slice(0, combCap.index), combinator });
+      combinator = combCap[1];
+      query = query.slice(combCap.index + combCap[0].length);
+    }
+    selectors.push({ type: query, combinator });
+    return selectors;
+  });
+}
+__name(parseSelector, "parseSelector");
+function normalize(source) {
+  return typeof source === "string" ? parse(source) : import_element.default.toElementArray(source);
+}
+__name(normalize, "normalize");
+function stringify(source) {
+  if (Array.isArray(source)) return source.filter(import_cosmokit.isNonNullable).join("");
+  if (source) return source.toString();
+  return "";
+}
+__name(stringify, "stringify");
+function escape(source, inline = false) {
+  return import_element.default.escape(source, inline);
+}
+__name(escape, "escape");
+function unescape(source) {
+  return source.replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, '"').replace(/&#0*([1-9]\d*|0);/g, (_, code) => code === "38" ? _ : String.fromCharCode(+code)).replace(/&#x0*([1-9a-f][0-9a-f]*|0);/gi, (_, code) => code === "26" ? _ : String.fromCharCode(parseInt(code, 16))).replace(/&(amp|#0*38|#x0*26);/g, "&");
+}
+__name(unescape, "unescape");
+function select(source, query) {
+  if (typeof source === "string") source = parse(source);
+  if (typeof query === "string") query = parseSelector(query);
+  return import_element.default.select(source, query);
+}
+__name(select, "select");
+function transform(source, rules, session) {
+  const elements = typeof source === "string" ? parse(source) : source;
+  const output = import_element.default.transform(elements, rules, session);
+  return typeof source === "string" ? output.join("") : output;
+}
+__name(transform, "transform");
+async function transformAsync(source, rules, session) {
+  const elements = typeof source === "string" ? parse(source) : source;
+  const output = await import_element.default.transformAsync(elements, rules, session);
+  return typeof source === "string" ? output.join("") : output;
+}
+__name(transformAsync, "transformAsync");
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  escape,
+  normalize,
+  parse,
+  parseSelector,
+  select,
+  stringify,
+  transform,
+  transformAsync,
+  unescape
+});

package/package.json

@@ -1,6 +1,24 @@
 {
   "name": "@dgck81lnn/satori-element-input",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Whitespace-preserving parsing and processing utilities for Satori element input.",
+  "keywords": [
+    "koishi"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/DGCK81LNN/koishi-better-parse.git",
+    "directory": "packages/satori-element-input"
+  },
+  "homepage": "https://github.com/DGCK81LNN/koishi-better-parse",
+  "license": "MIT",
+  "main": "lib/index.js",
+  "typings": "lib/index.d.ts",
+  "files": [
+    "lib"
+  ],
+  "dependencies": {
+    "@satorijs/element": "^3.2.0",
+    "cosmokit": "^1.8.1"
+  }
+}