@gunkin/uiify 0.0.26-alpha → 0.0.27-alpha

package/README.md

@@ -32,6 +32,65 @@ export function SaveButton() {
 Use focused `@gunkin/uiify/components/*`, `@gunkin/uiify/elements/*`, `@gunkin/uiify/core/*`, or `@gunkin/uiify/hooks` imports in
 Server Components so client boundaries remain explicit.
 
+## UI documents (`@gunkin/uiify/ai`)
+
+A UI document is a JSON tree of UIify parts: `{ type, props, children }`, with no styling and no
+code. An agent writes it in your repository, or an LLM in your product stores it in a database;
+`UiDocument` renders it in Server Components, with SSR and hydration, and without JavaScript in
+the browser.
+
+Ask your agent, for example `/uiify Add a status filter above the orders table at /orders`.
+The result is an ordinary component:
+
+```tsx
+import { Suspense } from "react";
+import { UiDocument, type UiNodeInput } from "@gunkin/uiify/ai";
+
+const filter = {
+  type: "form",
+  props: { method: "get", role: "search" },
+  children: [
+    { type: "label", props: { htmlFor: "status" }, children: ["Status"] },
+    {
+      type: "Select.Root",
+      props: { id: "status", name: "status" },
+      children: [
+        { type: "Select.Item", props: { value: "open" }, children: ["Open"] },
+        { type: "Select.Item", props: { value: "closed" }, children: ["Closed"] },
+      ],
+    },
+    { type: "Button", props: { type: "submit" }, children: ["Apply"] },
+  ],
+} satisfies UiNodeInput;
+
+export function OrdersFilter() {
+  return (
+    <Suspense>
+      <UiDocument node={filter} />
+    </Suspense>
+  );
+}
+```
+
+`satisfies UiNodeInput` makes TypeScript reject an unknown part, prop or value at the line that is
+wrong. For a document from a database, validate it before saving; `UiDocument` validates again
+before rendering and never renders an invalid document:
+
+```ts
+import { validateDocument } from "@gunkin/uiify/ai";
+
+const result = validateDocument(JSON.parse(body));
+if (!result.ok) return Response.json(result.issues, { status: 422 });
+// result.issues[0] for `variant: "primary"`:
+// { breadcrumb: "form › Stack › Button.props.variant",
+//   message: "\"primary\" is not allowed; use one of \"secondary\", \"outline\", …" }
+await db.pages.save(result.document);
+```
+
+Interactivity is native: links, `GET`/`POST` forms and invoker commands (`commandfor`). Parts
+documents cannot use yet are listed in `uiUnavailableParts`; `uiDocumentSchema` is the JSON Schema
+to give your own LLM.
+
 ## AI coding agents
 
 `@gunkin/uiify` ships rules, a component index and per-component references that match the

package/agents/components.md

@@ -4,6 +4,8 @@
 Rules and anti-patterns: [index.md](./index.md). Each entry links to a generated reference with
 its exports, props and shapes; exact types are in the `.d.ts` file listed in the Types column.
 
+UI documents (`@gunkin/uiify/ai`) use many of these components as parts; the part types are in `dist/ai/catalog.generated.d.ts`.
+
 ## Tiers
 
 | Tier | Meaning | Client JavaScript | Without JavaScript |

package/agents/index.md

@@ -186,6 +186,7 @@ With that order in place, rules in the `app` layer win over the library:
 
 - `@gunkin/uiify/components/<name>`: components (names in `components.md`)
 - `@gunkin/uiify/elements/<name>`: native-element primitives for building your own anatomy
+- `@gunkin/uiify/ai`: render JSON UI documents with `UiDocument` and check them with `validateDocument`; the version-matched catalog of part types and TSDoc is `dist/ai/catalog.generated.d.ts`
 - `@gunkin/uiify/hooks`: hooks
 - `@gunkin/uiify/core/<name>`: React-agnostic stores and render helpers
 - `@gunkin/uiify/components/behavior.css`: required behavior CSS, no visual styles

package/dist/ai/UiDocument.d.ts

@@ -0,0 +1,16 @@
+import type { ReactElement } from "react";
+import type { UiDocumentProps } from "./types.js";
+/**
+ * Renders an untrusted UI document. It validates first and throws `UiDocumentError` instead of
+ * rendering a partial guess, then renders each part with its UIify component. It uses no state
+ * or context, so it runs in a Server Component and hydrates on the client; wrap it in `Suspense`.
+ *
+ * Documents are immutable: the first render of a `node` object validates and renders a frozen
+ * copy of it (see `loadDocument`), and later changes to that object are ignored. Pass a new
+ * object to render a changed document.
+ */
+export declare function UiDocument({ node }: UiDocumentProps): ReactElement;
+export declare namespace UiDocument {
+    var displayName: string;
+}
+//# sourceMappingURL=UiDocument.d.ts.map

package/dist/ai/UiDocument.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"UiDocument.d.ts","sourceRoot":"","sources":["../../src/ai/UiDocument.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAiB,YAAY,EAAa,MAAM,OAAO,CAAC;AAIpE,OAAO,KAAK,EAAkB,eAAe,EAAE,MAAM,YAAY,CAAC;AAkClE;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,EAAE,IAAI,EAAE,EAAE,eAAe,GAAG,YAAY,CAGlE;yBAHe,UAAU"}

package/dist/ai/UiDocument.js

@@ -0,0 +1,33 @@
+import { createElement, use } from "react";
+import { uiParts } from "./catalog.generated.js";
+import { assertDocument, childrenOf, loadDocument } from "./load.js";
+const loads = /* @__PURE__ */ new WeakMap();
+function loadOnce(node) {
+  if (typeof node !== "object" || node === null) {
+    assertDocument(node);
+    return loadDocument(node);
+  }
+  let load = loads.get(node);
+  if (!load) {
+    load = loadDocument(node);
+    loads.set(node, load);
+  }
+  return load;
+}
+function renderNode(node, components, key) {
+  const type = uiParts[node.type].kind === "native" ? node.type : components.get(node.type);
+  if (type === void 0) throw new Error(`UI part type ${node.type} was not loaded`);
+  const children = childrenOf(node).map(
+    (child, index) => typeof child === "string" ? child : renderNode(child, components, index)
+  );
+  return createElement(type, key === void 0 ? node.props : { ...node.props, key }, ...children);
+}
+function UiDocument({ node }) {
+  const { root, components } = use(loadOnce(node));
+  return renderNode(root, components);
+}
+UiDocument.displayName = "UiDocument";
+export {
+  UiDocument
+};
+//# sourceMappingURL=UiDocument.js.map

package/dist/ai/UiDocument.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/ai/UiDocument.tsx"],"sourcesContent":["import { createElement, use } from \"react\";\nimport type { ComponentType, ReactElement, ReactNode } from \"react\";\nimport type { UiChild, UiNode, UiType } from \"./catalog.generated.js\";\nimport { uiParts } from \"./catalog.generated.js\";\nimport { assertDocument, childrenOf, loadDocument } from \"./load.js\";\nimport type { LoadedDocument, UiDocumentProps } from \"./types.js\";\n\n// One load per document object, so every render of the same `node` hands `use()` the same promise.\nconst loads = new WeakMap<object, Promise<LoadedDocument>>();\n\nfunction loadOnce(node: unknown): Promise<LoadedDocument> {\n  if (typeof node !== \"object\" || node === null) {\n    // A primitive cannot key the WeakMap and is never a valid document: throw its issues now.\n    assertDocument(node);\n    return loadDocument(node);\n  }\n  let load = loads.get(node);\n  if (!load) {\n    load = loadDocument(node);\n    loads.set(node, load);\n  }\n  return load;\n}\n\nfunction renderNode(\n  node: UiNode,\n  // oxlint-disable-next-line typescript/no-explicit-any -- each part takes its own props\n  components: ReadonlyMap<UiType, ComponentType<any>>,\n  key?: number,\n): ReactElement {\n  const type = uiParts[node.type].kind === \"native\" ? node.type : components.get(node.type);\n  if (type === undefined) throw new Error(`UI part type ${node.type} was not loaded`);\n  const children = childrenOf(node).map(\n    (child: UiChild, index: number): ReactNode =>\n      typeof child === \"string\" ? child : renderNode(child, components, index),\n  );\n  return createElement(type, key === undefined ? node.props : { ...node.props, key }, ...children);\n}\n\n/**\n * Renders an untrusted UI document. It validates first and throws `UiDocumentError` instead of\n * rendering a partial guess, then renders each part with its UIify component. It uses no state\n * or context, so it runs in a Server Component and hydrates on the client; wrap it in `Suspense`.\n *\n * Documents are immutable: the first render of a `node` object validates and renders a frozen\n * copy of it (see `loadDocument`), and later changes to that object are ignored. Pass a new\n * object to render a changed document.\n */\nexport function UiDocument({ node }: UiDocumentProps): ReactElement {\n  const { root, components } = use(loadOnce(node));\n  return renderNode(root, components);\n}\nUiDocument.displayName = \"UiDocument\";\n"],"mappings":"AAAA,SAAS,eAAe,WAAW;AAGnC,SAAS,eAAe;AACxB,SAAS,gBAAgB,YAAY,oBAAoB;AAIzD,MAAM,QAAQ,oBAAI,QAAyC;AAE3D,SAAS,SAAS,MAAwC;AACxD,MAAI,OAAO,SAAS,YAAY,SAAS,MAAM;AAE7C,mBAAe,IAAI;AACnB,WAAO,aAAa,IAAI;AAAA,EAC1B;AACA,MAAI,OAAO,MAAM,IAAI,IAAI;AACzB,MAAI,CAAC,MAAM;AACT,WAAO,aAAa,IAAI;AACxB,UAAM,IAAI,MAAM,IAAI;AAAA,EACtB;AACA,SAAO;AACT;AAEA,SAAS,WACP,MAEA,YACA,KACc;AACd,QAAM,OAAO,QAAQ,KAAK,IAAI,EAAE,SAAS,WAAW,KAAK,OAAO,WAAW,IAAI,KAAK,IAAI;AACxF,MAAI,SAAS,OAAW,OAAM,IAAI,MAAM,gBAAgB,KAAK,IAAI,iBAAiB;AAClF,QAAM,WAAW,WAAW,IAAI,EAAE;AAAA,IAChC,CAAC,OAAgB,UACf,OAAO,UAAU,WAAW,QAAQ,WAAW,OAAO,YAAY,KAAK;AAAA,EAC3E;AACA,SAAO,cAAc,MAAM,QAAQ,SAAY,KAAK,QAAQ,EAAE,GAAG,KAAK,OAAO,IAAI,GAAG,GAAG,QAAQ;AACjG;AAWO,SAAS,WAAW,EAAE,KAAK,GAAkC;AAClE,QAAM,EAAE,MAAM,WAAW,IAAI,IAAI,SAAS,IAAI,CAAC;AAC/C,SAAO,WAAW,MAAM,UAAU;AACpC;AACA,WAAW,cAAc;","names":[]}