Skip to main content

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.