cz-typography
Version:
Universal Czech typography fixer for JavaScript, React, Next.js, and any SSR framework. Non-breaking spaces after one-letter prepositions, units, dates, ordinals and more.
204 lines (194 loc) • 6.59 kB
text/typescript
import * as react_jsx_runtime from 'react/jsx-runtime';
import React$1 from 'react';
/**
* Apply Czech typography rules to a string.
*
* Returns the input unchanged when it isn't a string, so the function is
* safe to call on `null`, `undefined`, numbers etc. without guarding.
*
* Pipeline order matters – `thousands` runs before `units`, otherwise the
* "10 000 km" case would steal the thousand-separator space as the
* number-to-unit space.
*
* @param {string} text
* @param {FixCzechOptions} [options]
* @returns {string}
*/
declare function fixCzech(text: string, options?: FixCzechOptions): string;
type FixCzechOptions = {
/**
* Glue one-letter prepositions/conjunctions to the next word.
*/
prepositions?: boolean;
/**
* Glue numbers to units of measurement.
*/
units?: boolean;
/**
* Glue initials (J., A.) to surnames.
*/
initials?: boolean;
/**
* Glue dates (5. 12. 2024) together.
*/
dates?: boolean;
/**
* Glue ordinal numbers (1. ledna) to the next word.
*/
ordinals?: boolean;
/**
* Glue names to Roman numerals (Karel IV.).
*/
roman?: boolean;
/**
* Replace thousands separators (10 000) with nbsp.
*/
thousands?: boolean;
};
/**
* @typedef {object} TypoProps
* @property {React.ReactNode} [children]
* @property {import('./fixCzech.js').FixCzechOptions} [options]
* @property {string} [as='span']
*/
/**
* Async server component that renders its children to static markup,
* applies {@link fixCzechHtml}, and re-injects the fixed markup via
* `dangerouslySetInnerHTML`.
*
* Suitable for self-contained text fragments (article body, headline,
* description). **Loses client interactivity inside the wrapped tree** –
* for whole-page coverage use the Next.js middleware or a Vite SSR
* pipeline instead.
*
* @param {TypoProps} props
*/
declare function Typo({ children, options, as: Tag }: TypoProps): react_jsx_runtime.JSX.Element;
type TypoProps = {
children?: React.ReactNode;
options?: FixCzechOptions;
as?: string;
};
/**
* Hook that returns the input string with Czech typography rules
* applied. Memoised on the text + serialised options so re-renders with
* the same input do not redo the work.
*
* @param {string} text
* @param {import('./fixCzech.js').FixCzechOptions} [options]
* @returns {string}
*/
declare function useFixCzech(text: string, options?: FixCzechOptions): string;
/**
* Apply Czech typography rules to an HTML string. Tags, attributes,
* comments, doctypes and the contents of `script`/`style`/`pre`/`code`/
* `textarea` elements are left untouched.
*
* @param {string} html
* @param {import('./fixCzech.js').FixCzechOptions} [options]
* @returns {string}
*/
declare function fixCzechHtml(html: string, options?: FixCzechOptions): string;
/**
* @typedef {object} TypoWrapperProps
* @property {React.ReactNode} [children] Child JSX/text to process.
* @property {'jsx' | 'dom'} [mode='jsx'] Processing strategy.
* @property {import('./fixCzech.js').FixCzechOptions} [options] All rule toggles in one object.
* @property {boolean} [prepositions] Shortcut for `options.prepositions`.
* @property {boolean} [units] Shortcut for `options.units`.
* @property {boolean} [initials] Shortcut for `options.initials`.
* @property {boolean} [dates] Shortcut for `options.dates`.
* @property {boolean} [ordinals] Shortcut for `options.ordinals`.
* @property {boolean} [roman] Shortcut for `options.roman`.
* @property {boolean} [thousands] Shortcut for `options.thousands`.
* @property {string} [as='span'] Element used to host the DOM-mode subtree.
*/
/**
* React component that applies Czech typography rules to its children.
*
* Two modes:
*
* - **`mode="jsx"` (default)** – traverses the React children tree at
* render time. Fast, no DOM mutations, but only sees text passed
* directly as children (won't reach into `<App />`).
* - **`mode="dom"`** – after mount, walks the rendered DOM subtree and
* fixes every text node, then uses a `MutationObserver` to keep
* following changes. Works for the entire app even when wrapping
* `<App />` in pure React or arbitrary nested components. SSR-safe –
* does nothing during server rendering, applies after hydration.
*
* @param {TypoWrapperProps} props
* @returns {JSX.Element}
*/
declare function TypoWrapper(props: TypoWrapperProps): JSX.Element;
type TypoWrapperProps = {
/**
* Child JSX/text to process.
*/
children?: React$1.ReactNode;
/**
* Processing strategy.
*/
mode?: "jsx" | "dom";
/**
* All rule toggles in one object.
*/
options?: FixCzechOptions;
/**
* Shortcut for `options.prepositions`.
*/
prepositions?: boolean;
/**
* Shortcut for `options.units`.
*/
units?: boolean;
/**
* Shortcut for `options.initials`.
*/
initials?: boolean;
/**
* Shortcut for `options.dates`.
*/
dates?: boolean;
/**
* Shortcut for `options.ordinals`.
*/
ordinals?: boolean;
/**
* Shortcut for `options.roman`.
*/
roman?: boolean;
/**
* Shortcut for `options.thousands`.
*/
thousands?: boolean;
/**
* Element used to host the DOM-mode subtree.
*/
as?: string;
};
/**
* Recursively walk a DOM subtree and apply Czech typography rules to
* every text node, skipping `<script>`, `<style>`, `<pre>`, `<code>`,
* `<textarea>` and `contenteditable` elements.
*
* Idempotent – calling this on the same subtree twice produces the same
* output (processed text nodes are tracked in a `WeakSet`).
*
* @param {Node} root
* @param {import('./fixCzech.js').FixCzechOptions} [options]
*/
declare function fixCzechDom(root: Node, options?: FixCzechOptions): void;
/**
* Begin observing `root` for DOM mutations and apply Czech typography
* rules to any text nodes that are added or modified. Returns a
* disconnect function.
*
* @param {Node} root
* @param {import('./fixCzech.js').FixCzechOptions} [options]
* @returns {() => void}
*/
declare function observeCzechDom(root: Node, options?: FixCzechOptions): () => void;
// @ts-ignore
export = TypoWrapper;
export { Typo, TypoWrapper, fixCzech, fixCzechDom, fixCzechHtml, observeCzechDom, useFixCzech };