Namespace SharpConsoleUI.Helpers

Classes

AllocationGuard

Guards against integer overflow and unbounded allocations when computing buffer sizes from potentially untrusted dimensions. Use this whenever allocating arrays whose size derives from external input (image dimensions, video frame sizes, terminal coordinates from protocol responses).

BrailleHelpers

Shared static helpers for pixel-grid braille rendering. Provides Bresenham's line algorithm and braille character mapping for controls that render using Unicode Braille patterns (U+2800 block).

ClipboardHelper

Cross-platform clipboard helper for console applications. On Linux tries wl-clipboard, xclip, xsel. Falls back to an in-process buffer when no external tool is available. Operations are best-effort and will not throw on failure.

ColorBlendHelper

Shared color blending utilities used by flash overlay, fade animations, and other effects. Extracted to avoid code duplication between WindowStateService and WindowAnimations.

ColorGradient

Helper for creating and interpolating smooth color gradients. Supports predefined gradients (cool, warm, spectrum, grayscale) and custom gradients.

ColorResolver

Provides centralized color resolution logic for controls. Resolution chain: explicit value → theme slot → Color.Transparent. null and Color.Default are treated identically (both mean "no explicit value").

ColorRoleResolver

Derives a coordinated ColorRoleSet set from a single ColorRole, using per-theme seed colours (theme.PrimaryColor and friends) with a fall back to built-in defaults, plus the two non-null theme anchors. Pure and reflection-free — the single derivation brain shared by controls and the palette theme generator.

ContentHelper

Provides helper methods for content layout and positioning calculations.

ControlRenderingHelpers

Shared rendering utilities for controls to avoid code duplication. Pass Transparent as background to preserve whatever is already in the buffer (gradient, parent background, etc.).

DragAutoScroll

Pure step computation for drag-select autoscroll. Given the cursor's control-relative Y, the viewport height in rows, and the frame's elapsed time, returns the signed number of rows to scroll this frame. Distance-accelerated and time-normalized, with a fractional carry so speed stays smooth at any frame rate. No clock, no threads — fully unit-testable.

ExceptionFormatter

Writes ANSI-colored exception output to a TextWriter, replacing Spectre.Console's AnsiConsole.WriteException with zero external dependencies. Intended for crash-time reporting after Console.Clear().

FocusScrollHelper

Shared helpers for the focus scroll-into-view walk. When the focused control is nested deeper than a scroller's direct child (e.g. a button inside a non-scrolling CollapsiblePanel inside a ScrollablePanelControl), revealing the whole direct child is wrong: a tall direct child that already intersects the viewport is skipped by the "don't yank a spanning container to its top" guard, so the off-fold leaf is never revealed. These helpers compute the focused leaf's true row WITHIN the direct child so the scroller can reveal that row specifically.

GeometryHelpers

Provides static helper methods for Rectangle geometry operations. Extracted from ConsoleWindowSystem as part of Phase 3.1 refactoring. Consolidates duplicate geometry logic from multiple classes.

LinkHitTester

Resolves a clickable LinkSpan under a control-relative mouse position. Generalizes the per-row link lookup so any markup-rendering control can hit-test links against a per-row list of spans (display-column coordinates).

MouseGestureCapture<TRegion>

Sub-region gesture ownership for a control's mouse handling. On a fresh Button1 press (nothing captured) it hit-tests the region and captures it; every subsequent Button1 press/drag routes to the captured region without re-hit-testing (SGR re-sends Button1Pressed on motion, so a resent press mid- drag must NOT be treated as a fresh interaction with whatever region the cursor is now over); release ends the gesture. This is the same capture idea WindowEventDispatcher applies at the control level, applied at the sub-region level.

Osc52

Builds OSC 52 clipboard escape sequences (and the tmux passthrough-wrapped form). Pure string logic — no I/O. The caller writes the returned sequence to the terminal.

PaletteColors

Color derivation helpers for palette-based theme generation: tint (toward white), shade (toward black), mix (toward another color), relative luminance, and a readable contrast color. All are reflection-free and built on BlendColor(Color, Color, float).

PanelBorderRenderer

Shared box-border drawing primitives used by panel-style controls. Extracted from PanelControl so both it and CollapsiblePanel can render identical bordered chrome without duplicating the drawing logic.

PathValidator

Centralised path validation for preventing path traversal, symlink following, and access to sensitive system directories. All file-access paths in the framework that accept external input should validate through this class.

ProcessRunner

Safe process execution helper that prevents command injection by always using ArgumentList (never string-concatenated arguments). All process spawning in the framework should go through this class.

PropertySetterHelper

Helper class for property setters with validation and invalidation. Eliminates 200-250 lines of duplicated Width/Height/Color property patterns across 14+ controls.

ScrollbarHelper

Shared scrollbar geometry, drawing, and hit testing logic. Used by ListControl, TreeControl, and TableControl.

ScrollingHelper

Helper class for managing viewport scrolling logic across scrollable controls. Consolidates duplicated scroll adjustment code from TreeControl, ListControl, and DropdownControl.

SelectionStateHelper

Helper class for managing selection state updates across controls. Eliminates code duplication and prevents double event firing bugs.

SequenceHelper

Provides helper methods and constants for handling ANSI escape sequences, mouse input parsing, and keyboard input processing in console applications.

Size

Represents a size with width and height dimensions.

SliderRenderingHelper

Shared rendering and math utilities for SliderControl and RangeSliderControl. Eliminates code duplication between the two slider implementations.

SpinnerTextAnimator

Drives an arbitrary text setter from a looping spinner frame cycle, using the window system's animation manager. Useful for animating a status-bar label or window title without a dedicated control. Dispose or Stop to end the animation.

StringBuilderExtensions

Extension methods for StringBuilder to support Rune (supplementary plane) characters.

StringHelper

Provides helper methods for string manipulation operations.

TerminalCapabilities

Detects terminal rendering capabilities at runtime. Probed once during driver initialization; results are cached for the session.

TextMeasurementCache

Caches expensive text measurement operations for improved rendering performance. Eliminates duplicate measurements during rendering cycles (40+ calls per frame in complex controls). Thread-safe: uses ConcurrentDictionary to support concurrent read/write from render and UI threads.

TextSanitizer

Provides sanitization for text entering the character buffer. Prevents terminal escape injection by filtering control characters, BiDi overrides, and other unsafe runes before they reach cells.

TextTruncationHelper

Helper class for truncating text with ellipsis, handling Spectre.Console markup correctly. Consolidates 85% similar truncation logic from 4+ locations.

ThreadSafeStringBuilder

Provides a thread-safe wrapper around StringBuilder for concurrent string building operations.

UnicodeWidth

Provides display width information for Unicode characters. Delegates to the Wcwidth library for accurate width calculation including zero-width characters (combining marks, variation selectors, ZWJ). Spacing Combining Marks (Unicode category Mc) are corrected to width 1, as they occupy visual space in terminals despite Wcwidth marking them zero-width. Adapts to terminal capabilities: uses Unicode 15.0 width tables unless the terminal is detected to support Unicode 16.0 widths (probed at startup).

UrlLauncher

Opens URLs in the platform's default browser. Best-effort: pairs with the framework's markup and markdown link support so a clicked link can actually be opened. Never throws.

WordBoundaryHelper

Provides word boundary detection for text navigation and editing. Word characters: letters, digits, underscores. Everything else is a separator.

Structs

GestureRoute<TRegion>

The routing result of a mouse event through MouseGestureCapture<TRegion>: the gesture phase and the region the event is routed to.

Enums

ClipboardBackend

Identifies the clipboard backend in use.

GesturePhase

The phase of a captured mouse gesture as routed by MouseGestureCapture<TRegion>.

KeyCode

The KeyCode enumeration encodes key information from console drivers and provides a consistent way for application code to specify keys and receive key events.

Osc52Mode

Controls whether OSC 52 clipboard escapes are emitted on copy.

ScrollbarHitZone

Identifies which part of a scrollbar was hit by a click.