widget-creator

Widget Creator Skill

This skill provides a comprehensive step-by-step guide for AI coding agents to create new widgets in the Hex1b TUI library. Widgets are the building blocks of Hex1b applications, following a declarative pattern inspired by React.

Overview

Creating a widget in Hex1b involves several coordinated files:

File	Purpose
src/Hex1b/Widgets/{Name}Widget.cs	Immutable widget record (describes what to render)
src/Hex1b/Nodes/{Name}Node.cs	Mutable node class (manages state, renders)
src/Hex1b/{Name}Extensions.cs	Fluent API extension methods
src/Hex1b/Theming/{Name}Theme.cs	Theme elements (colors, characters)
tests/Hex1b.Tests/{Name}NodeTests.cs	Unit tests

Step-by-Step Process

Step 1: Define the Widget Record

Widgets are immutable record types that describe the desired UI. They capture configuration and event handlers but contain no rendering logic.

Location: src/Hex1b/Widgets/{Name}Widget.cs

Key principles:

• Use primary constructor parameters for required data
• Use internal properties with init for optional configuration
• Event handlers use Func<TEventArgs, Task>? pattern
• Provide sync and async overloads for event handlers using this with { } pattern
• Implement Reconcile() to create/update the corresponding node
• Implement GetExpectedNodeType() to return the node type

Template:

using Hex1b.Events;
using Hex1b.Nodes;

namespace Hex1b.Widgets;

/// <summary>
/// Brief description of what the widget does.
/// </summary>
/// <param name="PrimaryProperty">Description of the main property.</param>
public sealed record MyWidget(string PrimaryProperty) : Hex1bWidget
{
    /// <summary>
    /// ActionId for the activate action. Use "WidgetName.ActionName" naming
    /// convention (PascalCase, omit "Widget" suffix from the widget name).
    /// Define one static readonly ActionId per rebindable action.
    /// </summary>
    public static readonly ActionId Activate = new($"{nameof(MyWidget)}.{nameof(Activate)}");

    /// <summary>
    /// Optional configuration property.
    /// </summary>
    internal bool SomeOption { get; init; }
    
    /// <summary>
    /// Event handler for some action.
    /// </summary>
    internal Func<MyEventArgs, Task>? ActionHandler { get; init; }

    /// <summary>
    /// Sets a synchronous action handler.
    /// </summary>
    public MyWidget OnAction(Action<MyEventArgs> handler)
        => this with { ActionHandler = args => { handler(args); return Task.CompletedTask; } };

    /// <summary>
    /// Sets an asynchronous action handler.
    /// </summary>
    public MyWidget OnAction(Func<MyEventArgs, Task> handler)
        => this with { ActionHandler = handler };

    internal override Hex1bNode Reconcile(Hex1bNode? existingNode, ReconcileContext context)
    {
        var node = existingNode as MyNode ?? new MyNode();
        
        // Mark dirty if properties changed
        if (node.PrimaryProperty != PrimaryProperty || node.SomeOption != SomeOption)
        {
            node.MarkDirty();
        }
        
        node.PrimaryProperty = PrimaryProperty;
        node.SomeOption = SomeOption;
        node.SourceWidget = this;
        
        // Convert typed event handler to internal handler if needed
        if (ActionHandler != null)
        {
            node.ActionCallback = async ctx => 
            {
                var args = new MyEventArgs(this, node, ctx);
                await ActionHandler(args);
            };
        }
        else
        {
            node.ActionCallback = null;
        }
        
        return node;
    }

    internal override Type GetExpectedNodeType() => typeof(MyNode);
}