✨ Add UI update command with YAML support

go-go-golems · Feb 26, 2025 · d48e528 · d48e528
1 parent 9256bac
commit d48e528
Show file tree

Hide file tree

Showing 6 changed files with 801 additions and 22 deletions.
diff --git a/changelog.md b/changelog.md
@@ -1,3 +1,23 @@
+# Enhanced Documentation Metadata
+
+Added structured metadata to technical documentation for better maintainability:
+- Added YAML preamble to UI action handling documentation
+- Included code references to track dependencies between docs and code
+- Added RAG-optimized metadata for improved document retrieval
+- Created maintenance triggers to identify when docs need updates
+- Structured questions the document answers for better discoverability
+- Improved documentation organization and searchability
+
+# UI Action Handling Documentation
+
+Added comprehensive documentation for the UI action handling system:
+- Created detailed guide in ttmp/2025-02-22/04-sse-dynamic-form.md
+- Documented client-side event handling and server-side processing
+- Explained form data collection from multiple sources
+- Provided component-specific event handling reference
+- Included complete flow walkthrough for form submissions
+- Added debugging and console logging documentation
+
 # Enhanced UI Action Handling
 
 Improved the UI action system to focus on data-relevant events and provide better form submission data:
@@ -1339,29 +1359,19 @@ Fixed an issue where form input values weren't being properly collected during f
 - Added additional logging for form submission data
 - Fixed email input value collection in subscription forms
 
-# Enhanced UI Action Handling
+# UI Update Command with YAML Support
 
-Improved the UI action system to focus on data-relevant events and provide better form submission data:
-- Enhanced form submission to include complete form data in the action payload
-- Implemented smart logging that prioritizes data-relevant events (clicked, changed, submitted)
-- Added detailed form data logging for form submissions
-- Used INFO level for important events and DEBUG level for less important ones
-- Improved checkbox handling in form data collection
-- Maintained backward compatibility with existing event system
-
-# UI Component Action Endpoint
+Added a new shell command for updating UI components dynamically using YAML input. This command allows users to:
 
-Added a generic event handler system for UI components that sends events to a REST endpoint:
-- Created new `/api/ui-action` endpoint to receive component actions
-- Added JavaScript function to send component actions to the server
-- Updated all UI components to use the new action system
-- Actions include component ID, action type, and optional data
-- Server logs all actions for monitoring and debugging
-- Maintained backward compatibility with existing console logging
+- Define UI components in YAML format
+- Convert YAML to JSON before sending to the UI server
+- Update UI components without modifying YAML files directly
 
-# Added GitHub Pull Request Listing Command
+The command supports multiple conversion methods (Python, yq, or basic sed) and provides detailed documentation on the UI DSL.
 
-Added a new command to list pull requests from GitHub repositories:
-- Created list-github-pull-requests command with support for filtering by state, assignee, author, labels, and base branch
-- Added draft PR filtering support
-- Included comprehensive JSON output options for PR-specific fields
+## Changes
+- Created `examples/ui/update-ui.yaml` shell command
+- Added YAML to JSON conversion logic
+- Created example YAML form definition
+- Added comprehensive documentation in README.md
+- Created helper script for easy usage
diff --git a/examples/ui/README.md b/examples/ui/README.md
@@ -0,0 +1,283 @@
+# UI Update Command
+
+This directory contains a shell command for dynamically updating the UI components in the Go-Go-MCP UI server.
+
+## Update UI Command
+
+The `update-ui.yaml` command allows you to update UI components dynamically by sending a JSON payload to the UI server's update endpoint. The components are specified as a YAML string and will be converted to JSON before being sent to the server.
+
+### Usage
+
+```bash
+go-go-mcp run-command examples/ui/update-ui.yaml \
+  --components 'components:
+  - title:
+      content: "Hello World"
+      id: main-title' \
+  --server_url "http://localhost:8080" \
+  --verbose
+```
+
+### Parameters
+
+- `components` (required): YAML string containing UI components definition
+- `server_url` (optional): URL of the UI server (default: "http://localhost:8080")
+- `verbose` (optional): Show verbose output (default: false)
+
+### Using a YAML File
+
+You can also use a YAML file as input:
+
+```bash
+# Read YAML from a file
+YAML_CONTENT=$(cat example-form.yaml)
+
+# Pass the YAML content to the command
+go-go-mcp run-command examples/ui/update-ui.yaml \
+  --components "$YAML_CONTENT" \
+  --verbose
+```
+
+Or use the provided script:
+
+```bash
+./update-dino-form.sh
+```
+
+## UI DSL Reference
+
+The UI DSL (Domain Specific Language) is a YAML-based language for defining user interfaces declaratively. It allows you to create rich, interactive web interfaces without writing HTML directly.
+
+### Basic Structure
+
+Every UI definition consists of a list of components under the `components` key:
+
+```yaml
+components:
+  - componentType:
+      property1: value1
+      property2: value2
+```
+
+### Common Properties
+
+All components support these common properties:
+
+- `id`: Unique identifier for the component (required)
+- `disabled`: Boolean to disable the component (optional)
+- `data`: Map of data attributes (optional)
+
+### Component Types
+
+#### Button
+```yaml
+- button:
+    text: "Click me"
+    type: primary  # primary, secondary, danger, success
+    id: submit-btn
+    disabled: false
+```
+
+#### Title (H1 Heading)
+```yaml
+- title:
+    content: "Welcome to My App"
+    id: main-title
+```
+
+#### Text (Paragraph)
+```yaml
+- text:
+    content: "This is a paragraph of text."
+    id: description-text
+```
+
+#### Input Field
+```yaml
+- input:
+    type: text  # text, email, password, number, tel
+    placeholder: "Enter your name"
+    value: ""
+    required: true
+    id: name-input
+```
+
+#### Textarea
+```yaml
+- textarea:
+    placeholder: "Enter description"
+    id: description-textarea
+    rows: 4
+    cols: 50
+    value: |
+      Default multiline
+      text content
+```
+
+#### Checkbox
+```yaml
+- checkbox:
+    label: "Accept terms"
+    checked: false
+    required: true
+    name: terms
+    id: terms-checkbox
+```
+
+#### List
+
+Lists can contain various types of nested components, supporting both ordered (ol) and unordered (ul) lists.
+
+```yaml
+- list:
+    type: ul  # ul or ol
+    title: "Shopping List"
+    items:
+      - text:
+          content: "Groceries to buy:"
+      - checkbox:
+          label: "Milk"
+          id: milk-checkbox
+      - checkbox:
+          label: "Bread"
+          id: bread-checkbox
+      - button:
+          text: "Add Item"
+          id: add-item-btn
+          type: secondary
+```
+
+#### Form
+```yaml
+- form:
+    id: signup-form
+    components:
+      - title:
+          content: "Sign Up"
+      - input:
+          type: email
+          placeholder: "Email address"
+          required: true
+      - button:
+          id: submit
+          text: "Submit"
+          type: primary
+```
+
+### Complete Example
+
+Here's a complete example of a todo list interface:
+
+```yaml
+components:
+  - title:
+      content: What would you like to tackle next?
+  
+  - text:
+      content: I see you have several items that need attention.
+  
+  - list:
+      type: ul
+      items:
+        - Review Dependencies:
+            button:
+              id: review-deps-btn
+              text: Review Update (#316)
+              type: secondary
+        - Calendar Integration:
+            button:
+              id: review-calendar-btn
+              text: Review Calendar PR (#315)
+              type: primary
+  
+  - form:
+      id: task-input-form
+      components:
+        - title:
+            content: Add New Task
+        - input:
+            id: new-task-input
+            type: text
+            placeholder: What needs to be done?
+            required: true
+        - checkbox:
+            id: high-priority-check
+            label: High Priority
+        - button:
+            id: add-task-btn
+            text: Add Task
+            type: success
+```
+
+### Event Handling
+
+The UI components automatically handle various events:
+
+1. **clicked**: When a user clicks on a button or interactive element
+2. **changed**: When an input, textarea, or checkbox value changes
+3. **submitted**: When a form is submitted
+4. **focused**: When an input receives focus (debug level only)
+5. **blurred**: When an input loses focus (debug level only)
+
+### Form Data Collection
+
+When a form is submitted, the system collects data from:
+
+1. Standard form fields via FormData API
+2. Checkbox states (including unchecked boxes)
+3. All input values by ID (as a fallback)
+4. The ID of the button that triggered the submission
+
+### Best Practices
+
+1. Always provide meaningful IDs for components that need to be referenced
+2. Use semantic naming for form fields
+3. Group related components inside forms
+4. Use appropriate button types for different actions:
+   - `primary`: Main actions
+   - `secondary`: Alternative actions
+   - `danger`: Destructive actions
+   - `success`: Confirmation actions
+5. Provide clear labels and placeholders for form inputs
+
+## Example YAML for update-ui Command
+
+Here's an example of a contact form in YAML format:
+
+```yaml
+components:
+  - title:
+      content: Contact Form
+      id: contact-title
+  
+  - form:
+      id: contact-form
+      components:
+        - input:
+            type: text
+            placeholder: Your Name
+            required: true
+            id: name-input
+        
+        - input:
+            type: email
+            placeholder: Your Email
+            required: true
+            id: email-input
+        
+        - textarea:
+            placeholder: Your Message
+            rows: 4
+            id: message-textarea
+        
+        - checkbox:
+            label: Subscribe to newsletter
+            id: newsletter-checkbox
+        
+        - button:
+            text: Send Message
+            type: primary
+            id: send-btn
+```
+
+This will create a contact form with name, email, message fields, a newsletter checkbox, and a submit button.