silvery 0.17.0 → 0.17.2

package/dist/useLatest-BMIYXd6e.d.mts

@@ -0,0 +1,154 @@
+//#region packages/ag-react/src/ui/animation/easing.d.ts
+/**
+ * Easing Functions
+ *
+ * Maps time progress (0-1) to value progress (0-1) for smooth animations.
+ * Includes common presets and a resolver for name-or-function usage.
+ */
+/** Easing function: maps time progress (0-1) to value progress (0-1) */
+type EasingFn = (t: number) => number;
+declare const easings: {
+  readonly linear: (t: number) => number;
+  readonly ease: (t: number) => number;
+  readonly easeIn: (t: number) => number;
+  readonly easeOut: (t: number) => number;
+  readonly easeInOut: (t: number) => number;
+  readonly easeInCubic: (t: number) => number;
+  readonly easeOutCubic: (t: number) => number;
+};
+type EasingName = keyof typeof easings;
+/** Resolve an easing — accepts a name string or a custom function. */
+declare function resolveEasing(easing: EasingName | EasingFn): EasingFn;
+//#endregion
+//#region packages/ag-react/src/ui/animation/useAnimation.d.ts
+interface UseAnimationOptions {
+  /** Duration in milliseconds */
+  duration: number;
+  /** Easing function or preset name */
+  easing?: EasingName | EasingFn;
+  /** Delay before starting (ms) */
+  delay?: number;
+  /** Called when animation completes */
+  onComplete?: () => void;
+  /** Whether to run the animation (default: true) */
+  enabled?: boolean;
+}
+interface UseAnimationResult {
+  /** Current progress value (0 to 1, eased) */
+  value: number;
+  /** Whether the animation is still running */
+  isAnimating: boolean;
+  /** Reset and replay the animation */
+  reset: () => void;
+}
+/**
+ * Animate a value from 0 to 1 over a duration with easing.
+ *
+ * @example
+ * ```tsx
+ * function FadeIn({ children }) {
+ *   const { value } = useAnimation({ duration: 300, easing: "easeOut" })
+ *   return <Text dimColor={value < 1}>{children}</Text>
+ * }
+ * ```
+ */
+declare function useAnimation(options: UseAnimationOptions): UseAnimationResult;
+//#endregion
+//#region packages/ag-react/src/ui/animation/useTransition.d.ts
+interface UseTransitionOptions {
+  /** Duration in milliseconds (default: 300) */
+  duration?: number;
+  /** Easing function or preset name (default: "easeOut") */
+  easing?: EasingName | EasingFn;
+}
+/**
+ * Smoothly interpolate when the target value changes.
+ *
+ * Returns the current interpolated value. On the first render, returns
+ * the target value immediately (no animation). Subsequent changes
+ * animate from the previous value to the new target.
+ *
+ * @example
+ * ```tsx
+ * function ScrollOffset({ target }) {
+ *   const smooth = useTransition(target, { duration: 200, easing: "easeOut" })
+ *   return <Box marginTop={Math.round(smooth)}>...</Box>
+ * }
+ * ```
+ */
+declare function useTransition(targetValue: number, options?: UseTransitionOptions): number;
+//#endregion
+//#region packages/ag-react/src/ui/animation/useInterval.d.ts
+/**
+ * useInterval - Run a callback on a fixed interval.
+ *
+ * Uses Dan Abramov's ref pattern to avoid stale closures.
+ * The callback is NOT called on mount — only on subsequent ticks.
+ */
+/**
+ * Run a callback on a fixed interval.
+ *
+ * The callback is NOT called on mount — only on ticks after the interval
+ * elapses. Uses a ref for the callback to avoid stale closures.
+ *
+ * @param callback - Function to call on each tick
+ * @param ms - Interval in milliseconds
+ * @param enabled - Whether the interval is active (default: true)
+ */
+declare function useInterval(callback: () => void, ms: number, enabled?: boolean): void;
+//#endregion
+//#region packages/ag-react/src/ui/animation/useTimeout.d.ts
+/**
+ * useTimeout - Run a callback after a delay.
+ *
+ * Uses a ref for the callback to avoid stale closures (Dan Abramov pattern).
+ * The timer resets when `ms` or `enabled` changes. When `enabled` becomes false,
+ * the timer is cleared. Returns a `reset` function to restart the timer.
+ *
+ * Unlike useInterval, this fires exactly once per enable/reset cycle.
+ */
+/**
+ * Run a callback after a delay.
+ *
+ * The callback fires once after `ms` milliseconds. The timer resets when
+ * `ms` or `enabled` changes. Returns `{ reset, clear }` for manual control.
+ *
+ * @param callback - Function to call when the timer fires
+ * @param ms - Delay in milliseconds
+ * @param enabled - Whether the timer is active (default: true)
+ */
+declare function useTimeout(callback: () => void, ms: number, enabled?: boolean): {
+  reset: () => void;
+  clear: () => void;
+};
+//#endregion
+//#region packages/ag-react/src/ui/animation/useLatest.d.ts
+/**
+ * useLatest - Always-current ref to a value.
+ *
+ * The classic React pattern for avoiding stale closures in callbacks,
+ * timers, and effects. Returns a ref whose `.current` is always the
+ * latest value — safe to read from any async context.
+ *
+ * ```tsx
+ * const countRef = useLatest(count)
+ * useInterval(() => {
+ *   console.log(countRef.current) // always fresh
+ * }, 1000)
+ * ```
+ */
+/**
+ * Returns a ref that always holds the latest value.
+ *
+ * Useful when a callback needs access to current state/props without
+ * re-creating the callback (which would reset timers, event listeners, etc).
+ *
+ * @param value - The value to track
+ * @returns A ref whose `.current` is always `value`
+ */
+declare function useLatest<T>(value: T): {
+  readonly current: T;
+};
+//#endregion
+export { useTransition as a, useAnimation as c, easings as d, resolveEasing as f, UseTransitionOptions as i, EasingFn as l, useTimeout as n, UseAnimationOptions as o, useInterval as r, UseAnimationResult as s, useLatest as t, EasingName as u };
+//# sourceMappingURL=useLatest-BMIYXd6e.d.mts.map

package/dist/useLatest-BMIYXd6e.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useLatest-BMIYXd6e.d.mts","names":[],"sources":["../packages/ag-react/src/ui/animation/easing.ts","../packages/ag-react/src/ui/animation/useAnimation.ts","../packages/ag-react/src/ui/animation/useTransition.ts","../packages/ag-react/src/ui/animation/useInterval.ts","../packages/ag-react/src/ui/animation/useTimeout.ts","../packages/ag-react/src/ui/animation/useLatest.ts"],"mappings":";;AAYA;;;;;AAMA;AAAA,KANY,QAAA,IAAY,CAAA;AAAA,cAMX,OAAA;EAAA;;;;;;;;KAUD,UAAA,gBAA0B,OAAA;;iBAOtB,aAAA,CAAc,MAAA,EAAQ,UAAA,GAAa,QAAA,GAAW,QAAA;;;UCpB7C,mBAAA;EDW4B;ECT3C,QAAA;;EAEA,MAAA,GAAS,UAAA,GAAa,QAAA;;EAEtB,KAAA;;EAEA,UAAA;;EAEA,OAAA;AAAA;AAAA,UAGe,kBAAA;;EAEf,KAAA;;EAEA,WAAA;EDPwB;ECSxB,KAAA;AAAA;;;;ADCF;;;;;;;;iBCwBgB,YAAA,CAAa,OAAA,EAAS,mBAAA,GAAsB,kBAAA;;;UC5C3C,oBAAA;EFW4B;EET3C,QAAA;;EAEA,MAAA,GAAS,UAAA,GAAa,QAAA;AAAA;;;;;;;;;;;;;AFSxB;;;iBEoBgB,aAAA,CAAc,WAAA,UAAqB,OAAA,GAAU,oBAAA;;;;AFpC7D;;;;;AAMA;;;;;;;;;;AAAA,iBGKgB,WAAA,CAAY,QAAA,cAAsB,EAAA,UAAY,OAAA;;;;AHX9D;;;;;AAMA;;;;;;;;;;;;;iBIQgB,UAAA,CAAW,QAAA,cAAsB,EAAA,UAAY,OAAA;EAAmB,KAAA;EAAmB,KAAA;AAAA;;;;AJdnG;;;;;AAMA;;;;;;;;;;;;;;;;;iBKYgB,SAAA,GAAA,CAAa,KAAA,EAAO,CAAA;EAAA,SAAe,OAAA,EAAS,CAAA;AAAA"}

package/dist/useLayout-BG2cGl15.mjs

@@ -0,0 +1,139 @@
+import { i as NodeContext } from "./context-QreF3UHr.mjs";
+import { t as rectEqual } from "./types-Bhj5QkIQ.mjs";
+import { useContext, useLayoutEffect, useReducer, useRef } from "react";
+//#region packages/ag-react/src/hooks/useLayout.ts
+/**
+* Layout Hooks — three coordinate systems for positioning in silvery.
+*
+* Every silvery node has three rects that differ only by how scroll and
+* sticky offsets are applied. Pick the one that matches your use case:
+*
+* - `useBoxRect()`    — layout position (border-box sized). Use for responsive
+*                       sizing inside a component. Matches CSS offset-like
+*                       semantics for the content area.
+* - `useScrollRect()` — scroll-adjusted position, **pre** sticky clamping.
+*                       Use when you need the "natural" position of a node
+*                       in scrolled coordinates (can go off-screen).
+* - `useScreenRect()` — actual paint position on the terminal screen.
+*                       Use for hit testing, cursor positioning, and
+*                       cross-component visual navigation. The CSS
+*                       `getBoundingClientRect()` analogue.
+*
+* Each hook has two call signatures:
+*
+*   const rect = useBoxRect()                 // reactive — re-renders on change
+*   useBoxRect((rect) => register(id, rect))  // callback — zero re-renders
+*
+* The callback form is the right choice for hot paths like large lists where
+* re-rendering on every layout change is prohibitive.
+*/
+const EMPTY_RECT = {
+	x: 0,
+	y: 0,
+	width: 0,
+	height: 0
+};
+/**
+* Get the inner content dimensions of a node (border-box minus padding and border).
+* This is the space available for the node's children.
+*/
+function getInnerRect(node) {
+	const rect = node.boxRect;
+	if (!rect) return EMPTY_RECT;
+	const props = node.props;
+	if (!props || node.type === "silvery-text") return rect;
+	const pTop = props.paddingTop ?? props.paddingY ?? props.padding ?? 0;
+	const pBottom = props.paddingBottom ?? props.paddingY ?? props.padding ?? 0;
+	const pLeft = props.paddingLeft ?? props.paddingX ?? props.padding ?? 0;
+	const pRight = props.paddingRight ?? props.paddingX ?? props.padding ?? 0;
+	let bTop = 0;
+	let bBottom = 0;
+	let bLeft = 0;
+	let bRight = 0;
+	if (props.borderStyle) {
+		bTop = props.borderTop !== false ? 1 : 0;
+		bBottom = props.borderBottom !== false ? 1 : 0;
+		bLeft = props.borderLeft !== false ? 1 : 0;
+		bRight = props.borderRight !== false ? 1 : 0;
+	}
+	return {
+		x: rect.x + pLeft + bLeft,
+		y: rect.y + pTop + bTop,
+		width: Math.max(0, rect.width - pLeft - pRight - bLeft - bRight),
+		height: Math.max(0, rect.height - pTop - pBottom - bTop - bBottom)
+	};
+}
+/**
+* Reactive rect hook: subscribes to the node's layoutSubscribers and forces a
+* re-render whenever the selected rect changes. `getRect` pulls the current
+* rect from the node for each render and change check.
+*/
+function useReactiveRect(getRect) {
+	const node = useContext(NodeContext);
+	const [, forceUpdate] = useReducer((x) => x + 1, 0);
+	const prevRef = useRef(null);
+	useLayoutEffect(() => {
+		if (!node) return;
+		const handleLayoutComplete = () => {
+			const next = getRect(node) ?? null;
+			if (!rectEqual(prevRef.current, next)) {
+				prevRef.current = next;
+				forceUpdate();
+			}
+		};
+		node.layoutSubscribers.add(handleLayoutComplete);
+		return () => {
+			node.layoutSubscribers.delete(handleLayoutComplete);
+		};
+	}, [node]);
+	if (!node) return EMPTY_RECT;
+	return getRect(node) ?? EMPTY_RECT;
+}
+/**
+* Callback rect hook: subscribes without triggering re-renders. The callback
+* is invoked after layout completes whenever the selected rect is available.
+* Uses a ref so the hook doesn't re-subscribe when the caller passes a fresh
+* function each render.
+*
+* `getRectRef` is wrapped in a ref to keep the subscription stable across
+* renders — the `getRect` function is typically created inline as
+* `(node) => node.scrollRect` and would otherwise invalidate the effect on
+* every render, missing layout notifications in tests that re-render the
+* same tree with a fresh registry.
+*/
+function useCallbackRect(getRect, callback) {
+	const node = useContext(NodeContext);
+	const callbackRef = useRef(callback);
+	callbackRef.current = callback;
+	const getRectRef = useRef(getRect);
+	getRectRef.current = getRect;
+	useLayoutEffect(() => {
+		if (!node) return;
+		const handleLayoutComplete = () => {
+			const rect = getRectRef.current(node);
+			if (rect) callbackRef.current(rect);
+		};
+		node.layoutSubscribers.add(handleLayoutComplete);
+		const rect = getRectRef.current(node);
+		if (rect) callbackRef.current(rect);
+		return () => {
+			node.layoutSubscribers.delete(handleLayoutComplete);
+		};
+	}, [node]);
+}
+function useBoxRect(callback) {
+	if (callback) return useCallbackRect((node) => getInnerRect(node), callback);
+	return useReactiveRect((node) => getInnerRect(node));
+}
+function useScrollRect(callback) {
+	if (callback) return useCallbackRect((node) => node.scrollRect, callback);
+	return useReactiveRect((node) => node.scrollRect);
+}
+function useScreenRect(callback) {
+	if (callback) return useCallbackRect((node) => node.screenRect, callback);
+	return useReactiveRect((node) => node.screenRect);
+}
+//#endregion
+export { useScreenRect as n, useScrollRect as r, useBoxRect as t };
+
+//# sourceMappingURL=useLayout-BG2cGl15.mjs.map

package/dist/useLayout-BG2cGl15.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"useLayout-BG2cGl15.mjs","names":[],"sources":["../packages/ag-react/src/hooks/useLayout.ts"],"sourcesContent":["/**\n * Layout Hooks — three coordinate systems for positioning in silvery.\n *\n * Every silvery node has three rects that differ only by how scroll and\n * sticky offsets are applied. Pick the one that matches your use case:\n *\n * - `useBoxRect()`    — layout position (border-box sized). Use for responsive\n *                       sizing inside a component. Matches CSS offset-like\n *                       semantics for the content area.\n * - `useScrollRect()` — scroll-adjusted position, **pre** sticky clamping.\n *                       Use when you need the \"natural\" position of a node\n *                       in scrolled coordinates (can go off-screen).\n * - `useScreenRect()` — actual paint position on the terminal screen.\n *                       Use for hit testing, cursor positioning, and\n *                       cross-component visual navigation. The CSS\n *                       `getBoundingClientRect()` analogue.\n *\n * Each hook has two call signatures:\n *\n *   const rect = useBoxRect()                 // reactive — re-renders on change\n *   useBoxRect((rect) => register(id, rect))  // callback — zero re-renders\n *\n * The callback form is the right choice for hot paths like large lists where\n * re-rendering on every layout change is prohibitive.\n */\n\nimport { useContext, useLayoutEffect, useReducer, useRef } from \"react\"\nimport { NodeContext } from \"../context\"\nimport { type AgNode, type BoxProps, type Rect, rectEqual } from \"@silvery/ag/types\"\n\nexport type { Rect }\n\nconst EMPTY_RECT: Rect = { x: 0, y: 0, width: 0, height: 0 }\n\n/**\n * Get the inner content dimensions of a node (border-box minus padding and border).\n * This is the space available for the node's children.\n */\nfunction getInnerRect(node: AgNode): Rect {\n  const rect = node.boxRect\n  if (!rect) return EMPTY_RECT\n\n  const props = node.props as BoxProps\n  if (!props || node.type === \"silvery-text\") return rect\n\n  // Compute padding\n  const pTop = props.paddingTop ?? props.paddingY ?? props.padding ?? 0\n  const pBottom = props.paddingBottom ?? props.paddingY ?? props.padding ?? 0\n  const pLeft = props.paddingLeft ?? props.paddingX ?? props.padding ?? 0\n  const pRight = props.paddingRight ?? props.paddingX ?? props.padding ?? 0\n\n  // Compute border (1px per side if borderStyle is set)\n  let bTop = 0\n  let bBottom = 0\n  let bLeft = 0\n  let bRight = 0\n  if (props.borderStyle) {\n    bTop = props.borderTop !== false ? 1 : 0\n    bBottom = props.borderBottom !== false ? 1 : 0\n    bLeft = props.borderLeft !== false ? 1 : 0\n    bRight = props.borderRight !== false ? 1 : 0\n  }\n\n  return {\n    x: rect.x + pLeft + bLeft,\n    y: rect.y + pTop + bTop,\n    width: Math.max(0, rect.width - pLeft - pRight - bLeft - bRight),\n    height: Math.max(0, rect.height - pTop - pBottom - bTop - bBottom),\n  }\n}\n\ntype RectCallback = (rect: Rect) => void\n\n/**\n * Reactive rect hook: subscribes to the node's layoutSubscribers and forces a\n * re-render whenever the selected rect changes. `getRect` pulls the current\n * rect from the node for each render and change check.\n */\nfunction useReactiveRect(getRect: (node: AgNode) => Rect | null | undefined): Rect {\n  const node = useContext(NodeContext)\n  const [, forceUpdate] = useReducer((x: number) => x + 1, 0)\n  const prevRef = useRef<Rect | null>(null)\n\n  useLayoutEffect(() => {\n    if (!node) return\n\n    const handleLayoutComplete = () => {\n      const next = getRect(node) ?? null\n      if (!rectEqual(prevRef.current, next)) {\n        prevRef.current = next\n        forceUpdate()\n      }\n    }\n\n    node.layoutSubscribers.add(handleLayoutComplete)\n    return () => {\n      node.layoutSubscribers.delete(handleLayoutComplete)\n    }\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, [node])\n\n  if (!node) return EMPTY_RECT\n  return getRect(node) ?? EMPTY_RECT\n}\n\n/**\n * Callback rect hook: subscribes without triggering re-renders. The callback\n * is invoked after layout completes whenever the selected rect is available.\n * Uses a ref so the hook doesn't re-subscribe when the caller passes a fresh\n * function each render.\n *\n * `getRectRef` is wrapped in a ref to keep the subscription stable across\n * renders — the `getRect` function is typically created inline as\n * `(node) => node.scrollRect` and would otherwise invalidate the effect on\n * every render, missing layout notifications in tests that re-render the\n * same tree with a fresh registry.\n */\nfunction useCallbackRect(getRect: (node: AgNode) => Rect | null | undefined, callback: RectCallback): void {\n  const node = useContext(NodeContext)\n\n  const callbackRef = useRef(callback)\n  callbackRef.current = callback\n  const getRectRef = useRef(getRect)\n  getRectRef.current = getRect\n\n  useLayoutEffect(() => {\n    if (!node) return\n\n    const handleLayoutComplete = () => {\n      const rect = getRectRef.current(node)\n      if (rect) callbackRef.current(rect)\n    }\n\n    node.layoutSubscribers.add(handleLayoutComplete)\n\n    // Call immediately if the rect is already computed\n    const rect = getRectRef.current(node)\n    if (rect) callbackRef.current(rect)\n\n    return () => {\n      node.layoutSubscribers.delete(handleLayoutComplete)\n    }\n  }, [node])\n}\n\n// ============================================================================\n// boxRect — layout position (border-box)\n// ============================================================================\n\n/**\n * Returns the inner content dimensions for the current component's nearest Box.\n * Width and height reflect the space available for children (border-box minus\n * padding and border), like CSS `clientWidth`/`clientHeight`.\n *\n * Two signatures:\n *\n * ```tsx\n * // Reactive — re-renders when the rect changes\n * function Header() {\n *   const { width } = useBoxRect()\n *   return <Text>{'='.repeat(width)}</Text>\n * }\n *\n * // Callback — zero re-renders, use for hot paths like large lists\n * function Card({ id, onLayout }) {\n *   useBoxRect((rect) => onLayout(id, rect))\n *   return <Box>...</Box>\n * }\n * ```\n *\n * On first render (reactive form), returns `{ x: 0, y: 0, width: 0, height: 0 }`.\n * After layout completes, automatically re-renders with actual dimensions.\n */\nexport function useBoxRect(): Rect\nexport function useBoxRect(callback: RectCallback): void\nexport function useBoxRect(callback?: RectCallback): Rect | void {\n  if (callback) {\n    return useCallbackRect((node) => getInnerRect(node), callback)\n  }\n  return useReactiveRect((node) => getInnerRect(node))\n}\n\n// ============================================================================\n// scrollRect — scroll-adjusted position (pre-sticky clamping)\n// ============================================================================\n\n/**\n * Returns the scroll-adjusted position for the current component.\n *\n * This is the node's position in scroll coordinates, *before* sticky clamping.\n * For non-sticky nodes it equals `useScreenRect()`. For sticky nodes, the\n * scrollRect reflects where the node would be without sticky adjustment —\n * so it can go off-screen (negative y, etc.) when scrolled past.\n *\n * Use this when you need to reason about the node's \"natural\" position in the\n * scrolled document. For hit testing or cursor positioning, use\n * `useScreenRect()` instead.\n *\n * Two signatures:\n *\n * ```tsx\n * // Reactive — re-renders when scroll changes\n * function Card({ id }) {\n *   const { y } = useScrollRect()\n *   return <Box>Scroll y: {y}</Box>\n * }\n *\n * // Callback — zero re-renders\n * function Card({ id, onLayout }) {\n *   useScrollRect((rect) => onLayout(id, rect.y))\n *   return <Box>...</Box>\n * }\n * ```\n */\nexport function useScrollRect(): Rect\nexport function useScrollRect(callback: RectCallback): void\nexport function useScrollRect(callback?: RectCallback): Rect | void {\n  if (callback) {\n    return useCallbackRect((node) => node.scrollRect, callback)\n  }\n  return useReactiveRect((node) => node.scrollRect)\n}\n\n// ============================================================================\n// screenRect — actual paint position on the terminal screen\n// ============================================================================\n\n/**\n * Returns the actual paint position on the terminal screen — the silvery\n * analogue of `getBoundingClientRect()`.\n *\n * For non-sticky nodes this equals `useScrollRect()`. For sticky nodes\n * (`position=\"sticky\"`), it reflects the clamped position where pixels\n * actually land on screen.\n *\n * Use this for hit testing, cursor positioning, and any feature that needs\n * to know where a node visually appears on the terminal.\n *\n * Two signatures:\n *\n * ```tsx\n * // Reactive — re-renders when the screen position changes\n * function StickyHeader() {\n *   const { y } = useScreenRect()\n *   return <Box position=\"sticky\" stickyTop={0}>Header at row {y}</Box>\n * }\n *\n * // Callback — zero re-renders, recommended for cross-component visual\n * // navigation (e.g. registering card positions for arrow-key navigation\n * // across columns with independent scroll state).\n * function Card({ id, onLayout }) {\n *   useScreenRect((rect) => onLayout(id, rect.y))\n *   return <Box>...</Box>\n * }\n * ```\n */\nexport function useScreenRect(): Rect\nexport function useScreenRect(callback: RectCallback): void\nexport function useScreenRect(callback?: RectCallback): Rect | void {\n  if (callback) {\n    return useCallbackRect((node) => node.screenRect, callback)\n  }\n  return useReactiveRect((node) => node.screenRect)\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgCA,MAAM,aAAmB;CAAE,GAAG;CAAG,GAAG;CAAG,OAAO;CAAG,QAAQ;CAAG;;;;;AAM5D,SAAS,aAAa,MAAoB;CACxC,MAAM,OAAO,KAAK;AAClB,KAAI,CAAC,KAAM,QAAO;CAElB,MAAM,QAAQ,KAAK;AACnB,KAAI,CAAC,SAAS,KAAK,SAAS,eAAgB,QAAO;CAGnD,MAAM,OAAO,MAAM,cAAc,MAAM,YAAY,MAAM,WAAW;CACpE,MAAM,UAAU,MAAM,iBAAiB,MAAM,YAAY,MAAM,WAAW;CAC1E,MAAM,QAAQ,MAAM,eAAe,MAAM,YAAY,MAAM,WAAW;CACtE,MAAM,SAAS,MAAM,gBAAgB,MAAM,YAAY,MAAM,WAAW;CAGxE,IAAI,OAAO;CACX,IAAI,UAAU;CACd,IAAI,QAAQ;CACZ,IAAI,SAAS;AACb,KAAI,MAAM,aAAa;AACrB,SAAO,MAAM,cAAc,QAAQ,IAAI;AACvC,YAAU,MAAM,iBAAiB,QAAQ,IAAI;AAC7C,UAAQ,MAAM,eAAe,QAAQ,IAAI;AACzC,WAAS,MAAM,gBAAgB,QAAQ,IAAI;;AAG7C,QAAO;EACL,GAAG,KAAK,IAAI,QAAQ;EACpB,GAAG,KAAK,IAAI,OAAO;EACnB,OAAO,KAAK,IAAI,GAAG,KAAK,QAAQ,QAAQ,SAAS,QAAQ,OAAO;EAChE,QAAQ,KAAK,IAAI,GAAG,KAAK,SAAS,OAAO,UAAU,OAAO,QAAQ;EACnE;;;;;;;AAUH,SAAS,gBAAgB,SAA0D;CACjF,MAAM,OAAO,WAAW,YAAY;CACpC,MAAM,GAAG,eAAe,YAAY,MAAc,IAAI,GAAG,EAAE;CAC3D,MAAM,UAAU,OAAoB,KAAK;AAEzC,uBAAsB;AACpB,MAAI,CAAC,KAAM;EAEX,MAAM,6BAA6B;GACjC,MAAM,OAAO,QAAQ,KAAK,IAAI;AAC9B,OAAI,CAAC,UAAU,QAAQ,SAAS,KAAK,EAAE;AACrC,YAAQ,UAAU;AAClB,iBAAa;;;AAIjB,OAAK,kBAAkB,IAAI,qBAAqB;AAChD,eAAa;AACX,QAAK,kBAAkB,OAAO,qBAAqB;;IAGpD,CAAC,KAAK,CAAC;AAEV,KAAI,CAAC,KAAM,QAAO;AAClB,QAAO,QAAQ,KAAK,IAAI;;;;;;;;;;;;;;AAe1B,SAAS,gBAAgB,SAAoD,UAA8B;CACzG,MAAM,OAAO,WAAW,YAAY;CAEpC,MAAM,cAAc,OAAO,SAAS;AACpC,aAAY,UAAU;CACtB,MAAM,aAAa,OAAO,QAAQ;AAClC,YAAW,UAAU;AAErB,uBAAsB;AACpB,MAAI,CAAC,KAAM;EAEX,MAAM,6BAA6B;GACjC,MAAM,OAAO,WAAW,QAAQ,KAAK;AACrC,OAAI,KAAM,aAAY,QAAQ,KAAK;;AAGrC,OAAK,kBAAkB,IAAI,qBAAqB;EAGhD,MAAM,OAAO,WAAW,QAAQ,KAAK;AACrC,MAAI,KAAM,aAAY,QAAQ,KAAK;AAEnC,eAAa;AACX,QAAK,kBAAkB,OAAO,qBAAqB;;IAEpD,CAAC,KAAK,CAAC;;AAiCZ,SAAgB,WAAW,UAAsC;AAC/D,KAAI,SACF,QAAO,iBAAiB,SAAS,aAAa,KAAK,EAAE,SAAS;AAEhE,QAAO,iBAAiB,SAAS,aAAa,KAAK,CAAC;;AAqCtD,SAAgB,cAAc,UAAsC;AAClE,KAAI,SACF,QAAO,iBAAiB,SAAS,KAAK,YAAY,SAAS;AAE7D,QAAO,iBAAiB,SAAS,KAAK,WAAW;;AAsCnD,SAAgB,cAAc,UAAsC;AAClE,KAAI,SACF,QAAO,iBAAiB,SAAS,KAAK,YAAY,SAAS;AAE7D,QAAO,iBAAiB,SAAS,KAAK,WAAW"}

package/dist/with-text-input-CmHf_9d6.d.mts

@@ -0,0 +1,284 @@
+import { _ as TextInputOptions, b as WithSelectOptions, i as ProgressGenerator, o as SelectOption, r as ProgressCallback, x as WithSpinnerOptions, y as WithProgressOptions } from "./types-CDgkE-Rw.mjs";
+import { r as Spinner } from "./spinner-Cgej6Vnb.mjs";
+import { EventEmitter } from "events";
+
+//#region packages/ag-react/src/ui/wrappers/with-spinner.d.ts
+/**
+ * Wrap a promise with an animated spinner
+ *
+ * @example
+ * ```ts
+ * // Simple usage
+ * const data = await withSpinner(fetchData(), "Loading data...");
+ *
+ * // With options
+ * const result = await withSpinner(
+ *   processFiles(),
+ *   "Processing...",
+ *   { style: "arc", clearOnComplete: true }
+ * );
+ *
+ * // With dynamic text
+ * const result = await withSpinner(
+ *   longOperation(),
+ *   (elapsed) => `Processing... (${elapsed}s)`
+ * );
+ * ```
+ */
+declare function withSpinner<T>(promise: Promise<T> | (() => T | Promise<T>), text: string | ((elapsedSeconds: number) => string), options?: WithSpinnerOptions): Promise<T>;
+/**
+ * Attach a spinner to a promise for manual control
+ * Returns [result, spinner] tuple for custom control
+ *
+ * @example
+ * ```ts
+ * const [promise, spinner] = attachSpinner(fetchData(), "Loading...");
+ * spinner.text = "Still loading...";
+ * const result = await promise;
+ * spinner.succeed("Loaded!");
+ * ```
+ */
+declare function attachSpinner<T>(promise: Promise<T>, text: string, options?: WithSpinnerOptions): [Promise<T>, Spinner];
+//#endregion
+//#region packages/ag-react/src/ui/wrappers/with-progress.d.ts
+/**
+ * Wrap a function that takes a progress callback
+ *
+ * @example
+ * ```ts
+ * // Wrap existing km sync API
+ * const result = await withProgress(
+ *   (onProgress) => manager.syncFromFs(onProgress),
+ *   {
+ *     phases: {
+ *       scanning: "Scanning files",
+ *       reconciling: "Reconciling changes",
+ *       rules: "Evaluating rules"
+ *     }
+ *   }
+ * );
+ *
+ * // Simple usage without phases
+ * await withProgress((onProgress) => rebuildState(onProgress));
+ *
+ * // With custom format
+ * await withProgress(
+ *   (p) => processFiles(p),
+ *   { format: ":phase :bar :percent" }
+ * );
+ *
+ * // Show loading immediately (showAfter: 0) or after delay
+ * await withProgress(
+ *   (p) => slowOperation(p),
+ *   { showAfter: 1000, initialMessage: "Loading..." }
+ * );
+ * ```
+ */
+declare function withProgress<T>(fn: (onProgress: ProgressCallback) => T | Promise<T>, options?: WithProgressOptions): Promise<T>;
+/**
+ * Create a progress callback that can be passed to existing APIs
+ * Returns [callback, complete] tuple
+ *
+ * @example
+ * ```ts
+ * const [onProgress, complete] = createProgressCallback({
+ *   phases: { scanning: "Scanning", reconciling: "Reconciling" }
+ * });
+ *
+ * const result = await manager.syncFromFs(onProgress);
+ * complete();
+ * ```
+ */
+declare function createProgressCallback(options?: WithProgressOptions): [ProgressCallback, () => void];
+//#endregion
+//#region packages/ag-react/src/ui/wrappers/wrap-generator.d.ts
+/**
+ * Consume a progress generator while displaying progress
+ *
+ * @example
+ * ```ts
+ * // Wrap existing generator (like evaluateAllRules())
+ * await wrapGenerator(evaluateAllRules(), "Evaluating rules");
+ *
+ * // With custom format
+ * await wrapGenerator(
+ *   processItems(),
+ *   ({ current, total }) => `Processing: ${current}/${total}`
+ * );
+ *
+ * // Get the generator's return value
+ * const result = await wrapGenerator(generatorWithReturn(), "Processing");
+ * ```
+ */
+declare function wrapGenerator<T>(generator: ProgressGenerator<T>, textOrFormat: string | ((progress: {
+  current: number;
+  total: number;
+}) => string), options?: {
+  clearOnComplete?: boolean;
+}): Promise<T>;
+/**
+ * Create an async iterable wrapper that shows progress
+ *
+ * @example
+ * ```ts
+ * const items = [1, 2, 3, 4, 5];
+ * for await (const item of withIterableProgress(items, "Processing")) {
+ *   await processItem(item);
+ * }
+ * ```
+ */
+declare function withIterableProgress<T>(iterable: Iterable<T> | AsyncIterable<T>, label: string, options?: {
+  clearOnComplete?: boolean;
+}): AsyncGenerator<T, void, unknown>;
+//#endregion
+//#region packages/ag-react/src/ui/wrappers/wrap-emitter.d.ts
+/** Event handler configuration */
+interface EventConfig {
+  /** Display text for this event */
+  text?: string;
+  /** Dynamic text based on event data */
+  getText?: (data: unknown) => string;
+  /** Mark spinner as succeeded */
+  succeed?: boolean;
+  /** Mark spinner as failed */
+  fail?: boolean;
+  /** Stop tracking */
+  stop?: boolean;
+}
+/** Configuration for wrapEmitter */
+interface WrapEmitterConfig {
+  /** Event handlers */
+  events: Record<string, EventConfig>;
+  /** Initial text */
+  initialText?: string;
+}
+/**
+ * Track EventEmitter state changes with a spinner
+ *
+ * @example
+ * ```ts
+ * const stop = wrapEmitter(syncManager, {
+ *   initialText: "Starting sync...",
+ *   events: {
+ *     'ready': { text: "Watcher ready", succeed: true },
+ *     'state-change': { getText: (s) => `State: ${s}` },
+ *     'error': { fail: true },
+ *     'idle': { stop: true }
+ *   }
+ * });
+ *
+ * // Later, to stop manually
+ * stop();
+ * ```
+ */
+declare function wrapEmitter(emitter: EventEmitter, config: WrapEmitterConfig): () => void;
+/**
+ * Wait for an EventEmitter to emit a specific event
+ * Shows a spinner while waiting
+ *
+ * @example
+ * ```ts
+ * await waitForEvent(syncManager, "ready", "Waiting for watcher...");
+ * ```
+ */
+declare function waitForEvent(emitter: EventEmitter, eventName: string, text: string, options?: {
+  errorEvent?: string;
+  timeout?: number;
+}): Promise<unknown>;
+//#endregion
+//#region packages/ag-react/src/ui/wrappers/with-select.d.ts
+/**
+ * Display an interactive selection list in the terminal
+ *
+ * @example
+ * ```ts
+ * // Simple usage
+ * const color = await withSelect("Choose a color:", [
+ *   { label: "Red", value: "red" },
+ *   { label: "Green", value: "green" },
+ *   { label: "Blue", value: "blue" },
+ * ]);
+ *
+ * // With options
+ * const result = await withSelect(
+ *   "Select item:",
+ *   options,
+ *   { initial: 2, maxVisible: 5 }
+ * );
+ * ```
+ */
+declare function withSelect<T>(prompt: string, options: SelectOption<T>[], selectOptions?: WithSelectOptions): Promise<T>;
+/**
+ * Create a reusable select instance for multiple selections
+ *
+ * @example
+ * ```ts
+ * const select = createSelect({
+ *   maxVisible: 5,
+ * });
+ *
+ * const first = await select("Choose first:", options1);
+ * const second = await select("Choose second:", options2);
+ * ```
+ */
+declare function createSelect(defaultOptions?: WithSelectOptions): <T>(prompt: string, options: SelectOption<T>[], overrides?: WithSelectOptions) => Promise<T>;
+//#endregion
+//#region packages/ag-react/src/ui/wrappers/with-text-input.d.ts
+/**
+ * Prompt for text input in the terminal
+ *
+ * @example
+ * ```ts
+ * // Simple usage
+ * const name = await withTextInput("What is your name?");
+ *
+ * // With options
+ * const password = await withTextInput("Password:", { mask: "*" });
+ *
+ * // With validation
+ * const email = await withTextInput("Email:", {
+ *   validate: (v) => v.includes("@") ? undefined : "Invalid email"
+ * });
+ *
+ * // With autocomplete
+ * const fruit = await withTextInput("Pick a fruit:", {
+ *   autocomplete: ["apple", "banana", "cherry"]
+ * });
+ * ```
+ */
+declare function withTextInput(prompt: string, options?: TextInputOptions): Promise<string>;
+/**
+ * Create a text input instance for manual control
+ *
+ * @example
+ * ```ts
+ * const input = createTextInput("Name:", { placeholder: "Enter name" });
+ * input.render();
+ *
+ * // Later, get the value
+ * const value = await input.waitForSubmit();
+ * ```
+ */
+declare function createTextInput(prompt: string, options?: TextInputOptions): TextInputInstance;
+/** Instance returned by createTextInput for manual control */
+interface TextInputInstance {
+  /** Current input value */
+  value: string;
+  /** Current cursor position */
+  cursorPosition: number;
+  /** Render the current state */
+  render(): void;
+  /** Insert text at cursor */
+  insert(char: string): void;
+  /** Delete character before cursor */
+  backspace(): void;
+  /** Delete character at cursor */
+  delete(): void;
+  /** Clear all input */
+  clear(): void;
+  /** Accept autocomplete suggestion */
+  acceptSuggestion(): void;
+}
+//#endregion
+export { waitForEvent as a, wrapGenerator as c, attachSpinner as d, withSpinner as f, withSelect as i, createProgressCallback as l, withTextInput as n, wrapEmitter as o, createSelect as r, withIterableProgress as s, createTextInput as t, withProgress as u };
+//# sourceMappingURL=with-text-input-CmHf_9d6.d.mts.map

package/dist/with-text-input-CmHf_9d6.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"with-text-input-CmHf_9d6.d.mts","names":[],"sources":["../packages/ag-react/src/ui/wrappers/with-spinner.ts","../packages/ag-react/src/ui/wrappers/with-progress.ts","../packages/ag-react/src/ui/wrappers/wrap-generator.ts","../packages/ag-react/src/ui/wrappers/wrap-emitter.ts","../packages/ag-react/src/ui/wrappers/with-select.ts","../packages/ag-react/src/ui/wrappers/with-text-input.ts"],"mappings":";;;;;AA6BA;;;;;;;;;;;;;;;;;;;;;;AAAA,iBAAsB,WAAA,GAAA,CACpB,OAAA,EAAS,OAAA,CAAQ,CAAA,WAAY,CAAA,GAAI,OAAA,CAAQ,CAAA,IACzC,IAAA,aAAiB,cAAA,sBACjB,OAAA,GAAS,kBAAA,GACR,OAAA,CAAQ,CAAA;;;;;;AAmDX;;;;;;;iBAAgB,aAAA,GAAA,CACd,OAAA,EAAS,OAAA,CAAQ,CAAA,GACjB,IAAA,UACA,OAAA,GAAS,kBAAA,IACP,OAAA,CAAQ,CAAA,GAAI,OAAA;;;;;;;;;;;;;;;;AAJhB;;;;;;;;;;;;;;;;;;;;iBCnBsB,YAAA,GAAA,CACpB,EAAA,GAAK,UAAA,EAAY,gBAAA,KAAqB,CAAA,GAAI,OAAA,CAAQ,CAAA,GAClD,OAAA,GAAS,mBAAA,GACR,OAAA,CAAQ,CAAA;;;;;;AAHX;;;;;;;;;iBAqIgB,sBAAA,CAAuB,OAAA,GAAS,mBAAA,IAA4B,gBAAA;;;;ADzK5E;;;;;;;;;;;;;;;;;iBEHsB,aAAA,GAAA,CACpB,SAAA,EAAW,iBAAA,CAAkB,CAAA,GAC7B,YAAA,aAAyB,QAAA;EAAY,OAAA;EAAiB,KAAA;AAAA,eACtD,OAAA;EAAW,eAAA;AAAA,IACV,OAAA,CAAQ,CAAA;;;;;;AFsDX;;;;;;iBEeuB,oBAAA,GAAA,CACrB,QAAA,EAAU,QAAA,CAAS,CAAA,IAAK,aAAA,CAAc,CAAA,GACtC,KAAA,UACA,OAAA;EAAW,eAAA;AAAA,IACV,cAAA,CAAe,CAAA;;;;UC/FR,WAAA;EHqBuB;EGnB/B,IAAA;EHoBiB;EGlBjB,OAAA,IAAW,IAAA;EHkBkB;EGhB7B,OAAA;EHgBiC;EGdjC,IAAA;EHiBS;EGfT,IAAA;AAAA;;UAIQ,iBAAA;EHQC;EGNT,MAAA,EAAQ,MAAA,SAAe,WAAA;EHMM;EGJ7B,WAAA;AAAA;;;;;;;;;;AH0DF;;;;;;;;;;iBGpCgB,WAAA,CAAY,OAAA,EAAS,YAAA,EAAc,MAAA,EAAQ,iBAAA;;;;;;;;;;iBA0DrC,YAAA,CACpB,OAAA,EAAS,YAAA,EACT,SAAA,UACA,IAAA,UACA,OAAA;EACE,UAAA;EACA,OAAA;AAAA,IAED,OAAA;;;;AHrFH;;;;;;;;;;;;;;;;;;;iBIDsB,UAAA,GAAA,CACpB,MAAA,UACA,OAAA,EAAS,YAAA,CAAa,CAAA,KACtB,aAAA,GAAe,iBAAA,GACd,OAAA,CAAQ,CAAA;;;;;;;;;AJoDX;;;;;iBIwGgB,YAAA,CACd,cAAA,GAAgB,iBAAA,OACX,MAAA,UAAgB,OAAA,EAAS,YAAA,CAAa,CAAA,KAAM,SAAA,GAAY,iBAAA,KAAsB,OAAA,CAAQ,CAAA;;;;AJjK7F;;;;;;;;;;;;;;;;;;;;;iBKCsB,aAAA,CAAc,MAAA,UAAgB,OAAA,GAAS,gBAAA,GAAwB,OAAA;;;;;;;ALsDrF;;;;;;iBKwMgB,eAAA,CAAgB,MAAA,UAAgB,OAAA,GAAS,gBAAA,GAAwB,iBAAA;;UA0EhE,iBAAA;EL9QM;EKgRrB,KAAA;ELpR4B;EKsR5B,cAAA;ELrRiB;EKuRjB,MAAA;ELtRA;EKwRA,MAAA,CAAO,IAAA;ELvRP;EKyRA,SAAA;ELxRU;EK0RV,MAAA;EL1RqB;EK4RrB,KAAA;;EAEA,gBAAA;AAAA"}