@o.z/playground ⚡

A live HTML playground web component that dynamically generates form controls from template variables and displays real-time rendered output with a built-in code editor.

✨ Features

• Dynamic Template Variables – Use $variable syntax in your HTML templates
• Auto-generated Controls – Form inputs are created automatically based on variable metadata
• Live Preview – See rendered HTML update instantly as you change values
• Built-in Code Editor – Powered by CodeMirror with HTML syntax highlighting
• Multiple Input Types – Supports string, number, boolean, and select/dropdown inputs
• Customizable – Define options, labels, default values, and more
• Framework Agnostic – Works as a native web component

📦 Installation

yarn add @o.z/playground
# or
npm install @o.z/playground

🚀 Usage

Basic Setup

Import the component and use it in your HTML/JavaScript:

import "@o.z/playground"

HTML Structure

<zui-playground>
  <!-- Your template with $variables -->
  <template>
    <div class="card">
      <h2>$title</h2>
      <p>$description</p>
      <span class="status $status">$statusText</span>
    </div>
  </template>

  <!-- Variable definitions with metadata -->
  <div name="$title" data-meta='{"type":"string","value":"Hello World","label":"Title"}'></div>
  
  <div name="$description" data-meta='{"type":"string","value":"This is a description","label":"Description"}'></div>
  
  <div name="$status" data-meta='{"type":"choose","value":"success","options":[{"name":"Success","value":"success"},{"name":"Warning","value":"warning"},{"name":"Error","value":"error"}],"label":"Status"}'></div>
  
  <div name="$statusText" data-meta='{"type":"string","value":"All good!","label":"Status Text"}'></div>
</zui-playground>

📖 Configuration

Template Variables

Use $variableName syntax anywhere inside the <template> tag. These placeholders will be replaced with values from the generated form controls.

Variable Metadata

Each variable is defined by a <div> with:

• name attribute matching the $variableName
• data-meta attribute containing JSON configuration

Supported Input Types

String

{
  "type": "string",
  "value": "default text",
  "label": "Field Label",
  "placeholder": "Enter text...",
  "disabled": false
}

Number

{
  "type": "number",
  "value": 42,
  "label": "Number Field",
  "min": 0,
  "max": 100,
  "disabled": false
}

Choose (Dropdown)

{
  "type": "choose",
  "value": "option1",
  "label": "Select Option",
  "options": [
    { "name": "Option 1", "value": "option1" },
    { "name": "Option 2", "value": "option2" }
  ],
  "disabled": false
}

Boolean

{
  "type": "boolean",
  "value": true,
  "label": "Checkbox Label",
  "disabled": false
}

🎨 Example: Input Field Playground

The component ships with a complete example for styling input fields:

<zui-playground>
  <template>
    <div class="input-group">
      <input type="$type" class="$variant $state" placeholder="$label" />
      <span class="helper-text $state">$helperText</span>
    </div>
  </template>

  <div name="$type" data-meta='{"type":"choose","value":"text","options":[{"name":"Text","value":"text"},{"name":"Email","value":"email"},{"name":"Password","value":"password"},{"name":"Number","value":"number"},{"name":"Tel","value":"tel"},{"name":"URL","value":"url"},{"name":"Search","value":"search"}],"label":"Input Type"}'></div>

  <div name="$variant" data-meta='{"type":"choose","value":"filled","options":[{"name":"Filled","value":"filled"},{"name":"Underlined","value":"underlined"},{"name":"Secondary","value":"secondary"},{"name":"Default","value":"default"}],"label":"Variant"}'></div>

  <div name="$state" data-meta='{"type":"choose","value":"","options":[{"name":"Default","value":""},{"name":"Error","value":"error"},{"name":"Success","value":"success"}],"label":"State"}'></div>

  <div name="$label" data-meta='{"type":"string","value":"Enter text","label":"Placeholder Text"}'></div>

  <div name="$helperText" data-meta='{"type":"string","value":"Helper message","label":"Helper Text"}'></div>
</zui-playground>

🛠️ Development

# Install dependencies
yarn install

# Start dev server
yarn dev

# Build for production
yarn build

# Run tests
yarn test

# Generate documentation
yarn docs

📚 API Documentation

For detailed API reference, see the API Documentation.

🤝 Contributing

Contributions are welcome! Please open an issue or submit a pull request.

1. Fork the repo
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m "Add amazing feature")
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License and AI Training

This project is licensed under the GNU General Public License v3.0 (GPLv3).

AI Training Notice: The authors consider the use of this code, including its source code, documentation, and any other project artifacts, for the training of artificial intelligence (AI) systems (including but not limited to machine learning, large language models, and other AI technologies) to be creating a derivative work. As such, any entity using this code for such purposes must comply with the terms of the GPLv3. This includes, but is not limited to, making the entire source code of the AI system that uses this code available under the same GPLv3 license.

If you wish to use this code for AI training without being subject to the GPLv3, please contact the authors to negotiate a separate license.

Built with ❤️ using ZUI and CodeMirror