@flowtty/core 1.0.0-alpha.1 → 1.0.0-alpha.10

package/dist/host-CQGPghSs.d.ts

@@ -0,0 +1,178 @@
+import { i as Color } from "./cells-C-GthybI.js";
+import { loadYoga } from "yoga-layout/load";
+//#region src/host/yoga.d.ts
+type Yoga = Awaited<ReturnType<typeof loadYoga>>;
+type YogaNode = ReturnType<Yoga["Node"]["create"]>;
+declare function getYoga(): Promise<Yoga>;
+//#endregion
+//#region src/host/borders.d.ts
+type BorderStyle = "single" | "double" | "round" | "bold" | "classic";
+/** The library-wide default for components that draw a box-border chrome
+ *  (DialogHost wrappers, Menu panels, Table grids). Declared once so the
+ *  default is a single edit, not one per component. */
+declare const DEFAULT_BORDER_STYLE: BorderStyle;
+interface GridChars {
+  h: string;
+  v: string;
+  tl: string;
+  tr: string;
+  bl: string;
+  br: string;
+  tDown: string;
+  tUp: string;
+  tRight: string;
+  tLeft: string;
+  cross: string;
+}
+declare const GRID_CHARS: Record<BorderStyle, GridChars>;
+type BorderChars = Pick<GridChars, "h" | "v" | "tl" | "tr" | "bl" | "br">;
+declare const BORDER_CHARS: Record<BorderStyle, BorderChars>;
+//#endregion
+//#region src/host/layout.d.ts
+interface Rect {
+  left: number;
+  top: number;
+  width: number;
+  height: number;
+}
+declare function computeLayout(container: Container, width: number, height: number): void;
+declare function layoutOf(inst: Instance, offsetX?: number, offsetY?: number): Rect;
+//#endregion
+//#region src/host/host.d.ts
+type HostType = "flowtty-box";
+interface BoxProps {
+  /** Fixed size in cells. Strings like '100%' use Yoga's percentage sizing. */
+  width?: number | string;
+  height?: number | string;
+  flexDirection?: "row" | "column";
+  /** Default 'static' (Yoga's stack flow). 'absolute' positions via top/left/right/bottom relative to the nearest non-static ancestor. */
+  position?: "static" | "absolute";
+  top?: number;
+  left?: number;
+  right?: number;
+  bottom?: number;
+  /** Main-axis alignment of children (flexbox). */
+  justifyContent?: "flex-start" | "flex-end" | "center" | "space-between" | "space-around" | "space-evenly";
+  /** Cross-axis alignment of children. */
+  alignItems?: "flex-start" | "flex-end" | "center" | "stretch";
+  wrap?: "wrap" | "truncate" | "none";
+  color?: Color;
+  bold?: boolean;
+  dim?: boolean;
+  underline?: boolean;
+  inverse?: boolean;
+  strikethrough?: boolean;
+  link?: string;
+  backgroundColor?: Color;
+  border?: BorderStyle;
+  borderColor?: Color;
+  borderBackgroundColor?: Color;
+  borderTitle?: string;
+  padding?: number;
+  paddingX?: number;
+  paddingY?: number;
+  paddingTop?: number;
+  paddingRight?: number;
+  paddingBottom?: number;
+  paddingLeft?: number;
+  margin?: number;
+  marginX?: number;
+  marginY?: number;
+  marginTop?: number;
+  marginRight?: number;
+  marginBottom?: number;
+  marginLeft?: number;
+  gap?: number;
+  rowGap?: number;
+  columnGap?: number;
+  flexGrow?: number;
+  flexShrink?: number;
+  flexBasis?: number | "auto" | `${number}%`;
+  flexWrap?: "nowrap" | "wrap" | "wrap-reverse";
+  /** Cross-axis distribution of wrap lines. Only effective when flexWrap is 'wrap' or 'wrap-reverse'
+   *  AND the parent has extra cross-axis space. Default 'flex-start'. */
+  alignContent?: "flex-start" | "flex-end" | "center" | "space-between" | "space-around" | "space-evenly" | "stretch";
+  /** Minimum cell size — Yoga prevents the box from shrinking below this.
+   *  Accepts a number (cells) or a percent string (e.g. '50%'). Undefined = no minimum. */
+  minWidth?: number | `${number}%`;
+  maxWidth?: number | `${number}%`;
+  minHeight?: number | `${number}%`;
+  maxHeight?: number | `${number}%`;
+  /** Width / height ratio. Yoga derives the missing dimension from the constrained one.
+   *  CSS convention: `aspectRatio: 2` = twice as wide as tall; `0.5` = twice as tall as wide; `1` = square. */
+  aspectRatio?: number;
+  /** 'none' removes this box and all descendants from layout (siblings don't reserve space for it,
+   *  and paint skips the subtree). Default 'flex'. Useful for conditional UI without unmounting. */
+  display?: "flex" | "none";
+  /** Fires after layout with this box's computed rect. Use to read allocated dimensions
+   *  for responsive rendering (e.g. paginating an article reader). **Diff before setState** —
+   *  this fires on EVERY paint, and unconditionally calling setState with a new object
+   *  will infinite-loop. Pattern:
+   *    onLayout={(r) => { if (!size || size.width !== r.width || size.height !== r.height) setSize(r); }} */
+  onLayout?: (rect: Rect) => void;
+  /** Stacking order within the same paint pass. Higher values paint on top.
+   *  Default 0. Tree order is the tiebreaker. Does NOT cross pass boundaries:
+   *  absolutes always overlay stack-flow regardless of zIndex. */
+  zIndex?: number;
+  /** Clip descendants to this box's content rect. Default 'visible' (no clipping).
+   *  'hidden' clips ALL descendant writes including their backgrounds and borders.
+   *  Does NOT clip this box's own background or border (those are this box's own area). */
+  overflow?: "visible" | "hidden";
+  /** Scroll the content up by this many rows (0 = top). Setting either scroll
+   *  prop makes the box a scroll viewport: it clips like `overflow: 'hidden'`
+   *  and paints its flow children shifted. The value is clamped to the scrollable
+   *  range at paint time, against the content's CURRENT height — so it never
+   *  needs a second frame to catch up. `position: 'absolute'` children are
+   *  overlays: they neither scroll nor count as content (a scrollbar, a
+   *  "new messages" badge). */
+  scrollTop?: number;
+  /** Like `scrollTop`, but counted from the END of the content: 0 pins the last
+   *  rows into view and keeps them there as content grows. Wins over `scrollTop`
+   *  when both are set. */
+  scrollBottom?: number;
+  /** Fires every paint (diff before setState, like onLayout) with the numbers a
+   *  scrolling component needs: content and viewport heights, the effective
+   *  (clamped) `scrollTop`, and its maximum. */
+  onScrollMetrics?: (metrics: ScrollMetrics) => void;
+}
+interface ScrollMetrics {
+  contentHeight: number;
+  viewportHeight: number;
+  scrollTop: number;
+  maxScrollTop: number;
+}
+interface Instance {
+  type: "box";
+  props: BoxProps;
+  yogaNode: YogaNode;
+  children: Array<Instance | TextInstance>;
+}
+interface TextInstance {
+  type: "text";
+  text: string;
+  parent?: Instance;
+}
+/**
+ * Adapter-facing root container: a list of top-level Instances plus the loaded
+ * Yoga module. Each framework adapter (React reconciler, Vue, …) builds one of
+ * these and passes it to `computeLayout` + `paint`. Lives in host so layout /
+ * paint (in core) can depend on it without pulling in any adapter code.
+ */
+interface Container {
+  children: Instance[];
+  Yoga: Yoga;
+}
+declare function createInstance(type: HostType, props: BoxProps, Yoga: Yoga): Instance;
+declare function createTextInstance(text: string, _Yoga: Yoga): TextInstance;
+declare function applyProps(inst: Instance, props: BoxProps, _Yoga: Yoga): void;
+declare function measureText(text: string): {
+  width: number;
+  height: number;
+};
+declare function ownText(inst: Instance): string;
+declare function refreshMeasure(inst: Instance, _Yoga: Yoga): void;
+declare function appendChild(parent: Instance, child: Instance | TextInstance, Yoga: Yoga): void;
+declare function removeChild(parent: Instance, child: Instance | TextInstance, Yoga: Yoga): void;
+declare function insertBefore(parent: Instance, child: Instance | TextInstance, before: Instance | TextInstance, Yoga: Yoga): void;
+//#endregion
+export { GRID_CHARS as C, getYoga as D, YogaNode as E, DEFAULT_BORDER_STYLE as S, Yoga as T, computeLayout as _, ScrollMetrics as a, BorderChars as b, applyProps as c, insertBefore as d, measureText as f, Rect as g, removeChild as h, Instance as i, createInstance as l, refreshMeasure as m, Container as n, TextInstance as o, ownText as p, HostType as r, appendChild as s, BoxProps as t, createTextInstance as u, layoutOf as v, GridChars as w, BorderStyle as x, BORDER_CHARS as y };

package/dist/index.d.ts

@@ -1,10 +1,8 @@
-export { B as Buffer, C as Cell, S as Style } from './cells-CaXEx4lH.js';
-import { K as Key } from './backend-BcB7VR87.js';
-export { B as Backend } from './backend-BcB7VR87.js';
-export { a as BorderChars, b as BorderStyle, c as BoxProps, D as DEFAULT_BORDER_STYLE, G as GRID_CHARS, d as GridChars } from './host-DttBG-OZ.js';
-import 'yoga-layout/load';
-
-type WrapMode = 'wrap' | 'truncate' | 'none';
+import { C as GRID_CHARS, S as DEFAULT_BORDER_STYLE, a as ScrollMetrics, b as BorderChars, t as BoxProps, w as GridChars, x as BorderStyle } from "./host-CQGPghSs.js";
+import { a as NAMED_COLORS, i as Color, n as Cell, o as NamedColor, r as Style, t as Buffer } from "./cells-C-GthybI.js";
+import { a as NamedKey, i as NAMED_KEYS, n as Key, r as KeyName, t as Backend } from "./backend-CT8SGLO5.js";
+//#region src/wrap.d.ts
+type WrapMode = "wrap" | "truncate" | "none";
 /**
  * Lay out `text` into display lines fitting within `width` cells.
  * Assumes 1 code point = 1 cell (no CJK/emoji width awareness in M1d).
@@ -15,8 +13,9 @@ type WrapMode = 'wrap' | 'truncate' | 'none';
  *
  * Always returns at least one line (empty input → `['']`, matching measureText's height=1 default).
  */
-declare function wrapText(text: string, width: number, mode: WrapMode): string[];
-
+export declare function wrapText(text: string, width: number, mode: WrapMode): string[];
+//#endregion
+//#region src/visualLines.d.ts
 /**
  * Split a multi-line source text into visual lines for paginated rendering
  * with an optional line-number gutter.
@@ -39,12 +38,13 @@ declare function wrapText(text: string, width: number, mode: WrapMode): string[]
  * ```
  */
 interface VisualLine {
-    text: string;
-    /** Source-file line number for the first visual line of a wrapped source line; null for continuation lines. 1-based. */
-    lineNum: number | null;
+  text: string;
+  /** Source-file line number for the first visual line of a wrapped source line; null for continuation lines. 1-based. */
+  lineNum: number | null;
 }
-declare function splitVisualLines(text: string, mode: 'wrap' | 'nowrap', width: number): VisualLine[];
-
+export declare function splitVisualLines(text: string, mode: "wrap" | "nowrap", width: number): VisualLine[];
+//#endregion
+//#region src/windowAround.d.ts
 /**
  * Center a `visible`-sized window of items around `cursor`, clamped so the
  * window never starts before 0 or extends past the end of the list. Returns
@@ -62,82 +62,132 @@ declare function splitVisualLines(text: string, mode: 'wrap' | 'nowrap', width:
  * The window prefers to center the cursor; near the edges it sticks to the
  * top/bottom so the cursor remains visible without empty padding.
  */
-declare function windowAround<T>(items: readonly T[], cursor: number, visible: number): {
-    start: number;
-    items: T[];
+export declare function windowAround<T>(items: readonly T[], cursor: number, visible: number): {
+  start: number;
+  items: T[];
 };
-
+//#endregion
+//#region src/displayWidth.d.ts
 /**
  * Display width in terminal cells of a single Unicode code point: 0 for control
  * / combining / zero-width, 2 for East Asian Wide & Fullwidth (and most emoji),
  * 1 otherwise. Pass a code point (e.g. from `String#codePointAt`), not a string.
  */
-declare function charWidth(cp: number): 0 | 1 | 2;
+export declare function charWidth(cp: number): 0 | 1 | 2;
 /**
  * Display width in terminal cells of a string, summing `charWidth` over its
  * code points (surrogate pairs counted once). See the file header for the
  * grapheme-cluster caveat. Expects plain text, not ANSI-styled.
  */
-declare function stringWidth(str: string): number;
-
+export declare function stringWidth(str: string): number;
+//#endregion
+//#region src/editor.d.ts
 interface EditorState {
-    value: string;
-    cursor: number;
+  value: string;
+  /** UTF-16 index into `value` (so `value.slice(0, cursor)` is the text before
+   *  the caret). It only ever rests on a character boundary: movement and
+   *  deletion step over a whole code point, and a cursor handed in between the
+   *  two halves of a surrogate pair is snapped back before anything else. */
+  cursor: number;
 }
 type EditorAction = {
-    kind: 'edit';
-    state: EditorState;
+  kind: "edit";
+  state: EditorState;
 } | {
-    kind: 'submit';
+  kind: "submit";
 } | {
-    kind: 'cancel';
+  kind: "cancel";
 } | {
-    kind: 'noop';
+  kind: "noop";
 };
-declare function reduce$2(state: EditorState, key: Key): EditorAction;
-
+interface EditorOptions {
+  /** Multi-line editing: line breaks are part of the value. Shift+Enter,
+   *  Alt+Enter and backslash-then-Enter insert one (plain Enter still submits),
+   *  up/down move between visual rows, Home/End and the kill bindings work
+   *  within the current line, and a paste keeps its line breaks. */
+  multiline?: boolean;
+  /** Wrap width in cells — what up/down use to walk soft-wrapped rows. Only
+   *  read when `multiline`; without it each source line counts as one row.
+   *  It MUST be the width the field is actually drawn with (the one passed to
+   *  `inputRows` / `caretPosition`): a host that renders the rows itself computes
+   *  both, and a mismatch makes up/down land on a different column than shown. */
+  width?: number;
+}
+/**
+ * One key against an editor state. Contract hosts rely on: a key the editor has
+ * no meaning for (Tab, Ctrl+R, PgUp, the wheel, an unrecognized sequence …)
+ * returns `{ kind: 'noop' }` — never an edit — so a host can handle its own keys
+ * first and pass everything else through.
+ */
+declare function reduce(state: EditorState, key: Key, opts?: EditorOptions): EditorAction;
+//#endregion
+//#region src/inputRows.d.ts
+interface InputRow {
+  /** Text of this visual row (no line break). */
+  text: string;
+  /** Index into the value where this row starts. */
+  start: number;
+  /** True for a soft-wrap continuation of the previous row's source line. */
+  continuation: boolean;
+}
+export declare function inputRows(value: string, width: number, cursor?: number): InputRow[];
+/** UTF-16 index of character column `col` within `row` (clamped to its end). */
+export declare function rowIndexAt(row: InputRow, col: number): number;
+export declare function caretPosition(value: string, cursor: number, width: number): {
+  row: number;
+  col: number;
+};
+//#endregion
+//#region src/selectReducer.d.ts
 interface SelectItem<T> {
-    label: string;
-    value: T;
+  label: string;
+  value: T;
 }
 interface SelectState {
-    cursor: number;
-    filter: string;
+  cursor: number;
+  filter: string;
 }
 type SelectAction = {
-    kind: 'state';
-    state: SelectState;
+  kind: "state";
+  state: SelectState;
 } | {
-    kind: 'submit';
-    index: number;
+  kind: "submit";
+  index: number;
 } | {
-    kind: 'cancel';
+  kind: "cancel";
 } | {
-    kind: 'noop';
+  kind: "noop";
 };
 /**
  * Indices into `items` of items whose label contains `filter` (case-insensitive
  * substring). Empty filter → all indices.
  */
-declare function visibleIndices<T>(items: SelectItem<T>[], filter: string): number[];
-declare function reduce$1<T>(items: SelectItem<T>[], state: SelectState, key: Key): SelectAction;
-
+export declare function visibleIndices<T>(items: SelectItem<T>[], filter: string): number[];
+declare function reduce$2<T>(items: SelectItem<T>[], state: SelectState, key: Key): SelectAction;
+//#endregion
+//#region src/multiSelectReducer.d.ts
 interface MultiSelectState {
-    cursor: number;
+  cursor: number;
 }
 type MultiSelectAction = {
-    kind: 'state';
-    state: MultiSelectState;
+  kind: "state";
+  state: MultiSelectState;
 } | {
-    kind: 'toggle';
-    index: number;
+  kind: "toggle";
+  index: number;
 } | {
-    kind: 'submit';
+  kind: "submit";
 } | {
-    kind: 'cancel';
+  kind: "cancel";
 } | {
-    kind: 'noop';
+  kind: "noop";
 };
-declare function reduce<T>(items: SelectItem<T>[], state: MultiSelectState, key: Key): MultiSelectAction;
-
-export { type EditorAction, type EditorState, Key, type MultiSelectAction, type MultiSelectState, type SelectAction, type SelectItem, type SelectState, type VisualLine, type WrapMode, charWidth, reduce$2 as editorReducer, reduce as multiSelectReducer, reduce$1 as selectReducer, splitVisualLines, stringWidth, visibleIndices, windowAround, wrapText };
+interface MultiSelectOptions {
+  /** Rows after the items that the cursor can stand on but that hold no item —
+   *  e.g. a trailing "+ add new" row. Navigation wraps over items + extra rows;
+   *  Space on an extra row toggles nothing. Default 0. */
+  extraRows?: number;
+}
+declare function reduce$1<T>(items: SelectItem<T>[], state: MultiSelectState, key: Key, opts?: MultiSelectOptions): MultiSelectAction;
+//#endregion
+export { type Backend, type BorderChars, type BorderStyle, type BoxProps, Buffer, type Cell, type Color, DEFAULT_BORDER_STYLE, type EditorAction, type EditorOptions, type EditorState, GRID_CHARS, type GridChars, type InputRow, type Key, type KeyName, type MultiSelectAction, type MultiSelectOptions, type MultiSelectState, NAMED_COLORS, NAMED_KEYS, type NamedColor, type NamedKey, type ScrollMetrics, type SelectAction, type SelectItem, type SelectState, type Style, type VisualLine, type WrapMode, reduce as editorReducer, reduce$1 as multiSelectReducer, reduce$2 as selectReducer };