//
// 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,
};