@nkardaz/typography-rules 1.0.0

package/dist/glyphs/types.d.ts

@@ -0,0 +1,151 @@
+/** A plain string-to-string map used as the base shape for all glyph dictionaries. */
+export type GlyphStringMap = Record<string, string>;
+/** Raw glyph key-value data passed into glyph set constructors. */
+export type GlyphData = Record<string, string>;
+/**
+ * A glyph set with typed key access and prototype utility methods.
+ *
+ * Combines the original data shape `T` with a set of shared methods
+ * attached via prototype (see `createCharacters`).
+ *
+ * @template T - Raw glyph dictionary shape
+ */
+export type GlyphSet<T extends GlyphData = GlyphData> = {
+    [K in keyof T]: T[K];
+} & {
+    values(this: GlyphSet<T>): string[];
+    /**
+     * Joins all glyph values into a single string.
+     *
+     * @param joiner - Separator between values. Defaults to `'|'`.
+     * @returns Joined string of all values in the set.
+     *
+     * @example
+     * DASHES.join() // '-|–|⸺|…'
+     * DASHES.join('') // '-–⸺…'
+     */
+    join(joiner?: string): string;
+    /**
+     * Mutably inserts new entries into the glyph set.
+     *
+     * Note: TypeScript types are not updated after insertion.
+     * Use type casting if access to inserted keys is needed statically.
+     *
+     * @param entries - Key-value pairs to add to the set.
+     *
+     * @example
+     * DASHES.insert({ myDash: '\u2E1A' });
+     */
+    insert(entries: GlyphData): void;
+    /**
+     * Checks whether a key exists in the glyph set.
+     *
+     * @param key - The key to look up.
+     * @returns `true` if the key is present, `false` otherwise.
+     *
+     * @example
+     * DASHES.hasKey('em') // true
+     * DASHES.hasKey('foo') // false
+     */
+    hasKey(key: string): boolean;
+    /**
+     * Checks whether a value exists in the glyph set.
+     *
+     * @param value - The glyph value to search for.
+     * @returns `true` if the value is present, `false` otherwise.
+     *
+     * @example
+     * DASHES.hasValue('\u2014') // true
+     */
+    hasValue(value: string): boolean;
+    /**
+     * Returns the key associated with a given glyph value.
+     *
+     * @param value - The glyph value to look up.
+     * @returns The corresponding key, or `undefined` if not found.
+     *
+     * @example
+     * DASHES.findKey('\u2014') // 'em'
+     * DASHES.findKey('???') // undefined
+     */
+    findKey(value: string): string | undefined;
+    /**
+     * Returns the values associated with given keys.
+     *
+     * @param keys - The keys to look up.
+     * @returns An array of values, or `undefined` if not found.
+     *
+     * @example
+     * DASHES.find('em', 'en') // ['-', '–']
+     * DASHES.find('foo', 'bar') // undefined
+     */
+    find(...keys: string[]): string[] | undefined;
+};
+/**
+ * Structural contract for glyph sets used in generic contexts.
+ *
+ * Used where the concrete type parameter `T` is not available -
+ * for example, as values inside `createCharacterSet` group maps.
+ *
+ * The index signature allows arbitrary string keys alongside
+ * the explicitly declared utility methods.
+ */
+export interface GlyphSetInterface {
+    [key: string]: string | ((joiner?: string) => string) | ((entries: GlyphData) => void) | ((key: string) => boolean) | ((value: string) => boolean) | ((value: string) => string | undefined) | ((...keys: string[]) => string[] | undefined);
+    values(): string[];
+    join(joiner?: string): string;
+    insert(entries: GlyphData): void;
+    hasKey(key: string): boolean;
+    hasValue(value: string): boolean;
+    findKey(value: string): string | undefined;
+    find(...keys: string[]): string[] | undefined;
+}
+/**
+ * Prototype interface for grouped character sets (e.g. `PUNCTUATION`).
+ *
+ * Provides locale-aware access to glyph groups via hierarchical resolution:
+ * `common[key]` is merged with `locale[key]`, locale values taking precedence.
+ *
+ * @template T - The full character set structure, optionally containing a `common` group
+ * and one or more locale groups.
+ */
+export interface ProtoSet<T extends {
+    common?: Record<string, GlyphSetInterface>;
+}> {
+    /**
+     * Retrieves a merged glyph set for a given locale and group key.
+     *
+     * Merges the `common[key]` group with `locale[key]`, with locale
+     * values overriding common ones where keys collide.
+     *
+     * @param dataSet - Locale identifier (any key of `T` except `'common'`).
+     * @param key - Group key present in `common` and/or the target locale.
+     * @returns Merged glyph set for the requested locale and group.
+     *
+     * @example
+     * PUNCTUATION.get('en', 'leftSided')  // common + en leftSided merged
+     * PUNCTUATION.get('ru', 'rightSided') // common + ru rightSided merged
+     */
+    get<TDataSet extends Exclude<keyof T, 'common'>, TKey extends keyof (T['common'] & T[TDataSet])>(this: T & ProtoSet<T>, dataSet: TDataSet, key: TKey): GlyphSetInterface;
+    /**
+     * Returns all top-level group keys of the character set, including `'common'`.
+     *
+     * @returns Array of string keys present on the character set object.
+     *
+     * @example
+     * PUNCTUATION.getList() // ['common', 'ru', 'en', 'fr', 'is']
+     */
+    getList(): (keyof T & string)[];
+    /**
+     * Checks whether a given group key exists in the character set.
+     *
+     * @param key - Group key to check.
+     * @returns `true` if the key is present, `false` otherwise.
+     *
+     * @example
+     * PUNCTUATION.hasKey('en') // true
+     * PUNCTUATION.hasKey('de') // false
+     */
+    hasKey(key: keyof T & string): boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/helpers/index.cjs

@@ -0,0 +1,268 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+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 __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/helpers/index.ts
+var index_exports = {};
+__export(index_exports, {
+  NODE_MARKER: () => NODE_MARKER,
+  NODE_MARKER_REGEX: () => NODE_MARKER_REGEX,
+  PROTECTED_PATTERNS: () => PROTECTED_PATTERNS,
+  PROTECTION_MARKER: () => PROTECTION_MARKER,
+  PROTECTION_MARKER_REGEX: () => PROTECTION_MARKER_REGEX,
+  createPatterns: () => createPatterns,
+  joinNodes: () => joinNodes,
+  protect: () => protect,
+  splitNodes: () => splitNodes,
+  unprotect: () => unprotect
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/typography/aliases.ts
+function createAlias(map) {
+  const normalized = Object.fromEntries(
+    Object.entries(map).map(([key, values]) => [
+      key.toLowerCase(),
+      values.map((v) => v.toLowerCase())
+    ])
+  );
+  const methods = {
+    /**
+     * Checks whether an alias exists in the map,
+     * either as a root key or as an alternative name.
+     *
+     * @param alias - The alias to look up (case-insensitive).
+     * @returns `true` if the alias is found, `false` otherwise.
+     *
+     * @example
+     * ALIAS.has('English') // true
+     * ALIAS.has('fr')      // false
+     */
+    has(alias) {
+      const a = alias.toLowerCase();
+      if (a in normalized) return true;
+      return Object.values(normalized).some((vals) => vals.includes(a));
+    },
+    /**
+     * Resolves an alias to its root key.
+     *
+     * @param alias - The alias to resolve (case-insensitive).
+     * @returns The root key if found, `undefined` otherwise.
+     *
+     * @example
+     * ALIAS.resolve('Russian') // 'ru'
+     * ALIAS.resolve('ru-RU')   // 'ru'
+     * ALIAS.resolve('fr')      // undefined
+     */
+    resolve(alias) {
+      const a = alias.toLowerCase();
+      if (a in normalized) return a;
+      return Object.keys(normalized).find((k) => {
+        const values = normalized[k];
+        return Array.isArray(values) && values.includes(a);
+      });
+    },
+    /**
+     * Adds one or more alternative names to an existing or new root key.
+     * All values are automatically lowercased.
+     *
+     * @param root - The root key to add aliases to.
+     * @param aliases - One or more alternative names to register.
+     *
+     * @example
+     * ALIAS.push('ru', 'Рус', 'ру')
+     * ALIAS.ru // ['ru-ru', 'russian', 'русский', 'рус', 'ру']
+     */
+    push(root, ...aliases) {
+      for (const alias of aliases) {
+        const a = alias.toLowerCase();
+        const r = root.toLowerCase();
+        if (a in normalized) {
+          normalized[a]?.push(r);
+        } else {
+          normalized[a] = [r];
+        }
+      }
+    },
+    /**
+     * Normalizes one or more strings to lowercase.
+     *
+     * @param alias - One or more strings to normalize.
+     * @returns An array of lowercased strings.
+     *
+     * @example
+     * ALIAS.normalize('English', 'RU-RU') // ['english', 'ru-ru']
+     */
+    normalize(...alias) {
+      return alias.map((a) => a.toLowerCase());
+    }
+  };
+  return new Proxy(methods, {
+    get(target, prop) {
+      if (prop in target) return target[prop];
+      return normalized[prop];
+    },
+    has(_target, prop) {
+      return prop in normalized;
+    },
+    ownKeys() {
+      return [...Object.keys(normalized), ...Object.keys(methods)];
+    },
+    getOwnPropertyDescriptor(_target, prop) {
+      if (prop in normalized || prop in methods) {
+        return { enumerable: true, configurable: true };
+      }
+      return void 0;
+    }
+  });
+}
+var ALIAS = createAlias({
+  ru: ["ru-RU", "Russian", "\u0420\u0443\u0441\u0441\u043A\u0438\u0439"],
+  en: ["en-US", "English"],
+  ang: ["\xC6nglis\u010B", "\xC6nglisc", "Old English"]
+});
+
+// src/helpers/index.ts
+var NODE_MARKER = "\uE000\uEDFD\uF43E";
+var PROTECTION_MARKER = "\uE001\uEDF1\uF111";
+var NODE_MARKER_REGEX = new RegExp(NODE_MARKER, "g");
+var PROTECTION_MARKER_REGEX = new RegExp(PROTECTION_MARKER, "g");
+var patternProto = {
+  get values() {
+    return Object.keys(this).map((key) => {
+      const desc = Object.getOwnPropertyDescriptor(this, key);
+      return desc?.get ? this[key] : void 0;
+    }).filter((v) => v !== void 0);
+  },
+  combined(locale) {
+    const key = locale ? ALIAS.resolve(locale) ?? locale : void 0;
+    const baseSources = this.values.map((p) => `(${p.source})`);
+    const localeSources = [];
+    const locales = localeRegistry.get(this);
+    if (key && locales) {
+      const sub = locales.get(key);
+      if (sub) {
+        for (const rx of Object.values(sub)) {
+          localeSources.push(`(${rx.source})`);
+        }
+      }
+    }
+    const source = [...baseSources, ...localeSources].join("|");
+    return new RegExp(source, "g");
+  },
+  insert(patterns) {
+    const locales = localeRegistry.get(this) ?? /* @__PURE__ */ new Map();
+    for (const key of Object.keys(patterns)) {
+      const value = patterns[key];
+      if (value instanceof RegExp) {
+        const src = value.source;
+        const flags = value.flags;
+        Object.defineProperty(this, key, {
+          get() {
+            return new RegExp(src, flags);
+          },
+          enumerable: true,
+          configurable: true
+        });
+      } else {
+        locales.set(key, value);
+        localeRegistry.set(this, locales);
+      }
+    }
+  },
+  *[Symbol.iterator]() {
+    for (const key of Object.keys(this)) {
+      const desc = Object.getOwnPropertyDescriptor(this, key);
+      if (desc?.get) yield this[key];
+    }
+  }
+};
+function createPatterns(patterns) {
+  const result = Object.create(patternProto);
+  const locales = /* @__PURE__ */ new Map();
+  for (const key of Object.keys(patterns)) {
+    const value = patterns[key];
+    if (value instanceof RegExp) {
+      const src = value.source;
+      const flags = value.flags;
+      Object.defineProperty(result, key, {
+        get() {
+          return new RegExp(src, flags);
+        },
+        enumerable: true,
+        configurable: true
+      });
+    } else {
+      locales.set(key, value);
+    }
+  }
+  localeRegistry.set(result, locales);
+  return result;
+}
+var localeRegistry = /* @__PURE__ */ new WeakMap();
+var PROTECTED_PATTERNS = createPatterns({
+  email: /[a-zA-Z0-9._-]+@[a-zA-Z0-9._-]+\.[a-zA-Z0-9_-]+/g,
+  url: /https?:\/\/[^\s]+/g,
+  unixPath: /\/[a-zA-Z0-9._\-/]+\.[a-zA-Z0-9]+/g,
+  windowsPath: /[A-Za-z]:\\(?:[^\\/:*?"<>|\r\n]+\\)*[^\\/:*?"<>|\r\n]*/g,
+  xmlTag: /<\/?[a-zA-Z][^>]*>/g,
+  inlineCode: /`[^`\n]+`/g,
+  blockCode: /```[\s\S]*?```/g,
+  uuid: /\b[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}\b/gi,
+  hash: /\b(?=[0-9a-f]*[a-f])[0-9a-f]{7,40}\b/gi,
+  ipv4: /\b(?:\d{1,3}\.){3}\d{1,3}\b/g,
+  ipv6: /\b(?:[0-9a-fA-F]{1,4}:){7}[0-9a-fA-F]{1,4}\b/g,
+  mac: /\b(?:[0-9a-fA-F]{2}:){5}[0-9a-fA-F]{2}\b/g,
+  version: /\bv?\d+\.\d+\.\d+(?:[-+][A-Za-z0-9.-]+)?\b/g,
+  selector: /[.#][A-Za-z_][\w-]*/g,
+  cliOption: /--?[a-zA-Z][\w-]*/g,
+  hashNumber: /(?<!\w)#[0-9]+\b/g,
+  isbn: /\b(?:97[89][- ]?)?(?:\d[- ]?){9}[\dX]\b/g,
+  issn: /\b\d{4}-\d{3}[\dX]\b/g,
+  doi: /\b10\.\d{4,9}\/[-._;()/:A-Za-z0-9]+\b/g,
+  orcid: /\b\d{4}-\d{4}-\d{4}-\d{3}[\dX]\b/g,
+  protect: /\[##\((.+)\)##\]/g,
+  ["ru"]: {}
+});
+function protect(text, locale) {
+  const key = locale ? ALIAS.resolve(locale) ?? locale : void 0;
+  const captured = [];
+  const withNodeMarkers = text.replace(NODE_MARKER_REGEX, (match) => {
+    captured.push(match);
+    return PROTECTION_MARKER;
+  });
+  const withPatterns = withNodeMarkers.replace(PROTECTED_PATTERNS.combined(key), (match) => {
+    captured.push(match);
+    return PROTECTION_MARKER;
+  });
+  return [withPatterns, captured];
+}
+function unprotect(text, captured) {
+  const queue = [...captured];
+  return text.replace(PROTECTION_MARKER_REGEX, () => queue.shift() ?? "").replace(PROTECTED_PATTERNS.protect, "$1");
+}
+function joinNodes(nodes) {
+  return nodes.map((n) => n.value).join(NODE_MARKER);
+}
+function splitNodes(text, nodes) {
+  const segments = text.split(NODE_MARKER);
+  nodes.forEach((n, i) => {
+    n.value = segments[i] ?? n.value;
+  });
+}
+//# sourceMappingURL=index.cjs.map

package/dist/helpers/index.d.ts

@@ -0,0 +1,133 @@
+import type { PatternData, PatternSet } from './types';
+export type * from './types';
+/**
+ * Private Use Area (PUA) marker sequence used to identify AST nodes.
+ *
+ * This marker is embedded into text during preprocessing stages
+ * to preserve structural boundaries through transformations.
+ *
+ * Must remain unique and never appear in natural text.
+ */
+export declare const NODE_MARKER = "\uE000\uEDFD\uF43E";
+/**
+ * Private Use Area (PUA) marker sequence used for protected regions.
+ *
+ * Used to temporarily wrap substrings that must not be modified
+ * during typography or text-processing pipelines.
+ *
+ * Typically applied before regex-based transformations.
+ */
+export declare const PROTECTION_MARKER = "\uE001\uEDF1\uF111";
+/**
+ * RegExp matcher for NODE_MARKER sequences.
+ *
+ * Used to locate and remove node markers during cleanup phase
+ * of text processing pipeline.
+ */
+export declare const NODE_MARKER_REGEX: RegExp;
+/**
+ * RegExp matcher for PROTECTION_MARKER sequences.
+ *
+ * Used to detect protected regions in processed text
+ * and restore original content where necessary.
+ */
+export declare const PROTECTION_MARKER_REGEX: RegExp;
+/**
+ * Creates a pattern registry from a map of named RegExp patterns.
+ *
+ * Each pattern is stored as a getter that returns a new `RegExp` instance
+ * on every access, ensuring `lastIndex` is always reset to `0` regardless
+ * of how the pattern was previously used.
+ *
+ * Prototype methods (`values`, `Symbol.iterator`) are attached via
+ * `Object.create` and do not appear as enumerable keys on the result.
+ *
+ * @template T — Shape of the source pattern map
+ * @param patterns — Raw map of named RegExp patterns
+ * @returns A pattern registry with per-access instantiation and prototype utilities
+ *
+ * @example
+ * const PATTERNS = createPatterns({
+ *   email: /[a-zA-Z0-9._-]+@[a-zA-Z0-9._-]+\.[a-zA-Z0-9_-]+/g,
+ *   url: /https?:\/\/[^\s]+/g,
+ * });
+ *
+ * PATTERNS.email.test('user@example.com'); // always starts from lastIndex = 0
+ * [...PATTERNS];                           // [RegExp, RegExp]
+ * PATTERNS.values;                         // [RegExp, RegExp]
+ */
+export declare function createPatterns<T extends PatternData>(patterns: T): PatternSet<T>;
+/**
+ * Registry of protected regex patterns used in text preprocessing.
+ *
+ * These patterns are temporarily excluded from typography transformations
+ * by wrapping matches with protection markers.
+ *
+ * Includes:
+ * - URLs and emails
+ * - filesystem paths (Unix / Windows)
+ * - code blocks and inline code
+ * - identifiers (UUID, hashes, ORCID, DOI)
+ * - network addresses (IPv4, IPv6, MAC)
+ * - programming-related syntax (selectors, CLI flags, versions)
+ * - publishing identifiers (ISBN, ISSN)
+ *
+ * This system ensures that structured technical content
+ * is not corrupted by typographic transformations.
+ */
+export declare const PROTECTED_PATTERNS: PatternSet<{
+    email: RegExp;
+    url: RegExp;
+    unixPath: RegExp;
+    windowsPath: RegExp;
+    xmlTag: RegExp;
+    inlineCode: RegExp;
+    blockCode: RegExp;
+    uuid: RegExp;
+    hash: RegExp;
+    ipv4: RegExp;
+    ipv6: RegExp;
+    mac: RegExp;
+    version: RegExp;
+    selector: RegExp;
+    cliOption: RegExp;
+    hashNumber: RegExp;
+    isbn: RegExp;
+    issn: RegExp;
+    doi: RegExp;
+    orcid: RegExp;
+    protect: RegExp;
+    ru: {};
+}>;
+/**
+ * Wraps NODE_MARKER sequences and PROTECTED_PATTERNS matches
+ * with PROTECTION_MARKER, storing originals for later restoration.
+ *
+ * @returns Tuple of [protected text, captured matches]
+ */
+export declare function protect(text: string, locale?: string): [string, string[]];
+/**
+ * Restores original strings previously captured by `protect`.
+ */
+export declare function unprotect(text: string, captured: string[]): string;
+/**
+ * Joins an array of objects with a `value: string` field
+ * into a single string using NODE_MARKER as separator.
+ *
+ * Intended for combining sibling text nodes before rule application,
+ * so that rules can operate across node boundaries when needed.
+ */
+export declare function joinNodes<T extends {
+    value: string;
+}>(nodes: T[]): string;
+/**
+ * Splits a transformed string by NODE_MARKER and writes
+ * segments back into the corresponding nodes.
+ *
+ * If segment count doesn't match nodes count (e.g. a rule
+ * consumed a marker), original values are preserved as fallback.
+ */
+export declare function splitNodes<T extends {
+    value: string;
+}>(text: string, nodes: T[]): void;
+//# sourceMappingURL=index.d.ts.map