@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.
- package/README.md +571 -0
- package/dist/ansi-css-Sk5mWtdK.d.ts +119 -0
- package/dist/ansi-css-V6JIHGsM.d.ts +119 -0
- package/dist/ansi-css-_3eSEU9d.d.ts +119 -0
- package/dist/chunk-3EFDH7PK.js +5235 -0
- package/dist/chunk-3RG5ZIWI.js +10 -0
- package/dist/chunk-3X5IR6WE.js +884 -0
- package/dist/chunk-4FV5ZDCE.js +5236 -0
- package/dist/chunk-4OVMSF2J.js +243 -0
- package/dist/chunk-63FEETIS.js +4048 -0
- package/dist/chunk-B43KP7XJ.js +884 -0
- package/dist/chunk-BMTJXWUV.js +655 -0
- package/dist/chunk-C3SVH4N7.js +882 -0
- package/dist/chunk-EVWR7Y47.js +874 -0
- package/dist/chunk-F6A5VWUC.js +1285 -0
- package/dist/chunk-FD7KW7GE.js +882 -0
- package/dist/chunk-GBQ6UD6I.js +655 -0
- package/dist/chunk-GMDD3M6U.js +5227 -0
- package/dist/chunk-JBHRXOXM.js +1058 -0
- package/dist/chunk-JFOO3EYO.js +1182 -0
- package/dist/chunk-JQ5H3WXL.js +1291 -0
- package/dist/chunk-JQD5NASE.js +234 -0
- package/dist/chunk-KRHJP5R7.js +592 -0
- package/dist/chunk-KWF6WVJE.js +962 -0
- package/dist/chunk-LHYQVN3H.js +1038 -0
- package/dist/chunk-M3TLQLGC.js +1032 -0
- package/dist/chunk-MVW4Q5OP.js +240 -0
- package/dist/chunk-NXCZSWLU.js +1294 -0
- package/dist/chunk-O25TNRO6.js +607 -0
- package/dist/chunk-PNECDA2I.js +884 -0
- package/dist/chunk-QIHWRLJR.js +962 -0
- package/dist/chunk-QW5YMQ7K.js +882 -0
- package/dist/chunk-R5U7XKVJ.js +16 -0
- package/dist/chunk-RP2MVQLR.js +962 -0
- package/dist/chunk-TP6RXGXA.js +1087 -0
- package/dist/chunk-TQQSTITZ.js +655 -0
- package/dist/chunk-X24GWXQV.js +1281 -0
- package/dist/components/index.d.ts +802 -0
- package/dist/components/index.js +149 -0
- package/dist/data/index.d.ts +2554 -0
- package/dist/data/index.js +51 -0
- package/dist/forms/index.d.ts +1596 -0
- package/dist/forms/index.js +464 -0
- package/dist/index-CQRFZntR.d.ts +867 -0
- package/dist/index.d.ts +579 -0
- package/dist/index.js +786 -0
- package/dist/interactive-D0JkWosD.d.ts +217 -0
- package/dist/keyboard/index.d.ts +2 -0
- package/dist/keyboard/index.js +43 -0
- package/dist/renderers/index.d.ts +546 -0
- package/dist/renderers/index.js +2157 -0
- package/dist/storybook/index.d.ts +396 -0
- package/dist/storybook/index.js +641 -0
- package/dist/theme/index.d.ts +1339 -0
- package/dist/theme/index.js +123 -0
- package/dist/types-Bxu5PAgA.d.ts +710 -0
- package/dist/types-CIlop5Ji.d.ts +701 -0
- package/dist/types-Ca8p_p5X.d.ts +710 -0
- package/package.json +90 -0
- package/src/__tests__/components/data/card.test.ts +458 -0
- package/src/__tests__/components/data/list.test.ts +473 -0
- package/src/__tests__/components/data/metrics.test.ts +541 -0
- package/src/__tests__/components/data/table.test.ts +448 -0
- package/src/__tests__/components/input/field.test.ts +555 -0
- package/src/__tests__/components/input/form.test.ts +870 -0
- package/src/__tests__/components/input/search.test.ts +1238 -0
- package/src/__tests__/components/input/select.test.ts +658 -0
- package/src/__tests__/components/navigation/breadcrumb.test.ts +923 -0
- package/src/__tests__/components/navigation/command-palette.test.ts +1095 -0
- package/src/__tests__/components/navigation/sidebar.test.ts +1018 -0
- package/src/__tests__/components/navigation/tabs.test.ts +995 -0
- package/src/__tests__/components.test.tsx +1197 -0
- package/src/__tests__/core/compiler.test.ts +986 -0
- package/src/__tests__/core/parser.test.ts +785 -0
- package/src/__tests__/core/tier-switcher.test.ts +1103 -0
- package/src/__tests__/core/types.test.ts +1398 -0
- package/src/__tests__/data/collections.test.ts +1337 -0
- package/src/__tests__/data/db.test.ts +1265 -0
- package/src/__tests__/data/reactive.test.ts +1010 -0
- package/src/__tests__/data/sync.test.ts +1614 -0
- package/src/__tests__/errors.test.ts +660 -0
- package/src/__tests__/forms/integration.test.ts +444 -0
- package/src/__tests__/integration.test.ts +905 -0
- package/src/__tests__/keyboard.test.ts +1791 -0
- package/src/__tests__/renderer.test.ts +489 -0
- package/src/__tests__/renderers/ansi-css.test.ts +948 -0
- package/src/__tests__/renderers/ansi.test.ts +1366 -0
- package/src/__tests__/renderers/ascii.test.ts +1360 -0
- package/src/__tests__/renderers/interactive.test.ts +2353 -0
- package/src/__tests__/renderers/markdown.test.ts +1483 -0
- package/src/__tests__/renderers/text.test.ts +1369 -0
- package/src/__tests__/renderers/unicode.test.ts +1307 -0
- package/src/__tests__/theme.test.ts +639 -0
- package/src/__tests__/utils/assertions.ts +685 -0
- package/src/__tests__/utils/index.ts +115 -0
- package/src/__tests__/utils/test-renderer.ts +381 -0
- package/src/__tests__/utils/utils.test.ts +560 -0
- package/src/components/containers/card.ts +56 -0
- package/src/components/containers/dialog.ts +53 -0
- package/src/components/containers/index.ts +9 -0
- package/src/components/containers/panel.ts +59 -0
- package/src/components/feedback/badge.ts +40 -0
- package/src/components/feedback/index.ts +8 -0
- package/src/components/feedback/spinner.ts +23 -0
- package/src/components/helpers.ts +81 -0
- package/src/components/index.ts +153 -0
- package/src/components/layout/breadcrumb.ts +31 -0
- package/src/components/layout/index.ts +10 -0
- package/src/components/layout/list.ts +29 -0
- package/src/components/layout/sidebar.ts +79 -0
- package/src/components/layout/table.ts +62 -0
- package/src/components/primitives/box.ts +95 -0
- package/src/components/primitives/button.ts +54 -0
- package/src/components/primitives/index.ts +11 -0
- package/src/components/primitives/input.ts +88 -0
- package/src/components/primitives/select.ts +97 -0
- package/src/components/primitives/text.ts +60 -0
- package/src/components/render.ts +155 -0
- package/src/components/templates/app.ts +43 -0
- package/src/components/templates/index.ts +8 -0
- package/src/components/templates/site.ts +54 -0
- package/src/components/types.ts +777 -0
- package/src/core/compiler.ts +718 -0
- package/src/core/parser.ts +127 -0
- package/src/core/tier-switcher.ts +607 -0
- package/src/core/types.ts +672 -0
- package/src/data/collection.ts +316 -0
- package/src/data/collections.ts +50 -0
- package/src/data/context.tsx +174 -0
- package/src/data/db.ts +127 -0
- package/src/data/hooks.ts +532 -0
- package/src/data/index.ts +138 -0
- package/src/data/reactive.ts +1225 -0
- package/src/data/saas-collections.ts +375 -0
- package/src/data/sync.ts +1213 -0
- package/src/data/types.ts +660 -0
- package/src/forms/converters.ts +512 -0
- package/src/forms/index.ts +133 -0
- package/src/forms/schemas.ts +403 -0
- package/src/forms/types.ts +476 -0
- package/src/index.ts +542 -0
- package/src/keyboard/focus.ts +748 -0
- package/src/keyboard/index.ts +96 -0
- package/src/keyboard/integration.ts +371 -0
- package/src/keyboard/manager.ts +377 -0
- package/src/keyboard/presets.ts +90 -0
- package/src/renderers/ansi-css.ts +576 -0
- package/src/renderers/ansi.ts +802 -0
- package/src/renderers/ascii.ts +680 -0
- package/src/renderers/breadcrumb.ts +480 -0
- package/src/renderers/command-palette.ts +802 -0
- package/src/renderers/components/field.ts +210 -0
- package/src/renderers/components/form.ts +327 -0
- package/src/renderers/components/index.ts +21 -0
- package/src/renderers/components/search.ts +449 -0
- package/src/renderers/components/select.ts +222 -0
- package/src/renderers/index.ts +101 -0
- package/src/renderers/interactive/component-handlers.ts +622 -0
- package/src/renderers/interactive/cursor-manager.ts +147 -0
- package/src/renderers/interactive/focus-manager.ts +279 -0
- package/src/renderers/interactive/index.ts +661 -0
- package/src/renderers/interactive/input-handler.ts +164 -0
- package/src/renderers/interactive/keyboard-handler.ts +212 -0
- package/src/renderers/interactive/mouse-handler.ts +167 -0
- package/src/renderers/interactive/state-manager.ts +109 -0
- package/src/renderers/interactive/types.ts +338 -0
- package/src/renderers/interactive-string.ts +299 -0
- package/src/renderers/interactive.ts +59 -0
- package/src/renderers/markdown.ts +950 -0
- package/src/renderers/sidebar.ts +549 -0
- package/src/renderers/tabs.ts +682 -0
- package/src/renderers/text.ts +791 -0
- package/src/renderers/unicode.ts +917 -0
- package/src/renderers/utils.ts +942 -0
- package/src/router/adapters.ts +383 -0
- package/src/router/types.ts +140 -0
- package/src/router/utils.ts +452 -0
- package/src/schemas.ts +205 -0
- package/src/storybook/index.ts +91 -0
- package/src/storybook/interactive-decorator.tsx +659 -0
- package/src/storybook/keyboard-simulator.ts +501 -0
- package/src/theme/ansi-codes.ts +80 -0
- package/src/theme/box-drawing.ts +132 -0
- package/src/theme/color-convert.ts +254 -0
- package/src/theme/color-support.ts +321 -0
- package/src/theme/index.ts +134 -0
- package/src/theme/strip-ansi.ts +50 -0
- package/src/theme/tailwind-map.ts +469 -0
- package/src/theme/text-styles.ts +206 -0
- package/src/theme/theme-system.ts +568 -0
- package/src/types.ts +103 -0
package/dist/index.d.ts
ADDED
|
@@ -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 };
|