README

Table of Contents

• Embeddable overview
• Public
  • Guiding principles
  • Embeddable public overview
  • Publishing packages
  • Embeddable panel
  • Best practices
  • Examples
• Server
  • REST APIs
  • Transforms

Embeddable overview

Embeddables require registration in both server and public.

registerEmbeddableServerDefinition

Server registration defines the embeddable schema and other information required to include embeddables in public REST APIs like "dashboards as code".

registerEmbeddablePublicDefinition

Public registration defines the embeddable's UI. Embeddable UI consumes and returns state in the shape defined by the embeddable schema registered in the server.

Public

Guiding principles

Coupled to React

Kibana is a React application, and the minimum unit of sharing is the React component. Embeddables enforce this by requiring a React component during registration.

Composition over inheritence

Rather than an inheritance-based system with classes, imperative APIs are plain old typescript objects that implement any number of shared interfaces. Interfaces are enforced via type guards and are shared via Packages.

Internal state management

Each embeddable manages its own state. This is because the embeddable system allows a page to render a registry of embeddable types that can change over time. This makes it untenable for a single page to manage state for every type of embeddable. The page is only responsible for persisting and providing the last persisted state to the embeddable on startup. For implementation details, see Embeddable state management example.

An embeddable API shares state via a publishing subject, a read only RxJS Observable. An embeddable API shares setter methods for updating state.

Embeddable public overview

Embeddables are React components that manage their own state, can be serialized and deserialized, and return an API that can be used to interact with them imperatively.

Plugins register new embeddable types with the embeddable plugin.

embeddablePublicSetup.registerEmbeddablePublicDefinition('my_embeddable_type', async () => {
  const { myEmbeddableFactory } = await import('./embeddable_module');
  return myEmbeddableFactory;
});

Embeddables are rendered with EmbeddableRenderer React component.

Publishing packages

An embeddable API is a plain old typescript object that implements any number of shared interfaces. A shared interface is defined by a publishing package. A publishing package also provides a type guard that is used to check if a given object fulfills the interface.

Common publishing packages

The table below lists interface implemenations provided by EmbeddableRenderer React component. An embeddable does not need to implement these interfaces as they are already provided.

The table below lists required publishing package interfaces. An embeddable must implement these interfaces.

The table below lists optional publishing package interfaces. Embeddables may implement these interfaces. Embeddables without interface implemenations will not show UiActions that require an interface.

Custom publishing packages

Embeddables can expose interfaces unique to a single embeddable implemenation. The table below lists interfaces that only apply to single embeddable types. These interfaces may be used by actions to imperatively interact with specific embeddable types.

Embeddable panel

The EmbeddableRenderer React component wraps the embeddable component in an embeddable panel. The embeddable panel provides UI elements for interacting with the embeddable.

The embeddable panel uses UiActions and Triggers registry to make the embeddable UI extensible. The table below lists the trigger events used by the embeddable panel.

The embeddable panel passes the embeddable API to UiActions. Each UiAction uses its isCompatable method to exclude embeddable API's that do not implement the required shared interfaces. An action is not displayed when isCompatable returns false.

The table below lists the UiActions registered to embeddable panel triggers.

Best practices

Do not use Embeddables to share Components between plugins

Only create an embeddable if your Component is rendered on a page that persists embeddable state and renders multiple embeddable types. For example, create an embeddable to render your Component on a Dashboard. Otherwise, use a vanilla React Component to share Components between plugins.

Do not use Embeddables to avoid circular plugin dependencies

Break your Component into a Package or another plugin to avoid circular plugin dependencies.

Minimal API surface area

Embeddable APIs are accessable to all Kibana systems and all embeddable siblings and parents. Functions and state that are internal to an embeddable including any child components should not be added to the API. Consider passing internal state to child as props or react context.

Error handling

Embeddables should never throw. Instead, use PublishesBlockingError interface to surface unrecoverable errors. When an embeddable publishes a blocking error, the parent component will display an error component instead of the embeddable Component. Be thoughtful about which errors are surfaced with the PublishesBlockingError interface. If the embeddable can still render, use less invasive error handling such as a warning toast or notifications in the embeddable Component UI.

Examples

Examples available at /examples/embeddable_examples

Run examples with yarn start --run-examples

Embeddable factory examples

Use the following examples to learn how to create new Embeddable types. To access new Embeddable types, create a new dashboard, click "Add panel" and finally select "Embeddable examples".

• Register a new embeddable type
• Create an embeddable that responds to Unified search
• Create an embeddable that interacts with sibling embeddables
• Create an embeddable that can be by value or by reference

Rendering embeddable examples

Use the following examples to render embeddables in your application. To run embeddable examples, navigate to http://localhost:5601/app/embeddablesApp

• Render a single embeddable
• Embeddable state management
• Create a dashboard like application that renders many embeddables and allows users to add and remove embeddables

Server

Containers, such as Dashboard, incorporate embeddable state in REST APIs and store embeddable state in saved objects.

REST APIs considerations

Embeddable serialized state requires additional restrictions and planning since it is incorporated into public REST APIs.

No breaking changes

Embeddable serialized state can not be modified with breaking changes. Fields can not be deleted or change type. Optional fields can not be changed to required. Optional additive changes are allowed.

snake_case

Kibana's REST APIs require snake_case. Therefore, embeddable serialized state must be in snake_case.

Avoid duplicating state

Avoid unnecessary information to keep public REST APIs concise. Do not store duplicate information. Derived fields can be created in public when initializing an embeddable.

Apply defaults in your schema

POST, PUT, and GET requests should return complete data. Apply defaults in your embeddable schemas by using the defaultValue key.

Any key that has a defaultValue should not be wrapped in a schema.maybe, as this will cause the defaults to not be applied at validation time.

When a field is required with a default, instead of failing the request for not supplying a required field, route validation supplies the default value to the handler.

//
// Use this pattern
//
// When route validation recieves "{}", validation passes "{ foo: '' }" to handler
//
const myEmbeddlabeStateSchema = schema: schema.object({
  foo: schema.string({
    defaultValue: ''
  }),
});

When a field is optional with a default, route validation does not supply the default value to the handler.

//
// Avoid this pattern
//
// When route validation recieves "{}", validation passes "{}" to route handler
//
const myEmbeddlabeStateSchema = schema: schema.object({
  foo: schema.maybe(schema.string({
    defaultValue: ''
  })),
});

Derive types from schemas

Derive Embeddable state typescript types from REST API schemas to ensure type consistency.

//
// Example deriving type MyEmbeddableState from schema myEmbeddlabeStateSchema
//

import type { TypeOf } from '@kbn/config-schema';

const myEmbeddlabeStateSchema = schema: schema.object({
  foo: schema.string(),
});

export type MyEmbeddableState = TypeOf<typeof myEmbeddlabeStateSchema>;

//
// Example deriving type MyEmbeddableState from function
//

import type { GetDrilldownsSchemaFnType } from '@kbn/embeddable-plugin/server';
import type { TypeOf } from '@kbn/config-schema';

export const getMyEmbeddableSchema = (getDrilldownsSchema: GetDrilldownsSchemaFnType) => {
  return schema.allOf([
    serializedTitlesSchema,
    getDrilldownsSchema(MY_EMBEDDABLE_SUPPORTED_TRIGGERS),
    schema.object({
      foo: schema.string(),
    })
  ])
};

export type MyEmbeddableState = TypeOf<ReturnType<typeof getMyEmbeddableSchema>>;

Then, in common and public, replace existing embeddable types with derived types.

//
// Example showing how to use derived type when registering embeddable factory in public 
//

import type { DefaultEmbeddableApi } from '@kbn/embeddable-plugin/public';
import type { MyEmbeddableState } from '../../server';

export type MyEditorApi = DefaultEmbeddableApi<MyEmbeddableState>; 

export const myEmbeddableFactory: EmbeddableFactory<
  MyEmbeddableState,
  MyEmbeddableApi
> = {
  type: MY_EMBEDDABLE_TYPE,
  buildEmbeddable: async (initialState) => {
    //
    // initialState passed to Embeddable as MyEmbeddableState
    //
    return {
      api: {
        serializeState: () => {
          // Embeddable serializes state as MyEmbeddableState
          return {
            foo: 'hello world'
          }
        }
      },
      component: mockComponent
    }
  },

Transforms

Transforms decouple REST API state from stored state, allowing embeddables to have one shape for REST APIs and another for storage.

• On read, transformOut is used to convert StoredEmbeddableState and inject references into EmbeddableState.
• On write, transformIn is used to extract references and convert EmbeddableState into StoredEmbeddableState.

Note: Transforms are optional and only required when an embeddable has references or a container has stored legacy embeddable state that needs to converted into new schema defined shape.

Note: If your embeddable registeres transformOut, then you must also register the same function with embeddablePublicSetup.registerLegacyURLTransform. Dashboard allows users to share unsaved dashboard changes. This feature stores embeddable state in URLs.

Containers use schemas to

• Include embeddable state schemas in OpenAPI Specification (OAS) documenation.
• Validate embeddable state, failing REST API requests when schema validation fails.

embeddableServerSetup.registerEmbeddableServerDefinition(
  'my_embeddable_type',
  {
    title: 'My embeddable',
    getTransforms: (drilldownTransfroms) => ({
      transformIn: (state: EmbeddableState) => {
        return {
          state: convertToStoredState(state),
          references: extractReferences(state)
        };
      },
      transformOut: (state: StoredEmbeddableState, references?: Reference[]): EmbeddableState => {
        return convertAndInjectReferences(state, references);
      },
    }),
    getSchema: (getDrilldownsSchema) => schema: schema.object({
      foo: schema.string(),
    })
  }
});