Create a definition and mapper for web components to interface with the tooling

[janechu]

Background

The JSON schema intended to be used with the <Form /> consist of easily editable props (in the case of React) or attributes (in the case of regular web components). This does not cover other items that may be necessary to expand on such as CSS properties, custom tag, and events to name a few.

Requirements

1. JSON schema defined for a custom elements definition. An effort is already underway to conceptualize this here.
   • Should define the tag
   • Should define the attributes
   • Should define the slots (named and default)
   • Allows for validation when contributors are devising their own custom component definitions
   • Can be used to validate against any mappers that transform a custom element definition into a usable JSON schema for the <Form />
2. Mapper for any custom elements definition for the above JSON schema to transform it into a JSON schema for use in the <Form />

Implementation

Example JSON schema for custom element definitions, note that the tag item definition should be imported as its own schema to map against individual definitions written by users in the fast-comonents library:

{
    $schema: "http://json-schema.org/schema#",
    id: "custom-element-definition",
    title: "A definition for web components",
    type: "object",
    version: 1,
    required: ["version"],
    properties: {
        version: {
            title: "The version of the schema the web components map to",
            type: "number",
            enum: [1], // update this when new schema versions are released
        },
        tags: {
            type: "array",
                items: {
                    type: "object",
                    properties: {
                        name: {
                            type: "string"
                        },
                        description: {
                            type: "string"
                        },
                        attributes: {
                            type: "array",
                            items: {
                                type: "object",
                                properties: {
                                    name: {
                                        type: "string",
                                    },
                                    type: {
                                        type: "string",
                                    },
                                    description: {
                                        type: "string",
                                    },
                                    default: {
                                        type: "string",
                                    },
                                    required: {
                                        type: "boolean",
                                    },
                                }
                            }
                        },
                        slots: {
                            type: "array",
                            items: {
                                type: "object",
                                properties: {
                                    name: {
                                        type: "string"
                                    },
                                    description: {
                                        type: "string"
                                    },
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}

Example custom element definitions, note that these may be individual items in the fast-components library which are then compiled to this single definition:

{
    version: 1,
    tags: [
        {
            name: "fancy-button",
            description: "A fancier button",
            attributes: [
                {
                    name: "disabled",
                    type: "boolean",
                    description: "The disabled state",
                    default: "false",
                    required: false
                }
            ],
            slots: [
                {
                    name: "",
                    description: "The default slot, content in this slot displays directly inside the button"
                }
            ]
        }
    ]
}

Result of a mapper to make these definition usable in the message system, <Form />, and <Navigation />:

import { linkedDataSchema } from "@microsoft/fast-tooling";

{
    $schema: "http://json-schema.org/schema#",
    id: "fancy-button",
    mapsToTagName: "fancy-button",
    title: "The definition for fancy button custom element",
    type: "object",
    properties: {
        disabled: {
            mapsToAttribute: "disabled",
            title: "The disabled state",
            type: "boolean",
            default: false
        },
        // this should be generated in a way that avoids conflicts with attribute names
        // such as here, where attributes may not have uppercase in their naming
        Slot: {
            mapsToSlot: "", // the slot name this maps to
            title: "The default slot, content in this slot displays directly inside the button",
            ...linkedDataSchema
        }
    }
}