@onlive.ai/flow

v0.3.28

Published

4 months ago

A package containing reusable web components for building multi-step flows with forms, actions, and stages.

0High
0Medium
0Low

liesner

adrian.onlive.ai

Onlive Flow

A package containing reusable web components for building multi-step flows with forms, actions, and stages.

Overview

The Onlive Flow package is designed to facilitate the creation of interactive flows with multiple steps, forms, and actions. It provides a set of components that can be easily integrated into your web applications.

It uses the Onlive Flow Client to manage the flow process, including data handling, navigation, and state management.

Installation

Using pnpm (recommended)

pnpm add @onlive.ai/flow
# or
npm install @onlive.ai/flow

CDN

You can also use the components directly from the CDN without any installation:

<!-- Load all components -->
<script type="module" src="https://cdn.onlive.site/@onlive.ai/flow@latest/index.iife.js"></script>

<!-- Or load individual components -->
<script
  type="module"
  src="https://cdn.onlive.site/@onlive.ai/flow@latest/components/flow/flow.js"
></script>

Package Structure

This package provides the following components and exports:

Main Components

OflFlow - Main container component that manages the complete flow process
OflStages - Component for displaying stage progress and navigation
OflForm - Form component for rendering fields and handling validation
OflField - Individual field component supporting various input types
OflActions - Component for rendering action buttons

Exports

// Main component classes
export { OflField } from "./components/field/field";
export { OflForm } from "./components/form/form";
export { OflActions } from "./components/actions/actions";
export { OflFlow } from "./components/flow/flow";

// Types from flow-client
export type { Field, FieldValue } from "@onlive.ai/flow-client";

Directory Structure

packages/flow/
├── components/
│   ├── actions/     # Action buttons component
│   ├── field/       # Individual field component
│   ├── flow/        # Main flow container component
│   ├── form/        # Form container component
│   └── stages/      # Stage progress component
├── docs/            # Documentation assets
├── index.ts         # Main entry point
└── package.json     # Package configuration

Build Formats

The package is built in multiple formats to support different usage scenarios:

ESM (index.js) - ES6 modules for modern bundlers
CommonJS (index.cjs) - CommonJS for Node.js environments
IIFE (index.iife.js) - Immediately Invoked Function Expression for direct browser usage
TypeScript Definitions (index.d.ts) - Type definitions for TypeScript projects

Dependencies

This package depends on:

@onlive.ai/ui - UI component library for styling
@onlive.ai/flow-client - Flow management and API client
@onlive.ai/common-121 - Common utilities and types
@onlive.ai/calendar - Calendar components for date fields
lit - Web components framework
validator - Input validation utilities

Quick Start

Here's a simple example of how to use the main ofl-flow component:

<!DOCTYPE html>
<html>
<head>
  <title>Onlive Flow Example</title>
</head>
<body>
  <!-- Load from CDN -->
  <script
    type="module"
    src="https://cdn.onlive.site/@onlive.ai/flow@latest/index.iife.js"
  ></script>

  <!-- Use the component -->
  <ofl-flow
    .context=${{
      options: {
        baseUrl: "https://flow-api.onlive.site",
        organizationId: "your-organization-id",
        flowId: "your-flow-id"
      }
    }}
  ></ofl-flow>
</body>
</html>

Using with Bundlers

// Import all components
import "@onlive.ai/flow";

// Or import specific components
import "@onlive.ai/flow/components/flow/flow.js";
import "@onlive.ai/flow/components/form/form.js";

// Import types
import type { Field, FieldValue } from "@onlive.ai/flow";

API Reference

Components

Onlive Flow provides several components to help you build interactive flows. You can use the main ofl-flow component to create a complete flow, or use the individual components to customize your flow.

The following image shows the structural distribution of the components:

Flow components Form components

OFL-Flow

Description

The main container component that manages a flow process with multiple steps, forms, actions, and navigation between stages. It coordinates with a FlowClient to handle data and navigation logic.

This component already includes the ofl-stages, ofl-form, and ofl-actions components, so you can use it as a complete solution for your flow.

Also includes the Onlive Flow Client, which is used to manage the flow process.

Importing

// ESM/Bundler Import
import "@onlive.ai/flow/components/flow/flow.js";

// Script Import (CDN)
<script
  type="module"
  src="https://cdn.onlive.site/@onlive.ai/flow@latest/components/flow/flow.js"
></script>;

Then use the component in your HTML:

<ofl-flow
  .context=${{
    options: {
      baseUrl: "https://flow-api.onlive.site",
      organizationId: "58b4b948-36d7-459b-adea-ca60412725a6"
      flowId: "683dbe2ea5ab95720a6b242f",
      customStyles: customStyleSheet,
      initialState: {},
      tracking: true,
      navigation: "default",
      inContainer: false
    }
  }}
></ofl-flow>

Properties

| Name | Type | Description | Reflects | Default Value | | --------- | ---------------- | --------------------------------------------- | -------- | ------------- | | context | PackageContext | Package context containing flow configuration | false | undefined |

Events

| Name | Description | Event Detail | | ----------------------- | ------------------------------------------------ | -------------------------------------------------------------------- | | ofl-change | Fired when form field values change | { detail: { values: Record<string, FieldValue>, valid: boolean } } | | ofl-action-click | Fired when an action button is clicked | { detail: { action: Action } } | | ofl-organization-call | Fired when organization call action is triggered | { detail: { params: any } } | | ofl-close-panel | Fired when close panel action is triggered | {} |

Context Configuration

The context property accepts a PackageContext object with the following structure:

{
  options?: {
    baseUrl?: string;           // Base URL for the Flow API
    organizationId?: string;    // Organization identifier for the flow
    flowId?: string;           // Flow identifier to load and process
    customStyles?: CSSStyleSheet; // Custom styles to be applied
    initialState?: any;        // Initial state for the flow
    tracking?: boolean;        // Enable tracking functionality
    navigation?: string;       // Navigation type ("default", "accordion")
    inContainer?: boolean;     // Whether flow is displayed in a container
  };
  devMode?: boolean;           // Enable development mode
}

OFL-Stages

Description

A component that displays the current stage in a multi-step process. It adapts responsively to show either a progress bar with current stage name (on smaller screens) or a list of all stages (on larger screens).

Importing

// ESM/Bundler Import
import "@onlive.ai/flow/components/stages/stages.js";

// Script Import (CDN)
<script
  type="module"
  src="https://cdn.onlive.site/@onlive.ai/flow@latest/components/stages/stages.js"
></script>;

Then use the component in your HTML:

<ofl-stages
  active="stage-2"
  .stages=${[
    { id: "stage-1", name: "Personal Info" },
    { id: "stage-2", name: "Address" },
    { id: "stage-3", name: "Review" }
  ]}
></ofl-stages>

Properties

| Name | Type | Description | Reflects | Default Value | | ------------ | ----------------------------------- | ---------------------------------- | -------- | ------------- | | context | PackageContext | Package context with custom styles | false | undefined | | active | String | ID of the currently active stage | false | undefined | | stages | Array<{id: string, name: string}> | Array of stage definitions | false | [] | | position | "header" \| "footer" | Display position of the stages | false | "header" | | navigation | "steps" \| "accordion" | Navigation style for the stages | false | "steps" |

OFL-Form

Description

A form component that renders a list of fields and handles their values and validation state. Supports various field types and layouts.

Importing

// ESM/Bundler Import
import "@onlive.ai/flow/components/form/form.js";

// Script Import (CDN)
<script
  type="module"
  src="https://cdn.onlive.site/@onlive.ai/flow@latest/components/form/form.js"
></script>;

Then use the component in your HTML:

<ofl-form
  .fields=${[
    { name: "fullName", label: "Full Name", type: "text", required: true },
    { name: "email", label: "Email", type: "email", required: true }
  ]}
></ofl-form>

Properties

| Name | Type | Description | Reflects | Default Value | | ---------- | -------------------------------------- | ------------------------------------ | -------- | ------------- | | context | PackageContext | Package context with custom styles | false | undefined | | fields | Array<Field> | Array of field definitions | false | [] | | readonly | Boolean | Whether the form is in readonly mode | false | false | | errors | Array<{name: string, error: string}> | Array of field validation errors | false | [] |

Events

| Name | Description | Event Detail | | ----------------- | -------------------------------------------------- | ------------------------------------------------------------------------------------ | | ofl-change | Fired when form values or validation changes | { detail: { values: Record<string, FieldValue \| FieldValue[]>, valid: boolean } } | | ofl-submit | Fired when the form is submitted | { detail: { action?: string } } | | ofl-interaction | Fired when user interacts with form for first time | { detail: {} } |

OFL-Field

Description

A versatile form field component that adapts to different input types. Supports inputs, textareas, checkboxes, radio buttons, selects, maps, calendars, and more. Handles validation, value management, and specialized field controllers.

Importing

// ESM/Bundler Import
import "@onlive.ai/flow/components/field/field.js";

// Script Import (CDN)
<script
  type="module"
  src="https://cdn.onlive.site/@onlive.ai/flow@latest/components/field/field.js"
></script>;

Then use the component in your HTML:

<ofl-field
  .field=${{
    name: "email",
    label: "Email Address",
    type: "email",
    component: "input",
    required: true
  }}
></ofl-field>

Check the Field Types documentation for a complete list of supported field types.

Properties

| Name | Type | Description | Reflects | Default Value | | -------------- | ---------------- | ------------------------------------- | -------- | ------------- | | context | PackageContext | Package context with custom styles | false | undefined | | field | Field | Field configuration object | false | undefined | | name | String | Field name identifier | true | undefined | | errorMessage | String | External error message to display | true | '' | | type | String | Field input type (text, number, etc.) | true | undefined | | component | String | Component to render (input, select) | true | undefined |

Events

| Name | Description | Event Detail | | ----------------- | ----------------------------------------- | -------------------------------------------------------------------------------- | | ofl-change | Fired when the field value changes | { detail: { value: FieldValue \| FieldValue[] \| undefined, valid: boolean } } | | ofl-interaction | Fired when user interacts with field | { detail: {} } | | ofl-submit | Fired when field triggers form submission | { detail: { action?: string } } |

OFL-Actions

Description

A component that renders a collection of action buttons based on the provided configuration. Supports various button types, variants, loading states, and handles action click events.

Importing

// ESM/Bundler Import
import "@onlive.ai/flow/components/actions/actions.js";

// Script Import (CDN)
<script
  type="module"
  src="https://cdn.onlive.site/@onlive.ai/flow@latest/components/actions/actions.js"
></script>;

Then use the component in your HTML:

<ofl-actions
  .actions=${[
    { id: "back", label: "Back", type: "back", variant: "secondary" },
    { id: "next", label: "Continue", type: "submit", variant: "primary" }
  ]}
></ofl-actions>

Properties

| Name | Type | Description | Reflects | Default Value | | --------- | --------------- | ------------------------------ | -------- | ------------- | | actions | Array<Action> | Array of action configurations | false | [] |

Events

| Name | Description | Event Detail | | ------------------ | -------------------------------------- | -------------------------------- | | ofl-action-click | Fired when an action button is clicked | { detail: { action: Action } } |

Theming

The individual components: ofl-flow, ofl-stages, ofl-form, ofl-field, and ofl-actions can accept a customStyles property that allows you to pass a custom CSS stylesheet to override the default styles of the components.

The main ofl-flow component take the styles configuration from Onlive Flow installation configuration.

Base theming

The Onlive Flow package use the Onlive UI components library for styling and theming. For general theming purpose such as change color palette or font family use Onlive UI theming documentation and for individual UI component theming use specific component documentation.

Example

This example shows how to create new color palette and customize the button styles. Check to the Onlive UI documentation for more details.

Custom Buttons

:root {
  /* Theme Palette */
  --ol-color-primary-50: rgb(255 248 249);
  --ol-color-primary-100: rgb(254 231 236);
  --ol-color-primary-200: rgb(253 212 220);
  --ol-color-primary-300: rgb(252 190 203);
  --ol-color-primary-400: rgb(251 160 179);
  --ol-color-primary-500: rgb(249 117 145);
  --ol-color-primary-600: rgb(247 52 93);
  --ol-color-primary-700: rgb(217 4 49);
  --ol-color-primary-800: rgb(180 4 41);
  --ol-color-primary-900: rgb(131 3 30);
  --ol-color-primary-950: rgb(85 2 19);
}

/* Button styles */
ol-button::part(base) {
  border-radius: var(--ol-border-radius-pill);
  border: 2px solid var(--ol-color-primary-600);
}

/* Button styles for neutral variant */
ol-button[variant="default"]::part(base) {
  color: var(--ol-color-primary-600);
  font-weight: var(--ol-font-weight-bold);
}

Advanced theming

It is possible to use specific selectors in custom styles to modify each of the components in a granular way.

Example

This example shows how to change the number of actions per row in the ofl-actions component.

Actions per row

/* Change the number of actions per row to 3 */
.ofl__actions {
  grid-template-columns: repeat(3, 1fr);
}

.ofl__actions .ofl__actions__button:last-child {
  grid-column: span 1;
}

Development

Building the Package

To build the package locally:

# Install dependencies
pnpm install

# Build the package
pnpm run build:package

# Clean build artifacts
pnpm run clean

Package Scripts

build:package - Builds the package using tsup in multiple formats
clean - Removes all generated build files

TypeScript Support

This package is written in TypeScript and includes full type definitions. All components and exported types are properly typed for the best development experience.

Browser Support

The package supports modern browsers that have Web Components support:

Chrome 54+
Firefox 63+
Safari 10.1+
Edge 79+

For older browsers, you may need to include polyfills for Web Components.

Related Packages

@onlive.ai/flow-client - Flow management and API client
@onlive.ai/ui - UI component library used for styling
@onlive.ai/calendar - Calendar components for date fields

Documentation

License

This package is proprietary software owned by Onlive.

Support

For support and questions, please refer to the Onlive documentation or contact the development team.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Onlive Flow

Overview

Installation

Using pnpm (recommended)

CDN

Package Structure

Main Components

Exports

Directory Structure

Build Formats

Dependencies

Quick Start

Using with Bundlers

API Reference

Components

OFL-Flow

Description

Importing

Properties

Events

Context Configuration

OFL-Stages

Description

Importing

Properties

OFL-Form

Description

Importing

Properties

Events

OFL-Field

Description

Importing

Properties

Events

OFL-Actions

Description

Importing

Properties

Events

Theming

Base theming

Example

Advanced theming

Example

Development

Building the Package

Package Scripts

TypeScript Support

Browser Support

Related Packages

Documentation

License

Support