add: centralize exports to svgo (#2071)

svg · Sep 7, 2024 · 97d7d00 · 97d7d00
1 parent 50fc3c9
commit 97d7d00
Show file tree

Hide file tree

Showing 8 changed files with 192 additions and 24 deletions.
diff --git a/eslint.config.mjs b/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: [

diff --git a/lib/svgo-node.js b/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,
 };
diff --git a/lib/svgo.d.ts b/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[];
diff --git a/lib/svgo.js b/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,
 };
diff --git a/lib/xast.js b/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);

diff --git a/plugins/_collections.js b/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,
- * or semantic meaning.
- *
- * @see https://developer.mozilla.org/docs/Web/HTML/Element/pre
+ * @see svgo#_collections
  */
 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,
+};