Subscan Widget App

✨ Subscan Widget App is a platform to generate and configure data views by widgets. It has rich built-in widgets and support commonly used data sources, such as HTTP API, GraphQL, State, LocalStorage, etc.

Show Case

Take the Table component as an example:

1.Drag the Table component into the editing canvas

2.Configure the Table in inspect tab

Struct

src
 ┣ components  # react components
 ┣ config
 ┃ ┣ constants.ts
 ┃ ┗ runtime.ts  # editor default configured components libs
 ┣ editor  # editor interface
 ┃ ┣ LocalStorageManager.ts
 ┃ ┣ index.tsx
 ┃ ┗ services.ts # pro.subscan.io api
 ┣ hooks  # react hooks
 ┃ ┗ useStateValue.ts
 ┣ preview  # decoder interface
 ┣ widgets  # subscan widgets
 ┣ types
 ┣ ui   # theme, styled-components
 ┣ utils

User Docs

EN Docs

中文文档

Installation

yarn add @subscan/widget-app

import { Preview } from "@subscan/widget-app";
import '@subscan/widget-app/dist/main.css';

<Preview options={widgetJson} isDark={false} />

Available Scripts

In the project directory, you can run:

yarn start:local

Runs the app in the development mode.
Open http://localhost:3000 to view it in the browser.

The page will reload if you make edits.
You will also see any lint errors in the console.

yarn run build:local

Builds the app for production to the build folder.
It correctly bundles React in production mode and optimizes the build for the best performance.

The build is minified and the filenames include the hashes.
Your app is ready to be deployed!

See the section about deployment for more information.

Develop

# some useful yarn script could help you develop faster

# create a component
yarn run add:component -- --version custom/v1 --name button
# create a trait
yarn run add:trait -- --version custom/v1 --name validation
# create a util method
yarn run add:utilMethod -- --version custom/v1 --name alert

Subscan Components Storybook

# http://localhost:6006/
yarn storybook

Widget Spec

| parameter name | type | description | | -------------- | ------------- | ------------------------------------------------------------ | | version | string | The version of the same set of Components is usually the same. The format is "xxx/vx" , eg "core/v1". | | kind | "Component" | Fixed, indicating that this is a Component Spec. Calling implementRuntimeComponent does not require. | | metadata | | See below for details | | spec | | Array of Component Spe |

Component Spec

In Subscan Widget, it contains 2 basic concepts, a collection of functions is also a module exported by Editor, we call it Widget. The content that can be dragged in the right column of the Editor, we call it a Component, Widget is composed of multiple Components.

| parameter name | type | description | | -------------- | ------------- | ------------------------------------------------------------ | | version | string | The version of the same set of Components is usually the same. The format is "xxx/vx" , eg "core/v1". | | kind | "Component" | Fixed, indicating that this is a Component Spec. Calling implementRuntimeComponent does not require. | | metadata | | See below for details | | spec | | See below for details |

Metadata of Component Spec

Metadata contains the meta information of the Component.

| parameter name | type | remarks | | ----------------- | -------------------- | ------------------------------------------------------------ | | name | string | The name of the Component. The version and name of a Component together constitute the unique identifier of the Component. | | description | string? | | | displayName | string? | The name to display in the Component list in the Editor. | | exampleProperties | Record<string, any> | The initial properties for the Component when it was created in the Editor. | | annotations | Record<string, any>? | Some fields can be custom declared. |

Spec of Component Spec

When defining properties and state, we use JSONSchema. JSONSchema itself is JSON but can be used to declare the type of a JSON data structure. With type help, Widget Editor can checksum and autocomplete for parameters and expressions.

| parameter name | type | remarks | | -------------- | --------------------------------------- | ------------------------------------------------------------ | | properties | JSONSchema | Parameters accepted by Component. | | state | JSONSchema | State exposed by Component. | | methods | Record<KMethodName, JSONSchema> | Method exposed by Component. The key is the name of the Method, and the value is the parameter of the Method. | | events | string[] | Events that the Component will emit. The array element is the name of the Event. | | slots | Record<string, {slotProps: JSONSchema}> | Component reserved slots that can be inserted into child Component. | | styleSlots | string[] | Component Reserved slots for adding styles. |

Component Implementation Parameters

The parameter of Component Implementation is essentially an object, but it is actually a combination of several components. It can be roughly divided into:

| Parameter Name | Type | Remarks | Source | | --------------- | ------------------------------------------------------------ | ---------------------------------------------------------- | -------- | | component | ComponentSchema | Component's Schema | API | | app | ApplicationSchema | Schema of the entire Application | API | | slotsElements | Record<string, (slotProps: any) => ReactElement[]> | List of child Component | API | | mergeState | (partialState: object) => void | mergeState allows merging the internal state of the component into the global state. Get it through {{componentsId.state_name}} | API | | subscribeMethod | (methodsMap: Record<string, (params: object) => void>) => void | subscribeMethods is similar to mergeState to export methods to global. Components can trigger each other's internal methods through {{componentId.method_name}} | API | | elementRef | React.Ref | elementRef and getElement are to register the DOM elements with Widget. Widget implements many functions through the component's ref, such as the ability to highlight Components in the editor. | API | | getElement | (ele: HTMLElement) => void | same as above | API | | services | object | Various service instances of Widget. | services | | customStyle | Record<string, string> | Custom style from Trait | Trait | | callbackMap | Record<string, Function> | Callback function from Trait | Trait |

Services

Services are instances of Widget Editor's various services, including state management, event monitoring, component registration, and more. These Services are globally unique instances.

| parameter name | type | remarks | | ---------------- | ------------------------ | ------------------------------------------------------------ | | registry | Registry | All Widget Components, Traits, and Modules are registered on the Registry, where you can find their corresponding Spec and Implementation. | | stateManager | StateManager | StateManager manages global state store and also has the function of eval expression(stateManager.deepEval()). | | globalHandlerMap | GlobalHandlerMap | GlobalHandlerMap manages all Component Method instances. | | apiService | ApiService | ApiService is the global event bus. | | eleMap | Map<string, HTMLElement> | eleMap stores all Component's DOM elements. |

Links

Build-Local: https://subscan-widget-local.vercel.app/lowcode

Open Source Notice

We make extensive use of open source software for the various components of Subscan Widget. Open Source Credits

Learn More

Widget Editor

Create React App documentation

React documentation