create-forma-extension 0.1.0 → 0.2.0

package/README.md

@@ -49,8 +49,8 @@ Expected errors exit with code 1 and a single-line message; successful commands
 
 | Path | Contents |
 | --- | --- |
-| `package.json` | Private ESM package, display name, pinned SDK and development dependencies, development/typecheck/build scripts. |
-| `index.html`, `src/` | Native Autodesk controls, responsive panel layouts, proposal and footprint adapters, synthetic preview, loading/empty/error states. |
+| `package.json` | Private ESM package, display name, `forma-extension-kit` dependency, pinned SDK peer and development dependencies, development/typecheck/build scripts. |
+| `index.html`, `src/` | Native Autodesk controls, responsive panel layouts, host reads through `forma-extension-kit`, synthetic preview, loading/empty/error states. |
 | `forma/buttons.yaml` | Floating-panel button registration. |
 | `tsconfig.json`, `vite.config.ts` | Strict TypeScript and Vite on port 5173. |
 | `.editorconfig`, `.gitattributes`, `.gitignore` | Editor, line-ending and Git defaults. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-forma-extension",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Create an Autodesk Forma extension with Vite, TypeScript and native Autodesk UI.",
   "type": "module",
   "license": "MIT",

package/template/README.md

@@ -60,13 +60,13 @@ Select **Open full panel** in the toolbar for the floating view.
 
 ## What you get
 
-- Vite and strict TypeScript. SDK **0.96.0** is the only direct runtime npm dependency.
+- Vite and strict TypeScript. Runtime dependencies are `forma-extension-kit` and SDK **0.96.0**, retained directly to satisfy the kit's peer dependency.
 - Autodesk [base.css](https://app.autodeskforma.eu/design-system/v2/forma/styles/base.css), Artifakt type and CDN Weave tabs, select, primary button and inline error banner. No Weave npm package.
 - Local 4/8/16 px spacing, 24 px controls and 11/12 px type roles, accounting for the Design System's 10 px root.
 - Two tabs, a metric row, a working building-scope select and a locale-safe decimal input. The example limit demonstrates input only; it does not filter buildings.
 - Compact right-panel and full floating layouts. Each view reads independently; select Refresh after proposal edits. There is no shared mutable state or overlay in this starter.
-- `src/forma.ts`: persisted proposal reads, singular `building` and `site_limit` paths, deduplicated building counts and base-group classification.
-- An on-demand `readFootprint(path, snapshot)` adapter: graph and floor representations → direct context footprint → complete child footprints → XY triangles → last-resort direct native footprint. It checks the revision and retains failed-provider diagnostics.
+- Host adapters from [`forma-extension-kit`](https://www.npmjs.com/package/forma-extension-kit) ([repository](https://github.com/sharafutdinovdi/forma-extension-kit)): persisted proposal reads, singular `building` and `site_limit` paths, deduplicated building counts and base-group classification. `src/host.ts` selects fixture data or kit reads and prepares the proposal summary.
+- The kit's on-demand `readFootprint(path, snapshot)` adapter: graph and floor representations → direct footprint → complete child footprints → XY triangles → final direct-footprint retry. It checks the revision and retains failed-provider diagnostics.
 - Ready, loading, actionable empty and retryable error states. Use `?fixture=1&state=empty`, `state=loading` or `state=error`; Retry/Refresh returns the fixture to ready.
 
 

package/template/package.json

@@ -14,7 +14,8 @@
     "build": "vite build"
   },
   "dependencies": {
-    "forma-embedded-view-sdk": "0.96.0"
+    "forma-embedded-view-sdk": "0.96.0",
+    "forma-extension-kit": "^0.1.0"
   },
   "devDependencies": {
     "typescript": "5.9.3",

package/template/src/fixture.ts

@@ -1,8 +1,9 @@
-import type { ProposalSnapshot } from "./forma";
+import type { BuildingKind } from "forma-extension-kit";
+import type { ProposalView } from "./host";
 
 export type ViewState = "ready" | "empty" | "loading" | "error";
 
-export function fixtureData(empty = false): ProposalSnapshot {
+export function fixtureData(empty = false): ProposalView {
   return {
     rootUrn: "fixture-root",
     proposalId: "fixture-proposal",
@@ -11,7 +12,7 @@ export function fixtureData(empty = false): ProposalSnapshot {
     siteLimitPaths: empty ? [] : ["root/site"],
     buildings: empty ? [] : ["proposal", "proposal", "existing"].map((kind, index) => ({
       path: index === 2 ? "root/base/context" : `root/proposal-${index === 0 ? "a" : "b"}`,
-      kind: kind as "proposal" | "existing",
+      kind: kind as BuildingKind,
     })),
   };
 }

package/template/src/host.ts

@@ -0,0 +1,17 @@
+import { classifyBuilding, readProposalSnapshot, type BuildingKind, type ProposalSnapshot } from "forma-extension-kit";
+import { fixtureData } from "./fixture";
+
+export type ProposalView = Pick<ProposalSnapshot, "rootUrn" | "proposalId" | "buildingPaths" | "siteLimitPaths"> & {
+  name: string;
+  buildings: { path: string; kind: BuildingKind }[];
+};
+
+export async function readProposal(fixture = false, empty = false): Promise<ProposalView> {
+  if (fixture) return fixtureData(empty);
+  const snapshot = await readProposalSnapshot();
+  const buildings = await Promise.all(snapshot.buildingPaths.map(async path => ({
+    path, kind: await classifyBuilding(path, snapshot),
+  })));
+  const name = snapshot.rootTree.element.properties?.name;
+  return { ...snapshot, buildings, name: typeof name === "string" ? name : snapshot.proposalId };
+}

package/template/src/main.ts

@@ -1,5 +1,5 @@
 import "./styles.css";
-import { fixtureData } from "./fixture";
+import { readProposal } from "./host";
 import { createApp } from "./ui/app";
 
 const params = new URLSearchParams(location.search);
@@ -10,7 +10,7 @@ let generation = 0;
 async function load(retry = false) {
   const current = ++generation;
   app.render("loading", null, "Reading the current proposal…");
-  // A fixture always wins, even inside an iframe; importing /auto starts the SDK handshake.
+  // A fixture always wins, even inside an iframe; host reads start the SDK handshake.
   if (fixture) {
     const state = retry ? "ready" : params.get("state");
     if (state === "loading") return;
@@ -19,7 +19,7 @@ async function load(retry = false) {
       return;
     }
     const empty = state === "empty";
-    app.render(empty ? "empty" : "ready", fixtureData(empty), empty
+    app.render(empty ? "empty" : "ready", await readProposal(true, empty), empty
       ? "Draw a building or order Overture buildings in Contextual data, then select Refresh."
       : "Synthetic data. In Forma, select Refresh after editing the proposal.");
     return;
@@ -28,14 +28,8 @@ async function load(retry = false) {
     app.render("error", null, "Open this URL in Forma, or add ?fixture=1 for a synthetic preview. Then select Retry.");
     return;
   }
-  let timer: ReturnType<typeof setTimeout> | undefined;
   try {
-    const snapshot = await Promise.race([
-      import("./forma").then(({ readProposal }) => readProposal()),
-      new Promise<never>((_, reject) => {
-        timer = setTimeout(() => reject(new Error("Forma did not respond within 8 seconds")), 8000);
-      }),
-    ]);
+    const snapshot = await readProposal();
     if (current !== generation) return;
     app.render(snapshot.buildings.length ? "ready" : "empty", snapshot, snapshot.buildings.length
       ? "Select Refresh after editing the proposal."
@@ -43,8 +37,6 @@ async function load(retry = false) {
   } catch (error) {
     if (current !== generation) return;
     app.render("error", null, `${error instanceof Error ? error.message : String(error)}. Check the Forma project and select Retry.`);
-  } finally {
-    clearTimeout(timer);
   }
 }
 

package/template/src/ui/app.ts

@@ -1,4 +1,4 @@
-import type { ProposalSnapshot } from "../forma";
+import type { ProposalView } from "../host";
 import type { ViewState } from "../fixture";
 import { metricRow } from "./metric-row";
 import { numberInput } from "./number-input";
@@ -43,7 +43,7 @@ export function createApp(root: HTMLElement, fixture: boolean, refresh: () => vo
   help.textContent = "Decimal input example. It does not change the building count.";
   controls.append(help);
 
-  let snapshot: ProposalSnapshot | null = null;
+  let snapshot: ProposalView | null = null;
   let scope = "all";
   let state: ViewState = "loading";
   const paintMetric = () => {
@@ -78,7 +78,7 @@ export function createApp(root: HTMLElement, fixture: boolean, refresh: () => vo
   });
 
   return {
-    render(next: ViewState, data: ProposalSnapshot | null, message: string) {
+    render(next: ViewState, data: ProposalView | null, message: string) {
       state = next;
       snapshot = data;
       root.dataset.state = state;

package/template/src/ui/metric-row.ts

@@ -1,4 +1,4 @@
-const format = new Intl.NumberFormat("en-US");
+import { formatNumber } from "forma-extension-kit";
 
 export function metricRow(label: string, unit = "") {
   const row = document.createElement("div");
@@ -13,5 +13,5 @@ export function metricRow(label: string, unit = "") {
   suffix.textContent = unit ? ` ${unit}` : "";
   value.append(amount, suffix);
   row.append(caption, value);
-  return { row, set: (number: number | null) => { amount.textContent = number === null ? "—" : format.format(number); } };
+  return { row, set: (number: number | null) => { amount.textContent = number === null ? "—" : formatNumber(number); } };
 }

package/template/src/ui/number-input.ts

@@ -1,15 +1,4 @@
-const decimal = new Intl.NumberFormat("en-US", {
-  useGrouping: false,
-  maximumFractionDigits: 15,
-});
-
-export function parseDecimal(raw: string): number | undefined {
-  const text = raw.trim();
-  if (!text) return undefined;
-  // Grouping is forbidden: a single comma always means the decimal separator.
-  return /^[+-]?(?:\d+(?:[.,]\d*)?|[.,]\d+)$/.test(text)
-    ? Number(text.replace(",", ".")) : NaN;
-}
+import { formatNumber, parseNumber } from "forma-extension-kit";
 
 export function numberInput(id: string, label: string, initial: number) {
   const field = document.createElement("div");
@@ -21,18 +10,18 @@ export function numberInput(id: string, label: string, initial: number) {
   input.id = id;
   input.type = "text";
   input.inputMode = "decimal";
-  input.value = decimal.format(initial);
+  input.value = formatNumber(initial);
   input.setAttribute("aria-describedby", "number-help");
   const validate = () => {
-    const value = parseDecimal(input.value);
-    const valid = value !== undefined && Number.isFinite(value) && value >= 0;
+    const value = parseNumber(input.value);
+    const valid = value !== null && value >= 0;
     input.setCustomValidity(valid ? "" : "Enter a non-negative number with . or , and no grouping separators.");
     input.setAttribute("aria-invalid", String(!valid));
     return valid;
   };
   input.addEventListener("input", validate);
   input.addEventListener("change", () => {
-    if (validate()) input.value = decimal.format(parseDecimal(input.value)!);
+    if (validate()) input.value = formatNumber(parseNumber(input.value)!);
     else input.reportValidity();
   });
   field.append(caption, input);

package/template/src/forma.ts

@@ -1,211 +0,0 @@
-import { Forma } from "forma-embedded-view-sdk/auto";
-
-type Tree = Awaited<ReturnType<typeof Forma.elements.get>>;
-type RootUrn = Awaited<ReturnType<typeof Forma.proposal.getRootUrn>>;
-export type BuildingKind = "existing" | "proposal";
-export type Point = [number, number];
-export type Polygon = Point[][];
-export interface ProposalSnapshot {
-  rootUrn: string;
-  proposalId: string;
-  name: string;
-  buildingPaths: string[];
-  siteLimitPaths: string[];
-  buildings: { path: string; kind: BuildingKind }[];
-}
-export interface Footprint {
-  // Set union of polygons (outer ring, then holes); parts may overlap, so never sum their areas.
-  operation: "union";
-  parts: Polygon[];
-  source: "graphBuilding" | "grossFloorAreaPolygons" | "footprint" | "children" | "triangles";
-}
-export interface FootprintResult {
-  footprint: Footprint | null;
-  attempts: { provider: string; error?: string }[];
-}
-
-export function buildingClassifier(tree: Tree) {
-  const root = tree.element;
-  const elements: Tree["elements"] = { ...tree.elements, [root.urn]: root };
-  const pending = new Map<string, Promise<void>>();
-  return async (path: string): Promise<BuildingKind> => {
-    const keys = path.split("/").slice(1, -1);
-    const base = /:group:[^:]+:base:/;
-    // The building's own basic/basicbuilding URN does not identify its source.
-    if (base.test(root.urn) || keys.some(key => root.properties?.flags?.[key]?.base === true)) return "existing";
-    let parent = root;
-    for (const key of keys) {
-      const child = parent.children?.find(item => item.key === key);
-      if (!child) throw new Error(`Cannot resolve building ancestry: ${path}`);
-      if (base.test(child.urn)) return "existing";
-      if (!elements[child.urn]) {
-        if (!pending.has(child.urn)) pending.set(child.urn, Forma.elements.get({ urn: child.urn }).then(fetched => {
-          Object.assign(elements, fetched.elements, { [fetched.element.urn]: fetched.element });
-        }));
-        await pending.get(child.urn);
-      }
-      parent = elements[child.urn];
-    }
-    return "proposal";
-  };
-}
-
-async function assertRevision(rootUrn: string, proposalId: string) {
-  const [root, id] = await Promise.all([Forma.proposal.getRootUrn(), Forma.proposal.getId()]);
-  if (root !== rootUrn || id !== proposalId) throw new Error("Proposal changed while reading; refresh");
-}
-
-export async function readProposal(): Promise<ProposalSnapshot> {
-  // These proposal calls are verified in 0.96.0; that SDK deprecates them in favour of UDM.
-  await Forma.proposal.awaitProposalPersisted();
-  const [rootUrn, proposalId] = await Promise.all([Forma.proposal.getRootUrn(), Forma.proposal.getId()]);
-  const [tree, paths, sitePaths] = await Promise.all([
-    Forma.elements.get({ urn: rootUrn }),
-    Forma.geometry.getPathsByCategory({ category: "building", urn: rootUrn }),
-    Forma.geometry.getPathsByCategory({ category: "site_limit", urn: rootUrn }),
-  ]);
-  const unique = [...new Set(paths)];
-  // Nested category-building paths are parts of a counted parent, not additional buildings.
-  const buildingPaths = unique.filter(path => !unique.some(parent => path.startsWith(`${parent}/`)));
-  const classify = buildingClassifier(tree);
-  const buildings = await Promise.all(buildingPaths.map(async path => ({ path, kind: await classify(path) })));
-  await assertRevision(rootUrn, proposalId);
-  return {
-    rootUrn, proposalId, buildingPaths, buildings,
-    siteLimitPaths: [...new Set(sitePaths)],
-    name: typeof tree.element.properties?.name === "string" ? tree.element.properties.name : proposalId,
-  };
-}
-
-function ring(points: readonly (readonly number[])[]): Point[] {
-  const result = points.map(([x, y]): Point => {
-    if (!Number.isFinite(x) || !Number.isFinite(y)) throw new Error("Non-finite footprint coordinate");
-    return [x, y];
-  });
-  if (result.length > 1 && result[0][0] === result.at(-1)![0] && result[0][1] === result.at(-1)![1]) result.pop();
-  const cross = (a: Point, b: Point, c: Point) => (b[0] - a[0]) * (c[1] - a[1]) - (b[1] - a[1]) * (c[0] - a[0]);
-  const area = result.reduce((sum, point, index) => sum + cross(result[0], point, result[(index + 1) % result.length]), 0);
-  if (result.length < 3 || Math.abs(area) < 1e-8) throw new Error("Empty or degenerate footprint ring");
-  // Reject self-crossing boundaries rather than inventing a hull for invalid geometry.
-  const on = (a: Point, b: Point, p: Point) => Math.abs(cross(a, b, p)) < 1e-8 &&
-    p[0] >= Math.min(a[0], b[0]) && p[0] <= Math.max(a[0], b[0]) && p[1] >= Math.min(a[1], b[1]) && p[1] <= Math.max(a[1], b[1]);
-  for (let i = 0; i < result.length; i++) {
-    for (let j = i + 2; j < result.length; j++) {
-      if (i === 0 && j === result.length - 1) continue;
-      const a = result[i], b = result[(i + 1) % result.length], c = result[j], d = result[(j + 1) % result.length];
-      if ((cross(a, b, c) * cross(a, b, d) < 0 && cross(c, d, a) * cross(c, d, b) < 0) ||
-        on(a, b, c) || on(a, b, d) || on(c, d, a) || on(c, d, b)) throw new Error("Self-intersecting footprint ring");
-    }
-  }
-  return result;
-}
-
-export async function readFootprint(path: string, snapshot: Pick<ProposalSnapshot, "rootUrn" | "proposalId">): Promise<FootprintResult> {
-  const { rootUrn, proposalId } = snapshot;
-  await assertRevision(rootUrn, proposalId);
-  const { element } = await Forma.elements.getByPath({ path, rootUrn: rootUrn as RootUrn });
-  const attempts: FootprintResult["attempts"] = [];
-  const attempt = async (provider: string, read: () => Promise<Polygon[]>): Promise<Polygon[] | null> => {
-    try {
-      const parts = await read();
-      if (!parts.length || parts.some(polygon => !polygon.length)) throw new Error("No footprint polygons");
-      attempts.push({ provider });
-      return parts;
-    } catch (error) {
-      attempts.push({ provider, error: error instanceof Error ? error.message : String(error) });
-      return null;
-    }
-  };
-  const direct = (target: string) => attempt(`getFootprint:${target}`, async () => {
-    const value = await Forma.geometry.getFootprint({ path: target, urn: rootUrn });
-    // SDK footprint coordinates are one flat XY ring, unlike GeoJSON Polygon coordinates.
-    if (value?.type !== "Polygon") throw new Error(`getFootprint returned ${value === undefined ? "undefined" : "no Polygon"}`);
-    return [[ring(value.coordinates)]];
-  });
-  let transform: number[] | undefined;
-  const worldPolygon = async (polygon: Polygon): Promise<Polygon> => {
-    // Representations are element-local; the transform API cannot pin a root, so recheck below.
-    transform ??= (await Forma.elements.getWorldTransform({ path })).transform;
-    const t = transform;
-    if (t.length !== 16 || t.some(n => !Number.isFinite(n)) ||
-      [2, 3, 6, 7, 8, 9, 11].some(i => Math.abs(t[i]) > 1e-8) || t[10] <= 0 || Math.abs(t[15] - 1) > 1e-8) {
-      throw new Error("Invalid or tilted floor transform");
-    }
-    return polygon.map(points => ring(points.map(([x, y]) => [t[0] * x + t[4] * y + t[12], t[1] * x + t[5] * y + t[13]])));
-  };
-  const native = /:basicbuilding:/.test(element.urn);
-  let parts: Polygon[] | null = null;
-  let source: Footprint["source"] = "graphBuilding";
-  if (native || element.representations?.graphBuilding) {
-    parts = await attempt(source, async () => {
-      const graph = await Forma.elements.representations.graphBuilding({ urn: element.urn });
-      if (!graph?.data.levels.length) throw new Error("graphBuilding returned no levels");
-      const polygons: Polygon[] = [];
-      for (const level of graph.data.levels) {
-        if (!Number.isFinite(level.height) || level.height <= 0 || !level.spaces.length) throw new Error("Invalid graph level");
-        const surfaces = new Map(level.surfaces.map(surface => [surface.id, surface]));
-        // Graph points are indexed, not an ordered ring; reconstruct directed surface loops.
-        const loop = (edges: typeof level.spaces[number]["outerLoop"]): Point[] => {
-          const segments = edges.map(edge => {
-            const surface = surfaces.get(edge.surfaceId);
-            if (!surface) throw new Error("Missing graph surface");
-            return edge.directionAToB ? [surface.pointA, surface.pointB] : [surface.pointB, surface.pointA];
-          });
-          return segments.map(([start, end], i) => {
-            if (end !== segments[(i + 1) % segments.length][0] || !level.points[start]) throw new Error("Disconnected graph loop");
-            return level.points[start];
-          });
-        };
-        for (const space of level.spaces) polygons.push(await worldPolygon([loop(space.outerLoop), ...(space.innerLoops ?? []).map(loop)]));
-      }
-      return polygons;
-    });
-  }
-  if (!parts && (native || element.representations?.grossFloorAreaPolygons)) {
-    source = "grossFloorAreaPolygons";
-    parts = await attempt(source, async () => {
-      const floors = await Forma.elements.representations.grossFloorAreaPolygons({ urn: element.urn });
-      if (!floors?.data.length) throw new Error("grossFloorAreaPolygons returned no floors");
-      const polygons: Polygon[] = [];
-      for (const floor of floors.data) {
-        if (!Number.isFinite(floor.elevation)) throw new Error("Invalid floor elevation");
-        polygons.push(await worldPolygon(floor.grossFloorPolygon));
-      }
-      return polygons;
-    });
-  }
-  // Context/basic elements have readable direct footprints; authored basicbuilding often does not.
-  if (!parts && !native) { source = "footprint"; parts = await direct(path); }
-  if (!parts && element.children?.length) {
-    source = "children";
-    parts = await attempt(source, async () => {
-      const polygons: Polygon[] = [];
-      let complete = true;
-      for (const child of element.children!) {
-        // Child keys are path segments; a partial set must never look like a complete footprint.
-        const childParts = await direct(`${path}/${child.key}`);
-        if (childParts) polygons.push(...childParts); else complete = false;
-      }
-      if (!complete) throw new Error("Some child footprints are unavailable");
-      return polygons;
-    });
-  }
-  if (!parts) {
-    source = "triangles";
-    parts = await attempt(source, async () => {
-      const vertices = await Forma.geometry.getTriangles({ path, urn: rootUrn });
-      if (!vertices.length || vertices.length % 9 || vertices.some(n => !Number.isFinite(n))) throw new Error("Invalid or empty triangle array");
-      const polygons: Polygon[] = [];
-      for (let i = 0; i < vertices.length; i += 9) {
-        const a: Point = [vertices[i], vertices[i + 1]], b: Point = [vertices[i + 3], vertices[i + 4]], c: Point = [vertices[i + 6], vertices[i + 7]];
-        // Vertical faces have zero XY area; retain all other parts, including disconnected ones.
-        if (Math.abs((b[0] - a[0]) * (c[1] - a[1]) - (b[1] - a[1]) * (c[0] - a[0])) >= 1e-8) polygons.push([[a, b, c]]);
-      }
-      return polygons;
-    });
-  }
-  // Preserve a readable native footprint if every preferred provider failed.
-  if (!parts && native) { source = "footprint"; parts = await direct(path); }
-  await assertRevision(rootUrn, proposalId);
-  return { footprint: parts ? { operation: "union", parts, source } : null, attempts };
-}