-
+ {
+ "src" in Astro.props && (
+
diff --git a/docs/site/src/components/NavBar.astro b/docs/site/src/components/NavBar.astro
new file mode 100644
index 000000000..b754fbe15
--- /dev/null
+++ b/docs/site/src/components/NavBar.astro
@@ -0,0 +1,82 @@
+---
+import Default from "@astrojs/starlight/components/SocialIcons.astro";
+import type { Props } from "@astrojs/starlight/props";
+import VersionSelector from "./tools/VersionSelector";
+
+type SidebarEntry = (typeof Astro.props.sidebar)[number];
+
+function getFirstEntry(entry: SidebarEntry) {
+ if (entry.type === "group") {
+ if (entry.entries.length === 0) {
+ return;
+ }
+
+ return getFirstEntry(entry.entries[0]);
+ }
+
+ return entry;
+}
+
+function isCurrent(entry: SidebarEntry) {
+ if (entry.type === "link" && entry.isCurrent) {
+ return true;
+ }
+
+ if (entry.type === "group") {
+ return entry.entries.some((s): boolean => isCurrent(s));
+ }
+
+ return false;
+}
+
+const topEntries = Astro.props.sidebar.map((s) => ({
+ label: s.label,
+ href: getFirstEntry(s)?.href,
+ isCurrent: isCurrent(s),
+}));
+---
+
+
+
+
+ {
+ topEntries.map((entry) => {
+ return (
+
+ {entry.label}
+
+ );
+ })
+ }
+
+
+
+
+
+
+
+
+
+
+
+ {
+ TeamData.sort(() => 0.5 - Math.random()).map((teamMember) => (
+
diff --git a/docs/site/src/components/Sidebar.astro b/docs/site/src/components/Sidebar.astro
new file mode 100644
index 000000000..e24c5f974
--- /dev/null
+++ b/docs/site/src/components/Sidebar.astro
@@ -0,0 +1,61 @@
+---
+// https://github.com/lorenzolewis/starlight-utils/blob/main/packages/starlight-utils/components/Sidebar.astro
+import Default from "@astrojs/starlight/components/Sidebar.astro";
+import type { Props } from "@astrojs/starlight/props";
+import { AstroError } from "astro/errors";
+
+export type SidebarData = {
+ isCurrentSidebar: boolean;
+ starlightProps: Props;
+ labelEntry: Props["sidebar"][number];
+};
+
+const multiSidebarData: Array
+
+ ))
+ }
+
+ 
+
+
+
+ {teamMember.domain.join(", ")}
+
+
+ {teamMember.name}
+
+
+ );
+}
diff --git a/docs/site/src/components/tools/DSLContentPlayground.tsx b/docs/site/src/components/tools/DSLContentPlayground.tsx
new file mode 100644
index 000000000..8db8dad60
--- /dev/null
+++ b/docs/site/src/components/tools/DSLContentPlayground.tsx
@@ -0,0 +1,202 @@
+import { initialize, transform } from "esbuild-wasm/lib/browser";
+import * as React from "react";
+import * as PlayerDSL from "@player-tools/dsl";
+import * as ReferenceAssets from "@player-ui/reference-assets-plugin-components";
+import { loader, Editor } from "@monaco-editor/react";
+import stringify from "stringify-object";
+
+const { DSLCompiler } = PlayerDSL;
+
+const initialDSLContent = `import React from 'react';
+import { Info, Text } from '@player-ui/reference-assets-plugin-components';
+
+const view1 = (
+
+ {
+ try {
+ if (!value) {
+ setTree(undefined);
+ return;
+ }
+ setFlow(value);
+
+ const normalized = JSON5.parse(value);
+ const newAST = parser.parseView(normalized);
+ console.error(newAST);
+ setTree(newAST);
+ } catch (e) {
+ setTree(undefined);
+ }
+ }}
+ />
+
+ View (JSON)
+
+
+ View (AST)
+
+
+ );
+}
diff --git a/docs/site/src/components/tools/VersionSelector.tsx b/docs/site/src/components/tools/VersionSelector.tsx
new file mode 100644
index 000000000..98da4d13e
--- /dev/null
+++ b/docs/site/src/components/tools/VersionSelector.tsx
@@ -0,0 +1,62 @@
+import * as React from "react";
+import { BASE_PREFIX, DOCS_BASE_URL } from "./constants";
+
+interface VersionSelectorProps {
+ route: string;
+}
+
+const useGetReleasedVersions = () => {
+ const [releasedVersions, setReleasedVersions] = React.useState<
+ {
+ label: string;
+ path: string;
+ }[]
+ >([]);
+
+ React.useEffect(() => {
+ const send = async () => {
+ const response = await fetch(
+ "https://api.github.com/repos/player-ui/player-ui.github.io/contents/",
+ );
+
+ const data = await response.json();
+ const versions = data
+ .filter((d: any) => d.type === "dir" && d.name.match(/^\d/))
+ .map((d: any) => ({
+ label: d.name,
+ path: d.name,
+ }));
+ setReleasedVersions(versions);
+ };
+
+ send().catch(() => {});
+ }, []);
+
+ return releasedVersions;
+};
+const VersionSelector = (props: VersionSelectorProps) => {
+ const location = props.route;
+ const released = useGetReleasedVersions();
+
+ return (
+
+ );
+};
+
+export default VersionSelector;
diff --git a/docs/site/config/constants.ts b/docs/site/src/components/tools/constants.ts
similarity index 73%
rename from docs/site/config/constants.ts
rename to docs/site/src/components/tools/constants.ts
index 39f7bd4cd..5f67655cd 100644
--- a/docs/site/config/constants.ts
+++ b/docs/site/src/components/tools/constants.ts
@@ -1,5 +1,3 @@
-export const GITHUB_URL = "https://github.com/player-ui/player";
export const DOCS_BASE_URL = "https://player-ui.github.io/";
-
export const BASE_PREFIX: string | undefined =
process.env.NODE_ENV === "production" ? "DOCS_BASE_PATH" : undefined;
diff --git a/docs/site/src/components/tools/preview/PlayerPreview.tsx b/docs/site/src/components/tools/preview/PlayerPreview.tsx
new file mode 100644
index 000000000..563b08818
--- /dev/null
+++ b/docs/site/src/components/tools/preview/PlayerPreview.tsx
@@ -0,0 +1,96 @@
+import * as React from "react";
+import { ReferenceAssetsPlugin } from "@player-ui/reference-assets-plugin-react";
+import "@player-ui/reference-assets-plugin-react/dist/index.css";
+import { loader, Editor } from "@monaco-editor/react";
+import { ManagedPlayer, type Flow, type FlowManager } from "@player-ui/react";
+import { basicFlowManager } from "./sample-flow-manager";
+
+loader
+ .init()
+ .then((m) => {
+ m.languages.typescript.javascriptDefaults.setEagerModelSync(true);
+
+ // TODO: Re-add these when we can load `.d.ts` definitions into the editor
+ m.languages.typescript.typescriptDefaults.setDiagnosticsOptions({
+ noSemanticValidation: true,
+ noSyntaxValidation: true,
+ });
+ m.languages.typescript.typescriptDefaults.setCompilerOptions({
+ jsx: m.languages.typescript.JsxEmit.React,
+ });
+ })
+ .catch((e: unknown) => {
+ console.error("Error initializing monaco", e);
+ });
+
+export default function PlayerPreview() {
+ const theme = localStorage.getItem("starlight-theme") ?? "light";
+
+ const config = React.useMemo(
+ () => ({
+ plugins: [new ReferenceAssetsPlugin()],
+ }),
+ [],
+ );
+
+ const [completed, setCompleted] = React.useState(false);
+
+ const [currentFlow, setCurrentFlow] = React.useState
+ {
+ console.log(value);
+ try {
+ if (!value) {
+ setCompiledOutput(undefined);
+ return;
+ }
+ setDSLContent(value);
+
+ const code = await compileDSLCode(value);
+ console.log({ code });
+ setCompiledOutput(code);
+ setCompiledErrors(undefined);
+ } catch (e) {
+ console.error(e);
+ console.error("Compile Errors", e);
+ setCompiledErrors(e);
+ setCompiledOutput(undefined);
+ }
+ }}
+ />
+
+ Flow (DSL)
+
+
+ Compiled Flow (JSON)
+
+
+
+ );
+}
diff --git a/docs/site/src/components/tools/preview/flow-1.json b/docs/site/src/components/tools/preview/flow-1.json
new file mode 100644
index 000000000..5124d4e95
--- /dev/null
+++ b/docs/site/src/components/tools/preview/flow-1.json
@@ -0,0 +1,118 @@
+{
+ "id": "flow-1",
+ "views": [
+ {
+ "id": "view-1",
+ "type": "info",
+ "title": {
+ "asset": {
+ "id": "info-title",
+ "type": "text",
+ "value": "Welcome to Player"
+ }
+ },
+ "primaryInfo": {
+ "asset": {
+ "id": "info-primary",
+ "type": "collection",
+ "values": [
+ {
+ "asset": {
+ "id": "info-primary-1",
+ "type": "text",
+ "value": "This is some content inside of a Player view."
+ }
+ }
+ ]
+ }
+ },
+ "actions": [
+ {
+ "asset": {
+ "id": "action-next",
+ "type": "action",
+ "value": "Next",
+ "label": {
+ "asset": {
+ "id": "action-next-label",
+ "type": "text",
+ "value": "Next"
+ }
+ }
+ }
+ }
+ ]
+ },
+ {
+ "id": "view-2",
+ "type": "info",
+ "title": {
+ "asset": {
+ "id": "title",
+ "type": "text",
+ "value": "This is another page in the 1st flow."
+ }
+ },
+ "actions": [
+ {
+ "asset": {
+ "id": "action-back",
+ "type": "action",
+ "value": "Prev",
+ "label": {
+ "asset": {
+ "id": "action-back-label",
+ "type": "text",
+ "value": "Back"
+ }
+ }
+ }
+ },
+ {
+ "asset": {
+ "id": "action-next",
+ "type": "action",
+ "value": "Next",
+ "label": {
+ "asset": {
+ "id": "action-next-label",
+ "type": "text",
+ "value": "Next"
+ }
+ }
+ }
+ }
+ ]
+ }
+ ],
+ "navigation": {
+ "BEGIN": "FLOW_1",
+ "FLOW_1": {
+ "startState": "VIEW_1",
+ "VIEW_1": {
+ "state_type": "VIEW",
+ "ref": "view-1",
+ "transitions": {
+ "Prev": "END_Back",
+ "Next": "VIEW_2"
+ }
+ },
+ "VIEW_2": {
+ "state_type": "VIEW",
+ "ref": "view-2",
+ "transitions": {
+ "Prev": "VIEW_1",
+ "Next": "END_Done"
+ }
+ },
+ "END_Back": {
+ "state_type": "END",
+ "outcome": "back"
+ },
+ "END_Done": {
+ "state_type": "END",
+ "outcome": "done"
+ }
+ }
+ }
+ }
\ No newline at end of file
diff --git a/docs/site/src/components/tools/preview/flow-2.json b/docs/site/src/components/tools/preview/flow-2.json
new file mode 100644
index 000000000..bdd99af0c
--- /dev/null
+++ b/docs/site/src/components/tools/preview/flow-2.json
@@ -0,0 +1,83 @@
+{
+ "id": "flow-2",
+ "views": [
+ {
+ "id": "view-1",
+ "type": "info",
+ "title": {
+ "asset": {
+ "id": "info-title",
+ "type": "text",
+ "value": "This is the 2nd flow."
+ }
+ },
+ "primaryInfo": {
+ "asset": {
+ "id": "info-primary",
+ "type": "collection",
+ "values": [
+ {
+ "asset": {
+ "id": "info-primary-1",
+ "type": "text",
+ "value": "Note the delay between loading flows to emulate a network request/response"
+ }
+ }
+ ]
+ }
+ },
+ "actions": [
+ {
+ "asset": {
+ "id": "action-back",
+ "type": "action",
+ "value": "Prev",
+ "label": {
+ "asset": {
+ "id": "action-back-label",
+ "type": "text",
+ "value": "Back"
+ }
+ }
+ }
+ },
+ {
+ "asset": {
+ "id": "action-next",
+ "type": "action",
+ "value": "Next",
+ "label": {
+ "asset": {
+ "id": "action-next-label",
+ "type": "text",
+ "value": "Continue"
+ }
+ }
+ }
+ }
+ ]
+ }
+ ],
+ "navigation": {
+ "BEGIN": "FLOW_1",
+ "FLOW_1": {
+ "startState": "VIEW_1",
+ "VIEW_1": {
+ "state_type": "VIEW",
+ "ref": "view-1",
+ "transitions": {
+ "Prev": "END_Back",
+ "Next": "END_Done"
+ }
+ },
+ "END_Back": {
+ "state_type": "END",
+ "outcome": "back"
+ },
+ "END_Done": {
+ "state_type": "END",
+ "outcome": "done"
+ }
+ }
+ }
+ }
\ No newline at end of file
diff --git a/docs/site/src/components/tools/preview/flow-3.json b/docs/site/src/components/tools/preview/flow-3.json
new file mode 100644
index 000000000..5d8f96fc3
--- /dev/null
+++ b/docs/site/src/components/tools/preview/flow-3.json
@@ -0,0 +1,68 @@
+{
+ "id": "flow-3",
+ "views": [
+ {
+ "id": "view-1",
+ "type": "info",
+ "title": {
+ "asset": {
+ "id": "info-title",
+ "type": "text",
+ "value": "This is the 3nd and final flow in the series."
+ }
+ },
+ "actions": [
+ {
+ "asset": {
+ "id": "action-back",
+ "type": "action",
+ "value": "Prev",
+ "label": {
+ "asset": {
+ "id": "action-back-label",
+ "type": "text",
+ "value": "Back"
+ }
+ }
+ }
+ },
+ {
+ "asset": {
+ "id": "action-next",
+ "type": "action",
+ "value": "Next",
+ "label": {
+ "asset": {
+ "id": "action-next-label",
+ "type": "text",
+ "value": "Finish"
+ }
+ }
+ }
+ }
+ ]
+ }
+ ],
+ "navigation": {
+ "BEGIN": "FLOW_1",
+ "FLOW_1": {
+ "startState": "VIEW_1",
+ "VIEW_1": {
+ "state_type": "VIEW",
+ "ref": "view-1",
+ "transitions": {
+ "Prev": "END_Back",
+ "Next": "END_Done"
+ }
+ },
+ "END_Back": {
+ "state_type": "END",
+ "outcome": "back"
+ },
+ "END_Done": {
+ "state_type": "END",
+ "outcome": "done"
+ }
+ }
+ }
+ }
\ No newline at end of file
diff --git a/docs/site/components/player-demo/sample-flows/sample-flow-manager.tsx b/docs/site/src/components/tools/preview/sample-flow-manager.tsx
similarity index 98%
rename from docs/site/components/player-demo/sample-flows/sample-flow-manager.tsx
rename to docs/site/src/components/tools/preview/sample-flow-manager.tsx
index ed799b188..11b1cd716 100644
--- a/docs/site/components/player-demo/sample-flows/sample-flow-manager.tsx
+++ b/docs/site/src/components/tools/preview/sample-flow-manager.tsx
@@ -1,4 +1,4 @@
-import {
+import type {
FlowManager,
CompletedState,
Flow,
diff --git a/docs/site/src/content/config.ts b/docs/site/src/content/config.ts
new file mode 100644
index 000000000..a4eec59ba
--- /dev/null
+++ b/docs/site/src/content/config.ts
@@ -0,0 +1,6 @@
+import { defineCollection } from "astro:content";
+import { docsSchema } from "@astrojs/starlight/schema";
+
+export const collections = {
+ docs: defineCollection({ schema: docsSchema() }),
+};
diff --git a/docs/site/pages/assets/cross-platform.mdx b/docs/site/src/content/docs/assets/cross-platform.mdx
similarity index 65%
rename from docs/site/pages/assets/cross-platform.mdx
rename to docs/site/src/content/docs/assets/cross-platform.mdx
index b95fc26c3..ebd54084c 100644
--- a/docs/site/pages/assets/cross-platform.mdx
+++ b/docs/site/src/content/docs/assets/cross-platform.mdx
@@ -1,16 +1,14 @@
---
-title: 'User Player Across Platforms'
+title: Using Player Across Multiple Platforms
---
-# Using Player Across Multiple Platforms
-
One of the major benefits of adopting Player for rendering a UI is it's ability to function across all the platforms Player supports (React, Android, iOS) using the same content. In order to facilitate this, and get the most out of Player's architecture, here's a few things to keep in mind as you integrate Player into multiple platforms.
## Use Core Plugins to Share Functionality
-One of the easiest, and most beneficial thing to do when integrating Player is to organize feature sets into plugins. Keeping each plugin small and concise allows for easy sharing of features with other Player integrations. Player Core, as well as each of the platform integration, supplies an interface for users to augment/extend the functionality of Player. This can be used to author validations, formatters, expressions, etc once, and be shared across Player implementations across platforms. As Player Core runs on every platform, any core Player plugin will also run on every platform which allows for shared functionality to be authored once and shared across every platform.
+One of the easiest, and most beneficial thing to do when integrating Player is to organize feature sets into plugins. Keeping each plugin small and concise allows for easy sharing of features with other Player integrations. Player Core, as well as each of the platform integration, supplies an interface for users to augment/extend the functionality of Player. This can be used to author validations, formatters, expressions, etc once, and be shared across Player implementations across platforms. As Player Core runs on every platform, any core Player plugin will also run on every platform which allows for shared functionality to be authored once and shared across every platform.
-Plugins such as the [common-types plugin](../plugins/common-types) is a great example of a plugin used to add a feature to Player in a reusable way. Since the validations, formats, and data-types present in this plugin are authored in Player Core, we eliminate the need to rewrite them to target each individual platform. Using this mechanism, we also guaranteed that the React, iOS, and Android Player configurations are able to process the same content in the same way across the systems. The most important usecase of this is the asset transforms. Writing the logic to transform the asset as authored in content to the UI representation in the shared transform layer moves repeated functionality to the shared layer decreasing the implementation complexity of each asset on every platform but still leaves room for rendering variability for each platform.
+Plugins such as the [common-types plugin](/plugins/core/common-types) is a great example of a plugin used to add a feature to Player in a reusable way. Since the validations, formats, and data-types present in this plugin are authored in Player Core, we eliminate the need to rewrite them to target each individual platform. Using this mechanism, we also guaranteed that the React, iOS, and Android Player configurations are able to process the same content in the same way across the systems. The most important usecase of this is the asset transforms. Writing the logic to transform the asset as authored in content to the UI representation in the shared transform layer moves repeated functionality to the shared layer decreasing the implementation complexity of each asset on every platform but still leaves room for rendering variability for each platform.
## Use the meta-plugin to simplify plugin sets
@@ -22,6 +20,6 @@ and
> features/expressions/validations added in 1 are automatically present in the other platforms without any additional work.
-*If each plugin implements a single, small feature, how are we able to add new features to each platform without requiring additional work?*
+_If each plugin implements a single, small feature, how are we able to add new features to each platform without requiring additional work?_
-One pattern that we've found to work well is to continue to organize each feature into individual plugins/modules. This allows any application to opt-in to an individual feature, and makes sharing much, much simpler. In addition to this, we also create 1 more plugin using the meta-plugin to wrap all of the application's feature requirements into 1 plugin. This allows additional plugins to to be added to the meta-plugin and each platform will still only require 1 plugin registered (which makes integration easy) while still allowing the individual pieces to be consumed if desired (which makes extensibility easy)
\ No newline at end of file
+One pattern that we've found to work well is to continue to organize each feature into individual plugins/modules. This allows any application to opt-in to an individual feature, and makes sharing much, much simpler. In addition to this, we also create 1 more plugin using the meta-plugin to wrap all of the application's feature requirements into 1 plugin. This allows additional plugins to to be added to the meta-plugin and each platform will still only require 1 plugin registered (which makes integration easy) while still allowing the individual pieces to be consumed if desired (which makes extensibility easy)
diff --git a/docs/site/pages/assets/custom.mdx b/docs/site/src/content/docs/assets/custom.mdx
similarity index 89%
rename from docs/site/pages/assets/custom.mdx
rename to docs/site/src/content/docs/assets/custom.mdx
index 5b9d7b4b3..c91cba540 100644
--- a/docs/site/pages/assets/custom.mdx
+++ b/docs/site/src/content/docs/assets/custom.mdx
@@ -1,13 +1,13 @@
---
-title: 'Custom Assets'
+title: "Custom Assets"
---
-# Custom Assets
+import PlatformTabs from "../../../components/PlatformTabs.astro";
One of the conscious design decisions we made when building Player was to abstract away the actual asset implementation and open it up for users to bring their own when using Player. This way you can seamlessly integrate Player into your existing experiences and reuse UI assets you may have already built. Below we've outlined the way to build custom assets on the various platforms Player supports.
+
+ Content
+
+
+ Player View
+
+
+
+ {completed && Loading...
}>
+ Done with demo
}
+ {!completed && (
+
+
{props.text}
);
@@ -29,9 +29,9 @@ Assuming your authored JSON has a string property named text, this will render t
Now that we have a React component to render our asset, let's create a plugin to register with Player:
-import AssetProviderPlugin from '@player-ui/asset-provider-plugin-react';
-
```javascript
+import AssetProviderPlugin from "@player-ui/asset-provider-plugin-react";
+
class CustomAssetPlugin implements ReactPlayerPlugin{
applyReact(reactPlayer) {
new AssetProviderPlugin([['custom', CustomAssetComp]]).applyReact(reactPlayer);
@@ -48,11 +48,11 @@ Often times, assets contain a reference or slot to another asset. For this to fu
Use the ReactAsset Component from the `@player-ui/react` package with the nested asset as props to dynamically determine the rendering implementation to use:
```jsx
-import { ReactAsset } from '@player-ui/react';
+import { ReactAsset } from "@player-ui/react";
const CustomAssetComp = (props) => {
return (
-
+
+
+
SwiftUI Player assets are made of 3 parts:
-- [Data](/#Data): Decodable AssetData
-- [View](/#View): A SwiftUI View
-- [Asset](/#Asset): SwiftUIAsset implementation to tie the two together
+- [Data](#data): Decodable AssetData
+- [View](#view): A SwiftUI View
+- [Asset](#asset): SwiftUIAsset implementation to tie the two together
[Registering Your Asset](#registering-your-asset): Additional Topic
@@ -217,21 +217,20 @@ struct SomeView: View {
If your experience will be used on multiple platforms, it is not advised to use this method, a transform will ensure the same logic is followed on all 3 platforms and is strongly encouraged.
-
-
+
+
In order to render an asset a renderer for that type must be registered in the Android Player. If a renderer is found, then Player will delegate rendering when that type is encountered, otherwise Player will skip that node. Creating and registering such a renderer requires the following:
1. [Extending DecodableAsset](#extending-decodableasset)
- 1. [Implementing `initView` and `hydrate`](#implementing-initview)
- 2. [Define data structure](#accessing-data)
- 3. [Nested assets](#nested-assets)
- 4. [Styling](#styling)
+ 1. [Implementing `initView` and `hydrate`](#implementing-initview)
+ 2. [Define data structure](#accessing-data)
+ 3. [Nested assets](#nested-assets)
+ 4. [Styling](#styling)
2. [Registering assets](#registering-your-asset)
### Extending DecodableAsset
-
`DecodableAsset` is a subclass of `RenderableAsset` that contains data decoding capabilities built on [Kotlinx Serialization](https://github.com/Kotlin/kotlinx.serialization). This is the recommended approach for creating an asset and will be consolidated with `RenderableAsset` in future versions of the Android Player. On top of the requirements for subclassing `RenderableAsset`, subclassing `DecodableAsset` requires passing a `KSerializer` for the data class that represents the data for that asset.
`RenderableAsset` is the base structure used by Player to convert parsed content into Android Views. Each implementation is instantiated with an `AssetContext` and is required to implement two methods, `initView` and `hydrate`. The separation of logic between these two methods allow for views to be cached and optimize the render process. However, both of these methods are only used internally via the `render` method. `render` is the main entry point for getting the Android view representation of that asset. It automatically handles the caching and hydration optimizations, only rebuilding and rehydrating when a dependency has changed. The caller would be responsible for handling that view (i.e. injecting it into a ViewGroup).
@@ -293,16 +292,18 @@ val stringToRender: String = asset.getString("value")
```json
// ...
{
- "id": "some-card",
- "type": "card",
- "title": {
- "asset": {
- "id": "some-text",
- "type": "text",
- "value": "This is a text asset"
- }
+ "id": "some-card",
+ "type": "card",
+ "title": {
+ "asset": {
+ "id": "some-text",
+ "type": "text",
+ "value": "This is a text asset"
}
+ }
}
+
+
// ...
```
@@ -351,16 +352,15 @@ fun View.hydrate() {
}
```
-
+
-
### Registering your Asset
When registering your asset with an `AssetRegistry`, it can either be registered as a new type, if it is an entirely new construct, or registered as a variant of an existing asset type, to only be rendered under certain conditions.
-
+
```tsx
// Using AssetProviderPlugin from '@player-ui/asset-provider-plugin-react'
@@ -370,21 +370,21 @@ new AssetProviderPlugin([
//This will register a match on { type: 'example', metaData: {"role": "someRole"} }
[{ type: 'example', metaData: {"role": "someRole"}}, ExampleAsset])
```
-
-
+
+
```swift
// Convenience function for just registering for type
player.assetRegistry.register("example", asset: ExampleAsset.self)
-// Registers the type with the metaData present with someRole
+// Registers the type with the metaData present with someRole
player.assetRegistry.register(["type": "example", "metaData": ["role": "someRole"]], for: ExampleAsset.self)
```
-
-
+
+
Registering assets is done in the `AndroidPlayerPlugin`. Each plugin only needs to implement an `apply` method which gives the plugin the opportunity to supplement core player functionality. The `AndroidPlayer` instance contains an asset registry where assets should be register. A helper method has been created to make registration as simple as providing the type and a factory. The factory method must take an AssetContext, and is recommended to just be the constructor of your asset.
@@ -397,7 +397,7 @@ val map = mapOf("type" to "example", "metaData" to mapOf("role" to "someRole"))
androidPlayer.assetRegistry.set(map, ::ExampleAsset)
```
-
+
In the latter case, it is recommended to extend the original asset, so as to avoid boilerplate for data and construction, and just override the render function. If your variant will have additional data decoded that the original asset does not have, you will need to create the whole asset.
@@ -411,27 +411,26 @@ In the latter case, it is recommended to extend the original asset, so as to avo
For more info on transform registration see [Asset Transform Plugin](https://player-ui.github.io/latest/plugins/asset-transform#asset-transform-plugin)
### Use Cases
+
Below are 3 different use cases for different ways to mix and match the asset and transform registry to simplify the asset implementation
#### Use Case 1: Same type with different variants and asset implementations that can share the same transform
-
-
-
+
- ```tsx
+```tsx
// Using AssetProviderPlugin from '@player-ui/asset-provider-plugin-react'
new AssetProviderPlugin([
- //This will register a match on { type: 'example' }
- ['example', ExampleAsset],
- //This will register a match on { type: 'example', metaData: {"role": "someRole"} }
- [{ type: 'example', metaData: {"role": "someRole"}}, ExampleAsset]
- ])
+ //This will register a match on { type: 'example' }
+ ["example", ExampleAsset],
+ //This will register a match on { type: 'example', metaData: {"role": "someRole"} }
+ [{ type: "example", metaData: { role: "someRole" } }, ExampleAsset],
+]);
```
-
-
+
+
```swift
player.assetRegistry.register("input", asset: InputAsset.self)
@@ -439,44 +438,43 @@ player.assetRegistry.register("input", asset: InputAsset.self)
player.assetRegistry.register(["type": "input", "dataType": ["type": "DateType"]], for: DateInputAsset.self)
```
-
-
+
+
- ```kotlin
+```kotlin
androidPlayer.registerAsset("input", ::InputAsset)
val map = mapOf("type" to "input", "dataType" to mapOf("type" to "DateType"))
androidPlayer.assetRegistry.set(map, ::DateInputAsset)
```
-
-
+
If the common InputData fields for the decoded data looks like:
-
+
Taken from the reference asset Input Asset example, see [full transform implementation](https://github.com/player-ui/player/blob/main/plugins/reference-assets/core/src/assets/input/transform.ts)
+
```tsx
export interface InputAsset {
- id: String
- type: String
- value: String?
+ id: String;
+ type: String;
+ value: String?;
}
export interface TransformedInput extends InputAsset {
/** A function to commit the new value to the data-model */
- set: (newValue: ValueType) => void;
+ set: (newValue: ValueType) => void;
/** The `DataType` associated with this asset, for formatting the keyboard */
dataType?: DataType;
}
```
-
-
-
+
+
The InputData used in Swift and Android is using the TransformedInput which includes the original web input properties plus additional transform specific properties
@@ -492,8 +490,8 @@ struct InputData: AssetData {
}
```
-
-
+
+
The InputData used in Swift and Android is using the TransformedInput which includes the original web input properties plus additional transform specific properties
@@ -508,18 +506,15 @@ data class InputData(
)
```
-
+
And we would like to render two different assets based on whether or not "dataType" is present then both InputAsset and DateInputAsset can share the same InputData which can contain a transform (such as the function to perform after input data is set) but show different content for the views such as input accessories like a calender based on the DataType
-
#### Use Case 2: Same type with different variants and asset implementations that don't share the same transform
-
-
-
+
```tsx
// Using AssetProviderPlugin from '@player-ui/asset-provider-plugin-react'
@@ -529,9 +524,8 @@ new AssetProviderPlugin([
])
```
-
-
-
+
+
```swift
player.assetRegistry.register("input", asset: InputAsset.self)
@@ -539,8 +533,8 @@ player.assetRegistry.register("input", asset: InputAsset.self)
player.assetRegistry.register(["type": "input", "dataType": ["type": "DateType"]], for: DateInputAsset.self)
```
-
-
+
+
```kotlin
androidPlayer.registerAsset("input", ::InputAsset)
@@ -549,37 +543,37 @@ val map = mapOf("type" to "input", "dataType" to mapOf("type" to "DateType"))
androidPlayer.assetRegistry.set(map, ::DateInputAsset)
```
-
+
If the common InputData fields for the decoded data looks like:
-
+
```tsx
export interface InputAsset {
- id: String
- type: String
- value: String?
+ id: String;
+ type: String;
+ value: String?;
}
export interface DateInputAsset {
- id: String
- type: String
- value: String?
+ id: String;
+ type: String;
+ value: String?;
}
// Used in the transform function for inputTranform
export interface TransformedInput extends InputAsset {
/** A function to commit the new value to the data-model */
- set: (newValue: ValueType) => void;
+ set: (newValue: ValueType) => void;
}
// Used in the transform function for inputDateTranform
export interface TransformedDateInput extends DateInputAsset {
- /** A function to commit the new value to the data-model */
- set: (newValue: ValueType) => void;
+ /** A function to commit the new value to the data-model */
+ set: (newValue: ValueType) => void;
/** The `DataType` associated with this asset, for formatting the keyboard */
dataType?: DataType;
}
@@ -588,8 +582,8 @@ export interface TransformedDateInput extends DateInputAsset {
In the case where the regular InputAsset and the DateInputAsset should not share the same transform, its possible to target the variant in the transform registration (since transform also use the partial match registry) to specify a different transform when the "dataType" is present for example:
```tsx
-import { Player } from '@player-ui/player';
-import { AssetTransformPlugin } from '@player-ui/asset-transform-plugin';
+import { Player } from "@player-ui/player";
+import { AssetTransformPlugin } from "@player-ui/asset-transform-plugin";
// Add it to Player
@@ -598,17 +592,17 @@ const player = new Player({
new AssetTransformPlugin(
new Registry([
// Register a match for any input type with a custom transform.
- [{ type: 'input' }, inputTransform],
+ [{ type: "input" }, inputTransform],
// Register a match for any input type that has dataType DateType with a custom transform.
- [{ type: 'input', "dataType": {type: "DateType"} }, dateInputTransform]
- ])
- )
- ]
-});
+ [{ type: "input", dataType: { type: "DateType" } }, dateInputTransform],
+ ]),
+ ),
+ ],
+});
```
-
-
+
+
The InputData used in Swift and Android is using the TransformedInput which includes the original web input properties plus additional transform specific properties
@@ -624,8 +618,8 @@ struct InputData: AssetData {
}
```
-
-
+
+
The InputData used in Swift and Android is using the TransformedInput which includes the original web input properties plus additional transform specific properties
@@ -640,29 +634,24 @@ data class InputData(
)
```
-
+
-
-
#### Use Case 3: Different type, same asset implementation, different transforms
-
-
-
+
- ```tsx
+```tsx
// Using AssetProviderPlugin from '@player-ui/asset-provider-plugin-react'
new AssetProviderPlugin([
- ['choiceA', Choice],
- ['choiceB', Choice]
-])
+ ["choiceA", Choice],
+ ["choiceB", Choice],
+]);
```
-
-
-
+
+
```swift
player.assetRegistry.register("choiceA", asset: ChoiceAsset.self)
@@ -670,8 +659,8 @@ player.assetRegistry.register("choiceA", asset: ChoiceAsset.self)
player.assetRegistry.register("choiceB", asset: ChoiceAsset.self)
```
-
-
+
+
```kotlin
androidPlayer.registerAsset("choiceA", ::ChoiceAsset)
@@ -679,7 +668,7 @@ androidPlayer.registerAsset("choiceA", ::ChoiceAsset)
androidPlayer.registerAsset("choiceB", ::ChoiceAsset)
```
-
+
Its possible to register the same asset implementation to different type names with the same variant, this may be needed if the two types visually look the same but behaviourally is different such as when the choice is clicked "choiceA" does one action but "choiceB" does something else which is defined in the transform
@@ -687,7 +676,7 @@ Its possible to register the same asset implementation to different type names w
Since the transform is called on "select" of the `WrappedFunction` or `Invokable` in the data this doesnt change the ChoiceData (only the values of select function itself change depending on if we get ChoiceA or ChoiceB) which means they can both be registered to ChoiceAsset
-
+
```jsx
export interface Choice {
@@ -706,8 +695,8 @@ Create two transforms choiceATransform and choiceBTransform that both return Tra
Then in the web transform registration choiceA and choiceB are registered to those different transforms
```jsx
-import { Player } from '@player-ui/player';
-import { AssetTransformPlugin } from '@player-ui/asset-transform-plugin';
+import { Player } from "@player-ui/player";
+import { AssetTransformPlugin } from "@player-ui/asset-transform-plugin";
// Add it to Player
@@ -716,19 +705,20 @@ const player = new Player({
new AssetTransformPlugin(
new Registry([
// Register a match for any choiceA type with a custom transform.
- [{ type: 'choiceA' }, choiceATransform],
+ [{ type: "choiceA" }, choiceATransform],
// Register a match for any choiceB type with a custom transform.
- [{ type: 'choiceB' }, choiceBTransform]
- ])
- )
- ]
-});
+ [{ type: "choiceB" }, choiceBTransform],
+ ]),
+ ),
+ ],
+});
```
-
-
+
+
The ChoiceData used in Swift and Android is using the TransformedChoice which includes the original web choice properties plus additional transform specific properties
+
```swift
struct ChoiceData: AssetData {
var id: String
@@ -739,10 +729,11 @@ struct ChoiceData: AssetData {
}
```
-
-
+
+
The ChoiceData used in Swift and Android is using the TransformedChoice which includes the original web choice properties plus additional transform specific properties
+
```kotlin
@Serializable
data class ChoiceData(
@@ -754,9 +745,7 @@ data class ChoiceData(
)
```
-
+
-
-
Overall the asset and transform registry gives developers a lot of flexibility for extending and simplifying assets based on given constraints
diff --git a/docs/site/pages/assets/dsl.mdx b/docs/site/src/content/docs/assets/dsl.mdx
similarity index 80%
rename from docs/site/pages/assets/dsl.mdx
rename to docs/site/src/content/docs/assets/dsl.mdx
index d83da32ca..7b890770f 100644
--- a/docs/site/pages/assets/dsl.mdx
+++ b/docs/site/src/content/docs/assets/dsl.mdx
@@ -2,24 +2,22 @@
title: Writing DSL Components
---
-# Creating TSX Components
-
In order to take advantage of the auto-completion and validation of TypeScript types, asset libraries can export a component library for content authoring. Creating components isn't much different than writing a React component for the web. The primative elements uses the [react-json-reconciler](https://github.com/intuit/react-json-reconciler) to create the JSON content tree, with utilities to make it quick and painless to create new asset-components.
-
## Creating a Basic Component
The `Asset` component from the `@player-tools/dsl` package is the quickest way to create a new component. The `Asset` component will take all the Asset's properties and convert them to their equivalent JSON representation when serialized.
-In the examples below, we'll be creating a TSX component for the `action` asset in our reference set.
+In the examples below, we'll be creating a TSX component for the `action` asset in our reference set.
The `action` asset has a `label` slot (which is typically used as a `text` asset), a `value` (for flow transitions), and an `exp` for evaluating expressions.
For this example we'll use a resemblance of this type, but in practice types should be imported directly from their asset rather than duplicating them.
```ts
-import type { Asset, AssetWrapper, Expression } from '@player-ui/player';
+import type { Asset, AssetWrapper, Expression } from "@player-ui/player";
-export interface ActionAsset extends Asset<'action'> {
+export interface ActionAsset
+ extends Asset<"action"> {
/** The transition value of the action in the state machine */
value?: string;
@@ -36,26 +34,26 @@ _Note: The `Asset` type we're importing here from the `@player-ui/player` packag
To turn this interface into a usable component, create a new React component that _renders_ an Asset:
```tsx
-import { Asset, AssetPropsWithChildren } from '@player-tools/dsl';
+import { Asset, AssetPropsWithChildren } from "@player-tools/dsl";
export const Action = (props: AssetPropsWithChildren) => {
return
@@ -105,20 +103,20 @@ const myView = (
);
```
-which when compiled would look like (note the auto injection of the `Text` asset and corresponding Asset Wrapper):
+When compiled, both examples would look like (note the auto injection of the `Text` asset and corresponding Asset Wrapper):
```json
{
- "id": "root",
- "type": "action",
- "value": "next",
- "label": {
- "asset": {
- "id": "root-label-text",
- "type": "text",
- "value": "Continue"
- }
+ "id": "root",
+ "type": "action",
+ "value": "next",
+ "label": {
+ "asset": {
+ "id": "root-label-text",
+ "type": "text",
+ "value": "Continue"
}
+ }
}
```
@@ -128,8 +126,8 @@ And if we wanted to have the `label` property to have to text assets we could wr
const myView = (
- Some
- Text
+ Some
+ Text
);
@@ -139,30 +137,31 @@ which when compiled would look like the following (note the automatic insertion
```json
{
- "id": "root",
- "type": "action",
- "value": "next",
- "label": {
- "asset": {
- "id": "root-collection",
+ "id": "root",
+ "type": "action",
+ "value": "next",
+ "label": {
+ "asset": {
+ "id": "root-collection",
+ "type": "text",
+ "values": [
+ {
+ "asset": {
+ "id": "root-collection-1-text",
+ "type": "text",
+ "value": "Some"
+ }
+ },
+ {
+ "asset": {
+ "id": "root-collection-2-text",
"type": "text",
- "values": [
- {
- "asset": {
- "id": "root-collection-1-text",
- "type": "text",
- "value": "Some"
- }
- },{
- "asset": {
- "id": "root-collection-2-text",
- "type": "text",
- "value": "Text"
- }
- }
- ]
+ "value": "Text"
+ }
}
+ ]
}
+ }
}
```
@@ -170,18 +169,18 @@ which when compiled would look like the following (note the automatic insertion
While a majority of Assets can be described simply via the base `Action` Component, there are certain cases where DSL components need to contain a bit more logic. This section aims to describe further tools that are offered in the `@player-tools/dsl` package.
-### Components with Specially Handled Properties
+### Components with Specially Handled Properties
-In the previous example, we covered how to create a DSL Component for our reference `Action` Asset. Our actual Action Asset however looks a little bit different.
+In the previous example, we covered how to create a DSL Component for our reference `Action` Asset. Our actual Action Asset however looks a little bit different.
```tsx
-import React from 'react';
+import React from "react";
export const Action = (
- props: Omit, 'exp'> & {
+ props: Omit, "exp"> & {
/** An optional expression to execute before transitioning */
exp?: ExpressionTemplateInstance;
- }
+ },
) => {
const { exp, children, ...rest } = props;
@@ -196,12 +195,10 @@ export const Action = (
Crucially, the difference is in how the `exp` property is handled. As the `exp` property is an `Expression`, if we just allowed the `Action` component to process this property, we would end up with an `ExpressionTemplate` instance _not_ an `Expression` instance. While technically they are equivalent, there is no need to wrap the final string in the Expression Template tags (`@[]@`) since we know the string will be an `Expression` and it will just lead to additonal procssing at runtime. Therefore, we need to do a few things to properly construct this DSL component.
-The first is to modify the type for the commponent. In the above code snippit we are using the `Omit` type to remove the base `exp` property from the source type and replacing it with an `exp` property that expects a `ExpressionTemplateInstance` which allows an DSL expression to be passed in.
+The first is to modify the type for the commponent. In the above code snippit we are using the `Omit` type to remove the base `exp` property from the source type and replacing it with an `exp` property that expects a `ExpressionTemplateInstance` which allows an DSL expression to be passed in.
The second is to extract out the `exp` property from the props and use a `property` component to manually control how that property will get serialized. This component is exposed by the underlying `react-json-reconciler` library which also supplies an `array`, `obj` and `value` component to allow full control over more complicated data structures. The `@player-tools/dsl` package also exposes the `toJsonProperties` function to process whole non-Asset objects.
### View Components
For Assets that are intended to be Views, a `View` component is exported from the `@player-tools/dsl` package. Its usage is exactly the same as the `Asset` component, however it correctly handles the serialization of any Crossfield Validations that exist on the View.
-
-
diff --git a/docs/site/pages/assets/index.mdx b/docs/site/src/content/docs/assets/index.mdx
similarity index 72%
rename from docs/site/pages/assets/index.mdx
rename to docs/site/src/content/docs/assets/index.mdx
index cf3f9fe5b..af837b02b 100644
--- a/docs/site/pages/assets/index.mdx
+++ b/docs/site/src/content/docs/assets/index.mdx
@@ -1,8 +1,9 @@
---
-title: 'Assets'
+title: "Assets"
---
-# Assets
+import Image from "../../../components/Image.astro";
+import assetPartsImage from "../../../assets/asset-parts.png";
An asset is a generic term given to a semantic bit of information that we wish to convey to the user. Assets are the backbone that make up the content that Player renders. Though there are many different types of assets, they all follow the same basic principles:
@@ -19,7 +20,7 @@ There are a few key components that make up an asset:
- How it interacts with Player
- How it should render
-
+
-
+
For the React Player, we ship a package (`@player-ui/reference-assets-plugin-react`) that provides the reference set of assets. Each asset package exposes a `Component`, type, and optional transform. They also export hooks for easily consuming the transformed component and supplying your own UI for a custom look and feel. These components are all then exposed via a plugin that can be added to Player like so:
```javascript
-import { ReactPlayer } from '@player-ui/react';
-import { ReferenceAssetsPlugin } from '@player-ui/reference-assets-plugin-react';
+import { ReactPlayer } from "@player-ui/react";
+import { ReferenceAssetsPlugin } from "@player-ui/reference-assets-plugin-react";
const reactPlayer = new ReactPlayer({
plugins: [new ReferenceAssetsPlugin()],
@@ -24,8 +25,8 @@ const reactPlayer = new ReactPlayer({
The reference assets + React player can be viewed in [Storybook](/storybook-demo)
-
-
+
+
Alongside distributing the `PlayerUI` pod, there is a `PlayerUI/ReferenceAssets` subspec used as examples of how Player APIs work for building assets. This pod uses the shared TypeScript transform functions that the React and Android players use for their reference assets, ensuring consistent behavior across platforms. These assets can be loaded into Player like so:
@@ -45,8 +46,8 @@ struct MyApp: View {
}
```
-
-
+
+
Alongside distributing the Android Player framework, there is a reference assets library used as an example of how Player APIs work for building assets. These are intended to serve as a reference, but can be used early on in development as a means of understanding how to work with Player. This asset set uses the shared TypeScript transform functions that the Web and Android players use for their reference assets, ensuring consistent behavior across platforms. These assets can be loaded into Player like so:
@@ -55,6 +56,6 @@ import com.intuit.playerui.android.reference.assets.ReferenceAssetsPlugin
val player = AndroidPlayer(context, ReferenceAssetsPlugin())
```
-
-
+
+
diff --git a/docs/site/src/content/docs/assets/transforms.mdx b/docs/site/src/content/docs/assets/transforms.mdx
new file mode 100644
index 000000000..1a0c926a2
--- /dev/null
+++ b/docs/site/src/content/docs/assets/transforms.mdx
@@ -0,0 +1,44 @@
+---
+title: "Transforms"
+---
+
+import Image from "../../../components/Image.astro";
+import assetPipelineImage from "../../../assets/simple-diagram-asset.png";
+import assetWithoutTransformImage from "../../../assets/no-transform.png";
+import assetWithTransformImage from "../../../assets/pipeline-with-transform.png";
+
+This guide will walk through a few of the core concepts of assets, transforms and how they come together with the UI to create an experience.
+
+You can read more about what an asset is [here](/content/assets-views). In short:
+
+> An asset is a generic term given to a semantic bit of information that we wish to convey to the user. Assets are the primitive elements that make up the content that players present as user experiences.
+
+For all intents and purposes, views are equivalent to assets for this guide.
+
+## Assets and the UI
+
+In general, the pipeline for user-content is something like:
+
+
+
+```tsx
+import { Asset } from '@player-tools/dsl';
+
+
+
+
+
+
+```
+
+
+
```json
{
"id": "parent",
@@ -30,21 +46,43 @@ Nested assets are represented as objects containing an `asset` property. For exa
}
}
```
+
+
The `label` of the parent contains a nested asset reference. These are _slots_ that can usually contain any asset type.
-# Views
+## Views
Views are _assets_ that exist at the top level of the tree. They typically include the navigation actions, a title, or other top-level information.
The `id` of the views are used in the navigation section to reference a specific view from the list.
-## Cross-field validation
+### Cross-field validation
-The other special property of a `view` vs. an `asset` is the addition of a `validation` property on the view. These contain [`validation` objects](/schema) that are used for validations crossing multiple fields, and are ran on user navigation rather than data change.
+The other special property of a `view` vs. an `asset` is the addition of a `validation` property on the view. These contain [`validation` objects](../schema#validation) that are used for validations crossing multiple fields, and are ran on user navigation rather than data change.
Example:
+
+
+```tsx
+import { View, expression as e, binding as b } from '@player-tools/dsl';
+
+
+
```json
{
...
@@ -63,6 +101,8 @@ Example:
]
}
```
+
+
They follow the same guidelines for normal validation references, with the addition of a `ref` property that points to the binding that this validation is tied to.
@@ -70,20 +110,20 @@ They follow the same guidelines for normal validation references, with the addit
Any object in the tree (including _assets_) may contain an `applicability` property. This is an _expression_ that may conditionally show or hide an asset (and all of it's children) from the view tree. Applicability is dynamically calculated and will automatically update as data changes on the page.
-# Switches
+## Switches
-Switches are ways of dynamically changing the structure of the view based on data. There are 2 types of switches: `static` and `dynamic`, but their structures are identical. `switches` can appear anywhere you'd find a normal asset, and (similar to [templates](./templates)) are removed from the view before it reaches the UI layer.
+Switches are ways of dynamically changing the structure of the view based on data. There are 2 types of switches: `static` and `dynamic`, but their structures are identical. `switches` can appear anywhere you'd find a normal asset, and (similar to [templates](./#templates)) are removed from the view before it reaches the UI layer.
-## Usage
+### Usage
The switch is simply a list of objects with `case` and `asset` properties:
- `asset` - The asset that will replace the switch if the case is true
-- `case` - An [expression](./expression) to evaluate.
+- `case` - An [expression](../data-expressions#expressions) to evaluate.
The switch will run through each _case_ statement until the first case expression evaluates to true. For the _default_ case, simple use a value of `true` at the end of the array.
-## Static v Dynamic Switches
+### Static v Dynamic Switches
The only difference between a `static` and `dynamic` switch is the timing update behavior after the first rendering of a view.
@@ -91,15 +131,37 @@ A `staticSwitch` calculates the applicable case when a view first renders. It wi
A `dynamicSwitch` will always update the applicable case statement whenever data changes. If data is changed while a view is still showing, the switch will be updated to reflect the new case.
-## Example
+### Example
Anywhere you can place an `asset` node, a `dynamicSwitch` or `staticSwitch` can be placed instead.
+
+
+```tsx
+import { Switch, Asset, expression as e, binding as b } from '@player-tools/dsl';
+
+
+
+
+
+
+
+
+
+
+````
+
+
+
+
```json
{
"staticSwitch": [
{
- "case": "{{name.first}} == 'adam'",
+ "case": "{{name.first}} == 'John'",
"asset": {
"id": "name",
"type": "text",
@@ -107,7 +169,7 @@ Anywhere you can place an `asset` node, a `dynamicSwitch` or `staticSwitch` can
}
},
{
- "case": "{{name.first}} == 'notadam'",
+ "case": "{{name.first}} == 'Jane'",
"asset": {
"id": "name",
"type": "text",
@@ -124,13 +186,16 @@ Anywhere you can place an `asset` node, a `dynamicSwitch` or `staticSwitch` can
}
]
}
-```
+````
-# Templates
+
+
+
+## Templates
Templates provide a way to dynamically create a list of assets, or _any_ object, based on data from the model. All of the templating semantics are removed by the time it reaches an asset's transform or UI layer.
-## Usage
+### Usage
Within any asset, specify a `template` property as an array of:
@@ -141,7 +206,7 @@ Within any asset, specify a `template` property as an array of:
Within a template, the `_index_` string can be used to substitute the array-index of the item being mapped.
-### Example
+#### Example
**Authored**
@@ -194,17 +259,17 @@ Within a template, the `_index_` string can be used to substitute the array-inde
}
```
-## Multiple templates
+### Multiple templates
There's a few ways to leverage multiple templates within a single asset. Templates can be _nested_ or multiple used on a single node. These can also be combined to build out complicated nested expansion.
-### Nested Templates
+#### Nested Templates
Templates can contain other templates. When referencing a nested template, append the template depth to the `_index_` string to reference the correct data-item.
For example, if 1 template contains another, use `_index_` to reference the outer-loop, and `_index1_` to reference the inner loop. Furthermore, if templates are nested three levels deep, the first level loop will still be referenced by `_index_`, the second level will be referenced by `_index1_` and the bottom most loop will be referenced by `_index2_`.
-### Multiple Templates - Single Output
+#### Multiple Templates - Single Output
Templates will, by default, create an array, if needed, for the `output` property of each template. If that array already exits (either by manually writing it in the JSON, or from a previous template run), each item will be appended to the end of the existing array.
@@ -282,7 +347,7 @@ The template below will append it's values to the pre-existing `values` array.
}
```
-## Dynamic and Static Templates
+### Dynamic and Static Templates
Like switches, the only difference between a `static` and `dynamic` template is the timing update behavior after the first rendering of a view. If not defined, the value of `dynamic` is default to `false`.
@@ -316,8 +381,8 @@ If `dynamic` is `true`, template will be always updated whenever data changes. I
```
```typescript
-model.set([['list.of.names', ['Jain']]]);
-model.set([['list.of.names', ['Jain', 'Erica']]]);
+model.set([["list.of.names", ["Jain"]]]);
+model.set([["list.of.names", ["Jain", "Erica"]]]);
```
**Output**
diff --git a/docs/site/pages/content/data-expressions.mdx b/docs/site/src/content/docs/content/data-expressions.mdx
similarity index 84%
rename from docs/site/pages/content/data-expressions.mdx
rename to docs/site/src/content/docs/content/data-expressions.mdx
index 988d9fabd..1552a54b6 100644
--- a/docs/site/pages/content/data-expressions.mdx
+++ b/docs/site/src/content/docs/content/data-expressions.mdx
@@ -2,11 +2,11 @@
title: Data & Expressions
---
-# Data
+## Data
Data is central to a lot of the functionality and features of Player. The easiest way to deal with data is to supply it in the initial payload when starting a flow. This will _seed_ the model with data and allow you to easily reference values
-## Bindings
+### Bindings
A binding is a representation of a path within the data-model. In simple terms, it's a dot (`.`) separated string showing the path of the properties within the data object.
@@ -39,7 +39,7 @@ For most bindings, it is recommended to use the dot-notation for all properties
Note that you can also use integers to access into arrays in the data model. `foo.bar.array.0.property` will reference `"another value"`.
-### Query Syntax
+#### Query Syntax
Bindings also allow for query access into arrays using a `key`/`value` pair to find the first matching item in the array.
@@ -50,16 +50,16 @@ data: {
model: {
array: [
{
- name: 'alpha',
- foo: 'bar',
+ name: "alpha",
+ foo: "bar",
},
{
- name: 'bravo',
- foo: 'baz',
+ name: "bravo",
+ foo: "baz",
},
{
- name: 'charlie',
- foo: 'qux',
+ name: "charlie",
+ foo: "qux",
},
];
}
@@ -76,7 +76,7 @@ Quotes around the key or the value of the query are only required when needing t
Note that the query syntax resolves to the object of the matching query, not to any specific property on the object. If you want to access a specific property, add additional path information after the query. E.g., `model.array[name=bravo].name`.
-### Nested Bindings
+#### Nested Bindings
Nested bindings allow you to construct a binding path that is relative to a 2nd path or based on some dynamic property. This behavior follows similar model lookup rules that can be used elsewhere in Player.
@@ -106,7 +106,7 @@ With this data model, `colors.{{favorite.color}}.hex` will return the hex value
References to bindings that contains sub-paths `{{favorite.nestedPath}}.hex` will expand to `colors.yellow.hex`.
-### Nested Expressions
+#### Nested Expressions
Just like binding segments can contain other bindings, segments can also contain expressions. For this, they use a segment surrounded by `:
@@ -122,15 +122,15 @@ Similar to the bracket notation: `[]`. Paths can use brackets instead of dots fo
colors[`getFavoriteColor()`].hex
```
-# Expressions
+## Expressions
Expressions are callable functions that allow for dynamic behavior of Player and it's views.
These functions can be used in `ACTION` nodes in the navigation section, calculated values in a property of an asset, or anywhere else expressions are valid.
-Check out the [Expression Plugin](../plugins/expression) for registering custom functions.
+Check out the [Expression Plugin](/plugins/core/expression) for registering custom functions.
-## Using Expressions and Data in a View
+### Using Expressions and Data in a View
Expressions in the view are strings wrapped in: `@[` and `]@`.
@@ -158,7 +158,7 @@ Data is referenced by wrapping the binding in `{{` and `}}`. This can be used in
Similar to expressions, any property only consisting of a data value lookup, will get replaced by the raw value.
-## Using Expressions for Inline Text Formatting
+### Using Expressions for Inline Text Formatting
`format` expression is used to replace provided value with appropriate format.
For instance, to format a number into `currency`, you may use:
@@ -169,45 +169,49 @@ For instance, to format a number into `currency`, you may use:
}
```
-To see the list of currently supported format types, check out [Common Types Plugin](../plugins/common-types.md).
+To see the list of currently supported format types, check out [Common Types Plugin](/plugins/core/common-types).
-## Built-in Expressions
+### Built-in Expressions
-There are a few expressions built into Player. These are pretty basic, so if you're looking for extend this -- check out the [Common Expressions Plugin](../plugins/common-expressions) or the [Expression Plugin](../plugins/expression) to add more.
+There are a few expressions built into Player. These are pretty basic, so if you're looking for extend this -- check out the [Common Expressions Plugin](/plugins/core/common-expressions) or the [Expression Plugin](/plugins/core/expression) to add more.
-| name | description | arguments |
-| --------------- | ------------------------------------------------------------------------------------- | ------------------ |
-| `getDataVal` | Fetches a value from the model. This is equivalent to using the `{{foo.bar}}` syntax. | `binding` |
-| `setDataVal` | Sets a value from the model. This is equivalent to using `{{foo.bar}} = 'value'` | `binding`, `value` |
-| `deleteDataVal` | Clears a value from the model. | `binding` |
+| name | description | arguments |
+| --------------- | ------------------------------------------------------------------------------------- | ------------------------------------------ |
+| `getDataVal` | Fetches a value from the model. This is equivalent to using the `{{foo.bar}}` syntax. | `binding` |
+| `setDataVal` | Sets a value from the model. This is equivalent to using `{{foo.bar}} = 'value'` | `binding`, `value` |
+| `deleteDataVal` | Clears a value from the model. | `binding` |
| `conditional` | Execute expressions, or return data based on an expression condition | `condition`, `valueIfTrue`, `valueIfFalse` |
-### Examples
+#### Examples
+
+##### `getDataVal`
-#### `getDataVal`
```json
{
"value": "Hello @[getDataVal('user.name')]@"
}
```
-#### `setDataVal`
+##### `setDataVal`
+
```json
{
"exp": "setDataVal('user.name', 'Test User')"
}
```
-#### `deleteDataVal`
+##### `deleteDataVal`
+
```json
{
"exp": "deleteDataVal('user.name')"
}
```
-#### `conditional`
+##### `conditional`
+
```json
{
"value": "It is @[ conditional({{foo.bar}} == 'DAY', 'daytime', 'nighttime') ]@."
}
-```
\ No newline at end of file
+```
diff --git a/docs/site/pages/content/index.mdx b/docs/site/src/content/docs/content/index.mdx
similarity index 98%
rename from docs/site/pages/content/index.mdx
rename to docs/site/src/content/docs/content/index.mdx
index e351cc0b9..8d219f196 100644
--- a/docs/site/pages/content/index.mdx
+++ b/docs/site/src/content/docs/content/index.mdx
@@ -1,9 +1,7 @@
---
-title: 'Content'
+title: "Content"
---
-# Content
-
Player is driven off of JSON content that describes the user interactions. It mainly consists of a state-machine, some views to drive display, data, and a schema. Player, once started with the JSON content, will _play_ the flow until it reaches a terminal state in the state-machine, and return the outcome, data, and other relevant information about the flow's execution.
The structure of the JSON payload is described below.
diff --git a/docs/site/pages/content/navigation.mdx b/docs/site/src/content/docs/content/navigation.mdx
similarity index 88%
rename from docs/site/pages/content/navigation.mdx
rename to docs/site/src/content/docs/content/navigation.mdx
index fdb040844..9c34bf3dc 100644
--- a/docs/site/pages/content/navigation.mdx
+++ b/docs/site/src/content/docs/content/navigation.mdx
@@ -2,7 +2,8 @@
title: Navigation
---
-# Navigation
+import Image from "../../../components/Image.astro";
+import simpleFlowImage from "../../../assets/simple-flow.png";
The `navigation` section of the content describes the path the user goes through as they progress. In simple terms, this can be thought of as a set of finite state machines, and the user progresses through each state until they hit a `DONE` node.
@@ -100,9 +101,9 @@ State types can also contain `onStart` and `onEnd` properties for evaluating exp
1. `onStart` - Evaluated at the start of a node's lifecycle; useful for updating data before it's resolved
2. `exp`
-3. `onEnd` - Evaluated last, right before transition.
- 1. For an `onEnd` expression defined on an individual state, if a transition is halted (by validation or otherwise), the `onEnd` expressions for that state won't be executed.
- 2. As Player's navigation is a state machine, `onEnd` expressions defined for the entire flow will only execute when the state machine ends the flow, by reaching an `END` state. Terminating the flow by unmounting Player (on any given platform) will not execute flow defined `onEnd` expressions as it would not have reached an `END` state.
+3. `onEnd` - Evaluated last, right before transition.
+ 1. For an `onEnd` expression defined on an individual state, if a transition is halted (by validation or otherwise), the `onEnd` expressions for that state won't be executed.
+ 2. As Player's navigation is a state machine, `onEnd` expressions defined for the entire flow will only execute when the state machine ends the flow, by reaching an `END` state. Terminating the flow by unmounting Player (on any given platform) will not execute flow defined `onEnd` expressions as it would not have reached an `END` state.
## Examples
@@ -130,7 +131,7 @@ State types can also contain `onStart` and `onEnd` properties for evaluating exp
This is the simplest of flows. The navigation begins with executing `FLOW_1`. `FLOW_1` begins with the `VIEW_1` state. `VIEW_1` shows the view with id `view-1`, and any transition from that view goes to `END_1` which completes Player's execution with the `Done` outcome.
-
+
-
+
You can do this by running
@@ -26,8 +26,9 @@ or
npm install @player-ui/react
npm install @player-ui/reference-assets-plugin-react
```
-
-
+
+
+
In your `Podfile` you'll need to add `PlayerUI` as a dependency and the `ReferenceAssets` plugin to use the base set of assets.
@@ -40,8 +41,9 @@ target 'MyApp' do
pod 'PlayerUI/ReferenceAssets' # For example only
end
```
-
-
+
+
+
Configure the Android Player dependencies in your `build.gradle(.kts)` files.
@@ -73,21 +75,24 @@ buildTypes {
}
}
```
-
+
+
-
-
+
```javascript
-import { ReactPlayer } from '@player-ui/react';
-import { ReferenceAssetsPlugin } from '@player-ui/reference-assets-plugin-react';
+import { ReactPlayer } from "@player-ui/react";
+import { ReferenceAssetsPlugin } from "@player-ui/reference-assets-plugin-react";
// create a new web-player instance
@@ -95,8 +100,9 @@ const reactPlayer = new ReactPlayer({
plugins: [new ReferenceAssetsPlugin()],
});
```
-
-
+
+
+
`SwiftUIPlayer` is just a normal SwiftUI View and can be inserted anywhere in your hierarchy.
@@ -109,9 +115,10 @@ var body: some View {
)
}
```
-
-
+
+
+
```kotlin
// create Android Player with reference assets plugin
@@ -122,24 +129,29 @@ val player = AndroidPlayer(
)
)
```
+
Apart from providing a list of plugins while setting up `AndroidPlayer`, you can also provide a `config` object that has the following options:
- - `debuggable` - Indicates if the runtime is debuggable on android through chromium devtools, enabling this would let you set breakpoints in js code as you're running it on android.
- - `coroutineExceptionHandler` - [CoroutineExceptionHandler](https://kotlinlang.org/docs/exception-handling.html#coroutineexceptionhandler) should handle all uncaught exceptions while using the runtime coroutine scope.
- - `timeout` - Timeout for the JS thread. If none is provided then it is set as `if (debuggable) Int.MAX_VALUE.toLong() else 5000`.
+- `debuggable` - Indicates if the runtime is debuggable on android through chromium devtools, enabling this would let you set breakpoints in js code as you're running it on android.
+- `coroutineExceptionHandler` - [CoroutineExceptionHandler](https://kotlinlang.org/docs/exception-handling.html#coroutineexceptionhandler) should handle all uncaught exceptions while using the runtime coroutine scope.
+- `timeout` - Timeout for the JS thread. If none is provided then it is set as `if (debuggable) Int.MAX_VALUE.toLong() else 5000`.
+
+
-
### Render Content
+
Now that you have a Player instance created. You'll need to start it with some [content](/content).
-
+
```javascript
-const content = {/* your content here */}
+const content = {
+ /* your content here */
+};
reactPlayer.start(content);
```
@@ -150,8 +162,9 @@ const MyApp = () => {
return
-
+
+
+
Expanding on the `SwiftUIPlayer` creation above, providing a `flow` will start the Player automatically, and the `result` will update the `Binding?>` that you pass to it:
@@ -170,8 +183,9 @@ struct MyApp: View {
}
}
```
-
-
+
+
+
To receive view updates, you must add a handler to render the views which are represented as `RenderableAsset`s.
@@ -192,7 +206,7 @@ When you're done with Player, release any native runtime memory used to instanti
player.release()
```
-Creating your own `AndroidPlayer` instance is fairly simple, but it grows in complexity when considering proper resources management and app orchestration. We provide a Fragment/ViewModel integration to make it easier to properly integrate into your app and account for these concerns.
+Creating your own `AndroidPlayer` instance is fairly simple, but it grows in complexity when considering proper resources management and app orchestration. We provide a Fragment/ViewModel integration to make it easier to properly integrate into your app and account for these concerns.
#### ViewModel
@@ -228,13 +242,15 @@ As the core Player is written in TypeScript, we need a JVM compatible JavaScript
To support a specific runtime implementation, there needs to be code connecting the runtime constructs to the Player runtime abstraction. The Player project has implemented this layer for several runtimes, described below. It is possible to define your own, but the abstraction definition is not yet final, and therefore not appropriately documented. You can take inspiration from the existing implementations, or file an issue for a runtime you wish to see supported by our team.
-| Runtimes | Platforms |
-| -------- | --------- |
+| Runtimes | Platforms |
+| --------------------------------------------- | --------------------------- |
| [J2V8](https://github.com/eclipsesource/J2V8) | `android`, `linux`, `macos` |
-| [Hermes](https://github.com/facebook/hermes) | `android` |
-| [GraalJS](https://github.com/oracle/graaljs) | `linux`, `macos`, `win` |
+| [Hermes](https://github.com/facebook/hermes) | `android` |
+| [GraalJS](https://github.com/oracle/graaljs) | `linux`, `macos`, `win` |
-
-
+:::caution
+If your application includes dependencies that may transitively depend on `com.intuit.playerui:android`, you would likely need to ensure the default runtime is transitively excluded from those as well, either manually or as a global strategy.
+:::
-Congrats! You've got Player up and running. If you need additional functionality you can add more plugins to extend Player's functionality. Head over to the [Plugins](./plugins) section to take a look at the Plugins we've developed or take a look at the [Architecture](./architecture) section to see how you can write your own.
+
+
+Congrats! You've got Player up and running. If you need additional functionality you can add more plugins to extend Player's functionality. Head over to the [Plugins](/plugins) section to take a look at the Plugins we've developed or take a look at the [Architecture](./architecture) section to see how you can write your own.
\ No newline at end of file
diff --git a/docs/site/pages/guides/multi-flow-experiences.mdx b/docs/site/src/content/docs/guides/multi-flow-experiences.mdx
similarity index 75%
rename from docs/site/pages/guides/multi-flow-experiences.mdx
rename to docs/site/src/content/docs/guides/multi-flow-experiences.mdx
index d11a9ebfc..ba19cf709 100644
--- a/docs/site/pages/guides/multi-flow-experiences.mdx
+++ b/docs/site/src/content/docs/guides/multi-flow-experiences.mdx
@@ -2,16 +2,17 @@
title: Multi-Flow Experiences
---
-# Multi-Flow Experiences
-
-One large use-case for Player involves orchestrating experiences that span multiple screens that may need to communicate with a back-end between stages. This is commonly used for stepped-flows, onboarding workflows, etc, and manifests as using the response from one Player flow to determine the next one. To facilitate this back-and-forth, Player ships with support for creating a flow-manager.
+import PlatformTabs from "../../../components/PlatformTabs.astro";
+import Image from "../../../components/Image.astro";
+import flowManagerImage from "../../../assets/flow-manager.png";
+One large use-case for Player involves orchestrating experiences that span multiple screens that may need to communicate with a back-end between stages. This is commonly used for stepped-flows, onboarding workflows, etc, and manifests as using the response from one Player flow to determine the next one. To facilitate this back-and-forth, Player ships with support for creating a flow-manager.
## Flow Manager
-A flow-manager is an interface for asynchronously stepping through a series of flows in a multi-flow experience. Its API mirrors that of the JavaScript [iteration protocol](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols); each flow is loaded by calling `.next()` using the result of the previous flow (if one exists). Implementations are able to leverage this response to retrieve the _next_ flow in the series, or mark the cycle as complete by returning `done`.
+A flow-manager is an interface for asynchronously stepping through a series of flows in a multi-flow experience. Its API mirrors that of the JavaScript [iteration protocol](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols); each flow is loaded by calling `.next()` using the result of the previous flow (if one exists). Implementations are able to leverage this response to retrieve the _next_ flow in the series, or mark the cycle as complete by returning `done`.
-
+
-
+
-The `ManagedPlayer` component from the `@player-ui/react` module orchestrates running flows through Player using a provided `flow-manager`. Any provided configuration/plugins will be passed along to the underlying `ReactPlayer` instance, and `React.Suspense` is used while awaiting the next `flow-manager` response.
+The `ManagedPlayer` component from the `@player-ui/react` module orchestrates running flows through Player using a provided `flow-manager`. Any provided configuration/plugins will be passed along to the underlying `ReactPlayer` instance, and `React.Suspense` is used while awaiting the next `flow-manager` response.
-Simply render the `ManagedPlayer` with a flow-manager:
+Simply render the `ManagedPlayer` with a flow-manager:
```tsx
-import { ManagedPlayer } from '@player-ui/react';
+import { ManagedPlayer } from "@player-ui/react";
export const App = () => {
- return
+
-
-
-
-The `ManagedPlayer` SwiftUI Component from the `PlayerUI/SwiftUI` subspec orchestrates running flows through Player using a provided `FlowManager`. Any provided configuration or plugins are passed along to the underlying `SwiftUIPlayer` instance.
+The `ManagedPlayer` SwiftUI Component from the `PlayerUI/SwiftUI` subspec orchestrates running flows through Player using a provided `FlowManager`. Any provided configuration or plugins are passed along to the underlying `SwiftUIPlayer` instance.
When constructing the `ManagedPlayer` you supply views to be used for error scenarios, as well as what is displayed while the FlowManager is fetching flows.
### Error Handling
+
The `fallback` parameter receives a `ManagedPlayerErrorContext` object when called, this object contains the `Error` that was thrown, as well as `retry` and `reset` functions.
-* `retry` -- Retries the last failed request (the last call to `next()`)
-* `reset` -- Restarts the multi-flow from the begining, calling `next()` with an empty context.
+- `retry` -- Retries the last failed request (the last call to `next()`)
+- `reset` -- Restarts the multi-flow from the begining, calling `next()` with an empty context.
```swift
import PlayerUI
@@ -93,5 +94,5 @@ struct App: View {
}
```
-
+
diff --git a/docs/site/pages/plugin-implementation.mdx b/docs/site/src/content/docs/guides/plugin-implementation.mdx
similarity index 69%
rename from docs/site/pages/plugin-implementation.mdx
rename to docs/site/src/content/docs/guides/plugin-implementation.mdx
index 575c46d25..be93d4704 100644
--- a/docs/site/pages/plugin-implementation.mdx
+++ b/docs/site/src/content/docs/guides/plugin-implementation.mdx
@@ -2,11 +2,9 @@
title: Plugin Implementation
---
-# Plugin Implementation
-
The main purpose of a Plugin is to extend or add new functionality by tapping into Player's pipeline of components via hooks. In this section we'll go over the steps to implement a plugin.
-We'll use the [stage-revert-data](./plugins/stage-revert-data) plugin as example. After creating our plugin class, we'll use the `apply` method which provides access to the Player instance, which then gives access to the necessary hooks.
+We'll use the [stage-revert-data](/plugins/core/stage-revert-data) plugin as example. After creating our plugin class, we'll use the `apply` method which provides access to the Player instance, which then gives access to the necessary hooks.
```typescript
export default class StageRevertDataPlugin implements PlayerPlugin {
@@ -29,7 +27,9 @@ export default class StageRevertDataPlugin implements PlayerPlugin {
{ shouldIncludeInvalid: () => true }
);
```
+
For this case we needed to define variables that will store references for the scope the hooks will share:
+
- `dataController`: Reference to the data controller hook in the Player instance, can be used to read, update or commit new changes to the data model
- `stageData`: View attribute that comes from the view state, used for enabling the staging of data
- `commitTransitions`: The list of view names which the shadow model should be committed if transitioned to. Comes from the view state attribute as well.
@@ -39,54 +39,56 @@ For this case we needed to define variables that will store references for the s
The next step is to tap into the necessary Player hooks. First we tap into the `viewController` which we can then intercept the `resolveView` hook. Player hooks are implemented with the [Tapable](https://github.com/webpack/tapable) package, so we can use the interception API's `call` method, this triggers everytime the hook is triggered, then we get access to the current view state and read the `stageData` and `commitTransitions` attributes.
```typescript
- player.hooks.viewController.tap(this.name, (vc) => {
- vc.hooks.resolveView.intercept({
- call: (view, id, state) => {
- stageData = state?.attributes?.stageData;
- commitTransitions = state?.attributes?.commitTransitions;
- },
- });
- });
+player.hooks.viewController.tap(this.name, (vc) => {
+ vc.hooks.resolveView.intercept({
+ call: (view, id, state) => {
+ stageData = state?.attributes?.stageData;
+ commitTransitions = state?.attributes?.commitTransitions;
+ },
+ });
+});
```
+
`Note`: notice how each time we tap into a hook, we use the `this.name` property as the name of the plugin. This is important to avoid conflicts with other plugins.
Next we tap into the `dataController`, so we can scope the data controller instance for future use. Then we tap into the `resolveDataStages` plugin in this data controller instance. If the `stage` property is set to true, we add our `GatedDataMiddleware` to the data pipeline. If not, we return the data pipeline as is.
```typescript
- player.hooks.dataController.tap(this.name, (dc: DataController) => {
- dataController = dc;
-
- dc.hooks.resolveDataStages.tap(this.name, (dataPipeline) => {
- return stageData
- ? [...dataPipeline, GatedDataMiddleware]
- : [...dataPipeline];
- });
- });
+player.hooks.dataController.tap(this.name, (dc: DataController) => {
+ dataController = dc;
+
+ dc.hooks.resolveDataStages.tap(this.name, (dataPipeline) => {
+ return stageData
+ ? [...dataPipeline, GatedDataMiddleware]
+ : [...dataPipeline];
+ });
+});
```
+
Finally, we tap into the `flowController` so we can intercept the `flow` hook. We then tap into the `transition` hook, which is called every time the player transitions from one view to another. If the `commitTransitions` includes the next view name, we set the `commitShadowModel` flag to true, and commit the data stored in the shadow model through `GatedDataMiddleware` into the data model. Whether the data was committed from the shadow model or not, we clear the shadow model paths in the `GatedDataMiddleware` instance and set the `commitShadowModel` flag to false as final steps.
```typescript
- player.hooks.flowController.tap(this.name, (flowController) => {
- flowController.hooks.flow.tap(this.name, (flow) => {
- flow.hooks.transition.tap(this.name, (from, to) => {
- if (from) {
- if (commitTransitions.includes(to.name)) {
- commitShadowModel = true;
- player.logger.debug(
- 'Shadow Model Data to be committed %s',
- GatedDataMiddleware.shadowModelPaths
- );
- dataController.set(GatedDataMiddleware.shadowModelPaths);
- }
-
- commitShadowModel = false;
- GatedDataMiddleware.shadowModelPaths.clear();
- }
- });
- });
+player.hooks.flowController.tap(this.name, (flowController) => {
+ flowController.hooks.flow.tap(this.name, (flow) => {
+ flow.hooks.transition.tap(this.name, (from, to) => {
+ if (from) {
+ if (commitTransitions.includes(to.name)) {
+ commitShadowModel = true;
+ player.logger.debug(
+ "Shadow Model Data to be committed %s",
+ GatedDataMiddleware.shadowModelPaths,
+ );
+ dataController.set(GatedDataMiddleware.shadowModelPaths);
+ }
+
+ commitShadowModel = false;
+ GatedDataMiddleware.shadowModelPaths.clear();
+ }
});
+ });
+});
```
And this is how we implement a plugin that manages the staging of data based on the view state attributes.
-Code Snippets Reference: [StageRevertDataPlugin](https://github.com/player-ui/player/blob/main/plugins/stage-revert-data/core/src/index.ts)
\ No newline at end of file
+Code Snippets Reference: [StageRevertDataPlugin](https://github.com/player-ui/player/blob/main/plugins/stage-revert-data/core/src/index.ts)
diff --git a/docs/site/pages/writing-plugins.mdx b/docs/site/src/content/docs/guides/writing-plugins.mdx
similarity index 90%
rename from docs/site/pages/writing-plugins.mdx
rename to docs/site/src/content/docs/guides/writing-plugins.mdx
index d6c93b18b..51be375f6 100644
--- a/docs/site/pages/writing-plugins.mdx
+++ b/docs/site/src/content/docs/guides/writing-plugins.mdx
@@ -1,17 +1,16 @@
---
-title: Player Team
+title: Writing a Plugin
platform: core,react
---
-# Writing a Plugin
-
- While we have published a majority of the plugins we have developed, there will always be new use cases that may require new functionality. Writing a plugin in the easiest way to extend Player functionality for these cases. Plugins work slightly differently on each platform so in this guide we will cover how to write a plugin for each platform.
+import PlatformTabs from "../../../components/PlatformTabs.astro";
+While we have published a majority of the plugins we have developed, there will always be new use cases that may require new functionality. Writing a plugin in the easiest way to extend Player functionality for these cases. Plugins work slightly differently on each platform so in this guide we will cover how to write a plugin for each platform.
-
+
-Core plugins are the easiest way to extend Player functionality regardless of what platform you are using Player on. To make writing core plugins easy `@player-ui/player` exposes an interface `PlayerPlugin` that denotes everything needed. The two mandatory features are a `name` property which is lets Player know how to refer to the plugin and an implemented `apply` function that takes a `player` object. Optionally a `symbol` property can be used to provide a unique identifier that can be used to retrieve the plugin from Player.
+Core plugins are the easiest way to extend Player functionality regardless of what platform you are using Player on. To make writing core plugins easy `@player-ui/player` exposes an interface `PlayerPlugin` that denotes everything needed. The two mandatory features are a `name` property which is lets Player know how to refer to the plugin and an implemented `apply` function that takes a `player` object. Optionally a `symbol` property can be used to provide a unique identifier that can be used to retrieve the plugin from Player.
The first step for creating a plugin is making our plugin class, making sure it implements the `PlayerPlugin` interface from `@player-ui/player`. By convention, a name attribute with the dash-cased name of your plugin should be defined.
@@ -29,7 +28,7 @@ export default class ExamplePlayerPlugin implements PlayerPlugin {
}
```
-The `apply` function is where the actual logic of the plugin lives. By tapping the hooks exposed via `player.hooks` you gain access to the internal pipeline of components that comprise Player and can inject your functionality into their exposed hooks. For example if you want to do something any time Player's state changes you could do the following:
+The `apply` function is where the actual logic of the plugin lives. By tapping the hooks exposed via `player.hooks` you gain access to the internal pipeline of components that comprise Player and can inject your functionality into their exposed hooks. For example if you want to do something any time Player's state changes you could do the following:
```javascript
apply(player: Player) {
@@ -40,6 +39,7 @@ apply(player: Player) {
```
Some components expose hooks themselves which may require multiple levels of taps which is not uncommon. For example if you wanted to modify the `ViewInstance` before it was resolved you would do the following:
+
```javascript
apply(player: Player) {
player.hooks.viewController.tap(this.name, (vc) => {
@@ -50,20 +50,20 @@ apply(player: Player) {
}
```
-It is not uncommon for core plugins to have constructors for cases where the plugin needs to take some configuration. In cases where plugin configs are more complicated than basic feature flags, it is recommended to make an interface to represent the config object. As an added benefit it also makes it easier to down stream consumers to use your plugin.
+It is not uncommon for core plugins to have constructors for cases where the plugin needs to take some configuration. In cases where plugin configs are more complicated than basic feature flags, it is recommended to make an interface to represent the config object. As an added benefit it also makes it easier to down stream consumers to use your plugin.
-For a more comprehensive guide on plugins, check out this [Plugin Implementation](./plugin-implementation) example.
+For a more comprehensive guide on plugins, check out this [Plugin Implementation](/guides/plugin-implementation) example.
_Note: For the React Player you can import and load the plugin the same way you would a React Player Plugin but for the iOS and Android Players you will need to wrap the javascript bundle in a iOS/Android plugin to ensure it is available on your platform._
-
-
+
+
React Player Plugins are very similar to core plugins in both their composition and use. The `@player-ui/react` package exposes an interface `ReactPlayerPlugin` that, much like the `PlayerPlugin` interface provides the necessary attributes that are required for a React Player plugin. Again a dash-cased `name` attribute should be used by convention, and a function `applyReact` is required that takes a `ReactPlayer` instance. Similarly to core plugins in the `applyReact` function you have access to the React Player object and access to the three exposed hooks:
-- The `webComponent` hook allows you to modify a React component that is stored in the React Player for use when it renders content. This happens during the initialization phase and ise useful if you want to wrap components in various content providers.
-- The `playerComponent` hook allows you to modify a component or execute functionality when the React Player is rendering a component after the view has been reconciled in Player. This is useful if you want to inject additional props to components or collect data on which component was rendered.
-- The `onBeforeViewReset` hook is fired when the view is resetting to undefined and you want to execute some asynchronous tasks.
+- The `webComponent` hook allows you to modify a React component that is stored in the React Player for use when it renders content. This happens during the initialization phase and ise useful if you want to wrap components in various content providers.
+- The `playerComponent` hook allows you to modify a component or execute functionality when the React Player is rendering a component after the view has been reconciled in Player. This is useful if you want to inject additional props to components or collect data on which component was rendered.
+- The `onBeforeViewReset` hook is fired when the view is resetting to undefined and you want to execute some asynchronous tasks.
Below is an example of a basic `ReactPlayerPlugin` that would expose a function to every component that gets loaded in the React Player:
@@ -101,11 +101,11 @@ export class FunctionPlugin implements ReactPlayerPlugin {
}
```
-Lastly React plugins can also act as a core plugin in cases where core functionality needs to be extended for the React plugin to work. Since both the `PlayerPlugin` and `ReactPlayerPlugin` are typescript interfaces a plugin can implement both and be considered a valid plugin.
+Lastly React plugins can also act as a core plugin in cases where core functionality needs to be extended for the React plugin to work. Since both the `PlayerPlugin` and `ReactPlayerPlugin` are typescript interfaces a plugin can implement both and be considered a valid plugin.
-
-
-iOS Player Plugins are very similar to core and react plugins in both their composition and use.
+
+
+iOS Player Plugins are very similar to core and react plugins in both their composition and use.
### NativePlugin
@@ -116,8 +116,8 @@ The `player` passed to `apply` exposes hooks from the core player, as well as ho
- The `view` hook allows you to modify the root view that will be displayed in the SwiftUIPlayer body. This is useful for applying changes to the environment for the SwiftUI view tree, or apply ViewModifiers and such.
- The `transition` hook allows you to specify a `PlayerViewTransition` object to be applied when the flow transitions from one view to another, to animate the transition.
-
#### Basic Example
+
Below is an example of a basic `NativePlugin` that sets a value in the EnvironmentValues when the plugin is included:
```swift
@@ -134,7 +134,9 @@ class EnvironmentPlugin: NativePlugin {
}
}
```
+
#### Asset Registration
+
Likely the most common usecase for plugins is to register assets:
```swift
@@ -152,11 +154,13 @@ class ExampleAssetPlugin: NativePlugin {
```
### JSBasePlugin
-Building native features on top of shared functionality is one of the primary benefits of using player. As such we expose convenience utilities to enable loading JavaScript Player Plugins as the base for your `NativePlugin`.
+Building native features on top of shared functionality is one of the primary benefits of using player. As such we expose convenience utilities to enable loading JavaScript Player Plugins as the base for your `NativePlugin`.
#### Basic Setup
+
This example will load the `SharedJSPlugin` in the JavaScript layer when included as a plugin to `SwiftUIPlayer`.
+
```swift
import PlayerUI
@@ -177,7 +181,9 @@ class SharedJSPlugin: JSBasePlugin {
}
}
```
+
#### Arguments for constructing the JavaScript plugins
+
To simplify the ease of use, the `JSContext` for `JSBasePlugin` implementations is provided when the underlying resources for the core `player` are being setup. This means that we need to provide the arguments for the JavaScript constructor late. To do this, override the `getArguments` function:
```swift
@@ -203,7 +209,7 @@ class SharedJSPlugin: JSBasePlugin {
**Note**: As `JavaScriptCore` cannot resolve dependencies at runtime, using a module bundler such as [tsup](https://github.com/egoist/tsup) is required.
-**Note**: `JSBasePlugin` implementations do not necessarily need to be a `PlayerPlugin`, for example, the [BeaconPlugin](https://github.com/player-ui/player/blob/main/ios/plugins/BaseBeaconPlugin/Sources/BaseBeaconPlugin.swift#L63) can take plugins in it's constructor, that are not `PlayerPlugin`.
+**Note**: `JSBasePlugin` implementations do not necessarily need to be a `PlayerPlugin`, for example, the [BeaconPlugin](https://github.com/player-ui/player/blob/main/plugins/beacon/ios/Sources/BaseBeaconPlugin.swift#L59) can take plugins in it's constructor, that are not `PlayerPlugin`.
-
+
diff --git a/docs/site/src/content/docs/index.mdx b/docs/site/src/content/docs/index.mdx
new file mode 100644
index 000000000..46fc9f2f7
--- /dev/null
+++ b/docs/site/src/content/docs/index.mdx
@@ -0,0 +1,55 @@
+---
+title: Player
+description: Get started building your docs site with Starlight.
+template: splash
+hero:
+ tagline: A cross-platform semantic rendering engine
+ image:
+ file: ../../assets/logo/logo-dark-small.png
+ actions:
+ - text: Learn More
+ link: /player/about
+ icon: information
+ - text: Get Started
+ link: /guides/getting-started/
+ icon: right-arrow
+ variant: minimal
+---
+
+import { Card, CardGrid } from "@astrojs/starlight/components";
+import Image from "../../components/Image.astro";
+import playerPlatformDiagram from "../../assets/platform_diagram.png";
+import PlayerPreview from "../../components/PlayerPreview.astro";
+
+
+
+ Sharing content across platforms enables you to quickly release new
+ features, on all platforms, with just a simple content deployment.
+
+
+ Player works seamlessly with your existing UI components to fit application.
+ Define your own patterns through assets and render them exactly as your
+ designers intended.
+
+
+ Need to figure out where go next? Chaining multiple pages together with
+ Player is a breeze. Check out the [docs](/guides/multi-flow-experiences) for
+ more details.
+
+
+ Player is designed from the ground up with plugins in mind. [Read
+ more](/plugins/) about the 20+ provided plugins, or how to write your own.
+
+
+
+## What does it look like?
+
+
-
+
In build.gradle
```kotlin
@@ -23,26 +22,27 @@ implementation "com.intuit.playerui.plugins:coroutines:$PLAYER_VERSION"
```
In Player constructor
+
```kotlin
import com.intuit.playerui.plugins.coroutines.UpdatesPlugin
val plugins = listOf(UpdatesPlugin())
AndroidPlayer(plugins)
```
-
-
+
+
### API
-
+
The API for this plugin revolves around the `ReceiveChannel` for asset updates.
Public API available from sources here:
-[UpdatesPlugin](https://github.com/player-ui/player/blob/main/plugins/coroutines/jvm/src/main/kotlin/com/intuit/player/plugins/coroutines/UpdatesPlugin.kt)
+[UpdatesPlugin](https://github.com/player-ui/player/blob/main/plugins/coroutines/jvm/src/main/kotlin/com/intuit/playerui/plugins/coroutines/UpdatesPlugin.kt)
-
+
## FlowScopePlugin
@@ -53,7 +53,7 @@ All operations launched using the scope will be cancelled when player changes st
### Usage
-
+
In build.gradle
```kotlin
@@ -61,23 +61,25 @@ implementation "com.intuit.playerui.plugins:coroutines:$PLAYER_VERSION"
```
In Player constructor
+
```kotlin
import com.intuit.playerui.plugins.coroutines.FlowScopePlugin
val plugins = listOf(FlowScopePlugin())
AndroidPlayer(plugins)
```
-
-
+
+
### API
-
+
Public API available from sources here:
-[FlowScopePlugin](https://github.com/player-ui/player/blob/main/plugins/coroutines/jvm/src/main/kotlin/com/intuit/player/plugins/coroutines/FlowScopePlugin.kt)
-
-
\ No newline at end of file
+[FlowScopePlugin](https://github.com/player-ui/player/blob/main/plugins/coroutines/jvm/src/main/kotlin/com/intuit/playerui/plugins/coroutines/FlowScopePlugin.kt)
+
+
+
diff --git a/docs/site/pages/plugins/set-timeout.mdx b/docs/site/src/content/docs/plugins/android/set-timeout.mdx
similarity index 91%
rename from docs/site/pages/plugins/set-timeout.mdx
rename to docs/site/src/content/docs/plugins/android/set-timeout.mdx
index de673f465..6b010c2df 100644
--- a/docs/site/pages/plugins/set-timeout.mdx
+++ b/docs/site/src/content/docs/plugins/android/set-timeout.mdx
@@ -1,20 +1,19 @@
---
title: SetTimeout Plugin
-platform: android
---
-# setTimeout Plugin
-
The only explicit runtime plugin in the core Android plugin set, the `SetTimeoutPlugin` is a `RuntimePlugin` written to provide the global `setTimeout` method to the runtime.
-## Usage
+## Usage
In build.gradle
+
```kotlin
implementation "com.intuit.playerui.plugins:set-time-out:$PLAYER_VERSION"
```
In plugin implementation
+
```kotlin
class PluginThatNeedsSetTimeout : RuntimePlugin {
@@ -24,4 +23,4 @@ class PluginThatNeedsSetTimeout : RuntimePlugin {
}
}
-```
\ No newline at end of file
+```
diff --git a/docs/site/pages/plugins/asset-transform.mdx b/docs/site/src/content/docs/plugins/core/asset-transform.mdx
similarity index 83%
rename from docs/site/pages/plugins/asset-transform.mdx
rename to docs/site/src/content/docs/plugins/core/asset-transform.mdx
index ee4be5ed4..54376ef7b 100644
--- a/docs/site/pages/plugins/asset-transform.mdx
+++ b/docs/site/src/content/docs/plugins/core/asset-transform.mdx
@@ -1,13 +1,12 @@
---
title: Asset Transform
-platform: core,react
---
-# Asset Transform Plugin
+import PlatformTabs from "../../../../components/PlatformTabs.astro";
## What are _transforms_?
-Transforms are functions that map the authored JSON representation of an asset into a stateful JavaScript object, including all of the properties required for that asset to interact with the data-model, navigation, and the rest of Player. This allows UI implementations to have consistent treatment and behavior. While the transform plugin is registered in the _core_ layer, it can be wrapped by the native platforms.
+Transforms are functions that map the authored JSON representation of an asset into a stateful JavaScript object, including all of the properties required for that asset to interact with the data-model, navigation, and the rest of Player. This allows UI implementations to have consistent treatment and behavior. While the transform plugin is registered in the _core_ layer, it can be wrapped by the native platforms.
## Partial Matching
@@ -15,18 +14,16 @@ The transform plugin makes use of the `partial-match-registry` which ranks match
## Usage
-
-
+
## Transform Arguments
Each `transform` is a function that is passed 3 arguments: the current `asset` node, and an _options_ object containing a data-model, expression-evaluator, binding-parser, and a flow transition function, and a store for state management. The transforms should return an immutable representation of the asset, including any means of interacting with the _player_.
-
```javascript
-import { Player } from '@player-ui/player';
-import { AssetTransformPlugin } from '@player-ui/asset-transform-plugin';
+import { Player } from "@player-ui/player";
+import { AssetTransformPlugin } from "@player-ui/asset-transform-plugin";
// Add it to Player
@@ -36,21 +33,20 @@ const player = new Player({
new Registry([
// Register a match for any _action_ type with a custom transform.
[
- { type: 'action' },
- value => {
+ { type: "action" },
+ (value) => {
return {
...value,
- hello: () => console.log('hello world')
+ hello: () => console.log("hello world"),
};
- }
- ]
- ])
- )
- ]
+ },
+ ],
+ ]),
+ ),
+ ],
});
```
-
### State Management
Often times node transforms require some state to be stored between updates. Historically this state was put in the data-model under `local` (to not send it back to the server), but updates became difficult to manage, and namespace collisions under _local_ were up to the transforms to discern.
@@ -67,18 +63,18 @@ const transform = (asset, options, store) => {
count,
increment() {
setCount(count + 1);
- }
+ },
};
};
```
-
+
## Example
-
+
If the authored JSON is:
@@ -102,14 +98,14 @@ the transform-plugin would run the transform on the `action` asset, attaching a
actions: [
{
asset: {
- id: 'foo',
- type: 'action',
- hello: () => console.log('hello world')
- }
- }
+ id: "foo",
+ type: "action",
+ hello: () => console.log("hello world"),
+ },
+ },
];
}
```
-
+
diff --git a/docs/site/pages/plugins/common-expressions.mdx b/docs/site/src/content/docs/plugins/core/common-expressions.mdx
similarity index 71%
rename from docs/site/pages/plugins/common-expressions.mdx
rename to docs/site/src/content/docs/plugins/core/common-expressions.mdx
index 17b2566e6..501bfaee8 100644
--- a/docs/site/pages/plugins/common-expressions.mdx
+++ b/docs/site/src/content/docs/plugins/core/common-expressions.mdx
@@ -1,9 +1,8 @@
---
title: Common Expressions
-platform: react,core,ios
---
-# Common Expressions Plugin
+import PlatformTabs from "../../../../components/PlatformTabs.astro";
This plugin exposes some basic expressions into Player content.
@@ -12,7 +11,7 @@ It also serves as a good reference to adding your own custom expressions into Pl
## Usage
-
+
Install the plugin:
@@ -21,8 +20,9 @@ yarn add @player-ui/common-types-plugin
```
Add it to Player:
+
```js
-import CommonExpressionsPlugin from '@player-ui/common-expressions-plugin';
+import CommonExpressionsPlugin from "@player-ui/common-expressions-plugin";
const commonExpressionsPlugin = new CommonExpressionsPlugin();
const player = new Player({ plugins: [commonExpressionsPlugin] });
@@ -33,9 +33,9 @@ player.start(myFlow);
This will allow any included expressions or custom expressions to be used in the content
-
+
-
+
### CocoaPods
@@ -63,7 +63,8 @@ var body: some View {
)
}
```
-
+
+
@@ -76,7 +77,7 @@ var body: some View {
> Gets the size of a value. This is the number of keys in an object, the length of a string, or the number of items in an array.
```ts
-function size(value: string | array | object): number
+function size(value: string | array | object): number;
```
#### length
@@ -88,19 +89,19 @@ function size(value: string | array | object): number
> Concatenates arrays together, or strings into 1 value
```ts
-function concat(...values: Array): Array
+function concat(...values: Array): Array;
```
---
-## Strings
+## Strings
#### trim
> Trims whitespace from the leading and trailing edges of a string
```ts
-function trim(value: string): string
+function trim(value: string): string;
```
#### upperCase
@@ -108,7 +109,7 @@ function trim(value: string): string
> Transforms the string to all uppercase.
```ts
-function upperCase(value: string): string
+function upperCase(value: string): string;
```
#### lowerCase
@@ -116,7 +117,7 @@ function upperCase(value: string): string
> Transforms the string to all lowercase.
```ts
-function lowerCase(value: string): string
+function lowerCase(value: string): string;
```
#### titleCase
@@ -124,7 +125,7 @@ function lowerCase(value: string): string
> Transforms the string to title case. Each word is capitalized.
```ts
-function titleCase(value: string): string
+function titleCase(value: string): string;
```
#### sentenceCase
@@ -132,7 +133,7 @@ function titleCase(value: string): string
> Transforms the string to sentence case. The first word is capitalized.
```ts
-function sentenceCase(value: string): string
+function sentenceCase(value: string): string;
```
#### replace
@@ -140,7 +141,11 @@ function sentenceCase(value: string): string
> Replaces all instances of pattern in string with replacement. The pattern can also be a regex.
```ts
-function replace(value: string, pattern: string | RegExp, replacement: string): string
+function replace(
+ value: string,
+ pattern: string | RegExp,
+ replacement: string,
+): string;
```
#### containsAny
@@ -148,7 +153,7 @@ function replace(value: string, pattern: string | RegExp, replacement: string):
> Checks if a given string contains any keywords present in the given array.
```ts
-function containsAny(value: string, keywords: Array): boolean
+function containsAny(value: string, keywords: Array): boolean;
```
---
@@ -160,7 +165,7 @@ function containsAny(value: string, keywords: Array): boolean
> Converts the given value to a number if possible. Will handle removing currency modifiers and comma delimitated values.
```ts
-function number(value: string): number | undefined
+function number(value: string): number | undefined;
```
#### round
@@ -168,7 +173,7 @@ function number(value: string): number | undefined
> Rounds the given number to the nearest integer.
```ts
-function round(value: number): number
+function round(value: number): number;
```
#### floor
@@ -176,7 +181,7 @@ function round(value: number): number
> Rounds the number down the the nearest integer
```ts
-function floor(value: number): number
+function floor(value: number): number;
```
#### ceil
@@ -184,7 +189,7 @@ function floor(value: number): number
> Rounds the number up the the nearest integer
```ts
-function ceil(value: number): number
+function ceil(value: number): number;
```
#### sum
@@ -192,7 +197,7 @@ function ceil(value: number): number
> Sums up all arguments
```ts
-function sum(...values: Array): number
+function sum(...values: Array): number;
```
---
@@ -204,7 +209,11 @@ function sum(...values: Array): number
> Finds the index of the item in the given array (or array reference). Returns -1 for indexes that aren't found
```ts
-function findPropertyIndex(binding: Binding | Array, searchProperty: string, searchValue: any): number
+function findPropertyIndex(
+ binding: Binding | Array,
+ searchProperty: string,
+ searchValue: any,
+): number;
```
### findProperty
@@ -212,5 +221,11 @@ function findPropertyIndex(binding: Binding | Array, searchProperty: string, sea
> Finds the item in the given array that matches the search criteria. Optionally return a specific property or a fallback value if not found
```ts
-function findPropertyIndex(binding: Binding | Array, searchProperty: string, searchValue: any, fallBackProperty?: string, fallBackValue?: T): T
+function findPropertyIndex(
+ binding: Binding | Array,
+ searchProperty: string,
+ searchValue: any,
+ fallBackProperty?: string,
+ fallBackValue?: T,
+): T;
```
diff --git a/docs/site/pages/plugins/common-types.mdx b/docs/site/src/content/docs/plugins/core/common-types.mdx
similarity index 57%
rename from docs/site/pages/plugins/common-types.mdx
rename to docs/site/src/content/docs/plugins/core/common-types.mdx
index 881d7ba8b..f99bd2f9e 100644
--- a/docs/site/pages/plugins/common-types.mdx
+++ b/docs/site/src/content/docs/plugins/core/common-types.mdx
@@ -1,9 +1,8 @@
---
title: Common Types
-platform: react,core,ios
---
-# Common Types Plugin
+import PlatformTabs from "../../../../components/PlatformTabs.astro";
This plugin exposes some basic `DataTypes`, `validations`, and `formats` into Player content.
@@ -12,7 +11,7 @@ It also serves as a good reference to adding your own custom types into Player.
## Usage
-
+
Install the plugin:
@@ -21,8 +20,9 @@ yarn add @player-ui/common-types-plugin
```
Add it to Player:
+
```js
-import CommonTypesPlugin from '@player-ui/common-types-plugin';
+import CommonTypesPlugin from "@player-ui/common-types-plugin";
const commonTypesPlugin = new CommonTypesPlugin();
const player = new Player({ plugins: [commonTypesPlugin] });
@@ -33,9 +33,9 @@ player.start(myFlow);
This will allow any `DataTypes`, `formats`, `validations` and custom data types to be used in the content
-
+
-
+
### CocoaPods
@@ -64,18 +64,16 @@ var body: some View {
}
```
-
+
-
## Formats
#### commaNumber
-
-* **format**: Formats a number (or string containing only numbers) into a comma delineated string.
-* **deformat**: Converts a comma delineated string into a number
+- **format**: Formats a number (or string containing only numbers) into a comma delineated string.
+- **deformat**: Converts a comma delineated string into a number
Options:
@@ -87,11 +85,11 @@ Options:
#### integer
-* **deformat**: converts a string containing only integers to an integer
+- **deformat**: converts a string containing only integers to an integer
#### date
-* **format**: Formats a string of numbers into a slash separated date
+- **format**: Formats a string of numbers into a slash separated date
Options:
@@ -103,8 +101,8 @@ Options:
#### currency
-* **format**: Formats a number of string into a currency value
-* **deformat**: Converts a currency value into a number
+- **format**: Formats a number of string into a currency value
+- **deformat**: Converts a currency value into a number
Options:
@@ -118,7 +116,7 @@ Options:
#### phone
-* **format**: Formats the value as a phone number
+- **format**: Formats the value as a phone number
Options:
@@ -133,9 +131,11 @@ Options:
## Validations
#### required
+
> Asserts that a value is not `null`, `undefined`, or an empty string
-Options:
+Options:
+
```ts
{
/** An expression to limit the assertion only if the expression evaluates to truthy **/
@@ -146,13 +146,14 @@ Options:
}
```
-**Constants Support**:
+**Constants Support**:
-* namespace: `constants`
-* path: `validation.required`
-* message: "A value is required"
+- namespace: `constants`
+- path: `validation.required`
+- message: "A value is required"
#### expression
+
> Uses an expression to evaluate the validation assertion
Options:
@@ -164,77 +165,80 @@ Options:
}
```
-**Constants Support**:
-
-* namespace: `constants`
-* path: `validation.expression`
-* message: "Expression evaluation failed"
+**Constants Support**:
+- namespace: `constants`
+- path: `validation.expression`
+- message: "Expression evaluation failed"
#### readonly
+
> Asserts that the value cannot change
-**Constants Support**:
+**Constants Support**:
-* namespace: `constants`
-* path: `validation.readonly`
-* message: "Value cannot be modified"
+- namespace: `constants`
+- path: `validation.readonly`
+- message: "Value cannot be modified"
#### string
+
> Asserts that the value is a string
-**Constants Support**:
+**Constants Support**:
-* namespace: `constants`
-* path: `validation.string`
-* message: "Value must be a string"
-* parameters:
+- namespace: `constants`
+- path: `validation.string`
+- message: "Value must be a string"
+- parameters:
- `type`: the type of value being validated
-
#### integer
+
> Asserts that the value is an integer
-**Constants Support**:
+**Constants Support**:
-* namespace: `constants`
-* path: `validation.integer`
-* message: "Value must be an integer"
-* parameters:
+- namespace: `constants`
+- path: `validation.integer`
+- message: "Value must be an integer"
+- parameters:
- `type`: the type of value being validated
- `flooredValue`: the floored value of the value being validated
-
#### collection
+
> Asserts that the value is an array
-**Constants Support**:
+**Constants Support**:
-* namespace: `constants`
-* path: `validation.collection`
-* message: "Cannot set collection to non-array"
+- namespace: `constants`
+- path: `validation.collection`
+- message: "Cannot set collection to non-array"
#### oneOf
+
> Asserts that the value is one of the pre-defined accepted values
-Options:
+Options:
+
```ts
{
options?: Array;
}
```
-**Constants Support**:
-
-* namespace: `constants`
-* path: `validation.oneof`
-* message: "Cannot set collection to non-array"
+**Constants Support**:
+- namespace: `constants`
+- path: `validation.oneof`
+- message: "Cannot set collection to non-array"
#### regex
+
> Asserts that the value matches the provided regular expression
-Options:
+Options:
```ts
{
@@ -242,16 +246,17 @@ Options:
}
```
-**Constants Support**:
-
-* namespace: `constants`
-* path: `validation.regex`
+**Constants Support**:
+- namespace: `constants`
+- path: `validation.regex`
#### length
+
> Asserts that the value matches the given length criteria. Uses character counts for strings, and key-length for objects, and array length for arrays.
Options:
+
```ts
{
min?: number;
@@ -260,115 +265,125 @@ Options:
}
```
-**Constants Support**:
+**Constants Support**:
-* namespace: `constants`
-* path: `validation.minimum`, `validation.maximum`
-* message: "At least ${min} items needed", "Up to ${max} items allowed"
-* parameters:
+- namespace: `constants`
+- path: `validation.minimum`, `validation.maximum`
+- message: "At least \$\{min\} items needed", "Up to \$\{max\} items allowed"
+- parameters:
- `validationLength`: Returns the length of the value being validated
-
-
#### min
+
> Assets that the numeric value is at least as large as the target
Options:
+
```ts
{
value: number;
}
```
-**Constants Support**:
+**Constants Support**:
-* namespace: `constants`
-* path: `validation.min`
-* message: "Must be at least ${value}"
+- namespace: `constants`
+- path: `validation.min`
+- message: "Must be at least \$\{value\}"
#### max
+
> Assets that the numeric value is at no larger the target
Options:
+
```ts
{
value: number;
}
```
-**Constants Support**:
+**Constants Support**:
-* namespace: `constants`
-* path: `validation.max`
-* message: "Cannot exceed ${value}"
+- namespace: `constants`
+- path: `validation.max`
+- message: "Cannot exceed \$\{value\}"
#### email
-> Asserts that the value follows an email pattern
-**Constants Support**:
+> Asserts that the value follows an email pattern
-* namespace: `constants`
-* path: `validation.email`
-* message: "Improper email format"
+**Constants Support**:
+- namespace: `constants`
+- path: `validation.email`
+- message: "Improper email format"
#### phone
+
> Asserts that the value follows an phone number pattern
-**Constants Support**:
+**Constants Support**:
-* namespace: `constants`
-* path: `validation.phone`
-* message: "Invalid phone number"
+- namespace: `constants`
+- path: `validation.phone`
+- message: "Invalid phone number"
#### zip
-> Asserts that the value follows an zip-code pattern
-**Constants Support**:
+> Asserts that the value follows an zip-code pattern
-* namespace: `constants`
-* path: `validation.zip`
-* message: "Invalid zip code"
+**Constants Support**:
+- namespace: `constants`
+- path: `validation.zip`
+- message: "Invalid zip code"
---
## Data Types
#### BooleanType
+
> A true or false value.
-* **validations**: `oneOf([true, false])`
+- **validations**: `oneOf([true, false])`
#### IntegerType
+
> An integer value
-* **validations**: `integer`
-* **format**: `integer`
+- **validations**: `integer`
+- **format**: `integer`
#### IntegerPosType
+
> An integer value greater than 0
-* **validations**: `integer`, `min(1)`
-* **format**: `integer`
+- **validations**: `integer`, `min(1)`
+- **format**: `integer`
#### StringType
+
> A string value
-* **validations**: `string`
+- **validations**: `string`
#### CollectionType
+
> An array of items
-* **validations**: `collection`
+- **validations**: `collection`
#### DateType
+
> A value representing a date
-* **format**: `date`
+- **format**: `date`
#### PhoneType
+
> A value representing a phone number
-* **validations**: `phone`
-* **format**: `phone` (`(###) ###-####`)
+- **validations**: `phone`
+- **format**: `phone` (`(###) ###-####`)
diff --git a/docs/site/pages/plugins/computed-properties.mdx b/docs/site/src/content/docs/plugins/core/computed-properties.mdx
similarity index 82%
rename from docs/site/pages/plugins/computed-properties.mdx
rename to docs/site/src/content/docs/plugins/core/computed-properties.mdx
index 709887501..850a4bfe4 100644
--- a/docs/site/pages/plugins/computed-properties.mdx
+++ b/docs/site/src/content/docs/plugins/core/computed-properties.mdx
@@ -1,32 +1,31 @@
---
title: Computed Properties
-platform: react,core
---
-# Computed Properties Plugin
+import PlatformTabs from "../../../../components/PlatformTabs.astro";
-This plugin allows users to specify a path in the data-model (binding) as a computed property in the schema.
+This plugin allows users to specify a path in the data-model (binding) as a computed property in the schema.
Anytime this binding is read from, the given expression will be evaluated and returned instead of the it being read from the actual model. Writes to the binding will be prevented, and an error will be thrown.
## Usage
-
+
Add the plugin to Player:
```js
-import { Player } from '@player-ui/player';
-import { ComputedPropertiesPlugin } from '@player-ui/computed-properties-plugin';
+import { Player } from "@player-ui/player";
+import { ComputedPropertiesPlugin } from "@player-ui/computed-properties-plugin";
const player = new Player({
plugins: [new ComputedPropertiesPlugin()],
});
```
-
+
-
+
### CocoaPods
@@ -51,12 +50,13 @@ var body: some View {
)
}
```
-
+
+
## Expression Data Type
-The computed properties plugin introspects the schema, looking for any `DataType` that uses the `Expression`:
+The computed properties plugin introspects the schema, looking for any `DataType` that uses the `Expression`:
```json
{
diff --git a/docs/site/pages/plugins/data-change-listener.mdx b/docs/site/src/content/docs/plugins/core/data-change-listener.mdx
similarity index 89%
rename from docs/site/pages/plugins/data-change-listener.mdx
rename to docs/site/src/content/docs/plugins/core/data-change-listener.mdx
index bca06544b..d27ae87e8 100644
--- a/docs/site/pages/plugins/data-change-listener.mdx
+++ b/docs/site/src/content/docs/plugins/core/data-change-listener.mdx
@@ -1,9 +1,8 @@
---
title: Data Change Listener
-platform: react,core
---
-# Data Change Listener Plugin
+import PlatformTabs from "../../../../components/PlatformTabs.astro";
This plugin enables users to subscribe to data-change events within a view, and run expressions when the target value changes. Expressions are added to a listeners property of the view, with events prefixed by `dataChange` and the target binding:
@@ -21,20 +20,20 @@ This plugin enables users to subscribe to data-change events within a view, and
## Installation
-
+
Add it to Player:
```js
-import { Player } from '@player-ui/player';
-import { DataChangePlugin } from '@player-ui/data-change-plugin';
+import { Player } from "@player-ui/player";
+import { DataChangePlugin } from "@player-ui/data-change-plugin";
const player = new Player({
- plugins: [new DataChangePlugin()]
+ plugins: [new DataChangePlugin()],
});
```
-
+
## Usage
diff --git a/docs/site/pages/plugins/data-filter.mdx b/docs/site/src/content/docs/plugins/core/data-filter.mdx
similarity index 62%
rename from docs/site/pages/plugins/data-filter.mdx
rename to docs/site/src/content/docs/plugins/core/data-filter.mdx
index ec386875c..9c981af3e 100644
--- a/docs/site/pages/plugins/data-filter.mdx
+++ b/docs/site/src/content/docs/plugins/core/data-filter.mdx
@@ -1,27 +1,26 @@
---
title: Data Filter
-platform: react,core
---
-# Data Filter Plugin
+import PlatformTabs from "../../../../components/PlatformTabs.astro";
The `data-filter-plugin` enables users to filter out segments of the data-model during serialization.
## Usage
-
+
Add the plugin to Player and configure the exclusion paths:
```ts
-import { Player } from '@player-ui/player';
-import { DataFilterPlugin } from '@player-ui/data-filter-plugin';
+import { Player } from "@player-ui/player";
+import { DataFilterPlugin } from "@player-ui/data-filter-plugin";
const player = new Player({
plugins: [
new DataFilterPlugin({
- paths: ['local', 'constants'],
+ paths: ["local", "constants"],
}),
],
});
@@ -29,5 +28,5 @@ const player = new Player({
This will exclude any top-level `local` or `constants` paths in the data-model from appearing in the serialized response.
-
-
\ No newline at end of file
+
+
diff --git a/docs/site/pages/plugins/expression.mdx b/docs/site/src/content/docs/plugins/core/expression.mdx
similarity index 81%
rename from docs/site/pages/plugins/expression.mdx
rename to docs/site/src/content/docs/plugins/core/expression.mdx
index c10b89f20..d940b4b3f 100644
--- a/docs/site/pages/plugins/expression.mdx
+++ b/docs/site/src/content/docs/plugins/core/expression.mdx
@@ -1,40 +1,40 @@
---
title: Expression
-platform: react,core,ios,android
---
-# Expression Plugin
+import PlatformTabs from "../../../../components/PlatformTabs.astro";
This plugin assists with exposing custom expressions to Player content.
## Usage
-
+
Define handlers for the expressions you wish to add:
```ts
-import { ExpressionHandler, ExpressionContext } from '@player-ui/expression-plugin';
+import {
+ ExpressionHandler,
+ ExpressionContext,
+} from "@player-ui/expression-plugin";
const customExpressionHandler: ExpressionHandler = (ctx: ExpressionContext) => {
- return 'Hello World!'
-}
+ return "Hello World!";
+};
```
Register with Player. Subsequent registrations of an expression with the same name will override previous values.
```ts
-import { Player } from '@player-ui/player';
-import { ExpressionPlugin } from '@player-ui/expression-plugin';
+import { Player } from "@player-ui/player";
+import { ExpressionPlugin } from "@player-ui/expression-plugin";
const player = new Player({
plugins: [
- new ExpressionPlugin([
- ['myCustomFunction', customExpressionHandler]
- ])
- ]
-})
+ new ExpressionPlugin([["myCustomFunction", customExpressionHandler]]),
+ ],
+});
```
Any calls to `myCustomFunction()` within the flow will utilize the newly registered expression:
@@ -49,10 +49,11 @@ Any calls to `myCustomFunction()` within the flow will utilize the newly registe
}
```
-
-
+
+
### CocoaPods
+
Add the subspec to your `Podfile`
```ruby
@@ -78,6 +79,7 @@ let expressionPlugin = ExpressionPlugin(expressions: [
}
])
```
+
#### Arguments
Arguments can be passed to custom expressions, and your handler receives the arguments as an array of Any:
@@ -99,18 +101,21 @@ let expressionPlugin = ExpressionPlugin(expressions: [
])
```
-
-
+
+
The `ExpressionPlugin` enables consumers to register custom expressions in native JVM code. Simply supply a map of expression name to handler on instantiation, and the expressions will be available within the content. Handlers receive arguments are as a `List` and are permitted to return `Any?`.
## Usage
+
In build.gradle
+
```kotlin
implementation "com.intuit.playerui.plugins:expression:$PLAYER_VERSION"
```
In Player constructor
+
```kotlin
import com.intuit.playerui.plugins.expression.ExpressionPlugin
@@ -126,6 +131,7 @@ AndroidPlayer(expressionPlugin)
```
In Player content
+
```json
{
"id": "hello-world-text",
@@ -134,5 +140,5 @@ In Player content
}
```
-
-
\ No newline at end of file
+
+
diff --git a/docs/site/pages/plugins/markdown.mdx b/docs/site/src/content/docs/plugins/core/markdown.mdx
similarity index 73%
rename from docs/site/pages/plugins/markdown.mdx
rename to docs/site/src/content/docs/plugins/core/markdown.mdx
index 9ef462fff..650800c84 100644
--- a/docs/site/pages/plugins/markdown.mdx
+++ b/docs/site/src/content/docs/plugins/core/markdown.mdx
@@ -1,31 +1,30 @@
---
title: Markdown
-platform: core
---
-# Markdown Plugin
+import PlatformTabs from "../../../../components/PlatformTabs.astro";
The `markdown-plugin` adds support for parsing markdown content to Player Assets. This plugin is asset set agnostic, so it expects a mappers record to inform how to transform markdown content into valid Player Content with support from your asset set.
## Usage
-
+
### Defining The Mappers
```ts
-import type { Mappers } from '@player-ui/markdown-plugin';
+import type { Mappers } from "@player-ui/markdown-plugin";
export const mappers: Mappers = {
text: ({ originalAsset, value }) => ({
id: `${originalAsset.id}-text`,
- type: 'text',
+ type: "text",
value,
}),
image: ({ originalAsset, value, src }) => ({
id: `${originalAsset.id}-image`,
- type: 'image',
+ type: "image",
accessibility: value,
metaData: {
ref: src,
@@ -38,8 +37,8 @@ export const mappers: Mappers = {
## Add the plugin to Player
```ts
-import { MarkdownPlugin } from '@player-ui/markdown-plugin';
-import mappers from './mappers';
+import { MarkdownPlugin } from "@player-ui/markdown-plugin";
+import mappers from "./mappers";
const markdownPlugin = new MarkdownPlugin(myMarkdownMappers);
// Add it to the player
@@ -47,6 +46,6 @@ const player = new Player({
plugins: [markdownPlugin],
});
```
-
-
+
+
diff --git a/docs/site/pages/plugins/meta.mdx b/docs/site/src/content/docs/plugins/core/meta.mdx
similarity index 63%
rename from docs/site/pages/plugins/meta.mdx
rename to docs/site/src/content/docs/plugins/core/meta.mdx
index 83437a3d1..36759d044 100644
--- a/docs/site/pages/plugins/meta.mdx
+++ b/docs/site/src/content/docs/plugins/core/meta.mdx
@@ -3,30 +3,27 @@ title: Meta
platform: core
---
-# Meta Plugin
+import PlatformTabs from "../../../../components/PlatformTabs.astro";
The Meta Plugin is an easy way to combine multiple _other_ plugins into 1 group. It is often used when sharing a set of plugins across platforms (each platform registering 1 common set of _core_ plugins).
-# Usage
+## Usage
-
+
Create a grouping of other plugins:
```js
-import { MetaPlugin } from '@player-ui/meta-plugin';
+import { MetaPlugin } from "@player-ui/meta-plugin";
-const pluginGroup = new MetaPlugin([
- new Plugin1(),
- new Plugin2()
-]);
+const pluginGroup = new MetaPlugin([new Plugin1(), new Plugin2()]);
```
Add the plugin to Player:
```js
-import { Player } from '@player-ui/player';
+import { Player } from "@player-ui/player";
const player = new Player({
plugins: [pluginGroup],
@@ -35,5 +32,5 @@ const player = new Player({
You can share `pluginGroup` with others as an easy way to group multiple plugin features together.
-
-
\ No newline at end of file
+
+
diff --git a/docs/site/pages/plugins/stage-revert-data.mdx b/docs/site/src/content/docs/plugins/core/stage-revert-data.mdx
similarity index 87%
rename from docs/site/pages/plugins/stage-revert-data.mdx
rename to docs/site/src/content/docs/plugins/core/stage-revert-data.mdx
index 1b02ee8cc..f6a7bc6f4 100644
--- a/docs/site/pages/plugins/stage-revert-data.mdx
+++ b/docs/site/src/content/docs/plugins/core/stage-revert-data.mdx
@@ -1,9 +1,9 @@
---
title: Stage Revert Data
-platform: core,ios
+platform: core
---
-# Stage Revert Data Plugin
+import PlatformTabs from "../../../../components/PlatformTabs.astro";
This plugin enables users to temporarily stage data changes before committing to the actual data model
@@ -31,22 +31,23 @@ It also should include a list of acceptable `commitTransitions` valid `VIEW` nam
## Example
-
+
Simply add the plugin to the config when constructing a player instance.
```javascript
-import StageRevertPlugin from '@player/stage-revert-data';
+import StageRevertPlugin from "@player/stage-revert-data";
const player = new Player({
plugins: [new StageRevertPlugin()],
});
```
-
-
+
+
### CocoaPods
+
Add the subspec to your `Podfile`
```ruby
@@ -54,7 +55,9 @@ pod 'PlayerUI/StageRevertDataPlugin'
```
### Swift Usage
+
This plugin takes no parameters, and the configuration comes from content, it can just be added to the plugin array:
+
```swift
var body: some View {
SwiftUIPlayer(
@@ -66,5 +69,6 @@ var body: some View {
)
}
```
-
-
\ No newline at end of file
+
+
+
diff --git a/docs/site/pages/plugins/types-provider.mdx b/docs/site/src/content/docs/plugins/core/types-provider.mdx
similarity index 79%
rename from docs/site/pages/plugins/types-provider.mdx
rename to docs/site/src/content/docs/plugins/core/types-provider.mdx
index 809dc613e..d3da542d0 100644
--- a/docs/site/pages/plugins/types-provider.mdx
+++ b/docs/site/src/content/docs/plugins/core/types-provider.mdx
@@ -1,61 +1,58 @@
---
title: Types Provider
-platform: core,ios
---
-# Types Provider Plugin
+import PlatformTabs from "../../../../components/PlatformTabs.astro";
-Similar to the [Expression Plugin](./expression), this plugin adds support for easily exposing new `DataTypes`, `formats`, and `validations` to Player's content.
+Similar to the [Expression Plugin](/plugins/core/expression), this plugin adds support for easily exposing new `DataTypes`, `formats`, and `validations` to Player's content.
## Example
-
+
Define a new validation type:
```ts
-import { ValidatorFunction } from '@player-ui/player';
+import { ValidatorFunction } from "@player-ui/player";
const customValidator: ValidatorFunction = (context, value) => {
- if (value === 'bad-value') {
+ if (value === "bad-value") {
return {
- message: "This is a bad value."
- }
+ message: "This is a bad value.",
+ };
}
-}
+};
```
-Create a new `DataType` that references it:
+Create a new `DataType` that references it:
```ts
-import { Schema } from '@player-ui/player';
+import { Schema } from "@player-ui/player";
const CustomDataType: Schema.DataType = {
- name: 'CustomType',
+ name: "CustomType",
validation: [
{
- type: "custom-validator"
- }
- ]
-}
+ type: "custom-validator",
+ },
+ ],
+};
```
Register it with Player:
```ts
-import { Player } from '@player-ui/player';
-import { TypesProviderPlugin } from '@player-ui/types-provider-plugin';
+import { Player } from "@player-ui/player";
+import { TypesProviderPlugin } from "@player-ui/types-provider-plugin";
const player = new Player({
plugins: [
new TypesProviderPlugin({
types: [CustomDataType],
- validations: [
- ['custom-validator', customValidator]
- ]
- })
- ]
+ validations: [["custom-validator", customValidator]],
+ }),
+ ],
});
```
@@ -73,12 +70,13 @@ Given a data-type reference to `CustomType` in the content, your new validation
}
```
-
-
+
+
The swift `TypesProviderPlugin` enables adding custom data types, formatters and validation purely through swift code. While in general, the recommendation would be to share a single JavaScript implementation to multiple platforms, some use cases may need a native integration.
### CocoaPods
+
Add the subspec to your `Podfile`
```ruby
@@ -127,7 +125,7 @@ let formatFunction = {value, options in
if let stringValue = value as? String {
return stringValue.replacingOccurrences(of: ".", with: ",") // Turn all periods into commas
} else {
- return value
+ return value
}
}
@@ -171,14 +169,14 @@ let formatFunction = {value, options in
return stringValue.replacingOccurrences(of: ".", with: char)
// Turn all periods into the specified character
} else {
- return value
+ return value
}
}
```
#### Custom Types
-Just as you can define custom formats and validation, you can define a custom type that encapsulates that functionality into a type, to avoid the need to keep specifying options, this is how the [common-types](./plugins/common-types) are defined, so when you choose a type like `DateType` the formatting is already set up.
+Just as you can define custom formats and validation, you can define a custom type that encapsulates that functionality into a type, to avoid the need to keep specifying options, this is how the [common-types](/plugins/core/common-types) are defined, so when you choose a type like `DateType` the formatting is already set up.
```swift
let type = CustomType(
@@ -219,5 +217,5 @@ let type = CustomType(
)
```
-
-
\ No newline at end of file
+
+
diff --git a/docs/site/pages/plugins/external-action-view-modifier.mdx b/docs/site/src/content/docs/plugins/iOS/external-action-view-modifier.mdx
similarity index 96%
rename from docs/site/pages/plugins/external-action-view-modifier.mdx
rename to docs/site/src/content/docs/plugins/iOS/external-action-view-modifier.mdx
index 4c1240656..30b083106 100644
--- a/docs/site/pages/plugins/external-action-view-modifier.mdx
+++ b/docs/site/src/content/docs/plugins/iOS/external-action-view-modifier.mdx
@@ -1,13 +1,12 @@
---
-title: External Action View Modifier
+title: External Action View Modifier
platform: ios
---
-# External Action View Modifier Plugin
-
This plugin is used to handle EXTERNAL states, allowing you to asynchronously tell Player when, and what to transition with once you have finished processing the external state request.
### CocoaPods
+
Add the subspec to your `Podfile`
```ruby
@@ -96,4 +95,4 @@ struct ExternalAlertModifier: ExternalStateViewModifier {
}
}
}
-```
\ No newline at end of file
+```
diff --git a/docs/site/pages/plugins/swiftui-pending-transaction.mdx b/docs/site/src/content/docs/plugins/iOS/swiftui-pending-transaction.mdx
similarity index 89%
rename from docs/site/pages/plugins/swiftui-pending-transaction.mdx
rename to docs/site/src/content/docs/plugins/iOS/swiftui-pending-transaction.mdx
index cceb54f61..7abbdd43a 100644
--- a/docs/site/pages/plugins/swiftui-pending-transaction.mdx
+++ b/docs/site/src/content/docs/plugins/iOS/swiftui-pending-transaction.mdx
@@ -3,11 +3,10 @@ title: SwiftUIPendingTransactionPlugin
platform: ios
---
-# SwiftUIPendingTransactionPlugin
-
The `SwiftUIPendingTransactionPlugin` allows you to register pending transactions (callbacks) in the userInfo on the decoder. Users can decide when to register, commit and clear transactions based on the use case. Anytime there is a scenario where we want a native transaction to happen while a view update is taking place, we can make use of this plugin. Below is an example used in the sample app where we can see this take place:
### CocoaPods
+
Add the subspec to your `Podfile`
```ruby
@@ -29,7 +28,6 @@ Declare a new object for keeping track of the namespaces or use the default stru
If you use the default `PendingTransactionPhases` the plugin can be defined like `SwiftUIPendingTransactionPlugin()` or using the typealias `PendingTransactionPhasesPlugin()`
Otherwise pass the new object in the generics on plugin initialization
-
**Step 2:**
If you use the default `PendingTransactionPhases`:
@@ -82,7 +80,7 @@ public extension EnvironmentValues {
To start registering transactions with the assets, access the transactionContext through the default environment variable above or the new one you created
-Register the transaction with the "input" phase (the view update) when a user starts editing the input, (code snippet taken from [InputAsset](https://github.com/player-ui/player/blob/main/ios/packages/reference-assets/Sources/SwiftUI/InputAsset.swift)
+Register the transaction with the "input" phase (the view update) when a user starts editing the input, (code snippet taken from [InputAsset](https://github.com/player-ui/player/blob/main/plugins/reference-assets/swiftui/Sources/SwiftUI/InputAsset.swift)
```swift
onEditingChanged: { editing in
@@ -100,14 +98,14 @@ onEditingChanged: { editing in
}
```
-Note: we can register multiple transactions under a single phase and we commit based on phase, when commiting a phase if multiple transactions exist they commit in no particular order
+Note: we can register multiple transactions under a single phase and we commit based on phase, when commiting a phase if multiple transactions exist they commit in no particular order
**Step 4:**
Commit the transaction (view update) before the action to navigate takes place. The WrappedFunction provides access to the userInfo where the TransactionContext is stored and users can use this how they see fit.
-Now in the [ActionAsset](https://github.com/player-ui/player/blob/main/ios/packages/reference-assets/Sources/SwiftUI/ActionAsset.swift) instead of calling WrappedFunction `run` directly, we can extend the WrappedFunction and create another function called commitCallbacksThenCall which does the same thing as the normal call function except it will check for any input callbacks and commit then if they exist.
+Now in the [ActionAsset](https://github.com/player-ui/player/blob/main/plugins/reference-assets/swiftui/Sources/SwiftUI/ActionAsset.swift) instead of calling WrappedFunction `run` directly, we can extend the WrappedFunction and create another function called commitCallbacksThenCall which does the same thing as the normal call function except it will check for any input callbacks and commit then if they exist.
```swift
extension WrappedFunction {
@@ -123,6 +121,7 @@ extension WrappedFunction {
```
Calling the new function inside of the action handler:
+
```swift
model.data.run?.commitCallbacksThenCall()
```
diff --git a/docs/site/pages/plugins/transition.mdx b/docs/site/src/content/docs/plugins/iOS/transition.mdx
similarity index 97%
rename from docs/site/pages/plugins/transition.mdx
rename to docs/site/src/content/docs/plugins/iOS/transition.mdx
index c7c26a38b..3173c214c 100644
--- a/docs/site/pages/plugins/transition.mdx
+++ b/docs/site/src/content/docs/plugins/iOS/transition.mdx
@@ -1,13 +1,11 @@
---
title: Transition Plugin
-platform: ios
---
-# Transition Plugin
-
The `TransitionPlugin` allows for specifying transitions for when Player loads a flow, and for transition between views in the same flow.
### CocoaPods
+
Add the subspec to your `Podfile`
```ruby
@@ -15,6 +13,7 @@ pod 'PlayerUI/TransitionPlugin'
```
### Swift Usage
+
```swift
SwiftUIPlayer(flow: flowString, plugins: [TransitionPlugin(popTransition: .pop)], result: $resultBinding)
```
@@ -54,4 +53,4 @@ PlayerViewTransition.push
/// Transition that slides views in from the leading edge and out from to the trailing edge of the screen
PlayerViewTransition.pop
-```
\ No newline at end of file
+```
diff --git a/docs/site/src/content/docs/plugins/index.mdx b/docs/site/src/content/docs/plugins/index.mdx
new file mode 100644
index 000000000..be2c1bd2b
--- /dev/null
+++ b/docs/site/src/content/docs/plugins/index.mdx
@@ -0,0 +1,13 @@
+---
+title: Plugins
+---
+
+import Image from "../../../components/Image.astro";
+import pluginsOverview from "../../../assets/plugin_overview.png";
+
+Plugins are one of the main ways to customize Player to suite individual use-cases.
+Internally they allow access to many of the core sub-systems, which can add features, configuration, or custom behaviors.
+
+
-
+
Install the plugin:
@@ -19,25 +20,26 @@ Install the plugin:
yarn add @player-ui/asset-provider-plugin-react
```
-Create an instance, and add it to your Player instance.
+Create an instance, and add it to your Player instance.
The API is similar to the JavaScript `Map`, and takes a list of `[match, Component]` tuples.
```tsx
-import { ReactPlayer } from '@player-ui/react';
-import { AssetProviderPlugin } from '@player-ui/asset-provider-plugin-react';
+import { ReactPlayer } from "@player-ui/react";
+import { AssetProviderPlugin } from "@player-ui/asset-provider-plugin-react";
const player = new ReactPlayer({
plugins: [
new AssetProviderPlugin([
- ['custom-asset', () =>
+This will register a match on `{ type: 'custom-asset' }` and `{ type: 'custom', key: 'asset' }` in the view to use your React components.
+
+
### Content
@@ -45,21 +47,21 @@ const player = new ReactPlayer({
In this example, when your content has assets of type `custom-asset` and `custom`, they will render `
-
+
```tsx
-import { Custom, CustomAsset, Collection } from 'my-assets';
+import { Custom, CustomAsset, Collection } from "my-assets";
const view = (
-
);
```
-
-
+
+
```json
{
@@ -79,13 +81,13 @@ const view = (
{
"asset": {
"id": "custom-1",
- "type": "custom-asset",
+ "type": "custom-asset"
}
},
{
"asset": {
"id": "custom-2",
- "type": "custom",
+ "type": "custom"
}
}
]
@@ -111,9 +113,8 @@ const view = (
}
```
- This will register a match on `{ type: 'custom-asset' }` and `{ type: 'custom', key: 'asset' }` in the view to use your React components.
-
-
+This will register a match on `{ type: 'custom-asset' }` and `{ type: 'custom', key: 'asset' }` in the view to use your React components.
+
+
-
diff --git a/docs/site/pages/plugins/async-node.mdx b/docs/site/src/content/docs/plugins/multiplatform/async-node.mdx
similarity index 92%
rename from docs/site/pages/plugins/async-node.mdx
rename to docs/site/src/content/docs/plugins/multiplatform/async-node.mdx
index f7a3f3b28..63d30fb64 100644
--- a/docs/site/pages/plugins/async-node.mdx
+++ b/docs/site/src/content/docs/plugins/multiplatform/async-node.mdx
@@ -1,11 +1,10 @@
---
title: AsyncNode Plugin
-platform: core,react,ios,android
---
-# Async Node Plugin
+import PlatformTabs from "../../../../components/PlatformTabs.astro";
-The AsyncNode Plugin is used to enable streaming additional content into a flow that has already been loaded and rendered.
+The AsyncNode Plugin is used to enable streaming additional content into a flow that has already been loaded and rendered.
A common use case for this plugin is conversational UI, as the users input more dialogue, new content must be streamed into Player in order to keep the UI up to date.
The pillar that makes this possible is the concept of an `AsyncNode`. An `AsyncNode` is any tree node with the property `async: true`, it represents a placeholder node that will be replaced by a concrete node in the future.
@@ -38,7 +37,7 @@ Returning a value in the above context enables uses cases where the async node o
### Continuous Streaming
-In order to keep streaming in new content, there must be at least 1 or more `AsyncNode`s in the view tree at all times.
+In order to keep streaming in new content, there must be at least 1 or more `AsyncNode`s in the view tree at all times.
This means there must be a constant renewal of new `AsyncNode`s after the previous ones are resolved by the user.
## Usage
@@ -47,7 +46,7 @@ The `AsyncNodePlugin` itself accepts an options object with a `plugins` array, e
The `AsyncNodePluginPlugin` is provided as a default way of handling asset-async nodes, it is just one handler for one possible way of using async nodes. If the default behavior does not align with the desired usage, users are able to provide their own implementation of the handler in the form of a plugin to be passed to the base `AsyncNodePlugin`. The `AsyncNodePluginPlugin` also comes from the `'@player-ui/async-node-plugin'` and contains the resolver and parser functionality.
-
+
Add the plugin to Player:
@@ -83,28 +82,30 @@ const player = new Player({
]
})
```
-
-
+
+
+
The `react` version of the AsyncNodePlugin is identical to using the core plugin. Refer to core usage for handler configuration:
```js
-import { ReactPlayer } from '@player-ui/react';
-import { AsyncNodePlugin, AsyncNodePluginPlugin } from '@player-ui/async-node-plugin';
+import { ReactPlayer } from "@player-ui/react";
+import {
+ AsyncNodePlugin,
+ AsyncNodePluginPlugin,
+} from "@player-ui/async-node-plugin";
const asyncNodePlugin = new AsyncNodePlugin({
- plugins: [new AsyncNodePluginPlugin()],
+ plugins: [new AsyncNodePluginPlugin()],
});
const player = new ReactPlayer({
- plugins: [
- asyncNodePlugin
- ]
-})
+ plugins: [asyncNodePlugin],
+});
```
-
-
+
+
### CocoaPods
@@ -180,15 +181,17 @@ Note: the AsyncNode struct is already defined in the plugin with the `async` pro
As a convenience to the user, the AsyncNodePlugin just takes a callback which has the content to be returned, this is provided to the plugin which calls the the `onAsyncNode` hook tap method. The return could be a single asset node or an array of asset nodes, or null if the async node is no longer relevant.
-
-
+
+
In build.gradle
+
```kotlin
implementation "com.intuit.playerui.plugins:async-node:$PLAYER_VERSION"
```
In integration code
+
```kotlin
import com.intuit.playerui.plugins.asyncnode.AsyncNodePlugin
@@ -212,5 +215,6 @@ asyncNodePlugin.hooks.onAsyncNode.tap("handleAsync") { hookContext, node ->
AndroidPlayer(asyncNodePlugin)
```
-
+
+
diff --git a/docs/site/pages/plugins/beacon.mdx b/docs/site/src/content/docs/plugins/multiplatform/beacon.mdx
similarity index 85%
rename from docs/site/pages/plugins/beacon.mdx
rename to docs/site/src/content/docs/plugins/multiplatform/beacon.mdx
index fb1d39a24..fa57ef440 100644
--- a/docs/site/pages/plugins/beacon.mdx
+++ b/docs/site/src/content/docs/plugins/multiplatform/beacon.mdx
@@ -1,11 +1,10 @@
---
title: Beacon Plugin
-platform: core,react,ios,android
---
-# Beacon Plugin
+import PlatformTabs from "../../../../components/PlatformTabs.astro";
-The beacon plugin enables users to send and/or collect beaconing information from assets in a normalized API. It exposes a common API for publishing beacons from an asset library, and will automatically attach itself to the current view, enabling additional meta-data to be added to each event.
+The beacon plugin enables users to send and/or collect beaconing information from assets in a normalized API. It exposes a common API for publishing beacons from an asset library, and will automatically attach itself to the current view, enabling additional meta-data to be added to each event.
## Consuming Beacons
@@ -16,7 +15,7 @@ By default, the beacon plugin returns beacons in the following format:
```ts
interface DefaultBeacon {
/** The user action taken ('clicked', 'visited') **/
- action: string;
+ action: string;
/** The type of UI element interacted with ('button', 'menu') **/
element: string;
@@ -35,23 +34,22 @@ interface DefaultBeacon {
## Usage
-
+
Add the beacon plugin to a player:
```ts
-import { Player } from '@player-ui/player';
-import { BeaconPlugin } from '@player-ui/beacon-plugin';
+import { Player } from "@player-ui/player";
+import { BeaconPlugin } from "@player-ui/beacon-plugin";
const player = new Player({
plugins: [
new BeaconPlugin({
-
// Any plugins to the beacon-plugin
plugins: [],
// Callback to handle any beacon event
- callback: () => {}
+ callback: () => {},
}),
],
});
@@ -61,31 +59,30 @@ Beacons can be published directly by the plugin, but in most cases, a platform s
```ts
beaconPlugin.beacon({
- action: 'click',
- element: 'button',
- asset: asset // The entire Asset object, for use in the plugin pipeline
+ action: "click",
+ element: "button",
+ asset: asset, // The entire Asset object, for use in the plugin pipeline
// other metadata
});
```
-
-
+
+
Just like with the _core_ variant, to add support for beaconing in the `react` player, add the plugin to Player:
```ts
-import { ReactPlayer } from '@player-ui/react';
-import { BeaconPlugin } from '@player-ui/beacon-plugin-react';
+import { ReactPlayer } from "@player-ui/react";
+import { BeaconPlugin } from "@player-ui/beacon-plugin-react";
const player = new ReactPlayer({
plugins: [
new BeaconPlugin({
-
// Any plugins to the beacon-plugin
plugins: [],
// Callback to handle any beacon event
- callback: () => {}
+ callback: () => {},
}),
],
});
@@ -93,10 +90,11 @@ const player = new ReactPlayer({
This will add additional React Context to the running player for the producers from asset-libraries to leverage.
-
-
+
+
### CocoaPods
+
Add the subspec to your `Podfile`
```ruby
@@ -156,8 +154,8 @@ var body: some View {
}
```
-
-
+
+
Beaconing on the JVM platform (including Android) is done with an instance of the `BeaconPlugin`. By default, the Android Player includes a wrapper of the core beacon plugin. The Android Player can be configured to override the default BeaconPlugin by passing a different BeaconPlugin implementation on instantiation which can contain further configuration.
@@ -201,14 +199,14 @@ androidPlayer.beacon(
The base `RenderableAsset` class provides an additional helper to make beaconing less verbose from an asset perspective.
-[Helper in RenderableAsset](https://github.com/player-ui/player/blob/2a2110caf87ab752207c82ec9ab8ce72316d20f5/android/player/src/main/java/com/intuit/player/android/asset/RenderableAsset.kt#L253)
+[Helper in RenderableAsset](https://github.com/player-ui/player/blob/main/android/player/src/main/java/com/intuit/playerui/android/asset/RenderableAsset.kt#L253)
-
+
### Beacon Plugins
-Similar to how Player accepts plugins, the beacon-plugin itself accepts a list of plugins. These are able to mutate and augment the beacon payload as it makes its way through the publishing pipeline.
+Similar to how Player accepts plugins, the beacon-plugin itself accepts a list of plugins. These are able to mutate and augment the beacon payload as it makes its way through the publishing pipeline.
There are 3 hooks that are currently exposed:
@@ -235,30 +233,30 @@ The beacon plugin adds support for a `beacon` expression that can be referenced
### Assets
-
+
#### useBeacon hook
-The `@player-ui/beacon-plugin-react` package exports a hook that assets can leverage to publish beacons.
+The `@player-ui/beacon-plugin-react` package exports a hook that assets can leverage to publish beacons.
The `useBeacon` hook takes base options that apply broadly, and returns a function with those options as the base. You can then pass event specific information when calling `beacon`.
**Example**
```jsx
-import { useBeacon } from '@player-ui/beacon-plugin-react';
+import { useBeacon } from "@player-ui/beacon-plugin-react";
// inside of your asset
export const Component = (props) => {
- const beacon = useBeacon({ action: 'clicked', asset: props });
+ const beacon = useBeacon({ action: "clicked", asset: props });
return (
-
+
+
The SwiftUIBeaconPlugin attaches a BeaconContext to the root of the SwiftUI view tree as an environment value, so when included any asset can use that context to send a beacon, if the context is in the environment:
@@ -284,11 +282,11 @@ struct ActionAssetView: View {
}
```
-
+
-
+
- Using the base `RenderableAsset`'s helper function in this example fires off a basic beacon with no adjustment to format as well as empty data upon button click
+Using the base `RenderableAsset`'s helper function in this example fires off a basic beacon with no adjustment to format as well as empty data upon button click
**Example**
@@ -320,5 +318,5 @@ class MyAsset(assetContext: AssetContext) :
}
```
-
+
diff --git a/docs/site/pages/plugins/check-path.mdx b/docs/site/src/content/docs/plugins/multiplatform/check-path.mdx
similarity index 78%
rename from docs/site/pages/plugins/check-path.mdx
rename to docs/site/src/content/docs/plugins/multiplatform/check-path.mdx
index 84e993a8f..7f98c78f8 100644
--- a/docs/site/pages/plugins/check-path.mdx
+++ b/docs/site/src/content/docs/plugins/multiplatform/check-path.mdx
@@ -1,17 +1,16 @@
---
title: Check Path Plugin
-platform: react,core,android
---
-# Check Path Plugin
+import PlatformTabs from "../../../../components/PlatformTabs.astro";
-The Check Path Plugin enables users to query segments of the view tree for contextual rendering or behavior.
+The Check Path Plugin enables users to query segments of the view tree for contextual rendering or behavior.
This is best suited to be referenced during the UI rendering phase, where one can make decisions about the rendering of an asset based on where it lies in the tree.
## Usage
-
+
Install the plugin:
@@ -22,7 +21,7 @@ yarn add @player-ui/check-path-plugin
Add it to Player:
```js
-import CheckPathPlugin from '@player-ui/check-path-plugin';
+import CheckPathPlugin from "@player-ui/check-path-plugin";
const checkPathPlugin = new CheckPathPlugin();
const player = new Player({ plugins: [checkPathPlugin] });
@@ -34,26 +33,27 @@ player.start(myFlow);
Then use the plugin to query the view:
```js
-const isCustomThing = checkPathPlugin.hasParentContext('my-asset-id', [
- 'input',
- 'myCustomViewType',
+const isCustomThing = checkPathPlugin.hasParentContext("my-asset-id", [
+ "input",
+ "myCustomViewType",
]);
```
-
-
+
+
Install the plugin:
```bash
yarn add @player-ui/check-path-plugin-react
```
+
6474792156
Add it to Player:
```js
-import { ReactPlayer } from '@player-ui/react';
-import { CheckPathPlugin } from '@player-ui/check-path-plugin-react';
+import { ReactPlayer } from "@player-ui/react";
+import { CheckPathPlugin } from "@player-ui/check-path-plugin-react";
const rp = new ReactPlayer({
plugins: [new CheckPathPlugin()],
@@ -62,9 +62,9 @@ const rp = new ReactPlayer({
This will automatically create the underlying _core_ version of the `CheckPathPlugin` to be made available via `React` Context for the hooks.
-
+
-
+
### CocoaPods
@@ -89,9 +89,10 @@ var body: some View {
)
}
```
-
-
+
+
+
In build.gradle
```kotlin
@@ -106,15 +107,15 @@ import com.intuit.playerui.plugins.checkpath.CheckPathPlugin
val plugins = listOf(CheckPathPlugin())
AndroidPlayer(plugins)
```
-
-
+
+
## API
-
+
### Query
@@ -125,13 +126,12 @@ This can either be a `function`, `string`, or an `object`.
- `object` - uses a partial-object match to query the object
- `function` - a filter that gets passed an object, and returns a boolean
-
There are a few different functions exposed by the plugin you can use:
### getParent
```ts
-function getParent(id: string, query: Query | Query[]): Asset | undefined
+function getParent(id: string, query: Query | Query[]): Asset | undefined;
```
The `getParent` method allows you to query up the tree, and return the first parent that matches the given query, or `undefined`.
@@ -142,7 +142,7 @@ If an array is passed, the tree is parsed matching on each query item from left
### getParentProp
```ts
-function getParentProp(id: string): string | undefined
+function getParentProp(id: string): string | undefined;
```
The `getParentProp` method returns the property on the parent object that the current object falls under.
@@ -153,7 +153,7 @@ For example, an `input` with a `text` asset as the label, will return `label` fo
### hasParentContext
```ts
-function hasParentContext(id: string, query: Query | Query[]): boolean
+function hasParentContext(id: string, query: Query | Query[]): boolean;
```
Similar to `getParent`, the `hasParentContext` method responds with the _existence_ of a parent with the given context.
@@ -163,14 +163,13 @@ Similar to `getParent`, the `hasParentContext` method responds with the _existen
### hasChildContext
```ts
-function hasChildContext(id: string, query: Query | Query[]): boolean
+function hasChildContext(id: string, query: Query | Query[]): boolean;
```
The compliment of `hasParentContext`, `hasChildContext` traverses _down_ the tree for _any_ path from the given node that satisfies the context requirements.
-
-
-
+
+
The API for the `React` version of the `CheckPathPlugin` is similar to the _core_ version, just exposed through `React` hooks for easy use in custom assets:
@@ -184,21 +183,21 @@ function useHasChildContext(id: string, query: Query | Query[]): boolean;
## Example
```tsx
-import { useHasParentContext } from '@player-ui/check-path-plugin-react';
+import { useHasParentContext } from "@player-ui/check-path-plugin-react";
export const MyAsset = ({ id }) => {
// If the asset is rendered within a form, render as a select instead of a radio button
- const isInForm = useHasParentContext(id, 'form');
+ const isInForm = useHasParentContext(id, "form");
return isInForm ? :
-
+
+
### Swift Usage
-The SwiftUICheckPathPlugin attaches the `BaseCheckPathPlugin` named `checkPath` to the root of the SwiftUI view tree as an environment value, so when included any asset can use that environment value to access the base functionality
+The SwiftUICheckPathPlugin attaches the `BaseCheckPathPlugin` named `checkPath` to the root of the SwiftUI view tree as an environment value, so when included any asset can use that environment value to access the base functionality
```swift
@@ -216,17 +215,16 @@ struct MyAsset: View {
}
```
-
-
+
+
+
The JVM CheckPathPlugin API contains partial functionality in comparison to the core plugin, ideally this should not be used, and all logic where pathing is concerned should be handled in transforms
If the situation arises and this plugin is absolutely necessary, the API from the following source are available at the moment. This is subject to change in future releases:
-[CheckPathPlugin](https://github.com/player-ui/player/blob/main/plugins/check-path/jvm/src/main/kotlin/CheckPathPlugin.kt)
+[CheckPathPlugin](https://github.com/player-ui/player/blob/main/plugins/check-path/jvm/src/main/kotlin/com/intuit/playerui/plugins/checkpath/CheckPathPlugin.kt)
-
+
-
-
diff --git a/docs/site/pages/plugins/console-logger.mdx b/docs/site/src/content/docs/plugins/multiplatform/console-logger.mdx
similarity index 68%
rename from docs/site/pages/plugins/console-logger.mdx
rename to docs/site/src/content/docs/plugins/multiplatform/console-logger.mdx
index d50835e00..ccb0fa3f9 100644
--- a/docs/site/pages/plugins/console-logger.mdx
+++ b/docs/site/src/content/docs/plugins/multiplatform/console-logger.mdx
@@ -1,40 +1,40 @@
---
title: Console Logger
-platform: react,core,ios
---
-# Console Logger Plugin
+import PlatformTabs from "../../../../components/PlatformTabs.astro";
A plugin to easily enable logs to be written to the JS console. Extremely helpful for local Player development and debugging.
## Usage
-
+
Install the plugin:
```js
-import { Player } from '@player-ui/player';
-import { ConsoleLoggerPlugin } from '@player-ui/console-logger-plugin';
+import { Player } from "@player-ui/player";
+import { ConsoleLoggerPlugin } from "@player-ui/console-logger-plugin";
const consoleLogger = new ConsoleLoggerPlugin();
const player = new Player({
- plugins: [consoleLogger]
+ plugins: [consoleLogger],
});
```
To change the severity:
```js
-consoleLogger.setSeverity('warn');
+consoleLogger.setSeverity("warn");
```
-
-
+
+
### CocoaPods
+
Add the subspec to your `Podfile`
```ruby
@@ -56,9 +56,10 @@ var body: some View {
```
To change the severity, supply it as an argument to the constructor:
+
```swift
PrintLoggerPlugin(level: .warn)
```
-
-
\ No newline at end of file
+
+
diff --git a/docs/site/pages/plugins/external-action.mdx b/docs/site/src/content/docs/plugins/multiplatform/external-action.mdx
similarity index 89%
rename from docs/site/pages/plugins/external-action.mdx
rename to docs/site/src/content/docs/plugins/multiplatform/external-action.mdx
index e9caeec19..58e24c276 100644
--- a/docs/site/pages/plugins/external-action.mdx
+++ b/docs/site/src/content/docs/plugins/multiplatform/external-action.mdx
@@ -1,16 +1,15 @@
---
title: External Action
-platform: react,core,ios,android
---
-# External Action Plugin
+import PlatformTabs from "../../../../components/PlatformTabs.astro";
-The External Action Plugin is an easy way to handle External states from the navigation of a Player flow.
+The External Action Plugin is an easy way to handle External states from the navigation of a Player flow.
## Usage
-
+
Install the plugin:
@@ -33,22 +32,21 @@ const externalActionHandler: ExternalStateHandler = async (state, options) => {
Add it to Player:
```js
-import { Player } from '@player-ui/player';
-import { ExternalActionPlugin } from '@player-ui/external-action-plugin';
+import { Player } from "@player-ui/player";
+import { ExternalActionPlugin } from "@player-ui/external-action-plugin";
const player = new Player({
- plugins: [
- new ExternalActionPlugin(externalActionHandler)
- ]
-})
+ plugins: [new ExternalActionPlugin(externalActionHandler)],
+});
```
This will transition any `EXTERNAL` state in Player's navigation, with a `ref` property of `custom` using the `next` transition.
-
-
+
+
### CocoaPods
+
Add the subspec to your `Podfile`
```ruby
@@ -116,8 +114,8 @@ var body: some View {
}
```
-
-
+
+
The `ExternalActionPlugin` adds support for handling `EXTERNAL` navigation states in the application. The handler, which can be provided during plugin initialization, receives three parameters:
@@ -126,12 +124,15 @@ The `ExternalActionPlugin` adds support for handling `EXTERNAL` navigation state
3. transition: `(String) -> Unit` is provided to enable the handler to "complete" the `EXTERNAL` state and transition using the provided `String` value
## Usage
+
In build.gradle
+
```kotlin
implementation "com.intuit.playerui.plugins:external-action:$PLAYER_VERSION"
```
In Player constructor
+
```kotlin
import com.intuit.playerui.plugins.externalAction.ExternalActionPlugin
@@ -157,6 +158,7 @@ androidPlayer.onExernalAction { /** handle external action */ }
```
In Player content
+
```json
{
"navigation": {
@@ -189,6 +191,7 @@ In Player content
Public API available from sources here:
-[ExternalActionPlugin](https://github.com/player-ui/player/blob/main/plugins/external-action/jvm/src/main/kotlin/com/intuit/player/plugins/externalAction/ExternalActionPlugin.kt)
-
-
\ No newline at end of file
+[ExternalActionPlugin](https://github.com/player-ui/player/blob/main/plugins/external-action/jvm/src/main/kotlin/com/intuit/playerui/plugins/externalAction/ExternalActionPlugin.kt)
+
+
+
diff --git a/docs/site/pages/plugins/metrics.mdx b/docs/site/src/content/docs/plugins/multiplatform/metrics.mdx
similarity index 81%
rename from docs/site/pages/plugins/metrics.mdx
rename to docs/site/src/content/docs/plugins/multiplatform/metrics.mdx
index d4e62d922..f6f869e4e 100644
--- a/docs/site/pages/plugins/metrics.mdx
+++ b/docs/site/src/content/docs/plugins/multiplatform/metrics.mdx
@@ -1,76 +1,77 @@
---
title: Metrics
-platform: core,react,ios,android
---
-# Metrics Plugin
+import PlatformTabs from "../../../../components/PlatformTabs.astro";
+import Image from "../../../../components/Image.astro";
+import metricsTiming from "../../../../assets/metrics-timing.png";
The Metrics Plugin is used to gather timing information about Player's execution of a flow. There are also platform specific integrations to include `render` and `update` times.
The diagram below illistrates some of the timing information gathered:
-
+
-
+
Add the plugin to Player:
```js
-import { Player } from '@player-ui/player';
-import { MetricsPlugin } from '@player-ui/metrics-plugin';
+import { Player } from "@player-ui/player";
+import { MetricsPlugin } from "@player-ui/metrics-plugin";
const player = new Player({
plugins: [
new MetricsPlugin({
onUpdate: (metrics) => {
// Handle the update
- }
- })
- ]
-})
+ },
+ }),
+ ],
+});
```
The `onUpdate` callback will be invoked for any update to the metrics. There are also callbacks for finer-grained events (`onRenderEnd`, `onInteractive`, etc), as well as a `hooks` based API for even more control.
## Using a custom timer
-By default, all time is measured in ms using `performance.now()` with a fallback to the less-accurate `Date.now()`.
+By default, all time is measured in ms using `performance.now()` with a fallback to the less-accurate `Date.now()`.
If you wish to supply your own timer, simply use the `getTime` option to set the function to use.
-
## Measuring Render Time
For extensions of this plugin that wish to track the render (and update) times of nodes, add the `trackRenderTime` flag to `options`. You must then call `metrics.renderEnd()` to denote when content is painted on the screen. This is automatically handled for the platform specific versions of this plugin.
-
-
+
+
The `react` version of the Metrics Plugin adds support for `render` and `update` times to events. The API mirrors that of the core version:
```js
-import { ReactPlayer } from '@player-ui/react';
-import { MetricsPlugin } from '@player-ui/metrics-plugin-react';
+import { ReactPlayer } from "@player-ui/react";
+import { MetricsPlugin } from "@player-ui/metrics-plugin-react";
const player = new ReactPlayer({
plugins: [
new MetricsPlugin({
onUpdate: (metrics) => {
// Handle the update
- }
- })
- ]
-})
+ },
+ }),
+ ],
+});
```
-
-
+
+
The `ios` version of the Metrics Plugin will track initial render time for each view in a flow. Due to current SwiftUI limitations, update time can't be tracked yet. It can be used in conjunction with a core plugin that utilizes the events, through `findPlugin`, or standalone.
### CocoaPods
+
Add the subspec to your `Podfile`
```ruby
@@ -78,6 +79,7 @@ pod 'PlayerUI/MetricsPlugin'
```
### Swift Usage
+
```swift
var body: some View {
SwiftUIPlayer(
@@ -93,17 +95,20 @@ var body: some View {
)
}
```
-
-
+
+
+
The `JVM` Metrics plugin can track render time for views in a flow.
In build.gradle
+
```kotlin
implementation "com.intuit.playerui.plugins:metrics:$PLAYER_VERSION"
```
In Player constructor
+
```kotlin
import com.intuit.playerui.plugins.expression.ExpressionPlugin
@@ -112,14 +117,14 @@ val metricsPlugin = MetricsPlugin { timing, renderMetrics, flowMetrics ->
}
AndroidPlayer(metricsPlugin)
```
-
-
+
+
## Beaconing
-
+
The Metrics Plugin also includes a plugin for the Beacon Plugin that adds render time to the hook context for `viewed` beacons send for views. This plugin is automatically registered to the Beacon Plugin if the `trackRenderTime` option is enabled.
@@ -146,7 +151,7 @@ class MyBeaconPluginPlugin implements BeaconPluginPlugin {
}
```
-See the [Beacon Plugin](./beacon) for more info.
+See the [Beacon Plugin](/plugins/multiplatform/beacon) for more info.
-
-
\ No newline at end of file
+
+
diff --git a/docs/site/pages/plugins/partial-match-fingerprint.mdx b/docs/site/src/content/docs/plugins/multiplatform/partial-match-fingerprint.mdx
similarity index 67%
rename from docs/site/pages/plugins/partial-match-fingerprint.mdx
rename to docs/site/src/content/docs/plugins/multiplatform/partial-match-fingerprint.mdx
index 67c0ed8c9..399c8d3ec 100644
--- a/docs/site/pages/plugins/partial-match-fingerprint.mdx
+++ b/docs/site/src/content/docs/plugins/multiplatform/partial-match-fingerprint.mdx
@@ -1,53 +1,51 @@
---
title: Partial Match
-platform: core, ios
---
-# Partial Match Plugin
-
-This plugin enables users to map matches of assets to any arbitrary value in a partial-match-registry.
-For each asset in a resolved view, the matches will be computed.
+import PlatformTabs from "../../../../components/PlatformTabs.astro";
+This plugin enables users to map matches of assets to any arbitrary value in a partial-match-registry.
+For each asset in a resolved view, the matches will be computed.
## Usage
-
+
Create a registry and add matches:
```ts
-import { Registry } from '@player-ui/partial-match-registry';
+import { Registry } from "@player-ui/partial-match-registry";
-const registry = new Registry([
- [{ type: 'action' }, 'ABC']
-])
+const registry = new Registry([[{ type: "action" }, "ABC"]]);
```
Add the registy to a plugin:
```ts
-import { Player } from '@player-ui/player';
-import { PartialMatchFingerprintPlugin } from '@player-ui/partial-match-fingerprint-plugin';
+import { Player } from "@player-ui/player";
+import { PartialMatchFingerprintPlugin } from "@player-ui/partial-match-fingerprint-plugin";
const matchPlugin = new PartialMatchFingerprintPlugin(registry);
const player = new Player({
- plugins: [matchPlugin]
-})
+ plugins: [matchPlugin],
+});
```
Query the plugin for matches:
```ts
-const value = matchPlugin.get('asset-id') // 'ABC'
+const value = matchPlugin.get("asset-id"); // 'ABC'
```
-
-
+
+
+
This plugin is used by `BaseAssetRegistry` to handle matching resolved asset nodes with their native implementation, to decode for rendering. It is unlikely to be needed to be used directly in iOS use cases.
### CocoaPods
+
Add the subspec to your `Podfile`
```ruby
@@ -55,6 +53,7 @@ pod 'PlayerUI'
```
### Swift Usage
+
```swift
let plugin = PartialMatchFingerprintPlugin()
@@ -65,5 +64,6 @@ plugin.register(match: ["type": "text"], index: 1)
// get the index for the asset with matching ID if it was resolved in the core plugin
plugin.get(assetId: "test")
```
-
-
\ No newline at end of file
+
+
+
diff --git a/docs/site/pages/plugins/pub-sub.mdx b/docs/site/src/content/docs/plugins/multiplatform/pub-sub.mdx
similarity index 82%
rename from docs/site/pages/plugins/pub-sub.mdx
rename to docs/site/src/content/docs/plugins/multiplatform/pub-sub.mdx
index 0061bc2ab..a9fe2bcf8 100644
--- a/docs/site/pages/plugins/pub-sub.mdx
+++ b/docs/site/src/content/docs/plugins/multiplatform/pub-sub.mdx
@@ -1,32 +1,31 @@
---
title: PubSub
-platform: core,react,ios,android
---
-# PubSub Plugin
+import PlatformTabs from "../../../../components/PlatformTabs.astro";
-The PubSub plugin adds a publish/subscribe interface between the host app and Player's content.
+The PubSub plugin adds a publish/subscribe interface between the host app and Player's content.
## Usage
-
+
Add the plugin to Player:
```ts
-import { Player } from '@player-ui/player';
-import { PubSubPlugin } from '@player-ui/pub-sub-plugin';
+import { Player } from "@player-ui/player";
+import { PubSubPlugin } from "@player-ui/pub-sub-plugin";
const pubsub = new PubSubPlugin();
-const token = pubsub.subscribe('some-event', () => {
+const token = pubsub.subscribe("some-event", () => {
// Callback
});
const player = new Player({
- plugins: [pubsub]
-})
+ plugins: [pubsub],
+});
```
To unsubscribe:
@@ -35,12 +34,13 @@ To unsubscribe:
pubsub.unsubscribe(token);
```
-
-
+
+
If your content uses the `@[ publish() ]@` expression for actions, you can subscribe to these events by using the `PubSubPlugin`.
### CocoaPods
+
Add the subspec to your `Podfile`
```ruby
@@ -48,6 +48,7 @@ pod 'PlayerUI/PubSubPlugin'
```
### Swift Usage
+
```swift
let eventHandler: (String, AnyType?) -> Void = { (eventName, eventData) in
// Handle event
@@ -62,6 +63,7 @@ let plugin = PubSubPlugin([("eventName", eventHandler)], options: PubSubPluginOp
```
Then, just include it in your `plugins` to a Player instance:
+
```swift
var body: some View {
SwiftUIPlayer(
@@ -76,8 +78,8 @@ var body: some View {
_Note: AnyType is a custom enum type to handle the arbitrary types that can be received from these events, as the data is set in your Player Content, ensure that it matches either String, [String], or [String: String]._
-
-
+
+
The `PubSubPlugin` provides support for handling the publish expressions in Player content at the app level. The PubSubPlugin is included by default in the Android Player, so configuring events subscriptions can be done on Player using the provided extension methods.
@@ -88,6 +90,7 @@ The `PubSubPlugin` provides support for handling the publish expressions in Play
"exp": "@[ publish('some-event', {{foo.bar}}) ]@"
}
```
+
```kotlin
val player = AndroidPlayer(context)
@@ -98,16 +101,16 @@ val token = player.subscribe("some-event") { name: String, data: Any? ->
// handle event
}
-// extension method for removing a specific event subscription
+// extension method for removing a specific event subscription
player.unsubscribe(token)
```
-
+
## Publish Expression
-To trigger an event to be published, use the `publish()` expression in Player's content:
+To trigger an event to be published, use the `publish()` expression in Player's content:
```json
{
@@ -117,4 +120,4 @@ To trigger an event to be published, use the `publish()` expression in Player's
"exp": "@[ publish('some-event', 'some optional data') ]@""
}
}
-```
\ No newline at end of file
+```
diff --git a/docs/site/pages/plugins/shared-constants.mdx b/docs/site/src/content/docs/plugins/multiplatform/shared-constants.mdx
similarity index 54%
rename from docs/site/pages/plugins/shared-constants.mdx
rename to docs/site/src/content/docs/plugins/multiplatform/shared-constants.mdx
index be4299e64..68b372163 100644
--- a/docs/site/pages/plugins/shared-constants.mdx
+++ b/docs/site/src/content/docs/plugins/multiplatform/shared-constants.mdx
@@ -1,50 +1,48 @@
---
title: Shared Constants
-platform: core,react
---
-# Shared Constants Plugin
+import PlatformTabs from "../../../../components/PlatformTabs.astro";
The Shared Constants Plugin enables users to define and override commonly used static values. It can be leveraged by other plugins to enable localization.
## Usage
-
+
Create the plugin and add it to Player:
```ts
-
-import { Player } from '@player-ui/player';
-import { ConstantsPlugin } from '@player-ui/shared-constants-plugin';
+import { Player } from "@player-ui/player";
+import { ConstantsPlugin } from "@player-ui/shared-constants-plugin";
const constantsPlugin = new ConstantsPlugin({
data: {
- prop1: 'A',
- prop2: 'B'
+ prop1: "A",
+ prop2: "B",
},
- namespace: 'constants',
- dataPath: 'data.constants'
+ namespace: "constants",
+ dataPath: "data.constants",
});
const player = new Player({
- plugins: [ constantsPlugin ]
+ plugins: [constantsPlugin],
});
```
You can then query the plugin to get the value of a particular key:
```js
-constantsPlugin.getConstants('prop1') // 'A'
+constantsPlugin.getConstants("prop1"); // 'A'
```
-
+
### Overriding Values in Content
-The `dataPath` configuration option enables content to override specific values for a particular flow:
+The `dataPath` configuration option enables content to override specific values for a particular flow:
```json
{
@@ -60,41 +58,40 @@ using a similar query for `prop1`, the value in the content takes precidence and
### Fallback Values
-Any query can also specify an optional _default_ value to return:
+Any query can also specify an optional _default_ value to return:
```js
-constantsPlugin.getConstants('prop3', 'default value') // 'default value'
+constantsPlugin.getConstants("prop3", "default value"); // 'default value'
```
## Examples
-### Common Types Plugin
+### Common Types Plugin
The Common Types Plugin leverages this pattern to allow for global contextual message overrides. In order to override those messages you may use something like:
```ts
-import { Player } from '@player-ui/player';
-import { ConstantsPlugin } from '@player-ui/constants-plugion';
-import { CommonTypesPlugin } from '@player-ui/common-types-plugin';
+import { Player } from "@player-ui/player";
+import { ConstantsPlugin } from "@player-ui/constants-plugion";
+import { CommonTypesPlugin } from "@player-ui/common-types-plugin";
const player = new Player({
plugins: [
new CommonTypesPlugin(),
new ConstantsPlugin({
- namespace: 'constants',
- dataPath: 'data.constants',
+ namespace: "constants",
+ dataPath: "data.constants",
data: {
validation: {
lengthError: {
- minimum: 'Way too short',
- maximum: 'Way too long',
- }
- }
- }
- })
- ]
+ minimum: "Way too short",
+ maximum: "Way too long",
+ },
+ },
+ },
+ }),
+ ],
});
```
-Any triggerd validation for the `length` validation will now use the custom error messages. See the [Common Types Plugin](./common-types) for more information on the supported overrides and paths.
-
+Any triggerd validation for the `length` validation will now use the custom error messages. See the [Common Types Plugin](/plugins/core/common-types) for more information on the supported overrides and paths.
diff --git a/docs/site/pages/plugins/auto-scroll-manager.mdx b/docs/site/src/content/docs/plugins/react/auto-scroll-manager.mdx
similarity index 56%
rename from docs/site/pages/plugins/auto-scroll-manager.mdx
rename to docs/site/src/content/docs/plugins/react/auto-scroll-manager.mdx
index 253182221..28632d1f2 100644
--- a/docs/site/pages/plugins/auto-scroll-manager.mdx
+++ b/docs/site/src/content/docs/plugins/react/auto-scroll-manager.mdx
@@ -1,51 +1,52 @@
---
title: Auto Scroll Manager Plugin
-platform: react
---
-# Auto Scroll Manager Plugin
+import PlatformTabs from "../../../../components/PlatformTabs.astro";
-The Auto Scroll Plugin helps orchestrate scrolling to components based off of 3 scenarios:
+The Auto Scroll Plugin helps orchestrate scrolling to components based off of 3 scenarios:
- On page load
- On validation trigger
- On first appearance after page load
-## Usage
+## Usage
-
+
Pull in the plugin and attach it to a player instance:
```tsx
-import { ReactPlayer } from '@player-ui/react';
-import { AutoScrollManagerPlugin } from '@player-ui/auto-scroll-manager-plugin-react';
+import { ReactPlayer } from "@player-ui/react";
+import { AutoScrollManagerPlugin } from "@player-ui/auto-scroll-manager-plugin-react";
const reactPlayer = new ReactPlayer({
- plugins: [new AutoScrollManagerPlugin()]
+ plugins: [new AutoScrollManagerPlugin()],
});
```
Next you'll use the provided `useRegisterAsScrollable` hook to register a component as a scrollable target in a `useLayoutEffect` or similar hook.
```tsx
-import { useRegisterAsScrollable, ScrollType } from '@player-ui/auto-scroll-manager-plugin-react';
+import {
+ useRegisterAsScrollable,
+ ScrollType,
+} from "@player-ui/auto-scroll-manager-plugin-react";
const CustomScrollableAsset = (props: CustomAssetType) => {
const registerFunction = useRegisterAsScrollable();
-
+
useLayoutEffect(() => {
registerFunction({
type: ScrollType.FirstAppearance,
- ref: props.id
- })
- }, [])
-
- return
-
\ No newline at end of file
+
+
diff --git a/docs/site/pages/tools/cli.mdx b/docs/site/src/content/docs/tools/cli.mdx
similarity index 89%
rename from docs/site/pages/tools/cli.mdx
rename to docs/site/src/content/docs/tools/cli.mdx
index c040ec8f9..269c1e36a 100644
--- a/docs/site/pages/tools/cli.mdx
+++ b/docs/site/src/content/docs/tools/cli.mdx
@@ -2,9 +2,7 @@
title: CLI
---
-# CLI
-
-The `CLI` package is a simple way for users to interact with some of the build/validation tooling. As new capabilities are added to the ecosystem, they may be exposed via this cli to use of use for developers.
+The `CLI` package is a simple way for users to interact with some of the build/validation tooling. As new capabilities are added to the ecosystem, they may be exposed via this cli to use of use for developers.
## Config
@@ -24,10 +22,10 @@ Example:
```js
module.exports = {
- extends: '@my-scope/base',
+ extends: "@my-scope/base",
plugins: [
- 'plugin-npm-package',
- ['some-plugin-with-config', { config: true }],
+ "plugin-npm-package",
+ ["some-plugin-with-config", { config: true }],
{
// Plugins can also be defined inline
handler: () => {},
@@ -42,10 +40,10 @@ Options defined via the CLI arguments will take precedence over the config files
Plugins are the way to change runtime behavior of the CLI actions. This includes augmenting the behavior of the DSL compiler, language-service, and more.
-# Commands
+## Commands
- [`player dsl compile`](#player-dsl-compile)
-Compile Player DSL files into JSON after running TSC compiler against Typescript files
+ Compile Player DSL files into JSON after running TSC compiler against Typescript files
```
USAGE
@@ -64,11 +62,11 @@ DESCRIPTION
```
- [`player dsl validate`](#player-dsl-validate)
-Runs isolated TSC compiler on authored Player DSL Typescript files.
+ Runs isolated TSC compiler on authored Player DSL Typescript files.
```
USAGE
- $ player dsl validate [-f ] [-c ]
+ $ player dsl validate [-f ] [-c ]
FLAGS
-c, --config= Path to a specific config file to load.
@@ -80,7 +78,7 @@ DESCRIPTION
```
- [`player json validate`](#player-json-validate)
-Validate Player JSON content
+ Validate Player JSON content
```
USAGE
@@ -96,7 +94,7 @@ DESCRIPTION
```
- [`player dependency-versions check`](#player-dependency-versions-check)
-Checks for `@player-ui/@player-tools` dependency version mismatches and issues warnings/solutions accordingly
+ Checks for `@player-ui/@player-tools` dependency version mismatches and issues warnings/solutions accordingly
```
USAGE
@@ -116,4 +114,4 @@ DESCRIPTION
- `@player-ui/@player-tools` dependencies are fetched not only from inside the 'node_modules' at the top of the repository in which it is run but also from 'node_modules' in sub-directories.
For example, if you have some 'node_modules' inside of a 'packages' folder that contains `@player-ui/@player-tools` dependencies, then these will also be fetched.
The display of such dependencies also depends on the first bullet point.
-```
\ No newline at end of file
+```
diff --git a/docs/site/pages/tools/storybook.mdx b/docs/site/src/content/docs/tools/storybook.mdx
similarity index 81%
rename from docs/site/pages/tools/storybook.mdx
rename to docs/site/src/content/docs/tools/storybook.mdx
index fbaadbc7a..237e664d8 100644
--- a/docs/site/pages/tools/storybook.mdx
+++ b/docs/site/src/content/docs/tools/storybook.mdx
@@ -2,6 +2,12 @@
title: Player + Storybook Integration
---
+import Image from "../../../components/Image.astro";
+import eventsAddonGif from "../../../assets/tools/storybook/events-addon.gif";
+import flowAddonGif from "../../../assets/tools/storybook/flow-addon.gif";
+import docsAddonGif from "../../../assets/tools/storybook/docs-addon.gif";
+import flowResetGif from "../../../assets/tools/storybook/flow-reset.gif";
+
## Reference Assets
The reference asset set, complete with the storybook-plugin integration below is available [here](/storybook-demo)
@@ -60,19 +66,19 @@ export const parameters = {
The events panel addon shows a timeline of events as the flow is processed. Here you will see logs, render/update metrics, data mutations, and more.
-
+ = {
The reset button in the toolbar will reset the running Player with the initial content. This is useful for clearing any data or validation state, or for resetting a completed flow.
-
+
+
diff --git a/docs/site/src/pages/tools/view-ast-explorer.astro b/docs/site/src/pages/tools/view-ast-explorer.astro
new file mode 100644
index 000000000..96bf47149
--- /dev/null
+++ b/docs/site/src/pages/tools/view-ast-explorer.astro
@@ -0,0 +1,16 @@
+---
+import StarlightPage from "@astrojs/starlight/components/StarlightPage.astro";
+import ASTExplorer from "../../components/tools/ASTExplorer";
+---
+
+
+
diff --git a/docs/site/src/styles/custom.css b/docs/site/src/styles/custom.css
new file mode 100644
index 000000000..5436aefa8
--- /dev/null
+++ b/docs/site/src/styles/custom.css
@@ -0,0 +1,11 @@
+html[data-theme="dark"] img[src*="lightModeOnly"] {
+ display: none !important;
+}
+
+html[data-theme="light"] img[src*="darkModeOnly"] {
+ display: none !important;
+}
+
+:root {
+ --sl-content-width: 80rem;
+}
diff --git a/docs/site/src/tailwind.css b/docs/site/src/tailwind.css
new file mode 100644
index 000000000..510ff1d53
--- /dev/null
+++ b/docs/site/src/tailwind.css
@@ -0,0 +1,4 @@
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+@tailwind variants;
diff --git a/docs/site/tailwind.config.mjs b/docs/site/tailwind.config.mjs
new file mode 100644
index 000000000..f8363cf5c
--- /dev/null
+++ b/docs/site/tailwind.config.mjs
@@ -0,0 +1,10 @@
+import starlightPlugin from "@astrojs/starlight-tailwind";
+
+/** @type {import('tailwindcss').Config} */
+export default {
+ content: ["./src/**/*.{astro,html,js,jsx,md,mdx,svelte,ts,tsx,vue}"],
+ theme: {
+ extend: {},
+ },
+ plugins: [starlightPlugin()],
+};
diff --git a/docs/site/tsconfig.json b/docs/site/tsconfig.json
index c3d7583d8..bcbf8b509 100644
--- a/docs/site/tsconfig.json
+++ b/docs/site/tsconfig.json
@@ -1,16 +1,3 @@
{
- "extends": "../../tsconfig.json",
- "compilerOptions": {
- "module": "esnext",
- "emitDeclarationOnly": false
- },
- "include": [
- "components",
- "components/**/*.json",
- "config",
- "config/**/*.json",
- "public",
- "pages",
- "plugins"
- ]
+ "extends": "astro/tsconfigs/strict"
}
diff --git a/docs/site/webpack.config.ts b/docs/site/webpack.config.ts
deleted file mode 100644
index 40d8855cb..000000000
--- a/docs/site/webpack.config.ts
+++ /dev/null
@@ -1,133 +0,0 @@
-import path from "path";
-import CopyWebpackPlugin from "copy-webpack-plugin";
-import smartypants from "remark-smartypants";
-import rehypeSlug from "rehype-slug";
-import rehypeAutolinkHeadings from "rehype-autolink-headings";
-import { URL } from "url";
-import webpack from "webpack";
-import HTMLWebpackPlugin from "html-webpack-plugin";
-import TerserPlugin from "terser-webpack-plugin";
-
-import fs from "fs";
-
-const __dirname = new URL(".", import.meta.url).pathname;
-
-const findPageRoutes = (searchPath = "./pages") => {
- const files = fs.readdirSync(searchPath);
- const routes: string[] = [];
-
- files.forEach((file) => {
- const filePath = path.join(searchPath, file);
- if (fs.statSync(filePath).isDirectory()) {
- routes.push(...findPageRoutes(filePath));
- } else if ([".mdx", ".tsx", ".md", ".ts"].includes(path.extname(file))) {
- // without extension
- const ext = path.extname(file);
- const fileName = file.replace(ext, "");
-
- routes.push(path.relative("./pages", path.join(searchPath, fileName)));
- }
- });
-
- return routes;
-};
-
-const pageRoutes = findPageRoutes();
-
-const config = {
- mode: process.env.NODE_ENV ?? "development",
- devtool: "source-map",
- entry: "./components/App.tsx",
- optimization: {
- minimize: process.env.NODE_ENV === "production",
- minimizer: [new TerserPlugin()],
- splitChunks: {
- chunks: "all",
- },
- },
- output: {
- publicPath: "auto",
- filename: "[name].[hash].js",
- },
- module: {
- rules: [
- {
- test: /plugin-nav-data.json$/,
- use: [path.join(__dirname, "./plugins/plugin-nav-generator.cjs")],
- },
- {
- test: /search-index.json$/,
- use: [path.join(__dirname, "./plugins/search-index-loader.cjs")],
- },
- {
- test: /.mdx?$/, // load both .md and .mdx files
- use: [
- {
- loader: "babel-loader",
- options: {
- presets: [
- ["@babel/preset-env", { targets: "defaults" }],
- "@babel/preset-react",
- ],
- },
- },
- {
- loader: "@mdx-js/loader",
- options: {
- jsx: true,
- remarkPlugins: [
- smartypants, // Formatting (convert -- to em/en dash)
- ],
- rehypePlugins: [
- rehypeSlug, // Add ids to headings
- [rehypeAutolinkHeadings, { behavior: "wrap" }], // Make headings links
- ],
- },
- },
- path.join(__dirname, "./plugins/md-layout-loader.cjs"),
- path.join(__dirname, "./plugins/mdx-link-append-loader.cjs"),
- ],
- },
- {
- test: /\.css$/,
- oneOf: [
- { include: /node_modules/, use: ["style-loader", "css-loader"] },
- { exclude: /node_modules/, use: ["style-loader", "css-loader"] },
- ],
- },
- {
- exclude: /(node_modules)/,
- loader: "ts-loader",
- test: /\.tsx?$/,
- },
- ],
- },
- resolve: {
- extensions: [".js", ".cjs", ".jsx", ".ts", ".tsx", ".md", ".mdx"],
- },
- plugins: [
- new webpack.DefinePlugin({
- "process.env": {
- NODE_ENV: JSON.stringify(process.env.NODE_ENV),
- CHANGE_ID: JSON.stringify(process.env.CHANGE_ID || "latest"),
- },
- }),
- new CopyWebpackPlugin({
- patterns: [
- {
- from: "./public",
- },
- ],
- }),
-
- ...pageRoutes.map((key) => {
- return new HTMLWebpackPlugin({
- title: "Player UI",
- template: "./config/index.html",
- filename: `${key}.html`,
- });
- }),
- ],
-};
-
-export default config;
diff --git a/package.json b/package.json
index 207675f10..e1a3f22d4 100644
--- a/package.json
+++ b/package.json
@@ -13,6 +13,11 @@
},
"packageManager": "pnpm@9.7.0",
"dependencies": {
+ "@astrojs/react": "^3.6.2",
+ "@astrojs/starlight": "^0.28.3",
+ "@astrojs/starlight-docsearch": "^0.2.0",
+ "@astrojs/starlight-tailwind": "^2.0.3",
+ "@astrojs/tailwind": "^5.1.0",
"@auto-it/omit-release-notes": "^11.2.0",
"@auto-it/upload-assets": "^11.2.0",
"@auto-it/version-file": "^11.2.0",
@@ -75,6 +80,7 @@
"@types/redux-state-sync": "^3.1.5",
"@types/signale": "^1.4.2",
"@types/std-mocks": "^1.0.1",
+ "@types/stringify-object": "^4.0.5",
"@types/uuid": "^8.3.4",
"@typescript-eslint/eslint-plugin": "^5.1.0",
"@typescript-eslint/parser": "^5.1.0",
@@ -82,6 +88,7 @@
"@vitest/coverage-v8": "^1.0.2",
"all-contributors-cli": "^6.20.0",
"arr-flatten": "^1.1.0",
+ "astro": "^4.16.7",
"auto": "^11.2.0",
"autoprefixer": "^10.4.17",
"babel-loader": "^9.1.3",
@@ -92,6 +99,7 @@
"clsx": "^1.1.1",
"copy-webpack-plugin": "^12.0.2",
"css-loader": "^6.10.0",
+ "daisyui": "^4.12.10",
"dequal": "^2.0.2",
"dlv": "^1.1.3",
"ebnf": "^1.9.0",
@@ -109,6 +117,7 @@
"html-webpack-plugin": "^5.6.0",
"husky": "^7.0.2",
"is-ci-cli": "^2.2.0",
+ "json5": "^2.2.3",
"lcov-result-merger": "^3.1.0",
"leven": "3.1.0",
"lint-staged": "^11.2.3",
@@ -118,6 +127,7 @@
"mdast-util-from-markdown": "^2.0.0",
"mdast-util-toc": "^6.1.0",
"mini-css-extract-plugin": "^2.8.1",
+ "monaco-editor": "^0.51.0",
"next": "14.0.2",
"next-themes": "^0.3.0",
"nextjs-google-analytics": "^1.2.1",
@@ -126,6 +136,7 @@
"parsimmon": "^1.12.0",
"patch-package": "^6.4.7",
"path-browserify": "^1.0.1",
+ "playwright": "^1.47.0",
"postcss": "^8.4.33",
"postcss-loader": "^8.1.1",
"prettier": "^3.1.0",
@@ -145,6 +156,7 @@
"redux": "^4.1.2",
"redux-state-sync": "^3.1.4",
"rehype-autolink-headings": "^6.1.1",
+ "rehype-mermaid": "^2.1.0",
"rehype-slug": "^5.0.1",
"remark": "^12.0.1",
"remark-autolink-headings": "^7.0.1",
@@ -155,12 +167,14 @@
"remark-smartypants": "^2.0.0",
"remove-markdown": "^0.3.0",
"seamless-scroll-polyfill": "^2.3.4",
+ "sharp": "^0.33.5",
"signale": "^1.4.0",
"sorted-array": "^2.0.4",
"source-map-js": "^1.0.2",
"std-mocks": "^1.0.1",
"storybook": "^7.6.10",
"storybook-dark-mode": "3.0.3",
+ "stringify-object": "^5.0.0",
"style-loader": "^3.3.4",
"tailwind-merge": "^2.2.1",
"tailwindcss": "^3.4.1",
@@ -185,7 +199,7 @@
"webpack-dev-server": "^5.0.4"
},
"volta": {
- "node": "20.16.0",
+ "node": "20.17.0",
"pnpm": "9.7.0"
},
"pnpm": {
diff --git a/plugins/reference-assets/react/postcss.config.js b/plugins/reference-assets/react/postcss.config.js
index 5167d9fec..12a703d90 100644
--- a/plugins/reference-assets/react/postcss.config.js
+++ b/plugins/reference-assets/react/postcss.config.js
@@ -1,4 +1,6 @@
-/* eslint-disable @typescript-eslint/no-var-requires */
module.exports = {
- plugins: [require("tailwindcss")(), require("autoprefixer")()],
+ plugins: {
+ tailwindcss: {},
+ autoprefixer: {},
+ },
};
diff --git a/plugins/reference-assets/react/src/assets/choice/Choice.tsx b/plugins/reference-assets/react/src/assets/choice/Choice.tsx
index 962409f7d..14787f7ce 100644
--- a/plugins/reference-assets/react/src/assets/choice/Choice.tsx
+++ b/plugins/reference-assets/react/src/assets/choice/Choice.tsx
@@ -18,7 +18,7 @@ export const Choice = (props: TransformedChoice) => {
));
return (
-
{props.header &&
@@ -62,14 +62,14 @@ const CustomAssetComp = (props) => {
This would automatically find the appropriate handler for the `props.header` asset and use that to render.
-
- Hello World!
],
- [{ type: 'custom', key: 'asset' }, () => Other Custom Asset
],
- ])
- ]
-})
+ ["custom-asset", () => Hello World!
],
+ [{ type: "custom", key: "asset" }, () => Other Custom Asset
],
+ ]),
+ ],
+});
```
- This will register a match on `{ type: 'custom-asset' }` and `{ type: 'custom', key: 'asset' }` in the view to use your React components.
- Hello World!
` and `Other Custom Asset
`.
+ Content can be authored using JSON, or (preferred) with a TypeScript/React + API. Below is a sample editor where you can explore authoring content using + the DSL and our reference assets. +
++ The internal representation of the View parses into an AST structure. This + is often used during the transform phase to edit the content prior to + rendering. Below is an interactive way of previewing the internal AST + representation for the given content. +
+
+
{title && (