Integrate

Plain HTML

Astro 없이, 어떤 페이지나 프레임워크에서도 사용할 수 있는 comic-strip 커스텀 엘리먼트입니다.

@toonstrip/element는 프레임워크 의존성이 없는 커스텀 엘리먼트입니다. Astro 컴포넌트는 이를 감싼 얇은 래퍼일 뿐이며, 그것이 하는 모든 일을 이 엘리먼트가 자체적으로 해냅니다.

설치

npm install @toonstrip/element @toonstrip/pack-comic-chat

팩의 파일들을 브라우저가 가져올 수 있는 곳에 서빙하시기 바랍니다. 팩 패키지에는 pack.json, characters/, backdrops/가 들어 있으므로, 이 디렉터리를 정적 에셋 경로로 복사합니다. 예를 들어 public/packs/comic-chat/ 같은 위치입니다.

사용

<comic-strip id="strip"></comic-strip>

<script type="module">
  import "@toonstrip/element";

  const strip = document.getElementById("strip");
  strip.packs = ["/packs/comic-chat/"];
  strip.document = {
    version: 1,
    panels: [
      {
        backdrop: "pastoral",
        camera: "establishing",
        bodies: [{ character: "dan", emotion: { angle: 0, intensity: 0.6 } }],
        speakers: [{ speaker: "caption", balloon: "caption", text: "A field outside town." }],
      },
    ],
  };
</script>

API

packs보다 document를 먼저 설정해도 문제없습니다. 어느 쪽이 바뀌든 엘리먼트는 다시 빌드되며, 마지막에 설정한 값이 적용됩니다.

프레임워크에서 사용하기

React, Vue, Svelte를 비롯한 대부분의 프레임워크는 커스텀 엘리먼트를 렌더링하고 그 위에 프로퍼티를 설정할 수 있습니다. 기억해야 할 한 가지는 packs와 document가 프로퍼티이지 속성(attribute)이 아니라는 점입니다. 마운트 후 ref를 통해 설정하거나, 각 프레임워크의 프로퍼티 바인딩 문법을 사용하시기 바랍니다(Lit에서는 .document={doc}, Solid에서는 prop:document={doc}, Vue에서는 :document.prop). React와 Vue의 경우 @toonstrip/react와 @toonstrip/vue가 이 패턴을 정확히 <ComicStrip> 컴포넌트로 패키징해 제공합니다. React 레퍼런스와 Vue 레퍼런스를 참고하시기 바랍니다.

번들링

이 엘리먼트는 @toonstrip/core와 @toonstrip/schema를 임포트하며, 어떤 ESM 번들러로도 문제없이 처리됩니다. 스키마는 빌드 시점에 평범한 데이터로 임베드되고, 검증도 eval 없이 일반 JS로 실행되므로, 엄격한 콘텐츠 보안 정책(CSP)에서도 unsafe-eval이 필요하지 않습니다.

빌드 단계 자체를 두지 않는 경우

위의 install/npm/번들러 단계는 무언가가 import "@toonstrip/element"라는 베어 지정자를 리졸브해 준다는 전제 위에 있습니다. 번들러도 import map도 없다면 대신 패키지 자체의 의존성까지 리졸브해 주는 esm.sh를 사용하시기 바랍니다.

<script type="module">
  import "https://esm.sh/@toonstrip/[email protected]";
</script>

packs도 CDN을 가리키게 할 수 있습니다. unpkg는 팩의 정적 파일들(pack.json, 스프라이트 시트, 배경)을 CORS를 활성화한 채로 그대로 서빙합니다.

strip.packs = ["https://unpkg.com/@toonstrip/[email protected]/"];

전체 예제는 레포의 examples/vanilla-html/index.html입니다. 파일 하나뿐이고 package.json도 없으며, file://나 어떤 정적 파일 서버에서도 바로 열립니다. 다른 의존성과 마찬가지로 두 URL 모두 정확한 버전을 고정하시기 바랍니다. esm.sh와 unpkg 중 어느 쪽을 언제 쓸지에 대한 전체 논의는 레포의 docs/vanilla-html.md를 참고하시기 바랍니다.