Ion Components

Ion Components is a comprehensive library of Vue 3 Web Components designed for building dynamic, spec-driven user interfaces. It provides embeddable custom elements for workflow editing, form generation, data mapping, and more.

Technology Stack

Technology	Version	Purpose
Vue.js	3.5+	Component framework with Custom Elements support
TailwindCSS	4.x	Utility-first CSS with OKLCH color system
VueFlow	1.41+	Node-based graph editor (Flow/Mapper)
VeeValidate	4.x	Form validation
Yup / Zod	Latest	Schema validation
TipTap	3.x	Rich text editing
TypeScript	5.4	Type safety
Vite	5.x	Build tooling

Core Web Components

Form Component

Dynamic forms driven by a spec schema. Supports validation, nested fields, and external hooks.

<form-component>

Flow Component

Visual workflow editor with drag-and-drop nodes, connections, and execution visualization.

<flow-component>

FlowRaw Component

Read-only flow viewer for displaying workflow diagrams without editing capabilities.

<flow-raw-component>

Mapper Component

Visual data transformation tool for mapping input data to output structures.

<mapper-component>

Architecture Overview

Custom Element Pattern

Each component is registered as a Web Component using Vue’s defineCustomElement:

import { defineCustomElement } from 'vue';
import FormCe from './view/Form.ce.vue';
import { useCore } from './store/core';

// Expose hooks to browser context
window.$useFormCore = useCore();

// Register custom element
customElements.define('form-component', defineCustomElement(FormCe));

Browser Context Hooks

Components expose APIs through the window object for external control:

Hook	Purpose
`window.$useFlowCore`	Control flow editor state, push execution results
`window.$useFormCore`	Subscribe to form changes, dynamically modify specs

Spec-Driven Architecture

Forms and dynamic UI elements are driven by a spec object - a JSON schema that defines:

Field types (text, select, collection, array, etc.)
Validation rules
Nested structures
Dynamic behavior

Build Modes

Ion Components supports multiple build targets for different use cases:

# Build individual components
pnpm build-form      # Form component only
pnpm build-flow      # Flow component only
pnpm build-mapper    # Mapper component only
pnpm build-gateway   # Gateway components

# Build everything
pnpm build-all       # All components bundled

Quick Start

Using in HTML

<!DOCTYPE html>
<html>
<head>
  <script src="./dist/form.js"></script>
</head>
<body>
  <form-component
    id="my-form"
    theme="dark"
    :spec='{"type":"collection","spec":[{"type":"text","name":"email","label":"Email"}]}'
  ></form-component>

  <script>
    // Access form hooks
    const { onChange } = window.$useFormCore;

    onChange('my-form', (event) => {
      console.log('Form changed:', event.detail);
    });
  </script>
</body>
</html>

Using in Vue

<script setup>
import { ref, onMounted } from 'vue';

const formSpec = {
  type: 'collection',
  spec: [
    { type: 'text', name: 'name', label: 'Name', required: true },
    { type: 'email', name: 'email', label: 'Email', required: true },
  ],
};

const formData = ref({});

function handleSubmit(data) {
  console.log('Submitted:', data);
}
</script>

<template>
  <form-component
    id="user-form"
    :spec="formSpec"
    :values="formData"
    @submit="handleSubmit"
  />
</template>

Module Structure

ion-components/
├── src/
│   ├── form/           # Form web component
│   ├── flow/           # Flow editor web component
│   ├── flowraw/        # Flow viewer (read-only)
│   ├── mapper/         # Data mapper web component
│   ├── gateway/        # Gateway components (advanced)
│   └── ui/             # Internal UI components
├── packages/
│   ├── ui/             # Shared UI component library
│   ├── services/       # API and utility services
│   └── models/         # TypeScript type definitions
└── docs/               # This documentation

Next Steps

Form Component - Learn about spec-driven forms
Flow Component - Build visual workflows
Spec Paradigm - Understand the schema system
UI Library - Reusable Vue components