svg-icon-baker 1.2.1 → 2.0.1

package/README.md

@@ -2,49 +2,196 @@
 
 > Bake the `svg` icon into `symbol` 🍪
 
-The core library for transforming SVG icons into optimized SVG symbol sprites.
+`svg-icon-baker` is the core library for transforming SVG icons into optimized SVG symbol sprites.
+It converts SVG content into `<symbol>` markup for SVG sprite usage while preserving structure and handling local id references safely across multiple icons.
 
-If you like this project, please give it a [Star](https://github.com/yangxu52/svg-icon-baker).
+## Installation
+
+```bash
+pnpm add svg-icon-baker
+```
 
 ## Usage
 
 ```ts
-import { bakeIcon, bakeIcons } from 'svg-icon-baker'
+import { bakeIcon, bakeIcons, createBaker } from 'svg-icon-baker'
+
+const source = {
+  name: 'icon-home',
+  content: '<svg viewBox="0 0 16 16"><path d="..."/></svg>',
+}
 
-const source = { name: 'home', content: '<svg viewBox="0 0 16 16">...</svg>' }
 const result = bakeIcon(source)
-// result: { name: 'home', content: '<symbol id="home" viewBox="0 0 16 16">...</symbol>' }
 
-const results = bakeIcons([source])
+console.log(result)
+// {
+//   name: 'icon-home',
+//   content: '<symbol id="icon-home" viewBox="0 0 16 16">...</symbol>',
+//   issues: []
+// }
+
+const batch = bakeIcons([source])
+
+const baker = createBaker({
+  idPolicy: { idStyle: 'named', delim: '_' },
+})
+
+const reused = baker.bakeIcon(source)
 ```
 
-`bakeIcon` and `bakeIcons` are synchronous.
+`bakeIcon`, `bakeIcons`, and `createBaker(...).bakeIcon()` are synchronous.
 
 ## API
 
 ### `bakeIcon(source: BakeSource, options?: Options): BakeResult`
 
-Convert one SVG into one symbol result.
+Convert one SVG input into one symbol result.
 
 ### `bakeIcons(sources: BakeSource[], options?: Options): BakeResult[]`
 
-Convert multiple SVG inputs with one inferred option set.
+Convert multiple SVG inputs with one resolved option set.
+
+### `createBaker(options?: Options): Baker`
+
+Create a reusable baker instance with one resolved option set.
+This is the preferred API when the same options are applied to many icons.
+
+```ts
+type Baker = {
+  bakeIcon(source: BakeSource): BakeResult
+  bakeIcons(sources: BakeSource[]): BakeResult[]
+}
+```
+
+## Return Value
+
+```ts
+type BakeResult = {
+  name: string
+  content: string
+  issues: BakeIssue[]
+}
+```
+
+- `name` is the original source name.
+- `content` is the generated `<symbol>...</symbol>` markup.
+- `issues` contains non-fatal diagnostics. Conversion still succeeds when issues are reported.
 
 ## Options
 
-| name          | type          | default | description                                      |
-| ------------- | ------------- | ------- | ------------------------------------------------ |
-| `optimize`    | `boolean`     | `true`  | Enable default safe SVGO optimization preset.    |
-| `svgoOptions` | `SvgoOptions` | `{}`    | Custom SVGO options into the optimization layer. |
+| name          | type              | default                                                                    | description                                  |
+| ------------- | ----------------- | -------------------------------------------------------------------------- | -------------------------------------------- |
+| `optimize`    | `boolean`         | `true`                                                                     | Enable the built-in safe SVGO optimization.  |
+| `svgoOptions` | `SvgoOptions`     | `{}`                                                                       | Merge custom SVGO options into optimization. |
+| `idPolicy`    | `IdPolicyOptions` | `{ rewrite: true, unresolved: 'prefix', idStyle: 'minified', delim: '_' }` | Control local id rewriting for sprite use.   |
+
+### `idPolicy`
+
+```ts
+type IdPolicyOptions = {
+  rewrite?: boolean
+  unresolved?: 'prefix' | 'preserve'
+  idStyle?: 'named' | 'minified' | 'hashed'
+  delim?: '-' | '_'
+}
+```
+
+| name         | type                                | default      | description                                                                                                                          |
+| ------------ | ----------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `rewrite`    | `boolean`                           | `true`       | Rewrite local ids and local references for sprite safety.                                                                            |
+| `unresolved` | `'prefix' \| 'preserve'`            | `'prefix'`   | For unresolved local references, either rewrite them into the icon namespace or keep them unchanged. Both behaviors report an issue. |
+| `idStyle`    | `'named' \| 'minified' \| 'hashed'` | `'minified'` | Choose readable ids such as `icon_home`, short ids such as `icon_a`, or hashed ids such as `icon_dgxZM` (base62 characters).         |
+| `delim`      | `'-' \| '_'`                        | `'_'`        | Separator between the icon name and the generated id part.                                                                           |
+
+## Diagnostics
+
+### Issues
+
+```ts
+type BakeIssue = {
+  code: 'ResolveReferenceFailed' | 'DetectDefinitionDuplicate' | 'DetectReferenceCarrierUnsupported' | 'ParseStyleFailed'
+  message: string
+  targetId?: string
+}
+```
+
+Issues are returned in `BakeResult.issues` instead of throwing.
+Currently emitted issue codes include:
+
+- unresolved local references
+- duplicate local definitions
+- style content that cannot be safely parsed
+
+`ParseStyleFailed` means one or more `<style>` blocks could not be safely parsed.
+In that case, the original style content is preserved and conversion still succeeds.
+
+`DetectReferenceCarrierUnsupported` is reserved for unsupported local reference carriers.
+It is part of the public type contract, but it is not currently emitted by the implementation.
+
+Example:
 
-Notes:
+```ts
+const result = bakeIcon(
+  {
+    name: 'icon-alert',
+    content: '<svg viewBox="0 0 16 16"><use href="#ghost"/></svg>',
+  },
+  {
+    idPolicy: { unresolved: 'preserve' },
+  }
+)
+
+console.log(result.issues)
+// [
+//   {
+//     code: 'ResolveReferenceFailed',
+//     message: 'Resolve reference failed for local target "ghost"; reference was preserved.',
+//     targetId: 'ghost'
+//   }
+// ]
+```
+
+### Errors
+
+Fatal failures throw `BakeError`.
+
+```ts
+class BakeError extends Error {
+  code: 'ValidateSourceInvalid' | 'ValidateNameInvalid' | 'ValidateSvgRootInvalid' | 'ParseSvgFailed' | 'OptimizeSvgFailed' | 'ResolveViewBoxFailed'
+  cause?: unknown
+}
+```
 
-- Behavior matrix:
-  - `optimize: true` + no `svgoOptions`: run default safe optimization.
-  - `optimize: true` + `svgoOptions`: run default safe optimization, then merge custom options.
-  - `optimize: false` + no `svgoOptions`: skip optimization layer.
-  - `optimize: false` + `svgoOptions`: run custom optimization settings only.
-- When `svgoOptions.plugins` is provided, custom plugins run after default safe optimization plugins.
+Typical fatal cases:
+
+- missing `name` or `content`
+- invalid icon names
+- input that does not start with an `<svg>` root
+- malformed SVG that cannot be parsed for rewriting
+- SVGO plugin failures
+- output where `viewBox` cannot be determined
+
+## SVGO Behavior
+
+`svg-icon-baker` uses SVGO as an optimization layer after conversion preparation.
+
+- When `optimize` is `true`, the package applies a built-in safe preset.
+- User `svgoOptions` are merged into that optimization step.
+- `removeDimensions` is always applied so the output keeps `viewBox` as the sizing contract.
+- User-supplied `prefixIds` and `cleanupIds` plugins are ignored to keep id rewriting behavior stable.
+
+This means local id handling is controlled through `idPolicy`, not through external SVGO id plugins.
+
+## Output Guarantees
+
+On success, the output keeps these behaviors:
+
+- the root is always `<symbol>...</symbol>`
+- the symbol root `id` equals `source.name`
+- `viewBox` is required in the final output
+- root `width` and `height` are removed
+- non-structural root attributes such as `fill` are preserved
+- XML declarations, BOM, comments, and doctype preamble are stripped
 
 ## Type Definitions
 
@@ -59,22 +206,39 @@ type BakeSource = {
 type BakeResult = {
   name: string
   content: string
+  issues: BakeIssue[]
 }
 
+type BakeIssue = {
+  code: 'ResolveReferenceFailed' | 'DetectDefinitionDuplicate' | 'DetectReferenceCarrierUnsupported' | 'ParseStyleFailed'
+  message: string
+  targetId?: string
+}
+
+type BakeErrorCode =
+  | 'ValidateSourceInvalid'
+  | 'ValidateNameInvalid'
+  | 'ValidateSvgRootInvalid'
+  | 'ParseSvgFailed'
+  | 'OptimizeSvgFailed'
+  | 'ResolveViewBoxFailed'
+
 type SvgoOptions = Pick<Config, 'multipass' | 'floatPrecision' | 'js2svg' | 'plugins'>
 
+type IdPolicyOptions = {
+  rewrite?: boolean
+  unresolved?: 'prefix' | 'preserve'
+  idStyle?: 'named' | 'minified' | 'hashed'
+  delim?: '-' | '_'
+}
+
 type Options = {
   optimize?: boolean
   svgoOptions?: SvgoOptions
+  idPolicy?: IdPolicyOptions
 }
 ```
 
-## Features
-
-- Optimization: Reduce file size, and improve efficiency through `SVGO`
-- Reference Handling: ID and reference prefixing for sprite safety
-- Size Unify: `viewBox` preservation or inference from root dimensions
-
 ## License
 
 MIT © [yangxu52](https://github.com/yangxu52/svg-icon-baker/blob/main/LICENSE)

package/dist/index.d.mts

@@ -4,9 +4,34 @@ type BakeSource = {
     name: string;
     content: string;
 };
+type BakeIssueCode = 'ResolveReferenceFailed' | 'DetectDefinitionDuplicate' | 'DetectReferenceCarrierUnsupported' | 'ParseStyleFailed';
+type BakeIssue = {
+    code: BakeIssueCode;
+    message: string;
+    targetId?: string;
+};
+type BakeErrorCode = 'ValidateSourceInvalid' | 'ValidateNameInvalid' | 'ValidateSvgRootInvalid' | 'ParseSvgFailed' | 'OptimizeSvgFailed' | 'ResolveViewBoxFailed';
+declare class BakeError extends Error {
+    readonly code: BakeErrorCode;
+    readonly cause?: unknown;
+    constructor(code: BakeErrorCode, message: string, options?: {
+        cause?: unknown;
+    });
+}
+type IdPolicyOptions = {
+    rewrite?: boolean;
+    unresolved?: 'prefix' | 'preserve';
+    idStyle?: 'named' | 'minified' | 'hashed';
+    delim?: '-' | '_';
+};
 type BakeResult = {
     name: string;
     content: string;
+    issues: BakeIssue[];
+};
+type Baker = {
+    bakeIcon(source: BakeSource): BakeResult;
+    bakeIcons(sources: BakeSource[]): BakeResult[];
 };
 type SvgoOptions = Pick<Config, 'multipass' | 'floatPrecision' | 'js2svg' | 'plugins'>;
 type Options = {
@@ -19,10 +44,16 @@ type Options = {
      * custom svgo options merged into optimizer
      */
     svgoOptions?: SvgoOptions;
+    /**
+     * sprite-safe local id rewriting
+     * @default { rewrite: true, unresolved: 'prefix', idStyle: 'minified', delim: '_' }
+     */
+    idPolicy?: IdPolicyOptions;
 };
 
 declare function bakeIcon(source: BakeSource, options?: Options): BakeResult;
 declare function bakeIcons(sources: BakeSource[], options?: Options): BakeResult[];
+declare function createBaker(options?: Options): Baker;
 
-export { bakeIcon, bakeIcons };
-export type { BakeResult, BakeSource, Options, SvgoOptions };
+export { BakeError, bakeIcon, bakeIcons, createBaker };
+export type { BakeErrorCode, BakeIssue, BakeIssueCode, BakeResult, BakeSource, Baker, IdPolicyOptions, Options, SvgoOptions };

package/dist/index.d.ts

@@ -4,9 +4,34 @@ type BakeSource = {
     name: string;
     content: string;
 };
+type BakeIssueCode = 'ResolveReferenceFailed' | 'DetectDefinitionDuplicate' | 'DetectReferenceCarrierUnsupported' | 'ParseStyleFailed';
+type BakeIssue = {
+    code: BakeIssueCode;
+    message: string;
+    targetId?: string;
+};
+type BakeErrorCode = 'ValidateSourceInvalid' | 'ValidateNameInvalid' | 'ValidateSvgRootInvalid' | 'ParseSvgFailed' | 'OptimizeSvgFailed' | 'ResolveViewBoxFailed';
+declare class BakeError extends Error {
+    readonly code: BakeErrorCode;
+    readonly cause?: unknown;
+    constructor(code: BakeErrorCode, message: string, options?: {
+        cause?: unknown;
+    });
+}
+type IdPolicyOptions = {
+    rewrite?: boolean;
+    unresolved?: 'prefix' | 'preserve';
+    idStyle?: 'named' | 'minified' | 'hashed';
+    delim?: '-' | '_';
+};
 type BakeResult = {
     name: string;
     content: string;
+    issues: BakeIssue[];
+};
+type Baker = {
+    bakeIcon(source: BakeSource): BakeResult;
+    bakeIcons(sources: BakeSource[]): BakeResult[];
 };
 type SvgoOptions = Pick<Config, 'multipass' | 'floatPrecision' | 'js2svg' | 'plugins'>;
 type Options = {
@@ -19,10 +44,16 @@ type Options = {
      * custom svgo options merged into optimizer
      */
     svgoOptions?: SvgoOptions;
+    /**
+     * sprite-safe local id rewriting
+     * @default { rewrite: true, unresolved: 'prefix', idStyle: 'minified', delim: '_' }
+     */
+    idPolicy?: IdPolicyOptions;
 };
 
 declare function bakeIcon(source: BakeSource, options?: Options): BakeResult;
 declare function bakeIcons(sources: BakeSource[], options?: Options): BakeResult[];
+declare function createBaker(options?: Options): Baker;
 
-export { bakeIcon, bakeIcons };
-export type { BakeResult, BakeSource, Options, SvgoOptions };
+export { BakeError, bakeIcon, bakeIcons, createBaker };
+export type { BakeErrorCode, BakeIssue, BakeIssueCode, BakeResult, BakeSource, Baker, IdPolicyOptions, Options, SvgoOptions };

package/dist/index.mjs

@@ -1,28 +1,599 @@
 import { optimize } from 'svgo';
+import XMLBuilder from 'fast-xml-builder';
+import { XMLParser } from 'fast-xml-parser';
+import * as csstree from 'css-tree';
 
+const parser = new XMLParser({
+  preserveOrder: true,
+  ignoreAttributes: false,
+  attributeNamePrefix: "",
+  trimValues: false,
+  parseTagValue: false,
+  parseAttributeValue: false,
+  commentPropName: "#comment",
+  cdataPropName: "#cdata"
+});
+const builder = new XMLBuilder({
+  preserveOrder: true,
+  ignoreAttributes: false,
+  attributeNamePrefix: "",
+  suppressEmptyNode: true,
+  commentPropName: "#comment",
+  cdataPropName: "#cdata"
+});
+function parseSvg(code) {
+  return parser.parse(code);
+}
+function buildSvg(document) {
+  return builder.build(document);
+}
+function visitElements(document, visit) {
+  for (const node of document) {
+    visitNode(node, visit);
+  }
+}
+function visitNode(node, visit) {
+  const entry = getElementEntry(node);
+  if (!entry) {
+    return;
+  }
+  visit(entry.name, entry.node, entry.attrs);
+  for (const child of entry.children) {
+    visitNode(child, visit);
+  }
+}
+function getElementEntry(node) {
+  if (isMetaNode(node)) {
+    return null;
+  }
+  const elementNode = node;
+  for (const [key, value] of Object.entries(elementNode)) {
+    if (key === ":@" || key.startsWith("#")) {
+      continue;
+    }
+    if (!Array.isArray(value)) {
+      continue;
+    }
+    const attrs = elementNode[":@"] ?? {};
+    return {
+      name: key,
+      node: elementNode,
+      attrs,
+      children: value
+    };
+  }
+  return null;
+}
+function getRootElementEntry(document) {
+  for (const node of document) {
+    const entry = getElementEntry(node);
+    if (entry) {
+      return entry;
+    }
+  }
+  return null;
+}
+function isMetaNode(node) {
+  return "#text" in node || "#cdata" in node || "#comment" in node;
+}
+
+function rewriteRoot(document, symbolId) {
+  const rootEntry = getRootElementEntry(document);
+  if (!rootEntry || rootEntry.name !== "svg") {
+    throw new Error("Input must start with an <svg> root element.");
+  }
+  const viewBox = resolveViewBox(rootEntry.attrs);
+  if (!viewBox) {
+    throw new Error("Cannot determine viewBox. Provide an SVG with viewBox or width/height attributes.");
+  }
+  const children = rootEntry.node[rootEntry.name];
+  delete rootEntry.node[rootEntry.name];
+  rootEntry.node.symbol = children;
+  rootEntry.attrs.id = symbolId;
+  rootEntry.attrs.viewBox = viewBox;
+  delete rootEntry.attrs.width;
+  delete rootEntry.attrs.height;
+}
+function resolveViewBox(attrs) {
+  const explicitViewBox = attrs.viewBox?.trim();
+  if (explicitViewBox) {
+    return explicitViewBox;
+  }
+  const width = resolveDimension(attrs.width);
+  const height = resolveDimension(attrs.height);
+  if (width == null || height == null) {
+    return null;
+  }
+  return `0 0 ${width} ${height}`;
+}
+function resolveDimension(value) {
+  if (!value) {
+    return null;
+  }
+  const normalized = value.trim();
+  if (/^-?\d+(?:\.\d+)?$/.test(normalized)) {
+    return String(Number(normalized));
+  }
+  if (/^-?\d+(?:\.\d+)?px$/i.test(normalized)) {
+    return String(Number(normalized.slice(0, -2)));
+  }
+  return null;
+}
+
+const URL_REFERENCE_RE$1 = /\burl\((["'])?#(.+?)\1\)/gi;
+const HREF_REFERENCE_RE$1 = /^#(.+)$/;
+const SMIL_REFERENCE_RE$1 = /^([A-Za-z0-9_-]+)\.(begin|end)([+-].+)?$/;
+function collectIds(document) {
+  const elements = [];
+  const definedIds = /* @__PURE__ */ new Map();
+  const referenceIds = [];
+  let styleParseFailureCount = 0;
+  let order = 0;
+  visitElements(document, (name, node, attrs) => {
+    const element = { name, node, attrs };
+    elements.push(element);
+    for (const attrName of ["id", "xml:id"]) {
+      const id = attrs[attrName];
+      if (!id) {
+        continue;
+      }
+      const records = definedIds.get(id) ?? [];
+      records.push({
+        id,
+        attrName,
+        element,
+        order
+      });
+      definedIds.set(id, records);
+      order += 1;
+    }
+    const attributeRefs = collectAttributeReferences(attrs);
+    const styleResult = collectStyleReferences(element);
+    const styleRefs = styleResult.references;
+    styleParseFailureCount += styleResult.parseFailureCount;
+    if (attributeRefs.length === 0 && styleRefs.length === 0) {
+      return;
+    }
+    referenceIds.push({ element, attributeRefs, styleRefs });
+  });
+  return {
+    document,
+    elements,
+    definedIds,
+    referenceIds,
+    styleParseFailureCount
+  };
+}
+function collectAttributeReferences(attrs) {
+  const refs = [];
+  for (const [attrName, value] of Object.entries(attrs)) {
+    if (!value) {
+      continue;
+    }
+    if (attrName === "href" || attrName === "xlink:href") {
+      const match = HREF_REFERENCE_RE$1.exec(value);
+      if (match) {
+        refs.push({
+          kind: "href",
+          attrName,
+          targetIds: [decodeURI(match[1])]
+        });
+      }
+      continue;
+    }
+    if (isUrlReferenceAttribute(attrName)) {
+      const targetIds = collectUrlReferences(value);
+      if (targetIds.length > 0) {
+        refs.push({
+          kind: attrName === "style" ? "style-attr" : "url",
+          attrName,
+          targetIds
+        });
+      }
+      continue;
+    }
+    if (attrName === "begin" || attrName === "end") {
+      const targetIds = collectSmilReferences(value);
+      if (targetIds.length > 0) {
+        refs.push({
+          kind: attrName,
+          attrName,
+          targetIds
+        });
+      }
+      continue;
+    }
+    if (attrName === "aria-labelledby" || attrName === "aria-describedby") {
+      const targetIds = value.split(/\s+/).filter(Boolean);
+      if (targetIds.length > 0) {
+        refs.push({
+          kind: attrName,
+          attrName,
+          targetIds
+        });
+      }
+    }
+  }
+  return refs;
+}
+function collectStyleReferences(element) {
+  if (element.name !== "style") {
+    return { references: [], parseFailureCount: 0 };
+  }
+  const entry = getElementEntry(element.node);
+  if (!entry) {
+    return { references: [], parseFailureCount: 0 };
+  }
+  const refs = [];
+  let parseFailureCount = 0;
+  for (const child of entry.children) {
+    if (!("#text" in child) || typeof child["#text"] !== "string") {
+      continue;
+    }
+    const result = collectStyleTextReferences(child["#text"]);
+    parseFailureCount += result.parseFailureCount;
+    const targetIds = result.targetIds;
+    if (targetIds.length === 0) {
+      continue;
+    }
+    refs.push({
+      kind: "style-selector",
+      textNode: child,
+      targetIds
+    });
+  }
+  return {
+    references: refs,
+    parseFailureCount
+  };
+}
+function collectUrlReferences(value) {
+  const ids = [];
+  for (const match of value.matchAll(URL_REFERENCE_RE$1)) {
+    ids.push(decodeURI(match[2]));
+  }
+  return ids;
+}
+function collectSmilReferences(value) {
+  return value.split(/\s*;\s*/).map((part) => SMIL_REFERENCE_RE$1.exec(part)?.[1] ?? null).filter((id) => id != null);
+}
+function collectStyleTextReferences(value) {
+  const ids = /* @__PURE__ */ new Set();
+  let cssAst;
+  try {
+    cssAst = csstree.parse(value, {
+      parseValue: true,
+      parseCustomProperty: false
+    });
+  } catch {
+    return {
+      targetIds: [],
+      parseFailureCount: 1
+    };
+  }
+  csstree.walk(cssAst, (node) => {
+    if (node.type === "IdSelector" && typeof node.name === "string") {
+      ids.add(node.name);
+      return;
+    }
+    if (node.type === "Url" && typeof node.value === "string" && node.value.length > 0) {
+      const raw = unquote$1(node.value);
+      if (raw.startsWith("#")) {
+        ids.add(decodeURI(raw.slice(1)));
+      }
+    }
+  });
+  return {
+    targetIds: [...ids],
+    parseFailureCount: 0
+  };
+}
+function isUrlReferenceAttribute(attrName) {
+  return attrName === "clip-path" || attrName === "color-profile" || attrName === "fill" || attrName === "filter" || attrName === "marker-end" || attrName === "marker-mid" || attrName === "marker-start" || attrName === "mask" || attrName === "stroke" || attrName === "style";
+}
+function unquote$1(value) {
+  if (value.startsWith('"') && value.endsWith('"') || value.startsWith("'") && value.endsWith("'")) {
+    return value.slice(1, -1);
+  }
+  return value;
+}
+
+const URL_REFERENCE_RE = /\burl\((["'])?#(.+?)\1\)/gi;
+const HREF_REFERENCE_RE = /^#(.+)$/;
+const SMIL_REFERENCE_RE = /^([A-Za-z0-9_-]+)\.(begin|end)([+-].+)?$/;
+function rewriteIds(document, prefix, options, issues) {
+  const state = collectIds(document);
+  collectIssues(state, issues);
+  const idMap = createIdMap(state, prefix, options);
+  const unresolvedIdMap = /* @__PURE__ */ new Map();
+  let nextGeneratedIndex = idMap.size;
+  rewriteElementIds(state, idMap);
+  rewriteReferences(state, idMap, prefix, unresolvedIdMap, () => nextGeneratedIndex++, options, issues);
+  return idMap;
+}
+function createIdMap(state, prefix, options) {
+  const idMap = /* @__PURE__ */ new Map();
+  const records = [...state.definedIds.entries()].map(([id, definitions]) => ({
+    id,
+    order: Math.min(...definitions.map((definition) => definition.order))
+  })).sort((a, b) => a.order - b.order);
+  for (let counter = 0; counter < records.length; counter += 1) {
+    const { id } = records[counter];
+    idMap.set(id, createMappedId(id, prefix, counter, options));
+  }
+  return idMap;
+}
+function rewriteElementIds(state, idMap) {
+  for (const [id, definitions] of state.definedIds) {
+    const canonical = definitions[0];
+    canonical.element.attrs[canonical.attrName] = idMap.get(id);
+    for (const duplicate of definitions.slice(1)) {
+      delete duplicate.element.attrs[duplicate.attrName];
+    }
+  }
+}
+function rewriteReferences(state, idMap, prefix, unresolvedIdMap, nextIndex, options, issues) {
+  for (const reference of state.referenceIds) {
+    for (const attrRef of reference.attributeRefs) {
+      const value = reference.element.attrs[attrRef.attrName];
+      if (!value) {
+        continue;
+      }
+      if (attrRef.kind === "href") {
+        reference.element.attrs[attrRef.attrName] = rewriteHrefValue(value, idMap, prefix, unresolvedIdMap, nextIndex, options, issues);
+        continue;
+      }
+      if (attrRef.kind === "url" || attrRef.kind === "style-attr" && attrRef.attrName === "style") {
+        reference.element.attrs[attrRef.attrName] = rewriteUrlValue(value, idMap, prefix, unresolvedIdMap, nextIndex, options, issues);
+        continue;
+      }
+      if (attrRef.kind === "begin" || attrRef.kind === "end") {
+        reference.element.attrs[attrRef.attrName] = rewriteSmilValue(value, idMap, prefix, unresolvedIdMap, nextIndex, options, issues);
+        continue;
+      }
+      if (attrRef.kind === "aria-labelledby" || attrRef.kind === "aria-describedby") {
+        reference.element.attrs[attrRef.attrName] = rewriteTokenList(value, idMap, prefix, unresolvedIdMap, nextIndex, options, issues);
+      }
+    }
+    for (const styleRef of reference.styleRefs) {
+      styleRef.textNode["#text"] = rewriteStyleText(styleRef.textNode, idMap, prefix, unresolvedIdMap, nextIndex, options, issues);
+    }
+  }
+}
+function rewriteHrefValue(value, idMap, prefix, unresolvedIdMap, nextIndex, options, issues) {
+  const match = HREF_REFERENCE_RE.exec(value);
+  if (!match) {
+    return value;
+  }
+  const source = decodeURI(match[1]);
+  const next = idMap.get(source);
+  if (next) {
+    return `#${next}`;
+  }
+  return rewriteUnresolvedReference(source, value, prefix, unresolvedIdMap, nextIndex, options, issues, (resolved) => `#${resolved}`);
+}
+function rewriteUrlValue(value, idMap, prefix, unresolvedIdMap, nextIndex, options, issues) {
+  return value.replace(URL_REFERENCE_RE, (match, quote, body) => {
+    const source = decodeURI(body);
+    const next = idMap.get(source);
+    if (!next) {
+      return rewriteUnresolvedReference(source, match, prefix, unresolvedIdMap, nextIndex, options, issues, (resolved) => {
+        const wrappedQuote2 = quote ?? "";
+        return `url(${wrappedQuote2}#${resolved}${wrappedQuote2})`;
+      });
+    }
+    const wrappedQuote = quote ?? "";
+    return `url(${wrappedQuote}#${next}${wrappedQuote})`;
+  });
+}
+function rewriteSmilValue(value, idMap, prefix, unresolvedIdMap, nextIndex, options, issues) {
+  const parts = value.split(/\s*;\s*/);
+  return parts.map((part) => {
+    const match = SMIL_REFERENCE_RE.exec(part);
+    if (!match) {
+      return part;
+    }
+    const next = idMap.get(match[1]);
+    if (!next) {
+      return rewriteUnresolvedReference(match[1], part, prefix, unresolvedIdMap, nextIndex, options, issues, (resolved) => {
+        const offset2 = match[3] ?? "";
+        return `${resolved}.${match[2]}${offset2}`;
+      });
+    }
+    const offset = match[3] ?? "";
+    return `${next}.${match[2]}${offset}`;
+  }).join("; ");
+}
+function rewriteTokenList(value, idMap, prefix, unresolvedIdMap, nextIndex, options, issues) {
+  return value.split(/\s+/).filter(Boolean).map((token) => {
+    const next = idMap.get(token);
+    if (next) {
+      return next;
+    }
+    return rewriteUnresolvedReference(token, token, prefix, unresolvedIdMap, nextIndex, options, issues, (resolved) => resolved);
+  }).join(" ");
+}
+function rewriteStyleText(textNode, idMap, prefix, unresolvedIdMap, nextIndex, options, issues) {
+  let cssAst;
+  try {
+    cssAst = csstree.parse(textNode["#text"], {
+      parseValue: true,
+      parseCustomProperty: false
+    });
+  } catch {
+    return textNode["#text"];
+  }
+  csstree.walk(cssAst, (node) => {
+    if (node.type === "IdSelector" && typeof node.name === "string") {
+      const next = idMap.get(node.name);
+      if (next) {
+        node.name = next;
+        return;
+      }
+      const rewritten = rewriteUnresolvedReference(node.name, node.name, prefix, unresolvedIdMap, nextIndex, options, issues, (resolved) => resolved);
+      if (rewritten !== node.name) {
+        node.name = rewritten;
+      }
+      return;
+    }
+    if (node.type === "Url" && typeof node.value === "string" && node.value.length > 0) {
+      const raw = unquote(node.value);
+      if (!raw.startsWith("#")) {
+        return;
+      }
+      const source = decodeURI(raw.slice(1));
+      const next = idMap.get(source);
+      if (!next) {
+        const rewritten = rewriteUnresolvedReference(source, `#${source}`, prefix, unresolvedIdMap, nextIndex, options, issues, (resolved) => `#${resolved}`);
+        if (rewritten !== `#${source}`) {
+          node.value = rewritten;
+        }
+        return;
+      }
+      node.value = `#${next}`;
+    }
+  });
+  return csstree.generate(cssAst);
+}
+const BASE52_ALPHABET = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ";
+function encodeIndex(index) {
+  let current = index;
+  let result = "";
+  do {
+    result = BASE52_ALPHABET[current % 52] + result;
+    current = Math.floor(current / 52) - 1;
+  } while (current >= 0);
+  return result;
+}
+function createMappedId(sourceId, prefix, index, options) {
+  const delim = resolveDelim(options);
+  const style = options.idStyle;
+  if (style === "named") {
+    return `${prefix}${delim}${sourceId}`;
+  }
+  if (style === "hashed") {
+    return `${prefix}${delim}${hashId(sourceId)}`;
+  }
+  return `${prefix}${delim}${encodeIndex(index)}`;
+}
+function hashId(value) {
+  return toBase62(digest_djb2(value));
+}
+function digest_djb2(str) {
+  let hash = 5381;
+  for (const char of str) {
+    hash = (hash << 5) + hash ^ char.charCodeAt(0);
+  }
+  return hash >>> 0;
+}
+const BASE62_ALPHABET = "0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ";
+function toBase62(value) {
+  let current = value;
+  let result = "";
+  do {
+    result = BASE62_ALPHABET[current % 62] + result;
+    current = Math.floor(current / 62);
+  } while (current > 0);
+  return result;
+}
+function createUnresolvedMappedId(sourceId, prefix, unresolvedIdMap, nextIndex, options) {
+  const existing = unresolvedIdMap.get(sourceId);
+  if (existing) {
+    return existing;
+  }
+  const generated = createMappedId(sourceId, prefix, nextIndex(), options);
+  unresolvedIdMap.set(sourceId, generated);
+  return generated;
+}
+function rewriteUnresolvedReference(targetId, originalValue, prefix, unresolvedIdMap, nextIndex, options, issues, format) {
+  pushIssue(issues, {
+    code: "ResolveReferenceFailed",
+    message: `Resolve reference failed for local target "${targetId}"; reference was ${options.unresolved === "prefix" ? "prefixed" : "preserved"}.`,
+    targetId
+  });
+  if (options.unresolved === "preserve") {
+    return originalValue;
+  }
+  return format(createUnresolvedMappedId(targetId, prefix, unresolvedIdMap, nextIndex, options));
+}
+function resolveDelim(options) {
+  if (options.delim != null) {
+    return options.delim;
+  }
+  return "_";
+}
+function collectIssues(state, issues) {
+  for (const [id, definitions] of state.definedIds) {
+    if (definitions.length > 1) {
+      pushIssue(issues, {
+        code: "DetectDefinitionDuplicate",
+        message: `Detect definition duplicate for local target "${id}"; first occurrence was kept.`,
+        targetId: id
+      });
+    }
+  }
+  if (state.styleParseFailureCount > 0) {
+    pushIssue(issues, {
+      code: "ParseStyleFailed",
+      message: "Parse style failed for one or more <style> blocks; original content was preserved."
+    });
+  }
+}
+function pushIssue(issues, issue) {
+  const exists = issues.some((current) => current.code === issue.code && current.targetId === issue.targetId && current.message === issue.message);
+  if (!exists) {
+    issues.push(issue);
+  }
+}
+function unquote(value) {
+  if (value.startsWith('"') && value.endsWith('"') || value.startsWith("'") && value.endsWith("'")) {
+    return value.slice(1, -1);
+  }
+  return value;
+}
+
+function bakeSymbol(content, name, options) {
+  const document = parseSvg(content);
+  const issues = [];
+  if (options.rewrite) {
+    rewriteIds(document, name, options, issues);
+  }
+  rewriteRoot(document, name);
+  return {
+    name,
+    content: buildSvg(document).trim(),
+    issues
+  };
+}
+
+const PRESET_OVERRIDE_BLOCKED_PLUGINS = [
+  "cleanupIds",
+  "removeUselessDefs",
+  "removeHiddenElems",
+  "removeUnknownsAndDefaults",
+  "collapseGroups",
+  "mergePaths",
+  "convertShapeToPath",
+  "removeEmptyContainers"
+];
+const FILTER_ONLY_BLOCKED_PLUGINS = ["prefixIds", "reusePaths", "convertOneStopGradients"];
+const USER_FILTER_BLOCKED_PLUGINS = ["preset-default", ...PRESET_OVERRIDE_BLOCKED_PLUGINS, ...FILTER_ONLY_BLOCKED_PLUGINS];
 const DEFAULT_SAFE_PRESET = {
   name: "preset-default",
   params: {
-    overrides: {
-      removeUselessDefs: false,
-      removeHiddenElems: false,
-      removeUnknownsAndDefaults: false,
-      collapseGroups: false,
-      mergePaths: false,
-      convertShapeToPath: false
-    }
+    overrides: Object.fromEntries(PRESET_OVERRIDE_BLOCKED_PLUGINS.map((name) => [name, false]))
   }
 };
 const DEFAULT_SAFE_PLUGINS = [{ name: "removeTitle" }, { name: "removeXMLNS" }, { name: "removeXlink" }];
-const CORE_PLUGIN_BLOCKLIST = /* @__PURE__ */ new Set(["prefixIds"]);
 function resolveOptions(userOption) {
   const userObject = userOption ?? {};
   return {
     optimize: userObject.optimize ?? true,
-    svgoOptions: userObject.svgoOptions ?? {}
+    svgoOptions: userObject.svgoOptions ?? {},
+    idPolicy: resolveIdPolicyOptions(userObject.idPolicy)
   };
 }
-function createSvgoConfig(sourceName, options) {
+function createSvgoConfig(options) {
   const plugins = [];
   if (options.optimize) {
     plugins.push(DEFAULT_SAFE_PRESET);
@@ -31,7 +602,6 @@ function createSvgoConfig(sourceName, options) {
   if (options.svgoOptions.plugins != null) {
     plugins.push(...filterPlugins(options.svgoOptions.plugins));
   }
-  plugins.push(...createCorePlugins(sourceName));
   return {
     multipass: options.svgoOptions.multipass,
     floatPrecision: options.svgoOptions.floatPrecision,
@@ -45,7 +615,7 @@ function filterPlugins(plugins) {
     if (name == null) {
       return true;
     }
-    return !CORE_PLUGIN_BLOCKLIST.has(name);
+    return !USER_FILTER_BLOCKED_PLUGINS.includes(name);
   });
 }
 function resolvePluginName(plugin) {
@@ -57,57 +627,84 @@ function resolvePluginName(plugin) {
   }
   return null;
 }
-function createCorePlugins(sourceName) {
-  return [{ name: "removeDimensions" }, { name: "prefixIds", params: { prefix: `${sourceName}-`, delim: "" } }];
+function resolveIdPolicyOptions(idPolicy) {
+  return {
+    rewrite: idPolicy?.rewrite ?? true,
+    unresolved: idPolicy?.unresolved ?? "prefix",
+    idStyle: idPolicy?.idStyle ?? "minified",
+    delim: idPolicy?.delim ?? "_"
+  };
+}
+
+class BakeError extends Error {
+  code;
+  cause;
+  constructor(code, message, options) {
+    super(message, options);
+    this.name = "BakeError";
+    this.code = code;
+    this.cause = options?.cause;
+  }
 }
 
 function bakeIcon(source, options) {
-  const resolvedOptions = resolveOptions(options);
-  return {
-    name: source.name,
-    content: convertToSymbol(source, resolvedOptions)
-  };
+  return createBaker(options).bakeIcon(source);
 }
 function bakeIcons(sources, options) {
+  return createBaker(options).bakeIcons(sources);
+}
+function createBaker(options) {
   const resolvedOptions = resolveOptions(options);
-  return sources.map((source) => ({
-    name: source.name,
-    content: convertToSymbol(source, resolvedOptions)
-  }));
+  const svgoConfig = createSvgoConfig(resolvedOptions);
+  return {
+    bakeIcon(source) {
+      return convertSource(source, resolvedOptions, svgoConfig);
+    },
+    bakeIcons(sources) {
+      return sources.map((source) => {
+        return convertSource(source, resolvedOptions, svgoConfig);
+      });
+    }
+  };
 }
-function convertToSymbol(source, options) {
+function convertSource(source, options, svgoConfig) {
   if (!source || !source.name || !source.content) {
-    throw new TypeError("Property name and content are required.");
+    throw new BakeError("ValidateSourceInvalid", "Property name and content are required.");
   }
   if (!/^[A-Za-z][A-Za-z0-9_-]*$/.test(source.name)) {
-    throw new TypeError("Invalid name. Use letters, numbers, dash, or underscore, starting with a letter.");
+    throw new BakeError("ValidateNameInvalid", "Invalid name. Use letters, numbers, dash, or underscore, starting with a letter.");
   }
-  const normalizedSource = stripLeadingSvgPreamble(source.content);
+  const normalizedSource = trimSvgPreamble(source.content);
   if (!/^\s*<svg\b/i.test(normalizedSource)) {
-    throw new Error("Parsing failed. Input must start with an <svg> root element.");
+    throw new BakeError("ValidateSvgRootInvalid", "Input must start with an <svg> root element.");
   }
-  let result;
+  const optimized = optimizeSvg(normalizedSource, svgoConfig);
   try {
-    result = optimize(normalizedSource, createSvgoConfig(source.name, options));
-  } catch (err) {
-    throw new Error(`Parsing failed. ${String(err)}`);
+    return bakeSymbol(optimized, source.name, options.idPolicy);
+  } catch (cause) {
+    if (cause instanceof BakeError) {
+      throw cause;
+    }
+    if (cause instanceof Error && cause.message === "Cannot determine viewBox. Provide an SVG with viewBox or width/height attributes.") {
+      throw new BakeError("ResolveViewBoxFailed", cause.message);
+    }
+    if (cause instanceof Error && cause.message === "Input must start with an <svg> root element.") {
+      throw new BakeError("ValidateSvgRootInvalid", cause.message);
+    }
+    throw new BakeError("ParseSvgFailed", "SVG parsing failed during id rewrite.", { cause });
   }
-  const viewBox = result.data.match(/viewBox="([^"]+)"/)?.[1];
-  if (!viewBox) {
-    throw new Error("Cannot determine viewBox. Provide an SVG with viewBox or width/height attributes.");
+}
+function optimizeSvg(content, svgoConfig) {
+  let result;
+  try {
+    result = optimize(content, svgoConfig);
+  } catch (cause) {
+    throw new BakeError("OptimizeSvgFailed", "SVGO optimization failed.", { cause });
   }
-  const cleanedSvg = stripLeadingSvgPreamble(result.data);
-  return toSymbolRootTag(cleanedSvg, source.name, viewBox);
+  return result.data;
 }
-function stripLeadingSvgPreamble(content) {
+function trimSvgPreamble(content) {
   return content.replace(/^(?:\uFEFF|\s|<\?xml[\s\S]*?\?>|<!--[\s\S]*?-->|<!DOCTYPE[\s\S]*?>)+/i, "");
 }
-function toSymbolRootTag(svg, symbolId, viewBox) {
-  const rootOpenTag = svg.match(/^\s*<svg\b[^>]*>/i)[0];
-  const preservedAttrs = rootOpenTag.replace(/^\s*<svg\b/i, "").replace(/>\s*$/i, "").replace(/\s+id=(['"])[^'"]*\1/gi, "").replace(/\s+viewBox=(['"])[^'"]*\1/gi, "").replace(/\s+width=(['"])[^'"]*\1/gi, "").replace(/\s+height=(['"])[^'"]*\1/gi, "").trim();
-  const attrs = preservedAttrs ? ` ${preservedAttrs}` : "";
-  const symbolOpenTag = `<symbol id="${symbolId}" viewBox="${viewBox}"${attrs}>`;
-  return svg.replace(/^\s*<svg\b[^>]*>/i, symbolOpenTag).replace(/<\/svg>\s*$/i, "</symbol>").trim();
-}
 
-export { bakeIcon, bakeIcons };
+export { BakeError, bakeIcon, bakeIcons, createBaker };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "svg-icon-baker",
-  "version": "1.2.1",
+  "version": "2.0.1",
   "description": "A delightful toolkit for baking raw SVG icons into delicious SVG symbol sprites",
   "keywords": [
     "svg",
@@ -37,6 +37,9 @@
     "dist"
   ],
   "dependencies": {
+    "css-tree": "^3.2.1",
+    "fast-xml-builder": "^1.1.5",
+    "fast-xml-parser": "^5.7.2",
     "svgo": "^4.0.1"
   },
   "devDependencies": {
@@ -54,6 +57,6 @@
     "test": "vitest run",
     "coverage": "vitest run --coverage",
     "clean": "rimraf dist",
-    "log": "conventional-changelog -p angular --commit-path . -t svg-icon-baker@v"
+    "release": "commit-and-tag-version --path . -t svg-icon-baker@"
   }
 }