punctilio 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Alexander Turner
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,109 @@
+# punctilio
+
+> *punctilio* (n.): a fine point of conduct or procedure
+
+Smart typography transformations for JavaScript/TypeScript. Converts ASCII punctuation to typographically correct Unicode characters. Originally built for [my personal website](https://turntrout.com/design).
+
+## Features
+
+- **Smart quotes**: `"straight"` → `"curly"` and `'apostrophes'` → `'apostrophes'`
+- **Em dashes**: `word - word` or `word--word` → `word—word`
+- **En dashes**: `1-5` → `1–5` (number ranges), `January-March` → `January–March` (date ranges)
+- **Minus signs**: `-5` → `−5` (proper Unicode minus)
+- **Handles edge cases**: contractions, possessives, nested quotes, year abbreviations ('99), "rock 'n' roll"
+
+## Why another typography library?
+
+Existing solutions like [SmartyPants](https://daringfireball.net/projects/smartypants/) struggle with:
+
+- **Apostrophe ambiguity**: Is `'Twas` an opening quote or apostrophe? (It's an apostrophe)
+- **Cross-element text**: When quotes span `<em>"Hello</em> world"`, most libraries fail
+- **Context sensitivity**: `'99` (year) vs `'hello'` (quoted) vs `don't` (contraction)
+
+`punctilio` handles these through thorough regex patterns and an optional separator character for processing text that spans HTML elements.
+
+## Installation
+
+```bash
+npm install punctilio
+# or
+pnpm add punctilio
+```
+
+## Usage
+
+### Basic
+
+```typescript
+import { transform, niceQuotes, hyphenReplace } from 'punctilio'
+
+// Apply all transformations
+transform('"Hello," she said - "it\'s pages 1-5."')
+// → "Hello," she said—"it's pages 1–5."
+
+// Or use individual functions
+niceQuotes('"Hello", she said.')
+// → "Hello", she said.
+
+hyphenReplace('word - word')
+// → word—word
+```
+
+### With HTML Element Boundaries
+
+When processing text that spans multiple HTML elements, use a separator character to mark boundaries:
+
+```typescript
+import { transform, DEFAULT_SEPARATOR } from 'punctilio'
+
+// Your HTML: <p>"Hello <em>world</em>"</p>
+// Extract text with separator between elements:
+const text = `"Hello ${DEFAULT_SEPARATOR}world${DEFAULT_SEPARATOR}"`
+
+const result = transform(text, { separator: DEFAULT_SEPARATOR })
+// → "Hello \uE000world\uE000"
+// The separator is preserved; split on it to restore to your elements
+```
+
+For a complete implementation showing how to use this with a HAST (HTML AST) tree, see the [`transformElement` function in TurnTrout.com](https://github.com/alexander-turner/TurnTrout.com/blob/main/quartz/plugins/transformers/formatting_improvement_html.ts). I explain the philosophy behind this algorithm.
+
+## API
+
+### `transform(text, options?)`
+
+Applies all typography transformations (quotes + dashes).
+
+### `niceQuotes(text, options?)`
+
+Converts straight quotes to curly quotes. Handles:
+- Opening/closing double quotes: `"` → `"` or `"`
+- Opening/closing single quotes: `'` → `'` or `'`
+- Contractions: `don't` → `don't`
+- Possessives: `dog's` → `dog's`
+- Year abbreviations: `'99` → `'99`
+- Special cases: `'n'` in "rock 'n' roll"
+
+### `hyphenReplace(text, options?)`
+
+Converts hyphens to proper dashes. Handles:
+- Em dashes: `word - word` → `word—word`
+- En dashes for number ranges: `1-5` → `1–5`
+- En dashes for date ranges: `Jan-Mar` → `Jan–Mar`
+- Minus signs: `-5` → `−5`
+- Preserves: horizontal rules (`---`), compound words (`well-known`)
+
+### `enDashNumberRange(text, options?)`
+
+Converts number ranges only: `pages 10-20` → `pages 10–20`
+
+### `enDashDateRange(text, options?)`
+
+Converts month ranges only: `January-March` → `January–March`
+
+### `minusReplace(text, options?)`
+
+Converts hyphens to minus signs in numerical contexts: `-5` → `−5`
+
+## License
+
+MIT © Alexander Turner

package/dist/dashes.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Dash and hyphen transformation
+ *
+ * Converts hyphens and dashes to typographically correct em-dashes,
+ * en-dashes, and minus signs based on context.
+ */
+export interface DashOptions {
+    /**
+     * A boundary marker character used when transforming text that spans
+     * multiple HTML elements. This character is treated as "transparent"
+     * in the regex patterns.
+     *
+     * Should be a character that doesn't appear in your text.
+     * Default: "\uE000" (Unicode Private Use Area)
+     */
+    separator?: string;
+}
+/**
+ * List of month names (full and abbreviated) for date range detection
+ */
+export declare const months: string;
+/**
+ * Replaces hyphens with en-dashes in number ranges.
+ *
+ * Handles:
+ * - Simple ranges: "1-5" → "1–5"
+ * - Page numbers: "p.206-207" → "p.206–207"
+ * - Dollar amounts: "$100-$200" → "$100–$200"
+ * - Comma-formatted numbers: "1,000-2,000" → "1,000–2,000"
+ *
+ * Does NOT replace:
+ * - Spaced ranges: "1 - 5" (ambiguous, could be subtraction)
+ * - Version numbers with decimals: "1.5-1.8"
+ *
+ * @param text - The text to transform
+ * @param options - Configuration options
+ * @returns The text with en-dashes in number ranges
+ *
+ * @example
+ * ```ts
+ * enDashNumberRange("pages 10-15")
+ * // → "pages 10–15"
+ * ```
+ */
+export declare function enDashNumberRange(text: string, options?: DashOptions): string;
+/**
+ * Replaces hyphens with en-dashes in month/date ranges.
+ *
+ * Handles full and abbreviated month names:
+ * - "January-March" → "January–March"
+ * - "Jan-Mar" → "Jan–Mar"
+ *
+ * @param text - The text to transform
+ * @param options - Configuration options
+ * @returns The text with en-dashes in date ranges
+ *
+ * @example
+ * ```ts
+ * enDashDateRange("January-March 2024")
+ * // → "January–March 2024"
+ * ```
+ */
+export declare function enDashDateRange(text: string, options?: DashOptions): string;
+/**
+ * Replaces hyphens with proper minus signs (−) in numerical contexts.
+ *
+ * Handles negative numbers at:
+ * - Start of string/line
+ * - After whitespace
+ * - After opening parenthesis
+ * - After opening quote
+ *
+ * @param text - The text to transform
+ * @param options - Configuration options
+ * @returns The text with minus signs
+ *
+ * @example
+ * ```ts
+ * minusReplace("The temperature was -5 degrees")
+ * // → "The temperature was −5 degrees"
+ * ```
+ */
+export declare function minusReplace(text: string, options?: DashOptions): string;
+/**
+ * Comprehensive dash replacement for typographic correctness.
+ *
+ * Applies multiple transformations:
+ * 1. Converts hyphens to minus signs in numerical contexts
+ * 2. Converts surrounded dashes (- or --) to em-dashes (—)
+ * 3. Removes spaces around em-dashes (per modern style)
+ * 4. Preserves space after em-dash at start of line
+ * 5. Adds space after em-dash following quotation marks
+ * 6. Converts number ranges to en-dashes (1-5 → 1–5)
+ * 7. Converts date ranges to en-dashes (Jan-Mar → Jan–Mar)
+ *
+ * Does NOT modify:
+ * - Horizontal rules (---)
+ * - Compound modifiers (well-known, browser-specific)
+ * - Hyphens in quoted blockquotes ("> - item")
+ *
+ * @param text - The text to transform
+ * @param options - Configuration options
+ * @returns The text with proper dashes
+ *
+ * @example
+ * ```ts
+ * hyphenReplace("This is a - test")
+ * // → "This is a—test"
+ *
+ * hyphenReplace("Since--as you know")
+ * // → "Since—as you know"
+ *
+ * hyphenReplace("Pages 1-5")
+ * // → "Pages 1–5"
+ * ```
+ */
+export declare function hyphenReplace(text: string, options?: DashOptions): string;
+//# sourceMappingURL=dashes.d.ts.map

package/dist/dashes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dashes.d.ts","sourceRoot":"","sources":["../src/dashes.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,WAAW,WAAW;IAC1B;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAID;;GAEG;AACH,eAAO,MAAM,MAAM,QAyBR,CAAA;AAEX;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,WAAgB,GAAG,MAAM,CASjF;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,WAAgB,GAAG,MAAM,CAM/E;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,WAAgB,GAAG,MAAM,CAI5E;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,WAAgB,GAAG,MAAM,CAgD7E"}

package/dist/dashes.js

@@ -0,0 +1,172 @@
+/**
+ * Dash and hyphen transformation
+ *
+ * Converts hyphens and dashes to typographically correct em-dashes,
+ * en-dashes, and minus signs based on context.
+ */
+const DEFAULT_SEPARATOR = "\uE000";
+/**
+ * List of month names (full and abbreviated) for date range detection
+ */
+export const months = [
+    "January",
+    "February",
+    "March",
+    "April",
+    "May",
+    "June",
+    "July",
+    "August",
+    "September",
+    "October",
+    "November",
+    "December",
+    "Jan",
+    "Feb",
+    "Mar",
+    "Apr",
+    "May",
+    "Jun",
+    "Jul",
+    "Aug",
+    "Sep",
+    "Oct",
+    "Nov",
+    "Dec",
+].join("|");
+/**
+ * Replaces hyphens with en-dashes in number ranges.
+ *
+ * Handles:
+ * - Simple ranges: "1-5" → "1–5"
+ * - Page numbers: "p.206-207" → "p.206–207"
+ * - Dollar amounts: "$100-$200" → "$100–$200"
+ * - Comma-formatted numbers: "1,000-2,000" → "1,000–2,000"
+ *
+ * Does NOT replace:
+ * - Spaced ranges: "1 - 5" (ambiguous, could be subtraction)
+ * - Version numbers with decimals: "1.5-1.8"
+ *
+ * @param text - The text to transform
+ * @param options - Configuration options
+ * @returns The text with en-dashes in number ranges
+ *
+ * @example
+ * ```ts
+ * enDashNumberRange("pages 10-15")
+ * // → "pages 10–15"
+ * ```
+ */
+export function enDashNumberRange(text, options = {}) {
+    const chr = options.separator ?? DEFAULT_SEPARATOR;
+    return text.replace(new RegExp(`\\b(?<![a-zA-Z.])((?:p\\.?|\\$)?\\d[\\d.,]*${chr}?)-(${chr}?\\$?\\d[\\d.,]*)(?!\\.\\d)\\b`, "g"), "$1–$2");
+}
+/**
+ * Replaces hyphens with en-dashes in month/date ranges.
+ *
+ * Handles full and abbreviated month names:
+ * - "January-March" → "January–March"
+ * - "Jan-Mar" → "Jan–Mar"
+ *
+ * @param text - The text to transform
+ * @param options - Configuration options
+ * @returns The text with en-dashes in date ranges
+ *
+ * @example
+ * ```ts
+ * enDashDateRange("January-March 2024")
+ * // → "January–March 2024"
+ * ```
+ */
+export function enDashDateRange(text, options = {}) {
+    const chr = options.separator ?? DEFAULT_SEPARATOR;
+    return text.replace(new RegExp(`\\b(${months}${chr}?)-(${chr}?(?:${months}))\\b`, "g"), "$1–$2");
+}
+/**
+ * Replaces hyphens with proper minus signs (−) in numerical contexts.
+ *
+ * Handles negative numbers at:
+ * - Start of string/line
+ * - After whitespace
+ * - After opening parenthesis
+ * - After opening quote
+ *
+ * @param text - The text to transform
+ * @param options - Configuration options
+ * @returns The text with minus signs
+ *
+ * @example
+ * ```ts
+ * minusReplace("The temperature was -5 degrees")
+ * // → "The temperature was −5 degrees"
+ * ```
+ */
+export function minusReplace(text, options = {}) {
+    const chr = options.separator ?? DEFAULT_SEPARATOR;
+    const minusRegex = new RegExp(`(^|[\\s\\(${chr}""])-(\\s?\\d*\\.?\\d+)`, "gm");
+    return text.replaceAll(minusRegex, "$1−$2");
+}
+/**
+ * Comprehensive dash replacement for typographic correctness.
+ *
+ * Applies multiple transformations:
+ * 1. Converts hyphens to minus signs in numerical contexts
+ * 2. Converts surrounded dashes (- or --) to em-dashes (—)
+ * 3. Removes spaces around em-dashes (per modern style)
+ * 4. Preserves space after em-dash at start of line
+ * 5. Adds space after em-dash following quotation marks
+ * 6. Converts number ranges to en-dashes (1-5 → 1–5)
+ * 7. Converts date ranges to en-dashes (Jan-Mar → Jan–Mar)
+ *
+ * Does NOT modify:
+ * - Horizontal rules (---)
+ * - Compound modifiers (well-known, browser-specific)
+ * - Hyphens in quoted blockquotes ("> - item")
+ *
+ * @param text - The text to transform
+ * @param options - Configuration options
+ * @returns The text with proper dashes
+ *
+ * @example
+ * ```ts
+ * hyphenReplace("This is a - test")
+ * // → "This is a—test"
+ *
+ * hyphenReplace("Since--as you know")
+ * // → "Since—as you know"
+ *
+ * hyphenReplace("Pages 1-5")
+ * // → "Pages 1–5"
+ * ```
+ */
+export function hyphenReplace(text, options = {}) {
+    const chr = options.separator ?? DEFAULT_SEPARATOR;
+    text = minusReplace(text, options);
+    // Handle dashes with potential spaces and optional marker character
+    //  Being right after chr is a sufficient condition for being an em
+    //  dash, as it indicates the start of a new line
+    const preDash = new RegExp(`((?<markerBeforeTwo>${chr}?)[ ]+|(?<markerBeforeThree>${chr}))`);
+    // Want eg " - " to be replaced with "—"
+    const surroundedDash = new RegExp(`(?<=[^\\s>]|^)${preDash.source}[~–—-]+[ ]*(?<markerAfter>${chr}?)([ ]+|$)`, "g");
+    // Replace surrounded dashes with em dash
+    text = text.replace(surroundedDash, "$<markerBeforeTwo>$<markerBeforeThree>—$<markerAfter>");
+    // "Since--as you know" should be "Since—as you know"
+    const multipleDashInWords = new RegExp(`(?<=[A-Za-z\\d])(?<markerBefore>${chr}?)[~–—-]{2,}(?<markerAfter>${chr}?)(?=[A-Za-z\\d ])`, "g");
+    text = text.replace(multipleDashInWords, "$<markerBefore>—$<markerAfter>");
+    // Handle dashes at the start of a line
+    text = text.replace(new RegExp(`^(${chr})?[-]+ `, "gm"), "$1— ");
+    // Create a regex for spaces around em dashes, allowing for optional spaces around the em dash
+    const spacesAroundEM = new RegExp(`(?<markerBefore>${chr}?)[ ]*—[ ]*(?<markerAfter>${chr}?)[ ]*`, "g");
+    // Remove spaces around em dashes
+    text = text.replace(spacesAroundEM, "$<markerBefore>—$<markerAfter>");
+    // Handle special case after quotation marks
+    const postQuote = new RegExp(`(?<quote>[.!?]${chr}?['"'"]${chr}?|…)${spacesAroundEM.source}`, "g");
+    text = text.replace(postQuote, "$<quote> $<markerBefore>—$<markerAfter> ");
+    // Handle em dashes at the start of a line
+    const startOfLine = new RegExp(`^${spacesAroundEM.source}(?<after>[A-Z0-9])`, "gm");
+    text = text.replace(startOfLine, "$<markerBefore>—$<markerAfter> $<after>");
+    text = enDashNumberRange(text, options);
+    text = enDashDateRange(text, options);
+    return text;
+}
+//# sourceMappingURL=dashes.js.map

package/dist/dashes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dashes.js","sourceRoot":"","sources":["../src/dashes.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,47 @@
+/**
+ * punctilio - Smart typography transformations
+ *
+ * A library for converting plain ASCII punctuation into typographically
+ * correct Unicode characters. Handles smart quotes, em-dashes, en-dashes,
+ * minus signs, and more.
+ *
+ * @packageDocumentation
+ */
+export { niceQuotes, type QuoteOptions } from "./quotes.js";
+export { hyphenReplace, enDashNumberRange, enDashDateRange, minusReplace, months, type DashOptions, } from "./dashes.js";
+export interface TransformOptions {
+    /**
+     * A boundary marker character used when transforming text that spans
+     * multiple HTML elements. This character is treated as "transparent"
+     * in the regex patterns.
+     *
+     * Should be a character that doesn't appear in your text.
+     * Default: "\uE000" (Unicode Private Use Area)
+     */
+    separator?: string;
+}
+/**
+ * Applies all typography transformations: smart quotes and proper dashes.
+ *
+ * This is a convenience function that applies both `niceQuotes` and
+ * `hyphenReplace` in sequence.
+ *
+ * @param text - The text to transform
+ * @param options - Configuration options
+ * @returns The text with all typography improvements applied
+ *
+ * @example
+ * ```ts
+ * import { transform } from '@alexander-turner/punctilio'
+ *
+ * transform('"Hello," she said - "it\'s pages 1-5."')
+ * // → '"Hello," she said—"it's pages 1–5."'
+ * ```
+ */
+export declare function transform(text: string, options?: TransformOptions): string;
+/**
+ * Default separator character for boundary marking.
+ * Uses Unicode Private Use Area character U+E000.
+ */
+export declare const DEFAULT_SEPARATOR = "\uE000";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,UAAU,EAAE,KAAK,YAAY,EAAE,MAAM,aAAa,CAAA;AAC3D,OAAO,EACL,aAAa,EACb,iBAAiB,EACjB,eAAe,EACf,YAAY,EACZ,MAAM,EACN,KAAK,WAAW,GACjB,MAAM,aAAa,CAAA;AAEpB,MAAM,WAAW,gBAAgB;IAC/B;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAKD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,gBAAqB,GAAG,MAAM,CAI9E;AAED;;;GAGG;AACH,eAAO,MAAM,iBAAiB,WAAW,CAAA"}

package/dist/index.js

@@ -0,0 +1,42 @@
+/**
+ * punctilio - Smart typography transformations
+ *
+ * A library for converting plain ASCII punctuation into typographically
+ * correct Unicode characters. Handles smart quotes, em-dashes, en-dashes,
+ * minus signs, and more.
+ *
+ * @packageDocumentation
+ */
+export { niceQuotes } from "./quotes.js";
+export { hyphenReplace, enDashNumberRange, enDashDateRange, minusReplace, months, } from "./dashes.js";
+import { niceQuotes } from "./quotes.js";
+import { hyphenReplace } from "./dashes.js";
+/**
+ * Applies all typography transformations: smart quotes and proper dashes.
+ *
+ * This is a convenience function that applies both `niceQuotes` and
+ * `hyphenReplace` in sequence.
+ *
+ * @param text - The text to transform
+ * @param options - Configuration options
+ * @returns The text with all typography improvements applied
+ *
+ * @example
+ * ```ts
+ * import { transform } from '@alexander-turner/punctilio'
+ *
+ * transform('"Hello," she said - "it\'s pages 1-5."')
+ * // → '"Hello," she said—"it's pages 1–5."'
+ * ```
+ */
+export function transform(text, options = {}) {
+    text = hyphenReplace(text, options);
+    text = niceQuotes(text, options);
+    return text;
+}
+/**
+ * Default separator character for boundary marking.
+ * Uses Unicode Private Use Area character U+E000.
+ */
+export const DEFAULT_SEPARATOR = "\uE000";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,UAAU,EAAqB,MAAM,aAAa,CAAA;AAC3D,OAAO,EACL,aAAa,EACb,iBAAiB,EACjB,eAAe,EACf,YAAY,EACZ,MAAM,GAEP,MAAM,aAAa,CAAA;AAcpB,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AACxC,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAE3C;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,SAAS,CAAC,IAAY,EAAE,UAA4B,EAAE;IACpE,IAAI,GAAG,aAAa,CAAC,IAAI,EAAE,OAAO,CAAC,CAAA;IACnC,IAAI,GAAG,UAAU,CAAC,IAAI,EAAE,OAAO,CAAC,CAAA;IAChC,OAAO,IAAI,CAAA;AACb,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,QAAQ,CAAA"}

package/dist/quotes.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Smart quote transformation
+ *
+ * Converts straight quotes to typographically correct curly quotes,
+ * handling contractions, possessives, and nested quotes.
+ */
+export interface QuoteOptions {
+    /**
+     * A boundary marker character used when transforming text that spans
+     * multiple HTML elements. This character is treated as "transparent"
+     * in the regex patterns - it won't affect quote matching but allows
+     * the algorithm to work across element boundaries.
+     *
+     * Should be a character that doesn't appear in your text.
+     * Default: "\uE000" (Unicode Private Use Area)
+     */
+    separator?: string;
+}
+/**
+ * Converts standard quotes to typographic smart quotes.
+ *
+ * @param text - The text to transform
+ * @param options - Configuration options
+ * @returns The text with smart quotes
+ */
+export declare function niceQuotes(text: string, options?: QuoteOptions): string;
+//# sourceMappingURL=quotes.d.ts.map

package/dist/quotes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"quotes.d.ts","sourceRoot":"","sources":["../src/quotes.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,WAAW,YAAY;IAC3B;;;;;;;;OAQG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAYD;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,YAAiB,GAAG,MAAM,CA+D3E"}

package/dist/quotes.js

@@ -0,0 +1,66 @@
+/**
+ * Smart quote transformation
+ *
+ * Converts straight quotes to typographically correct curly quotes,
+ * handling contractions, possessives, and nested quotes.
+ */
+const DEFAULT_SEPARATOR = "\uE000";
+// Unicode typography characters
+const EM_DASH = "\u2014"; // —
+const LEFT_DOUBLE = "\u201C"; // "
+const RIGHT_DOUBLE = "\u201D"; // "
+const LEFT_SINGLE = "\u2018"; // '
+const RIGHT_SINGLE = "\u2019"; // '
+const ELLIPSIS = "\u2026"; // …
+/**
+ * Converts standard quotes to typographic smart quotes.
+ *
+ * @param text - The text to transform
+ * @param options - Configuration options
+ * @returns The text with smart quotes
+ */
+export function niceQuotes(text, options = {}) {
+    const chr = options.separator ?? DEFAULT_SEPARATOR;
+    // Single quotes //
+    // Ending comes first so as to not mess with the open quote
+    const afterEndingSinglePatterns = `\\s\\.!?;,\\)${EM_DASH}\\-\\]"`;
+    const afterEndingSingle = `(?=${chr}?(?:s${chr}?)?(?:[${afterEndingSinglePatterns}]|$))`;
+    const endingSingle = `(?<=[^\\s${LEFT_DOUBLE}'])[']${afterEndingSingle}`;
+    text = text.replace(new RegExp(endingSingle, "gm"), RIGHT_SINGLE);
+    // Contractions are sandwiched between two letters
+    const contraction = `(?<=[A-Za-z])['${RIGHT_SINGLE}](?=${chr}?[a-zA-Z])`;
+    text = text.replace(new RegExp(contraction, "gm"), RIGHT_SINGLE);
+    // Apostrophes always point down
+    //  Whitelist for eg rock 'n' roll
+    const apostropheWhitelist = `(?=n${RIGHT_SINGLE} )`;
+    const endQuoteNotContraction = `(?!${contraction})${RIGHT_SINGLE}${afterEndingSingle}`;
+    //  Convert to apostrophe if not followed by an end quote
+    // Note: The character class uses LEFT_SINGLE and ASCII straight quote (U+0027)
+    // NOT RIGHT_SINGLE - this is intentional for the algorithm to work correctly
+    const apostropheRegex = new RegExp(`(?<=^|[^\\w])'(${apostropheWhitelist}|(?![^${LEFT_SINGLE}'\\n]*${endQuoteNotContraction}))`, "gm");
+    text = text.replace(apostropheRegex, RIGHT_SINGLE);
+    // Beginning single quotes
+    const beginningSingle = `((?:^|[\\s${LEFT_DOUBLE}${RIGHT_DOUBLE}\\-\\(])${chr}?)['](?=${chr}?\\S)`;
+    text = text.replace(new RegExp(beginningSingle, "gm"), `$1${LEFT_SINGLE}`);
+    // Double quotes //
+    const beginningDouble = new RegExp(`(?<=^|[\\s\\(\\/\\[\\{\\-${EM_DASH}${chr}])(?<beforeChr>${chr}?)["](?<afterChr>(${chr}[ .,])|(?=${chr}?\\.{3}|${chr}?[^\\s\\)\\${EM_DASH},!?${chr};:.\\}]))`, "gm");
+    text = text.replace(beginningDouble, `$<beforeChr>${LEFT_DOUBLE}$<afterChr>`);
+    // Open quote after brace (generally in math mode)
+    text = text.replace(new RegExp(`(?<=\\{)(${chr}? )?["]`, "g"), `$1${LEFT_DOUBLE}`);
+    // note: Allowing 2 chrs in a row
+    const endingDouble = `([^\\s\\(])["](${chr}?)(?=${chr}|[\\s/\\).,;${EM_DASH}:\\-\\}!?s]|$)`;
+    text = text.replace(new RegExp(endingDouble, "g"), `$1${RIGHT_DOUBLE}$2`);
+    // If end of line, replace with right double quote
+    text = text.replace(new RegExp(`["](${chr}?)$`, "g"), `${RIGHT_DOUBLE}$1`);
+    // If single quote has a right double quote after it, replace with right single and then double
+    text = text.replace(new RegExp(`'(?=${RIGHT_DOUBLE})`, "gu"), RIGHT_SINGLE);
+    // Punctuation //
+    // Periods inside quotes
+    const periodRegex = new RegExp(`(?<![!?:\\.${ELLIPSIS}])(${chr}?)([${RIGHT_SINGLE}${RIGHT_DOUBLE}])(${chr}?)(?!\\.\\.\\.)\\.`, "g");
+    text = text.replace(periodRegex, "$1.$2$3");
+    // Commas outside of quotes
+    const commaRegex = new RegExp(`(?<![!?]),(${chr}?[${RIGHT_DOUBLE}${RIGHT_SINGLE}])`, "g");
+    text = text.replace(commaRegex, "$1,");
+    return text;
+}
+//# sourceMappingURL=quotes.js.map

package/dist/quotes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"quotes.js","sourceRoot":"","sources":["../src/quotes.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "punctilio",
+  "version": "0.1.0",
+  "description": "Smart typography transformations: curly quotes, em-dashes, en-dashes, and more",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "typography",
+    "smart-quotes",
+    "curly-quotes",
+    "em-dash",
+    "en-dash",
+    "typesetting",
+    "punctuation",
+    "text-formatting"
+  ],
+  "author": "Alexander Turner",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/alexander-turner/punctilio.git"
+  },
+  "bugs": {
+    "url": "https://github.com/alexander-turner/punctilio/issues"
+  },
+  "homepage": "https://github.com/alexander-turner/punctilio#readme",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.12",
+    "@types/node": "^20.11.0",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.1.2",
+    "typescript": "^5.3.3"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js",
+    "postinstall": "bash scripts/install-hooks.sh || true",
+    "install-hooks": "bash scripts/install-hooks.sh"
+  }
+}