@cbcruk/highlight-kit 0.1.0 → 0.2.0

package/dist/react.d.ts

@@ -1,4 +1,4 @@
-import { a as MatchOptions, i as HighlightSnapshot, p as highlights, t as HighlightController } from "./core-B8g04jvB.js";
+import { F as TokenRule, N as OverlapStrategy, S as ValueRangeElement, a as HighlightSnapshot, m as highlights, o as MatchOptions, t as HighlightController } from "./core-DDCXN2b_.js";
 import { CSSProperties, ComponentPropsWithoutRef, ElementType, ReactNode, RefObject } from "react";
 //#region src/react.d.ts
 /** The controller in scope — the shared singleton unless a provider overrides it. */
@@ -259,5 +259,207 @@ export interface HighlightStylesProps {
  * {@link useHighlightSearch}.
  */
 export declare function HighlightStyles({ styles }: HighlightStylesProps): ReactNode;
+/** Options shared by the form-control hooks. */
+export interface ValueHighlightOptions {
+  /**
+   * The control's current value, for a controlled component.
+   *
+   * Assigning `value` collapses every live range and fires no `input` event, so
+   * without this the highlight would go stale on a programmatic change (a reset
+   * button, loading a template). Omit it for an uncontrolled control: typing is
+   * tracked through `input` either way.
+   */
+  value?: string;
+  /**
+   * Re-tokenize on the control's `input` events.
+   * @default true
+   */
+  observe?: boolean;
+}
+/** Options for {@link useValueTokens}. */
+export interface UseValueTokensOptions extends ValueHighlightOptions {
+  /**
+   * How matches covering the same characters resolve.
+   * @default 'first'
+   */
+  overlap?: OverlapStrategy;
+}
+/**
+ * Return value of {@link useValueTokens}.
+ *
+ * @template T - The form control element type
+ */
+export interface UseValueTokensResult<T extends ValueRangeElement> {
+  /** Attach to the `<input>` or `<textarea>` to tokenize. */
+  ref: RefObject<T | null>;
+  /** Whether this browser and this element support value ranges. */
+  supported: boolean;
+  /** Match count per highlight name, with an entry for every rule name. */
+  counts: Readonly<Record<string, number>>;
+}
+/**
+ * Tokenize a form control's value and highlight each rule's matches.
+ *
+ * The control's text is re-tokenized on every `input` event, with one highlight
+ * name per rule name, and the previous generation of live ranges is released.
+ * Rules are compared by content, so an inline rule array is fine.
+ *
+ * Needs `OpaqueRange` (Chromium 152+). Everywhere else `supported` is false and
+ * the hook does nothing, leaving the control to render normally.
+ *
+ * @template T - The form control element type
+ * @param rules - Ordered rules; earlier ones win, see {@link TokenRule}
+ * @returns The control ref, support flag, and per-name match counts
+ *
+ * @example A textarea highlighted like a code editor
+ * ```tsx
+ * import { HighlightStyles, useValueTokens } from '@cbcruk/highlight-kit/react'
+ *
+ * const RULES = [
+ *   { name: 'comment', pattern: /\/\/[^\n]*|\/\*[\s\S]*?\*\// },
+ *   { name: 'string', pattern: /'[^']*'|"[^"]*"/ },
+ *   { name: 'keyword', pattern: /\b(?:const|function|return)\b/ },
+ * ]
+ *
+ * function CodeArea() {
+ *   const { ref, supported, counts } = useValueTokens<HTMLTextAreaElement>(RULES)
+ *   return (
+ *     <>
+ *       <HighlightStyles
+ *         styles={{
+ *           comment: { color: '#6b7280' },
+ *           string: { color: '#16a34a' },
+ *           keyword: { color: '#7c3aed' },
+ *         }}
+ *       />
+ *       <textarea ref={ref} defaultValue="const x = 1 // note" />
+ *       {!supported && <p>This browser cannot highlight inside a textarea.</p>}
+ *       <small>{counts.keyword ?? 0} keywords</small>
+ *     </>
+ *   )
+ * }
+ * ```
+ */
+export declare function useValueTokens<T extends ValueRangeElement = HTMLTextAreaElement>(rules: readonly TokenRule[], options?: UseValueTokensOptions): UseValueTokensResult<T>;
+/** Options for {@link useValueHighlight}. */
+export interface UseValueHighlightOptions extends MatchOptions, ValueHighlightOptions {
+  /** Text or expression to highlight. Falsy clears this source. */
+  query: string | RegExp;
+  /** CSS `::highlight()` name. Defaults to a unique per-instance name. */
+  name?: string;
+  /**
+   * Stacking order against other highlight names.
+   * @default 0
+   */
+  priority?: number;
+}
+/**
+ * Return value of {@link useValueHighlight}.
+ *
+ * @template T - The form control element type
+ */
+export interface UseValueHighlightResult<T extends ValueRangeElement> extends HighlightSnapshot {
+  /** Attach to the `<input>` or `<textarea>` to scan. */
+  ref: RefObject<T | null>;
+  /** The resolved highlight name (auto-generated if not provided). */
+  name: string;
+  /** Whether this browser and this element support value ranges. */
+  supported: boolean;
+}
+/**
+ * Highlight one pattern inside an `<input>` or `<textarea>`.
+ *
+ * The single-pattern form of {@link useValueTokens} — the counterpart to
+ * {@link useHighlight}, which cannot reach into a form control's value.
+ *
+ * @template T - The form control element type
+ *
+ * @example Flagging a word as it is typed
+ * ```tsx
+ * import { useValueHighlight } from '@cbcruk/highlight-kit/react'
+ *
+ * function Composer() {
+ *   const { ref, count, supported } = useValueHighlight<HTMLTextAreaElement>({
+ *     query: /\bexample\b/gi,
+ *     name: 'flagged',
+ *   })
+ *   return (
+ *     <>
+ *       <style>{'::highlight(flagged) { background: #fde68a }'}</style>
+ *       <textarea ref={ref} />
+ *       {supported && <small>{count} occurrences</small>}
+ *     </>
+ *   )
+ * }
+ * ```
+ */
+export declare function useValueHighlight<T extends ValueRangeElement = HTMLInputElement>(options: UseValueHighlightOptions): UseValueHighlightResult<T>;
+/** Options for {@link useValueHighlightSearch}. */
+export interface UseValueHighlightSearchOptions extends MatchOptions, ValueHighlightOptions {
+  /**
+   * Base highlight name. The active match is registered under
+   * `${name}-current` with a higher priority.
+   * @default 'search'
+   */
+  name?: string;
+}
+/**
+ * Return value of {@link useValueHighlightSearch}.
+ *
+ * @template T - The form control element type
+ */
+export interface UseValueHighlightSearchResult<T extends ValueRangeElement> {
+  /** Attach to the `<input>` or `<textarea>` to search. */
+  ref: RefObject<T | null>;
+  /** Number of matches in the control's value. */
+  count: number;
+  /** Index of the active match, or -1 when there are no matches. */
+  active: number;
+  /** Move to the next match, wrapping to the first after the last. */
+  next(): void;
+  /** Move to the previous match, wrapping to the last before the first. */
+  prev(): void;
+  /** Whether this browser and this element support value ranges. */
+  supported: boolean;
+}
+/**
+ * Search inside an `<input>` or `<textarea>` with next/prev navigation.
+ *
+ * All matches go to `name`, the active one to `${name}-current` at a higher
+ * priority, and the control is scrolled just far enough to reveal the active
+ * match. Scrolling adjusts the control's own `scrollTop`/`scrollLeft` rather
+ * than calling `setSelectionRange()`, so the caret and the user's selection are
+ * left untouched.
+ *
+ * @template T - The form control element type
+ * @param query - Text or expression to find. Falsy clears the highlight
+ *
+ * @example
+ * ```tsx
+ * import { useState } from 'react'
+ * import {
+ *   HighlightStyles,
+ *   useValueHighlightSearch,
+ * } from '@cbcruk/highlight-kit/react'
+ *
+ * function NoteSearch() {
+ *   const [query, setQuery] = useState('')
+ *   const { ref, count, active, next, prev } =
+ *     useValueHighlightSearch<HTMLTextAreaElement>(query)
+ *
+ *   return (
+ *     <>
+ *       <HighlightStyles />
+ *       <input value={query} onChange={(e) => setQuery(e.target.value)} />
+ *       <span>{count === 0 ? '0/0' : `${active + 1}/${count}`}</span>
+ *       <button onClick={prev}>Prev</button>
+ *       <button onClick={next}>Next</button>
+ *       <textarea ref={ref} rows={10} />
+ *     </>
+ *   )
+ * }
+ * ```
+ */
+export declare function useValueHighlightSearch<T extends ValueRangeElement = HTMLTextAreaElement>(query: string | RegExp, options?: UseValueHighlightSearchOptions): UseValueHighlightSearchResult<T>;
 //#endregion
 export { highlights };

package/dist/react.js

@@ -1,4 +1,4 @@
-import { a as generateHighlightCSS, l as isHighlightSupported, r as createHighlightController, s as highlights, t as computeRanges } from "./core-LUnH63zG.js";
+import { _ as highlights, d as computeRanges, h as generateHighlightCSS, i as disconnectValueRanges, n as createValueRangeRegistry, p as createHighlightController, r as createValueRanges, s as scrollValueRangeIntoView, t as createValueHighlighter, u as tokenizeValue, y as isHighlightSupported } from "./value-range-CH2vegQi.js";
 import { createContext, createElement, forwardRef, useCallback, useContext, useEffect, useId, useImperativeHandle, useLayoutEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
 import { jsx } from "react/jsx-runtime";
 //#region src/react.tsx
@@ -316,5 +316,303 @@ const DEFAULT_SEARCH_STYLES = {
 function HighlightStyles({ styles = DEFAULT_SEARCH_STYLES }) {
 	return /* @__PURE__ */ jsx("style", { children: generateHighlightCSS(styles) });
 }
+/**
+* Stable identity for a rule list.
+*
+* Rule arrays are almost always written inline, so a new reference arrives on
+* every render. Keying effects on the rules' *content* instead keeps a fresh
+* array from tearing down and rebuilding the highlighter each render, which
+* would discard and recreate every live range.
+*/
+function useRulesKey(rules) {
+	return useMemo(() => JSON.stringify(rules.map((rule) => [
+		rule.name,
+		String(rule.pattern),
+		rule.caseSensitive ?? false,
+		rule.wholeWord ?? false,
+		rule.priority ?? 0
+	])), [rules]);
+}
+/**
+* Tokenize a form control's value and highlight each rule's matches.
+*
+* The control's text is re-tokenized on every `input` event, with one highlight
+* name per rule name, and the previous generation of live ranges is released.
+* Rules are compared by content, so an inline rule array is fine.
+*
+* Needs `OpaqueRange` (Chromium 152+). Everywhere else `supported` is false and
+* the hook does nothing, leaving the control to render normally.
+*
+* @template T - The form control element type
+* @param rules - Ordered rules; earlier ones win, see {@link TokenRule}
+* @returns The control ref, support flag, and per-name match counts
+*
+* @example A textarea highlighted like a code editor
+* ```tsx
+* import { HighlightStyles, useValueTokens } from '@cbcruk/highlight-kit/react'
+*
+* const RULES = [
+*   { name: 'comment', pattern: /\/\/[^\n]*|\/\*[\s\S]*?\*\// },
+*   { name: 'string', pattern: /'[^']*'|"[^"]*"/ },
+*   { name: 'keyword', pattern: /\b(?:const|function|return)\b/ },
+* ]
+*
+* function CodeArea() {
+*   const { ref, supported, counts } = useValueTokens<HTMLTextAreaElement>(RULES)
+*   return (
+*     <>
+*       <HighlightStyles
+*         styles={{
+*           comment: { color: '#6b7280' },
+*           string: { color: '#16a34a' },
+*           keyword: { color: '#7c3aed' },
+*         }}
+*       />
+*       <textarea ref={ref} defaultValue="const x = 1 // note" />
+*       {!supported && <p>This browser cannot highlight inside a textarea.</p>}
+*       <small>{counts.keyword ?? 0} keywords</small>
+*     </>
+*   )
+* }
+* ```
+*/
+function useValueTokens(rules, options = {}) {
+	const { overlap, value, observe = true } = options;
+	const controller = useHighlightController();
+	const sourceId = useId();
+	const ref = useRef(null);
+	const rulesKey = useRulesKey(rules);
+	const rulesRef = useRef(rules);
+	rulesRef.current = rules;
+	const highlighterRef = useRef(null);
+	const [supported, setSupported] = useState(false);
+	useIsomorphicLayoutEffect(() => {
+		const element = ref.current;
+		if (!element) return;
+		const highlighter = createValueHighlighter({
+			element,
+			rules: rulesRef.current,
+			overlap,
+			controller,
+			sourceId,
+			observe
+		});
+		highlighterRef.current = highlighter;
+		setSupported(highlighter.supported);
+		return () => {
+			highlighterRef.current = null;
+			highlighter.dispose();
+		};
+	}, [
+		controller,
+		sourceId,
+		rulesKey,
+		overlap,
+		observe
+	]);
+	const seenFirstValue = useRef(false);
+	useIsomorphicLayoutEffect(() => {
+		if (!seenFirstValue.current) {
+			seenFirstValue.current = true;
+			return;
+		}
+		highlighterRef.current?.refresh();
+	}, [value]);
+	const snapshots = useHighlightSnapshots();
+	return {
+		ref,
+		supported,
+		counts: useMemo(() => {
+			const result = {};
+			for (const rule of rulesRef.current) result[rule.name] = snapshots[rule.name]?.count ?? 0;
+			return result;
+		}, [snapshots, rulesKey])
+	};
+}
+/**
+* Highlight one pattern inside an `<input>` or `<textarea>`.
+*
+* The single-pattern form of {@link useValueTokens} — the counterpart to
+* {@link useHighlight}, which cannot reach into a form control's value.
+*
+* @template T - The form control element type
+*
+* @example Flagging a word as it is typed
+* ```tsx
+* import { useValueHighlight } from '@cbcruk/highlight-kit/react'
+*
+* function Composer() {
+*   const { ref, count, supported } = useValueHighlight<HTMLTextAreaElement>({
+*     query: /\bexample\b/gi,
+*     name: 'flagged',
+*   })
+*   return (
+*     <>
+*       <style>{'::highlight(flagged) { background: #fde68a }'}</style>
+*       <textarea ref={ref} />
+*       {supported && <small>{count} occurrences</small>}
+*     </>
+*   )
+* }
+* ```
+*/
+function useValueHighlight(options) {
+	const { query, priority = 0, caseSensitive, wholeWord, value, observe } = options;
+	const autoId = useId();
+	const name = options.name ?? `hk-value-${autoId}`;
+	const { ref, supported, counts } = useValueTokens(useMemo(() => query ? [{
+		name,
+		pattern: query,
+		caseSensitive,
+		wholeWord,
+		priority
+	}] : [], [
+		name,
+		query,
+		caseSensitive,
+		wholeWord,
+		priority
+	]), {
+		value,
+		observe
+	});
+	const count = counts[name] ?? 0;
+	return {
+		ref,
+		name,
+		supported,
+		count,
+		active: count > 0
+	};
+}
+/**
+* Search inside an `<input>` or `<textarea>` with next/prev navigation.
+*
+* All matches go to `name`, the active one to `${name}-current` at a higher
+* priority, and the control is scrolled just far enough to reveal the active
+* match. Scrolling adjusts the control's own `scrollTop`/`scrollLeft` rather
+* than calling `setSelectionRange()`, so the caret and the user's selection are
+* left untouched.
+*
+* @template T - The form control element type
+* @param query - Text or expression to find. Falsy clears the highlight
+*
+* @example
+* ```tsx
+* import { useState } from 'react'
+* import {
+*   HighlightStyles,
+*   useValueHighlightSearch,
+* } from '@cbcruk/highlight-kit/react'
+*
+* function NoteSearch() {
+*   const [query, setQuery] = useState('')
+*   const { ref, count, active, next, prev } =
+*     useValueHighlightSearch<HTMLTextAreaElement>(query)
+*
+*   return (
+*     <>
+*       <HighlightStyles />
+*       <input value={query} onChange={(e) => setQuery(e.target.value)} />
+*       <span>{count === 0 ? '0/0' : `${active + 1}/${count}`}</span>
+*       <button onClick={prev}>Prev</button>
+*       <button onClick={next}>Next</button>
+*       <textarea ref={ref} rows={10} />
+*     </>
+*   )
+* }
+* ```
+*/
+function useValueHighlightSearch(query, options = {}) {
+	const { name = "search", caseSensitive, wholeWord, value, observe = true } = options;
+	const controller = useHighlightController();
+	const sourceId = useId();
+	const ref = useRef(null);
+	const registryRef = useRef(null);
+	const [spans, setSpans] = useState([]);
+	const [active, setActive] = useState(0);
+	const [supported, setSupported] = useState(false);
+	useIsomorphicLayoutEffect(() => {
+		const element = ref.current;
+		if (!element) return;
+		const registry = createValueRangeRegistry({
+			element,
+			controller,
+			sourceId
+		});
+		registryRef.current = registry;
+		setSupported(registry.supported);
+		return () => {
+			registryRef.current = null;
+			registry.dispose();
+		};
+	}, [controller, sourceId]);
+	useIsomorphicLayoutEffect(() => {
+		const element = ref.current;
+		if (!element) return;
+		const recompute = () => {
+			const next = query ? tokenizeValue(element.value, [{
+				name,
+				pattern: query,
+				caseSensitive,
+				wholeWord
+			}]).map(({ start, end }) => ({
+				start,
+				end
+			})) : [];
+			setSpans((previous) => previous.length === next.length && previous.every((span, i) => span.start === next[i].start && span.end === next[i].end) ? previous : next);
+		};
+		recompute();
+		if (!observe) return;
+		element.addEventListener("input", recompute);
+		return () => element.removeEventListener("input", recompute);
+	}, [
+		name,
+		query,
+		caseSensitive,
+		wholeWord,
+		value,
+		observe
+	]);
+	useIsomorphicLayoutEffect(() => {
+		setActive((a) => spans.length === 0 ? 0 : Math.min(a, spans.length - 1));
+	}, [spans]);
+	useIsomorphicLayoutEffect(() => {
+		const registry = registryRef.current;
+		if (!registry) return;
+		const current = spans[active];
+		registry.commit([{
+			name,
+			priority: 0,
+			spans
+		}, ...current ? [{
+			name: `${name}-current`,
+			priority: 1,
+			spans: [current]
+		}] : []]);
+	}, [
+		name,
+		spans,
+		active
+	]);
+	useEffect(() => {
+		const element = ref.current;
+		const current = spans[active];
+		if (!element || !current) return;
+		const ranges = createValueRanges(element, [current]);
+		if (ranges[0]) scrollValueRangeIntoView(element, ranges[0]);
+		disconnectValueRanges(ranges);
+	}, [spans, active]);
+	const next = useCallback(() => setActive((a) => spans.length ? (a + 1) % spans.length : 0), [spans.length]);
+	const prev = useCallback(() => setActive((a) => spans.length ? (a - 1 + spans.length) % spans.length : 0), [spans.length]);
+	return {
+		ref,
+		count: spans.length,
+		active: spans.length ? active : -1,
+		next,
+		prev,
+		supported
+	};
+}
 //#endregion
-export { Highlight, HighlightMatch, HighlightProvider, HighlightRoot, HighlightStyles, highlights, useHighlight, useHighlightController, useHighlightRanges, useHighlightSearch, useHighlightSnapshots, useHighlightState, useHighlightSupport, useTextMatches };
+export { Highlight, HighlightMatch, HighlightProvider, HighlightRoot, HighlightStyles, highlights, useHighlight, useHighlightController, useHighlightRanges, useHighlightSearch, useHighlightSnapshots, useHighlightState, useHighlightSupport, useTextMatches, useValueHighlight, useValueHighlightSearch, useValueTokens };