Component API

Everything here is exported from @rd/designer. The element class is ReportDesigner, and the tag is report-designer (HTMLElementTagNameMap is augmented, so document.querySelector('report-designer') is typed).

Attributes#

Attributes are strings, so use them in HTML. Each one also has a property of the same meaning.

Properties (objects)#

Set these from JavaScript, never as attributes.

Read-only properties:

Note: The element also exposes a store property, the internal editor state. It is not a supported API and may change in any release.

Methods#

Events#

All events bubble and are composed, so they cross shadow boundaries.

Typed listeners:

import type { HelpRequestDetail, ReportDesigner, TemplateChangeDetail } from '@rd/designer';

const designer = document.querySelector('report-designer') as ReportDesigner;

designer.addEventListener('template-change', (e) => {
    const { template } = (e as CustomEvent<TemplateChangeDetail>).detail;
    console.log('edited:', template.name);
});

designer.addEventListener('save', (e) => {
    void saveTemplate('bol', (e as CustomEvent<TemplateChangeDetail>).detail.template);
});

designer.addEventListener('help-request', (e) => {
    const { topic, url } = (e as CustomEvent<HelpRequestDetail>).detail;
    console.log('help for', topic, 'at', url);
});

Slots#

<report-designer font-base-url="/rd-fonts/">
    <img slot="logo" src="/assets/brand-mark.svg" alt="" />
</report-designer>

With mountDesigner, add it to the element it returns:

const logo = Object.assign(document.createElement('img'), { src: '/assets/brand-mark.svg', alt: '' });
logo.slot = 'logo';
handle.element.append(logo);

mountDesigner(container, options)#

Creates a <report-designer> inside container (give the container a height) and returns a handle.

interface MountOptions {
    template?: Template | null;
    schema?: object | null;
    fontBaseUrl?: string;
    helpBaseUrl?: string;          // optional: show an external copy of the guide instead of the built-in one
    help?: boolean;                // false hides help
    theme?: 'light' | 'dark' | 'auto';
    lang?: string;
    gallery?: GalleryEntry[];
    builtinGallery?: boolean;      // false hides the built-in templates
    readOnly?: boolean;
    onChange?: (template: Template) => void;   // debounced 300 ms after edits
    onSave?: (template: Template) => void;     // Ctrl/Cmd+S or Save
}

interface DesignerHandle {
    element: ReportDesigner;
    getTemplate(): Template;
    setTemplate(template: Template | null): void;
    setSchema(schema: object | null): void;
    openHelp(topic?: string): boolean;
    setLang(lang: string): void;   // switches the UI language live
    renderPdf(): Promise<RenderResult>;
    destroy(): void;               // removes the element and its listeners
}

Exported types and values#

Building a language picker with the exported values:

import { LANGS, LANG_NAMES, resolveLang, type ReportDesigner } from '@rd/designer';

const designer = document.querySelector('report-designer') as ReportDesigner;
const select = document.createElement('select');
for (const lang of LANGS) {
    select.add(new Option(LANG_NAMES[lang], lang, false, lang === resolveLang(navigator.language)));
}
select.addEventListener('change', () => (designer.lang = select.value));
document.body.prepend(select);

Validating a template before storing it, in the browser or in Node:

import { validateTemplate, type Template } from '@rd/designer';

function assertValid(template: Template): void {
    const errors = validateTemplate(template).filter((i) => i.severity === 'error');
    if (errors.length) {
        throw new Error(errors.map((i) => `${i.path}: ${i.message}`).join('\n'));
    }
}

Keyboard handling and focus#

The element sets tabindex="0" (unless you set one) and handles its shortcuts (Ctrl/Cmd+Z, Ctrl/Cmd+S, Delete, arrows, F1 …) only while focus is inside it, so it doesn't steal shortcuts from the rest of your page. Ctrl/Cmd+S calls preventDefault() so the browser's "Save page" dialog doesn't open.