@kokoa/clotho-editor 0.1.1 → 0.1.4

package/README.md

@@ -1,53 +1,106 @@
 # @kokoa/clotho-editor
 
-[clotho](../clotho) 애니메이션 문서를 위한 비주얼 에디터.
+`@kokoa/clotho-editor`는 [Clotho](https://github.com/shinkeonkim/clotho) 애니메이션 문서를 만드는 React 기반 시각 편집기입니다. 저장소, 이미지 업로드, 예제 목록과 저장 동작을 host application에서 주입할 수 있으므로 독립형 편집기와 기존 관리 화면에서 같은 package를 사용할 수 있습니다.
 
-## 상태
+실제 화면은 [Clotho Editor](https://clotho-editor.shinkeonkim.com/)에서 확인할 수 있습니다.
 
-두 블로그 저장소 안에 있던 Studio(약 8,900 LOC)를 clotho
-기반 독립 패키지로 옮겼다. typecheck 0 errors, 빌드·테스트 통과.
-
-이식에서 가장 의미 있는 변화는 **미리보기가 clotho를 쓴다**는 점이다. Studio는 자체
-캔버스 렌더를 갖고 있어 에디터에서 맞게 보이는 것이 사이트에서 다르게 보일 수 있었다.
-이제 `buildScene` + `patchScene`을 지나므로 에디터와 배포본이 갈라질 수 없다.
-
-자세한 내용과 남은 정리 항목은 [`docs/PORTING.md`](./docs/PORTING.md).
-
-## 사용
+## 설치
 
 ```bash
 npm install @kokoa/clotho @kokoa/clotho-editor react react-dom
-# yarn add / pnpm add / bun add 도 같은 패키지 목록을 사용한다.
 ```
 
 ```tsx
-import { Studio, configureApi, configureHost } from "@kokoa/clotho-editor";
+import { StudioMount, createLocalStorageRepository } from "@kokoa/clotho-editor";
+import "@kokoa/clotho/styles.css";
 import "@kokoa/clotho-editor/styles.css";
 
-// 문서가 어디 저장되는지는 호스트가 정한다. 기본값은 원래 Studio가 쓰던 경로다.
-configureApi({ baseUrl: "/api/admin/animations" });
-configureHost({ placeholderImageUrl: "/uploads/placeholder.png" });
+const repository = createLocalStorageRepository({
+  storageKey: "my-app.animations",
+  examples,
+});
 
-<Studio initial={doc} onSave={handleSave} />;
+export function AnimationEditor() {
+  return <StudioMount editorTitle="Clotho Editor" repository={repository} />;
+}
 ```
 
-`Studio`는 저장 방식을 호스트가 소유하는 삽입형 컴포넌트다. 기존 API 경로를 그대로 쓰는
-완성형 화면이 필요하면 `<StudioMount initialId="document-id" />`를 사용한다. 일반적인
-Vite/Next.js/React SPA에 둘 다 삽입할 수 있고, 브라우저 전용 코드는 mount 이후에
-초기화된다.
+`StudioMount`는 목록 조회, 새 문서 생성, 저장, 삭제와 JSON 내보내기를 포함한 편집기 화면입니다. 편집기 shell을 application이 직접 구성해야 한다면 `Studio`를 사용할 수 있습니다.
 
-## 개발
+## 저장소 연결
+
+편집기는 특정 backend에 의존하지 않습니다. `AnimationRepository`를 구현하면 REST API, browser storage, Git 기반 저장소 등 원하는 데이터 계층을 연결할 수 있습니다.
+
+```ts
+import type { AnimationRepository } from "@kokoa/clotho-editor";
+
+const repository: AnimationRepository = {
+  list: async () => api.list(),
+  load: async (id) => api.load(id),
+  create: async (id, title) => api.create(id, title),
+  save: async (document) => api.save(document),
+  delete: async (id) => api.delete(id),
+};
+```
+
+간단한 demo나 offline 편집기는 `createLocalStorageRepository`를 사용하면 됩니다. 기존 HTTP API를 사용하는 application은 `configureApi({ baseUrl })`로 기본 adapter를 설정할 수도 있습니다.
+
+## Host hooks
+
+상단 제목과 이미지 처리 방식은 실행 환경에서 정할 수 있습니다. `resolveImage`를 지정하지 않으면 이미지를 data URL로 변환해 문서의 `assets`에 저장합니다. 같은 이미지는 하나의 asset을 공유하며, 사용되지 않는 asset은 JSON을 내보낼 때 제거됩니다.
+
+```tsx
+<StudioMount
+  editorTitle="블로그 애니메이션 편집기"
+  repository={repository}
+  resolveImage={async (file) => uploadToMediaServer(file)}
+/>
+```
+
+저장 버튼의 동작 자체를 바꾸려면 repository의 `create`와 `save`를 구현합니다. 예제 목록은 repository의 `list`와 `load`에서 제공하므로 editor package 안에 application별 API 경로를 넣을 필요가 없습니다.
+
+## 주요 기능
+
+- Clotho v1 JSON 문서 작성과 검증
+- 사각형, 원, 선, 화살표, 텍스트, 이미지, Path, 다각형과 그룹 편집
+- anchor를 유지하는 선 연결과 다중 선택
+- keyframe, effect, chapter와 재생 설정 편집
+- light/dark theme와 단계 목록 위치 설정
+- 별도 브라우저 창으로 분리할 수 있는 timeline
+- 실제 `@kokoa/clotho/dom` player를 사용하는 독립 미리보기
+- JSON 가져오기와 내보내기, 참조되지 않는 image asset 정리
+
+도구 단축키는 편집기 안에서 확인할 수 있으며 input, textarea와 contenteditable에 입력하는 동안에는 동작하지 않습니다.
+
+## 독립 실행형 앱
+
+저장소의 `app`은 package 통합 예제이자 Cloudflare Workers Static Assets용 demo입니다.
 
 ```bash
 bun install
+bun run app:dev
+bun run build:app
+bun run dev:cloudflare
+```
+
+Cloudflare Dashboard에서는 Build command를 `bun run build:app`, Deploy command를 `npx wrangler deploy`로 지정합니다. custom domain은 Dashboard에서 별도로 연결합니다.
+
+## 개발
+
+```bash
+bun install --frozen-lockfile
 bun run typecheck
 bun test
 bun run build
 ```
 
-개발 시에는 devDependency가 이웃 `../clotho`를 가리킨다. 배포물에는 이 경로가 포함되지
-않고 `^0.1.0` peer 계약만 노출된다. 배포 순서와 검증은
-[`../clotho/docs/RELEASING.md`](../clotho/docs/RELEASING.md)를 따른다.
+npm release는 GitHub Release와 [publish workflow](./.github/workflows/publish.yml)를 통해 진행합니다. `@kokoa/clotho`의 호환 버전이 먼저 공개되어 있어야 합니다.
+
+## 문서
+
+- [Clotho 저장소](https://github.com/shinkeonkim/clotho)
+- [Clotho Editor demo](https://clotho-editor.shinkeonkim.com/)
+- [Porting 기록](./docs/PORTING.md)
 
 ## 라이선스
 

package/dist/{chunk-UE32Q6U5.js → chunk-GMGB7NIL.js}

@@ -1,6 +1,163 @@
-import { computeSnapshot, encodeImageAsset, inlineAssetFromDataUri, animationDocumentSchema } from '@kokoa/clotho';
+import { animationDocumentSchema, computeSnapshot, encodeImageAsset, inlineAssetFromDataUri } from '@kokoa/clotho';
 
-// src/legacy/state/internals.ts
+// src/export-json.ts
+function animationDocumentToJson(def) {
+  const parsed = garbageCollectAnimationAssets(def);
+  return `${JSON.stringify(parsed, null, 2)}
+`;
+}
+function garbageCollectAnimationAssets(def) {
+  const parsed = animationDocumentSchema.parse(def);
+  const used = new Set(
+    parsed.elements.filter((element) => element.type === "image").map((element) => element.assetId)
+  );
+  return animationDocumentSchema.parse({
+    ...parsed,
+    assets: Object.fromEntries(
+      Object.entries(parsed.assets).filter(([id]) => used.has(id))
+    )
+  });
+}
+function animationDocumentFileName(def) {
+  const id = def.id.trim().replace(/[^a-zA-Z0-9._-]+/g, "-");
+  return `${id || "animation"}.json`;
+}
+function downloadAnimationJson(def) {
+  if (typeof document === "undefined" || typeof URL.createObjectURL !== "function") {
+    throw new Error("JSON \uD30C\uC77C\uC740 \uBE0C\uB77C\uC6B0\uC800\uC5D0\uC11C\uB9CC \uB0B4\uB824\uBC1B\uC744 \uC218 \uC788\uC2B5\uB2C8\uB2E4.");
+  }
+  const url = URL.createObjectURL(
+    new Blob([animationDocumentToJson(def)], {
+      type: "application/json;charset=utf-8"
+    })
+  );
+  const link = document.createElement("a");
+  link.href = url;
+  link.download = animationDocumentFileName(def);
+  link.hidden = true;
+  document.body.append(link);
+  link.click();
+  link.remove();
+  URL.revokeObjectURL(url);
+}
+var DEFAULT_BASE = "/api/admin/animations";
+var BASE = DEFAULT_BASE;
+function configureApi(options) {
+  if (options.baseUrl) BASE = options.baseUrl.replace(/\/+$/, "");
+  repository = httpRepository;
+}
+function apiBaseUrl() {
+  return BASE;
+}
+var revisions = /* @__PURE__ */ new Map();
+var MissingAnimationRevisionError = class extends Error {
+};
+var AnimationStudioApiError = class extends Error {
+};
+function isRecord(value) {
+  return typeof value === "object" && value !== null;
+}
+async function readJson(res) {
+  if (!res.ok) {
+    const text = await res.text();
+    throw new AnimationStudioApiError(`HTTP ${res.status}: ${text}`);
+  }
+  return res.json();
+}
+function parseRevision(value) {
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 1) {
+    throw new TypeError("Animation revision is malformed");
+  }
+  return value;
+}
+function parseAnimationEnvelope(value) {
+  if (!isRecord(value)) throw new TypeError("Animation response is malformed");
+  return {
+    def: animationDocumentSchema.parse(value.def),
+    revision: parseRevision(value.revision)
+  };
+}
+var httpRepository = {
+  list: async () => {
+    const res = await fetch(BASE);
+    const data = await readJson(res);
+    if (!isRecord(data) || !Array.isArray(data.items))
+      throw new TypeError("Animation list response is malformed");
+    return data.items.map((item) => {
+      if (!isRecord(item) || typeof item.id !== "string" || typeof item.title !== "string" || typeof item.description !== "string") {
+        throw new TypeError("Animation summary is malformed");
+      }
+      return {
+        id: item.id,
+        title: item.title,
+        description: item.description,
+        ...typeof item.updatedAt === "string" ? { updatedAt: item.updatedAt } : {}
+      };
+    });
+  },
+  load: async (id) => {
+    const res = await fetch(`${BASE}/${encodeURIComponent(id)}`);
+    const data = parseAnimationEnvelope(await readJson(res));
+    revisions.set(data.def.id, data.revision);
+    return data.def;
+  },
+  save: async (def) => {
+    const revision = revisions.get(def.id);
+    if (revision === void 0)
+      throw new MissingAnimationRevisionError(
+        `Animation '${def.id}' has no loaded revision`
+      );
+    const res = await fetch(`${BASE}/${encodeURIComponent(def.id)}`, {
+      method: "PUT",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ def, revision })
+    });
+    const data = parseAnimationEnvelope(await readJson(res));
+    revisions.set(data.def.id, data.revision);
+    return data.def;
+  },
+  create: async (id, title) => {
+    const res = await fetch(BASE, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ id, title })
+    });
+    const data = parseAnimationEnvelope(await readJson(res));
+    revisions.set(data.def.id, data.revision);
+    return data.def;
+  },
+  delete: async (id) => {
+    const res = await fetch(`${BASE}/${encodeURIComponent(id)}`, {
+      method: "DELETE"
+    });
+    await readJson(res);
+    revisions.delete(id);
+  }
+};
+var repository = httpRepository;
+function configureAnimationRepository(next) {
+  repository = next;
+}
+var listAnimations = () => repository.list();
+var loadAnimation = (id) => repository.load(id);
+var saveAnimation = (def) => repository.save(def);
+var createAnimation = (id, title) => repository.create(id, title);
+var deleteAnimation = (id) => repository.delete(id);
+async function importAnimation(def) {
+  const parsed = animationDocumentSchema.parse(def);
+  try {
+    await repository.load(parsed.id);
+  } catch {
+    await repository.create(parsed.id, parsed.title || parsed.id);
+  }
+  return repository.save(parsed);
+}
+async function duplicateAnimation(sourceId, newId, newTitle) {
+  const source = await loadAnimation(sourceId);
+  const cloned = { ...source, id: newId, title: newTitle };
+  await createAnimation(newId, newTitle);
+  return await saveAnimation(cloned);
+}
 var listeners = /* @__PURE__ */ new Set();
 var state = {
   def: null,
@@ -44,7 +201,19 @@ function mutateDef(fn, label = "edit", kind = "other") {
     console.warn("[studio.state] invalid mutation", parsed.error.issues);
     return;
   }
-  state.def = parsed.data;
+  const localized = cloned;
+  const next = parsed.data;
+  if (localized.locales) next.locales = localized.locales;
+  next.elements = next.elements.map((element, index) => {
+    const source = localized.elements[index];
+    if (source?.id !== element.id || element.type !== "text") return element;
+    return {
+      ...element,
+      ...source.locales ? { locales: source.locales } : {},
+      ...source.translations ? { translations: source.translations } : {}
+    };
+  });
+  state.def = next;
   state.dirty = true;
   emit();
 }
@@ -548,6 +717,15 @@ function updateMeta(patch) {
     "meta"
   );
 }
+function updateLocales(locales) {
+  mutateDef(
+    (def) => {
+      def.locales = locales;
+    },
+    "\uBB38\uC11C \uC5B8\uC5B4 \uBCC0\uACBD",
+    "meta"
+  );
+}
 function updateCanvas(patch) {
   const keys = Object.keys(patch).join(", ");
   mutateDef(
@@ -608,6 +786,13 @@ function registerExternalAsset(url) {
 }
 function registerInlineAsset(bytes, mime) {
   const { asset } = encodeImageAsset(bytes, mime);
+  const def = getDef();
+  if (def) {
+    for (const [id2, existing] of Object.entries(def.assets)) {
+      if (existing.kind === "inline" && existing.mime === asset.mime && existing.data === asset.data)
+        return id2;
+    }
+  }
   const id = uniqueAssetId();
   mutateDef(
     (draft) => {
@@ -628,6 +813,13 @@ function uniqueAssetId() {
 function registerDataUriAsset(dataUri) {
   const inline = inlineAssetFromDataUri(dataUri);
   if (!inline) return registerExternalAsset(dataUri);
+  const def = getDef();
+  if (def) {
+    for (const [id2, existing] of Object.entries(def.assets)) {
+      if (existing.kind === "inline" && existing.mime === inline.mime && existing.data === inline.data)
+        return id2;
+    }
+  }
   const id = uniqueAssetId();
   mutateDef(
     (draft) => {
@@ -840,104 +1032,7 @@ function configureHost(options) {
 function placeholderImageUrl() {
   return placeholderUrl;
 }
-var DEFAULT_BASE = "/api/admin/animations";
-var BASE = DEFAULT_BASE;
-function configureApi(options) {
-  if (options.baseUrl) BASE = options.baseUrl.replace(/\/+$/, "");
-}
-function apiBaseUrl() {
-  return BASE;
-}
-var revisions = /* @__PURE__ */ new Map();
-var MissingAnimationRevisionError = class extends Error {
-};
-var AnimationStudioApiError = class extends Error {
-};
-function isRecord(value) {
-  return typeof value === "object" && value !== null;
-}
-async function readJson(res) {
-  if (!res.ok) {
-    const text = await res.text();
-    throw new AnimationStudioApiError(`HTTP ${res.status}: ${text}`);
-  }
-  return res.json();
-}
-function parseRevision(value) {
-  if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 1) {
-    throw new TypeError("Animation revision is malformed");
-  }
-  return value;
-}
-function parseAnimationEnvelope(value) {
-  if (!isRecord(value)) throw new TypeError("Animation response is malformed");
-  return {
-    def: animationDocumentSchema.parse(value.def),
-    revision: parseRevision(value.revision)
-  };
-}
-async function listAnimations() {
-  const res = await fetch(BASE);
-  const data = await readJson(res);
-  if (!isRecord(data) || !Array.isArray(data.items))
-    throw new TypeError("Animation list response is malformed");
-  return data.items.map((item) => {
-    if (!isRecord(item) || typeof item.id !== "string" || typeof item.title !== "string" || typeof item.description !== "string") {
-      throw new TypeError("Animation summary is malformed");
-    }
-    return {
-      id: item.id,
-      title: item.title,
-      description: item.description,
-      ...typeof item.updatedAt === "string" ? { updatedAt: item.updatedAt } : {}
-    };
-  });
-}
-async function loadAnimation(id) {
-  const res = await fetch(`${BASE}/${encodeURIComponent(id)}`);
-  const data = parseAnimationEnvelope(await readJson(res));
-  revisions.set(data.def.id, data.revision);
-  return data.def;
-}
-async function saveAnimation(def) {
-  const revision = revisions.get(def.id);
-  if (revision === void 0)
-    throw new MissingAnimationRevisionError(
-      `Animation '${def.id}' has no loaded revision`
-    );
-  const res = await fetch(`${BASE}/${encodeURIComponent(def.id)}`, {
-    method: "PUT",
-    headers: { "Content-Type": "application/json" },
-    body: JSON.stringify({ def, revision })
-  });
-  const data = parseAnimationEnvelope(await readJson(res));
-  revisions.set(data.def.id, data.revision);
-  return data.def;
-}
-async function createAnimation(id, title) {
-  const res = await fetch(BASE, {
-    method: "POST",
-    headers: { "Content-Type": "application/json" },
-    body: JSON.stringify({ id, title })
-  });
-  const data = parseAnimationEnvelope(await readJson(res));
-  revisions.set(data.def.id, data.revision);
-  return data.def;
-}
-async function deleteAnimation(id) {
-  const res = await fetch(`${BASE}/${encodeURIComponent(id)}`, {
-    method: "DELETE"
-  });
-  await readJson(res);
-  revisions.delete(id);
-}
-async function duplicateAnimation(sourceId, newId, newTitle) {
-  const source = await loadAnimation(sourceId);
-  const cloned = { ...source, id: newId, title: newTitle };
-  await createAnimation(newId, newTitle);
-  return await saveAnimation(cloned);
-}
 
-export { addAppearance, addChapter, addEffect, addElement, apiBaseUrl, beginTransient, canRedo, canUndo, childIdsOf, configureApi, configureHost, createAnimation, deleteAnimation, deleteChapter, deleteEffect, deleteElement, duplicateAnimation, endTransient, findContainingGroup, getCurrentSnapshot, getCurrentTime, getDef, getHistory, getSelectedElementIds, getSelection, groupBbox, groupElements, isDirty, isDraft, isElementSelected, isGroup, jumpBack, jumpForward, listAnimations, loadAnimation, markClean, moveElementToEnd, moveElementToFront, moveGroupBy, placeholderImageUrl, promoteDraftToSaved, redo, registerDataUriAsset, registerExternalAsset, registerInlineAsset, removeAppearance, removeTrack, removeTrackKeyframe, reorderElement, resetHistory, saveAnimation, setCurrentTime, setDef, setDraft, setElementValueAtTime, setSelection, setTrackKeyframe, subscribe, toggleSelectionFor, undo, ungroupElement, uniqueChapterId, uniqueEffectId, uniqueElementId, updateAppearance, updateCanvas, updateChapter, updateDuration, updateEffect, updateElementBase, updateMeta, updateSettings };
-//# sourceMappingURL=chunk-UE32Q6U5.js.map
-//# sourceMappingURL=chunk-UE32Q6U5.js.map
+export { addAppearance, addChapter, addEffect, addElement, animationDocumentFileName, animationDocumentToJson, apiBaseUrl, beginTransient, canRedo, canUndo, childIdsOf, configureAnimationRepository, configureApi, configureHost, createAnimation, deleteAnimation, deleteChapter, deleteEffect, deleteElement, downloadAnimationJson, duplicateAnimation, endTransient, findContainingGroup, garbageCollectAnimationAssets, getCurrentSnapshot, getCurrentTime, getDef, getHistory, getSelectedElementIds, getSelection, groupBbox, groupElements, importAnimation, isDirty, isDraft, isElementSelected, isGroup, jumpBack, jumpForward, listAnimations, loadAnimation, markClean, moveElementToEnd, moveElementToFront, moveGroupBy, placeholderImageUrl, promoteDraftToSaved, redo, registerDataUriAsset, registerExternalAsset, registerInlineAsset, removeAppearance, removeTrack, removeTrackKeyframe, reorderElement, resetHistory, saveAnimation, setCurrentTime, setDef, setDraft, setElementValueAtTime, setSelection, setTrackKeyframe, subscribe, toggleSelectionFor, undo, ungroupElement, uniqueChapterId, uniqueEffectId, uniqueElementId, updateAppearance, updateCanvas, updateChapter, updateDuration, updateEffect, updateElementBase, updateLocales, updateMeta, updateSettings };
+//# sourceMappingURL=chunk-GMGB7NIL.js.map
+//# sourceMappingURL=chunk-GMGB7NIL.js.map