@zoneflow/core 0.0.2 → 0.0.3

package/README.md

@@ -0,0 +1,133 @@
+# @zoneflow/core
+
+`@zoneflow/core`는 Zoneflow의 도메인 레이어입니다.
+
+이 패키지는 다음 역할을 담당합니다.
+
+- `UniverseModel`, `UniverseLayoutModel` 타입
+- zone / path 생성, 수정, 삭제 mutation
+- lookup / validation 유틸
+- layout 유틸
+- zoneflow 문서 import / export
+
+일반적으로 `@zoneflow/react`와 함께 사용합니다.
+
+## 설치
+
+```bash
+pnpm add @zoneflow/core
+```
+
+## 포함 기능
+
+- 모델 타입
+  - `UniverseModel`
+  - `UniverseLayoutModel`
+  - `Zone`
+  - `Path`
+- mutation
+  - `createZone`
+  - `updateZone`
+  - `removeZone`
+  - `addPath`
+  - `updatePath`
+  - `removePath`
+- layout
+  - `createUniverseLayoutModel`
+  - `createZoneLayout`
+  - `getZoneLayout`
+  - `updateZoneLayout`
+- 문서 포맷
+  - `createZoneflowDocument`
+  - `serializeZoneflowDocument`
+  - `parseZoneflowDocument`
+
+## 최소 예제
+
+```ts
+import {
+  createUniverseId,
+  createUniverseLayoutModel,
+  createZone,
+  createZoneLayout,
+  serializeZoneflowDocument,
+} from "@zoneflow/core";
+
+const universeId = createUniverseId();
+
+let model = {
+  version: "1.0.0",
+  universeId,
+  rootZoneIds: [],
+  zonesById: {},
+};
+
+let layoutModel = createUniverseLayoutModel({
+  universeId,
+  version: "1.0.0",
+});
+
+model = createZone(model, {
+  name: "Start",
+  zoneType: "action",
+  parentZoneId: null,
+});
+
+const rootZoneId = model.rootZoneIds[0];
+
+layoutModel = {
+  ...layoutModel,
+  zoneLayoutsById: {
+    ...layoutModel.zoneLayoutsById,
+    [rootZoneId]: createZoneLayout({
+      x: 120,
+      y: 100,
+      width: 220,
+      height: 140,
+    }),
+  },
+};
+
+const json = serializeZoneflowDocument({
+  model,
+  layoutModel,
+});
+```
+
+## 문서 저장 / 불러오기
+
+Zoneflow 문서 포맷은 다음 함수를 사용합니다.
+
+```ts
+import {
+  serializeZoneflowDocument,
+  parseZoneflowDocument,
+} from "@zoneflow/core";
+
+const json = serializeZoneflowDocument({
+  model,
+  layoutModel,
+});
+
+const documentBundle = parseZoneflowDocument(json);
+```
+
+문서 형식:
+
+```json
+{
+  "kind": "zoneflow/universe",
+  "formatVersion": 1,
+  "exportedAt": "2026-03-31T12:00:00.000Z",
+  "model": {},
+  "layoutModel": {}
+}
+```
+
+레거시 호환을 위해 raw `{ "model": ..., "layoutModel": ... }` 형태도 읽을 수 있습니다.
+
+## 함께 쓰는 패키지
+
+- 렌더링/에디팅 UI까지 필요하면 `@zoneflow/react`
+
+레포지토리: [github.com/groobee/zoneflow](https://github.com/groobee/zoneflow)

package/dist/document.d.ts

@@ -0,0 +1,22 @@
+import type { UniverseLayoutModel, UniverseModel } from "./types";
+export declare const ZONEFLOW_DOCUMENT_KIND = "zoneflow/universe";
+export declare const ZONEFLOW_DOCUMENT_VERSION = 1;
+export type ZoneflowDocument = {
+    kind: typeof ZONEFLOW_DOCUMENT_KIND;
+    formatVersion: typeof ZONEFLOW_DOCUMENT_VERSION;
+    exportedAt: string;
+    model: UniverseModel;
+    layoutModel: UniverseLayoutModel;
+};
+export declare function createZoneflowDocument(params: {
+    model: UniverseModel;
+    layoutModel: UniverseLayoutModel;
+    exportedAt?: string;
+}): ZoneflowDocument;
+export declare function serializeZoneflowDocument(params: {
+    model: UniverseModel;
+    layoutModel: UniverseLayoutModel;
+    exportedAt?: string;
+}, space?: number): string;
+export declare function readZoneflowDocument(input: unknown): ZoneflowDocument;
+export declare function parseZoneflowDocument(json: string): ZoneflowDocument;

package/dist/document.js

@@ -0,0 +1,83 @@
+import { validateUniverseModel } from "./validation";
+export const ZONEFLOW_DOCUMENT_KIND = "zoneflow/universe";
+export const ZONEFLOW_DOCUMENT_VERSION = 1;
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function assertUniverseShape(value, key) {
+    if (!isRecord(value)) {
+        throw new Error(`Invalid zoneflow document: "${key}" must be an object.`);
+    }
+    if (typeof value.universeId !== "string" || typeof value.version !== "string") {
+        throw new Error(`Invalid zoneflow document: "${key}" must include string "universeId" and "version".`);
+    }
+}
+function validateLayoutModel(layoutModel) {
+    const errors = [];
+    if (!isRecord(layoutModel.zoneLayoutsById)) {
+        errors.push(`layoutModel.zoneLayoutsById must be an object`);
+    }
+    if (!isRecord(layoutModel.pathLayoutsById)) {
+        errors.push(`layoutModel.pathLayoutsById must be an object`);
+    }
+    return errors;
+}
+export function createZoneflowDocument(params) {
+    return {
+        kind: ZONEFLOW_DOCUMENT_KIND,
+        formatVersion: ZONEFLOW_DOCUMENT_VERSION,
+        exportedAt: params.exportedAt ?? new Date().toISOString(),
+        model: structuredClone(params.model),
+        layoutModel: structuredClone(params.layoutModel),
+    };
+}
+export function serializeZoneflowDocument(params, space = 2) {
+    return JSON.stringify(createZoneflowDocument(params), null, space);
+}
+export function readZoneflowDocument(input) {
+    if (!isRecord(input)) {
+        throw new Error("Invalid zoneflow document: root must be an object.");
+    }
+    const isLegacyBundle = !("kind" in input) &&
+        "model" in input &&
+        "layoutModel" in input;
+    if (!isLegacyBundle) {
+        if (input.kind !== ZONEFLOW_DOCUMENT_KIND) {
+            throw new Error(`Invalid zoneflow document: "kind" must be "${ZONEFLOW_DOCUMENT_KIND}".`);
+        }
+        if (input.formatVersion !== ZONEFLOW_DOCUMENT_VERSION) {
+            throw new Error(`Unsupported zoneflow document version: "${String(input.formatVersion)}".`);
+        }
+    }
+    assertUniverseShape(input.model, "model");
+    assertUniverseShape(input.layoutModel, "layoutModel");
+    const model = structuredClone(input.model);
+    const layoutModel = structuredClone(input.layoutModel);
+    if (layoutModel.universeId !== model.universeId) {
+        throw new Error("Invalid zoneflow document: model.universeId and layoutModel.universeId must match.");
+    }
+    const modelErrors = validateUniverseModel(model);
+    const layoutErrors = validateLayoutModel(layoutModel);
+    const errors = [...modelErrors, ...layoutErrors];
+    if (errors.length > 0) {
+        throw new Error(`Invalid zoneflow document:\\n- ${errors.join("\\n- ")}`);
+    }
+    return {
+        kind: ZONEFLOW_DOCUMENT_KIND,
+        formatVersion: ZONEFLOW_DOCUMENT_VERSION,
+        exportedAt: typeof input.exportedAt === "string" ? input.exportedAt : new Date().toISOString(),
+        model,
+        layoutModel,
+    };
+}
+export function parseZoneflowDocument(json) {
+    let parsed;
+    try {
+        parsed = JSON.parse(json);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : "Unknown JSON parse error";
+        throw new Error(`Failed to parse zoneflow document JSON: ${message}`);
+    }
+    return readZoneflowDocument(parsed);
+}

package/dist/ids.d.ts

@@ -1,3 +1,4 @@
-import type { ZoneId, PathId } from "./types";
+import type { UniverseId, ZoneId, PathId } from "./types";
+export declare function createUniverseId(): UniverseId;
 export declare function createZoneId(): ZoneId;
 export declare function createPathId(): PathId;

package/dist/ids.js

@@ -1,4 +1,7 @@
 import { v7 as uuidv7 } from "uuid";
+export function createUniverseId() {
+    return `universe_${uuidv7()}`;
+}
 export function createZoneId() {
     return `zone_${uuidv7()}`;
 }

package/dist/index.d.ts

@@ -7,6 +7,7 @@ export * from "./traversal";
 export * from "./validation";
 export * from "./mutation";
 export * from "./layout";
+export * from "./document";
 export * from "./ids";
 export * from "./remap";
 export * from "./clone";

package/dist/index.js

@@ -7,6 +7,7 @@ export * from "./traversal";
 export * from "./validation";
 export * from "./mutation";
 export * from "./layout";
+export * from "./document";
 export * from "./ids";
 export * from "./remap";
 export * from "./clone";

package/package.json

@@ -1,9 +1,11 @@
 {
   "name": "@zoneflow/core",
-  "version": "0.0.2",
+  "version": "0.0.3",
+  "description": "Zoneflow core model, layout, mutation, validation, and document utilities.",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "homepage": "https://github.com/groobee/zoneflow",
   "repository": {
     "type": "git",
     "url": "https://github.com/groobee/zoneflow.git",