chore: storybook docs

player-ui · Mar 25, 2024 · 2cfe251 · 2cfe251
1 parent 136a3c7
commit 2cfe251
Show file tree

Hide file tree

Showing 32 changed files with 1,429 additions and 15 deletions.
diff --git a/README.md b/README.md
@@ -24,7 +24,7 @@ To run the tests, you can run `bazel test //...`.
 
 ## Storybook
 
-We use Storybook for developing and showcasing the components. You can start the Storybook server by running `bazel run //docs/storybook:storybook`. Then, you can open your browser and navigate to `localhost:6006` to view the Storybook.
+We use Storybook for developing and showcasing the components. You can start the Storybook server by running `bazel run //docs/storybook:start`. Then, you can open your browser and navigate to `localhost:6006` to view the Storybook.
 
 ## Generating Assets
 

diff --git a/action/README.md b/action/README.md
@@ -0,0 +1,103 @@
+# @devtools-ui/action
+
+## Overview
+
+`@devtools-ui/action` is a component package designed to be leveraged by a [Player-UI assets plugin](https://player-ui.github.io/next/plugins).
+
+It provides a `Action` component that can be used to allow a user interaction (e.g., [transition](https://player-ui.github.io/next/content/navigation)), usually rendered as a `<button>`.
+
+## Installation
+
+To install `@devtools-ui/action`, you can use pnpm or yarn:
+
+```sh
+pnpm i @devtools-ui/action
+```
+
+or
+
+```sh
+yarn add @devtools-ui/action
+```
+
+## Usage
+
+You can leverage this asset through the `@devtools-ui/plugin`:
+
+```ts
+import { Action } from "@devtools-ui/plugin";
+
+// and use it to define your Player-UI content:
+myFlow = {
+  id: "my_flow",
+  views: [
+    <MyView>
+      <MyView.Actions>
+        <Action exp={e`noop`}>
+          <Action.Label>Label</Action.Label>
+          <Action.Icon>
+            <Asset type="icon">
+              <property name="value">SomeIcon</property>
+            </Asset>
+          </Action.Icon>
+        </Action>
+      </MyView.Actions>
+    </MyView>,
+  ],
+};
+```
+
+For more information on how to author Player-UI content using DSL, please check our [Player-UI docs](https://player-ui.github.io/next/dsl#tsxjsx-content-authoring-player-dsl).
+
+Or, your can leverage this asset in your own plugin:
+
+```ts
+// TransformPlugin.ts
+import type { Player, PlayerPlugin } from "@player-ui/player";
+import { AssetTransformPlugin } from "@player-ui/asset-transform-plugin";
+import { actionTransform } from "@devtools-ui/action";
+
+export class TransformsPlugin implements PlayerPlugin {
+  name = "my-plugin-transforms";
+
+  apply(player: Player) {
+    player.registerPlugin(
+      new AssetTransformPlugin([[{ type: "action" }, actionTransform]])
+    );
+  }
+}
+```
+
+```ts
+// AssetRegistryPlugin.ts
+import React from "react";
+import type { Player } from "@player-ui/player";
+import type {
+  ExtendedPlayerPlugin,
+  ReactPlayer,
+  ReactPlayerPlugin,
+} from "@player-ui/react";
+import { AssetProviderPlugin } from "@player-ui/asset-provider-plugin-react";
+import { TransformsPlugin } from "./TransformPlugin";
+import { ActionAsset, ActionComponent } from "@devtools-ui/action";
+
+export class AssetsRegistryPlugin
+  implements ReactPlayerPlugin, ExtendedPlayerPlugin<[ActionAsset]>
+{
+  name = "my-plugin";
+
+  applyReact(reactPlayer: ReactPlayer) {
+    reactPlayer.registerPlugin(
+      new AssetProviderPlugin([["action", ActionComponent]])
+    );
+  }
+
+  apply(player: Player) {
+    player.registerPlugin(new TransformsPlugin());
+  }
+}
+```
+
+## Contributing
+
+We welcome contributions to `@devtools-ui/action`!
diff --git a/action/src/types/index.ts b/action/src/types/index.ts
@@ -24,7 +24,7 @@ export interface ActionAsset extends Asset<"action"> {
     /** Button variant */
     variant?: Variant;
 
-    /**indicate a spinner for loading */
+    /** Indicate a spinner for loading */
     isLoading?: boolean;
 
     /** icon position */

diff --git a/template/BUILD.hbs → asset-template/BUILD.hbs b/template/BUILD.hbs → asset-template/BUILD.hbs
diff --git a/template/README.hbs → asset-template/README.md.hbs b/template/README.hbs → asset-template/README.md.hbs
diff --git a/template/package.json.hbs → asset-template/package.json.hbs b/template/package.json.hbs → asset-template/package.json.hbs
diff --git a/template/src/component/index.tsx.hbs → asset-template/src/component/index.tsx.hbs b/template/src/component/index.tsx.hbs → asset-template/src/component/index.tsx.hbs
diff --git a/...late/src/dsl/__tests__/index.test.tsx.hbs → ...late/src/dsl/__tests__/index.test.tsx.hbs b/...late/src/dsl/__tests__/index.test.tsx.hbs → ...late/src/dsl/__tests__/index.test.tsx.hbs
diff --git a/template/src/dsl/index.tsx.hbs → asset-template/src/dsl/index.tsx.hbs b/template/src/dsl/index.tsx.hbs → asset-template/src/dsl/index.tsx.hbs
diff --git a/template/src/index.ts.hbs → asset-template/src/index.ts.hbs b/template/src/index.ts.hbs → asset-template/src/index.ts.hbs
diff --git a/template/src/transform/index.ts.hbs → asset-template/src/transform/index.ts.hbs b/template/src/transform/index.ts.hbs → asset-template/src/transform/index.ts.hbs
diff --git a/template/src/types/index.ts.hbs → asset-template/src/types/index.ts.hbs b/template/src/types/index.ts.hbs → asset-template/src/types/index.ts.hbs
diff --git a/collection/README.md b/collection/README.md
@@ -0,0 +1,86 @@
+# @devtools-ui/collection
+
+## Overview
+
+`@devtools-ui/collection` is a component package designed to be leveraged by a [Player-UI assets plugin](https://player-ui.github.io/next/plugins).
+
+It provides a `Collection` component that can be used to group other Player assets into a stacked layout.
+
+## Installation
+
+To install `@devtools-ui/collection`, you can use pnpm or yarn:
+
+```sh
+pnpm i @devtools-ui/collection
+```
+
+or
+
+```sh
+yarn add @devtools-ui/collection
+```
+
+## Usage
+
+You can leverage this asset through the `@devtools-ui/plugin`:
+
+```ts
+import { Collection } from "@devtools-ui/plugin";
+
+// and use it to define your Player-UI content:
+myFlow = {
+  id: "my_flow",
+  views: [
+    <MyView>
+      <Collection>
+        <Collection.Values>
+          <Asset type="text">
+            <property name="value">Test 1</property>
+          </Asset>
+          <Asset type="text">
+            <property name="value">Test 2</property>
+          </Asset>
+        </Collection.Values>
+      </Collection>
+    </MyView>,
+  ],
+};
+```
+
+For more information on how to author Player-UI content using DSL, please check our [Player-UI docs](https://player-ui.github.io/next/dsl#tsxjsx-content-authoring-player-dsl).
+
+Or, your can leverage this asset in your own plugin:
+
+```ts
+// AssetRegistryPlugin.ts
+import React from "react";
+import type { Player } from "@player-ui/player";
+import type {
+  ExtendedPlayerPlugin,
+  ReactPlayer,
+  ReactPlayerPlugin,
+} from "@player-ui/react";
+import { AssetProviderPlugin } from "@player-ui/asset-provider-plugin-react";
+import { TransformsPlugin } from "./TransformPlugin";
+import { CollectionAsset, CollectionComponent } from "@devtools-ui/collection";
+
+export class AssetsRegistryPlugin
+  implements ReactPlayerPlugin, ExtendedPlayerPlugin<[CollectionAsset]>
+{
+  name = "my-plugin";
+
+  applyReact(reactPlayer: ReactPlayer) {
+    reactPlayer.registerPlugin(
+      new AssetProviderPlugin([["collection", CollectionComponent]])
+    );
+  }
+
+  apply(player: Player) {
+    player.registerPlugin(new TransformsPlugin());
+  }
+}
+```
+
+## Contributing
+
+We welcome contributions to `@devtools-ui/collection`!
diff --git a/docs/storybook/.storybook/main.ts b/docs/storybook/.storybook/main.ts
@@ -1,9 +1,19 @@
 import type { StorybookConfig } from "@storybook/react-vite";
+import remarkGfm from "remark-gfm";
 
 const config: StorybookConfig = {
   stories: ["../src/**/*.@(stories.@(js|tsx|ts))", "../src/**/*.mdx"],
   addons: [
-    "@storybook/addon-docs",
+    {
+      name: "@storybook/addon-docs",
+      options: {
+        mdxPluginOptions: {
+          mdxCompileOptions: {
+            remarkPlugins: [remarkGfm],
+          },
+        },
+      },
+    },
     "@storybook/blocks",
     "@player-ui/storybook-addon-player",
     "@chakra-ui/storybook-addon",

diff --git a/docs/storybook/BUILD b/docs/storybook/BUILD
@@ -21,6 +21,7 @@ deps = [
     "//:node_modules/@player-ui/data-change-listener-plugin",
     "//:node_modules/@player-ui/computed-properties-plugin",
     "//:node_modules/@chakra-ui/storybook-addon",
+    "//:node_modules/remark-gfm",
     ":node_modules/@player-ui/storybook-addon-player",
     ":node_modules/@devtools-ui/plugin",
 ]

diff --git a/docs/storybook/src/Welcome.mdx b/docs/storybook/src/Welcome.mdx
@@ -2,6 +2,70 @@ import { Meta } from "@storybook/blocks";
 
 <Meta title="Welcome" />
 
-Player is a framework for building cross-platform experiences. The main engine is written in Typescript, with platform specific adapters for iOS, Android, and React (web). It's built from the ground up with plugins in mind to perfectly tailor the experience specifically for your app.
+# Devtools-UI
 
-This storybook focuses on some example of using the React Player library, including some of the underlying plugins and references for building out apps using Player.
+Welcome to Devtools-UI, a monorepo containing a collection of assets packages and an assets plugin designed to be leveraged by [Player-UI](https://player-ui.github.io/).
+
+## Packages
+
+The packages in this repository are designed to be used as assets in Player-UI. Each package is self-contained and can be used independently.
+
+## Assets Plugin
+
+The assets plugin is a convenient way to use the assets packages in Player-UI. It provides a unified interface for managing and using the assets.
+
+It register the following assets to your React Player instance:
+
+- action
+- collection
+- input
+- list
+- navigation
+- object-inspector
+- text
+
+## Getting Started
+
+
+The easiest way to get started is to use the `@devtools-ui/plugin` package.
+
+## Installation
+
+To install `@devtools-ui/plugin`, you can use pnpm or yarn:
+
+```sh
+pnpm i @devtools-ui/plugin
+```
+
+or
+
+```sh
+yarn add @devtools-ui/plugin
+```
+
+## Usage
+
+You can leverage this plugin through the `@devtools-ui/plugin`:
+
+```ts
+import { ReactPlayer } from "@player-ui/react";
+import DevtoolsUIPlugin from "@devtools-ui/plugin";
+
+const reactPlayer = new ReactPlayer({
+  plugins: [new DevtoolsUIPlugin()],
+});
+```
+
+And leverage the DSL components to author your content:
+
+```tsx
+import { Collection, Text } from "@devtools-ui/plugin";
+
+const content = (
+  <Collection>
+    <Collection.Values>
+        <Text>My Collection</Text>
+    </List>
+  </Collection>
+);
+```
diff --git a/docs/storybook/src/assets/Action.mdx b/docs/storybook/src/assets/Action.mdx
@@ -5,18 +5,33 @@ import * as ActionStories from "./Action.stories";
 
 # Action Asset
 
-The `action` asset is used when you want a user to perform some _action_. It typically manifests as a `button` or `link` depending on the context, and intention.
+> type: `action`
+
+It provides a `Action` component that can be used to allow a user interaction (e.g., [transition](https://player-ui.github.io/next/content/navigation)), usually rendered as a `<button>`.
 
 Actions can advance Player's state machine using the `value` prop, and/or evaluate an expression using the `exp` prop.
 
+## DSL Properties
+
+| Property | Type | Required | Description |
+| --- | --- | --- | --- |
+| `value` | `string` | false | The value to transition to when the action is clicked |
+| `icon` | `AssetWrapper` | false | The icon to display on the action |
+| `label` | `AssetWrapper<TextAsset>` | false | A text asset for the action's label |
+| `exp` | `string` | false | The expression to evaluate when the action is clicked |
+| `metadata.skipValidation` | `boolean` | false | Force transition to the next view without checking for validation |
+| `metadata.variant` | `"solid" | "outline" | "ghost" | "link"` | false | Button variant |
+| `metadata.isLoading` | `boolean` | false | Indicate a spinner for loading |
+| `metadata.iconPosition` | `"left" | "right"` | false | Disable the action |
+
 ## Basic Use Case
 
-The example below uses the `exp` property to evaluate an expression when the action is clicked.
-This will increment the count, and update the label
+The example below uses the `exp` property to evaluate an expression when the action is clicked. This will increment the count, and update the label
 
 <Canvas of={ActionStories.Basic} />
 
 ## Navigation Transition
 
-<Canvas of={ActionStories.Transitions} />
+This example uses the `value` property to transition to a different scene when the action is clicked.
 
+<Canvas of={ActionStories.Transitions} />
diff --git a/docs/storybook/src/assets/Collection.mdx b/docs/storybook/src/assets/Collection.mdx
@@ -0,0 +1,20 @@
+import { Canvas, Meta } from '@storybook/blocks';
+import * as CollectionStories from "./Collection.stories";
+
+<Meta of={CollectionStories} />
+
+# Collection Asset
+
+> type: `collection`
+
+It provides a `Collection` component that can be used to group other Player assets into a stacked layout.
+
+## DSL Properties
+
+| Property | Type | Required | Description |
+| --- | --- | --- | --- |
+| `values` | `Array<AssetWrapper>` | false | list of assets in the collection |
+
+## Basic Use Case
+
+<Canvas of={CollectionStories.Basic} />
diff --git a/docs/storybook/src/assets/Input.mdx b/docs/storybook/src/assets/Input.mdx
@@ -0,0 +1,25 @@
+import { Canvas, Meta } from '@storybook/blocks';
+import * as InputStories from "./Input.stories";
+
+<Meta of={InputStories} />
+
+# Input Asset
+
+> type: `input`
+
+It provides an `Input` component that can be used to acquire data from the user.
+
+## DSL Properties
+
+| Property | Type | Required | Description |
+| --- | --- | --- | --- |
+| `binding` | `string` | false | The location in the data-model to store the data |
+| `label` | `AssetWrapper<TextAsset>` | false | A text asset for the action's label |
+| `note` | `AssetWrapper<TextAsset>` | false | Asset container for a note |
+| `size` | `"xs" | "sm" | "md" | "lg"` | false | Size of the Input height |
+| `placeholder` | `string` | false | A text asset for the input's placeholder |
+| `maxLength` | `number` | false | Max character length in the Input |
+
+## Basic Use Case
+
+<Canvas of={InputStories.Basic} />