@surrealdb/ui 1.2.22 → 1.2.24

package/dist/ui.d.ts

@@ -431,19 +431,82 @@ export declare interface CodeEditorProps extends BoxProps {
     withPadding?: boolean;
 }
 
+/** Value of a single fenced-code info attribute. Loose flags resolve to `true`. */
+export declare type CodeInfoAttributeValue = string | boolean;
+
+/** Read a string-valued attribute, or `undefined` when absent or a loose flag. */
+export declare function codeInfoString(parsed: ParsedCodeInfo, key: string): string | undefined;
+
 /** React component keyed by lower-cased fenced-code info string. */
 export declare type CodeRenderer = ComponentType<CodeRendererProps>;
 
+/**
+ * A renderer registration: either a bare component, or a config object that
+ * also declares how the block hosting it behaves.
+ *
+ * Every field is optional and defaults to the behaviour a bare component gets,
+ * so `{ mermaid: MermaidCodeRenderer }` and
+ * `{ mermaid: { component: MermaidCodeRenderer } }` are equivalent.
+ */
+export declare interface CodeRendererConfig {
+    component: CodeRenderer;
+    /**
+     * Derives a stable widget identity from the block body.
+     *
+     * Widget identity is positional by default, so a block's widget is rebuilt
+     * whenever an edit above it shifts its offsets - which remounts the React
+     * subtree and loses whatever state it held. Return something drawn from the
+     * body instead and the widget is reused, so React reconciles. Return
+     * `undefined` to fall back to the positional id.
+     */
+    identify?: (code: string, language: string) => string | undefined;
+    /**
+     * Keeps the block rendered even while the selection touches it.
+     *
+     * A block yields to its raw source when the selection intersects any line it
+     * spans, which arrow keys and `Mod+A` both do. Set this where the body is
+     * machine-written and there is nothing to edit by hand; `mode="source"`
+     * remains the way to reach it.
+     */
+    alwaysRendered?: boolean;
+    /**
+     * Draws the block without the wrapper's own frame.
+     *
+     * The wrapper gives a rendered block a padded, bordered card, which is right
+     * for a diagram or a preview sitting in prose. A renderer that draws its own
+     * container - a panel, a card of its own - otherwise sits inside a second one,
+     * held away from its own edges by padding it did not ask for.
+     */
+    bare?: boolean;
+    /**
+     * Height in pixels to assume before the block has been measured.
+     *
+     * CodeMirror's height map treats an unmeasured widget as one line tall, so a
+     * document of tall blocks has the wrong scroll height on first paint. Supply
+     * this where the rendered height is known up front.
+     */
+    estimatedHeight?: number;
+}
+
+/** A registered renderer is either a bare component or a config object. */
+export declare type CodeRendererDef = CodeRenderer | CodeRendererConfig;
+
 /** Props for a custom fenced-code-block renderer (inactive block / viewer). */
 export declare interface CodeRendererProps {
     /** The code body verbatim (CodeText slice, fences excluded). */
     code: string;
     /** The (lower-cased) info string from the opening fence, e.g. `mermaid`. */
     language: string;
+    /** Start of the whole fenced block in the document, fences included. */
+    from?: number;
+    /** End of the whole fenced block in the document, fences included. */
+    to?: number;
+    /** Attributes parsed from the info string, e.g. ```` ```mermaid theme="dark" ````. */
+    attributes?: Readonly<Record<string, CodeInfoAttributeValue>>;
 }
 
-/** Map of lower-cased fenced-code info string to renderer component. */
-declare type CodeRenderers = Record<string, CodeRenderer>;
+/** Map of lower-cased fenced-code info string to renderer registration. */
+export declare type CodeRenderers = Record<string, CodeRendererDef>;
 
 export declare type ColorScheme = keyof ThemeConfig;
 
@@ -670,6 +733,10 @@ export declare interface EditorOptions {
     extensions?: Extension;
     /**
      * The language to use for the editor.
+     *
+     * Not applied by this hook. Pass the language's extension through
+     * {@link EditorOptions.extensions} instead, which is what the reconfigure
+     * effect reads.
      */
     language?: Language;
     /**
@@ -1285,6 +1352,16 @@ export declare interface LiveMarkdownEditorOptions {
  */
 export declare const MANTINE_THEME: MantineThemeOverride;
 
+/** What a renderer can reach about the block hosting it. */
+export declare interface MarkdownBlockContextValue {
+    /** The editor the block belongs to, for dispatching a change to its own range. */
+    view: EditorView;
+    from: number;
+    to: number;
+    language: string;
+    code: string;
+}
+
 /**
  * Configuration for a single `<Component />` registered in {@link MarkdownComponents}.
  * Set `block: true` to opt into the block-rendering path (own line, hover
@@ -1368,7 +1445,7 @@ export declare interface MarkdownEditorProps extends Omit<EditorOptions, "langua
      */
     autoFocus?: boolean;
     /**
-     * The placeholder text to display in the editor when it is empty.
+     * Placeholder text shown on the caret's line whenever that line is empty.
      */
     placeholder?: string;
     /**
@@ -1417,6 +1494,12 @@ export declare const markdownEditorReadyField: StateField<boolean>;
  */
 export declare const markdownModeField: StateField<MarkdownEditMode>;
 
+/**
+ * Shows `text` on the caret's line whenever that line is empty, rather than only
+ * while the whole document is.
+ */
+export declare function markdownPlaceholder(text: string): Extension;
+
 /**
  * Bundles the slash session {@link slashSessionField} with a `ViewPlugin` that
  * mirrors the active session and caret into the given {@link SlashStore}, which
@@ -1727,6 +1810,27 @@ declare interface OptionalNode {
     child: RailroadNode;
 }
 
+/**
+ * Parse a fenced code info string such as `surql runnable="SELECT 1"`,
+ * `js title="Example"`, or `ts runnable` into a language plus an attribute map.
+ *
+ * Loose attributes (no `=value`) resolve to `true`; quoted, braced, and bare
+ * values keep their literal string. The first whitespace-delimited token is the
+ * language (lower-cased).
+ */
+export declare function parseCodeInfo(info: string): ParsedCodeInfo;
+
+/** Parsed language and attribute map from a fenced-code info line. */
+export declare interface ParsedCodeInfo {
+    /** Primary language identifier (first token, lower-cased). */
+    language: string;
+    /**
+     * Attributes following the language. Key/value pairs (`title="value"`) keep
+     * their string value; loose flags (`runnable`) resolve to `true`.
+     */
+    attributes: Record<string, CodeInfoAttributeValue>;
+}
+
 declare interface ParsedHeadingTitle {
     /** Visible title text (custom id suffix removed). */
     text: string;
@@ -3271,6 +3375,12 @@ export declare interface RailroadDiagramProps extends BoxProps {
 
 export declare type RailroadNode = DiagramNode | SequenceNode | TerminalNode | NonTerminalNode | OptionalNode | ChoiceNode | OneOrMoreNode | ZeroOrMoreNode | CommentNode;
 
+/**
+ * Normalises a renderer registration, so a bare component and a config object
+ * are handled identically downstream.
+ */
+export declare function resolveCodeRenderer(def: CodeRendererDef | undefined): CodeRendererConfig | undefined;
+
 /** Resolve heading `id` from `{#custom}` suffix or slugged plain title. */
 export declare function resolveHeadingId(node: SyntaxNode, source: MarkdownSource, slugger: default_2): string | undefined;
 
@@ -4031,6 +4141,15 @@ export declare function useKeyNavigation<T extends Identified>(items: T[], onSub
  */
 export declare function useLater<T extends unknown[]>(doLater: (...args: T) => unknown): (...args: T) => void;
 
+/**
+ * The block a custom code renderer is rendering, or `null` outside one.
+ *
+ * A renderer reaches this to act on its own source - to replace, duplicate or
+ * delete the fence it was built from - which needs both the editor and the
+ * range the block occupies.
+ */
+export declare function useMarkdownBlock(): MarkdownBlockContextValue | null;
+
 /**
  * Hook returning a stable {@link SlashStore} for the lifetime of the calling
  * component. Pair with {@link SlashCommandMenu} and pass the same store into