@develemit/web-hooks 0.3.0 → 0.4.0

package/dist/terminal-output.d.cts

@@ -0,0 +1,186 @@
+import { RefObject } from 'react';
+
+type AnsiColor = {
+    kind: 'ansi';
+    index: number;
+} | {
+    kind: 'rgb';
+    r: number;
+    g: number;
+    b: number;
+};
+interface AnsiStyle {
+    fg?: AnsiColor;
+    bg?: AnsiColor;
+    bold?: boolean;
+    dim?: boolean;
+    italic?: boolean;
+    underline?: boolean;
+    inverse?: boolean;
+}
+interface AnsiSegment extends AnsiStyle {
+    text: string;
+    href?: string;
+}
+type AnsiLine = AnsiSegment[];
+interface ParseAnsiOptions {
+    /** URL schemes kept on OSC 8 hyperlinks. Default `['http', 'https', 'file']`. */
+    linkSchemes?: readonly string[];
+}
+
+/** Removes CSI, OSC and two-byte escape sequences. Leaves `\r` and `\n` alone. */
+declare function stripAnsi(text: string): string;
+/**
+ * Turns raw terminal text into lines of styled segments. `\r` and cursor-up
+ * redraws overwrite earlier text the way a terminal would. Cursor-up/down,
+ * column set (`G`), erase-line and erase-below are emulated; every other
+ * escape sequence is dropped. Text is never interpreted as markup.
+ */
+declare function parseAnsi(text: string, options?: ParseAnsiOptions): AnsiLine[];
+/** Like `parseAnsi`, but colour and link state carry from one call to the next. */
+declare function createAnsiParser(options?: ParseAnsiOptions): {
+    parse: (chunk: string) => AnsiLine[];
+    reset: () => void;
+};
+
+type StreamCursor = number | string;
+interface LineBufferOptions {
+    /** Most complete lines kept. Older ones are dropped and counted. */
+    maxLines: number;
+}
+interface LineBufferUpdate {
+    /** Complete raw lines from this push, escape codes intact. */
+    lines: string[];
+    /** The unfinished line, raw, without an escape code still being written. */
+    partial: string;
+    /** Lines this push pushed out of the buffer. */
+    dropped: number;
+}
+interface LineBuffer {
+    push(chunk: string | Uint8Array, options?: {
+        cursor?: StreamCursor;
+    }): LineBufferUpdate;
+    /** Ends the stream: the unfinished line becomes a complete one. */
+    flush(): LineBufferUpdate;
+    reset(): void;
+    /** The lines still held, oldest first. */
+    readonly lines: readonly string[];
+    readonly partial: string;
+    /** The server's cursor from the last push that had one. Ask for `since: cursor` on reconnect. */
+    readonly cursor: StreamCursor | undefined;
+    /** Lines dropped over the buffer's life. */
+    readonly dropped: number;
+}
+/**
+ * Turns stream chunks (strings or bytes) into complete lines. Resuming is the
+ * server's job: pass its cursor to `push` and read `cursor` back on reconnect.
+ * The buffer never compares text, so a log that repeats a line keeps both.
+ */
+declare function createLineBuffer({ maxLines }: LineBufferOptions): LineBuffer;
+
+interface AnsiStreamOptions extends ParseAnsiOptions {
+    /** Rendered lines above the cursor that a redraw can still overwrite. Default 50. */
+    tailLines?: number;
+}
+/**
+ * Rows from `from` on are replaced by `lines`. Row numbers count from the first
+ * row of the stream. Truncate your list to `from` rows, then append `lines`.
+ */
+interface AnsiStreamUpdate {
+    replaced?: {
+        from: number;
+        lines: AnsiLine[];
+    };
+}
+interface AnsiStream {
+    /** Feeds newly completed raw lines and the current unfinished line. */
+    push(lines: readonly string[], partial?: string): AnsiStreamUpdate;
+    /**
+     * Ends the stream. Renders the unfinished line without adding a newline;
+     * pass `partial` to replace the one given to the last `push`. Pushes after
+     * this are ignored until `reset()`.
+     */
+    finish(partial?: string): AnsiStreamUpdate;
+    reset(): void;
+}
+/**
+ * Renders a stream the way `parseAnsi` renders the whole text, line by line.
+ * It keeps a small screen tail so cursor-up redraws reach rows already shown,
+ * and says which rows changed. Older rows are frozen and forgotten.
+ */
+declare function createAnsiStream(options?: AnsiStreamOptions): AnsiStream;
+
+interface TextSegment {
+    text: string;
+    match: boolean;
+}
+type FailureTool = 'vitest' | 'nx' | 'tsc' | 'pnpm' | 'npm' | 'docker' | 'generic';
+interface FailurePattern {
+    tool: FailureTool;
+    kind: string;
+    pattern: RegExp;
+}
+interface Failure {
+    index: number;
+    tool: FailureTool;
+    kind: string;
+}
+declare function filterLines(lines: readonly string[], query: string): number[];
+declare function splitByMatch(line: string, query: string): TextSegment[];
+declare const FAILURE_PATTERNS: readonly FailurePattern[];
+declare function findFailures(lines: readonly string[], patterns?: readonly FailurePattern[]): Failure[];
+declare function firstFailureIndex(lines: readonly string[], patterns?: readonly FailurePattern[]): number;
+declare const NOISE_PATTERNS: readonly RegExp[];
+declare function isNoise(line: string, patterns?: readonly RegExp[]): boolean;
+declare function tailMeaningful(lines: readonly string[], n: number, patterns?: readonly RegExp[]): string[];
+
+interface ScrollMetrics {
+    scrollTop: number;
+    scrollHeight: number;
+    clientHeight: number;
+}
+declare const DEFAULT_TAIL_THRESHOLD = 24;
+declare function distanceFromEnd({ scrollTop, scrollHeight, clientHeight }: ScrollMetrics): number;
+/** Within `threshold` px of the end; negative distances (iOS rubber-band past the end) count. */
+declare function isNearEnd(metrics: ScrollMetrics, threshold?: number): boolean;
+/**
+ * Whether the view should keep following after a scroll event. A scroll the hook made itself
+ * never changes the answer; a user scroll follows only while it ends near the end.
+ */
+declare function shouldStick(prevAtBottom: boolean, metrics: ScrollMetrics, userInitiated: boolean, threshold?: number): boolean;
+type ScrollEventKind = 'scroll' | 'wheel' | 'touch' | 'gutter';
+interface ScrollEventInfo {
+    kind: ScrollEventKind;
+    /** wheel: `deltaY`. touch: how far the finger moved down since touchstart. Unused otherwise. */
+    delta?: number;
+    /** Where the hook last scrolled to, or null when it hasn't since the user last took over. */
+    lastTarget: number | null;
+    scrollTop: number;
+}
+/**
+ * Whether an event is the user reading upward, whichever frame it lands in. Wheel-up, a finger
+ * dragging down and a press on the scrollbar are intent; a scroll event counts only when it sits
+ * below where the hook last scrolled to, because the hook only ever scrolls down.
+ */
+declare function isUserScrollUp({ kind, delta, lastTarget, scrollTop }: ScrollEventInfo, threshold?: number): boolean;
+/** Items to add to the unread count after the list grew while the user is reading above the end. */
+declare function unreadDelta(prevCount: number, nextCount: number, attached: boolean): number;
+
+interface UseFollowTailOptions {
+    scrollRef: RefObject<HTMLElement | null>;
+    itemCount: number;
+    /** Scroll to the last item. A virtualizer passes `() => virtualizer.scrollToIndex(count - 1, { align: 'end' })`. */
+    scrollToEnd?: () => void;
+    /** Snap back to the bottom whenever this changes (a project switch). */
+    resetKey?: unknown;
+    /** Distance from the end that still counts as the bottom. Default 24. */
+    threshold?: number;
+}
+interface UseFollowTailResult {
+    atBottom: boolean;
+    unread: number;
+    jumpToBottom: () => void;
+}
+declare function useFollowTail({ scrollRef, itemCount, scrollToEnd, resetKey, threshold, }: UseFollowTailOptions): UseFollowTailResult;
+
+export { type AnsiColor, type AnsiLine, type AnsiSegment, type AnsiStream, type AnsiStreamOptions, type AnsiStreamUpdate, type AnsiStyle, DEFAULT_TAIL_THRESHOLD, FAILURE_PATTERNS, type Failure, type FailurePattern, type FailureTool, type LineBuffer, type LineBufferOptions, type LineBufferUpdate, NOISE_PATTERNS, type ParseAnsiOptions, type ScrollEventInfo, type ScrollEventKind, type ScrollMetrics, type StreamCursor, type TextSegment, type UseFollowTailOptions, type UseFollowTailResult, createAnsiParser, createAnsiStream, createLineBuffer, distanceFromEnd, filterLines, findFailures, firstFailureIndex, isNearEnd, isNoise, isUserScrollUp, parseAnsi, shouldStick, splitByMatch, stripAnsi, tailMeaningful, unreadDelta, useFollowTail };

package/dist/terminal-output.d.ts

@@ -0,0 +1,186 @@
+import { RefObject } from 'react';
+
+type AnsiColor = {
+    kind: 'ansi';
+    index: number;
+} | {
+    kind: 'rgb';
+    r: number;
+    g: number;
+    b: number;
+};
+interface AnsiStyle {
+    fg?: AnsiColor;
+    bg?: AnsiColor;
+    bold?: boolean;
+    dim?: boolean;
+    italic?: boolean;
+    underline?: boolean;
+    inverse?: boolean;
+}
+interface AnsiSegment extends AnsiStyle {
+    text: string;
+    href?: string;
+}
+type AnsiLine = AnsiSegment[];
+interface ParseAnsiOptions {
+    /** URL schemes kept on OSC 8 hyperlinks. Default `['http', 'https', 'file']`. */
+    linkSchemes?: readonly string[];
+}
+
+/** Removes CSI, OSC and two-byte escape sequences. Leaves `\r` and `\n` alone. */
+declare function stripAnsi(text: string): string;
+/**
+ * Turns raw terminal text into lines of styled segments. `\r` and cursor-up
+ * redraws overwrite earlier text the way a terminal would. Cursor-up/down,
+ * column set (`G`), erase-line and erase-below are emulated; every other
+ * escape sequence is dropped. Text is never interpreted as markup.
+ */
+declare function parseAnsi(text: string, options?: ParseAnsiOptions): AnsiLine[];
+/** Like `parseAnsi`, but colour and link state carry from one call to the next. */
+declare function createAnsiParser(options?: ParseAnsiOptions): {
+    parse: (chunk: string) => AnsiLine[];
+    reset: () => void;
+};
+
+type StreamCursor = number | string;
+interface LineBufferOptions {
+    /** Most complete lines kept. Older ones are dropped and counted. */
+    maxLines: number;
+}
+interface LineBufferUpdate {
+    /** Complete raw lines from this push, escape codes intact. */
+    lines: string[];
+    /** The unfinished line, raw, without an escape code still being written. */
+    partial: string;
+    /** Lines this push pushed out of the buffer. */
+    dropped: number;
+}
+interface LineBuffer {
+    push(chunk: string | Uint8Array, options?: {
+        cursor?: StreamCursor;
+    }): LineBufferUpdate;
+    /** Ends the stream: the unfinished line becomes a complete one. */
+    flush(): LineBufferUpdate;
+    reset(): void;
+    /** The lines still held, oldest first. */
+    readonly lines: readonly string[];
+    readonly partial: string;
+    /** The server's cursor from the last push that had one. Ask for `since: cursor` on reconnect. */
+    readonly cursor: StreamCursor | undefined;
+    /** Lines dropped over the buffer's life. */
+    readonly dropped: number;
+}
+/**
+ * Turns stream chunks (strings or bytes) into complete lines. Resuming is the
+ * server's job: pass its cursor to `push` and read `cursor` back on reconnect.
+ * The buffer never compares text, so a log that repeats a line keeps both.
+ */
+declare function createLineBuffer({ maxLines }: LineBufferOptions): LineBuffer;
+
+interface AnsiStreamOptions extends ParseAnsiOptions {
+    /** Rendered lines above the cursor that a redraw can still overwrite. Default 50. */
+    tailLines?: number;
+}
+/**
+ * Rows from `from` on are replaced by `lines`. Row numbers count from the first
+ * row of the stream. Truncate your list to `from` rows, then append `lines`.
+ */
+interface AnsiStreamUpdate {
+    replaced?: {
+        from: number;
+        lines: AnsiLine[];
+    };
+}
+interface AnsiStream {
+    /** Feeds newly completed raw lines and the current unfinished line. */
+    push(lines: readonly string[], partial?: string): AnsiStreamUpdate;
+    /**
+     * Ends the stream. Renders the unfinished line without adding a newline;
+     * pass `partial` to replace the one given to the last `push`. Pushes after
+     * this are ignored until `reset()`.
+     */
+    finish(partial?: string): AnsiStreamUpdate;
+    reset(): void;
+}
+/**
+ * Renders a stream the way `parseAnsi` renders the whole text, line by line.
+ * It keeps a small screen tail so cursor-up redraws reach rows already shown,
+ * and says which rows changed. Older rows are frozen and forgotten.
+ */
+declare function createAnsiStream(options?: AnsiStreamOptions): AnsiStream;
+
+interface TextSegment {
+    text: string;
+    match: boolean;
+}
+type FailureTool = 'vitest' | 'nx' | 'tsc' | 'pnpm' | 'npm' | 'docker' | 'generic';
+interface FailurePattern {
+    tool: FailureTool;
+    kind: string;
+    pattern: RegExp;
+}
+interface Failure {
+    index: number;
+    tool: FailureTool;
+    kind: string;
+}
+declare function filterLines(lines: readonly string[], query: string): number[];
+declare function splitByMatch(line: string, query: string): TextSegment[];
+declare const FAILURE_PATTERNS: readonly FailurePattern[];
+declare function findFailures(lines: readonly string[], patterns?: readonly FailurePattern[]): Failure[];
+declare function firstFailureIndex(lines: readonly string[], patterns?: readonly FailurePattern[]): number;
+declare const NOISE_PATTERNS: readonly RegExp[];
+declare function isNoise(line: string, patterns?: readonly RegExp[]): boolean;
+declare function tailMeaningful(lines: readonly string[], n: number, patterns?: readonly RegExp[]): string[];
+
+interface ScrollMetrics {
+    scrollTop: number;
+    scrollHeight: number;
+    clientHeight: number;
+}
+declare const DEFAULT_TAIL_THRESHOLD = 24;
+declare function distanceFromEnd({ scrollTop, scrollHeight, clientHeight }: ScrollMetrics): number;
+/** Within `threshold` px of the end; negative distances (iOS rubber-band past the end) count. */
+declare function isNearEnd(metrics: ScrollMetrics, threshold?: number): boolean;
+/**
+ * Whether the view should keep following after a scroll event. A scroll the hook made itself
+ * never changes the answer; a user scroll follows only while it ends near the end.
+ */
+declare function shouldStick(prevAtBottom: boolean, metrics: ScrollMetrics, userInitiated: boolean, threshold?: number): boolean;
+type ScrollEventKind = 'scroll' | 'wheel' | 'touch' | 'gutter';
+interface ScrollEventInfo {
+    kind: ScrollEventKind;
+    /** wheel: `deltaY`. touch: how far the finger moved down since touchstart. Unused otherwise. */
+    delta?: number;
+    /** Where the hook last scrolled to, or null when it hasn't since the user last took over. */
+    lastTarget: number | null;
+    scrollTop: number;
+}
+/**
+ * Whether an event is the user reading upward, whichever frame it lands in. Wheel-up, a finger
+ * dragging down and a press on the scrollbar are intent; a scroll event counts only when it sits
+ * below where the hook last scrolled to, because the hook only ever scrolls down.
+ */
+declare function isUserScrollUp({ kind, delta, lastTarget, scrollTop }: ScrollEventInfo, threshold?: number): boolean;
+/** Items to add to the unread count after the list grew while the user is reading above the end. */
+declare function unreadDelta(prevCount: number, nextCount: number, attached: boolean): number;
+
+interface UseFollowTailOptions {
+    scrollRef: RefObject<HTMLElement | null>;
+    itemCount: number;
+    /** Scroll to the last item. A virtualizer passes `() => virtualizer.scrollToIndex(count - 1, { align: 'end' })`. */
+    scrollToEnd?: () => void;
+    /** Snap back to the bottom whenever this changes (a project switch). */
+    resetKey?: unknown;
+    /** Distance from the end that still counts as the bottom. Default 24. */
+    threshold?: number;
+}
+interface UseFollowTailResult {
+    atBottom: boolean;
+    unread: number;
+    jumpToBottom: () => void;
+}
+declare function useFollowTail({ scrollRef, itemCount, scrollToEnd, resetKey, threshold, }: UseFollowTailOptions): UseFollowTailResult;
+
+export { type AnsiColor, type AnsiLine, type AnsiSegment, type AnsiStream, type AnsiStreamOptions, type AnsiStreamUpdate, type AnsiStyle, DEFAULT_TAIL_THRESHOLD, FAILURE_PATTERNS, type Failure, type FailurePattern, type FailureTool, type LineBuffer, type LineBufferOptions, type LineBufferUpdate, NOISE_PATTERNS, type ParseAnsiOptions, type ScrollEventInfo, type ScrollEventKind, type ScrollMetrics, type StreamCursor, type TextSegment, type UseFollowTailOptions, type UseFollowTailResult, createAnsiParser, createAnsiStream, createLineBuffer, distanceFromEnd, filterLines, findFailures, firstFailureIndex, isNearEnd, isNoise, isUserScrollUp, parseAnsi, shouldStick, splitByMatch, stripAnsi, tailMeaningful, unreadDelta, useFollowTail };

package/dist/terminal-output.js

@@ -0,0 +1,45 @@
+"use client";
+import {
+  DEFAULT_TAIL_THRESHOLD,
+  FAILURE_PATTERNS,
+  NOISE_PATTERNS,
+  createAnsiParser,
+  createAnsiStream,
+  createLineBuffer,
+  distanceFromEnd,
+  filterLines,
+  findFailures,
+  firstFailureIndex,
+  isNearEnd,
+  isNoise,
+  isUserScrollUp,
+  parseAnsi,
+  shouldStick,
+  splitByMatch,
+  stripAnsi,
+  tailMeaningful,
+  unreadDelta,
+  useFollowTail
+} from "./chunk-TE2FRIPF.js";
+export {
+  DEFAULT_TAIL_THRESHOLD,
+  FAILURE_PATTERNS,
+  NOISE_PATTERNS,
+  createAnsiParser,
+  createAnsiStream,
+  createLineBuffer,
+  distanceFromEnd,
+  filterLines,
+  findFailures,
+  firstFailureIndex,
+  isNearEnd,
+  isNoise,
+  isUserScrollUp,
+  parseAnsi,
+  shouldStick,
+  splitByMatch,
+  stripAnsi,
+  tailMeaningful,
+  unreadDelta,
+  useFollowTail
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@develemit/web-hooks",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Shared React behavior hooks for develemit web apps: drawer swipe, focus trap, escape key and clipboard.",
   "license": "MIT",
   "author": "Emit Dutcher",
@@ -109,6 +109,11 @@
       "types": "./dist/push.d.ts",
       "import": "./dist/push.js",
       "require": "./dist/push.cjs"
+    },
+    "./terminal-output": {
+      "types": "./dist/terminal-output.d.ts",
+      "import": "./dist/terminal-output.js",
+      "require": "./dist/terminal-output.cjs"
     }
   },
   "main": "./dist/index.cjs",
@@ -128,6 +133,7 @@
   "devDependencies": {
     "@eslint/js": "^9.0.0",
     "@testing-library/react": "^16.0.0",
+    "@types/node": "^20.19.43",
     "@types/react": "^19.0.0",
     "@types/react-18": "npm:@types/react@^18.3.31",
     "@types/react-dom": "^19.0.0",