// // Copyright 2025 DXOS.org // import { JSONPath } from 'jsonpath-plus'; import React, { type PropsWithChildren, forwardRef, useCallback, useMemo, useState } from 'react'; import * as Field from '@dxos/react-ui/Field'; import * as Input from '@dxos/react-ui/Input'; import * as ScrollArea from '@dxos/react-ui/ScrollArea'; import * as Util from '@dxos/react-ui/Util'; import { type ComposableProps } from '@dxos/ui-types'; import { JsonHighlighter, type JsonReplacer } from '../JsonHighlighter/index.ts'; import { SyntaxHighlighter } from '../SyntaxHighlighter/index.ts'; import { SyntaxProvider, useSyntaxContext } from './SyntaxContext.ts'; // // Context // export type SyntaxContextValue = { mode: 'text' | 'json'; // Text mode. source?: string; language?: string; // JSON mode. data?: any; filteredData?: any; filterText: string; setFilterText: (text: string) => void; filterError: Error | null; replacer?: JsonReplacer; // Expansion depth (JSON mode); consumed by a `getReplacer` factory, edited via `Syntax.Depth`. depth: number; setDepth: (depth: number) => void; }; // // Root // const SYNTAX_ROOT_NAME = 'Syntax.Root'; type SyntaxRootProps = PropsWithChildren<{ // Text mode. language?: string; source?: string; // JSON mode (presence of the `data` prop selects JSON mode; `undefined` is still JSON). data?: any; /** * `JSON.stringify` replacer applied to `data`. Use the function form to follow domain * references (e.g. ECHO refs) by returning a transformed value at the root call. Keeps * this package free of any domain-specific knowledge. */ replacer?: JsonReplacer; /** * Depth-parametrized replacer, re-evaluated as the `Syntax.Depth` control changes. Takes * precedence over `replacer`. The consumer owns any domain knowledge (e.g. how depth maps to * ref resolution), so this package stays domain-free. */ getReplacer?: (depth: number) => JsonReplacer | undefined; /** Initial expansion depth for `Syntax.Depth` / `getReplacer`. */ defaultDepth?: number; /** Notified when the depth changes (via `Syntax.Depth`). */ onDepthChange?: (depth: number) => void; }>; /** * Headless context provider. Selects JSON mode when the `data` prop is passed at all — even * `data={undefined}` — so loading states render an empty JSON view rather than flipping to * text mode (which would trip `Syntax.Filter`'s JSON-only guard). Mode is chosen by prop * presence, not value. */ const SyntaxRoot = (props: SyntaxRootProps) => { const { children, language, source, replacer, getReplacer, defaultDepth = 0, onDepthChange } = props; const isJson = 'data' in props; const data = props.data; const [filterText, setFilterText] = useState(''); const [depth, setDepthState] = useState(defaultDepth); const setDepth = useCallback( (next: number) => { setDepthState(next); onDepthChange?.(next); }, [onDepthChange], ); // `getReplacer` (depth-parametrized) takes precedence over the static `replacer`. const effectiveReplacer = useMemo( () => (getReplacer ? getReplacer(depth) : replacer), [getReplacer, replacer, depth], ); const { filteredData, filterError } = useMemo<{ filteredData: any; filterError: Error | null }>(() => { if (!isJson || !filterText.trim().length) { return { filteredData: data, filterError: null }; } try { return { filteredData: JSONPath({ path: filterText, json: data }), filterError: null }; } catch (err) { return { filteredData: data, filterError: err as Error }; } }, [isJson, data, filterText]); return ( {children} ); }; SyntaxRoot.displayName = SYNTAX_ROOT_NAME; // // Content // const SYNTAX_CONTENT_NAME = 'Syntax.Content'; type SyntaxContentProps = ComposableProps; /** Flex-column layout container for composite parts; unpadded so the host panel owns the frame. */ const SyntaxContent = Util.composable(({ children, ...props }, forwardedRef) => { return (
{children}
); }); SyntaxContent.displayName = SYNTAX_CONTENT_NAME; // // Filter // const SYNTAX_FILTER_NAME = 'Syntax.Filter'; type SyntaxFilterProps = ComposableProps<{ placeholder?: string; }>; /** JSONPath filter input. Only meaningful when `Syntax.Root` is in JSON mode. */ const SyntaxFilter = forwardRef( ({ classNames, placeholder = 'JSONPath (e.g., $.graph.nodes)' }, forwardedRef) => { const { mode, filterText, setFilterText, filterError } = useSyntaxContext(SYNTAX_FILTER_NAME); if (mode !== 'json') { throw new Error(`\`${SYNTAX_FILTER_NAME}\` requires \`Syntax.Root\` to be in JSON mode (pass \`data\`).`); } return ( setFilterText(event.target.value)} ref={forwardedRef} /> ); }, ); SyntaxFilter.displayName = SYNTAX_FILTER_NAME; // // Depth // const SYNTAX_DEPTH_NAME = 'Syntax.Depth'; type SyntaxDepthProps = ComposableProps; /** * Numeric expansion-depth control bound to `Syntax.Root`'s depth state. Meaningful when the Root is * given a `getReplacer` that consumes depth (e.g. to resolve references N levels deep). */ const SyntaxDepth = forwardRef(({ classNames }, forwardedRef) => { const { depth, setDepth } = useSyntaxContext(SYNTAX_DEPTH_NAME); return ( setDepth(Math.max(0, valueAsNumber || 0))} ref={forwardedRef} /> ); }); SyntaxDepth.displayName = SYNTAX_DEPTH_NAME; // // Viewport // const SYNTAX_VIEWPORT_NAME = 'Syntax.Viewport'; type SyntaxViewportProps = ComposableProps; /** Optional scroll wrapper. Compose around `Syntax.Code` to make it scrollable. */ const SyntaxViewport = Util.composable(({ children, ...props }, forwardedRef) => { return ( {children} ); }); SyntaxViewport.displayName = SYNTAX_VIEWPORT_NAME; // // Code // const SYNTAX_CODE_NAME = 'Syntax.Code'; type SyntaxCodeProps = ComposableProps<{ testId?: string; }>; /** Highlighted code leaf, unscrolled: `Syntax.Viewport` owns the scrolling. Reads source/data from `Syntax.Root`. */ const SyntaxCode = Util.composable(({ testId, ...props }, forwardedRef) => { const merged = Util.composableProps(props, { classNames: 'text-sm' }); const context = useSyntaxContext(SYNTAX_CODE_NAME); if (context.mode === 'json') { return ( ); } return ( {context.source ?? ''} ); }); SyntaxCode.displayName = SYNTAX_CODE_NAME; // // Syntax // export const Syntax = { Root: SyntaxRoot, Content: SyntaxContent, Filter: SyntaxFilter, Depth: SyntaxDepth, Viewport: SyntaxViewport, Code: SyntaxCode, }; export type { SyntaxCodeProps, SyntaxContentProps, SyntaxDepthProps, SyntaxFilterProps, SyntaxRootProps, SyntaxViewportProps, };