Visual annotations of resources

[eladb]

Summary

Add information to Wing resources that improve their visual representation in the Wing Console

Feature Spec

You can control how a Wing resource looks & behaves in the Wing Console using the display API:

Let's look at an example:

bring cloud;

let queue = new cloud.Queue();
queue.display.visible = false; // default is "true"
queue.display.title = "My queue"; // default is to use the resource ID and/or type
queue.display.description = "This is the most awesome queue in the whole wide web"; // default is not defined

// or this can be defined within a resource initializer:
resource TaskList {
  init() {
    this.display.title = "TODO";
    this.display.description = "A task list that gets things done";
  }
}

Use Cases

The use case is to allow users (and us) to control how a resource looks and behaves in the Wing Console.

Initially, we will just support:

• title
• description
• hidden

Future ideas:

1. The ability to add behavioral information such as operations that can you perform with the resource (incl. specifying an inflight function that will be executed inside the console 🤯 ).
2. The ability to control the customize the look & feel of the resource in the resource map and in the resource page.
3. Eventually we want to move most of the UI logic for each resource into this model.

But let's start simple.

Implementation Notes

This is mostly straightforward to implement. Sketch:

• Create a Display class.
• Add a display property to the base Resource class with these three getters/setters.
• Apply the default when Display is initialized (this.display = new Display(this))
• When we synthesize tree.json we include a display section for each resource that includes this information.

Consume the information in the Wing Console.

Component

SDK, Wing Console

[skyrpex]

I like the idea of defining the resource's look and behavior using source code. I'll dump some thoughts here, not very curated...

Referencing Nova, which is similar to Wing Console

Laravel Nova is kind of similar to the Wing Console. It's an admin panel that allows you to define how your Laravel models look and behave by using code. For every resource (ex, a User), Nova allows you to define the fields that are displayed and the actions you can take on it. It's an API similar to this:

/**
 * Get the fields displayed by the resource.
 *
 * @param  \Laravel\Nova\Http\Requests\NovaRequest  $request
 * @return array
 */
public function fields(NovaRequest $request)
{
    return [
        ID::make()->sortable(),
        Text::make('Name')->sortable(),
    ];
}

/**
 * Get the actions available for the resource.
 *
 * @param  \Laravel\Nova\Http\Requests\NovaRequest  $request
 * @return array
 */
public function actions(NovaRequest $request)
{
    return [
        new Actions\EmailAccountProfile
    ];
}

It's all PHP code, no UI code. Nova will end up consuming whatever is defined in these resources and provide the UI for it. The Wing Console could do the same.

(Complex) Ideas for resource customization in Wing

For every Wing custom resource, we could allow defining the following:

• Title
• Description
• Whether it's visible by default
• Icon
• The fields that should be rendered by the Console (eg: text fields, number fields, json fields)
• The actions that can be taken upon the resource (eg: adding a task, removing a task)

Details that matter:

• Icon: constraints should apply for a good UX... It should be a relative filename to an SVG icon, IMO
• Fields and actions: Wing should provide autocomplete and type hinting when you write your fields and actions, based on the inflight API of the resource. That's why I think we should have the console keyword built-in in Wing

Let's see some pseudo code just to gather an idea of some interesting capabilities:

Example with console keyword

// task-list.w
bring cloud;

resource TaskList {
    inflight tasks(): Array<str> {
        // ...
    }

    inflight taskCount(): num {
        // ...
    }

    inflight addTask(taskName: str) {
        // ...
    }

    // Typing the `console` keyword would allow auto-completing either icon, fields or actions.
    // Maybe, the icon could be deduced automatically if it has the same filename as the source code, but with `.svg` extension.
    console icon: "./task-list.svg";

    // The fields to be shown in the Console UI
    console fields(fields) {
        return [
            // For excellent UX, the names of the inflight methods should be autocompleted for these field classes.
            new fields.Number("taskCount", name: "Task Count"),
            new fields.Json("tasks", name: "Tasks"),
        ];
    }

    // The actions to be shown in the Console UI
    console actions(actions) {
        return [
            // Same autocompletion capabilities here.
            new actions.Action("addTask", name: "Add Task", description: "Adds a task to the list"),
        ];
    }
}

It needs more thought as to how to provide the autocompletion and type hinting properly...

Example without the console keyword

Another possible syntax, without the console keyword (but feels wrong, see comment below):

// task-list.w
bring cloud;

resource TaskList {
    inflight tasks(): Array<str> {
        // ...
    }

    inflight taskCount(): num {
        // ...
    }

    inflight addTask(taskName: str) {
        // ...
    }

    init() {
        // The callbacks receive an inflight client, which feels wrong since we're running preflight code here...
        this.display.addField(new console.NumberField(name: "Task Count", value: client => client.taskCount()));
        this.display.addField(new console.NumberField(name: "Tasks", value: client => client.tasks()));
        this.display.addAction(new console.Action(
            name: "Add Task",
            description: "Adds a task to the list",
            handle: (input: { taskName: str }, client) => client.addTask(taskName),
        ));
    }
}

A different flavor of the console keyword: console field and console action

// task-list.w
bring cloud;

resource TaskList {
    inflight tasks(): Array<str> {
        // ...
    }

    inflight taskCount(): num {
        // ...
    }

    inflight addTask(taskName: str) {
        // ...
    }

    console field taskCountDoubled(): num {
        return this.client.taskCount() * 2;
    }

    console field tasks() {
        return this.client.tasks();
    }

    console action addTask(taskName: str) {
        return this.client.addTask(taskName);
    }
}

[eladb]

@skyrpex this is great. I don't see strong need to add dedicated syntax for this.

Let's start simple (and also with minimal APIs, this.display.title, description, visibility), and iterate on it.

Any objects?

[monadabot]

Congrats! 🚀 This was released in Wing 0.4.91.