babylon.quarks-editor 0.26.0 → 0.28.0

package/src/react/TimelineTrackRow.tsx

@@ -1,4 +1,4 @@
-import type {TransformNode} from '@babylonjs/core/Meshes/transformNode';
+import type {TransformNode} from '@babylonjs/core/Meshes/transformNode.js';
 import {
     CheckIcon,
     ChevronDownIcon,
@@ -13,14 +13,14 @@ import {
 } from '@heroicons/react/24/solid';
 import type {ParticleSystem} from 'babylon.quarks';
 import React, {useState} from 'react';
-import type {EffectBinding} from '../core/binding';
-import {buildEffectTree, collectSystems} from '../core/effectTree';
-import {ungroupNode} from '../core/groups';
-import {createChildSystem, removeSystems} from '../core/systems';
-import type {TimelineRow} from '../core/timeline';
-import {PromptDialog} from './PromptDialog';
-import {iconStyle} from './icons';
-import {theme} from './theme';
+import type {EffectBinding} from '../core/binding.js';
+import {buildEffectTree, collectSystems} from '../core/effectTree.js';
+import {ungroupNode} from '../core/groups.js';
+import {createChildSystem, removeSystems} from '../core/systems.js';
+import type {TimelineRow} from '../core/timeline.js';
+import {PromptDialog} from './PromptDialog.js';
+import {iconStyle} from './icons.js';
+import {theme} from './theme.js';
 
 const iconButton: React.CSSProperties = {
     background: 'none',
@@ -34,21 +34,31 @@ const iconButton: React.CSSProperties = {
 
 const ROW_HEIGHT = 28;
 
+/** Props of {@link TimelineTrackRow}. */
 export interface TimelineTrackRowProps {
+    /** The group or track the row shows. */
     row: TimelineRow;
+    /** The focused effect, edited by the row's actions. */
     binding: EffectBinding;
+    /** The row's node is the one in the inspector. */
     selected: boolean;
+    /** Selects the row's node. */
     onSelectNode: (node: TransformNode | null) => void;
+    /** The ruler's scale, pixels per second. */
     pxPerSecond: number;
     /** Matches the ruler's left gutter so bars line up under the correct tick. */
     offsetPx: number;
+    /** A group row's children are hidden. */
     collapsed: boolean;
+    /** Collapses or expands a group row. */
     onToggleCollapse?: () => void;
     /** Preview-only visibility (toggles `system.emitter.visible`); lets you isolate one track. */
     hidden?: boolean;
+    /** Shows or hides the track in the preview. */
     onToggleVisible?: () => void;
     /** Membership in the "group selected rows together" set (unrelated to inspector selection). */
     groupSelected: boolean;
+    /** Adds the row to the set, or takes it out. */
     onToggleGroupSelect: () => void;
 }
 

package/src/react/TransportBar.tsx

@@ -1,23 +1,32 @@
-import type {Scene} from '@babylonjs/core/scene';
+import type {Scene} from '@babylonjs/core/scene.js';
 import {ArrowPathIcon, ForwardIcon, PauseIcon, PlayIcon} from '@heroicons/react/24/solid';
 import type {BatchedRenderer} from 'babylon.quarks';
 import React from 'react';
-import type {EffectBinding} from '../core/binding';
-import type {PlaybackState} from '../core/playback';
-import {PLAYBACK_SPEEDS, restartFocusPlayback, toggleStagePlayback} from '../core/transport';
-import {iconStyle} from './icons';
-import {buttonStyle, theme} from './theme';
+import type {EffectBinding} from '../core/binding.js';
+import type {PlaybackState} from '../core/playback.js';
+import {PLAYBACK_SPEEDS, restartFocusPlayback, toggleStagePlayback} from '../core/transport.js';
+import {iconStyle} from './icons.js';
+import {buttonStyle, theme} from './theme.js';
 
+/** Props of {@link TransportBar}. */
 export interface TransportBarProps {
+    /** The focused effect, which Restart and Step act on. */
     binding: EffectBinding | null;
+    /** The preview scene, redrawn after a restart. */
     scene: Scene;
+    /** The renderer the effects draw through. */
     renderer: BatchedRenderer;
+    /** Playback state shared with the host's render loop. */
     playbackRef: React.MutableRefObject<PlaybackState>;
     /** The host's render loop writes time and particle count here. */
-    counterRef: React.RefObject<HTMLSpanElement>;
+    counterRef: React.RefObject<HTMLSpanElement | null>;
+    /** The stage is playing. */
     stagePlaying: boolean;
+    /** Plays or pauses the stage. */
     setStagePlaying: (playing: boolean) => void;
+    /** Playback speed, 1 for real time. */
     speed: number;
+    /** Sets the playback speed. */
     setSpeed: (speed: number) => void;
     /** False when the focused effect is hidden. */
     enabled: boolean;

package/src/react/ValueField.tsx

@@ -1,28 +1,72 @@
+import type {ValueGenerator} from 'babylon.quarks';
 import React from 'react';
-import {ScalarGenerator, ScalarValueState, buildCurve, buildScalar, readPieces, readScalar} from '../core/values';
-import {CurveEditor} from './CurveEditor';
-import {NumberField, Row, SelectField} from './fields';
+import {
+    AnyGenerator,
+    ScalarGenerator,
+    ScalarValueState,
+    buildCurve,
+    buildScalar,
+    readPieces,
+    readScalar,
+} from '../core/values.js';
+import {CurveEditor} from './CurveEditor.js';
+import {NumberField, Row, SelectField} from './fields.js';
 
-/**
- * Unity-like value field: Constant | Random Between Two Constants | Curve,
- * bound to a quarks value generator.
- */
 const captionStyle: React.CSSProperties = {fontSize: 10.5, opacity: 0.6, flex: 'none'};
 
-export function ValueField(props: {
+/** Props every {@link ValueField} takes. */
+interface ValueFieldBaseProps {
+    /** The row's label. */
     label: string;
+    /** Tooltip text of the label. */
     hint?: string;
+    /** Key into the inspector hints, used when `hint` is not given. */
     hintKey?: string;
-    generator: ScalarGenerator | undefined;
-    onChange: (generator: ScalarGenerator) => void;
+    /** The generator shown; one that is not a scalar reads as the constant 1. */
+    generator: AnyGenerator | undefined;
+    /** Smallest value the number fields accept. */
     min?: number;
+    /** Top of the curve editor's value range. */
     curveMax?: number;
-}) {
-    const state = readScalar(props.generator);
+}
+
+/** A value field for a setting that takes a curve over the particle's life. */
+export interface CurveValueFieldProps extends ValueFieldBaseProps {
+    /** Offers Curve beside Constant and Random (the default). */
+    curve?: true;
+    /** Receives the edited generator. */
+    onChange: (generator: ScalarGenerator) => void;
+}
+
+/** A value field for a setting sampled once, without a curve: Constant or Random. */
+export interface ConstantValueFieldProps extends ValueFieldBaseProps {
+    /** Hides Curve: the setting takes no curve. */
+    curve: false;
+    /** Receives the edited generator. */
+    onChange: (generator: ValueGenerator) => void;
+}
+
+function isValueGenerator(generator: ScalarGenerator): generator is ValueGenerator {
+    return generator.type === 'value';
+}
+
+/**
+ * Unity-like value field: Constant | Random Between Two Constants | Curve, bound to a quarks value
+ * generator. With `curve={false}` it offers only the first two, for settings sampled once.
+ */
+export function ValueField(props: CurveValueFieldProps | ConstantValueFieldProps): React.ReactElement {
+    const read = readScalar(props.generator);
+    // A setting without curves shows a curve it was loaded with as a constant, so an edit replaces it.
+    const state: ScalarValueState = props.curve === false && read.mode === 'curve' ? {...read, mode: 'constant'} : read;
 
-    const commit = (patch: Partial<ScalarValueState>) => {
-        props.onChange(buildScalar({...state, ...patch}));
+    const emit = (generator: ScalarGenerator) => {
+        if (props.curve !== false) {
+            props.onChange(generator);
+        } else if (isValueGenerator(generator)) {
+            props.onChange(generator);
+        }
     };
+    const commit = (patch: Partial<ScalarValueState>) => emit(buildScalar({...state, ...patch}));
 
     return (
         <>
@@ -32,7 +76,7 @@ export function ValueField(props: {
                     options={[
                         {value: 'constant', label: 'Constant'},
                         {value: 'random', label: 'Random between two'},
-                        {value: 'curve', label: 'Curve'},
+                        ...(props.curve !== false ? [{value: 'curve' as const, label: 'Curve'}] : []),
                     ]}
                     onChange={(mode) => commit({mode})}
                 />
@@ -57,7 +101,7 @@ export function ValueField(props: {
                     <CurveEditor
                         pieces={readPieces(props.generator)}
                         maxValue={props.curveMax}
-                        onChange={(pieces) => props.onChange(buildCurve(pieces))}
+                        onChange={(pieces) => emit(buildCurve(pieces))}
                     />
                 </div>
             )}