Help Text Guide

Overview

The playground now includes comprehensive help text for components with complex configurations. This guide explains what was added and how to use it.

Components with Help Text (13 total)

UI Components

#### 1. pan-tabs Shows how to configure tabs using JSON array:

[
  { "label": "Tab 1", "id": "tab1" },
  { "label": "Tab 2", "id": "tab2", "disabled": true },
  { "label": "Tab 3", "id": "tab3", "icon": "🎨" }
]

#### 2. pan-chart Examples for chart data structure and options:

{
  "labels": ["Jan", "Feb", "Mar"],
  "datasets": [{
    "label": "Sales",
    "data": [12, 19, 3]
  }]
}

#### 3. pan-data-table Shows expected data format from PAN topics:

{
  "data": {
    "items": [
      { "id": 1, "name": "Alice", "email": "alice@example.com" }
    ]
  }
}

#### 4. drag-drop-list Array of items with id and text:

[
  {"id": 1, "text": "First item"},
  {"id": 2, "text": "Second item"}
]

Form Components

#### 5. pan-json-form JSON schema for dynamic form generation:

{
  "fields": [
    {
      "name": "email",
      "type": "email",
      "label": "Email Address",
      "required": true,
      "placeholder": "you@example.com"
    }
  ]
}

#### 6. pan-form Shows PAN topic integration for CRUD operations:

• Listens: {resource}.item.select
• Requests: {resource}.item.get
• Submits: {resource}.item.save
• Deletes: {resource}.item.delete

• accept="image/*" - File type filter
• max-size="5242880" - 5MB in bytes
• preview - Show image previews
• drag-drop - Enable drag-drop zone

State Management Components

#### 8. pan-computed-state Derived state with automatic dependency tracking:

<pan-computed-state sources="todos.list" output="todos.stats">
  <script>
    (todos) => ({
      total: todos.length,
      completed: todos.filter(t => t.completed).length
    })
  </script>
</pan-computed-state>

#### 9. pan-state-sync Cross-tab synchronization with BroadcastChannel:

<pan-state-sync
  channel="myapp"
  topics="user.*,cart.*">
</pan-state-sync>

#### 10. pan-offline-sync Offline-first with automatic queue and sync:

{
  "todos.create": "/api/todos",
  "todos.update": "/api/todos/:id",
  "todos.delete": "/api/todos/:id"
}

#### 11. pan-persistence-strategy Declarative routing to storage backends:

<pan-persistence-strategy auto-hydrate>
  <strategy topics="user.prefs" storage="localStorage"></strategy>
  <strategy topics="cart.*" storage="indexedDB" ttl="3600000"></strategy>
</pan-persistence-strategy>

#### 12. pan-schema-validator Runtime JSON Schema validation:

{
  "type": "object",
  "required": ["email", "name"],
  "properties": {
    "email": {"type": "string", "format": "email"},
    "name": {"type": "string", "minLength": 2}
  }
}

#### 13. pan-undo-redo Time-travel debugging for state:

<pan-undo-redo
  topics="editor.*"
  max-history="50"
  channel="editor-history">
</pan-undo-redo>

Attributes with Help Text (9 total)

Attributes now show inline examples when you click "Show example":

| Component | Attribute | Type | Help Text | |-----------|-----------|------|-----------| | pan-tabs | tabs | json | Tab configuration array | | pan-json-form | schema | json | Form field definitions | | pan-chart | data | json | Chart dataset structure | | pan-chart | options | json | Chart configuration options | | pan-data-table | columns | string | Comma-separated column names | | pan-form | fields | string | Comma-separated field names | | pan-computed-state | sources | string | Source topic patterns | | pan-offline-sync | endpoints | json | Topic-to-URL mappings | | drag-drop-list | items | json | Array of draggable items |

Updated Attribute Types

For better editing experience, these attributes now use json or textarea input types:

• JSON types: pan-tabs.tabs, pan-json-form.schema, pan-chart.data/options, pan-offline-sync.endpoints, drag-drop-list.items, pan-schema-validator.schema
• These render as textareas with monospace font for easier JSON editing

How to Use in Playground

cd playground
   python3 -m http.server 8080
   open http://localhost:8080/

Adding New Help Text

To add help text for more components:

const COMPONENT_HELP = {
     'your-component': {
       helpText: `<p>Description here</p><pre>Example code</pre>`
     }
   };

const ATTRIBUTE_HELP = {
     'your-component': {
       'attribute-name': `Example value or JSON`
     }
   };

const ATTRIBUTE_TYPES = {
     'your-component': {
       'attribute-name': 'json' // or 'textarea', 'number', etc.
     }
   };

node playground/scripts/add-help-text.mjs

Tips for Writing Help Text

Component Help Text (HTML)

• Start with a brief description
• Show complete, working examples in

   tags

• Explain the data shape or format
• Mention related PAN topics or components
• Keep it concise but complete

Attribute Help Text (Plain Text)

• Show actual example values
• For JSON: format it nicely with newlines
• For strings: show common patterns
• For arrays: show 1-2 example items
• Keep it one-line or minimal

Good Examples

helpText: `<p>Description of what it does:</p>
<pre>&lt;component
  attr1="value"
  attr2='{"json": "here"}'&gt;
&lt;/component&gt;</pre>
<p>Additional usage notes.</p>`

helpText: `[{"id":1,"name":"Example"},{"id":2,"name":"Another"}]`

Benefits

Impact

Before:

• Generic descriptions only
• No examples
• Unclear data shapes
• Single-line text inputs for complex JSON

• 13 components with detailed help
• 9 attributes with examples
• Clear data format specifications
• Proper textarea inputs for JSON/objects
• Expandable help sections