@ticatec/topside-flexi

Flexible and dynamic UI framework for Svelte 5 — including schema-driven forms, criteria panels, dynamic data tables, and multi-tenant layout patches.

中文文档 (README_CN.md)

Features

• 🚀 Dynamic Form Engine: Schema-driven forms with Svelte 5 Runes, supporting sections, nested groups, and editable sub-tables (FlexiTable).
• ⚡ Declarative Reactions: Synchronous cross-field and cross-row bindings using concise expressions ($exp{status == 'A'}) or custom methods.
• 🔍 Criteria Panel: Advanced search filtering component (FlexiCriteriaSet) built on the same reactive core.
• 📊 Dynamic Data Tables: Configurable tables (FlexiDataTable, PureFlexiDataTable) with remote dictionary formatting and customizable actions.
• 🏗️ Page Module Host: Full-lifecycle CRUD management (FlexiPageModule, FlexiModulePage) connecting home pages, editor dialogs/pages, and action bars.
• 🧩 Multi-Tenant Layout Patches: Incremental layout customization via applyLayoutPatches (operations: remove, hide, set, replace, insert, move).
• 🌐 Centralized Context: Unified dictionary loading and i18n support through FlexiContext and ModuleContext.
• 🎭 Svelte 5 Runes: Built entirely with $state, $derived, and $effect for zero-boilerplate fine-grained reactivity.

Installation

pnpm add @ticatec/topside-flexi
# or
npm install @ticatec/topside-flexi

Peer Dependencies: Ensure @ticatec/topside-elements, @ticatec/topside-editors, @ticatec/topside-datatable, @ticatec/topside-pro, @ticatec/topside-micro, @ticatec/app-data-manager, @ticatec/app-data-service, and @ticatec/i18n are installed in your application.

Quick Start

1. Initialize FlexiContext

Set up global dictionary loading and optional language:

import FlexiContext from '@ticatec/topside-flexi';

const dictLoader = async (names: string[]) => {
  const response = await fetch('/api/dictionaries', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ names })
  });
  return await response.json();
};

FlexiContext.initialize(dictLoader, 'en-US');

2. Using FlexiForm

Define schema and bind form data:

<script lang="ts">
  import { FlexiForm, FlexiFormPanel, type FormSchema } from '@ticatec/topside-flexi';
  import { ModuleContext } from '@ticatec/topside-flexi';
  import '@ticatec/topside-flexi/topside-flexi.css';

  const schema: FormSchema = {
    title: 'Customer Details',
    fields: [
      {
        keyField: 'name',
        type: 'text-editor',
        label: 'Name',
        required: true
      },
      {
        keyField: 'type',
        type: 'options-selector',
        label: 'Type',
        dictName: 'customerTypes'
      },
      {
        keyField: 'taxNumber',
        type: 'text-editor',
        label: 'Tax Number',
        reactions: {
          visible: "$exp{type == 'CORP'}",
          required: "$exp{type == 'CORP'}"
        }
      }
    ]
  };

  const moduleContext = new ModuleContext();
  const form = new FlexiForm(moduleContext, { type: 'CORP' }, schema);

  const handleSubmit = async () => {
    if (await form.validateAsync()) {
      const payload = form.getData();
      console.log('Valid submission:', payload);
    }
  };
</script>

<FlexiFormPanel {form} />
<button onclick={handleSubmit}>Submit</button>

3. Using FlexiModulePage (Full CRUD Page)

<script lang="ts">
  import { FlexiPageModule, FlexiModulePage, type UILayout } from '@ticatec/topside-flexi';
  import { onMount } from 'svelte';

  class CustomerModule extends FlexiPageModule {
    // Custom method hooks, formatters, and action handlers
    override createNewData() {
      return { status: 'A', country: 'US' };
    }
  }

  const module = new CustomerModule();

  onMount(async () => {
    const layout: UILayout = await fetch('/api/modules/customer/layout').then(r => r.json());
    await module.initialize(layout);
  });
</script>

{#if module.initialized}
  <FlexiModulePage {module} />
{/if}

Core Components & Architecture

• FlexiForm & FlexiFormPanel: Form model and layout panel (Guide)
• FlexiCriteriaSet & CriteriaFieldsPanel: Filter criteria panel (Guide)
• FlexiDataTable & PureFlexiDataTable: Dynamic data tables (Guide)
• FlexiModuleBase & FlexiPageModule: Base classes for dynamic code modules (Guide)
• Layout Patches: Incremental multi-tenant layout customization (Guide)
• ModuleLoader: Dynamic script loader with sandboxed runtime (Guide)

Documentation

• Documentation Index
• Architecture & Contracts (中文)
• Form Guide (中文)
• Data Table Guide (中文)
• Criteria Set Guide (中文)
• Module Base Guide (中文)
• Layout Patch Guide (中文)

License

MIT License - see LICENSE for details.

Support

For issues and discussions, please visit the GitHub Issues.