@md-plugins/shared 0.1.0-rc.9 → 1.1.0

package/README.md

@@ -1,13 +1,24 @@
 # @md-plugins/shared
 
-The `@md-plugins/shared` package provides common utilities, types, and helpers used across various Markdown-It plugins in the `@md-plugins` ecosystem. It serves as a foundational package to ensure consistency and reduce code duplication across the plugins.
+[![npm version](https://img.shields.io/npm/v/@md-plugins/shared?label=%40md-plugins%2Fshared)](https://www.npmjs.com/package/@md-plugins/shared)
+[![npm downloads](https://img.shields.io/npm/dt/@md-plugins/shared)](https://www.npmjs.com/package/@md-plugins/shared)
+[![npm monthly downloads](https://img.shields.io/npm/dm/@md-plugins/shared)](https://www.npmjs.com/package/@md-plugins/shared)
+[![license](https://img.shields.io/npm/l/@md-plugins/shared)](https://www.npmjs.com/package/@md-plugins/shared)
 
-QPress applications and regular `@md-plugins/vite-md-plugin` users do not need to install this package directly. Use it only when building a custom Markdown-It plugin or contributing to the MD-Plugins packages.
+<span class="badge-github-sponsors"><a href="https://github.com/sponsors/hawkeye64" title="Sponsor this project on GitHub"><img src="https://img.shields.io/badge/github-sponsors-ea4aaa.svg?logo=githubsponsors&logoColor=white" alt="GitHub Sponsors button" /></a></span>
+<span class="badge-paypal"><a href="https://paypal.me/hawkeye64" title="Donate to this project using Paypal"><img src="https://img.shields.io/badge/paypal-donate-yellow.svg" alt="PayPal donate button" /></a></span>
+
+[![Discord](https://img.shields.io/badge/discord-join%20server-738ADB?style=for-the-badge&logo=discord&logoColor=738ADB)](https://chat.quasar.dev)
+[![X](https://img.shields.io/badge/follow-@jgalbraith64-1DA1F2?style=for-the-badge&logo=x&logoColor=1DA1F2)](https://twitter.com/jgalbraith64)
+
+The `@md-plugins/shared` package provides common utilities, types, and helpers used across the Markdown-it plugins in the md-plugins ecosystem. It keeps Q-Press and direct plugin usage on the same environment shape for frontmatter, table of contents, extracted titles, and page-level imports.
+
+Q-Press applications and regular `@md-plugins/vite-md-plugin` users do not need to install this package directly. Use it only when building a custom Markdown-it plugin or contributing to the md-plugins packages.
 
 ## Features
 
 - Shared TypeScript types for plugin environments.
-- Common utility functions for Markdown-It processing.
+- Common utility functions for Markdown-it processing.
 - Centralized definitions for easier maintenance and reusability.
 - Lightweight and dependency-free.
 

package/dist/index.d.mts

@@ -1,65 +1,59 @@
-import Token from 'markdown-it/lib/token.mjs';
-
+import Token from "markdown-it/lib/token.mjs";
 /**
  * Escapes HTML-sensitive characters so text can be safely injected into markup.
  */
 declare const htmlEscape: (str: string) => string;
-
 /**
  * Decodes the HTML entities emitted by {@link htmlEscape} and common numeric variants.
  */
 declare const htmlUnescape: (str: string) => string;
-
 interface MarkdownItEnv {
-    plugins?: Record<string, unknown>;
+  plugins?: Record<string, unknown>;
 }
 interface MarkdownItHeader {
-    /**
-     * The slug of the header
-     *
-     * Typically the `id` attr of the header anchor
-     */
-    id: string;
-    /**
-     * The level of the header
-     *
-     * `1` to `6` for `<h1>` to `<h6>`
-     */
-    level: number;
-    /**
-     * The title of the header
-     */
-    title: string;
-    /**
-     * Link of the header
-     *
-     * Typically using `#${slug}` as the anchor hash
-     */
-    link: string;
-    /**
-     * The children of the header
-     */
-    children: MarkdownItHeader[];
+  /**
+   * The slug of the header
+   *
+   * Typically the `id` attr of the header anchor
+   */
+  id: string;
+  /**
+   * The level of the header
+   *
+   * `1` to `6` for `<h1>` to `<h6>`
+   */
+  level: number;
+  /**
+   * The title of the header
+   */
+  title: string;
+  /**
+   * Link of the header
+   *
+   * Typically using `#${slug}` as the anchor hash
+   */
+  link: string;
+  /**
+   * The children of the header
+   */
+  children: MarkdownItHeader[];
 }
-type ResolvePluginOptionsFn = <T extends object, K extends keyof any>(options: T | {
-    [P in K]?: T;
-} | undefined, key: K, defaults: T) => T;
-
+type ResolvePluginOptionsFn = <T extends object, K extends keyof any>(options: T | { [P in K]?: T; } | undefined, key: K, defaults: T) => T;
 interface ResolveTitleOptions {
-    /**
-     * Should allow inline HTML tags or not.
-     *
-     * If the result is going to be used as Vue template, it should allow inline
-     * HTML tags so that Vue custom components would be kept.
-     */
-    shouldAllowHtml: boolean;
-    /**
-     * Should escape the text content or not.
-     *
-     * If the result is going to be used in HTML directly, it should be escaped
-     * so that the text content won't be wrongly treated as HTML tags.
-     */
-    shouldEscapeText: boolean;
+  /**
+   * Should allow inline HTML tags or not.
+   *
+   * If the result is going to be used as Vue template, it should allow inline
+   * HTML tags so that Vue custom components would be kept.
+   */
+  shouldAllowHtml: boolean;
+  /**
+   * Should escape the text content or not.
+   *
+   * If the result is going to be used in HTML directly, it should be escaped
+   * so that the text content won't be wrongly treated as HTML tags.
+   */
+  shouldEscapeText: boolean;
 }
 /**
  * Extracts plain heading text from a markdown-it inline token.
@@ -69,28 +63,27 @@ interface ResolveTitleOptions {
  * are ignored so the title remains human-readable.
  */
 declare const resolveTitleFromToken: (token: Token, { shouldAllowHtml, shouldEscapeText }: ResolveTitleOptions) => string;
-
 interface ResolveHeadersOptions extends ResolveTitleOptions {
-    /**
-     * Heading level that going to be resolved
-     */
-    level: number[];
-    /**
-     * Should allow headers inside nested blocks or not
-     *
-     * If set to `true`, headers inside blockquote, list, etc. would also be resolved.
-     */
-    shouldAllowNested: boolean;
-    /**
-     * A custom slugification function
-     *
-     * Would be ignored if the `id` attr of the token is set.
-     */
-    slugify?: (str: string) => string;
-    /**
-     * A function for formatting headings
-     */
-    format?: (str: string) => string | undefined;
+  /**
+   * Heading level that going to be resolved
+   */
+  level: number[];
+  /**
+   * Should allow headers inside nested blocks or not
+   *
+   * If set to `true`, headers inside blockquote, list, etc. would also be resolved.
+   */
+  shouldAllowNested: boolean;
+  /**
+   * A custom slugification function
+   *
+   * Would be ignored if the `id` attr of the token is set.
+   */
+  slugify?: (str: string) => string;
+  /**
+   * A function for formatting headings
+   */
+  format?: (str: string) => string | undefined;
 }
 /**
  * Builds a nested heading tree from markdown-it heading tokens.
@@ -98,16 +91,14 @@ interface ResolveHeadersOptions extends ResolveTitleOptions {
  * Existing heading `id` attributes are preserved. When a heading has no `id`,
  * the configured `slugify` function creates one from the resolved heading text.
  */
-declare const resolveHeadersFromTokens: (tokens: Token[], { level, shouldAllowHtml, shouldAllowNested, shouldEscapeText, slugify, format, }?: Partial<ResolveHeadersOptions>) => MarkdownItHeader[];
-
+declare const resolveHeadersFromTokens: (tokens: Token[], { level, shouldAllowHtml, shouldAllowNested, shouldEscapeText, slugify, format }?: Partial<ResolveHeadersOptions>) => MarkdownItHeader[];
 /**
  * Converts arbitrary heading text into a stable URL-friendly slug.
  *
  * The result is lowercase, accent-free, hyphen-separated, and safe to use as a
  * generated Markdown heading id.
  */
-declare const slugify: (str: string) => string;
-
+declare const slugify$1: (str: string) => string;
 /**
  * Resolves plugin options from either a direct options object or a nested
  * package-level options bag.
@@ -116,9 +107,5 @@ declare const slugify: (str: string) => string;
  * or through a shared md-plugins config object keyed by plugin name. This helper
  * supports both shapes while applying default values.
  */
-declare function resolvePluginOptions<T extends object, K extends keyof any>(options: T | {
-    [key in K]?: T;
-} | undefined, key: K, defaults: T): T;
-
-export { htmlEscape, htmlUnescape, resolveHeadersFromTokens, resolvePluginOptions, resolveTitleFromToken, slugify };
-export type { MarkdownItEnv, MarkdownItHeader, ResolveHeadersOptions, ResolvePluginOptionsFn, ResolveTitleOptions };
+declare function resolvePluginOptions<T extends object, K extends keyof any>(options: T | { [key in K]?: T; } | undefined, key: K, defaults: T): T;
+export { type MarkdownItEnv, type MarkdownItHeader, ResolveHeadersOptions, type ResolvePluginOptionsFn, ResolveTitleOptions, htmlEscape, htmlUnescape, resolveHeadersFromTokens, resolvePluginOptions, resolveTitleFromToken, slugify$1 as slugify };

package/dist/index.d.ts

@@ -1,65 +1,59 @@
-import Token from 'markdown-it/lib/token.mjs';
-
+import Token from "markdown-it/lib/token.mjs";
 /**
  * Escapes HTML-sensitive characters so text can be safely injected into markup.
  */
 declare const htmlEscape: (str: string) => string;
-
 /**
  * Decodes the HTML entities emitted by {@link htmlEscape} and common numeric variants.
  */
 declare const htmlUnescape: (str: string) => string;
-
 interface MarkdownItEnv {
-    plugins?: Record<string, unknown>;
+  plugins?: Record<string, unknown>;
 }
 interface MarkdownItHeader {
-    /**
-     * The slug of the header
-     *
-     * Typically the `id` attr of the header anchor
-     */
-    id: string;
-    /**
-     * The level of the header
-     *
-     * `1` to `6` for `<h1>` to `<h6>`
-     */
-    level: number;
-    /**
-     * The title of the header
-     */
-    title: string;
-    /**
-     * Link of the header
-     *
-     * Typically using `#${slug}` as the anchor hash
-     */
-    link: string;
-    /**
-     * The children of the header
-     */
-    children: MarkdownItHeader[];
+  /**
+   * The slug of the header
+   *
+   * Typically the `id` attr of the header anchor
+   */
+  id: string;
+  /**
+   * The level of the header
+   *
+   * `1` to `6` for `<h1>` to `<h6>`
+   */
+  level: number;
+  /**
+   * The title of the header
+   */
+  title: string;
+  /**
+   * Link of the header
+   *
+   * Typically using `#${slug}` as the anchor hash
+   */
+  link: string;
+  /**
+   * The children of the header
+   */
+  children: MarkdownItHeader[];
 }
-type ResolvePluginOptionsFn = <T extends object, K extends keyof any>(options: T | {
-    [P in K]?: T;
-} | undefined, key: K, defaults: T) => T;
-
+type ResolvePluginOptionsFn = <T extends object, K extends keyof any>(options: T | { [P in K]?: T; } | undefined, key: K, defaults: T) => T;
 interface ResolveTitleOptions {
-    /**
-     * Should allow inline HTML tags or not.
-     *
-     * If the result is going to be used as Vue template, it should allow inline
-     * HTML tags so that Vue custom components would be kept.
-     */
-    shouldAllowHtml: boolean;
-    /**
-     * Should escape the text content or not.
-     *
-     * If the result is going to be used in HTML directly, it should be escaped
-     * so that the text content won't be wrongly treated as HTML tags.
-     */
-    shouldEscapeText: boolean;
+  /**
+   * Should allow inline HTML tags or not.
+   *
+   * If the result is going to be used as Vue template, it should allow inline
+   * HTML tags so that Vue custom components would be kept.
+   */
+  shouldAllowHtml: boolean;
+  /**
+   * Should escape the text content or not.
+   *
+   * If the result is going to be used in HTML directly, it should be escaped
+   * so that the text content won't be wrongly treated as HTML tags.
+   */
+  shouldEscapeText: boolean;
 }
 /**
  * Extracts plain heading text from a markdown-it inline token.
@@ -69,28 +63,27 @@ interface ResolveTitleOptions {
  * are ignored so the title remains human-readable.
  */
 declare const resolveTitleFromToken: (token: Token, { shouldAllowHtml, shouldEscapeText }: ResolveTitleOptions) => string;
-
 interface ResolveHeadersOptions extends ResolveTitleOptions {
-    /**
-     * Heading level that going to be resolved
-     */
-    level: number[];
-    /**
-     * Should allow headers inside nested blocks or not
-     *
-     * If set to `true`, headers inside blockquote, list, etc. would also be resolved.
-     */
-    shouldAllowNested: boolean;
-    /**
-     * A custom slugification function
-     *
-     * Would be ignored if the `id` attr of the token is set.
-     */
-    slugify?: (str: string) => string;
-    /**
-     * A function for formatting headings
-     */
-    format?: (str: string) => string | undefined;
+  /**
+   * Heading level that going to be resolved
+   */
+  level: number[];
+  /**
+   * Should allow headers inside nested blocks or not
+   *
+   * If set to `true`, headers inside blockquote, list, etc. would also be resolved.
+   */
+  shouldAllowNested: boolean;
+  /**
+   * A custom slugification function
+   *
+   * Would be ignored if the `id` attr of the token is set.
+   */
+  slugify?: (str: string) => string;
+  /**
+   * A function for formatting headings
+   */
+  format?: (str: string) => string | undefined;
 }
 /**
  * Builds a nested heading tree from markdown-it heading tokens.
@@ -98,16 +91,14 @@ interface ResolveHeadersOptions extends ResolveTitleOptions {
  * Existing heading `id` attributes are preserved. When a heading has no `id`,
  * the configured `slugify` function creates one from the resolved heading text.
  */
-declare const resolveHeadersFromTokens: (tokens: Token[], { level, shouldAllowHtml, shouldAllowNested, shouldEscapeText, slugify, format, }?: Partial<ResolveHeadersOptions>) => MarkdownItHeader[];
-
+declare const resolveHeadersFromTokens: (tokens: Token[], { level, shouldAllowHtml, shouldAllowNested, shouldEscapeText, slugify, format }?: Partial<ResolveHeadersOptions>) => MarkdownItHeader[];
 /**
  * Converts arbitrary heading text into a stable URL-friendly slug.
  *
  * The result is lowercase, accent-free, hyphen-separated, and safe to use as a
  * generated Markdown heading id.
  */
-declare const slugify: (str: string) => string;
-
+declare const slugify$1: (str: string) => string;
 /**
  * Resolves plugin options from either a direct options object or a nested
  * package-level options bag.
@@ -116,9 +107,5 @@ declare const slugify: (str: string) => string;
  * or through a shared md-plugins config object keyed by plugin name. This helper
  * supports both shapes while applying default values.
  */
-declare function resolvePluginOptions<T extends object, K extends keyof any>(options: T | {
-    [key in K]?: T;
-} | undefined, key: K, defaults: T): T;
-
-export { htmlEscape, htmlUnescape, resolveHeadersFromTokens, resolvePluginOptions, resolveTitleFromToken, slugify };
-export type { MarkdownItEnv, MarkdownItHeader, ResolveHeadersOptions, ResolvePluginOptionsFn, ResolveTitleOptions };
+declare function resolvePluginOptions<T extends object, K extends keyof any>(options: T | { [key in K]?: T; } | undefined, key: K, defaults: T): T;
+export { type MarkdownItEnv, type MarkdownItHeader, ResolveHeadersOptions, type ResolvePluginOptionsFn, ResolveTitleOptions, htmlEscape, htmlUnescape, resolveHeadersFromTokens, resolvePluginOptions, resolveTitleFromToken, slugify$1 as slugify };

package/dist/index.mjs

@@ -1,103 +1,102 @@
 const htmlEscapeMap = {
-  "&": "&",
-  "<": "&lt;",
-  ">": "&gt;",
-  "'": "&#39;",
-  '"': "&quot;"
+	"&": "&amp;",
+	"<": "&lt;",
+	">": "&gt;",
+	"'": "&#39;",
+	"\"": "&quot;"
 };
 const htmlEscapeRegexp = /[&<>'"]/g;
+
 const htmlEscape = (str) => str.replace(htmlEscapeRegexp, (char) => htmlEscapeMap[char]);
 
 const htmlUnescapeMap = {
-  "&amp;": "&",
-  "&#38;": "&",
-  "&lt;": "<",
-  "&#60;": "<",
-  "&gt;": ">",
-  "&#62;": ">",
-  "&apos;": "'",
-  "&#39;": "'",
-  "&quot;": '"',
-  "&#34;": '"'
+	"&amp;": "&",
+	"&#38;": "&",
+	"&lt;": "<",
+	"&#60;": "<",
+	"&gt;": ">",
+	"&#62;": ">",
+	"&apos;": "'",
+	"&#39;": "'",
+	"&quot;": "\"",
+	"&#34;": "\""
 };
 const htmlUnescapeRegexp = /&(amp|#38|lt|#60|gt|#62|apos|#39|quot|#34);/g;
+
 const htmlUnescape = (str) => str.replace(htmlUnescapeRegexp, (char) => htmlUnescapeMap[char]);
 
+
 const resolveTitleFromToken = (token, { shouldAllowHtml, shouldEscapeText }) => {
-  const children = token.children ?? [];
-  const titleTokenTypes = ["text", "emoji", "code_inline"];
-  if (shouldAllowHtml) {
-    titleTokenTypes.push("html_inline");
-  }
-  const titleTokens = children.filter(
-    (item) => titleTokenTypes.includes(item.type) && // filter permalink symbol that generated by markdown-it-anchor
-    !item.meta?.isPermalinkSymbol
-  );
-  return titleTokens.reduce((result, item) => {
-    if (shouldEscapeText) {
-      if (item.type === "code_inline" || item.type === "text") {
-        return `${result}${htmlEscape(item.content)}`;
-      }
-    }
-    return `${result}${item.content}`;
-  }, "").trim();
+	const children = token.children ?? [];
+	const titleTokenTypes = [
+		"text",
+		"emoji",
+		"code_inline"
+	];
+	if (shouldAllowHtml) titleTokenTypes.push("html_inline");
+	return children.filter((item) => titleTokenTypes.includes(item.type) && !item.meta?.isPermalinkSymbol).reduce((result, item) => {
+		if (shouldEscapeText) {
+			if (item.type === "code_inline" || item.type === "text") return `${result}${htmlEscape(item.content)}`;
+		}
+		return `${result}${item.content}`;
+	}, "").trim();
 };
 
 const andRE = /&/g;
 const rCombining = /[\u0300-\u036F]/g;
 const rControl = /[\u0000-\u001f]/g;
 const rSpecial = /[\s~`!@#$%^&*()\-_+=[\]{}|\\;:"'“”‘’<>,.?/]+/g;
+
 const slugify = (str) => str.trim().replace(/([a-z])([A-Z])/g, "$1-$2").replace(/[\s_]+/g, "-").toLowerCase().normalize("NFKD").replace(rCombining, "").replace(andRE, "-and-").replace(rControl, "-").replace(rSpecial, "-").replace(/[^a-z0-9-]+/g, "").replace(/([a-z])(\d)/g, "$1-$2").replace(/(\d)([a-z])/g, "$1-$2").replace(/-{2,}/g, "-").replace(/(^-|-$)/g, "").replace(/^(\d)/, "_$1");
 
-const resolveHeadersFromTokens = (tokens, {
-  level = [1, 2, 3],
-  shouldAllowHtml = false,
-  shouldAllowNested = false,
-  shouldEscapeText = false,
-  slugify: slugify$1 = slugify,
-  format = (str) => str
-} = {}) => {
-  const headers = [];
-  const stack = [];
-  const pushHeader = (header) => {
-    while (stack.length > 0 && header.level <= stack[0].level) {
-      stack.shift();
-    }
-    if (stack.length === 0) {
-      headers.push(header);
-    } else {
-      stack[0].children.push(header);
-    }
-    stack.unshift(header);
-  };
-  tokens.forEach((token, i) => {
-    if (token.type !== "heading_open") return;
-    if (token.level !== 0 && !shouldAllowNested) return;
-    const headerLevel = Number.parseInt(token.tag.slice(1), 10);
-    if (!level.includes(headerLevel)) return;
-    const nextToken = tokens[i + 1];
-    if (!nextToken) return;
-    const title = resolveTitleFromToken(nextToken, {
-      shouldAllowHtml,
-      shouldEscapeText
-    });
-    const slug = token.attrGet("id") ?? slugify$1(title);
-    pushHeader({
-      level: headerLevel,
-      title: format(title) ?? title,
-      id: slug,
-      link: `#${slug}`,
-      children: []
-    });
-  });
-  return headers;
+
+const resolveHeadersFromTokens = (tokens, { level = [
+	1,
+	2,
+	3
+], shouldAllowHtml = false, shouldAllowNested = false, shouldEscapeText = false, slugify: slugify$1 = slugify, format = (str) => str } = {}) => {
+	const headers = [];
+	const stack = [];
+	
+	const pushHeader = (header) => {
+		while (stack.length > 0 && header.level <= stack[0].level) stack.shift();
+		if (stack.length === 0) headers.push(header);
+		else stack[0].children.push(header);
+		stack.unshift(header);
+	};
+	tokens.forEach((token, i) => {
+		if (token.type !== "heading_open") return;
+		if (token.level !== 0 && !shouldAllowNested) return;
+		const headerLevel = Number.parseInt(token.tag.slice(1), 10);
+		if (!level.includes(headerLevel)) return;
+		const nextToken = tokens[i + 1];
+		if (!nextToken) return;
+		const title = resolveTitleFromToken(nextToken, {
+			shouldAllowHtml,
+			shouldEscapeText
+		});
+		const slug = token.attrGet("id") ?? slugify$1(title);
+		pushHeader({
+			level: headerLevel,
+			title: format(title) ?? title,
+			id: slug,
+			link: `#${slug}`,
+			children: []
+		});
+	});
+	return headers;
 };
 
+
 function resolvePluginOptions(options, key, defaults) {
-  if (options && typeof options === "object" && key in options) {
-    return { ...defaults, ...options[key] };
-  }
-  return { ...defaults, ...options };
+	if (options && typeof options === "object" && key in options) return {
+		...defaults,
+		...options[key]
+	};
+	return {
+		...defaults,
+		...options
+	};
 }
 
-export { htmlEscape, htmlUnescape, resolveHeadersFromTokens, resolvePluginOptions, resolveTitleFromToken, slugify };
+export { htmlEscape, htmlUnescape, resolveHeadersFromTokens, resolvePluginOptions, resolveTitleFromToken, slugify };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@md-plugins/shared",
-  "version": "0.1.0-rc.9",
+  "version": "1.1.0",
   "description": "Shared functions and utilities for md-plugins.",
   "keywords": [
     "markdown-it",
@@ -37,13 +37,13 @@
   },
   "devDependencies": {
     "@types/markdown-it": "^14.1.2",
-    "markdown-it": "^14.2.0"
+    "markdown-it": "^14.3.0"
   },
   "peerDependencies": {
     "markdown-it": "^14.2.0"
   },
   "scripts": {
-    "build": "unbuild",
+    "build": "obuild && node ../../scripts/ensure-obuild-types.mjs",
     "clean": "rm -rf dist/ node_modules/",
     "test": "vitest"
   }