The kragle editor only scans the top-level workspace directory for scene files. Instead, it should recursively scan all sub-directories inside the workspace. Scenes from sub-directories must be opened, saved, and new scenes created.

Consider this example entity:

import { t } from "@kragle/runtime";

interface User {
  readonly firstName: string;
  readonly lastName: string;
  getFullName(): string;
}

const userEntity = t.entity<User>("acme::User");

If we want to extract the user name and pass it to a node input of type string, we need to create a library function function getFirstName(user: User): string { return user.firstName; } for that. This approach doesn't scale for larger data models.

When defining an entity, it should be possible to declare properties, like so:

const userEntity = t.entity<User>("acme::User", {
  firstName: {
    type: t.string(),
  },
  lastName: {
    type: t.string(),
  },
  getFullName: {
    type: t.function()(t.string()),
  },
});

I'm debating whether we should support t.undefined() in the Kragle type system. Advantages of removing undefined:

1. null is a billion dollar mistake on it's own, and JavaScript has two flavors of null. We could encourage users to use only null, and never use undefined.
2. Hopefully, an ecosystem of 3rd party packages will evolve around Kragle. Removing undefined could help with harmonizing node APIs and remove one pitfall that package authors no longer have to worry about.
3. If expressions configured in the editor can only evaluate to null, then it's possible for a node component to detect whether an optional input was set to null, or not set at all. (Question: is that useful for node components?)

Follow-up to #11. When assigning a node input value, users can choose from all scene inputs that are assignable to the input type. They can also choose the option "Create new scene input ...", this will prompt for an input name, then create a new scene input with the same type as the node input type.

In the editor node tree, the scene itself should be selectable as the tree root element. When selecting the scene itself, the node properties tool displays a list of scene inputs and let's the user assign a literal value, a library member, a function call, or a stage-prop.

stage-props are values that are passed to the <Stage /> component, like this:

root.render(
  <StrictMode>
    <Stage
      definitions={definitions}
      translate={{ type: t.function(t.string())(t.string()), value: myTranslateCallback }}
    />
  </StrictMode>
);

Support undo and redo actions for changing node input expressions, and for changing the node tree structure.

New nodes can only be inserted into empty regular slots, or in the last position of a collection slot. After creating a node, it can't be moved to a different place; if the node needs to be moved, the user has only two options: 1. Delete the node and create a new one at the target location with the same properties and descendants, or 2. manually edit the scene.json file.

The editor needs to support drag&drop gestures inside the node tree, allowing users to move nodes to a new location.

Task

At the moment, the project code is unlicensed, which makes it unusable by anyone but me. I need to decide on a license.

Background thoughts

• I would love to open source the project completely.
• I believe the project has a lot of potential, and I would like to work on it full-time. I already work a full-time job, but could quit it if this project somehow generates revenue to sustain me.
• Profitability is not a top priority at this stage of the project; I'm fine with publishing the project as open source for now and figure out the business aspects later.
• While I focus on building the technical foundation, and rest assured that nobody can exploit my work without collaborating with me.

Solution ideas

I'm thinking of publishing the project under these licensing terms:

• Buildings apps (private, open source, closed source, and commercial) with the engine is free.
• Building node libraries and IDE extensions (private, open source, closed source, and commercial) is free.
• Embedding the IDE, building a new IDE on the existing type system and runtime, or forking the project, is allowed IF AND ONLY IF the new project is published under a strict open source license that prevents commercial use, like GPL.
  • The idea here is to give the community a safety net in case the project is not commercially successful, and I eventually have to stop supporting it. In this case, it could still be maintained by volunteers.
  • If a 3rd party wants to embed the IDE into a commercial product, or build a new IDE on the existing type system, it could be allowed through individually negotiated multi-licensing.

Next steps

• Research how other open source projects are financed (e.g. Remix).
• Contact a lawyer.

The editor node tree should support an edit operation to turn the left node tree into the right node tree, without having to delete and re-create node C (including all descendants of C).

A              A
└╴C            └╴B
  ├╴D    -->     └╴C
  └╴E              ├╴D
                   └╴E

For collection slots, #6 will offer a decent workaround: create B as a sibling of C, then move C into B. This doesn't work for regular slots, because B can't be created while C still occupies the slot.

One possible solution is to replace the "add child" button of regular slots with a "replace child" button while the slot is filled. Pressing this button will create the selected node type, insert it into that slot, and insert the previous slot child into the first slot of the newly created node.

When pressing the "add child" button in the editor node tree, a dialog opens that prompts the user to select a node type for the new node. In addition to selecting a node type, it should also be possible to select an existing scene that is rendered into the slot.

The nested scene is only referenced, not copied. It is not possible to change the structure of the nested scene from within the host scene.

It is possible to bind scene inputs to node outputs from the host scene.

1. Add a property formatScene?(code: string): string to the editor app props in @kragle/editor.
2. Pass prettier.format to the editor in the example.

Add a description property of type string to NodeSchemaInput. Display the text in the editor inside the tooltip when a user hovers over the "help" icon. (At least for inputs; we can display the output description inside the data flow analyzer, once it's implemented.)

export const MuiButtonSchema = new NodeSchema(
  "@kragle/template-mui-material::Button",
  {
    inputs: {
      label: {
        description: `
          Buttons allow users to take actions, and make choices, with a single
          tap.

          Buttons communicate actions that users can take. They are typically
          placed throughout your UI, in places like:
           * Modal windows
           * Forms
           * Cards
           * Toolbars`,
        type: t.string(),
      },
    },
  }
);

At the moment, we use the native HTML title attribute to display tooltips, so we can only render simple strings without formatting. For the scope of this issue, implement a simple text transformation for the description:

• Remove the common leading whitespace from all lines.
• Concatenate adjacent non-empty lines.

The result of this transformation, applied to the example above, results in this string:

Buttons allow users to take actions, and make choices, with a single tap.

Buttons communicate actions that users can take. They are typically placed throughout your UI, in places like:
 * Modal windows
 * Forms
 * Cards
 * Toolbars

This is the text that needs to be passed to the form controls as a help tooltip.

Later on, we want to support full Markdown rendering. First we need to implement HTML tooltips though; let's hope that Open UI makes some progress fast. :)

Follow-up to #9. It should be possible to define recursive entities. Here is an idea how the API could look like:

// The result of `t.entity<User>` becomes `() => t.Entity<User>`, but every call
// returns the identical `t.Entity` object.
const userEntity = t.entity<User>("acme::User", () => ({
  name: {
    type: t.string(),
  },
  friends: {
    type: t.array(userEntity()),
  },
}));

At the moment, generated scene components can't have props. This means that all external state must be passed into the scene through React context, then unpacked and exposed as outputs by BLoC components that are placed at the root of the scene node tree.

Instead, it should be possible to declare scene inputs inside of a scene. Scene inputs are serialized and stored inside the scene.json file, like this:

{
  "sceneInputs": {
    "colorScheme": {
      "type": {
        "type": "union",
        "elements": [
          {
            "type": "string",
            "value": "light"
          },
          {
            "type": "string",
            "value": "dark"
          }
        ]
      },
      "stageValue": {
        "type": "string-literal",
        "value": "light"
      }
    },
    "translate": {
      "type": {
        "type": "function",
        "parameters": [
          {
            "type": "string"
          }
        ],
        "returns": {
          "type": "string"
        }
      },
      "stageValue": {
        "type": "stage-prop",
        "prop": "translate"
      }
    }
  },
  "rootNode": "MyBloc",
  "nodes": {
    ...
  }
}

The generated scene.tsx file will contain the following code:

export interface MySceneProps {
  colorScheme: "light" | "dark";
  translate: (p1: string) => string;
}

export function MyScene({ colorScheme, translate }: MySceneProps) {
  ...
}

For the production scene.tsx code, the scene input values can be provided by the user when the scene component is rendered. Inside the stage, that doesn't work. Instead, the user must be able to assign values to the scene inputs through the editor UI. The editor UI changes are out of scope of this issue, and will be covered in a separate issue. But this issue needs to lay the foundation by implementing a mechanism where the stage runtime evaluates Expressions and passes the values to the scene inputs. The expressions are persisted in the stageValue key of scene.json.