@cbcruk/highlight-kit 0.1.0 → 0.2.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@cbcruk/highlight-kit",
   "description": "CSS Custom Highlight API 기반 텍스트 하이라이트 core와 React 어댑터",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "license": "MIT",
   "repository": {

package/dist/core-B8g04jvB.d.ts

@@ -1,168 +0,0 @@
-//#region src/core.d.ts
-/** Options controlling how a string pattern is matched against text. */
-interface MatchOptions {
-  /**
-   * Case sensitive match. Ignored for `RegExp` patterns, which keep their own flags.
-   * @default false
-   */
-  caseSensitive?: boolean;
-  /**
-   * Match whole words only (wraps the pattern in `\b`). Ignored for `RegExp` patterns.
-   * @default false
-   */
-  wholeWord?: boolean;
-}
-/** Reactive state of one highlight name, as exposed to subscribers. */
-interface HighlightSnapshot {
-  /** Whether this name currently has any registered ranges */
-  readonly active: boolean;
-  /** Number of ranges registered under this name */
-  readonly count: number;
-}
-/** A source contributing ranges, keyed by a unique id (e.g. React's useId) */
-type SourceId = string | symbol;
-/**
- * Where reconciled ranges are written. The controller's bookkeeping always
- * runs; only this side effect is swappable (CSS registry, no-op for tests/SSR).
- */
-interface HighlightSink {
-  /** Replace the registered highlight for `name` with `ranges`. */
-  commit(name: string, ranges: Range[], priority: number): void;
-  /** Drop the registered highlight for `name`. */
-  remove(name: string): void;
-  /**
-   * When this returns false the controller skips bookkeeping entirely, so
-   * snapshots stay empty. Omit it to always track ranges.
-   */
-  isSupported?(): boolean;
-}
-/** Options for {@link createHighlightController}. */
-interface HighlightControllerOptions {
-  /** Where reconciled ranges are written. Defaults to {@link createCssHighlightSink}. */
-  sink?: HighlightSink;
-}
-/** Whether the CSS Custom Highlight API (`CSS.highlights` and `Highlight`) is available. */
-declare function isHighlightSupported(): boolean;
-/**
- * Collect the text nodes under an element that contain non-whitespace text.
- *
- * Whitespace-only nodes (newlines, indentation between elements) are skipped,
- * so this is suited to pattern matching, not to offset math against `textContent`.
- */
-declare function getTextNodes(root: Node): Text[];
-/**
- * Compute Range objects for every match of `pattern` within `root`.
- * Pure: returns ranges, does not touch the registry.
- */
-declare function computeRanges(root: Element, pattern: string | RegExp, options?: MatchOptions): Range[];
-/**
- * Map flat character offsets onto Range objects. Useful when you already know positions.
- *
- * Offsets count over `root.textContent`, whitespace-only text nodes (newlines,
- * indentation between elements) included, so positions computed from
- * `textContent` or on a server against the same text line up. Unlike
- * {@link computeRanges}, a span may cross text node boundaries; it yields one
- * range per text node it touches. Out-of-bounds parts are ignored.
- *
- * @example
- * ```ts
- * import { rangesFromOffsets } from '@cbcruk/highlight-kit'
- *
- * const el = document.querySelector('#article')!
- * const start = el.textContent!.indexOf('wisdom')
- * rangesFromOffsets(el, [{ start, end: start + 'wisdom'.length }])
- * ```
- */
-declare function rangesFromOffsets(root: Element, spans: ReadonlyArray<{
-  start: number;
-  end: number;
-}>): Range[];
-/** Sink that writes to the document-global `CSS.highlights` registry. */
-declare function createCssHighlightSink(): HighlightSink;
-/** Side-effect-free sink: bookkeeping still runs, nothing is painted. */
-declare function createNoopSink(): HighlightSink;
-/**
- * Tracks ranges per highlight name and source, and writes their union to a sink.
- *
- * Multiple sources may contribute to one name; each change reconciles the name
- * into a single highlight and notifies `subscribe` listeners. Create instances
- * with {@link createHighlightController} or use the shared {@link highlights}.
- *
- * @example
- * ```ts
- * import { computeRanges, highlights } from '@cbcruk/highlight-kit'
- *
- * const el = document.querySelector('#article')!
- * highlights.set('search', 'my-source', computeRanges(el, 'wisdom'))
- * highlights.getSnapshot('search') // { active: true, count: ... }
- * highlights.remove('search', 'my-source')
- * ```
- */
-declare class HighlightController {
-  #private;
-  /** Create a controller that writes to `sink` (the CSS registry sink by default). */
-  constructor({ sink }?: HighlightControllerOptions);
-  /**
-   * Whether the sink reports support. `true` when the sink has no `isSupported`.
-   * When `false`, {@link HighlightController.set} is a no-op.
-   */
-  get supported(): boolean;
-  /** useSyncExternalStore: stable identity (arrow field on the instance). */
-  subscribe: (listener: () => void) => (() => void);
-  /** Snapshot for a given highlight name (referentially stable). */
-  getSnapshot: (name: string) => HighlightSnapshot;
-  /** Snapshots of every active name (referentially stable between changes). */
-  getSnapshots: () => Readonly<Record<string, HighlightSnapshot>>;
-  /** SSR / unsupported: constant empty snapshot. */
-  getServerSnapshot: () => HighlightSnapshot;
-  /** SSR / unsupported: constant empty record. */
-  getServerSnapshots: () => Readonly<Record<string, HighlightSnapshot>>;
-  /** Union of every source's ranges currently registered under `name`. */
-  getRanges(name: string): Range[];
-  /**
-   * Register/replace a source's ranges under a name, then reconcile.
-   * `priority` applies to the whole name; the most recent call wins.
-   */
-  set(name: string, sourceId: SourceId, ranges: Range[], priority?: number): void;
-  /** Remove a single source's contribution to a name. */
-  remove(name: string, sourceId: SourceId): void;
-  /** Drop a name entirely, regardless of sources. */
-  clear(name: string): void;
-  /** Drop everything this controller manages. */
-  clearAll(): void;
-}
-/**
- * Create an isolated controller. Useful for tests (with {@link createNoopSink})
- * or for scoping subscriptions via the React `HighlightProvider`. Highlight
- * *names* are still document-global once painted by a CSS sink.
- */
-declare function createHighlightController(options?: HighlightControllerOptions): HighlightController;
-/** The shared singleton. */
-declare const highlights: HighlightController;
-/**
- * Build `::highlight(name)` CSS rules from a style map without injecting them.
- *
- * camelCase property names are converted to kebab-case; values are written as is.
- *
- * @example
- * ```ts
- * import { generateHighlightCSS } from '@cbcruk/highlight-kit'
- *
- * generateHighlightCSS({ search: { backgroundColor: 'yellow' } })
- * // '::highlight(search) {\n  background-color: yellow;\n}'
- * ```
- */
-declare function generateHighlightCSS(styles: Record<string, Partial<CSSStyleDeclaration>>): string;
-/**
- * Append a `<style>` element with `::highlight()` rules to `document.head`.
- *
- * An existing element with the same `id` is removed first, so calling it again
- * replaces the previous rules.
- *
- * @param styles - Style declarations keyed by highlight name
- * @param id - `id` of the `<style>` element
- * @returns The inserted `<style>` element
- */
-declare function injectHighlightStyles(styles: Record<string, Partial<CSSStyleDeclaration>>, id?: string): HTMLStyleElement;
-//#endregion
-export { MatchOptions as a, createCssHighlightSink as c, generateHighlightCSS as d, getTextNodes as f, rangesFromOffsets as g, isHighlightSupported as h, HighlightSnapshot as i, createHighlightController as l, injectHighlightStyles as m, HighlightControllerOptions as n, SourceId as o, highlights as p, HighlightSink as r, computeRanges as s, HighlightController as t, createNoopSink as u };

package/dist/core-LUnH63zG.js

@@ -1,306 +0,0 @@
-//#region src/core.ts
-/** Stable empty snapshot — referentially constant for useSyncExternalStore */
-const EMPTY_SNAPSHOT = Object.freeze({
-	active: false,
-	count: 0
-});
-/** Whether the CSS Custom Highlight API (`CSS.highlights` and `Highlight`) is available. */
-function isHighlightSupported() {
-	return typeof CSS !== "undefined" && "highlights" in CSS && typeof Highlight !== "undefined";
-}
-/**
-* Collect the text nodes under an element that contain non-whitespace text.
-*
-* Whitespace-only nodes (newlines, indentation between elements) are skipped,
-* so this is suited to pattern matching, not to offset math against `textContent`.
-*/
-function getTextNodes(root) {
-	const nodes = [];
-	const walker = document.createTreeWalker(root, NodeFilter.SHOW_TEXT, null);
-	let node;
-	while (node = walker.nextNode()) if (node.textContent && node.textContent.trim()) nodes.push(node);
-	return nodes;
-}
-function toRegExp(pattern, options) {
-	if (pattern instanceof RegExp) return pattern.flags.includes("g") ? pattern : new RegExp(pattern.source, pattern.flags + "g");
-	const escaped = pattern.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-	const body = options.wholeWord ? `\\b${escaped}\\b` : escaped;
-	return new RegExp(body, options.caseSensitive ? "g" : "gi");
-}
-/**
-* Compute Range objects for every match of `pattern` within `root`.
-* Pure: returns ranges, does not touch the registry.
-*/
-function computeRanges(root, pattern, options = {}) {
-	if (!pattern) return [];
-	const regex = toRegExp(pattern, options);
-	const ranges = [];
-	for (const textNode of getTextNodes(root)) {
-		const text = textNode.textContent ?? "";
-		regex.lastIndex = 0;
-		let m;
-		while ((m = regex.exec(text)) !== null) {
-			if (m[0].length === 0) {
-				regex.lastIndex++;
-				continue;
-			}
-			try {
-				const range = new Range();
-				range.setStart(textNode, m.index);
-				range.setEnd(textNode, m.index + m[0].length);
-				ranges.push(range);
-			} catch {}
-		}
-	}
-	return ranges;
-}
-/** Collect every text node under `root`, whitespace-only ones included. */
-function getAllTextNodes(root) {
-	const nodes = [];
-	const walker = document.createTreeWalker(root, NodeFilter.SHOW_TEXT, null);
-	let node;
-	while (node = walker.nextNode()) nodes.push(node);
-	return nodes;
-}
-/**
-* Map flat character offsets onto Range objects. Useful when you already know positions.
-*
-* Offsets count over `root.textContent`, whitespace-only text nodes (newlines,
-* indentation between elements) included, so positions computed from
-* `textContent` or on a server against the same text line up. Unlike
-* {@link computeRanges}, a span may cross text node boundaries; it yields one
-* range per text node it touches. Out-of-bounds parts are ignored.
-*
-* @example
-* ```ts
-* import { rangesFromOffsets } from '@cbcruk/highlight-kit'
-*
-* const el = document.querySelector('#article')!
-* const start = el.textContent!.indexOf('wisdom')
-* rangesFromOffsets(el, [{ start, end: start + 'wisdom'.length }])
-* ```
-*/
-function rangesFromOffsets(root, spans) {
-	const nodes = getAllTextNodes(root);
-	const layout = [];
-	let offset = 0;
-	for (const node of nodes) {
-		const len = node.textContent?.length ?? 0;
-		if (len === 0) continue;
-		layout.push({
-			node,
-			start: offset,
-			end: offset + len
-		});
-		offset += len;
-	}
-	const ranges = [];
-	for (const { start, end } of spans) for (const { node, start: ns, end: ne } of layout) if (ns < end && ne > start) try {
-		const range = new Range();
-		range.setStart(node, Math.max(0, start - ns));
-		range.setEnd(node, Math.min(node.textContent?.length ?? 0, end - ns));
-		ranges.push(range);
-	} catch {}
-	return ranges;
-}
-/** Sink that writes to the document-global `CSS.highlights` registry. */
-function createCssHighlightSink() {
-	return {
-		commit(name, ranges, priority) {
-			if (!isHighlightSupported()) return;
-			const highlight = new Highlight(...ranges);
-			highlight.priority = priority;
-			CSS.highlights.set(name, highlight);
-		},
-		remove(name) {
-			if (!isHighlightSupported()) return;
-			CSS.highlights.delete(name);
-		},
-		isSupported: isHighlightSupported
-	};
-}
-/** Side-effect-free sink: bookkeeping still runs, nothing is painted. */
-function createNoopSink() {
-	return {
-		commit() {},
-		remove() {}
-	};
-}
-const EMPTY_SNAPSHOTS = Object.freeze({});
-/**
-* Tracks ranges per highlight name and source, and writes their union to a sink.
-*
-* Multiple sources may contribute to one name; each change reconciles the name
-* into a single highlight and notifies `subscribe` listeners. Create instances
-* with {@link createHighlightController} or use the shared {@link highlights}.
-*
-* @example
-* ```ts
-* import { computeRanges, highlights } from '@cbcruk/highlight-kit'
-*
-* const el = document.querySelector('#article')!
-* highlights.set('search', 'my-source', computeRanges(el, 'wisdom'))
-* highlights.getSnapshot('search') // { active: true, count: ... }
-* highlights.remove('search', 'my-source')
-* ```
-*/
-var HighlightController = class {
-	#sink;
-	/** name -> (sourceId -> ranges). Multiple sources may share a name. */
-	#entries = /* @__PURE__ */ new Map();
-	/** Cached per-name snapshots; refs are stable until that name changes. */
-	#snapshots = /* @__PURE__ */ new Map();
-	/** Cached name -> snapshot record; rebuilt on every emit. */
-	#allSnapshots = EMPTY_SNAPSHOTS;
-	/** External-store listeners. */
-	#listeners = /* @__PURE__ */ new Set();
-	/** Create a controller that writes to `sink` (the CSS registry sink by default). */
-	constructor({ sink = createCssHighlightSink() } = {}) {
-		this.#sink = sink;
-	}
-	/**
-	* Whether the sink reports support. `true` when the sink has no `isSupported`.
-	* When `false`, {@link HighlightController.set} is a no-op.
-	*/
-	get supported() {
-		return this.#sink.isSupported?.() ?? true;
-	}
-	/** useSyncExternalStore: stable identity (arrow field on the instance). */
-	subscribe = (listener) => {
-		this.#listeners.add(listener);
-		return () => this.#listeners.delete(listener);
-	};
-	/** Snapshot for a given highlight name (referentially stable). */
-	getSnapshot = (name) => {
-		return this.#snapshots.get(name) ?? EMPTY_SNAPSHOT;
-	};
-	/** Snapshots of every active name (referentially stable between changes). */
-	getSnapshots = () => {
-		return this.#allSnapshots;
-	};
-	/** SSR / unsupported: constant empty snapshot. */
-	getServerSnapshot = () => EMPTY_SNAPSHOT;
-	/** SSR / unsupported: constant empty record. */
-	getServerSnapshots = () => EMPTY_SNAPSHOTS;
-	/** Union of every source's ranges currently registered under `name`. */
-	getRanges(name) {
-		const entry = this.#entries.get(name);
-		return entry ? this.#merge(entry) : [];
-	}
-	/**
-	* Register/replace a source's ranges under a name, then reconcile.
-	* `priority` applies to the whole name; the most recent call wins.
-	*/
-	set(name, sourceId, ranges, priority = 0) {
-		if (!this.supported) return;
-		let entry = this.#entries.get(name);
-		if (!entry) {
-			entry = {
-				priority,
-				sources: /* @__PURE__ */ new Map()
-			};
-			this.#entries.set(name, entry);
-		} else entry.priority = priority;
-		entry.sources.set(sourceId, ranges);
-		this.#reconcile(name);
-		this.#emit();
-	}
-	/** Remove a single source's contribution to a name. */
-	remove(name, sourceId) {
-		const entry = this.#entries.get(name);
-		if (!entry || !entry.sources.delete(sourceId)) return;
-		if (entry.sources.size === 0) this.#entries.delete(name);
-		this.#reconcile(name);
-		this.#emit();
-	}
-	/** Drop a name entirely, regardless of sources. */
-	clear(name) {
-		if (!this.#entries.delete(name)) return;
-		this.#reconcile(name);
-		this.#emit();
-	}
-	/** Drop everything this controller manages. */
-	clearAll() {
-		const names = [...this.#entries.keys()];
-		this.#entries.clear();
-		for (const name of names) this.#sink.remove(name);
-		this.#snapshots.clear();
-		this.#emit();
-	}
-	#merge(entry) {
-		const all = [];
-		for (const ranges of entry.sources.values()) all.push(...ranges);
-		return all;
-	}
-	/** Union all sources for `name` into one highlight and update the snapshot. */
-	#reconcile(name) {
-		const entry = this.#entries.get(name);
-		const all = entry ? this.#merge(entry) : [];
-		if (!entry || all.length === 0) {
-			this.#sink.remove(name);
-			this.#snapshots.set(name, EMPTY_SNAPSHOT);
-			return;
-		}
-		this.#sink.commit(name, all, entry.priority);
-		this.#snapshots.set(name, {
-			active: true,
-			count: all.length
-		});
-	}
-	#emit() {
-		const next = {};
-		for (const [name, snapshot] of this.#snapshots) if (snapshot.active) next[name] = snapshot;
-		this.#allSnapshots = next;
-		for (const listener of this.#listeners) listener();
-	}
-};
-/**
-* Create an isolated controller. Useful for tests (with {@link createNoopSink})
-* or for scoping subscriptions via the React `HighlightProvider`. Highlight
-* *names* are still document-global once painted by a CSS sink.
-*/
-function createHighlightController(options) {
-	return new HighlightController(options);
-}
-/** The shared singleton. */
-const highlights = createHighlightController();
-/**
-* Build `::highlight(name)` CSS rules from a style map without injecting them.
-*
-* camelCase property names are converted to kebab-case; values are written as is.
-*
-* @example
-* ```ts
-* import { generateHighlightCSS } from '@cbcruk/highlight-kit'
-*
-* generateHighlightCSS({ search: { backgroundColor: 'yellow' } })
-* // '::highlight(search) {\n  background-color: yellow;\n}'
-* ```
-*/
-function generateHighlightCSS(styles) {
-	return Object.entries(styles).map(([name, style]) => {
-		return `::highlight(${name}) {\n${Object.entries(style).map(([prop, value]) => {
-			return `  ${prop.replace(/([A-Z])/g, "-$1").toLowerCase()}: ${value};`;
-		}).join("\n")}\n}`;
-	}).join("\n\n");
-}
-/**
-* Append a `<style>` element with `::highlight()` rules to `document.head`.
-*
-* An existing element with the same `id` is removed first, so calling it again
-* replaces the previous rules.
-*
-* @param styles - Style declarations keyed by highlight name
-* @param id - `id` of the `<style>` element
-* @returns The inserted `<style>` element
-*/
-function injectHighlightStyles(styles, id = "highlight-kit-styles") {
-	document.getElementById(id)?.remove();
-	const el = document.createElement("style");
-	el.id = id;
-	el.textContent = generateHighlightCSS(styles);
-	document.head.appendChild(el);
-	return el;
-}
-//#endregion
-export { generateHighlightCSS as a, injectHighlightStyles as c, createNoopSink as i, isHighlightSupported as l, createCssHighlightSink as n, getTextNodes as o, createHighlightController as r, highlights as s, computeRanges as t, rangesFromOffsets as u };