React Components

The AirStickerUploader component manages the entire pipeline of uploading a custom image (decal/sticker) and placing it onto a 3D canvas object. It integrates a 2D dropzone, client-side temporary media upload, and the AirTransformControls component.

The Atomic Layout Lock (No-Jump Pipeline)

Rendering a sticker in 3D before calculating its boundaries causes a momentary visual glitch/jump. AirStickerUploader resolves this with a deferred flush lock:

1. When a file is dropped, the uploader uploads it as a temporary item to window.aircadaverse.primaryRealm.mediaManager.makeTemporaryMediaItemFromBlob and holds the returned ID in pendingUploadIdRef.

2. The component mounts the image inside a hidden/under-evaluation AirTransformControls block.

3. Once the 2D transform engine calculates the correct aspect-ratio boundaries and fires the first change callback, the uploader releases the lock, firing onAtomicUploadReady(mediaId, transformData).

4. The parent application receives both the asset ID and the pristine centered coordinates at the exact same moment, performing a clean, glitch-free mount in the 3D scene.

Props Interface

export interface AircadaStickerUploaderProps {
  onAtomicUploadReady: (operatorId: string, transformData: TransformData) => void;
  onTransformUpdate: (transformData: TransformData) => void;
  onImagePreviewSelected?: (localUrl: string) => void;
  onClearImage?: () => void;
  className?: string;
  activeClassName?: string;
  dragActiveClassName?: string;
  renderPlaceholder?: (isDragActive: boolean) => React.ReactNode;
  renderControlsOverlay?: (onClear: () => void, doReplace: () => void) => React.ReactNode;
  uploadedImageUrl?: string;
  transformProps?: { x?: number, y?: number, scale?: number, rotation?: number };
  controlsConfig?: Partial<AirTransformControlsProps>;
  flipY?: boolean;
}

Example Integration Pattern

Use AirStickerUploader within a sticker editor panel to update a sticker effect on a 3D model:

import React, { useState } from "react";
import { AirStickerUploader, TransformData } from "@aircada/react";
import { useAirStore } from "@aircada/react";

export function StickerCustomizer() {
  const [store, patch] = useAirStore();
  const activeSticker = store.product.sticker;

  const handleAtomicUpload = (mediaId: string, transform: TransformData) => {
    // Commit the temporary media ID and initial clean transform to the store
    patch({
      product: {
        sticker: {
          assetId: mediaId,
          x: transform.x,
          y: transform.y,
          scale: transform.scale,
          rotation: transform.rotation
        }
      }
    });
  };

  const handleTransformUpdate = (transform: TransformData) => {
    // Continuously update transform parameters in the store as user drags
    patch({
      product: {
        sticker: {
          x: transform.x,
          y: transform.y,
          scale: transform.scale,
          rotation: transform.rotation
        }
      }
    });
  };

  return (
    <div className="p-4 bg-gray-900 rounded-2xl w-80 pointer-events-auto">
      <h3 className="text-white text-md font-semibold mb-3">Upload Artwork</h3>
      <AirStickerUploader
        onAtomicUploadReady={handleAtomicUpload}
        onTransformUpdate={handleTransformUpdate}
        uploadedImageUrl={activeSticker?.assetId}
        transformProps={{
          x: activeSticker?.x,
          y: activeSticker?.y,
          scale: activeSticker?.scale,
          rotation: activeSticker?.rotation
        }}
        className="h-32 border-2 border-dashed border-gray-700 rounded-xl flex items-center justify-center"
        activeClassName="border-solid border-blue-500"
      />
    </div>
  );
}

The AirTransformControls component is an overlay system that wraps any child element (typically an image/sticker preview) in a bounding box equipped with corner drag handles. It tracks drag (translation), corner drags (scaling), and rotational gestures to output precise coordinate offsets.

Key Capabilities

1. Dimension Observability: Uses a ResizeObserver internally to defer initialization until the target element has nonzero physical dimensions. This prevents premature layout calculations and avoids the common 0x0 cache trap.

2. State Persistence: Accepts a persistenceKey prop. When provided, the component automatically saves transform states to localStorage under the key air-transform-${persistenceKey} and restores them on mount, overriding autoCenterOnMount.

3. Mock Input Manager: Instantiates a custom MockInputManager bridge to parse mouse and touch gestures identically across devices.

4. Aspect Fit Modes: Supports auto-fitting (autoFitMode: 'fitWidth' | 'fitHeight' | 'contain' | 'cover') to scale the source element relative to container bounds.

Suggested Use Pattern

Wrap a sticker thumbnail inside AirTransformControls and update state variables or stores inside onChange:

The AircadaViewport component is a fundamental building block of any Aircada overlay interface. It serves as the physical mount point for the 3D canvas. When mounted, it instructs the underlying client engine to append the active WebGL viewer canvas container directly inside its DOM node.

Core Responsibilities

1. Engine Hijacking: Intercepts the engine's CanvasFrameController and attaches it to the component's internal ref container.

2. Cleanup & Prevention: Tracks the original parent node so that when React triggers a layout reflow or unmounts the component, the WebGL context is safely returned to the body rather than being destroyed.

3. Gesture Blocking: Automatically applies the CSS property touch-action: none to the DOM wrapper. This is non-negotiable for preventing default mobile swipe-to-scroll behavior from breaking orbit camera rotation.

Suggested Use Pattern

Place AircadaViewport as an absolute-positioned container filling the screen beneath your interactive 2D pointer overlays:

The HorizontalScrollContainer is a structural React wrapper that converts static lists of interactive buttons, models, or configurations into a smooth horizontal carousel.

Key Capabilities

1. Click-and-Drag Panning: Enables mouse-drag scrolling with perfect 1:1 pointer tracking. It automatically sets a hasDragged threshold (5px) and intercept clicks via onClickCapture so that dragging the list does not accidentally trigger button clicks on child elements.

2. Auto-Centering: Observes the activeId prop. When it changes, the container queries its DOM tree for an element containing data-id="{activeId}", calculates its horizontal offset relative to the viewport, and calls scrollTo({ left: targetScroll, behavior: 'smooth' }) to center the item.

3. Vertical Bleed Overrides: Scrolling elements usually require overflow-x: auto which clips vertical overflow. By using the verticalBleed prop, the container applies a padding offset and equivalent negative margins, allowing visual items (like tooltips, drop shadows, or scaling hover effects) to overflow top and bottom borders without clipping.

Suggested Use Pattern

Wrap configurator cards inside the scroll container, providing a matching data-id to the active option item:

The StepPanel component is a layout manager specifically engineered for sequential workflows, such as step-by-step 3D product customization. It manages mounting steps, triggering transition CSS keyframes, and handling header layouts.

Key Capabilities

1. Slide Transition Engine: Uses a local hook (useStepTransitions) to queue active steps. When activeStepIndex changes, the hook temporarily preserves the exiting step and mounts the entering step simultaneously. It injects a style block containing @keyframes definitions (step-enter-right, step-exit-left, etc.) to execute a 500ms sliding animation.

2. Content Isolation: Isolates the sliding body content from header logic, allowing users to scroll page content while keeping step titles and chevrons fixed at the top.

3. Extensible Header Slots: To avoid hardcoding application-specific features (such as menus, checkout buttons, or minimize buttons), the component exposes clean React Node slots: leftHeaderContent and rightHeaderContent.

Suggested Use Pattern

Initialize steps containing distinct configuration parameters, linking activeStepIndex to a local state or store step parameter: