@glyphjs/runtime 0.1.0 → 0.3.0

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { GlyphRuntimeConfig, GlyphRuntime, GlyphIR, AnimationConfig, Diagnostic, Block, LayoutHints, ContainerContext, GlyphComponentDefinition, ComponentType, BlockProps, GlyphTheme, Reference, GlyphThemeContext, GlyphComponentProps, InlineNode, ContainerTier } from '@glyphjs/types';
+import { GlyphRuntimeConfig, GlyphRuntime, GlyphIR, AnimationConfig, Diagnostic, Block, LayoutHints, ContainerContext, GlyphComponentDefinition, ComponentType, BlockProps, GlyphTheme, Reference, GlyphThemeContext, InteractionEvent, GlyphComponentProps, InlineNode, ContainerTier } from '@glyphjs/types';
 export { AnimationConfig } from '@glyphjs/types';
 import * as react from 'react';
 import { ReactNode, Component, ErrorInfo, CSSProperties, ComponentType as ComponentType$1, RefObject } from 'react';
@@ -142,13 +142,16 @@ declare class PluginRegistry {
 interface RuntimeContextValue {
     registry: PluginRegistry;
     references: Reference[];
+    documentId: string;
     theme: GlyphThemeContext;
     onDiagnostic: (diagnostic: Diagnostic) => void;
     onNavigate: (ref: Reference, targetBlock: Block) => void;
+    onInteraction?: (event: InteractionEvent) => void;
 }
 interface RuntimeProviderProps {
     registry: PluginRegistry;
     references: Reference[];
+    documentId: string;
     theme: 'light' | 'dark' | GlyphTheme | undefined;
     /** Optional CSS class name applied to the runtime wrapper div. */
     className?: string;
@@ -156,9 +159,10 @@ interface RuntimeProviderProps {
     style?: CSSProperties;
     onDiagnostic?: (diagnostic: Diagnostic) => void;
     onNavigate?: (ref: Reference, targetBlock: Block) => void;
+    onInteraction?: (event: InteractionEvent) => void;
     children: ReactNode;
 }
-declare function RuntimeProvider({ registry, references, theme, className, style: consumerStyle, onDiagnostic, onNavigate, children, }: RuntimeProviderProps): ReactNode;
+declare function RuntimeProvider({ registry, references, documentId, theme, className, style: consumerStyle, onDiagnostic, onNavigate, onInteraction, children, }: RuntimeProviderProps): ReactNode;
 /** Access the full runtime context. Throws if used outside RuntimeProvider. */
 declare function useRuntime(): RuntimeContextValue;
 /**
@@ -204,9 +208,10 @@ declare function validateComponentDefinition(definition: GlyphComponentDefinitio
  * @param themeContext - Current theme context passed through to the component.
  * @param layoutHints - Layout hints (e.g., viewport size, container width) for responsive rendering.
  * @param containerContext - Container measurement context for container-adaptive layout.
+ * @param onInteraction - Optional callback for interactive blocks. Only provided when `block.metadata.interactive` is true.
  * @returns Fully assembled GlyphComponentProps ready to pass to the component's render function.
  */
-declare function resolveComponentProps<T = unknown>(block: Block, definition: GlyphComponentDefinition<T>, references: Reference[], onNavigate: (ref: Reference) => void, themeContext: GlyphThemeContext, layoutHints: LayoutHints, containerContext: ContainerContext): GlyphComponentProps<T>;
+declare function resolveComponentProps<T = unknown>(block: Block, definition: GlyphComponentDefinition<T>, references: Reference[], onNavigate: (ref: Reference) => void, themeContext: GlyphThemeContext, layoutHints: LayoutHints, containerContext: ContainerContext, onInteraction?: (event: Omit<InteractionEvent, 'documentId'>) => void): GlyphComponentProps<T>;
 
 interface LayoutProviderProps {
     layout: LayoutHints;
@@ -273,6 +278,21 @@ interface InlineRendererProps {
  */
 declare function InlineRenderer({ nodes }: InlineRendererProps): ReactNode;
 
+interface RichTextProps {
+    content: string | InlineNode[];
+    style?: React.CSSProperties;
+    className?: string;
+}
+/**
+ * Renders text that may be plain string or formatted InlineNode[].
+ * Type guard checks if content is array, then uses InlineRenderer.
+ *
+ * This component enables component text fields to support both:
+ * - Plain strings (backward compatibility)
+ * - Markdown-parsed InlineNode arrays (when markdown: true)
+ */
+declare function RichText({ content, style, className }: RichTextProps): ReactNode;
+
 /**
  * Renders a heading block (`<h1>` through `<h6>`) based on `data.depth`.
  * Generates an `id` attribute from the heading text for anchor links.
@@ -567,4 +587,16 @@ interface SSRPlaceholderProps {
  */
 declare function SSRPlaceholder({ width, height, className, children, }: SSRPlaceholderProps): ReactNode;
 
-export { AnimationContext, AnimationProvider, type AnimationState, type BlockAnimationResult, BlockDiagnosticIndicator, BlockRenderer, PluginRegistry as ComponentRegistry, ContainerMeasure, DashboardLayout, DiagnosticsOverlay, DocumentLayout, ErrorBoundary, FallbackRenderer, GlyphBlockquote, GlyphCodeBlock, GlyphDocument, GlyphHeading, GlyphImage, GlyphList, GlyphParagraph, GlyphRawHtml, GlyphThematicBreak, InlineRenderer, LayoutProvider, type NavigationResult, PluginRegistry, PresentationLayout, ReferenceIndicator, type RegistryChangeListener, type RuntimeContextValue, RuntimeProvider, type RuntimeProviderProps, SSRPlaceholder, type SSRPlaceholderProps, ThemeProvider, type ThemeProviderProps, type ValidationResult, builtInRenderers, createGlyphRuntime, createResolveVar, darkTheme, isDarkTheme, lightTheme, mergeThemeDefaults, resolveComponentProps, resolveTheme, resolveTier, useAnimation, useBlockAnimation, useGlyphTheme, useIsClient, useLayout, useNavigation, useReferences, useRuntime, validateComponentDefinition };
+/**
+ * Creates a debounced interaction handler that groups events by
+ * `blockId + kind`. Each unique stream is debounced independently,
+ * so a tab switch fires immediately even while a table filter is
+ * being debounced.
+ *
+ * @param callback - The handler to invoke with the debounced event.
+ * @param delay - Debounce window in milliseconds (default: 300).
+ * @returns A function with the same signature as `onInteraction`.
+ */
+declare function debounceInteractions(callback: (event: InteractionEvent) => void, delay?: number): (event: InteractionEvent) => void;
+
+export { AnimationContext, AnimationProvider, type AnimationState, type BlockAnimationResult, BlockDiagnosticIndicator, BlockRenderer, PluginRegistry as ComponentRegistry, ContainerMeasure, DashboardLayout, DiagnosticsOverlay, DocumentLayout, ErrorBoundary, FallbackRenderer, GlyphBlockquote, GlyphCodeBlock, GlyphDocument, GlyphHeading, GlyphImage, GlyphList, GlyphParagraph, GlyphRawHtml, GlyphThematicBreak, InlineRenderer, LayoutProvider, type NavigationResult, PluginRegistry, PresentationLayout, ReferenceIndicator, type RegistryChangeListener, RichText, type RichTextProps, type RuntimeContextValue, RuntimeProvider, type RuntimeProviderProps, SSRPlaceholder, type SSRPlaceholderProps, ThemeProvider, type ThemeProviderProps, type ValidationResult, builtInRenderers, createGlyphRuntime, createResolveVar, darkTheme, debounceInteractions, isDarkTheme, lightTheme, mergeThemeDefaults, resolveComponentProps, resolveTheme, resolveTier, useAnimation, useBlockAnimation, useGlyphTheme, useIsClient, useLayout, useNavigation, useReferences, useRuntime, validateComponentDefinition };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { GlyphRuntimeConfig, GlyphRuntime, GlyphIR, AnimationConfig, Diagnostic, Block, LayoutHints, ContainerContext, GlyphComponentDefinition, ComponentType, BlockProps, GlyphTheme, Reference, GlyphThemeContext, GlyphComponentProps, InlineNode, ContainerTier } from '@glyphjs/types';
+import { GlyphRuntimeConfig, GlyphRuntime, GlyphIR, AnimationConfig, Diagnostic, Block, LayoutHints, ContainerContext, GlyphComponentDefinition, ComponentType, BlockProps, GlyphTheme, Reference, GlyphThemeContext, InteractionEvent, GlyphComponentProps, InlineNode, ContainerTier } from '@glyphjs/types';
 export { AnimationConfig } from '@glyphjs/types';
 import * as react from 'react';
 import { ReactNode, Component, ErrorInfo, CSSProperties, ComponentType as ComponentType$1, RefObject } from 'react';
@@ -142,13 +142,16 @@ declare class PluginRegistry {
 interface RuntimeContextValue {
     registry: PluginRegistry;
     references: Reference[];
+    documentId: string;
     theme: GlyphThemeContext;
     onDiagnostic: (diagnostic: Diagnostic) => void;
     onNavigate: (ref: Reference, targetBlock: Block) => void;
+    onInteraction?: (event: InteractionEvent) => void;
 }
 interface RuntimeProviderProps {
     registry: PluginRegistry;
     references: Reference[];
+    documentId: string;
     theme: 'light' | 'dark' | GlyphTheme | undefined;
     /** Optional CSS class name applied to the runtime wrapper div. */
     className?: string;
@@ -156,9 +159,10 @@ interface RuntimeProviderProps {
     style?: CSSProperties;
     onDiagnostic?: (diagnostic: Diagnostic) => void;
     onNavigate?: (ref: Reference, targetBlock: Block) => void;
+    onInteraction?: (event: InteractionEvent) => void;
     children: ReactNode;
 }
-declare function RuntimeProvider({ registry, references, theme, className, style: consumerStyle, onDiagnostic, onNavigate, children, }: RuntimeProviderProps): ReactNode;
+declare function RuntimeProvider({ registry, references, documentId, theme, className, style: consumerStyle, onDiagnostic, onNavigate, onInteraction, children, }: RuntimeProviderProps): ReactNode;
 /** Access the full runtime context. Throws if used outside RuntimeProvider. */
 declare function useRuntime(): RuntimeContextValue;
 /**
@@ -204,9 +208,10 @@ declare function validateComponentDefinition(definition: GlyphComponentDefinitio
  * @param themeContext - Current theme context passed through to the component.
  * @param layoutHints - Layout hints (e.g., viewport size, container width) for responsive rendering.
  * @param containerContext - Container measurement context for container-adaptive layout.
+ * @param onInteraction - Optional callback for interactive blocks. Only provided when `block.metadata.interactive` is true.
  * @returns Fully assembled GlyphComponentProps ready to pass to the component's render function.
  */
-declare function resolveComponentProps<T = unknown>(block: Block, definition: GlyphComponentDefinition<T>, references: Reference[], onNavigate: (ref: Reference) => void, themeContext: GlyphThemeContext, layoutHints: LayoutHints, containerContext: ContainerContext): GlyphComponentProps<T>;
+declare function resolveComponentProps<T = unknown>(block: Block, definition: GlyphComponentDefinition<T>, references: Reference[], onNavigate: (ref: Reference) => void, themeContext: GlyphThemeContext, layoutHints: LayoutHints, containerContext: ContainerContext, onInteraction?: (event: Omit<InteractionEvent, 'documentId'>) => void): GlyphComponentProps<T>;
 
 interface LayoutProviderProps {
     layout: LayoutHints;
@@ -273,6 +278,21 @@ interface InlineRendererProps {
  */
 declare function InlineRenderer({ nodes }: InlineRendererProps): ReactNode;
 
+interface RichTextProps {
+    content: string | InlineNode[];
+    style?: React.CSSProperties;
+    className?: string;
+}
+/**
+ * Renders text that may be plain string or formatted InlineNode[].
+ * Type guard checks if content is array, then uses InlineRenderer.
+ *
+ * This component enables component text fields to support both:
+ * - Plain strings (backward compatibility)
+ * - Markdown-parsed InlineNode arrays (when markdown: true)
+ */
+declare function RichText({ content, style, className }: RichTextProps): ReactNode;
+
 /**
  * Renders a heading block (`<h1>` through `<h6>`) based on `data.depth`.
  * Generates an `id` attribute from the heading text for anchor links.
@@ -567,4 +587,16 @@ interface SSRPlaceholderProps {
  */
 declare function SSRPlaceholder({ width, height, className, children, }: SSRPlaceholderProps): ReactNode;
 
-export { AnimationContext, AnimationProvider, type AnimationState, type BlockAnimationResult, BlockDiagnosticIndicator, BlockRenderer, PluginRegistry as ComponentRegistry, ContainerMeasure, DashboardLayout, DiagnosticsOverlay, DocumentLayout, ErrorBoundary, FallbackRenderer, GlyphBlockquote, GlyphCodeBlock, GlyphDocument, GlyphHeading, GlyphImage, GlyphList, GlyphParagraph, GlyphRawHtml, GlyphThematicBreak, InlineRenderer, LayoutProvider, type NavigationResult, PluginRegistry, PresentationLayout, ReferenceIndicator, type RegistryChangeListener, type RuntimeContextValue, RuntimeProvider, type RuntimeProviderProps, SSRPlaceholder, type SSRPlaceholderProps, ThemeProvider, type ThemeProviderProps, type ValidationResult, builtInRenderers, createGlyphRuntime, createResolveVar, darkTheme, isDarkTheme, lightTheme, mergeThemeDefaults, resolveComponentProps, resolveTheme, resolveTier, useAnimation, useBlockAnimation, useGlyphTheme, useIsClient, useLayout, useNavigation, useReferences, useRuntime, validateComponentDefinition };
+/**
+ * Creates a debounced interaction handler that groups events by
+ * `blockId + kind`. Each unique stream is debounced independently,
+ * so a tab switch fires immediately even while a table filter is
+ * being debounced.
+ *
+ * @param callback - The handler to invoke with the debounced event.
+ * @param delay - Debounce window in milliseconds (default: 300).
+ * @returns A function with the same signature as `onInteraction`.
+ */
+declare function debounceInteractions(callback: (event: InteractionEvent) => void, delay?: number): (event: InteractionEvent) => void;
+
+export { AnimationContext, AnimationProvider, type AnimationState, type BlockAnimationResult, BlockDiagnosticIndicator, BlockRenderer, PluginRegistry as ComponentRegistry, ContainerMeasure, DashboardLayout, DiagnosticsOverlay, DocumentLayout, ErrorBoundary, FallbackRenderer, GlyphBlockquote, GlyphCodeBlock, GlyphDocument, GlyphHeading, GlyphImage, GlyphList, GlyphParagraph, GlyphRawHtml, GlyphThematicBreak, InlineRenderer, LayoutProvider, type NavigationResult, PluginRegistry, PresentationLayout, ReferenceIndicator, type RegistryChangeListener, RichText, type RichTextProps, type RuntimeContextValue, RuntimeProvider, type RuntimeProviderProps, SSRPlaceholder, type SSRPlaceholderProps, ThemeProvider, type ThemeProviderProps, type ValidationResult, builtInRenderers, createGlyphRuntime, createResolveVar, darkTheme, debounceInteractions, isDarkTheme, lightTheme, mergeThemeDefaults, resolveComponentProps, resolveTheme, resolveTier, useAnimation, useBlockAnimation, useGlyphTheme, useIsClient, useLayout, useNavigation, useReferences, useRuntime, validateComponentDefinition };

package/dist/index.js

@@ -394,11 +394,13 @@ var RuntimeContext = createContext(null);
 function RuntimeProvider({
   registry,
   references,
+  documentId,
   theme,
   className,
   style: consumerStyle,
   onDiagnostic,
   onNavigate,
+  onInteraction,
   children
 }) {
   const resolvedThemeObject = useMemo(() => resolveTheme(theme), [theme]);
@@ -414,11 +416,13 @@ function RuntimeProvider({
     () => ({
       registry,
       references,
+      documentId,
       theme: resolvedTheme,
       onDiagnostic: onDiagnostic ?? noop,
-      onNavigate: onNavigate ?? noop
+      onNavigate: onNavigate ?? noop,
+      onInteraction
     }),
-    [registry, references, resolvedTheme, onDiagnostic, onNavigate]
+    [registry, references, documentId, resolvedTheme, onDiagnostic, onNavigate, onInteraction]
   );
   const style = useMemo(
     () => ({ ...resolvedThemeObject.variables, ...consumerStyle }),
@@ -775,6 +779,12 @@ function GlyphRawHtml({ block }) {
   const clean = DOMPurify.sanitize(data.value);
   return /* @__PURE__ */ jsx("div", { dangerouslySetInnerHTML: { __html: clean } });
 }
+function RichText({ content, style, className }) {
+  if (Array.isArray(content)) {
+    return /* @__PURE__ */ jsx("span", { style, className, children: /* @__PURE__ */ jsx(InlineRenderer, { nodes: content }) });
+  }
+  return /* @__PURE__ */ jsx("span", { style, className, children: content });
+}
 
 // src/renderers/index.ts
 var builtInRenderers = {
@@ -789,7 +799,7 @@ var builtInRenderers = {
 };
 
 // src/plugins/resolve-props.ts
-function resolveComponentProps(block, definition, references, onNavigate, themeContext, layoutHints, containerContext) {
+function resolveComponentProps(block, definition, references, onNavigate, themeContext, layoutHints, containerContext, onInteraction) {
   const parseResult = definition.schema.safeParse(block.data);
   const data = parseResult.success ? parseResult.data : (() => {
     const err = parseResult.error;
@@ -819,7 +829,7 @@ function resolveComponentProps(block, definition, references, onNavigate, themeC
       }
     }
   }
-  return {
+  const props = {
     data,
     block,
     outgoingRefs,
@@ -829,6 +839,10 @@ function resolveComponentProps(block, definition, references, onNavigate, themeC
     layout: layoutHints,
     container: containerContext
   };
+  if (onInteraction) {
+    props.onInteraction = onInteraction;
+  }
+  return props;
 }
 var defaultConfig = {
   enabled: true,
@@ -1018,7 +1032,7 @@ function ReferenceIndicator({
   );
 }
 function BlockDispatch({ block, layout, container }) {
-  const { registry, references, theme, onNavigate } = useRuntime();
+  const { registry, references, theme, documentId, onNavigate, onInteraction } = useRuntime();
   const { incomingRefs, outgoingRefs } = useReferences(block.id);
   const hasRefs = incomingRefs.length > 0 || outgoingRefs.length > 0;
   if (block.type.startsWith("ui:")) {
@@ -1034,6 +1048,9 @@ function BlockDispatch({ block, layout, container }) {
       }
     }
   }
+  const handleInteraction = onInteraction && block.metadata?.interactive === true ? (event) => {
+    onInteraction({ ...event, documentId });
+  } : void 0;
   let content;
   const overrideDef = registry.getOverride(block.type);
   if (overrideDef) {
@@ -1052,7 +1069,8 @@ function BlockDispatch({ block, layout, container }) {
         handleNavigate,
         theme,
         layout,
-        container
+        container,
+        handleInteraction
       );
       const Renderer = definition.render;
       content = /* @__PURE__ */ jsx(Renderer, { ...props });
@@ -1644,7 +1662,7 @@ function createGlyphRuntime(config) {
       setThemeState(currentTheme);
       setVersion(registryVersion);
     }, []);
-    useMemo(() => {
+    useEffect(() => {
       listeners.add(forceUpdate);
       return () => {
         listeners.delete(forceUpdate);
@@ -1655,9 +1673,11 @@ function createGlyphRuntime(config) {
       {
         registry,
         references: ir.references,
+        documentId: ir.id,
         theme,
         onDiagnostic: config.onDiagnostic,
         onNavigate: config.onNavigate,
+        onInteraction: config.onInteraction,
         children: /* @__PURE__ */ jsx(GlyphDocument, { ir, className, animation: config.animation })
       }
     );
@@ -1709,6 +1729,25 @@ function SSRPlaceholder({
   return /* @__PURE__ */ jsx(Fragment, { children });
 }
 
-export { AnimationContext, AnimationProvider, BlockDiagnosticIndicator, BlockRenderer, PluginRegistry as ComponentRegistry, ContainerMeasure, DashboardLayout, DiagnosticsOverlay, DocumentLayout, ErrorBoundary, FallbackRenderer, GlyphBlockquote, GlyphCodeBlock, GlyphDocument, GlyphHeading, GlyphImage, GlyphList, GlyphParagraph, GlyphRawHtml, GlyphThematicBreak, InlineRenderer, LayoutProvider, PluginRegistry, PresentationLayout, ReferenceIndicator, RuntimeProvider, SSRPlaceholder, ThemeProvider, builtInRenderers, createGlyphRuntime, createResolveVar, darkTheme, isDarkTheme, lightTheme, mergeThemeDefaults, resolveComponentProps, resolveTheme, resolveTier, useAnimation, useBlockAnimation, useGlyphTheme, useIsClient, useLayout, useNavigation, useReferences, useRuntime, validateComponentDefinition };
+// src/debounce.ts
+function debounceInteractions(callback, delay = 300) {
+  const timers = /* @__PURE__ */ new Map();
+  return (event) => {
+    const key = `${event.blockId}:${event.kind}`;
+    const existing = timers.get(key);
+    if (existing !== void 0) {
+      clearTimeout(existing);
+    }
+    timers.set(
+      key,
+      setTimeout(() => {
+        timers.delete(key);
+        callback(event);
+      }, delay)
+    );
+  };
+}
+
+export { AnimationContext, AnimationProvider, BlockDiagnosticIndicator, BlockRenderer, PluginRegistry as ComponentRegistry, ContainerMeasure, DashboardLayout, DiagnosticsOverlay, DocumentLayout, ErrorBoundary, FallbackRenderer, GlyphBlockquote, GlyphCodeBlock, GlyphDocument, GlyphHeading, GlyphImage, GlyphList, GlyphParagraph, GlyphRawHtml, GlyphThematicBreak, InlineRenderer, LayoutProvider, PluginRegistry, PresentationLayout, ReferenceIndicator, RichText, RuntimeProvider, SSRPlaceholder, ThemeProvider, builtInRenderers, createGlyphRuntime, createResolveVar, darkTheme, debounceInteractions, isDarkTheme, lightTheme, mergeThemeDefaults, resolveComponentProps, resolveTheme, resolveTier, useAnimation, useBlockAnimation, useGlyphTheme, useIsClient, useLayout, useNavigation, useReferences, useRuntime, validateComponentDefinition };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map