@mdxui/terminal 2.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (191) hide show
  1. package/README.md +571 -0
  2. package/dist/ansi-css-Sk5mWtdK.d.ts +119 -0
  3. package/dist/ansi-css-V6JIHGsM.d.ts +119 -0
  4. package/dist/ansi-css-_3eSEU9d.d.ts +119 -0
  5. package/dist/chunk-3EFDH7PK.js +5235 -0
  6. package/dist/chunk-3RG5ZIWI.js +10 -0
  7. package/dist/chunk-3X5IR6WE.js +884 -0
  8. package/dist/chunk-4FV5ZDCE.js +5236 -0
  9. package/dist/chunk-4OVMSF2J.js +243 -0
  10. package/dist/chunk-63FEETIS.js +4048 -0
  11. package/dist/chunk-B43KP7XJ.js +884 -0
  12. package/dist/chunk-BMTJXWUV.js +655 -0
  13. package/dist/chunk-C3SVH4N7.js +882 -0
  14. package/dist/chunk-EVWR7Y47.js +874 -0
  15. package/dist/chunk-F6A5VWUC.js +1285 -0
  16. package/dist/chunk-FD7KW7GE.js +882 -0
  17. package/dist/chunk-GBQ6UD6I.js +655 -0
  18. package/dist/chunk-GMDD3M6U.js +5227 -0
  19. package/dist/chunk-JBHRXOXM.js +1058 -0
  20. package/dist/chunk-JFOO3EYO.js +1182 -0
  21. package/dist/chunk-JQ5H3WXL.js +1291 -0
  22. package/dist/chunk-JQD5NASE.js +234 -0
  23. package/dist/chunk-KRHJP5R7.js +592 -0
  24. package/dist/chunk-KWF6WVJE.js +962 -0
  25. package/dist/chunk-LHYQVN3H.js +1038 -0
  26. package/dist/chunk-M3TLQLGC.js +1032 -0
  27. package/dist/chunk-MVW4Q5OP.js +240 -0
  28. package/dist/chunk-NXCZSWLU.js +1294 -0
  29. package/dist/chunk-O25TNRO6.js +607 -0
  30. package/dist/chunk-PNECDA2I.js +884 -0
  31. package/dist/chunk-QIHWRLJR.js +962 -0
  32. package/dist/chunk-QW5YMQ7K.js +882 -0
  33. package/dist/chunk-R5U7XKVJ.js +16 -0
  34. package/dist/chunk-RP2MVQLR.js +962 -0
  35. package/dist/chunk-TP6RXGXA.js +1087 -0
  36. package/dist/chunk-TQQSTITZ.js +655 -0
  37. package/dist/chunk-X24GWXQV.js +1281 -0
  38. package/dist/components/index.d.ts +802 -0
  39. package/dist/components/index.js +149 -0
  40. package/dist/data/index.d.ts +2554 -0
  41. package/dist/data/index.js +51 -0
  42. package/dist/forms/index.d.ts +1596 -0
  43. package/dist/forms/index.js +464 -0
  44. package/dist/index-CQRFZntR.d.ts +867 -0
  45. package/dist/index.d.ts +579 -0
  46. package/dist/index.js +786 -0
  47. package/dist/interactive-D0JkWosD.d.ts +217 -0
  48. package/dist/keyboard/index.d.ts +2 -0
  49. package/dist/keyboard/index.js +43 -0
  50. package/dist/renderers/index.d.ts +546 -0
  51. package/dist/renderers/index.js +2157 -0
  52. package/dist/storybook/index.d.ts +396 -0
  53. package/dist/storybook/index.js +641 -0
  54. package/dist/theme/index.d.ts +1339 -0
  55. package/dist/theme/index.js +123 -0
  56. package/dist/types-Bxu5PAgA.d.ts +710 -0
  57. package/dist/types-CIlop5Ji.d.ts +701 -0
  58. package/dist/types-Ca8p_p5X.d.ts +710 -0
  59. package/package.json +90 -0
  60. package/src/__tests__/components/data/card.test.ts +458 -0
  61. package/src/__tests__/components/data/list.test.ts +473 -0
  62. package/src/__tests__/components/data/metrics.test.ts +541 -0
  63. package/src/__tests__/components/data/table.test.ts +448 -0
  64. package/src/__tests__/components/input/field.test.ts +555 -0
  65. package/src/__tests__/components/input/form.test.ts +870 -0
  66. package/src/__tests__/components/input/search.test.ts +1238 -0
  67. package/src/__tests__/components/input/select.test.ts +658 -0
  68. package/src/__tests__/components/navigation/breadcrumb.test.ts +923 -0
  69. package/src/__tests__/components/navigation/command-palette.test.ts +1095 -0
  70. package/src/__tests__/components/navigation/sidebar.test.ts +1018 -0
  71. package/src/__tests__/components/navigation/tabs.test.ts +995 -0
  72. package/src/__tests__/components.test.tsx +1197 -0
  73. package/src/__tests__/core/compiler.test.ts +986 -0
  74. package/src/__tests__/core/parser.test.ts +785 -0
  75. package/src/__tests__/core/tier-switcher.test.ts +1103 -0
  76. package/src/__tests__/core/types.test.ts +1398 -0
  77. package/src/__tests__/data/collections.test.ts +1337 -0
  78. package/src/__tests__/data/db.test.ts +1265 -0
  79. package/src/__tests__/data/reactive.test.ts +1010 -0
  80. package/src/__tests__/data/sync.test.ts +1614 -0
  81. package/src/__tests__/errors.test.ts +660 -0
  82. package/src/__tests__/forms/integration.test.ts +444 -0
  83. package/src/__tests__/integration.test.ts +905 -0
  84. package/src/__tests__/keyboard.test.ts +1791 -0
  85. package/src/__tests__/renderer.test.ts +489 -0
  86. package/src/__tests__/renderers/ansi-css.test.ts +948 -0
  87. package/src/__tests__/renderers/ansi.test.ts +1366 -0
  88. package/src/__tests__/renderers/ascii.test.ts +1360 -0
  89. package/src/__tests__/renderers/interactive.test.ts +2353 -0
  90. package/src/__tests__/renderers/markdown.test.ts +1483 -0
  91. package/src/__tests__/renderers/text.test.ts +1369 -0
  92. package/src/__tests__/renderers/unicode.test.ts +1307 -0
  93. package/src/__tests__/theme.test.ts +639 -0
  94. package/src/__tests__/utils/assertions.ts +685 -0
  95. package/src/__tests__/utils/index.ts +115 -0
  96. package/src/__tests__/utils/test-renderer.ts +381 -0
  97. package/src/__tests__/utils/utils.test.ts +560 -0
  98. package/src/components/containers/card.ts +56 -0
  99. package/src/components/containers/dialog.ts +53 -0
  100. package/src/components/containers/index.ts +9 -0
  101. package/src/components/containers/panel.ts +59 -0
  102. package/src/components/feedback/badge.ts +40 -0
  103. package/src/components/feedback/index.ts +8 -0
  104. package/src/components/feedback/spinner.ts +23 -0
  105. package/src/components/helpers.ts +81 -0
  106. package/src/components/index.ts +153 -0
  107. package/src/components/layout/breadcrumb.ts +31 -0
  108. package/src/components/layout/index.ts +10 -0
  109. package/src/components/layout/list.ts +29 -0
  110. package/src/components/layout/sidebar.ts +79 -0
  111. package/src/components/layout/table.ts +62 -0
  112. package/src/components/primitives/box.ts +95 -0
  113. package/src/components/primitives/button.ts +54 -0
  114. package/src/components/primitives/index.ts +11 -0
  115. package/src/components/primitives/input.ts +88 -0
  116. package/src/components/primitives/select.ts +97 -0
  117. package/src/components/primitives/text.ts +60 -0
  118. package/src/components/render.ts +155 -0
  119. package/src/components/templates/app.ts +43 -0
  120. package/src/components/templates/index.ts +8 -0
  121. package/src/components/templates/site.ts +54 -0
  122. package/src/components/types.ts +777 -0
  123. package/src/core/compiler.ts +718 -0
  124. package/src/core/parser.ts +127 -0
  125. package/src/core/tier-switcher.ts +607 -0
  126. package/src/core/types.ts +672 -0
  127. package/src/data/collection.ts +316 -0
  128. package/src/data/collections.ts +50 -0
  129. package/src/data/context.tsx +174 -0
  130. package/src/data/db.ts +127 -0
  131. package/src/data/hooks.ts +532 -0
  132. package/src/data/index.ts +138 -0
  133. package/src/data/reactive.ts +1225 -0
  134. package/src/data/saas-collections.ts +375 -0
  135. package/src/data/sync.ts +1213 -0
  136. package/src/data/types.ts +660 -0
  137. package/src/forms/converters.ts +512 -0
  138. package/src/forms/index.ts +133 -0
  139. package/src/forms/schemas.ts +403 -0
  140. package/src/forms/types.ts +476 -0
  141. package/src/index.ts +542 -0
  142. package/src/keyboard/focus.ts +748 -0
  143. package/src/keyboard/index.ts +96 -0
  144. package/src/keyboard/integration.ts +371 -0
  145. package/src/keyboard/manager.ts +377 -0
  146. package/src/keyboard/presets.ts +90 -0
  147. package/src/renderers/ansi-css.ts +576 -0
  148. package/src/renderers/ansi.ts +802 -0
  149. package/src/renderers/ascii.ts +680 -0
  150. package/src/renderers/breadcrumb.ts +480 -0
  151. package/src/renderers/command-palette.ts +802 -0
  152. package/src/renderers/components/field.ts +210 -0
  153. package/src/renderers/components/form.ts +327 -0
  154. package/src/renderers/components/index.ts +21 -0
  155. package/src/renderers/components/search.ts +449 -0
  156. package/src/renderers/components/select.ts +222 -0
  157. package/src/renderers/index.ts +101 -0
  158. package/src/renderers/interactive/component-handlers.ts +622 -0
  159. package/src/renderers/interactive/cursor-manager.ts +147 -0
  160. package/src/renderers/interactive/focus-manager.ts +279 -0
  161. package/src/renderers/interactive/index.ts +661 -0
  162. package/src/renderers/interactive/input-handler.ts +164 -0
  163. package/src/renderers/interactive/keyboard-handler.ts +212 -0
  164. package/src/renderers/interactive/mouse-handler.ts +167 -0
  165. package/src/renderers/interactive/state-manager.ts +109 -0
  166. package/src/renderers/interactive/types.ts +338 -0
  167. package/src/renderers/interactive-string.ts +299 -0
  168. package/src/renderers/interactive.ts +59 -0
  169. package/src/renderers/markdown.ts +950 -0
  170. package/src/renderers/sidebar.ts +549 -0
  171. package/src/renderers/tabs.ts +682 -0
  172. package/src/renderers/text.ts +791 -0
  173. package/src/renderers/unicode.ts +917 -0
  174. package/src/renderers/utils.ts +942 -0
  175. package/src/router/adapters.ts +383 -0
  176. package/src/router/types.ts +140 -0
  177. package/src/router/utils.ts +452 -0
  178. package/src/schemas.ts +205 -0
  179. package/src/storybook/index.ts +91 -0
  180. package/src/storybook/interactive-decorator.tsx +659 -0
  181. package/src/storybook/keyboard-simulator.ts +501 -0
  182. package/src/theme/ansi-codes.ts +80 -0
  183. package/src/theme/box-drawing.ts +132 -0
  184. package/src/theme/color-convert.ts +254 -0
  185. package/src/theme/color-support.ts +321 -0
  186. package/src/theme/index.ts +134 -0
  187. package/src/theme/strip-ansi.ts +50 -0
  188. package/src/theme/tailwind-map.ts +469 -0
  189. package/src/theme/text-styles.ts +206 -0
  190. package/src/theme/theme-system.ts +568 -0
  191. package/src/types.ts +103 -0
@@ -0,0 +1,579 @@
1
+ import React__default, { ReactNode } from 'react';
2
+ export { ActionConfig, ActionProp, ActionsProps, App, AppHeader, AppHeaderProps, AppHeaderUser, AppProps, Badge, BadgeProps, Box, BoxProps, Breadcrumb, BreadcrumbItem, BreadcrumbProps, Button, ButtonProps, COMPONENT_TYPES, Card, CardProps, Dashboard, DashboardMetric, DashboardProps, Dialog, DialogProps, FAQ, FAQItem, FAQProps, FeatureItem, Features, FeaturesProps, Footer, FooterLinkGroup, FooterProps, Header, HeaderProps, Hero, HeroProps, Input, InputProps, LandingPage, LandingPageProps, List, ListProps, NavItem, Page, PageProps, Panel, PanelProps, Pricing, PricingProps, PricingTier, RenderContext, Select, SelectOption, SelectProps, Settings, SettingsProps, SettingsSection, Shell, ShellProps, Sidebar, SidebarItem, SidebarItemProps, SidebarLayout, SidebarProps, Site, SiteProps, SocialLink, Spinner, SpinnerProps, Table, TableColumn, TableProps, TerminalComponentType, TerminalSidebarLayoutProps, Text, TextProps, bgColorMap, colorMap, extractChildren, getBgColorCode, getColorCode, isBadgeProps, isBoxProps, isBreadcrumbProps, isButtonProps, isCardProps, isDialogProps, isInputProps, isListProps, isPanelProps, isPropsObject, isSelectProps, isSidebarItemProps, isSidebarProps, isSpinnerProps, isTableProps, isTerminalComponentType, isTextProps, renderBadge, renderBox, renderBreadcrumb, renderButton, renderCard, renderComponent, renderDialog, renderElement, renderInput, renderList, renderPanel, renderSelect, renderSidebar, renderSidebarItem, renderSpinner, renderTable, spinnerFrames } from './components/index.js';
3
+ export { ANSI, Ansi256Code, Ansi256CodeSchema, AnsiEscapeSchema, BoxStyle, ColorSupport, ColorSupportSchema, CreateTerminalThemeOptions, CreateTerminalThemeOptionsInput, CreateTerminalThemeOptionsSchema, CreateThemeInput, CreateThemeInputSchema, HexColor, HexColorSchema, LegacyTerminalTheme, LegacyTerminalThemeSchema, LegacyTerminalThemeWithExtras, LegacyTerminalThemeWithExtrasSchema, RgbColor, RgbColorSchema, RgbComponentSchema, RgbToAnsiOptions, RgbToAnsiOptionsSchema, TAILWIND_COLORS, TerminalTheme, TerminalThemeColors, TerminalThemeColorsSchema, ThemeMode, ThemeModeSchema, adaptColor, ansi256, ansi256Bg, applyThemeStyles, bg, bold, boxChars, colors, composeThemes, createTerminalTheme, createTheme, createThemeVariant, cssVarToAnsi, darkTheme, defaultTheme, degradeColor, detectColorScheme, detectColorSupport, dim, drawBox, extendTheme, fg, getThemeColor, hex, hexBg, hexToAnsi, hexToRgb, highContrastTheme, italic, lightTheme, rgb, rgbBg, rgbToAnsi, strikethrough, stripAnsi, style, styled, tailwindToAnsi, tailwindToTerminal, themePresets, themeTokens, underline, visibleLength } from './theme/index.js';
4
+ export { h as ARROW_BINDINGS, A as ActionContext, c as ActionHandler, y as AttachKeyboardOptions, C as COMMON_BINDINGS, D as DetachKeyboard, E as EMACS_BINDINGS, r as FocusContext, J as FocusId, k as FocusManagerState, x as FocusProvider, q as FocusProviderProps, F as FocusableElement, f as KEY, b as KeyBindings, K as KeyModifiers, a as KeyboardAction, e as KeyboardManager, d as KeyboardManagerOptions, N as NormalizedKey, O as OpenTUIKeyEvent, R as ReadlineKey, j as UseFocusOptions, U as UseKeyboardOptions, i as UseKeyboardResult, o as UseNavigableGridOptions, p as UseNavigableGridResult, l as UseNavigableListOptions, n as UseNavigableListResult, V as VIM_BINDINGS, _ as __resetFocusIdCounter, G as attachKeyboardManager, L as createFocusId, g as createKeyboardManager, I as createOpenTUIKeyHandler, M as isFocusId, B as keyToBindingString, m as matchKey, H as normalizeOpenTUIKey, z as normalizeReadlineKey, s as useFocus, t as useFocusManager, u as useKeyboard, w as useNavigableGrid, v as useNavigableList } from './index-CQRFZntR.js';
5
+ export { APIKey, APIKeySchema, APIKeysCollection, Collection, ComparisonOperators, ConflictResolution, DB, DBConfig, DBProvider, DBProviderProps, DOSyncAdapter, DOSyncConfig, FieldFilter, FindManyOptions, MetricValue, MutationOperation, MutationOptions, MutationResult, OrderByClause, OrderDirection, PaginationState, QueryOptions, QueryResult, ReactiveCardOptions, ReactiveCardResult, ReactiveDataOptions, ReactiveDataResult, ReactiveListOptions, ReactiveMetricsOptions, ReactiveMetricsResult, ReactiveTableOptions, ReconnectOptions, SelectionState, SortState, SyncAdapter, Team, TeamSchema, TeamsCollection, Usage, UsageCollection, UsageSchema, User, UserRole, UserRoleSchema, UserSchema, UsersCollection, Webhook, WebhookSchema, WebhooksCollection, WhereClause, createCollection, createDB, createDOSync, useDBContext, useMutation, useQuery, useReactiveCard, useReactiveData, useReactiveList, useReactiveMetrics, useReactiveTable } from './data/index.js';
6
+ import { U as UINode } from './types-Bxu5PAgA.js';
7
+ export { a as CoreRenderContext, e as RenderContextSchema, R as RenderTier, c as RenderTierSchema, T as ThemeTokens, d as ThemeTokensSchema, b as UINodeSchema } from './types-Bxu5PAgA.js';
8
+ export { A as ANSIToCSSResult, C as CSSStyleProperties, S as StyledSpan, T as TextRenderOptions, a as ansiToCSS, b as ansiToHTML, p as parseAnsiToSpans, r as renderText, s as spanToInlineStyle } from './ansi-css-_3eSEU9d.js';
9
+ import 'zod';
10
+
11
+ /**
12
+ * @mdxui/terminal JSX to UINode Compiler
13
+ *
14
+ * Compiles React element trees into UINode trees for terminal rendering.
15
+ *
16
+ * @remarks
17
+ * This module provides a TDD-implemented JSX compiler that converts React's
18
+ * dynamic component tree model into a serializable UINode tree optimized for
19
+ * terminal rendering. The compiler handles all React element types including
20
+ * fragments, nested trees, and edge cases like null/undefined filtering.
21
+ *
22
+ * **Performance Characteristics:**
23
+ * - Single-pass traversal: O(n) where n = total nodes
24
+ * - No backtracking or re-traversal of elements
25
+ * - Memory-efficient: Reuses object literals where safe
26
+ * - Deep tree optimization: Tail-call patterns for stack efficiency
27
+ * - Allocation minimization: Early returns avoid intermediate arrays
28
+ *
29
+ * **Key Design Principles:**
30
+ * 1. **Type Safety**: All child types validated at process time
31
+ * 2. **Fragment Flattening**: React Fragments unwrapped during traversal
32
+ * 3. **Null Filtering**: React's null/undefined/boolean children filtered out
33
+ * 4. **Key Preservation**: React keys converted to string keys for reconciliation
34
+ * 5. **Props Isolation**: Children field excluded from props object
35
+ *
36
+ * **Usage Example:**
37
+ * ```typescript
38
+ * import { compileJSX } from '@mdxui/terminal'
39
+ *
40
+ * const jsx = <Box padding={2}>
41
+ * <Text bold>Hello</Text>
42
+ * <Text>World</Text>
43
+ * </Box>
44
+ *
45
+ * const uiTree = compileJSX(jsx)
46
+ * // Result:
47
+ * // {
48
+ * // type: 'Box',
49
+ * // props: { padding: 2 },
50
+ * // children: [
51
+ * // { type: 'Text', props: { bold: true }, children: [{ type: 'Text', props: {}, children: ['Hello'] }] },
52
+ * // { type: 'Text', props: {}, children: ['World'] }
53
+ * // ]
54
+ * // }
55
+ * ```
56
+ *
57
+ * @category Compiler
58
+ * @module compiler
59
+ */
60
+
61
+ /**
62
+ * Compiles a React JSX element into a UINode tree for terminal rendering.
63
+ *
64
+ * Converts React's dynamic element tree into a serializable form suitable for
65
+ * cross-tier terminal rendering (text, markdown, ascii, unicode, ansi, interactive).
66
+ *
67
+ * @param element - A React element created via React.createElement or JSX
68
+ * @returns A UINode tree representing the compiled element with all descendants
69
+ *
70
+ * @remarks
71
+ * **Input Handling:**
72
+ * - Accepts React elements from `React.createElement()` or JSX syntax
73
+ * - Component types (functions, classes, strings) are normalized to strings
74
+ * - Props are extracted and children are processed separately
75
+ * - React keys are preserved for list reconciliation
76
+ *
77
+ * **Output Structure:**
78
+ * - Always returns an object with `type` (string) and `props` (object)
79
+ * - Includes `children` array only if children exist or were explicitly provided
80
+ * - Includes `key` field only if key was present in source element
81
+ * - All props except `children` are preserved as-is
82
+ *
83
+ * **Fragment Handling:**
84
+ * Fragments are automatically unwrapped:
85
+ * ```typescript
86
+ * // Input
87
+ * <Box>
88
+ * <>
89
+ * <Text>A</Text>
90
+ * <Text>B</Text>
91
+ * </>
92
+ * </Box>
93
+ *
94
+ * // Output - Fragment is transparent
95
+ * {
96
+ * type: 'Box',
97
+ * props: {},
98
+ * children: [
99
+ * { type: 'Text', props: {}, children: ['A'] },
100
+ * { type: 'Text', props: {}, children: ['B'] }
101
+ * ]
102
+ * }
103
+ * ```
104
+ *
105
+ * **Key Preservation:**
106
+ * React keys are converted to strings and preserved for reconciliation:
107
+ * ```typescript
108
+ * // Input
109
+ * <List>
110
+ * {items.map((item, i) => <Item key={item.id}>{item.name}</Item>)}
111
+ * </List>
112
+ *
113
+ * // Output - Keys preserved for stable reconciliation
114
+ * {
115
+ * type: 'List',
116
+ * props: {},
117
+ * children: [
118
+ * { type: 'Item', props: {}, key: 'item-1', children: ['Alice'] },
119
+ * { type: 'Item', props: {}, key: 'item-2', children: ['Bob'] }
120
+ * ]
121
+ * }
122
+ * ```
123
+ *
124
+ * **Null/Undefined Filtering:**
125
+ * React's falsy child filtering is applied:
126
+ * ```typescript
127
+ * // Input - null, undefined, and boolean children filtered
128
+ * <Box>
129
+ * {text}
130
+ * {condition && <Element />}
131
+ * {false}
132
+ * {null}
133
+ * {undefined}
134
+ * </Box>
135
+ *
136
+ * // Output - Only truthy content remains
137
+ * {
138
+ * type: 'Box',
139
+ * props: {},
140
+ * children: [
141
+ * { type: 'string', props: {}, children: ['some text'] },
142
+ * { type: 'Element', props: {} } // Only if condition was true
143
+ * ]
144
+ * }
145
+ * ```
146
+ *
147
+ * **Performance Notes:**
148
+ * - Single-pass tree traversal with O(n) complexity
149
+ * - Tail-call optimized for deep component trees
150
+ * - Minimal intermediate allocations
151
+ * - Type checks ordered by frequency (strings before rare types)
152
+ *
153
+ * @example
154
+ * Simple component:
155
+ * ```typescript
156
+ * const element = <Box padding={2} />
157
+ * const result = compileJSX(element)
158
+ * // { type: 'Box', props: { padding: 2 } }
159
+ * ```
160
+ *
161
+ * @example
162
+ * With children:
163
+ * ```typescript
164
+ * const element = <Text bold>Hello World</Text>
165
+ * const result = compileJSX(element)
166
+ * // { type: 'Text', props: { bold: true }, children: ['Hello World'] }
167
+ * ```
168
+ *
169
+ * @example
170
+ * With nested elements and fragment:
171
+ * ```typescript
172
+ * const element = (
173
+ * <Layout>
174
+ * <Header title="App" />
175
+ * <>
176
+ * <Content />
177
+ * <Sidebar />
178
+ * </>
179
+ * <Footer />
180
+ * </Layout>
181
+ * )
182
+ * const result = compileJSX(element)
183
+ * // { type: 'Layout', props: {}, children: [
184
+ * // { type: 'Header', props: { title: 'App' } },
185
+ * // { type: 'Content', props: {} },
186
+ * // { type: 'Sidebar', props: {} },
187
+ * // { type: 'Footer', props: {} }
188
+ * // ]}
189
+ * ```
190
+ *
191
+ * @see {@link UINode} for the output structure
192
+ * @see {@link processChildren} for child processing logic
193
+ * @see {@link processChild} for single child handling
194
+ *
195
+ * @throws {Error} Will not throw - gracefully handles all React element types
196
+ */
197
+ declare function compileJSX(element: React__default.ReactElement): UINode;
198
+ /**
199
+ * Compiles a React JSX element into a UINode tree using iteration.
200
+ *
201
+ * This is an alternative to {@link compileJSX} optimized for deeply nested
202
+ * trees that might cause stack overflow with recursive compilation. Use this
203
+ * when you expect trees with nesting depth > 1000 levels.
204
+ *
205
+ * @param element - A React element created via React.createElement or JSX
206
+ * @returns A UINode tree representing the compiled element with all descendants
207
+ *
208
+ * @remarks
209
+ * **Algorithm:**
210
+ * Uses an explicit work stack to process elements iteratively:
211
+ * 1. Start with root element on the stack
212
+ * 2. Pop element, create UINode with props
213
+ * 3. Process children:
214
+ * - Primitives (string/number): add directly to children array
215
+ * - Fragments: extract children, add to pending work
216
+ * - Elements: add placeholder, push to work stack
217
+ * 4. Continue until stack is empty
218
+ *
219
+ * **Performance:**
220
+ * - O(n) time complexity where n = total nodes
221
+ * - O(d) space complexity where d = maximum tree depth
222
+ * - No recursion limit - can handle 10,000+ nesting levels
223
+ * - Slightly more overhead than recursive version for shallow trees
224
+ *
225
+ * **When to Use:**
226
+ * - Trees with > 1000 nesting levels
227
+ * - Dynamic tree generation where depth is unbounded
228
+ * - Processing user-generated content with arbitrary nesting
229
+ *
230
+ * For most use cases with reasonable tree depths (< 500 levels),
231
+ * use the standard {@link compileJSX} function instead.
232
+ *
233
+ * @example
234
+ * Deep tree compilation:
235
+ * ```typescript
236
+ * // Build a very deep tree
237
+ * let deepElement = <Text>Leaf</Text>
238
+ * for (let i = 0; i < 5000; i++) {
239
+ * deepElement = <Box>{deepElement}</Box>
240
+ * }
241
+ *
242
+ * // This would cause stack overflow with compileJSX
243
+ * // But works fine with compileJSXDeep
244
+ * const uiTree = compileJSXDeep(deepElement)
245
+ * ```
246
+ *
247
+ * @see {@link compileJSX} for the standard recursive implementation
248
+ */
249
+ declare function compileJSXDeep(element: React__default.ReactElement): UINode;
250
+
251
+ /**
252
+ * @mdxui/terminal JSON Parser
253
+ *
254
+ * Converts JSON strings and objects into validated UINode structures.
255
+ * Supports both JSON string parsing and pre-parsed object validation.
256
+ */
257
+
258
+ /**
259
+ * Custom error class for parsing errors.
260
+ * Provides helpful error messages for JSON parsing and UINode validation failures.
261
+ */
262
+ declare class ParseError extends Error {
263
+ constructor(message: string);
264
+ }
265
+ /**
266
+ * Parse a JSON string or JavaScript object into a validated UINode.
267
+ *
268
+ * @param input - JSON string or pre-parsed JavaScript object
269
+ * @returns Validated UINode
270
+ * @throws ParseError if the input is invalid JSON or doesn't match UINode structure
271
+ *
272
+ * @example
273
+ * ```tsx
274
+ * // Parse JSON string
275
+ * const node = parseUINode('{"type":"text","props":{"content":"Hello"}}')
276
+ *
277
+ * // Parse pre-parsed object
278
+ * const node = parseUINode({ type: 'text', props: { content: 'Hello' } })
279
+ * ```
280
+ */
281
+ declare function parseUINode(input: string | unknown): UINode;
282
+ /**
283
+ * Parse a JSON string into a validated UINode.
284
+ *
285
+ * This is a convenience function that only accepts JSON strings.
286
+ * For parsing pre-parsed objects, use parseUINode directly.
287
+ *
288
+ * @param json - JSON string representation of a UINode
289
+ * @returns Validated UINode
290
+ * @throws ParseError if the JSON is invalid or doesn't match UINode structure
291
+ *
292
+ * @example
293
+ * ```tsx
294
+ * const node = parseUINodeFromJSON('{"type":"text","props":{"content":"Hello"}}')
295
+ * ```
296
+ */
297
+ declare function parseUINodeFromJSON(json: string): UINode;
298
+
299
+ /**
300
+ * @mdxui/terminal
301
+ *
302
+ * OpenTUI renderer for MDXUI primitives.
303
+ * Build CLI dashboards with the same component contracts as web.
304
+ *
305
+ * @example
306
+ * ```tsx
307
+ * import { CLI, Box, Text } from '@mdxui/terminal'
308
+ *
309
+ * async function main() {
310
+ * const cli = await CLI()
311
+ * cli.render(
312
+ * <Box border="single">
313
+ * <Text color="cyan">Hello Terminal!</Text>
314
+ * </Box>
315
+ * )
316
+ * }
317
+ *
318
+ * main()
319
+ * ```
320
+ *
321
+ * @example
322
+ * ```tsx
323
+ * // For more control, use the lower-level API
324
+ * import { createCliRenderer, createRoot } from '@mdxui/terminal'
325
+ *
326
+ * async function main() {
327
+ * const renderer = await createCliRenderer()
328
+ * const root = createRoot(renderer)
329
+ * root.render(<App />)
330
+ * }
331
+ * ```
332
+ */
333
+
334
+ /**
335
+ * CLI renderer configuration options
336
+ */
337
+ interface CliRendererConfig {
338
+ /** Input stream (defaults to process.stdin) */
339
+ stdin?: NodeJS.ReadStream;
340
+ /** Output stream (defaults to process.stdout) */
341
+ stdout?: NodeJS.WriteStream;
342
+ /** Exit on Ctrl+C (defaults to true) */
343
+ exitOnCtrlC?: boolean;
344
+ /** Target frames per second */
345
+ targetFps?: number;
346
+ /** Use alternate screen buffer */
347
+ useAlternateScreen?: boolean;
348
+ /** Enable mouse support */
349
+ useMouse?: boolean;
350
+ /** Background color */
351
+ backgroundColor?: string;
352
+ }
353
+ /**
354
+ * CLI renderer instance
355
+ */
356
+ interface CliRenderer {
357
+ /** Terminal width in columns */
358
+ width: number;
359
+ /** Terminal height in rows */
360
+ height: number;
361
+ /** Start the render loop */
362
+ start(): void;
363
+ /** Stop the render loop */
364
+ stop(): void;
365
+ /** Destroy the renderer and clean up */
366
+ destroy(): void;
367
+ /** Request a render update */
368
+ requestRender(): void;
369
+ }
370
+ /**
371
+ * Root interface for React rendering
372
+ */
373
+ interface Root {
374
+ /** Render a React element */
375
+ render(element: ReactNode): void;
376
+ /** Unmount and clean up */
377
+ unmount(): void;
378
+ }
379
+ /**
380
+ * Create an OpenTUI CLI renderer for terminal rendering.
381
+ *
382
+ * @param config - Optional configuration options
383
+ * @returns Promise resolving to a CLI renderer instance
384
+ *
385
+ * @example
386
+ * ```tsx
387
+ * import { createCliRenderer, createRoot } from '@mdxui/terminal'
388
+ *
389
+ * async function main() {
390
+ * const renderer = await createCliRenderer()
391
+ * const root = createRoot(renderer)
392
+ * root.render(<App />)
393
+ * }
394
+ * ```
395
+ */
396
+ declare function createCliRenderer(config?: CliRendererConfig): Promise<CliRenderer>;
397
+ /**
398
+ * Create a root for rendering a React tree with the given CLI renderer.
399
+ *
400
+ * @param renderer - The CLI renderer to use (from createCliRenderer)
401
+ * @returns A root object with render and unmount methods
402
+ *
403
+ * @example
404
+ * ```tsx
405
+ * const renderer = await createCliRenderer()
406
+ * const root = createRoot(renderer)
407
+ * root.render(<App />)
408
+ *
409
+ * // Later, to clean up:
410
+ * root.unmount()
411
+ * renderer.destroy()
412
+ * ```
413
+ */
414
+ declare function createRoot(renderer: CliRenderer): Root;
415
+ /**
416
+ * Options for the CLI() function
417
+ */
418
+ interface CLIOptions {
419
+ /** Color support level. Auto-detected if not specified. */
420
+ colorSupport?: 'none' | '16' | '256' | 'truecolor';
421
+ /** Input stream (defaults to process.stdin) */
422
+ stdin?: NodeJS.ReadStream;
423
+ /** Output stream (defaults to process.stdout) */
424
+ stdout?: NodeJS.WriteStream;
425
+ /** Exit on Ctrl+C (defaults to true) */
426
+ exitOnCtrlC?: boolean;
427
+ /** Target frames per second */
428
+ targetFps?: number;
429
+ /** Use alternate screen buffer */
430
+ useAlternateScreen?: boolean;
431
+ /** Enable mouse support */
432
+ useMouse?: boolean;
433
+ /** Background color */
434
+ backgroundColor?: string;
435
+ }
436
+ /**
437
+ * CLI instance returned by CLI()
438
+ */
439
+ interface CLIInstance {
440
+ /** Terminal width in columns */
441
+ readonly width: number;
442
+ /** Terminal height in rows */
443
+ readonly height: number;
444
+ /** Render a React element to the terminal */
445
+ render: (element: ReactNode) => void;
446
+ /** Clear the terminal */
447
+ clear: () => void;
448
+ /** Destroy the CLI instance and clean up resources */
449
+ destroy: () => void;
450
+ /** Request a render update */
451
+ requestRender: () => void;
452
+ /** The underlying renderer instance */
453
+ readonly renderer: CliRenderer;
454
+ /** The underlying root instance */
455
+ readonly root: Root;
456
+ }
457
+ /**
458
+ * Create a high-level CLI instance for terminal rendering.
459
+ *
460
+ * This is the recommended entry point for building terminal UIs with @mdxui/terminal.
461
+ * It combines `createCliRenderer` and `createRoot` into a single, easy-to-use API.
462
+ *
463
+ * @param options - Optional configuration options
464
+ * @returns Promise resolving to a CLI instance with render, clear, and destroy methods
465
+ *
466
+ * @example
467
+ * ```tsx
468
+ * import { CLI, Box, Text } from '@mdxui/terminal'
469
+ *
470
+ * async function main() {
471
+ * const cli = await CLI()
472
+ * cli.render(
473
+ * <Box border="single">
474
+ * <Text color="cyan">Hello Terminal!</Text>
475
+ * </Box>
476
+ * )
477
+ * }
478
+ *
479
+ * main()
480
+ * ```
481
+ *
482
+ * @example
483
+ * ```tsx
484
+ * // With custom options
485
+ * const cli = await CLI({
486
+ * useAlternateScreen: true,
487
+ * useMouse: true,
488
+ * exitOnCtrlC: true,
489
+ * })
490
+ * ```
491
+ */
492
+ declare function CLI(options?: CLIOptions): Promise<CLIInstance>;
493
+ /**
494
+ * Get the current terminal dimensions, with automatic updates on resize.
495
+ *
496
+ * Returns `{ width, height }` representing the terminal's column and row count.
497
+ *
498
+ * **Behavior by environment:**
499
+ * - **Node.js TTY**: Uses `process.stdout.columns/rows` and subscribes to resize events
500
+ * - **Browser/Non-TTY**: Falls back to 80x24 defaults
501
+ *
502
+ * @returns Current terminal width and height in columns/rows
503
+ *
504
+ * @example
505
+ * ```tsx
506
+ * function MyComponent() {
507
+ * const { width, height } = useTerminalSize()
508
+ * return <Text>Terminal: {width}x{height}</Text>
509
+ * }
510
+ * ```
511
+ */
512
+ declare function useTerminalSize(): {
513
+ width: number;
514
+ height: number;
515
+ };
516
+ /**
517
+ * Access terminal context and capabilities.
518
+ *
519
+ * Provides terminal dimensions plus color support detection and raw mode status.
520
+ * Uses @opentui/react for dimensions and our color-support module for capabilities.
521
+ *
522
+ * @returns Terminal state including dimensions, color support level, and raw mode
523
+ *
524
+ * @example
525
+ * ```tsx
526
+ * function StatusBar() {
527
+ * const { width, height, colorSupport } = useTerminal()
528
+ * return (
529
+ * <Box>
530
+ * <Text>Size: {width}x{height}</Text>
531
+ * <Text>Colors: {colorSupport}</Text>
532
+ * </Box>
533
+ * )
534
+ * }
535
+ * ```
536
+ */
537
+ declare function useTerminal(): {
538
+ width: number;
539
+ height: number;
540
+ colorSupport: 'none' | 'basic' | '256' | 'truecolor';
541
+ isRaw: boolean;
542
+ };
543
+ interface ThemeContextValue {
544
+ theme: 'light' | 'dark';
545
+ setTheme: (theme: 'light' | 'dark') => void;
546
+ colors: Record<string, string>;
547
+ }
548
+ /**
549
+ * Access current theme and colors
550
+ */
551
+ declare function useTheme(): ThemeContextValue;
552
+ interface TerminalProviderProps {
553
+ children?: ReactNode;
554
+ }
555
+ /**
556
+ * Terminal context provider - wraps app with terminal capabilities
557
+ */
558
+ declare function TerminalProvider(props: TerminalProviderProps): React__default.ReactElement;
559
+ interface ThemeProviderProps {
560
+ children?: ReactNode;
561
+ theme?: 'light' | 'dark';
562
+ }
563
+ /**
564
+ * Theme provider - provides color scheme to components
565
+ */
566
+ declare function ThemeProvider(props: ThemeProviderProps): React__default.ReactElement;
567
+ interface TerminalAppProps {
568
+ children: React__default.ReactNode;
569
+ /** Show status bar at bottom */
570
+ statusBar?: React__default.ReactNode;
571
+ /** Handle quit (Ctrl+C, q) */
572
+ onQuit?: () => void;
573
+ }
574
+ /**
575
+ * Terminal app shell with standard layout
576
+ */
577
+ declare function TerminalApp(props: TerminalAppProps): React__default.ReactElement;
578
+
579
+ export { CLI, type CLIInstance, type CLIOptions, type CliRenderer, type CliRendererConfig, ParseError, type Root, TerminalApp, type TerminalAppProps, TerminalProvider, type TerminalProviderProps, ThemeProvider, type ThemeProviderProps, UINode, compileJSX, compileJSXDeep, createCliRenderer, createRoot, parseUINode, parseUINodeFromJSON, useTerminal, useTerminalSize, useTheme };