add: centralize exports to svgo (#2071)

eslint.config.mjs

@@ -2,10 +2,10 @@ import js from '@eslint/js';
 import globals from 'globals';
 
 /**
- * @typedef {import('eslint').Linter.FlatConfig} FlatConfig
+ * @typedef {import('eslint').Linter.Config} Config
  */
 
-/** @type {FlatConfig[]} */
+/** @type {Config[]} */
 export default [
   {
     ignores: [

lib/svgo-node.js

@@ -6,6 +6,9 @@ import {
   VERSION,
   optimize as optimizeAgnostic,
   builtinPlugins,
+  querySelector,
+  querySelectorAll,
+  _collections,
 } from './svgo.js';
 
 const importConfig = async (configFile) => {
@@ -29,7 +32,13 @@ const isFile = async (file) => {
   }
 };
 
-export { VERSION, builtinPlugins };
+export {
+  VERSION,
+  builtinPlugins,
+  querySelector,
+  querySelectorAll,
+  _collections,
+};
 
 export const loadConfig = async (configFile, cwd = process.cwd()) => {
   if (configFile != null) {
@@ -84,4 +93,7 @@ export default {
   builtinPlugins,
   loadConfig,
   optimize,
+  querySelector,
+  querySelectorAll,
+  _collections,
 };

lib/svgo.d.ts

@@ -1,4 +1,10 @@
-import type { StringifyOptions, DataUri, Plugin } from './types.js';
+import type {
+  StringifyOptions,
+  DataUri,
+  Plugin,
+  XastChild,
+  XastNode,
+} from './types.js';
 import type {
   BuiltinsWithOptionalParams,
   BuiltinsWithRequiredParams,
@@ -34,7 +40,10 @@ type BuiltinPlugin<Name, Params> = {
   fn: Plugin<Params>;
 };
 
-type BuiltinPluginOrPreset<Name, Params> = BuiltinPlugin<Name, Params> & {
+export type BuiltinPluginOrPreset<Name, Params> = BuiltinPlugin<
+  Name,
+  Params
+> & {
   /** If the plugin is itself a preset that invokes other plugins. */
   isPreset: true | undefined;
   /**
@@ -83,8 +92,98 @@ type Output = {
   data: string;
 };
 
+export declare const _collections: {
+  elemsGroups: Readonly<Record<string, Set<string>>>;
+  /**
+   * Elements where adding or removing whitespace may effect rendering, metadata,
+   * or semantic meaning.
+   *
+   * @see https://developer.mozilla.org/docs/Web/HTML/Element/pre
+   */
+  textElems: Readonly<Set<string>>;
+  pathElems: Readonly<Set<string>>;
+  /**
+   * @see https://www.w3.org/TR/SVG11/intro.html#Definitions
+   */
+  attrsGroups: Readonly<Record<string, Set<string>>>;
+  attrsGroupsDefaults: Readonly<Record<string, Record<string, string>>>;
+  /**
+   * @see https://www.w3.org/TR/SVG11/intro.html#Definitions
+   */
+  attrsGroupsDeprecated: Readonly<
+    Record<string, { safe?: Set<string>; unsafe?: Set<string> }>
+  >;
+  /**
+   * @see https://www.w3.org/TR/SVG11/eltindex.html
+   */
+  elems: Readonly<
+    Record<
+      string,
+      {
+        attrsGroups: Set<string>;
+        attrs?: Set<string>;
+        defaults?: Record<string, string>;
+        deprecated?: {
+          safe?: Set<string>;
+          unsafe?: Set<string>;
+        };
+        contentGroups?: Set<string>;
+        content?: Set<string>;
+      }
+    >
+  >;
+  /**
+   * @see https://wiki.inkscape.org/wiki/index.php/Inkscape-specific_XML_attributes
+   */
+  editorNamespaces: Readonly<Set<string>>;
+  /**
+   * @see https://www.w3.org/TR/SVG11/linking.html#processingIRI
+   */
+  referencesProps: Readonly<Set<string>>;
+  /**
+   * @see https://www.w3.org/TR/SVG11/propidx.html
+   */
+  inheritableAttrs: Readonly<Set<string>>;
+  presentationNonInheritableGroupAttrs: Readonly<Set<string>>;
+  /**
+   * @see https://www.w3.org/TR/SVG11/single-page.html#types-ColorKeywords
+   */
+  colorsNames: Readonly<Record<string, string>>;
+  colorsShortNames: Readonly<Record<string, string>>;
+  /**
+   * @see https://www.w3.org/TR/SVG11/single-page.html#types-DataTypeColor
+   */
+  colorsProps: Readonly<Set<string>>;
+  /**
+   * @see https://developer.mozilla.org/docs/Web/CSS/Pseudo-classes
+   */
+  pseudoClasses: Readonly<Record<string, Set<string>>>;
+};
+
+export type * from './types.d.ts';
+
 /** Installed version of SVGO. */
 export declare const VERSION: string;
 
 /** The core of SVGO */
 export declare function optimize(input: string, config?: Config): Output;
+
+/**
+ * @param node Element to query the children of.
+ * @param selector CSS selector string.
+ * @returns First match, or null if there was no match.
+ */
+export declare function querySelector(
+  node: XastNode,
+  selector: string,
+): XastChild | null;
+
+/**
+ * @param node Element to query the children of.
+ * @param selector CSS selector string.
+ * @returns All matching elements.
+ */
+export declare function querySelectorAll(
+  node: XastNode,
+  selector: string,
+): XastChild[];

lib/svgo.js

@@ -4,6 +4,8 @@ import { builtin } from './builtin.js';
 import { invokePlugins } from './svgo/plugins.js';
 import { encodeSVGDatauri } from './svgo/tools.js';
 import { VERSION } from './version.js';
+import { querySelector, querySelectorAll } from './xast.js';
+import _collections from '../plugins/_collections.js';
 
 /**
  * @typedef {import('./svgo.js').BuiltinPluginOrPreset<?, ?>} BuiltinPluginOrPreset
@@ -65,7 +67,13 @@ const resolvePluginConfig = (plugin) => {
   return null;
 };
 
-export { VERSION, builtin as builtinPlugins };
+export {
+  VERSION,
+  builtin as builtinPlugins,
+  querySelector,
+  querySelectorAll,
+  _collections,
+};
 
 export const optimize = (input, config) => {
   if (config == null) {
@@ -124,4 +132,7 @@ export default {
   VERSION,
   optimize,
   builtinPlugins: builtin,
+  querySelector,
+  querySelectorAll,
+  _collections,
 };

lib/xast.js

@@ -6,6 +6,8 @@ import xastAdaptor from './svgo/css-select-adapter.js';
  * @typedef {import('./types.js').XastChild} XastChild
  * @typedef {import('./types.js').XastParent} XastParent
  * @typedef {import('./types.js').Visitor} Visitor
+ * @typedef {import('./svgo.ts').querySelector} querySelector
+ * @typedef {import('./svgo.ts').querySelectorAll} querySelectorAll
  */
 
 const cssSelectOptions = {
@@ -14,14 +16,14 @@ const cssSelectOptions = {
 };
 
 /**
- * @type {(node: XastNode, selector: string) => XastChild[]}
+ * @type {querySelectorAll}
  */
 export const querySelectorAll = (node, selector) => {
   return selectAll(selector, node, cssSelectOptions);
 };
 
 /**
- * @type {(node: XastNode, selector: string) => ?XastChild}
+ * @type {querySelector}
  */
 export const querySelector = (node, selector) => {
   return selectOne(selector, node, cssSelectOptions);

plugins/_collections.js

@@ -1,7 +1,12 @@
 // https://www.w3.org/TR/SVG11/intro.html#Definitions
 
+/**
+ * @typedef {import('../lib/svgo.ts')} svgo
+ */
+
 /**
  * @type {Record<string, Set<string>>}
+ * @see svgo#_collections
  */
 export const elemsGroups = {
   animation: new Set([
@@ -101,18 +106,18 @@ export const elemsGroups = {
 };
 
 /**
- * Elements where adding or removing whitespace may effect rendering, metadata,
+ * @see svgo#_collections
- * or semantic meaning.
- *
- * @see https://developer.mozilla.org/docs/Web/HTML/Element/pre
  */
 export const textElems = new Set([...elemsGroups.textContent, 'pre', 'title']);
 
+/**
+ * @see svgo#_collections
+ */
 export const pathElems = new Set(['glyph', 'missing-glyph', 'path']);
 
 /**
  * @type {Record<string, Set<string>>}
- * @see https://www.w3.org/TR/SVG11/intro.html#Definitions
+ * @see svgo#_collections
  */
 export const attrsGroups = {
   animationAddition: new Set(['additive', 'accumulate']),
@@ -311,6 +316,7 @@ export const attrsGroups = {
 
 /**
  * @type {Record<string, Record<string, string>>}
+ * @see svgo#_collections
  */
 export const attrsGroupsDefaults = {
   core: { 'xml:space': 'default' },
@@ -378,7 +384,7 @@ export const attrsGroupsDefaults = {
 
 /**
  * @type {Record<string, { safe?: Set<string>, unsafe?: Set<string> }>}
- * @see https://www.w3.org/TR/SVG11/intro.html#Definitions
+ * @see svgo#_collections
  */
 export const attrsGroupsDeprecated = {
   animationAttributeTarget: { unsafe: new Set(['attributeType']) },
@@ -408,7 +414,7 @@ export const attrsGroupsDeprecated = {
  *   contentGroups?: Set<string>,
  *   content?: Set<string>,
  * }>}
- * @see https://www.w3.org/TR/SVG11/eltindex.html
+ * @see svgo#_collections
  */
 export const elems = {
   a: {
@@ -2067,7 +2073,9 @@ export const elems = {
   },
 };
 
-// https://wiki.inkscape.org/wiki/index.php/Inkscape-specific_XML_attributes
+/**
+ * @see svgo#_collections
+ */
 export const editorNamespaces = new Set([
   'http://creativecommons.org/ns#',
   'http://inkscape.sourceforge.net/DTD/sodipodi-0.dtd',
@@ -2094,7 +2102,7 @@ export const editorNamespaces = new Set([
 ]);
 
 /**
- * @see https://www.w3.org/TR/SVG11/linking.html#processingIRI
+ * @see svgo#_collections
  */
 export const referencesProps = new Set([
   'clip-path',
@@ -2110,7 +2118,7 @@ export const referencesProps = new Set([
 ]);
 
 /**
- * @see https://www.w3.org/TR/SVG11/propidx.html
+ * @see svgo#_collections
  */
 export const inheritableAttrs = new Set([
   'clip-rule',
@@ -2172,9 +2180,8 @@ export const presentationNonInheritableGroupAttrs = new Set([
 ]);
 
 /**
- * https://www.w3.org/TR/SVG11/single-page.html#types-ColorKeywords
- *
  * @type {Record<string, string>}
+ * @see svgo#_collections
  */
 export const colorsNames = {
   aliceblue: '#f0f8ff',
@@ -2366,7 +2373,7 @@ export const colorsShortNames = {
 };
 
 /**
- * @see https://www.w3.org/TR/SVG11/single-page.html#types-DataTypeColor
+ * @see svgo#_collections
  */
 export const colorsProps = new Set([
   'color',
@@ -2377,7 +2384,9 @@ export const colorsProps = new Set([
   'stroke',
 ]);
 
-/** @see https://developer.mozilla.org/docs/Web/CSS/Pseudo-classes */
+/**
+ * @see svgo#_collections
+ */
 export const pseudoClasses = {
   displayState: new Set(['fullscreen', 'modal', 'picture-in-picture']),
   input: new Set([
@@ -2434,3 +2443,21 @@ export const pseudoClasses = {
   ]),
   functional: new Set(['is', 'not', 'where', 'has']),
 };
+
+export default {
+  elemsGroups,
+  textElems,
+  pathElems,
+  attrsGroups,
+  attrsGroupsDefaults,
+  attrsGroupsDeprecated,
+  elems,
+  editorNamespaces,
+  referencesProps,
+  inheritableAttrs,
+  presentationNonInheritableGroupAttrs,
+  colorsNames,
+  colorsShortNames,
+  colorsProps,
+  pseudoClasses,
+};

test/browser.js

@@ -30,13 +30,14 @@ const expected = `<svg xmlns="http://www.w3.org/2000/svg">
 
 const content = `
 <script type="module">
-import { VERSION, optimize, builtinPlugins } from '/svgo.browser.js';
+import { VERSION, optimize, builtinPlugins, _collections } from '/svgo.browser.js';
 const result = optimize(${JSON.stringify(fixture)}, {
   plugins : [],
   js2svg  : { pretty: true, indent: 2 }
 });
 globalThis.version = VERSION;
 globalThis.builtinPlugins = builtinPlugins;
+globalThis._collections = _collections;
 globalThis.result = result.data;
 </script>
 `;
@@ -62,11 +63,21 @@ const runTest = async () => {
   const actual = await page.evaluate(() => ({
     version: globalThis.version,
     builtinPlugins: globalThis.builtinPlugins,
+    _collections: globalThis._collections,
     result: globalThis.result,
   }));
 
   assert.strictEqual(actual.version, version);
-  assert.notEqual(actual.builtinPlugins, undefined);
+  assert.notEqual(
+    actual.builtinPlugins,
+    undefined,
+    'builtinPlugins must be defined',
+  );
+  assert.notEqual(
+    actual._collections,
+    undefined,
+    '_collections must be defined',
+  );
   assert.equal(actual.result, expected);
 
   await browser.close();

test/svgo.cjs

@@ -4,6 +4,9 @@ const {
   optimize,
   builtinPlugins,
   loadConfig,
+  querySelector,
+  querySelectorAll,
+  _collections,
 } = require('../dist/svgo-node.cjs');
 const PKG = require('../package.json');
 
@@ -37,6 +40,9 @@ const runTest = () => {
   assert.equal(actual, expected);
   assert.notEqual(builtinPlugins, undefined);
   assert.notEqual(loadConfig, undefined);
+  assert.notEqual(querySelector, undefined);
+  assert.notEqual(querySelectorAll, undefined);
+  assert.notEqual(_collections, undefined);
 };
 
 runTest();