@shlomoa/openui-spec 0.1.1 → 0.3.0

package/README.md

@@ -9,13 +9,37 @@ This repository contains a technology-independent specification for a Web UI fra
 Contributor and developer entry points for this repository:
 
 - [Contributing guide](CONTRIBUTING.md) — local setup and validation basics.
+- [Changelog](CHANGELOG.md) — release notes, breaking changes, and upgrade guidance.
 
-## OpenUI JSON API
+## OpenUI JSON packages
 
-The [`@shlomoa/openui-spec`](package.json) package provides `OpenUiJson` for
-loading, validating, and editing an OpenUI JSON document. It bundles
-`spec/openui.schema.json` and `spec/openui.json`; validation checks both the
-schema and the object types supported by the canonical catalog.
+Both implementations bundle `spec/openui.schema.json` and `spec/openui.json`.
+Validation checks the document shape, exact
+[known object type](https://openui-spec.readthedocs.io/en/latest/#known-object-type)
+membership, and globally unique object IDs.
+
+### Python
+
+The [`openui-spec`](https://pypi.org/project/openui-spec/) package requires
+Python 3.12 or newer and installs two command-line tools:
+
+- `openui_spec` validates and edits documents with `validate`, `add`, `remove`,
+  and `modify` commands.
+- `compare_openui_spec` structurally compares two documents and emits a
+  deterministic JSON changelog.
+
+```bash
+python -m pip install openui-spec
+openui_spec validate --input document.json
+openui_spec add --input document.json --parent root --object '{"id":"newTable","type":"Table"}'
+compare_openui_spec reference.json updated.json --output changelog.json
+```
+
+### TypeScript and Node.js
+
+The [`@shlomoa/openui-spec`](https://www.npmjs.com/package/@shlomoa/openui-spec)
+package provides the typed `OpenUiJson` document API and the equivalent
+`ng-openui-spec` editing CLI.
 
 ```bash
 npm install @shlomoa/openui-spec
@@ -27,19 +51,28 @@ import { OpenUiJson } from "@shlomoa/openui-spec";
 const document = OpenUiJson.load("input.json");
 document.validate();
 document.add("root", { id: "newTable", type: "Table" });
+document.updateAttributes("newTable", { title: "Updated" });
 document.save("output.json");
 ```
 
-The published [OpenUI JSON editing](https://openui-spec.readthedocs.io/en/latest/tooling/editing/)
-tooling page documents the API and command-line interface.
-
-The package also installs an `ng-openui-spec` CLI to validate or apply one change
-in place (pass `--output` to write to a different file):
-
 ```bash
-ng-openui-spec validate --input spec/openui.json
-ng-openui-spec add --input document.json --parent root --object '{"id":"newTable","type":"Table"}'
-ng-openui-spec remove --input document.json --id newTable
-ng-openui-spec modify --input document.json --id table --attrs '{"title":"Updated"}'
-ng-openui-spec modify --input document.json --id table --object '{"id":"table","type":"Grid"}'
+ng-openui-spec validate --input document.json
 ```
+
+### Essentials
+
+- An OpenUI document is a tree with a root `id` of `root`; every node has a
+  unique camelCase `id` and an exact, case-sensitive catalog `type`.
+- Put non-hierarchical values in `attrs` as strings or `null`, and nested objects
+  in `children`.
+- Editing commands revalidate the result and update `--input` in place. Pass
+  `--output` to preserve the source document.
+- Values accepted by `--object` and `--attrs` can be inline JSON or paths to JSON
+  files.
+
+### Documentation
+
+- [Specification overview and artifact model](https://openui-spec.readthedocs.io/en/latest/#specification-artifacts-grammar-vs-catalog)
+- [OpenUI JSON editing API and CLI reference](https://openui-spec.readthedocs.io/en/latest/tooling/editing/)
+- [OpenUI JSON comparison guide](https://openui-spec.readthedocs.io/en/latest/tooling/comparison/)
+- [OpenUI document examples](https://openui-spec.readthedocs.io/en/latest/examples/)

package/dist/src/index.d.ts

@@ -42,6 +42,7 @@ export declare class OpenUiJson {
     }): void;
     updateAttributes(objectId: string, attributes: Record<string, string | null>): void;
     private validateChild;
+    private catalogTypes;
     private validateNode;
     private find;
     private findParent;

package/dist/src/index.js

@@ -77,15 +77,15 @@ class OpenUiJson {
         if (!validator(this.document)) {
             throw new OpenUiValidationError(formatValidationErrors(validator.errors));
         }
-        const supportedTypes = new Set([...this.walk(catalog)].map((node) => node.type));
+        const knownTypes = this.catalogTypes(catalog);
         const seenIds = new Set();
         for (const node of this.walk(this.document)) {
             if (seenIds.has(node.id)) {
                 throw new OpenUiValidationError(`duplicate object id: ${node.id}`);
             }
             seenIds.add(node.id);
-            if (!supportedTypes.has(node.type)) {
-                throw new OpenUiValidationError(`unsupported object type: ${node.type}`);
+            if (!knownTypes.has(node.type)) {
+                throw new OpenUiValidationError(`unknown OpenUI object type: ${node.type}`);
             }
         }
     }
@@ -164,18 +164,21 @@ class OpenUiJson {
     validateChild(child) {
         this.validateNode(child, false);
         const catalog = this.loadJson(this.options.catalog, this.options.catalogPath, "catalog");
-        const supportedTypes = new Set([...this.walk(catalog)].map((node) => node.type));
+        const knownTypes = this.catalogTypes(catalog);
         const seenIds = new Set();
         for (const node of this.walk(child)) {
             if (seenIds.has(node.id)) {
                 throw new OpenUiJsonError(`duplicate object id: ${node.id}`);
             }
             seenIds.add(node.id);
-            if (!supportedTypes.has(node.type)) {
-                throw new OpenUiJsonError(`unsupported object type: ${node.type}`);
+            if (!knownTypes.has(node.type)) {
+                throw new OpenUiJsonError(`unknown OpenUI object type: ${node.type}`);
             }
         }
     }
+    catalogTypes(catalog) {
+        return new Set([...this.walk(catalog)].map((node) => node.type));
+    }
     validateNode(node, isRoot) {
         const schema = this.loadJson(this.options.schema, this.options.schemaPath, "schema");
         const definition = isRoot ? schema : { $ref: "#/$defs/element", $defs: schema.$defs };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shlomoa/openui-spec",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "Load, validate, and edit OpenUI JSON documents.",
   "scripts": {
     "build:tsc": "tsc -p tsconfig.json",

package/spec/openui.json

@@ -1,7 +1,7 @@
 {
   "id": "root",
   "type": "html",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "attrs": {
     "name": "OpenUI",
     "description": "Technology-independent Web UI framework specification",
@@ -54,6 +54,35 @@
                 }
               ]
             },
+            {
+              "id": "route",
+              "type": "Route",
+              "attrs": {
+                "title": "Route",
+                "purpose": "A route maps a location pattern to application content or redirects the location to another route.",
+                "scopeDocument": "scopes/Application/route.scope.md",
+                "status": "draft"
+              },
+              "children": [
+                {
+                  "id": "routeInstance",
+                  "type": "Route",
+                  "attrs": {
+                    "[path]": null,
+                    "[target]": null,
+                    "[title]": null,
+                    "[redirectTo]": null,
+                    "[access]": null
+                  },
+                  "children": [
+                    {
+                      "id": "routeChildRoute",
+                      "type": "Route"
+                    }
+                  ]
+                }
+              ]
+            },
             {
               "id": "navigation",
               "type": "Navigation",
@@ -83,6 +112,58 @@
                 }
               ]
             },
+            {
+              "id": "navItem",
+              "type": "NavItem",
+              "attrs": {
+                "title": "Navigation item",
+                "purpose": "A navigation item presents one labelled application route as a user-selectable destination.",
+                "scopeDocument": "scopes/Application/nav_item.scope.md",
+                "status": "draft"
+              },
+              "children": [
+                {
+                  "id": "navItemInstance",
+                  "type": "NavItem",
+                  "attrs": {
+                    "[label]": null,
+                    "[route]": null,
+                    "[icon]": null,
+                    "[disabled]": null
+                  }
+                }
+              ]
+            },
+            {
+              "id": "navGroup",
+              "type": "NavGroup",
+              "attrs": {
+                "title": "Navigation group",
+                "purpose": "A navigation group labels and organizes related navigation destinations.",
+                "scopeDocument": "scopes/Application/nav_group.scope.md",
+                "status": "draft"
+              },
+              "children": [
+                {
+                  "id": "navGroupInstance",
+                  "type": "NavGroup",
+                  "attrs": {
+                    "[label]": null,
+                    "[expanded]": null
+                  },
+                  "children": [
+                    {
+                      "id": "navGroupNavigationItem",
+                      "type": "NavItem"
+                    },
+                    {
+                      "id": "navGroupNavigationGroup",
+                      "type": "NavGroup"
+                    }
+                  ]
+                }
+              ]
+            },
             {
               "id": "toolBars",
               "type": "ToolBars",
@@ -96,19 +177,62 @@
                 {
                   "id": "toolBarsInstance",
                   "type": "ToolBar",
+                  "attrs": {
+                    "[ariaLabel]": null
+                  },
                   "children": [
                     {
                       "id": "toolBarsToolBarRow",
                       "type": "ToolBarRow"
-                    },
+                    }
+                  ]
+                }
+              ]
+            },
+            {
+              "id": "toolBarRow",
+              "type": "ToolBarRow",
+              "attrs": {
+                "title": "Tool bar row",
+                "purpose": "A tool bar row orders command actions within a tool bar.",
+                "scopeDocument": "scopes/Application/tool_bar_row.scope.md",
+                "status": "draft"
+              },
+              "children": [
+                {
+                  "id": "toolBarRowInstance",
+                  "type": "ToolBarRow",
+                  "children": [
                     {
-                      "id": "toolBarsToolAction",
+                      "id": "toolBarRowToolAction",
                       "type": "ToolAction"
                     }
                   ]
                 }
               ]
             },
+            {
+              "id": "toolAction",
+              "type": "ToolAction",
+              "attrs": {
+                "title": "Tool action",
+                "purpose": "A tool action is a labelled application command exposed from a tool bar.",
+                "scopeDocument": "scopes/Application/tool_action.scope.md",
+                "status": "draft"
+              },
+              "children": [
+                {
+                  "id": "toolActionInstance",
+                  "type": "ToolAction",
+                  "attrs": {
+                    "[label]": null,
+                    "[icon]": null,
+                    "[disabled]": null,
+                    "(activate)": null
+                  }
+                }
+              ]
+            },
             {
               "id": "favicon",
               "type": "Favicon",
@@ -147,7 +271,8 @@
                   "type": "html",
                   "attrs": {
                     "[lang]": null,
-                    "[dir]": null
+                    "[dir]": null,
+                    "[title]": null
                   },
                   "children": [
                     {
@@ -657,7 +782,7 @@
               "type": "ShellPage",
               "attrs": {
                 "title": "Shell page",
-                "purpose": "A page shell with no business-object content that connects application routing and navigation.",
+                "purpose": "A page shell with no business-object content that presents application routing and navigation.",
                 "scopeDocument": "scopes/Pages/shell_page.scope.md",
                 "status": "draft"
               },