Skip to main content

Documentation Index

Fetch the complete documentation index at: https://developers.smarterservices.com/llms.txt

Use this file to discover all available pages before exploring further.

Renderer

Renders BlockKit JSON structures into interactive UI components with support for dynamic content, replacements, and event handling

Element Type

blockkit/renderer

Usage

React Integration

import { useSmarterElements } from '@smarterservices/smarter-elements';

function MyComponent() {
  const elements = useSmarterElements();
  
  const handleCreateElement = async () => {
    const element = elements.create('blockkit/renderer', {
      config: {
        // Add your configuration here
      },
      onReady: () => {
        console.log('Element is ready');
      },
      onError: (error) => {
        console.error('Element error:', error);
      }
    });
    
    // Mount the element
    element.mount('#element-container');
    
    // Or open as modal
    await element.openModal({
      width: '80%',
      maxWidth: '900px'
    });
  };
  
  return (
    <div>
      <button onClick={handleCreateElement}>
        Create Renderer
      </button>
      <div id="element-container"></div>
    </div>
  );
}

JavaScript Integration

// Load SmarterElements
import { SmarterElements } from '@smarterservices/smarter-elements';

// Initialize
const elements = new SmarterElements({
  baseUrl: '/elements'
});

// Create element
const element = elements.create('blockkit/renderer', {
  config: {
    // Add your configuration here
  },
  onReady: () => {
    console.log('Element is ready');
  },
  onError: (error) => {
    console.error('Element error:', error);
  }
});

// Mount to DOM element
element.mount('#element-container');

// Or open as modal
element.openModal({
  width: '80%',
  maxWidth: '900px'
});

Configuration

Input Parameters

The following parameters can be passed in the config object:
interface InputSchema {
    /**
     * Array of BlockKit elements to render
     * @optional - Either blocks or blocksJson must be provided
     */
    blocks?: Array<{
        type: string;
        [key: string]: any;
    }>;

    /**
     * JSON string containing BlockKit elements
     * @optional - Either blocks or blocksJson must be provided
     */
    blocksJson?: string;

    /**
     * Key-value pairs for dynamic content replacement
     * @optional
     * @example { "courseName": "React Fundamentals", "instructor": "John Doe" }
     */
    replacements?: Record<string, any>;

    /**
     * Theme configuration for the rendered content
     * @optional
     */
    theme?: {
        /**
         * Primary color scheme
         * @default "blue"
         */
        primaryColor?: 'blue' | 'green' | 'red' | 'purple' | 'orange' | 'gray';

        /**
         * Component size variant
         * @default "medium"
         */
        size?: 'small' | 'medium' | 'large';

        /**
         * Border radius style
         * @default "medium"
         */
        borderRadius?: 'none' | 'small' | 'medium' | 'large';
    };

    /**
     * Accessibility configuration
     * @optional
     */
    accessibility?: {
        /**
         * ARIA label for the rendered content
         */
        ariaLabel?: string;

        /**
         * ARIA description for the rendered content
         */
        ariaDescription?: string;

        /**
         * Whether to announce content changes to screen readers
         * @default true
         */
        announceChanges?: boolean;
    };

}

Output

This element provides the following output interface:
interface OutputSchema {
    /**
     * The rendered BlockKit content as HTML
     */
    renderedContent: string;

    /**
     * Parsed and validated BlockKit elements
     */
    parsedBlocks: Array<{
        type: string;
        [key: string]: any;
    }>;

    /**
     * Current theme configuration
     */
    currentTheme: {
        primaryColor: string;
        size: string;
        borderRadius: string;
    };

    /**
     * Validation errors, if any
     */
    validationErrors: Array<{
        blockIndex: number;
        field: string;
        message: string;
    }>;

}

Events

This element emits the following events:
interface EventsSchema {
    /**
     * Fired when BlockKit content is successfully rendered
     */
    'content-rendered': {
        /**
         * Number of blocks rendered
         */
        blockCount: number;

        /**
         * Rendering time in milliseconds
         */
        renderTime: number;

        /**
         * Whether any replacements were applied
         */
        hasReplacements: boolean;
    };

    /**
     * Fired when there's an error rendering BlockKit content
     */
    'render-error': {
        /**
         * Error message
         */
        message: string;

        /**
         * Error code
         */
        code: 'INVALID_JSON' | 'VALIDATION_ERROR' | 'RENDER_ERROR';

        /**
         * Block index where error occurred (if applicable)
         */
        blockIndex?: number;
    };

    /**
     * Fired when user interacts with rendered content
     */
    'content-interaction': {
        /**
         * Type of interaction
         */
        interactionType: 'click' | 'focus' | 'hover' | 'input';

        /**
         * Element that was interacted with
         */
        elementType: string;

        /**
         * Additional data about the interaction
         */
        data?: Record<string, any>;
    };

    /**
     * Fired when content is updated with new blocks or replacements
     */
    'content-updated': {
        /**
         * Previous block count
         */
        previousBlockCount: number;

        /**
         * New block count
         */
        newBlockCount: number;

        /**
         * Whether replacements changed
         */
        replacementsChanged: boolean;
    };

    /**
     * Fired when theme is changed
     */
    'theme-changed': {
        /**
         * Previous theme configuration
         */
        previousTheme: {
            primaryColor: string;
            size: string;
            borderRadius: string;
        };

        /**
         * New theme configuration
         */
        newTheme: {
            primaryColor: string;
            size: string;
            borderRadius: string;
        };
    };

}

Event Handling

const element = elements.create('blockkit/renderer', {
  onEvent: (eventType, data) => {
    switch (eventType) {
      case 'eventName':
        console.log('Event received:', data);
        break;
    }
  }
});

Examples

Basic Example

const element = elements.create('blockkit/renderer', {
  config: {
    // Minimal configuration
  }
});

element.mount('#container');
const element = elements.create('blockkit/renderer', {
  config: {
    // Your configuration
  }
});

await element.openModal({
  width: '90%',
  maxWidth: '1000px',
  dismissOnDocumentClick: false,
  escapeClose: true
});

API Reference

Element Methods

  • mount(selector) - Mount element to DOM
  • openModal(options) - Open element in modal
  • destroy() - Clean up and destroy element
  • postMessage(data) - Send message to element
  • on(event, callback) - Listen for events
  • off(event, callback) - Remove event listener
  • width - Modal width (string or number)
  • height - Modal height (string or number)
  • maxWidth - Maximum width constraint
  • maxHeight - Maximum height constraint
  • dismissOnDocumentClick - Close on backdrop click
  • escapeClose - Close on Escape key
  • zIndex - Modal z-index value

This documentation was auto-generated from the element schema.