Feature: Snippet

[Yuyz0112]

What problem does this feature solve?

The snippet was proposed as an editor-level feature, which helps insert preset schema fragments into the current application.

A demo:

Kapture.2022-06-23.at.07.14.03.mp4

What does the proposed API look like?

Like other concepts, a snippet can be defined as a serializable spec.

An example:

{
  version: 'example/v1',
  kind: 'Snippet',
  metadata: {
    name: 'Tabs',
  },
  spec: {
    components: `[
      {
        "id": "root",
        "type": "chakra_ui/v1/root",
        "properties": {},
        "traits": []
      },
      {
        "id": "tabs",
        "type": "chakra_ui/v1/tabs",
        "properties": {
          "tabNames": [
            ~~@times(tabNum) => val~~
              "Tab ~~ val + 1 ~~"~~@if(val < tabNum - 1)~~,~~/if~~
            ~~/times~~
          ],
          "initialSelectedTabIndex": 0
        },
        "traits": [
          ~~@if(container)~~
          {
            "type": "core/v1/slot",
            "properties": {
              "container": {
                "id": "~~ container.id ~~",
                "slot": "~~ container.slot ~~"
              }
            }
          }
          ~~/if~~
        ]
      }
    ]`,
    values: {
      type: 'object',
      properties: {
        tabNum: {
          type: 'number',
          default: 2,
        },
        container: {
          type: 'object',
          properties: {
            id: {
              type: 'string',
              default: 'root',
            },
            slot: {
              type: 'string',
              default: 'root',
            },
          },
          required: ['id', 'slot'],
        },
      },
    },
  },
}

As the example shows, there are two things defined in a snippet's spec:

1. Components: a set of components' schema that will be inserted into an application schema's components array.
2. Values: variables that can be used in the snippet template.

Here comes a new concept: template string.
Since a snippet may have some customizable parts, we write the snippet components field as a template string, where ~~ ~~ means an interpretation tag. (Temporarily use ~~ to avoid conflict with the {{ }} expression syntax, but another char can replace it).

The values are defined in JSON schema, so the editor can use the SpecWidget to render a form from it.

User Story

The use case of the snippet feature is similar to traditional website templates. Vendors/developers provide beautiful and complex templates, users will download them and edit part of the code like title, logo, and theme.

Compare to traditional website templates, sunmao-ui's snippet feature:

1. Can scale from one component to a whole website.
2. Provide a low-code favor API: template + structured variables. So the editor can infer a form UI to input the variables. The design is largely inspired by the helm chart.

With snippets, vendors/developers can provide a set of snippets along with their sunmao-ui lib.

For example, a vendor like Twilio may create a sunmao-ui lib including message, video, voice, etc components. Then they can create a chatroom snippet that shows how to combine these components. They can define access token and theme colors as variables in the snippet, so users can start with the snippet without modifying components one by one.