Skip to content

README.en.md

Latest commit

 

History

History
178 lines (131 loc) · 6.26 KB

README.en.md

File metadata and controls

178 lines (131 loc) · 6.26 KB
Raw

Chameleon icon

Chameleon

Visual page editing for React applications.

简体中文 | English

npm version npm downloads license

  • Schema-driven page editor
  • Responsive layout and style editing
  • Extensible component materials
  • Plugin-based workbench
  • Design-time and runtime rendering
  • Fully typed React APIs

Chameleon is an open-source engine for building visual web page editors, component configuration panels, responsive layouts, and schema-driven page renderers with React. It provides the editor shell and plugin system while allowing applications to supply their own component materials, page schemas, assets, and rendering strategy.

Get Started

Resource Link
Documentation Chameleon Docs
Main demo Open the editor
Layout debug Open layout debug
Example project chameleon-demo
Repository hlerenow/chameleon
npm package @chamn/engine

Packages

Package Version Description
@chamn/engine 0.11.1 Editor workbench, plugins, panels, and design-time interactions
@chamn/model 0.11.1 Page schema, node model, material types, and model utilities
@chamn/render 0.11.1 Runtime and design-time React rendering
@chamn/layout 0.11.1 Canvas layout, drag-and-drop, selection, and resize interactions

See the package changelogs and the npm organization for published versions.

Screenshots

Chameleon layout editor

Chameleon editor

Chameleon component and property panels

Chameleon visual editor

Chameleon responsive editing

Installation

npm install @chamn/engine react react-dom

Or with pnpm:

pnpm add @chamn/engine react react-dom

The package currently targets Node.js 22+ and pnpm 9+ for repository development. Applications should use a React version supported by their surrounding toolchain.

Usage

The engine requires a page schema and a plugin list. Applications normally provide their own materials and component implementations.

import React from 'react';
import { createRoot } from 'react-dom/client';
import '@chamn/engine/dist/style.css';
import { Engine, plugins } from '@chamn/engine';
import { EmptyPage } from '@chamn/model';

const App = () => (
  <Engine
    plugins={plugins.DEFAULT_PLUGIN_LIST}
    schema={EmptyPage}
    material={[]}
    onReady={({ engine }) => {
      console.log('Chameleon is ready', engine);
    }}
  />
);

createRoot(document.getElementById('root')!).render(<App />);

For a complete setup with custom materials, iframe rendering, third-party assets, and page persistence, see the example project.

Responsive Breakpoints

The editor includes default responsive breakpoints:

Key Label Width
MODERN_PC Modern PC 1920px
PC PC 1200px
IPAD Tablet 768px
MOBILE Mobile 350px

Applications can provide their own breakpoint list:

<Engine
  plugins={plugins.DEFAULT_PLUGIN_LIST}
  schema={schema}
  responsiveSizes={[
    { key: 'LARGE', label: 'Large', width: 1440 },
    { key: 'PC', label: 'PC', width: 1200 },
    { key: 'TABLET', label: 'Tablet', width: 768 },
    { key: 'MOBILE', label: 'Mobile', width: 375 },
  ]}
/>

Pass breakpoints from wide to narrow so the generated max-width media rules have the expected cascade order.

Internationalization

The built-in UI supports zh_CN and en_US. Set the initial locale or change it through the engine instance:

<Engine locale="en_US" {...engineProps} />;

engine.getI18n().changeLanguage('zh_CN');

Development

pnpm install
pnpm run lint
pnpm run build
pnpm run run-tests

Useful package-level commands:

pnpm --filter @chamn/engine build
pnpm --filter @chamn/engine lint
pnpm --filter @chamn/engine storybook

Contributing

Issues and pull requests are welcome. Search existing issues first, keep changes focused, update tests for behavior changes, and run lint plus the relevant package build before submitting a pull request.

License

Chameleon is released under the Apache License 2.0.