API 레퍼런스

Disintegrator는 하나의 완전한 시각 설정, 선택적 오디오, 캡처, 레이아웃 애니메이션, 백그라운드 준비와 보관 노드 저장소를 연결합니다.

엔트리 포인트

루트 및 /snapdom 엔트리는 완성된 내장 프리셋 네 개를 등록합니다. /snapdom만 캡처 어댑터를 제공하며, /core는 내장 프리셋, 파티클, 내장 사운드 파일과 캡처 없이 수명 주기만 제공합니다. 어떤 엔트리도 기본 프리셋을 선택하지 않습니다. 파티클, 캡처, 오디오 페이지에서 각 전용 export를 자세히 설명합니다.

생성자

import Disintegrator, { createParticleEffect } from 'vanilla-disintegrate/snapdom';

const ready = new Disintegrator({ preset: 'dust' });
const custom = new Disintegrator({ effect: createParticleEffect() });

preset과 effect 중 정확히 하나가 필요합니다.

type DisintegratorOptions =
  | { preset: PresetSelection; effect?: never; sound?: false; fallback?: FallbackEffectDefinition }
  | { preset?: never; effect: EffectDefinition; sound?: false | SoundSelection; fallback?: FallbackEffectDefinition };

프리셋은 시각 효과와 오디오를 합친 원자적 선택입니다. sound: false로 음소거할 수 있지만 다른 시각 효과나 대체 오디오와 조합할 수 없습니다. 사용자 효과는 완전한 remove 및 restore 단계를 가진 객체이며 사운드 쌍을 제공하지 않으면 무음입니다.

공통 옵션:

¹ SnapDOM은 /snapdom에서만 기본값입니다. 선택한 효과에 스냅샷이 필요하면 루트 및 /core 엔트리에 capture를 제공해야 합니다.

백그라운드 스냅샷 오류는 context.operation === 'prepare'를, 작업 오류는 remove 또는 restore를 보고합니다.

LayoutOptions

레이아웃 애니메이션은 FLIP 기법으로 삭제 후 영향을 받은 요소를 이전 위치에서 새 위치로 이동합니다.

layout: false를 전달하면 리플로 애니메이션이 비활성화됩니다. layout은 remove()에만 적용됩니다. 복원 시 삽입된 요소는 최종 레이아웃 위치에서 애니메이션됩니다. 음수 duration은 0으로, 유한하지 않은 값은 기본값으로 정규화됩니다.

PreparationOptions

preparation: false는 자동 준비를 비활성화하지만 명시적 prepare() 호출은 막지 않습니다. 음수인 시간과 캐시 예산은 0으로, 유한하지 않은 값은 각 기본값으로 정규화됩니다.

AudioPreparationOptions

audioPreparation: false는 자동 작업을 비활성화합니다. 명시적 오디오 준비는 계속 사용할 수 있습니다. 음수 캐시 예산은 0으로 정규화됩니다.

완성된 프리셋

import Disintegrator, { createParticleEffect, definePreset } from 'vanilla-disintegrate/snapdom';

const dissolve = definePreset({
  effect: createParticleEffect({
    remove: { curve: 'float' },
    restore: { curve: 'settle' },
  }),
  sound: {
    remove: { src: '/audio/out.ogg', volume: 0.4 },
    restore: { src: '/audio/in.ogg', volume: 0.4 },
  },
});

const effects = new Disintegrator({
  preset: 'dissolve',
  presets: { dissolve },
});

definePreset()은 프리셋, 시각 단계와 네이티브 사운드 옵션 객체를 동결하지만 호출자가 소유한 바이너리 오디오 데이터는 동결하지 않습니다.

const builtInPresets: Readonly<Record<'dust' | 'scatter' | 'vapor' | 'wind', Readonly<PresetDefinition>>>;

builtInPresets는 루트와 /snapdom 엔트리에서 내보냅니다. 각 값은 파티클과 오디오를 합친 완전하고 동결된 프리셋입니다. /particles 엔트리는 시각 설정만 포함한 particlePresets를 대신 내보냅니다.

사용자 효과 계약

import { defineEffect } from 'vanilla-disintegrate/core';

interface EffectPhase {
  requires?: 'webgl2';
  needsSnapshot?: boolean;
  animate: AnimationFactory;
}

interface EffectDefinition {
  remove: EffectPhase;
  restore: EffectPhase;
}

const effect = defineEffect({
  remove: { needsSnapshot: false, animate: removeFactory },
  restore: { needsSnapshot: false, animate: restoreFactory },
});

needsSnapshot의 기본값은 true입니다. defineEffect()는 효과와 두 단계 객체를 동결하면서 TypeScript가 추론한 좁은 타입을 보존합니다.

WebGL2 폴백 효과

createParticleEffect()와 내장 프리셋은 단계에 requires: 'webgl2'를 자동으로 표시합니다. 라이브러리는 캡처 전에 WebGL2를 확인합니다. WebGL2가 꺼져 있거나 사용할 수 없으면 fallback이 기본 단계를 대신 실행하므로 불필요한 Canvas 스냅샷을 만들지 않습니다.

import Disintegrator, { defineEffect } from 'vanilla-disintegrate/snapdom';

const fade = defineEffect({
  remove: {
    needsSnapshot: false,
    animate: ({ element }) => element.animate([{ opacity: 1 }, { opacity: 0 }], { duration: 180 }),
  },
  restore: {
    needsSnapshot: false,
    animate: ({ element }) => element.animate([{ opacity: 0 }, { opacity: 1 }], { duration: 180 }),
  },
});

const effects = new Disintegrator({ preset: 'dust', fallback: fade });

폴백은 프리셋뿐 아니라 requires: 'webgl2'를 선언한 모든 사용자 효과에도 적용됩니다. CSS, WAAPI, Canvas 2D, SVG 또는 다른 렌더러를 사용할 수 있으며 기본적으로 무음입니다. TypeScript는 fallback에 또 다른 WebGL2 단계를 전달하지 못하게 하고, JavaScript 구성에도 런타임에서 같은 검증을 적용합니다. 사전 확인 뒤에도 파티클 렌더러가 시작하지 못하면 라이브러리는 이미 만든 스냅샷 뒤에 폴백을 시도합니다.

애니메이션 팩토리는 AnimationContext를 받습니다.

AnimationFactory는 Web Animation, 임의의 PromiseLike, AnimationPlayback 컨트롤러를 반환하거나 애니메이션을 만들 수 없을 때 null을 반환할 수 있습니다.

interface AnimationPlayback {
  finished: PromiseLike<unknown>;
  element?: HTMLElement;
  duration?: number;
  layoutDelay?: number;
  cancel?(): void;
  dispose?(): void;
}

element에 아직 부모가 없다면 layer에 추가됩니다. duration은 네이티브 오디오를 맞추고, layoutDelay는 삭제 리플로를 지연하며, cancel()은 재생을 멈추고, dispose()는 모든 종료 경로에서 렌더러 리소스를 해제합니다.

remove(target, options?)

해석된 요소를 분리하고 EffectOperation을 동기적으로 반환합니다.

remove(target: EffectTarget, options?: RemoveOptions): EffectOperation;

const operation = effects.remove('.card', {
  preset: 'scatter',
  sound: false,
  retain: true,
  layout: { duration: 260 },
  detach: (element) => element.remove(),
});

target은 HTMLElement 또는 선택자 문자열입니다. 선택자를 찾지 못하면 작업 시작 전에 오류를 던집니다.

detach는 기본 element.remove() 커밋을 대체합니다. 반응형 렌더러가 자체 상태로 노드를 제거해야 할 때 사용하세요. 콜백이 오류를 던지면 onError로 전달하고 네이티브 제거를 안전한 폴백으로 사용합니다.

restore(target, options?)

연결되고 측정 가능한 요소를 현재 지오메트리에서 애니메이션합니다.

restore(target: EffectTarget, options?: RestoreOptions): EffectOperation;

const operation = effects.restore(element, {
  preset: 'scatter',
  sound: false,
});

요소가 분리됐거나 너비 또는 높이가 0이면 오류를 던집니다.

두 작업 모두 하나의 완성된 preset, 해당 단계의 선택적 사운드 정의와 함께 사용자 effect, 또는 아무것도 전달하지 않아 인스턴스나 보관 노드의 표현을 상속할 수 있습니다. 상속 오디오와 프리셋 오디오는 sound: false로만 음소거할 수 있습니다.

작업 옵션

작업 콜백은 인스턴스 콜백과 함께 추가로 실행됩니다. preset과 effect를 모두 생략하면 표현을 상속합니다. 상속된 사운드와 프리셋 사운드는 음소거할 수 있지만 독립적으로 교체할 수 없습니다.

보관 요소

const element = effects.take(removalId); // HTMLElement | null
const discarded = effects.discard(removalId); // boolean
const count = effects.discardAll(); // number

take()은 저장 항목을 소비합니다. discard()와 discardAll()은 콘텐츠를 삽입하지 않고 참조를 해제합니다.

스냅샷 준비

const unregister = effects.register(elements);
await effects.prepare(elements);
effects.invalidate(elements);
effects.clearPrepared();

invalidate()는 context.invalidate를 통해 준비된 canvas와 캡처 엔진을 함께 갱신합니다. 명시적인 prepare()도 갱신을 요청하며 clearPrepared() 후 다음 캡처는 새로 갱신해야 합니다. DOM 관찰자가 감지할 수 없는 CSSOM 변경도 포함됩니다. 자체 캐시가 있는 사용자 정의 어댑터는 context.invalidate를 처리해야 합니다.

register()는 설정된 전략을 따릅니다. 백그라운드 준비가 꺼져 있어도 prepare()는 즉시 캡처합니다. 같은 요소의 반복 등록은 참조 카운트를 사용하며 각 해제 함수는 자신의 등록만 해제합니다.

register()는 멱등인 () => void를 반환하고, prepare()는 Promise<void>를 반환하며, invalidate()와 clearPrepared()는 void를 반환합니다.

오디오 준비

await effects.prepareAudio({
  remove: { src: 'dust' },
  restore: { src: 'dust', reverse: true },
});
effects.discardPreparedAudio();
effects.clearPreparedAudio();

인수가 없으면 prepareAudio()와 discardPreparedAudio()는 인스턴스에 설정한 사운드 쌍을 사용합니다. 자동 준비가 꺼져 있어도 명시적 메서드는 동작합니다. 디코딩 버퍼는 제한된 인스턴스 소유권 LRU를 사용하고 요청, 버퍼와 AudioContext는 인스턴스 간 공유합니다.

prepareAudio()는 Promise<void>를 반환하고, discardPreparedAudio()는 해제한 인스턴스 소유 디코딩 항목 수를 반환하며, clearPreparedAudio()는 void를 반환합니다.

destroy()

effects.destroy();

활성 작업을 취소하고 관찰자와 백그라운드 작업을 중지하며 스냅샷과 디코딩 오디오 소유권을 해제하고 보관 노드를 비웁니다. 마지막 소유자가 파괴되면 공유 재생 컨텍스트가 닫힙니다. destroy()를 반복 호출해도 안전하며 이후 새 작업을 시작하면 오류를 던집니다.

EffectOperation

interface EffectOperation {
  readonly operation: 'remove' | 'restore';
  readonly removalId: RemovalId | null;
  readonly finished: Promise<{
    operation: 'remove' | 'restore';
    status: 'completed' | 'cancelled' | 'skipped' | 'rejected';
    removalId: RemovalId | null;
  }>;
  cancel(): void;
}

핸들은 요소를 노출하지 않고 완료된 뒤 참조를 해제합니다.

콜백과 우선순위

인스턴스 콜백은 모든 작업에 실행되고 작업 콜백은 그와 함께 실행됩니다. 명시적 작업 표현, 보관 노드가 기억한 표현, 인스턴스 설정 순서로 우선합니다. 이미 사용 중인 요소에 대한 동시 호출은 현재 소유자가 끝난 뒤 rejected로 완료됩니다.

interface EffectContext {
  operation: 'remove' | 'restore';
  element: HTMLElement;
  overlay: HTMLElement | null;
  removalId: RemovalId | null;
}

interface EffectErrorContext {
  operation: 'remove' | 'restore' | 'prepare';
  element: HTMLElement;
  overlay: HTMLElement | null;
  removalId: RemovalId | null;
}

onTrigger는 검증과 측정 뒤, 캡처 및 DOM 커밋 전에 실행되며 이때 overlay는 null입니다. onStart는 콘텐츠 작업이 커밋되고 시각 재생이 시작된 뒤 실행됩니다. onComplete는 시각 효과와 레이아웃이 정상적으로 완료된 경우에만 실행됩니다. onError는 준비, 캡처, 애니메이션, 오디오, 정리 및 애플리케이션 콜백 오류를 받으며, 이러한 오류가 필요한 DOM 작업이나 정리를 중단하지 못하게 합니다.