@surrealdb/ui 1.2.3 → 1.2.4

package/dist/ui.d.ts

@@ -294,12 +294,13 @@ export declare interface CodeRendererProps {
     language: string;
 }
 
+/** Map of lower-cased fenced-code info string to renderer component. */
+declare type CodeRenderers = Record<string, CodeRenderer>;
+
 export declare type ColorScheme = keyof ThemeConfig;
 
 declare type ColorScheme_2 = keyof ThemeConfig_2;
 
-declare type CommandAction = (view: EditorView, range: SlashCommandRange) => void;
-
 declare interface CommentNode {
     type: "Comment";
     text: string;
@@ -354,10 +355,16 @@ export declare function createStyleHighlighter(theme: ThemeConfig_2, colorScheme
  */
 export declare const customHistoryKeymap: readonly KeyBinding[];
 
-/** Default fenced-code renderers keyed by lower-cased info string (e.g. `mermaid`). */
-export declare const DEFAULT_CODE_RENDERERS: Record<string, CodeRenderer>;
+/**
+ * Default fenced-code renderers keyed by lower-cased info string (e.g. `mermaid`).
+ */
+export declare const DEFAULT_CODE_RENDERERS: CodeRenderers;
 
-/** Default JSX components for `<PascalCase />` tags in markdown (e.g. `<Since />`, `<Tabs>`). */
+/**
+ * Default JSX components for `<PascalCase />` tags in markdown (e.g. `<Since />`,
+ * `<Tabs>`). Inline components register as a bare `ComponentType`; block
+ * components use the explicit `{ component, block: true }` form.
+ */
 export declare const DEFAULT_COMPONENTS: MarkdownComponents;
 
 /** Default mode used when no mode is provided. */
@@ -406,17 +413,58 @@ export declare interface EditorController {
 export declare const editorExtensions: () => Extension;
 
 export declare interface EditorOptions {
+    /**
+     * The state fields to use for the editor.
+     */
     fields?: StateFields;
+    /**
+     * The theme to use for the editor.
+     * @default VIVID_THEME
+     */
     theme?: ThemeConfig;
+    /**
+     * The initial document to use for the editor.
+     * Do not set this if you are using the `state` prop.
+     */
     document?: string;
+    /**
+     * The initial state to use for the editor.
+     * Do not set this if you are using the `document` prop.
+     */
     state?: EditorStateSnapshot;
+    /**
+     * Whether the editor is read-only.
+     * @default false
+     */
     readOnly?: boolean;
+    /**
+     * Additional extensions to add to the editor.
+     */
     extensions?: Extension;
+    /**
+     * The language to use for the editor.
+     */
     language?: Language;
+    /**
+     * Whether to show line numbers.
+     * @default false
+     */
     lineNumbers?: boolean;
+    /**
+     * Callback to call when the editor is mounted.
+     */
     onMounted?: (editor: EditorView) => void;
+    /**
+     * Callback to call when the document changes.
+     */
     onChangeDocument?: (document: string) => void;
+    /**
+     * Callback to call when the selection changes.
+     */
     onChangeSelection?: (selection: EditorSelection) => void;
+    /**
+     * Callback to call when the state changes.
+     */
     onChangeState?: (snapshot: EditorStateSnapshot) => void;
 }
 
@@ -427,6 +475,9 @@ export declare type EditorStateSnapshot = Record<string, unknown>;
  */
 export declare function editorTheme(theme: ThemeConfig_2, colorScheme: MantineColorScheme): Extension;
 
+/** Estimated reading time in minutes (minimum 1). */
+export declare function estimateMarkdownReadTimeMinutes(markdown: string): number;
+
 export declare function extractCdnId(query: string): string | undefined;
 
 export declare interface ExtractedCode {
@@ -454,6 +505,9 @@ export declare function extractTest(input: string): ExtractedCode;
 /** Case-insensitive filter over command titles and keywords. */
 export declare function filterSlashCommands(commands: readonly SlashCommand[], query: string): SlashCommand[];
 
+/** Human-readable reading time label, e.g. `5 min read`. */
+export declare function formatMarkdownReadTime(markdown: string): string;
+
 /**
  * Generate a 24-character hex string suitable for use as a
  * stable block identifier. Uses `crypto.getRandomValues` for
@@ -461,7 +515,7 @@ export declare function filterSlashCommands(commands: readonly SlashCommand[], q
  */
 export declare function generateRandomId(): string;
 
-export declare function getCDNImageURL(imageId: string | undefined, width?: number, quality?: number): string | undefined;
+export declare function getCDNImageURL(imageId: string | undefined, width?: number, quality?: number, extension?: string): string | undefined;
 
 export declare function getCDNVideoURL(videoId: string | undefined, format?: "mp4" | "webm" | "mov", controls?: boolean): string | undefined;
 
@@ -901,30 +955,32 @@ export declare type Identified<T = object, I = string> = T & {
     id: I;
 };
 
-/** Normalised image descriptor for viewer renderers and `onImage` callbacks. */
-export declare interface ImageDescriptor {
-    src: string;
-    alt?: string;
-    title?: string;
-    darkSrc?: string;
-}
+/**
+ * Build a `run` that inserts a block-level JSX tag on its own line with blank lines before when needed.
+ */
+export declare function insertBlock(block: string): SlashCommandAction;
 
 /**
  * Build a `run` that inserts a callout of the given kind.
  */
-export declare function insertCallout(kind: CalloutKind): CommandAction;
+export declare function insertCallout(kind: CalloutKind): SlashCommandAction;
 
 /**
- * Build a `run` that inserts the given markdown and positions the caret at the end of the inserted text,
- * or at the given offset.
+ * Build a `run` that inserts the given markdown and positions the caret.
+ * Use `$` in the insert string to mark the initial caret position.
  */
-export declare function insertMarkdown(insert: string, caretOffset?: number): CommandAction;
+export declare function insertMarkdown(markdown: string): SlashCommandAction;
 
 export declare function isCDNId(query: string): boolean;
 
 /** True when the registered component declares `block: true`. */
 export declare function isMarkdownComponentBlock(components: MarkdownComponents | undefined, name: string): boolean;
 
+/**
+ * Returns whether the given URL points at a recognised video container.
+ */
+export declare function isVideoUrl(src: string): boolean;
+
 /** How `<Component />` tags are handled. */
 export declare type JsxMode = "render" | "throw" | "graceful" | "omit";
 
@@ -934,7 +990,36 @@ export declare interface LabelProps extends Omit<BadgeProps, "children"> {
     label: string;
 }
 
-declare type Language = "csharp" | "rust" | "javascript" | "typescript" | "surrealql" | "json" | "yaml" | "java" | "go" | "python" | "html" | "cli" | "php" | "markdown" | "syntax";
+declare type Language = "csharp" | "rust" | "javascript" | "typescript" | "surrealql" | "json" | "yaml" | "java" | "go" | "python" | "html" | "bash" | "cli" | "php" | "markdown" | "syntax";
+
+/**
+ * A CodeMirror extension that provides support for live markdown editing.
+ */
+export declare function liveMarkdownEditor(opts: LiveMarkdownEditorOptions): Extension;
+
+/**
+ * Options to configure the behaviour of the live markdown editor
+ */
+export declare interface LiveMarkdownEditorOptions {
+    /** Required widget store, typically returned by `useMarkdownWidgetStore()`. */
+    widgetStore: WidgetStore;
+    /** Enable automatic table formatting on edit. */
+    withTableFormatter?: boolean;
+    /** Custom code renderers for fenced code blocks. */
+    codeRenderers?: CodeRenderers;
+    /** Whether to install the markdown language alongside the live preview. */
+    includeLanguage?: boolean;
+    /** Optional language resolver for embedded fenced code blocks. */
+    resolveCodeLanguage?: (info: string) => Language_2 | undefined;
+    /** Custom JSX components to expose in the editor. */
+    components?: MarkdownComponents;
+    /** How unsupported JSX is handled in preview mode. */
+    jsxMode?: JsxMode;
+    /** Rewrite image/video sources before preview render. */
+    onResolveMedia?: (node: MediaDescriptor) => MediaDescriptor;
+    /** Optional slash command store, typically returned by `useMarkdownSlashStore()`. */
+    slashStore?: SlashStore;
+}
 
 /**
  * The Mantine theme configurtation
@@ -949,6 +1034,15 @@ export declare const MANTINE_THEME: MantineThemeOverride;
 export declare interface MarkdownComponentConfig {
     component: ComponentType<any>;
     block?: boolean;
+    /**
+     * Whether source newlines inside the component's children are preserved as
+     * `<br />` (and the resulting inline runs wrapped in `<p>`). Defaults to
+     * `true`, matching prose components that want line breaks honoured. Set to
+     * `false` for layout components (e.g. a grid/columns wrapper) where the
+     * whitespace between child blocks would otherwise inject stray
+     * `<p><br /></p>` nodes and break the layout.
+     */
+    preserveNewlines?: boolean;
 }
 
 /** A registered component is either a bare React component (inline) or a config object. */
@@ -957,6 +1051,26 @@ export declare type MarkdownComponentDef = ComponentType<any> | MarkdownComponen
 /** Map of PascalCase JSX tag names to viewer/editor component registrations. */
 export declare type MarkdownComponents = Record<string, MarkdownComponentDef>;
 
+/**
+ * Wraps a run of rendered markdown so it gets the same block spacing / vertical
+ * rhythm as top-level {@link MarkdownViewer} content.
+ *
+ * ```tsx
+ * function ElementWithContent({ children }) {
+ *     return <MarkdownContent>{children}</MarkdownContent>;
+ * }
+ * ```
+ *
+ * **Note**: This component is only used in the Markdown viewer. Markdown editors do not
+ * support JSX sub-content.
+ */
+export declare const MarkdownContent: FC<MarkdownContentProps>;
+
+export declare interface MarkdownContentProps extends BoxProps {
+    /** Rendered markdown nodes (e.g. the `children` a custom JSX component receives). */
+    children?: ReactNode;
+}
+
 /**
  * Rendering mode of the markdown editor.
  *
@@ -967,43 +1081,62 @@ export declare type MarkdownComponents = Record<string, MarkdownComponentDef>;
 export declare type MarkdownEditMode = "source" | "preview";
 
 /**
- * High-level Markdown editor primitive that wires together the
- * `CodeEditor` shell, the live preview extension, the widget store and
- * the React portal host.
+ * High-level self contained live markdown editor component.
+ *
+ * Wires together the `CodeEditor` shell, the live preview extension, the widget store and the React portal host.
  *
  * See {@link MarkdownViewer} for a Markdown viewer equivalent.
  */
 export declare const MarkdownEditor: FC<MarkdownEditorProps>;
 
-export declare interface MarkdownEditorProps extends Omit<EditorOptions, "language" | "extensions">, Omit<BoxProps, "onChange"> {
-    /** `source` or `preview` (live preview). Defaults to `preview`. */
+export declare interface MarkdownEditorProps extends Omit<EditorOptions, "language">, Omit<BoxProps, "onChange"> {
+    /**
+     * The display mode of the editor. Defaults to `preview`.
+     */
     mode?: MarkdownEditMode;
-    /** Additional CodeMirror extensions to layer on top of the live preview. */
-    extensions?: Extension;
-    /** GFM table preview widgets in preview mode. Defaults to `true`. */
-    tables?: boolean;
     /**
-     * Auto-format GFM table source while editing: align columns and pad cells
-     * with trailing spaces. Defaults to `false`.
+     * Custom JSX components to expose in the editor.
      */
-    withTableFormatter?: boolean;
-    /** React components for `<PascalCase />` tags (preview widgets). */
     components?: MarkdownComponents;
-    /** How unsupported JSX is handled in preview. Default `render` (uses {@link DEFAULT_COMPONENTS}). */
+    /**
+     * How unsupported JSX is handled in preview mode.
+     * @default `render`
+     */
     jsxMode?: JsxMode;
-    /** Auto-focus the editor on mount. */
+    /**
+     * Whether to auto-focus the editor on mount.
+     * @default false
+     */
     autoFocus?: boolean;
+    /**
+     * The placeholder text to display in the editor when it is empty.
+     */
+    placeholder?: string;
     /**
      * Custom per-language renderers for fenced code blocks. Keys are the
-     * lower-cased fenced-code info string (e.g. `mermaid`). When the block
-     * is inactive, a matching renderer fully replaces the source. Defaults
-     * to `{ mermaid: MermaidCodeRenderer }`; pass `{}` to disable.
+     * lower-cased fenced-code info string (e.g. `mermaid`).
+     * @default `{ mermaid: MermaidCodeRenderer }`
+     */
+    codeRenderers?: CodeRenderers;
+    /**
+     * Whether to enable the slash command palette.
+     * @default true
      */
-    codeRenderers?: Record<string, CodeRenderer>;
-    /** Enable the slash command palette. Defaults to `true`. */
     slashCommands?: boolean;
-    /** Override the slash command set. Defaults to {@link DEFAULT_SLASH_COMMANDS}. */
+    /**
+     * Override the slash command set.
+     * @default {@link DEFAULT_SLASH_COMMANDS}
+     */
     commands?: readonly SlashCommand[];
+    /**
+     * Auto-format GFM table source while editing.
+     * @default false
+     */
+    withTableFormatter?: boolean;
+    /**
+     * Rewrite image/video sources before preview render.
+     */
+    onResolveMedia?: (node: MediaDescriptor) => MediaDescriptor;
 }
 
 /**
@@ -1020,47 +1153,6 @@ export declare function markdownEditorReady(): Extension;
  */
 export declare const markdownEditorReadyField: StateField<boolean>;
 
-/**
- * Live preview stack: language (optional), mode field, folding, decorations, theme.
- */
-export declare function markdownLivePreview(opts: MarkdownLivePreviewOptions): Extension;
-
-/** Options for {@link markdownLivePreview}. */
-export declare interface MarkdownLivePreviewOptions {
-    /** GFM table preview widgets in preview mode. Defaults to `true`. */
-    tables?: boolean;
-    /**
-     * Auto-format GFM table source on edit: align columns, pad cells with
-     * trailing spaces, and normalise the delimiter row. Defaults to `false`.
-     */
-    withTableFormatter?: boolean;
-    /**
-     * Per-language renderers used when a fenced code block is inactive (preview
-     * unfocused / caret outside the block). Keys are the lower-cased fenced-code
-     * info string (e.g. `mermaid`). Defaults to `{}`.
-     */
-    codeRenderers?: Record<string, CodeRenderer>;
-    /** Required widget store, typically returned by `useMarkdownWidgetStore()`. */
-    widgetStore: WidgetStore;
-    /** Whether to install the markdown language alongside the live preview. */
-    includeLanguage?: boolean;
-    /**
-     * Optional language resolver for embedded fenced code blocks.
-     */
-    resolveCodeLanguage?: (info: string) => Language_2 | undefined;
-    /** JSX/HTML preview widgets (viewer parity). Omit to leave raw source in preview. */
-    components?: MarkdownComponents;
-    jsxMode?: JsxMode;
-    /**
-     * Slash command palette. Pass a store (from `useSlashStore()`) to enable
-     * the slash (`/`) command menu. Render `<SlashCommandMenu>` with the
-     * same store. Omit to disable.
-     */
-    slash?: {
-        store: SlashStore;
-    };
-}
-
 /**
  * State field tracking the current {@link MarkdownEditMode}.
  */
@@ -1108,41 +1200,67 @@ export declare function markdownSourceFromString(source: string): MarkdownSource
 /**
  * Editor base theme for the markdown live preview. Cursor / scroller rules and
  * editor-only chrome; shared surface styles live in `markdown.module.scss`.
+ *
+ * Line wrapping is enabled so long lines (prose and fenced code alike) wrap to
+ * the editor width instead of growing the content box and scrolling the whole
+ * editor horizontally.
  */
 export declare function markdownTheme(): Extension;
 
+/** Strip common Markdown syntax to approximate plain text for word counting. */
+export declare function markdownToPlainText(markdown: string): string;
+
 /**
- * High-level Markdown viewer primitive that renders a Markdown structure
- * as a React tree.
+ * High-level self contained live markdown viewer component.
+ *
+ * Renders a Markdown structure as a React tree.
  *
  * See {@link MarkdownEditor} for a Markdown editor equivalent.
  */
 export declare const MarkdownViewer: FC<MarkdownViewerProps>;
 
 export declare interface MarkdownViewerProps extends BoxProps {
-    /** Markdown source string. Ignored when `tree` is provided. */
+    /**
+     * Markdown source string. Ignored when `tree` is provided.
+     */
     content?: string;
-    /** Pre-parsed tree and markdown source. */
+    /**
+     * Pre-parsed tree and markdown source.
+     */
     tree?: MarkdownViewerTreeInput;
-    /** Collapse consecutive blank lines into a single line break. Defaults to `true`. */
-    collapseBlankLines?: boolean;
-    /** Override built-in element renderers. */
+    /**
+     * Override built-in element renderers.
+     */
     renderers?: MarkdownViewerRenderers;
-    /** Rewrite image URLs before render (e.g. CDN resolution). */
-    onImage?: (node: ImageDescriptor) => ImageDescriptor;
-    /** Add slug IDs and hover anchor links on headings. */
-    autoLink?: boolean;
     /**
      * Custom per-language renderers for fenced code blocks. Keys are the
-     * lower-cased fenced-code info string (e.g. `mermaid`). When the block
-     * is inactive, a matching renderer fully replaces the source. Defaults
-     * to `{ mermaid: MermaidCodeRenderer }`; pass `{}` to disable.
+     * lower-cased fenced-code info string (e.g. `mermaid`).
+     * @default `{ mermaid: MermaidCodeRenderer }`
+     */
+    codeRenderers?: CodeRenderers;
+    /**
+     * Custom JSX components to expose in the viewer.
      */
-    codeRenderers?: Record<string, CodeRenderer>;
-    /** React components for `<PascalCase />` tags. */
     components?: MarkdownComponents;
-    /** How unsupported JSX is handled. Default `render` (uses {@link DEFAULT_COMPONENTS}). */
+    /**
+     * How unsupported JSX is handled.
+     * @default `render`
+     */
     jsxMode?: JsxMode;
+    /**
+     * Add slug IDs and hover anchor links on headings.
+     * @default true
+     */
+    withAutoLink?: boolean;
+    /**
+     * Collapse consecutive blank lines into a single line break.
+     * @default true
+     */
+    withBlankLineCollapse?: boolean;
+    /**
+     * Rewrite image/video sources before render.
+     */
+    onResolveMedia?: (node: MediaDescriptor) => MediaDescriptor;
 }
 
 /**
@@ -1188,7 +1306,7 @@ export declare type MarkdownViewerRenderers = Partial<{
         children: ReactNode;
     }) => ReactNode;
     thematicBreak: () => ReactNode;
-    image: (props: ImageDescriptor) => ReactNode;
+    image: (props: MediaDescriptor) => ReactNode;
     strong: (props: {
         children: ReactNode;
     }) => ReactNode;
@@ -1226,6 +1344,17 @@ export declare interface MarkdownWidgetPortalsProps {
     store: WidgetStore;
 }
 
+/** Normalised media descriptor for viewer renderers and `onResolveMedia` callbacks. */
+export declare interface MediaDescriptor {
+    src: string;
+    alt?: string;
+    title?: string;
+    darkSrc?: string;
+}
+
+/** Merge default code renderers with caller overrides (caller wins on key clash). */
+export declare function mergeCodeRenderers(renderers?: CodeRenderers): CodeRenderers;
+
 /** Merge default JSX components with caller overrides (caller wins on key clash). */
 export declare function mergeMarkdownComponents(components?: MarkdownComponents): MarkdownComponents;
 
@@ -1330,10 +1459,16 @@ declare interface ParsedHeadingTitle {
 export declare function parseHeadingTitleText(plain: string): ParsedHeadingTitle;
 
 /**
- * Parse markdown into a Lezer syntax tree using the same grammar as CodeMirror.
+ * Parse markdown into a Lezer syntax tree using the same grammar as the editor.
  * Safe in SSR: no {@link EditorState} or DOM.
  */
-export declare function parseMarkdownTree(source: string): Tree;
+export declare function parseMarkdownTree(source: string, options?: ParseMarkdownTreeOptions): Tree;
+
+/** Options for {@link parseMarkdownTree}. */
+export declare interface ParseMarkdownTreeOptions {
+    /** Recognise GFM callout syntax (`> [!note]`). Defaults to `true`. */
+    callouts?: boolean;
+}
 
 export declare const picto2106: string;
 
@@ -2358,7 +2493,15 @@ export declare type RailroadNode = DiagramNode | SequenceNode | TerminalNode | N
 /** Resolve heading `id` from `{#custom}` suffix or slugged plain title. */
 export declare function resolveHeadingId(node: SyntaxNode, source: MarkdownSource, slugger: default_2): string | undefined;
 
-/** Normalise a component registration into its `{ component, block }` form. */
+/**
+ * Resolve a markdown image destination into an {@link MediaDescriptor}. Splits
+ * the optional `light|dark` source pair and applies the caller's `onResolveMedia`
+ * rewrite (e.g. CDN code → full URL). Shared by the editor preview widgets and
+ * the read-only viewer so both surfaces resolve sources identically.
+ */
+export declare function resolveImageDescriptor(url: string, alt: string, title?: string, onResolveMedia?: (node: MediaDescriptor) => MediaDescriptor): MediaDescriptor;
+
+/** Normalise a component registration into its `{ component, block, preserveNewlines }` form. */
 export declare function resolveMarkdownComponent(def: MarkdownComponentDef | undefined): MarkdownComponentConfig | undefined;
 
 export declare interface ResponsiveTabItem {
@@ -2441,9 +2584,11 @@ export declare interface SlashCommand {
     /** React node for the leading icon. */
     readonly icon?: ReactNode;
     /** Apply the command — typically replaces `range` with markdown. */
-    readonly run: CommandAction;
+    readonly run: SlashCommandAction;
 }
 
+export declare type SlashCommandAction = (view: SlashCommandView, range: SlashCommandRange) => void;
+
 /**
  * Renders the slash command palette. Reads the active session
  * from the {@link SlashStore}, filters {@link SlashCommand}s by the typed
@@ -2458,7 +2603,7 @@ export declare interface SlashCommand {
 export declare const SlashCommandMenu: FC<SlashCommandMenuProps>;
 
 export declare interface SlashCommandMenuProps {
-    /** Store fed by `markdownSlashCommands` (see {@link useSlashStore}). */
+    /** Store fed by `markdownSlashCommands` (see {@link useMarkdownSlashStore}). */
     store: SlashStore;
     /** Accessor for the live editor view (e.g. `controller.getEditor`). */
     getEditor: () => EditorView;
@@ -2472,6 +2617,8 @@ export declare interface SlashCommandRange {
     readonly to: number;
 }
 
+export declare type SlashCommandView = EditorView;
+
 /** Viewport coordinates of the slash anchor (from `view.coordsAtPos`). */
 export declare interface SlashCoords {
     readonly left: number;
@@ -2632,6 +2779,13 @@ export declare function useKeyNavigation<T extends Identified>(items: T[], onSub
  */
 export declare function useLater<T extends unknown[]>(doLater: (...args: T) => unknown): (...args: T) => void;
 
+/**
+ * Hook returning a stable {@link SlashStore} for the lifetime of the calling
+ * component. Pair with {@link SlashCommandMenu} and pass the same store into
+ * `markdownLivePreview({ slash: { store } })`.
+ */
+export declare function useMarkdownSlashStore(): SlashStore;
+
 /**
  * Hook returning a stable {@link WidgetStore} reference for the lifetime of
  * the calling component. Pair with {@link MarkdownWidgetPortals} and pass
@@ -2641,13 +2795,6 @@ export declare function useMarkdownWidgetStore(): WidgetStore;
 
 export declare function useMiniController(): [RefObject<HTMLIFrameElement | null>, MiniController];
 
-/**
- * Hook returning a stable {@link SlashStore} for the lifetime of the calling
- * component. Pair with {@link SlashCommandMenu} and pass the same store into
- * `markdownLivePreview({ slash: { store } })`.
- */
-export declare function useSlashStore(): SlashStore;
-
 export declare function useSort<T = DefaultSort>(options?: SortOptions<T>): SortHandle<T>;
 
 /**