@valyrianjs/terminal 0.1.1 → 0.2.0

package/src/types.ts

@@ -0,0 +1,541 @@
+export type AnyProps = Record<string, any> | null | undefined;
+
+export type TerminalPrimitiveTag =
+  | "terminal-screen"
+  | "terminal-box"
+  | "terminal-view"
+  | "terminal-pane"
+  | "terminal-split"
+  | "terminal-fixed"
+  | "terminal-overlay"
+  | "terminal-focus-scope"
+  | "terminal-text"
+  | "terminal-input"
+  | "terminal-editor"
+  | "terminal-button"
+  | "terminal-scroll"
+  | "terminal-log-view"
+  | "terminal-list"
+  | "terminal-table"
+  | "terminal-row"
+  | "terminal-td";
+
+export type TerminalCommandScope = "global" | "focus" | "input" | "editor" | "button" | "list" | "scroll";
+
+export type TerminalCommandId =
+  | "focus.next"
+  | "focus.prev"
+  | "button.press"
+  | "list.prev"
+  | "list.next"
+  | "list.press"
+  | "scroll.up"
+  | "scroll.down"
+  | "input.submit"
+  | "input.backspace"
+  | "input.delete"
+  | "input.cursorLeft"
+  | "input.cursorRight"
+  | "input.selectLeft"
+  | "input.selectRight"
+  | "input.wordLeft"
+  | "input.wordRight"
+  | "input.home"
+  | "input.end"
+  | "input.selectAll"
+  | "input.copy"
+  | "input.paste"
+  | "input.pasteText"
+  | "input.cut"
+  | "input.insertText"
+  | "editor.submit"
+  | "editor.cancel"
+  | "editor.newline"
+  | "editor.backspace"
+  | "editor.delete"
+  | "editor.cursorLeft"
+  | "editor.cursorRight"
+  | "editor.cursorUp"
+  | "editor.cursorDown"
+  | "editor.home"
+  | "editor.end"
+  | "editor.paste"
+  | "editor.pasteText"
+  | "editor.insertText"
+  | (string & {});
+
+export interface TerminalCommand {
+  id: TerminalCommandId;
+  text?: string;
+}
+
+export interface TerminalCommandContext {
+  key: string;
+  focusedId?: string;
+  focusedTag?: TerminalPrimitiveTag;
+}
+
+export interface TerminalKeyBindingCondition {
+  focusedId?: string;
+  focusedTag?: TerminalPrimitiveTag;
+}
+
+export interface TerminalKeyBinding {
+  key: string;
+  command: TerminalCommand;
+  scope?: TerminalCommandScope;
+  when?: TerminalKeyBindingCondition;
+}
+
+export interface TerminalKeymapOptions {
+  bindings?: TerminalKeyBinding[];
+  onCommand?(command: TerminalCommand, context: TerminalCommandContext): boolean | void;
+}
+
+export interface VnodeLike {
+  tag: any;
+  props: AnyProps;
+  children: any[];
+}
+
+export interface TerminalTextNode {
+  type: "text";
+  value: string;
+}
+
+export interface TerminalElementNode {
+  type: "element";
+  tag: TerminalPrimitiveTag;
+  props: Record<string, any>;
+  children: TerminalNode[];
+}
+
+export type TerminalNode = TerminalTextNode | TerminalElementNode;
+
+export interface TerminalFocusNode extends TerminalElementNode {
+  props: Record<string, any> & { id?: string };
+}
+
+export interface TerminalHitbox {
+  id: string;
+  tag: TerminalPrimitiveTag;
+  x1: number;
+  x2: number;
+  y1: number;
+  y2: number;
+  textStartX?: number;
+  textLength?: number;
+  itemOffset?: number;
+  pointerLayer?: number;
+}
+
+export interface CursorPosition {
+  x: number;
+  y: number;
+}
+
+export interface TerminalSelectionRange {
+  x1: number;
+  x2: number;
+  y: number;
+}
+
+export type TerminalSemanticStyleKind =
+  | "selection"
+  | "focus"
+  | "highlight"
+  | "current-row"
+  | "hover"
+  | "disabled"
+  | "error"
+  | "warning"
+  | "success"
+  | "muted";
+
+export interface TerminalStyleToken {
+  color?: TerminalColor;
+  background?: TerminalColor;
+  style?: TerminalStyleDefinition;
+  ansiOpen?: string;
+  ansiClose?: string;
+  plainPrefix?: string;
+  plainSuffix?: string;
+}
+
+export type TerminalVisualState =
+  | "focus" | "hover" | "disabled" | "loading"
+  | "pressed" | "checked" | "unchecked" | "indeterminate"
+  | "selected" | "current" | "expanded" | "collapsed"
+  | "invalid" | "valid" | "readonly" | "placeholder" | "selection" | "editing" | "submitted"
+  | "empty" | "error" | "warning" | "success" | "muted"
+  | "dragging" | "dropTarget" | "capturing";
+
+export type TerminalColor = string;
+export type TerminalStyleReference = string;
+export type TerminalSpacing = number | { x?: number; y?: number; top?: number; right?: number; bottom?: number; left?: number };
+export type TerminalBorderStyle = "solid" | "dotted" | "double" | string;
+export type TerminalBorder = boolean | TerminalBorderStyle | {
+  top?: boolean;
+  right?: boolean;
+  bottom?: boolean;
+  left?: boolean;
+  style?: TerminalBorderStyle;
+  color?: TerminalColor;
+};
+
+export interface TerminalStyleDefinition {
+  color?: TerminalColor;
+  background?: TerminalColor;
+  border?: TerminalBorder;
+  padding?: TerminalSpacing;
+  plainPrefix?: string;
+  plainSuffix?: string;
+}
+
+export type TerminalStyleRecipeKey = keyof TerminalStyleDefinition;
+export type TerminalStyleTree = {
+  [key: string]: TerminalStyleDefinition[TerminalStyleRecipeKey] | TerminalStyleTree | undefined;
+};
+export type TerminalStyleValue = TerminalStyleReference | TerminalStyleDefinition;
+export type TerminalStateStyles = Partial<Record<TerminalVisualState, TerminalStyleValue>>;
+export interface TerminalStyleProps {
+  style?: TerminalStyleValue;
+  styles?: TerminalStateStyles;
+  state?: TerminalVisualState | TerminalVisualState[];
+}
+
+export interface TerminalTheme {
+  styles?: TerminalStyleTree;
+  spans?: Partial<Record<TerminalSemanticStyleKind | (string & {}), TerminalStyleToken>>;
+}
+
+export interface TerminalStyleSpan extends TerminalSelectionRange {
+  kind: TerminalSemanticStyleKind | (string & {});
+  style?: TerminalStyleDefinition;
+}
+
+export interface TerminalFrame {
+  lines: string[];
+  hitboxes: TerminalHitbox[];
+  cursor: CursorPosition | null;
+  spans: TerminalStyleSpan[];
+}
+
+export interface TerminalSize {
+  cols: number;
+  rows: number;
+}
+
+export interface InputInteractionState {
+  cursor: number;
+  anchor: number;
+}
+
+export interface TerminalClipboardAdapter {
+  readText?(): string | undefined;
+  writeText?(value: string): void;
+}
+
+export interface TerminalFocusableProps {
+  id?: string;
+  focusable?: boolean;
+}
+
+export interface TerminalPointerCaptureProps {
+  pointerCapture?: boolean;
+}
+
+export interface TerminalDirectiveProps {
+  "v-for"?: any[];
+}
+
+export interface TerminalLayoutProps extends TerminalFocusableProps, TerminalStyleProps {
+  direction?: "row" | "column";
+  gap?: number;
+  padding?: TerminalSpacing;
+  width?: number;
+  height?: number;
+  fill?: boolean;
+}
+
+export interface TerminalEventPayloadBase {
+  id: string;
+}
+
+export interface TerminalValueEventPayloadBase<T = string> extends TerminalEventPayloadBase {
+  value: T;
+}
+
+export interface TerminalInputChangeEventPayload extends TerminalValueEventPayloadBase<string> {
+  type: "change" | "input";
+}
+
+export interface TerminalInputSubmitEventPayload extends TerminalValueEventPayloadBase<string> {
+  type: "submit";
+}
+
+export interface TerminalEditorChangeEventPayload extends TerminalValueEventPayloadBase<string> {
+  type: "change" | "input";
+}
+
+export interface TerminalEditorSubmitEventPayload extends TerminalValueEventPayloadBase<string> {
+  type: "submit";
+}
+
+export interface TerminalEditorCancelEventPayload extends TerminalValueEventPayloadBase<string> {
+  type: "cancel";
+}
+
+export interface TerminalButtonPressEventPayload extends TerminalEventPayloadBase {
+  type: "press" | "doublepress" | "contextpress";
+}
+
+export interface TerminalListChangeEventPayload<T = any> extends TerminalValueEventPayloadBase<T> {
+  type: "change";
+  index: number;
+}
+
+export interface TerminalListPressEventPayload<T = any> extends TerminalValueEventPayloadBase<T> {
+  type: "press" | "doublepress" | "contextpress";
+  index: number;
+}
+
+export type TerminalChangeEventPayload =
+  | TerminalInputChangeEventPayload
+  | TerminalEditorChangeEventPayload
+  | TerminalListChangeEventPayload<any>;
+
+export type TerminalPressEventPayload = TerminalButtonPressEventPayload | TerminalListPressEventPayload<any>;
+
+export interface TerminalInputContextPressEventPayload extends TerminalValueEventPayloadBase<string>, TerminalPointerCoordinates {
+  type: "contextpress";
+  cursor: number;
+}
+
+export interface TerminalScrollContextPressEventPayload extends TerminalRowPointerEventPayloadBase {
+  type: "contextpress";
+  value: string;
+}
+
+export type TerminalMouseEventType = "hover" | "rowenter" | "rowleave";
+
+export type TerminalPointerSource = "press" | "drag" | "release";
+
+export interface TerminalPointerCoordinates {
+  x: number | null;
+  y: number | null;
+}
+
+export interface TerminalRowPointerEventPayloadBase extends TerminalPointerCoordinates {
+  id: string;
+  row: number;
+}
+
+export interface TerminalListPointerEventPayload<T = any> extends TerminalRowPointerEventPayloadBase {
+  type: TerminalMouseEventType;
+  index: number;
+  value: T;
+}
+
+export interface TerminalScrollPointerEventPayload extends TerminalRowPointerEventPayloadBase {
+  type: TerminalMouseEventType;
+  value: string;
+}
+
+export type TerminalRowPointerEventPayload = TerminalListPointerEventPayload<any> | TerminalScrollPointerEventPayload;
+
+export interface TerminalCaptureEventPayload extends TerminalPointerCoordinates {
+  type: "capturestart" | "captureend";
+  id: string;
+  source: TerminalPointerSource;
+  row: number | null;
+}
+
+export interface TerminalInputProps extends TerminalFocusableProps, TerminalStyleProps {
+  value?: string;
+  placeholder?: string;
+  onchange?(event: TerminalInputChangeEventPayload): void;
+  oninput?(event: TerminalInputChangeEventPayload): void;
+  onsubmit?(event: TerminalInputSubmitEventPayload): void;
+  oncontextpress?(event: TerminalInputContextPressEventPayload): void;
+}
+
+export interface TerminalEditorProps extends TerminalFocusableProps, TerminalStyleProps {
+  value?: string;
+  placeholder?: string;
+  height?: number;
+  onchange?(event: TerminalEditorChangeEventPayload): void;
+  oninput?(event: TerminalEditorChangeEventPayload): void;
+  onsubmit?(event: TerminalEditorSubmitEventPayload): void;
+  oncancel?(event: TerminalEditorCancelEventPayload): void;
+}
+
+export interface TerminalButtonProps extends TerminalFocusableProps, TerminalStyleProps {
+  label?: string;
+  onpress?(event: TerminalButtonPressEventPayload): void;
+  ondoublepress?(event: TerminalButtonPressEventPayload): void;
+  oncontextpress?(event: TerminalButtonPressEventPayload): void;
+}
+
+export interface TerminalListProps<T = any> extends TerminalFocusableProps, TerminalPointerCaptureProps, TerminalStyleProps {
+  items?: readonly T[];
+  virtualized?: boolean;
+  itemHeight?: 1;
+  overscan?: number;
+  renderItem?(item: T, index: number): string;
+  onchange?(event: TerminalListChangeEventPayload<T>): void;
+  onpress?(event: TerminalListPressEventPayload<T>): void;
+  ondoublepress?(event: TerminalListPressEventPayload<T>): void;
+  oncontextpress?(event: TerminalListPressEventPayload<T>): void;
+  onhover?(event: TerminalListPointerEventPayload<T>): void;
+  onrowenter?(event: TerminalListPointerEventPayload<T>): void;
+  onrowleave?(event: TerminalListPointerEventPayload<T>): void;
+  oncapturestart?(event: TerminalCaptureEventPayload): void;
+  oncaptureend?(event: TerminalCaptureEventPayload): void;
+}
+
+export interface TerminalScrollViewProps extends TerminalLayoutProps, TerminalPointerCaptureProps {
+  highlightRows?: number[];
+  onhover?(event: TerminalScrollPointerEventPayload): void;
+  onrowenter?(event: TerminalScrollPointerEventPayload): void;
+  onrowleave?(event: TerminalScrollPointerEventPayload): void;
+  oncontextpress?(event: TerminalScrollContextPressEventPayload): void;
+  oncapturestart?(event: TerminalCaptureEventPayload): void;
+  oncaptureend?(event: TerminalCaptureEventPayload): void;
+}
+
+export interface TerminalLogViewEntry {
+  id: string;
+  content: string;
+}
+
+export interface TerminalLogViewProps extends TerminalLayoutProps {
+  entries?: readonly TerminalLogViewEntry[];
+  followTail?: boolean;
+  emptyText?: string;
+  renderEntry?(entry: TerminalLogViewEntry, index: number): string;
+}
+
+export interface TerminalScreenProps extends TerminalFocusableProps {
+  title?: string;
+}
+
+export interface TerminalBoxProps extends TerminalLayoutProps {}
+
+export interface TerminalViewProps extends TerminalLayoutProps {
+  role?: string;
+}
+
+export interface TerminalPaneProps extends TerminalLayoutProps {}
+
+export type TerminalSplitSize = number | `${number}%` | `${number}fr`;
+export interface TerminalSplitBreakpoint {
+  maxCols?: number;
+  maxRows?: number;
+  direction?: "row" | "column";
+  sizes?: TerminalSplitSize[];
+  gap?: number;
+}
+
+export interface TerminalSplitProps extends TerminalFocusableProps {
+  direction?: "row" | "column";
+  width?: number;
+  height?: number;
+  fill?: boolean;
+  sizes?: TerminalSplitSize[];
+  breakpoints?: TerminalSplitBreakpoint[];
+  gap?: number;
+}
+
+export interface TerminalFixedProps {
+  position: "top" | "bottom" | "left" | "right";
+  size: number;
+}
+
+export type TerminalOverlayMarginValue = number | `${number}%`;
+
+export interface TerminalOverlayMarginAxes {
+  x: TerminalOverlayMarginValue;
+  y: TerminalOverlayMarginValue;
+}
+
+export interface TerminalOverlayProps extends TerminalFocusableProps, TerminalStyleProps {
+  margin: TerminalOverlayMarginValue | TerminalOverlayMarginAxes;
+  trapFocus?: boolean;
+}
+
+export interface TerminalFocusScopeProps {
+  active?: boolean;
+}
+
+export interface TerminalTextProps extends TerminalStyleProps {
+  value?: any;
+}
+
+export interface TerminalTableProps extends TerminalDirectiveProps {}
+
+export interface TerminalRowProps {
+  separator?: string;
+}
+
+export interface TerminalTdProps extends TerminalStyleProps {
+  padding?: TerminalSpacing;
+}
+
+export interface TerminalSession {
+  size(): TerminalSize;
+  resize(cols: number, rows: number): void;
+  update(): string;
+  output(): string;
+  ansiOutput(): string;
+  tree(): TerminalNode[];
+  focus(id: string): boolean;
+  focusAt(x: number, y: number): boolean;
+  focusNext(): boolean;
+  focusPrev(): boolean;
+  dispatchKey(key: string): string;
+  click(id?: string): string;
+  clickAt(x: number, y: number): string;
+  clipboard(): string;
+  setClipboard(value: string): string;
+  selectAll(): string;
+  destroy(): void;
+}
+
+export type TerminalRuntime = "app" | "headless";
+
+export interface TerminalMountOptions {
+  runtime?: TerminalRuntime;
+  cols?: number;
+  rows?: number;
+  theme?: TerminalTheme;
+  keymap?: TerminalKeymapOptions;
+  alternateScreen?: boolean;
+  hideCursor?: boolean;
+  restoreOnDestroy?: boolean;
+  clipboard?: TerminalClipboardAdapter | false;
+  stdin?: {
+    isTTY?: boolean;
+    on(event: "data", listener: (chunk: string | Uint8Array) => void): any;
+    off?(event: "data", listener: (chunk: string | Uint8Array) => void): any;
+    removeListener?(event: "data", listener: (chunk: string | Uint8Array) => void): any;
+    setRawMode?(value: boolean): void;
+    resume?(): void;
+    pause?(): void;
+  };
+  stdout?: TerminalOutputStream;
+}
+
+export interface TerminalOutputStream {
+  isTTY?: boolean;
+  columns?: number;
+  rows?: number;
+  write(chunk: string): any;
+  on?(event: "drain" | "resize", listener: () => void): any;
+  off?(event: "drain" | "resize", listener: () => void): any;
+  removeListener?(event: "drain" | "resize", listener: () => void): any;
+}
+
+export type ParsedTerminalInput =
+  | { type: "key"; key: string }
+  | { type: "mouse"; x: number; y: number; button: number; action: "press" | "release" | "drag" | "wheel-up" | "wheel-down" };

package/tsconfig.json

@@ -6,20 +6,17 @@
     "moduleResolution": "NodeNext",
     "noEmit": true,
     "moduleDetection": "force",
-    "jsx": "react",
-    "jsxFactory": "v",
-    "jsxFragmentFactory": "v.fragment",
+    "jsx": "react-jsx",
+    "jsxImportSource": "valyrian.js",
     "allowJs": true,
     "esModuleInterop": true,
     "strict": true,
     "forceConsistentCasingInFileNames": true,
     "skipLibCheck": true,
     "types": ["bun-types", "node"],
-    "downlevelIteration": true,
     "allowSyntheticDefaultImports": true,
     "allowImportingTsExtensions": true,
-    "resolveJsonModule": true,
-    "baseUrl": "."
+    "resolveJsonModule": true
   },
-  "include": ["src", "test", "examples"]
+  "include": ["src", "test", "examples", "scripts"]
 }

package/docs/local-demo.md

@@ -1,28 +0,0 @@
-# Local Demo
-
-`examples/` exists only to support local development. It is not part of the package published to npm, it does not appear in `exports`, and `valyrianjs-terminal` does not publish a CLI.
-
-## Files
-
-- `examples/demo.tsx`: defines `createDemoState()` and `DemoApp`; validates primitive composition (`Screen`, `Box`, `View`, `Text`, `Input`, `Button`, `List`, `ScrollView`, `Table`, `Row`, `Td`) and basic event payloads.
-- `examples/basic.tsx`: validates the minimum path for using `renderTerminal()` in snapshot mode and `mountTerminal()` with local `stdin`/`stdout`.
-- `examples/cli.tsx`: validates the local launcher with `--help`, `--snapshot`, initial focus, exit via `Esc` or `Ctrl+C`, and ANSI cleanup on close.
-
-## Commands
-
-```bash
-bun run examples/basic.tsx
-bun run examples/basic.tsx --snapshot
-bun run examples/cli.tsx
-bun run examples/cli.tsx --snapshot
-bun run examples/cli.tsx --help
-bun run test
-bun run typecheck
-bun run build
-```
-
-## Scope
-
-- `--snapshot` prints the example UI as plain text.
-- without `--snapshot`, the examples mount a local session connected to `process.stdin` and `process.stdout`.
-- these files are not a distributed interface for package consumers; they are manual fixtures for validating the adapter on a local machine.