@nuvin/ink 7.0.2-alpha → 7.1.1-alpha

package/readme.md

@@ -2527,6 +2527,53 @@ Type: `() => void`
 
 Resets `frame`, `time`, and `delta` to `0` and restarts timing from the current moment. Useful for one-shot animations triggered by events.
 
+### useTextSelection()
+
+A React hook exposing the instance-owned text selection: the currently selected terminal text plus actions to drive a selection programmatically. Ink paints the highlight as a final overlay on the rendered output and recomputes `text` as rows render.
+
+Selection is **Text-only**: only cells written by `<Text>` components are highlighted and extracted. Box borders, backgrounds, and padding/margin gaps are never part of a selection. Mark chrome text (icons, line-number gutters, diff markers) with `<Text selectable={false}>` to exclude it too — extraction drops chrome at the edges of a line and collapses interior chrome gaps to a single space.
+
+```jsx
+import {Text, useTextSelection} from 'ink';
+
+const SelectionFooter = () => {
+	const selection = useTextSelection();
+
+	return <Text dimColor>{selection.isEmpty ? 'no selection' : selection.text}</Text>;
+};
+```
+
+This hook is mouse-agnostic; mouse-driven selection (click-and-drag, edge auto-scroll) is provided by `useMouseTextSelection()` in `@nuvin/ink-input`, which drives these same actions.
+
+When a component only needs to *drive* the selection (mouse bridges, key handlers that clear it), use `useTextSelectionActions()` instead: it returns the same actions plus an imperative `getSnapshot()` but never subscribes, so the host component does not re-render on selection changes. Reserve `useTextSelection()` for components that display selection state.
+
+#### Return value
+
+- `anchor` / `focus` — `{x, y} | null` in **content space**: `x` is cells from the selection container's left edge, `y` is the content row index (survives scrolling).
+- `isDragging` — `boolean`, true between `start()` and `finish()`.
+- `text` — `string`, the selected text. Blank lines inside the selection are preserved; trailing whitespace is not selectable.
+- `isEmpty` — `boolean`, true when no text is selected.
+- `start(screenPoint)` / `update(screenPoint)` — begin/extend a selection. Points are 0-based **screen cells** on the Ink output grid; the registered viewport provider converts them to content space.
+- `finish()` — end the drag; the selected text stays available (and is frozen — if content reflows underneath a finished selection, it auto-clears rather than silently changing).
+- `clear()` — clear the selection and its row cache.
+- `registerViewportProvider(fn)` — register a function returning `{top, left, width, height, scrollY}` for the selection container (in output grid cells, `scrollY` in rendered rows). Providers stack: the most recently registered one is active (e.g. a modal's selection area over the main list's); the returned unregister function restores the previous provider. Registering or unregistering clears any live selection (its coordinate space changed). The provider returning `null` means "bounds not measurable this frame" and the frame is skipped. With no provider registered, the whole output grid is the viewport.
+- `setViewportProvider(fn | null)` — single-slot convenience over `registerViewportProvider`: replaces the provider set by the previous call (`null` unregisters it). Prefer `registerViewportProvider` where selection areas can overlap (overlays, modals).
+
+#### `<Text selectable>`
+
+Type: `boolean`\
+Default: `true`
+
+When `false`, the text is never highlighted and never appears in extracted selection text. Note that nested `<Text>` squashes into its outermost `<Text>` ancestor's write, so `selectable` must be set on the outermost text element (use sibling `<Text>` elements in a `<Box>` to mix chrome and content on one line).
+
+#### Known limits
+
+- Mouse-to-grid mapping (in `useMouseTextSelection`) assumes the Ink output starts at terminal cell (1,1) — i.e. fullscreen/alternate-screen apps.
+- The selection container must not be nested inside another scroll container (`getBounds()` ignores ancestor scroll offsets).
+- A Text node's own padding cells count as selectable.
+- Horizontal scrolling containers are not supported.
+- Clipboard integration is app-owned: read `useTextSelection().text` and apply your own copy policy.
+
 ## API
 
 #### render(tree, options?)

package/build/current-frame.d.ts

@@ -1,27 +0,0 @@
-export type SelectionScope = {
-    surfaceId: string;
-    itemKey: string;
-    itemIndex: number;
-    itemOffsetY: number;
-    originX: number;
-    originY: number;
-};
-export type RegisteredSelectionLine = {
-    key: string;
-    order: number;
-    text: string;
-    viewportX: number;
-    viewportY: number;
-    itemKey: string;
-};
-export type LogicalSelectionPoint = {
-    lineKey: string;
-    column: number;
-};
-export declare const recordSelectionFrame: (lines: readonly string[], scrollOffsetY: number, viewportTopY?: number) => void;
-export declare const getSelectionFrameCache: () => ReadonlyMap<number, string>;
-export declare const clearSelectionFrameCache: () => void;
-export declare const registerSelectionLines: (lines: readonly string[], scope: SelectionScope) => void;
-export declare const getRegisteredSelectionLines: () => ReadonlyMap<string, RegisteredSelectionLine>;
-export declare const clearRegisteredSelectionLines: () => void;
-export declare const getSelectionPointAtCell: (x: number, y: number) => LogicalSelectionPoint | null;

package/build/current-frame.js

@@ -1,73 +0,0 @@
-import stringWidth from 'string-width';
-const MAX_CACHED_ROWS = 2000;
-const MAX_REGISTERED_LINES = 5000;
-let selectionFrameCache = new Map();
-let registeredSelectionLines = new Map();
-export const recordSelectionFrame = (lines, scrollOffsetY, viewportTopY = 0) => {
-    for (let viewportY = viewportTopY; viewportY < lines.length; viewportY++) {
-        const contentY = scrollOffsetY + viewportY - viewportTopY;
-        const line = lines[viewportY] ?? '';
-        const existing = selectionFrameCache.get(contentY);
-        if (line.length === 0 && existing && existing.length > 0) {
-            continue;
-        }
-        selectionFrameCache.set(contentY, line);
-    }
-    while (selectionFrameCache.size > MAX_CACHED_ROWS) {
-        const oldestKey = selectionFrameCache.keys().next().value;
-        if (oldestKey === undefined)
-            break;
-        selectionFrameCache.delete(oldestKey);
-    }
-};
-export const getSelectionFrameCache = () => selectionFrameCache;
-export const clearSelectionFrameCache = () => {
-    selectionFrameCache = new Map();
-};
-const widthToColumn = (text, targetWidth) => {
-    let width = 0;
-    let column = 0;
-    for (const character of text) {
-        const nextWidth = width + Math.max(1, stringWidth(character));
-        if (targetWidth < nextWidth)
-            break;
-        width = nextWidth;
-        column++;
-    }
-    return column;
-};
-export const registerSelectionLines = (lines, scope) => {
-    for (let lineIndex = 0; lineIndex < lines.length; lineIndex++) {
-        const text = lines[lineIndex] ?? '';
-        const key = `${scope.surfaceId}:${scope.itemKey}:${lineIndex}`;
-        const viewportY = scope.originY + scope.itemOffsetY + lineIndex;
-        registeredSelectionLines.set(key, {
-            key,
-            order: viewportY * 100_000 + scope.originX,
-            text,
-            viewportX: scope.originX,
-            viewportY,
-            itemKey: scope.itemKey,
-        });
-    }
-    while (registeredSelectionLines.size > MAX_REGISTERED_LINES) {
-        const oldestKey = registeredSelectionLines.keys().next().value;
-        if (oldestKey === undefined)
-            break;
-        registeredSelectionLines.delete(oldestKey);
-    }
-};
-export const getRegisteredSelectionLines = () => registeredSelectionLines;
-export const clearRegisteredSelectionLines = () => {
-    registeredSelectionLines = new Map();
-};
-export const getSelectionPointAtCell = (x, y) => {
-    const line = [...registeredSelectionLines.values()]
-        .filter(candidate => candidate.viewportY === y)
-        .sort((left, right) => right.order - left.order || right.itemKey.length - left.itemKey.length)[0];
-    if (!line)
-        return null;
-    const column = widthToColumn(line.text, Math.max(0, x - line.viewportX));
-    return { lineKey: line.key, column };
-};
-//# sourceMappingURL=current-frame.js.map

package/build/current-frame.js.map

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

package/build/hooks/use-selection-overlay.d.ts

@@ -1,3 +0,0 @@
-import { type SelectionRange } from '../selection.js';
-declare const useSelectionOverlay: (range: SelectionRange | null) => void;
-export default useSelectionOverlay;

package/build/hooks/use-selection-overlay.js

@@ -1,14 +0,0 @@
-import { useLayoutEffect } from 'react';
-import { setSelectionRange } from '../selection.js';
-const useSelectionOverlay = (range) => {
-    useLayoutEffect(() => {
-        setSelectionRange(range);
-    });
-    useLayoutEffect(() => {
-        return () => {
-            setSelectionRange(null);
-        };
-    }, []);
-};
-export default useSelectionOverlay;
-//# sourceMappingURL=use-selection-overlay.js.map

package/build/hooks/use-selection-overlay.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"use-selection-overlay.js","sourceRoot":"","sources":["../../src/hooks/use-selection-overlay.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,eAAe,EAAC,MAAM,OAAO,CAAC;AACtC,OAAO,EAAC,iBAAiB,EAAsB,MAAM,iBAAiB,CAAC;AAEvE,MAAM,mBAAmB,GAAG,CAAC,KAA4B,EAAQ,EAAE;IAClE,eAAe,CAAC,GAAG,EAAE;QACpB,iBAAiB,CAAC,KAAK,CAAC,CAAC;IAC1B,CAAC,CAAC,CAAC;IAEH,eAAe,CAAC,GAAG,EAAE;QACpB,OAAO,GAAG,EAAE;YACX,iBAAiB,CAAC,IAAI,CAAC,CAAC;QACzB,CAAC,CAAC;IACH,CAAC,EAAE,EAAE,CAAC,CAAC;AACR,CAAC,CAAC;AAEF,eAAe,mBAAmB,CAAC"}

package/build/selection.d.ts

@@ -1,28 +0,0 @@
-export type SelectionPoint = {
-    x: number;
-    y: number;
-};
-export type SelectionStyle = {
-    backgroundColor?: string;
-    color?: string;
-};
-export type SelectionScope = {
-    surfaceId: string;
-    itemKey: string;
-    itemIndex: number;
-    itemOffsetY: number;
-    originX: number;
-    originY: number;
-};
-export type SelectionRange = {
-    anchor: SelectionPoint;
-    focus: SelectionPoint;
-    scrollOffsetY: number;
-    viewportTopY?: number;
-    viewportLeftX?: number;
-    scope?: SelectionScope;
-    style: SelectionStyle;
-};
-export declare const setSelectionRange: (range: SelectionRange | null) => void;
-export declare const getSelectionRange: () => SelectionRange | null;
-export declare const clearSelectionRange: () => void;

package/build/selection.js

@@ -1,9 +0,0 @@
-let currentSelectionRange = null;
-export const setSelectionRange = (range) => {
-    currentSelectionRange = range;
-};
-export const getSelectionRange = () => currentSelectionRange;
-export const clearSelectionRange = () => {
-    currentSelectionRange = null;
-};
-//# sourceMappingURL=selection.js.map

package/build/selection.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"selection.js","sourceRoot":"","sources":["../src/selection.ts"],"names":[],"mappings":"AA6BA,IAAI,qBAAqB,GAA0B,IAAI,CAAC;AAExD,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,KAA4B,EAAQ,EAAE;IACvE,qBAAqB,GAAG,KAAK,CAAC;AAC/B,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,iBAAiB,GAAG,GAA0B,EAAE,CAAC,qBAAqB,CAAC;AAEpF,MAAM,CAAC,MAAM,mBAAmB,GAAG,GAAS,EAAE;IAC7C,qBAAqB,GAAG,IAAI,CAAC;AAC9B,CAAC,CAAC"}