babylon.quarks-editor 0.27.0 → 0.28.0

package/src/react/host/ViewportPane.tsx

@@ -0,0 +1,300 @@
+import {
+    ArrowLeftIcon,
+    ArrowPathIcon,
+    ArrowsPointingOutIcon,
+    ArrowUturnLeftIcon,
+    ArrowUturnRightIcon,
+    CubeTransparentIcon,
+    CursorArrowRaysIcon,
+    Square2StackIcon,
+} from '@heroicons/react/24/solid';
+import React from 'react';
+import type {AssetLoadProgress} from '../../core/assets.js';
+import type {PrefabInfo} from '../../core/editorSession.js';
+import {iconStyle, type HeroIcon} from '../icons.js';
+import {buttonStyle, theme} from '../theme.js';
+import {activeSquareButtonStyle, floatingPanelStyle, saveButtonStyle, squareButtonStyle} from './hostStyles.js';
+
+/** What the stage gizmo does: nothing, or move, rotate or scale the selected node. */
+export type GizmoMode = 'none' | 'position' | 'rotation' | 'scale';
+
+const GIZMO_MODE_BUTTONS: Array<{value: GizmoMode; Icon: HeroIcon; title: string}> = [
+    {value: 'none', Icon: CursorArrowRaysIcon, title: 'Select (hide stage gizmo)'},
+    {value: 'position', Icon: ArrowsPointingOutIcon, title: 'Move the stage node (position)'},
+    {value: 'rotation', Icon: ArrowPathIcon, title: 'Rotate the stage node'},
+    {value: 'scale', Icon: Square2StackIcon, title: 'Scale the stage node'},
+];
+
+/** Props of {@link ViewportPane}. */
+export interface ViewportPaneProps {
+    /** The canvas the engine draws into. */
+    canvasRef: React.RefObject<HTMLCanvasElement | null>;
+    /** The render loop writes the frame rate here. */
+    fpsRef: React.RefObject<HTMLSpanElement | null>;
+    /** Pixels at the bottom covered by the floating Assets drawer. */
+    inset: number;
+    /** The transport bar, once the scene exists. */
+    transport: React.ReactNode;
+    /** The asset drag hovering the viewport, if any. */
+    dragHover: {label: string; count: number} | null;
+    /** Asset import progress, while importing. */
+    assetsLoading: AssetLoadProgress | null;
+    /** The open prefab, if any. */
+    prefabInfo: PrefabInfo | null;
+    /** The open prefab has unsaved edits. */
+    prefabDirty: boolean;
+    /** Link shown in the top-left corner, outside prefab mode. */
+    backLink?: {href: string; label: string};
+    /** Undo is possible. */
+    canUndo: boolean;
+    /** Redo is possible. */
+    canRedo: boolean;
+    /** An effect is focused. */
+    hasFocus: boolean;
+    /** The stage gizmo's mode. */
+    gizmoMode: GizmoMode;
+    /** Emitter shape wireframes are shown. */
+    showWireframes: boolean;
+    /** Drag handlers of the viewport, for assets dropped from the drawer. */
+    dragHandlers: Pick<React.HTMLAttributes<HTMLDivElement>, 'onDragEnter' | 'onDragLeave' | 'onDragOver' | 'onDrop'>;
+    /** Undo (`false`) or redo. */
+    onHistoryStep(redo: boolean): void;
+    /** Pick the stage gizmo's mode. */
+    onGizmoMode(mode: GizmoMode): void;
+    /** Show or hide the emitter wireframes. */
+    onToggleWireframes(): void;
+    /** Back from the prefab to the scene. */
+    onExitPrefab(): void;
+    /** Save the open prefab. */
+    onSavePrefab(): void;
+}
+
+/** The 3D viewport and what floats over it: toolbars, transport, drag and import feedback. */
+export function ViewportPane({
+    canvasRef,
+    fpsRef,
+    inset,
+    transport,
+    dragHover,
+    assetsLoading,
+    prefabInfo,
+    prefabDirty,
+    backLink,
+    canUndo,
+    canRedo,
+    hasFocus,
+    gizmoMode,
+    showWireframes,
+    dragHandlers,
+    onHistoryStep,
+    onGizmoMode,
+    onToggleWireframes,
+    onExitPrefab,
+    onSavePrefab,
+}: ViewportPaneProps): React.ReactElement {
+    return (
+        <div style={{position: 'relative', flex: 1, minWidth: 0}} {...dragHandlers}>
+            <canvas
+                ref={canvasRef}
+                style={{width: '100%', height: '100%', display: 'block', touchAction: 'none', outline: 'none'}}
+            />
+            <div
+                style={{
+                    ...floatingPanelStyle,
+                    position: 'absolute',
+                    bottom: 12 + inset,
+                    left: 12,
+                    padding: '4px 10px',
+                    fontSize: 12,
+                    color: theme.textDim,
+                    fontVariantNumeric: 'tabular-nums',
+                    pointerEvents: 'none',
+                    fontFamily: theme.font,
+                }}
+            >
+                <span ref={fpsRef}>— FPS</span>
+            </div>
+            {transport && (
+                <div style={{position: 'absolute', bottom: 12 + inset, left: '50%', transform: 'translateX(-50%)'}}>
+                    {transport}
+                </div>
+            )}
+            {dragHover && (
+                <div
+                    style={{
+                        position: 'absolute',
+                        inset: 10,
+                        border: '2px dashed rgba(120, 165, 255, 0.75)',
+                        borderRadius: 12,
+                        pointerEvents: 'none',
+                        boxShadow: 'inset 0 0 0 1px rgba(120, 165, 255, 0.15)',
+                    }}
+                >
+                    <div
+                        style={{
+                            position: 'absolute',
+                            left: '50%',
+                            top: 18,
+                            transform: 'translateX(-50%)',
+                            background: 'rgba(7, 11, 22, 0.88)',
+                            border: `1px solid ${theme.border}`,
+                            borderRadius: 8,
+                            padding: '8px 14px',
+                            fontSize: 13,
+                            color: theme.text,
+                            whiteSpace: 'nowrap',
+                        }}
+                    >
+                        Drop {dragHover.count === 1 ? 'effect' : `${dragHover.count} effects`} — {dragHover.label}
+                    </div>
+                </div>
+            )}
+            {assetsLoading && (
+                <div
+                    style={{
+                        position: 'absolute',
+                        inset: 0,
+                        display: 'flex',
+                        alignItems: 'center',
+                        justifyContent: 'center',
+                        background: 'rgba(7, 11, 22, 0.72)',
+                        pointerEvents: 'none',
+                    }}
+                >
+                    <div style={{...floatingPanelStyle, borderRadius: 10, padding: '16px 22px', textAlign: 'center'}}>
+                        <div style={{fontWeight: 600, marginBottom: 6}}>Importing assets…</div>
+                        <div style={{fontSize: 13, color: theme.textDim}}>
+                            {assetsLoading.done} / {assetsLoading.total || '…'} files
+                            {assetsLoading.failed > 0 ? ` · ${assetsLoading.failed} skipped` : ''}
+                        </div>
+                    </div>
+                </div>
+            )}
+            {prefabInfo && (
+                <div
+                    style={{
+                        ...floatingPanelStyle,
+                        position: 'absolute',
+                        top: 12,
+                        left: '50%',
+                        transform: 'translateX(-50%)',
+                        display: 'flex',
+                        alignItems: 'center',
+                        gap: 8,
+                        padding: '4px 4px 4px 6px',
+                        border: `1px solid ${theme.borderActive}`,
+                        fontSize: 12.5,
+                        zIndex: 5,
+                    }}
+                >
+                    <button
+                        type="button"
+                        className="qe-hover"
+                        title="Back to the scene"
+                        style={{...buttonStyle, padding: '3px 10px'}}
+                        onClick={onExitPrefab}
+                    >
+                        ← Scene
+                    </button>
+                    <span style={{color: theme.textDim}}>›</span>
+                    <span style={{fontWeight: 600, whiteSpace: 'nowrap'}}>
+                        {prefabInfo.name}
+                        {prefabDirty ? ' *' : ''}
+                    </span>
+                    <button
+                        type="button"
+                        className="qe-hover"
+                        title="Overwrite the prefab asset (Ctrl+S)"
+                        style={saveButtonStyle(prefabDirty, '3px 12px')}
+                        onClick={onSavePrefab}
+                    >
+                        Save
+                    </button>
+                </div>
+            )}
+            {backLink && !prefabInfo && (
+                <a
+                    className="qe-hover"
+                    href={backLink.href}
+                    style={{
+                        ...floatingPanelStyle,
+                        position: 'absolute',
+                        top: 12,
+                        left: 12,
+                        display: 'inline-flex',
+                        alignItems: 'center',
+                        gap: 6,
+                        padding: '6px 12px',
+                        fontSize: 13,
+                        fontWeight: 500,
+                        color: theme.text,
+                        textDecoration: 'none',
+                        fontFamily: theme.font,
+                    }}
+                >
+                    <ArrowLeftIcon style={iconStyle(14)} />
+                    {backLink.label.replace(/^←\s*/, '')}
+                </a>
+            )}
+            <div
+                style={{
+                    position: 'absolute',
+                    top: 12,
+                    right: 12,
+                    display: 'flex',
+                    flexDirection: 'column',
+                    alignItems: 'flex-end',
+                    gap: 6,
+                }}
+            >
+                <div style={{...floatingPanelStyle, display: 'flex', gap: 4, padding: 4}}>
+                    <button
+                        className="qe-hover"
+                        style={squareButtonStyle}
+                        title="Undo (Ctrl+Z)"
+                        disabled={!canUndo || !hasFocus}
+                        onClick={() => onHistoryStep(false)}
+                    >
+                        <ArrowUturnLeftIcon style={iconStyle(14)} />
+                    </button>
+                    <button
+                        className="qe-hover"
+                        style={squareButtonStyle}
+                        title="Redo (Ctrl+Shift+Z)"
+                        disabled={!canRedo || !hasFocus}
+                        onClick={() => onHistoryStep(true)}
+                    >
+                        <ArrowUturnRightIcon style={iconStyle(14)} />
+                    </button>
+                </div>
+                <div style={{...floatingPanelStyle, display: 'flex', flexDirection: 'column', gap: 4, padding: 4}}>
+                    {GIZMO_MODE_BUTTONS.map((m) => (
+                        <button
+                            key={m.value}
+                            className="qe-hover"
+                            style={{
+                                ...squareButtonStyle,
+                                ...(gizmoMode === m.value ? activeSquareButtonStyle : {}),
+                            }}
+                            title={m.title}
+                            onClick={() => onGizmoMode(m.value)}
+                        >
+                            <m.Icon style={iconStyle(14)} />
+                        </button>
+                    ))}
+                </div>
+                <div style={{...floatingPanelStyle, display: 'flex', flexDirection: 'column', gap: 4, padding: 4}}>
+                    <button
+                        className="qe-hover"
+                        style={{...squareButtonStyle, ...(showWireframes ? activeSquareButtonStyle : {})}}
+                        title="Show emitter shape wireframes"
+                        disabled={!hasFocus}
+                        onClick={onToggleWireframes}
+                    >
+                        <CubeTransparentIcon style={iconStyle(14)} />
+                    </button>
+                </div>
+            </div>
+        </div>
+    );
+}

package/src/react/host/hostHooks.ts

@@ -0,0 +1,198 @@
+import {Viewport} from '@babylonjs/core/Maths/math.viewport.js';
+import type {TransformNode} from '@babylonjs/core/Meshes/transformNode.js';
+import {useEffect, useRef, useState} from 'react';
+import type {EditorSession} from '../../core/editorSession.js';
+import {notifyTransformChanged} from '../../core/transformStore.js';
+import {DRAWER_HEIGHT} from './hostStyles.js';
+import type {GizmoMode} from './ViewportPane.js';
+
+/** True for a field that takes typed text, where editor shortcuts stay out of the way. */
+export function isTextInput(target: EventTarget | null): boolean {
+    const el = target as HTMLElement | null;
+    return !!el && (el.isContentEditable || ['INPUT', 'TEXTAREA', 'SELECT'].includes(el.tagName));
+}
+
+/**
+ * Inspector value controls (numbers, checkboxes, selects): Ctrl+Z there means the effect's undo,
+ * not the browser's per-field text undo. Free-text inputs (names, filters) keep the native one.
+ */
+export function isInspectorValueControl(target: EventTarget | null): boolean {
+    const el = target as HTMLElement | null;
+    if (!el) return false;
+    if (el.tagName === 'SELECT') return true;
+    return el.tagName === 'INPUT' && ['number', 'checkbox', 'range', 'color'].includes((el as HTMLInputElement).type);
+}
+
+/** What the editor's keyboard shortcuts do. */
+export interface HostShortcuts {
+    /** Ctrl+S: save the scene, or ask about the open prefab. */
+    save(): void;
+    /** Ctrl+Space: open or close the Assets drawer. */
+    toggleAssets(): void;
+    /** Space: play or pause the stage. */
+    togglePlayback(): void;
+    /** Escape: close the floating Assets drawer. */
+    closeDrawer(): void;
+    /** Ctrl+Z / Ctrl+Y / Ctrl+Shift+Z. */
+    historyStep(redo: boolean): void;
+    /** Delete: remove the focused effect; returns whether it did. */
+    deleteFocused(): boolean;
+}
+
+/** Handles a keydown on the editor's window; exported for tests. */
+export function handleHostShortcut(e: KeyboardEvent, shortcuts: HostShortcuts): void {
+    const key = e.key.toLowerCase();
+    const command = e.ctrlKey || e.metaKey;
+    if (command && key === 's') {
+        e.preventDefault();
+        shortcuts.save();
+        return;
+    }
+    if (e.code === 'Space' && command) {
+        e.preventDefault();
+        shortcuts.toggleAssets();
+        return;
+    }
+    const target = e.target as HTMLElement | null;
+    if (e.code === 'Space' && !isTextInput(target) && target?.tagName !== 'BUTTON') {
+        e.preventDefault();
+        shortcuts.togglePlayback();
+        return;
+    }
+    if (e.key === 'Escape') {
+        shortcuts.closeDrawer();
+    }
+    if (command && (key === 'z' || key === 'y')) {
+        if (isTextInput(e.target) && !isInspectorValueControl(e.target)) {
+            return;
+        }
+        e.preventDefault();
+        // Leave the field first so it shows the restored value instead of its draft text.
+        (e.target as HTMLElement | null)?.blur?.();
+        shortcuts.historyStep(key === 'y' || e.shiftKey);
+        return;
+    }
+    if (e.key === 'Delete' && !isTextInput(e.target) && shortcuts.deleteFocused()) {
+        e.preventDefault();
+    }
+}
+
+/** Installs the editor's keyboard shortcuts on the window; the latest `shortcuts` are always used. */
+export function useHostShortcuts(shortcuts: HostShortcuts): void {
+    const ref = useRef(shortcuts);
+    ref.current = shortcuts;
+    useEffect(() => {
+        const onKey = (e: KeyboardEvent) => handleHostShortcut(e, ref.current);
+        window.addEventListener('keydown', onKey);
+        return () => window.removeEventListener('keydown', onKey);
+    }, []);
+}
+
+/**
+ * Puts the stage gizmo in `mode` and attaches it to `target`, leaving it where it is while
+ * `paused`. One gizmo drag is one undo step: the binding snapshots at drag start, and the UI
+ * refreshes at most once a frame while dragging.
+ */
+export function useStageGizmo(
+    session: EditorSession | null,
+    mode: GizmoMode,
+    target: TransformNode | null,
+    paused: boolean
+): void {
+    useEffect(() => {
+        const gm = session?.gizmoManager;
+        if (!gm) return;
+        gm.positionGizmoEnabled = mode === 'position';
+        gm.rotationGizmoEnabled = mode === 'rotation';
+        gm.scaleGizmoEnabled = mode === 'scale';
+        const activeGizmo =
+            mode === 'position'
+                ? gm.gizmos.positionGizmo
+                : mode === 'rotation'
+                  ? gm.gizmos.rotationGizmo
+                  : mode === 'scale'
+                    ? gm.gizmos.scaleGizmo
+                    : null;
+        let dragRaf = 0;
+        const scheduleTransformRefresh = () => {
+            if (dragRaf !== 0) {
+                return;
+            }
+            dragRaf = requestAnimationFrame(() => {
+                dragRaf = 0;
+                notifyTransformChanged();
+            });
+        };
+        const dragStartObserver = activeGizmo?.onDragStartObservable.add(() => session.binding?.onBeforeChange?.());
+        const dragObserver = activeGizmo?.onDragObservable.add(scheduleTransformRefresh);
+        const dragEndObserver = activeGizmo?.onDragEndObservable.add(() => {
+            notifyTransformChanged();
+            session.binding?.markChanged();
+        });
+        return () => {
+            if (dragRaf !== 0) {
+                cancelAnimationFrame(dragRaf);
+            }
+            if (activeGizmo) {
+                activeGizmo.onDragStartObservable.remove(dragStartObserver ?? null);
+                activeGizmo.onDragObservable.remove(dragObserver ?? null);
+                activeGizmo.onDragEndObservable.remove(dragEndObserver ?? null);
+            }
+        };
+    }, [session, mode]);
+
+    useEffect(() => {
+        if (!paused) {
+            session?.gizmoManager.attachToNode(target);
+        }
+    }, [session, target, paused]);
+}
+
+/**
+ * The floating drawer is opaque, so the scene renders only in the part of the viewport above it:
+ * the view, and every "frame this effect" camera move, re-centres on what is visible. Measured
+ * again when the drawer floats or docks and when the timeline collapses. Returns the pixels the
+ * drawer covers.
+ */
+export function useViewportInset(
+    session: EditorSession | null,
+    canvasRef: React.RefObject<HTMLCanvasElement | null>,
+    areaRef: React.RefObject<HTMLDivElement | null>,
+    drawerFloating: boolean,
+    timelineCollapsed: boolean
+): number {
+    const [inset, setInset] = useState(0);
+    useEffect(() => {
+        const update = () => {
+            const camera = session?.camera;
+            const canvas = canvasRef.current;
+            const area = areaRef.current;
+            if (!camera || !canvas || !area) return;
+            const canvasRect = canvas.getBoundingClientRect();
+            const drawerTop = area.getBoundingClientRect().bottom - DRAWER_HEIGHT;
+            const covered = drawerFloating
+                ? Math.max(0, Math.min(canvasRect.height * 0.8, canvasRect.bottom - drawerTop))
+                : 0;
+            const fraction = canvasRect.height > 0 ? covered / canvasRect.height : 0;
+            camera.viewport = new Viewport(0, fraction, 1, 1 - fraction);
+            setInset(covered);
+        };
+        update();
+        window.addEventListener('resize', update);
+        return () => window.removeEventListener('resize', update);
+    }, [session, canvasRef, areaRef, drawerFloating, timelineCollapsed]);
+    return inset;
+}
+
+/** Asks before the page unloads while `dirty`. */
+export function useUnsavedChangesGuard(dirty: boolean): void {
+    useEffect(() => {
+        if (!dirty) return;
+        const onBeforeUnload = (e: BeforeUnloadEvent) => {
+            e.preventDefault();
+            e.returnValue = '';
+        };
+        window.addEventListener('beforeunload', onBeforeUnload);
+        return () => window.removeEventListener('beforeunload', onBeforeUnload);
+    }, [dirty]);
+}

package/src/react/host/hostStyles.ts

@@ -0,0 +1,65 @@
+import type React from 'react';
+import {buttonStyle, theme} from '../theme.js';
+
+/** Width of the Scene list on the left. */
+export const SCENE_PANEL_WIDTH = 280;
+/** Width of the inspector on the right. */
+export const INSPECTOR_WIDTH = 340;
+/** Height of the timeline dock when expanded. */
+export const TIMELINE_HEIGHT = 200;
+/** Height of the Assets drawer. */
+export const DRAWER_HEIGHT = 280;
+
+/** A square icon button of the viewport toolbars. */
+export const squareButtonStyle: React.CSSProperties = {
+    ...buttonStyle,
+    width: 28,
+    height: 28,
+    padding: 0,
+    display: 'flex',
+    alignItems: 'center',
+    justifyContent: 'center',
+    fontWeight: 700,
+};
+
+/** Added to a toolbar button that is switched on. */
+export const activeSquareButtonStyle: React.CSSProperties = {
+    border: `1px solid ${theme.borderActive}`,
+    background: 'rgba(120, 165, 255, 0.35)',
+};
+
+/** Title of a dock (Assets, Timeline). */
+export const dockTitleStyle: React.CSSProperties = {
+    fontSize: 11,
+    fontWeight: 600,
+    letterSpacing: 0.4,
+    textTransform: 'uppercase',
+    color: theme.text,
+};
+
+/** A small icon button in a dock's header. */
+export const dockIconButtonStyle: React.CSSProperties = {
+    ...buttonStyle,
+    width: 24,
+    height: 22,
+    padding: 0,
+    display: 'inline-flex',
+    alignItems: 'center',
+    justifyContent: 'center',
+};
+
+/** A floating panel over the viewport. */
+export const floatingPanelStyle: React.CSSProperties = {
+    background: theme.panelBg,
+    border: `1px solid ${theme.border}`,
+    borderRadius: 8,
+};
+
+/** A Save button, highlighted while there is something to save. */
+export function saveButtonStyle(pending: boolean, padding: string): React.CSSProperties {
+    return {
+        ...buttonStyle,
+        padding,
+        ...(pending ? {background: theme.accent, color: '#0a1128', border: `1px solid ${theme.accent}`} : {}),
+    };
+}

package/src/react/index.ts

@@ -28,7 +28,7 @@ export type {EditorWorkspaceProps} from './EditorWorkspace.js';
 export {EffectEditor} from './EffectEditor.js';
 export type {EffectEditorProps} from './EffectEditor.js';
 export {EffectEditorHost, QuarksEffectEditor} from './EffectEditorHost.js';
-export type {EffectEditorHostHandle, EffectEditorHostProps} from './EffectEditorHost.js';
+export type {EditorProject, EffectEditorHostHandle, EffectEditorHostProps} from './EffectEditorHost.js';
 export {EffectTreeView} from './EffectTreeView.js';
 export type {EffectTreeViewProps} from './EffectTreeView.js';
 export {CheckboxField, NumberField, Row, SelectField} from './fields.js';
@@ -45,6 +45,7 @@ export {
 } from './modules.js';
 export type {GeometryData, GeometryOption, TextureOption} from './modules.js';
 export {ModuleSection} from './ModuleSection.js';
+export type {ModuleProps} from './ModuleSection.js';
 export {ProjectsPage} from './ProjectsPage.js';
 export type {ProjectsPageProps} from './ProjectsPage.js';
 export {PromptDialog} from './PromptDialog.js';
@@ -62,3 +63,4 @@ export type {TimelineTrackRowProps} from './TimelineTrackRow.js';
 export {TransportBar} from './TransportBar.js';
 export type {TransportBarProps} from './TransportBar.js';
 export {ValueField} from './ValueField.js';
+export type {ConstantValueFieldProps, CurveValueFieldProps} from './ValueField.js';