@hyperframes/studio 0.7.6 → 0.7.8

package/src/components/editor/propertyPanel3dTransform.tsx

@@ -1,8 +1,10 @@
+import { useState } from "react";
 import type { DomEditSelection } from "./domEditingTypes";
 import { STUDIO_KEYFRAMES_ENABLED } from "./manualEditingAvailability";
 import { MetricField } from "./propertyPanelPrimitives";
 import { KeyframeNavigation } from "./KeyframeNavigation";
 import { formatPxMetricValue, parsePxMetricValue, RESPONSIVE_GRID } from "./propertyPanelHelpers";
+import { Transform3DCube, type CubePose } from "./Transform3DCube";
 
 type KeyframeEntry = Array<{
   percentage: number;
@@ -24,9 +26,216 @@ interface PropertyPanel3dTransformProps {
     property: string,
     value: number,
   ) => Promise<void>;
+  /** Batched commit — several props into one keyframe (the cube's rotationX/Y/Z). */
+  onCommitAnimatedProperties?: (
+    element: DomEditSelection,
+    props: Record<string, number | string>,
+  ) => Promise<void>;
   onSeekToTime?: (time: number) => void;
   onRemoveKeyframe?: (animId: string, pct: number) => void;
-  onConvertToKeyframes?: (animId: string) => void;
+  onConvertToKeyframes?: (animId: string, duration?: number) => void;
+  /** Live-set props on the preview element during a cube drag (no source write). */
+  onLivePreviewProps?: (element: DomEditSelection, props: Record<string, number>) => void;
+}
+
+type CommitAnimatedProperty = (
+  element: DomEditSelection,
+  property: string,
+  value: number,
+) => Promise<void>;
+
+/** The draggable cube + its commit/recenter/live-preview wiring. */
+function Cube3dControl({
+  element,
+  gsapRuntimeValues,
+  onCommitAnimatedProperty,
+  onCommitAnimatedProperties,
+  onLivePreviewProps,
+  onKeyframe,
+  keyframed,
+}: {
+  element: DomEditSelection;
+  gsapRuntimeValues: Record<string, number>;
+  onCommitAnimatedProperty: CommitAnimatedProperty;
+  onCommitAnimatedProperties?: (
+    element: DomEditSelection,
+    props: Record<string, number | string>,
+  ) => Promise<void>;
+  onLivePreviewProps?: (element: DomEditSelection, props: Record<string, number>) => void;
+  onKeyframe?: () => void;
+  keyframed?: boolean;
+}) {
+  const pose: CubePose = {
+    rotationX: gsapRuntimeValues.rotationX ?? 0,
+    rotationY: gsapRuntimeValues.rotationY ?? 0,
+    rotationZ: gsapRuntimeValues.rotationZ ?? 0,
+  };
+  // Commit only the rotation axes the drag actually changed (each rounded to a
+  // whole degree). Reuses the keyframe-aware animated-property commit, so a drag
+  // at the playhead writes/updates a keyframe just like the numeric fields.
+  const commitPose = (next: CubePose) => {
+    const changedProps: Record<string, number> = {};
+    for (const axis of ["rotationX", "rotationY", "rotationZ"] as const) {
+      const rounded = Math.round(next[axis]);
+      if (rounded !== Math.round(pose[axis])) changedProps[axis] = rounded;
+    }
+    const axes = Object.keys(changedProps);
+    if (axes.length === 0) return;
+    // ONE keyframe for the whole pose change — avoids per-axis commits racing into
+    // adjacent duplicate keyframes. Fall back to per-axis if no batched commit.
+    if (onCommitAnimatedProperties) {
+      void onCommitAnimatedProperties(element, changedProps);
+    } else {
+      for (const [axis, v] of Object.entries(changedProps))
+        onCommitAnimatedProperty(element, axis, v);
+    }
+  };
+  const recenter = () => {
+    // ONE commit for the whole reset — six per-axis commits meant six soft-reloads
+    // (six flashes) for a single click. Batch like commitPose does.
+    const identity = {
+      rotationX: 0,
+      rotationY: 0,
+      rotationZ: 0,
+      z: 0,
+      scale: 1,
+      transformPerspective: 0,
+    };
+    if (onCommitAnimatedProperties) {
+      void onCommitAnimatedProperties(element, identity);
+    } else {
+      for (const [prop, v] of Object.entries(identity))
+        void onCommitAnimatedProperty(element, prop, v);
+    }
+  };
+  // Immediate element feedback while dragging — set the live transform without a
+  // source write; the release commits via onCommitAnimatedProperty.
+  const livePreview = (next: CubePose) =>
+    onLivePreviewProps?.(element, {
+      rotationX: next.rotationX,
+      rotationY: next.rotationY,
+      rotationZ: next.rotationZ,
+    });
+
+  return (
+    <div className="mb-2 px-2">
+      <div className="mx-auto max-w-[184px]">
+        <Transform3DCube
+          pose={pose}
+          perspective={gsapRuntimeValues.transformPerspective ?? 0}
+          onPoseDraft={livePreview}
+          onPoseCommit={commitPose}
+          onPerspectiveDraft={(px) => onLivePreviewProps?.(element, { transformPerspective: px })}
+          onPerspectiveCommit={(px) =>
+            void onCommitAnimatedProperty(element, "transformPerspective", px)
+          }
+          onRecenter={recenter}
+          onKeyframe={onKeyframe}
+          keyframed={keyframed}
+        />
+        <p className="mt-1 text-center text-[9px] leading-snug text-neutral-600">
+          Drag to tilt · Shift-drag to roll
+        </p>
+      </div>
+    </div>
+  );
+}
+
+interface FieldCtx {
+  element: DomEditSelection;
+  gsapRuntimeValues: Record<string, number>;
+  gsapKeyframes: KeyframeEntry;
+  gsapAnimId: string | null;
+  currentPct: number;
+  elStart: number;
+  elDuration: number;
+  resolveAnimIdForProp?: (prop: string) => string | null;
+  onCommitAnimatedProperty?: (
+    element: DomEditSelection,
+    property: string,
+    value: number,
+  ) => Promise<void>;
+  onSeekToTime?: (time: number) => void;
+  onRemoveKeyframe?: (animId: string, pct: number) => void;
+  onConvertToKeyframes?: (animId: string, duration?: number) => void;
+}
+
+const parseDeg = (s: string): number | null => {
+  const n = Number.parseFloat(s.replace("°", ""));
+  return Number.isFinite(n) ? n : null;
+};
+const parseScale = (s: string): number | null => {
+  const n = Number.parseFloat(s);
+  return Number.isFinite(n) ? n : null;
+};
+const parsePxNonNeg = (s: string): number | null => {
+  const v = parsePxMetricValue(s);
+  return v != null && v >= 0 ? v : null;
+};
+
+/**
+ * One 3D-transform field: a number/scrub input plus its keyframe diamond, so
+ * rotation / perspective / Z / scale can each be keyframed just like Layout's
+ * X / Y — the diamond was previously missing on the rotation + perspective rows.
+ */
+function Transform3dField({
+  label,
+  prop,
+  scrub,
+  format,
+  parse,
+  defaultValue,
+  ctx,
+}: {
+  label: string;
+  prop: string;
+  scrub?: boolean;
+  format: (v: number) => string;
+  parse: (s: string) => number | null;
+  defaultValue: number;
+  ctx: FieldCtx;
+}) {
+  const { gsapAnimId, onCommitAnimatedProperty } = ctx;
+  const idFor = (p: string) => ctx.resolveAnimIdForProp?.(p) ?? gsapAnimId;
+  const current = ctx.gsapRuntimeValues[prop] ?? defaultValue;
+  return (
+    <div className="flex items-center gap-1">
+      <div className="flex-1">
+        <MetricField
+          label={label}
+          value={format(current)}
+          scrub={scrub}
+          onCommit={(next) => {
+            const v = parse(next);
+            if (v != null && onCommitAnimatedProperty) {
+              void onCommitAnimatedProperty(ctx.element, prop, v);
+            }
+          }}
+        />
+      </div>
+      {STUDIO_KEYFRAMES_ENABLED && (gsapAnimId || onCommitAnimatedProperty) && (
+        <KeyframeNavigation
+          property={prop}
+          keyframes={ctx.gsapKeyframes}
+          currentPercentage={ctx.currentPct}
+          onSeek={(pct) => ctx.onSeekToTime?.(ctx.elStart + (pct / 100) * ctx.elDuration)}
+          onAddKeyframe={() => {
+            if (onCommitAnimatedProperty) void onCommitAnimatedProperty(ctx.element, prop, current);
+          }}
+          onRemoveKeyframe={(pct) => {
+            const id = idFor(prop);
+            if (id) ctx.onRemoveKeyframe?.(id, pct);
+          }}
+          onConvertToKeyframes={() => {
+            const id = idFor(prop);
+            // Pass the element's clip duration so a converted static 3D `set`
+            // spans the whole clip (keyframes land in range at any playhead).
+            if (id) ctx.onConvertToKeyframes?.(id, ctx.elDuration);
+          }}
+        />
+      )}
+    </div>
+  );
 }
 
 export function PropertyPanel3dTransform({
@@ -39,110 +248,120 @@ export function PropertyPanel3dTransform({
   elDuration,
   element,
   onCommitAnimatedProperty,
+  onCommitAnimatedProperties,
   onSeekToTime,
   onRemoveKeyframe,
   onConvertToKeyframes,
+  onLivePreviewProps,
 }: PropertyPanel3dTransformProps) {
-  const idFor = (prop: string) => resolveAnimIdForProp?.(prop) ?? gsapAnimId;
+  // Expanded by default — the cube gizmo is the headline of this panel, so show
+  // it up front rather than hiding it behind a collapsed header.
+  const [collapsed, setCollapsed] = useState(false);
+  const ctx: FieldCtx = {
+    element,
+    gsapRuntimeValues,
+    gsapKeyframes,
+    gsapAnimId,
+    currentPct,
+    elStart,
+    elDuration,
+    resolveAnimIdForProp,
+    onCommitAnimatedProperty,
+    onSeekToTime,
+    onRemoveKeyframe,
+    onConvertToKeyframes,
+  };
+
   return (
     <div className="mt-3 border-t border-neutral-800/40 pt-3">
-      <div className="mb-2 text-[10px] font-medium uppercase tracking-wider text-neutral-600">
-        3D Transform
-      </div>
-      <div className={RESPONSIVE_GRID}>
-        <div className="flex items-center gap-1">
-          <div className="flex-1">
-            <MetricField
-              label="Z"
-              value={formatPxMetricValue(gsapRuntimeValues.z ?? 0)}
-              scrub
-              onCommit={(next) => {
-                const v = parsePxMetricValue(next);
-                if (v != null && onCommitAnimatedProperty) {
-                  void onCommitAnimatedProperty(element, "z", v);
-                }
-              }}
-            />
-          </div>
-          {STUDIO_KEYFRAMES_ENABLED && (gsapAnimId || onCommitAnimatedProperty) && (
-            <KeyframeNavigation
-              property="z"
-              keyframes={gsapKeyframes}
-              currentPercentage={currentPct}
-              onSeek={(pct) => onSeekToTime?.(elStart + (pct / 100) * elDuration)}
-              onAddKeyframe={() => {
-                if (onCommitAnimatedProperty) {
-                  void onCommitAnimatedProperty(element, "z", gsapRuntimeValues?.z ?? 0);
-                }
-              }}
-              onRemoveKeyframe={(pct) => {
-                const id = idFor("z");
-                if (id) onRemoveKeyframe?.(id, pct);
-              }}
-              onConvertToKeyframes={() => {
-                const id = idFor("z");
-                if (id) onConvertToKeyframes?.(id);
+      <button
+        type="button"
+        onClick={() => setCollapsed((v) => !v)}
+        className="mb-2 flex w-full items-center justify-between text-[10px] font-medium uppercase tracking-wider text-neutral-600 hover:text-neutral-400"
+      >
+        <span>3D Transform</span>
+        <svg width="9" height="9" viewBox="0 0 10 10" fill="currentColor" aria-hidden>
+          {collapsed ? <path d="M3 2l4 3-4 3z" /> : <path d="M2 3l3 4 3-4z" />}
+        </svg>
+      </button>
+      {collapsed ? null : (
+        <>
+          {onCommitAnimatedProperty && (
+            <Cube3dControl
+              element={element}
+              gsapRuntimeValues={gsapRuntimeValues}
+              onCommitAnimatedProperty={onCommitAnimatedProperty}
+              onCommitAnimatedProperties={onCommitAnimatedProperties}
+              onLivePreviewProps={onLivePreviewProps}
+              keyframed={(gsapKeyframes ?? []).some(
+                (kf) =>
+                  "rotationX" in kf.properties ||
+                  "rotationY" in kf.properties ||
+                  "rotationZ" in kf.properties,
+              )}
+              onKeyframe={() => {
+                // Convert the 3D ("other"-group) static set to keyframes so the
+                // cube can animate; spans the element's clip via elDuration.
+                const id = resolveAnimIdForProp?.("rotationX") ?? gsapAnimId;
+                if (id) onConvertToKeyframes?.(id, elDuration);
               }}
             />
           )}
-        </div>
-        <div className="flex items-center gap-1">
-          <div className="flex-1">
-            <MetricField
+          <div className={RESPONSIVE_GRID}>
+            <Transform3dField
+              ctx={ctx}
+              label="Z"
+              prop="z"
+              scrub
+              format={formatPxMetricValue}
+              parse={parsePxMetricValue}
+              defaultValue={0}
+            />
+            <Transform3dField
+              ctx={ctx}
               label="Scale"
-              value={String(gsapRuntimeValues.scale ?? 1)}
+              prop="scale"
               scrub
-              onCommit={(next) => {
-                const v = Number.parseFloat(next);
-                if (Number.isFinite(v) && onCommitAnimatedProperty) {
-                  void onCommitAnimatedProperty(element, "scale", v);
-                }
-              }}
+              format={(v) => String(v)}
+              parse={parseScale}
+              defaultValue={1}
             />
-          </div>
-          {STUDIO_KEYFRAMES_ENABLED && (gsapAnimId || onCommitAnimatedProperty) && (
-            <KeyframeNavigation
-              property="scale"
-              keyframes={gsapKeyframes}
-              currentPercentage={currentPct}
-              onSeek={(pct) => onSeekToTime?.(elStart + (pct / 100) * elDuration)}
-              onAddKeyframe={() => {
-                if (onCommitAnimatedProperty) {
-                  void onCommitAnimatedProperty(element, "scale", gsapRuntimeValues?.scale ?? 1);
-                }
-              }}
-              onRemoveKeyframe={(pct) => {
-                const id = idFor("scale");
-                if (id) onRemoveKeyframe?.(id, pct);
-              }}
-              onConvertToKeyframes={() => {
-                const id = idFor("scale");
-                if (id) onConvertToKeyframes?.(id);
-              }}
+            <Transform3dField
+              ctx={ctx}
+              label="RotX"
+              prop="rotationX"
+              format={(v) => `${v}°`}
+              parse={parseDeg}
+              defaultValue={0}
             />
-          )}
-        </div>
-        <MetricField
-          label="RotX"
-          value={`${gsapRuntimeValues.rotationX ?? 0}°`}
-          onCommit={(next) => {
-            const v = Number.parseFloat(next.replace("°", ""));
-            if (Number.isFinite(v) && onCommitAnimatedProperty) {
-              void onCommitAnimatedProperty(element, "rotationX", v);
-            }
-          }}
-        />
-        <MetricField
-          label="RotY"
-          value={`${gsapRuntimeValues.rotationY ?? 0}°`}
-          onCommit={(next) => {
-            const v = Number.parseFloat(next.replace("°", ""));
-            if (Number.isFinite(v) && onCommitAnimatedProperty) {
-              void onCommitAnimatedProperty(element, "rotationY", v);
-            }
-          }}
-        />
-      </div>
+            <Transform3dField
+              ctx={ctx}
+              label="RotY"
+              prop="rotationY"
+              format={(v) => `${v}°`}
+              parse={parseDeg}
+              defaultValue={0}
+            />
+            <Transform3dField
+              ctx={ctx}
+              label="RotZ"
+              prop="rotationZ"
+              format={(v) => `${v}°`}
+              parse={parseDeg}
+              defaultValue={0}
+            />
+            <Transform3dField
+              ctx={ctx}
+              label="Perspective"
+              prop="transformPerspective"
+              scrub
+              format={formatPxMetricValue}
+              parse={parsePxNonNeg}
+              defaultValue={0}
+            />
+          </div>
+        </>
+      )}
     </div>
   );
 }

package/src/components/editor/propertyPanelHelpers.ts

@@ -67,12 +67,19 @@ export interface PropertyPanelProps {
   ) => void;
   onRemoveKeyframe?: (animationId: string, percentage: number) => void;
   onUpdateKeyframeEase?: (animationId: string, percentage: number, ease: string) => void;
-  onConvertToKeyframes?: (animationId: string) => void;
+  onSetAllKeyframeEases?: (animationId: string, ease: string) => void;
+  onConvertToKeyframes?: (animationId: string, duration?: number) => void;
   onCommitAnimatedProperty?: (
     selection: DomEditSelection,
     property: string,
     value: number | string,
   ) => Promise<void>;
+  /** Batched variant: commit several props into ONE keyframe (e.g. the 3D cube's
+   * rotationX/Y/Z) so multi-axis edits don't race into adjacent duplicates. */
+  onCommitAnimatedProperties?: (
+    selection: DomEditSelection,
+    props: Record<string, number | string>,
+  ) => Promise<void>;
   onSeekToTime?: (time: number) => void;
   recordingState?: "idle" | "recording" | "preview";
   recordingDuration?: number;
@@ -211,8 +218,8 @@ export const LABEL = "text-[11px] font-medium text-panel-text-3";
 export const RESPONSIVE_GRID = "grid grid-cols-[repeat(auto-fit,minmax(118px,1fr))] gap-3";
 export const EMPTY_STYLES: Record<string, string> = {};
 
-export const EMPTY_FILTER_VALUE = "none";
-export const BOX_SHADOW_PRESETS = {
+const EMPTY_FILTER_VALUE = "none";
+const BOX_SHADOW_PRESETS = {
   none: "none",
   soft: "0 12px 36px rgba(0, 0, 0, 0.28)",
   lift: "0 18px 54px rgba(0, 0, 0, 0.38)",
@@ -272,12 +279,7 @@ export function parsePxMetricValue(value: string): number | null {
   return token.value;
 }
 
-export function clampPanelNumber(
-  value: number,
-  min: number,
-  max: number,
-  fallback: number,
-): number {
+function clampPanelNumber(value: number, min: number, max: number, fallback: number): number {
   if (!Number.isFinite(value)) return fallback;
   return Math.max(min, Math.min(max, value));
 }
@@ -320,6 +322,7 @@ export function normalizeTextMetricValue(
 function splitCssFunctions(value: string): string[] {
   const functions: string[] = [];
   let current = "";
+  // fallow-ignore-next-line code-duplication -- pre-existing; surfaced in this file's diff by an unrelated line shift
   let depth = 0;
 
   for (const char of value.trim()) {
@@ -485,6 +488,39 @@ export function extractBackgroundImageUrl(value: string | undefined): string {
 
 // ── GSAP runtime value readers (used by PropertyPanel) ────────────────────
 
+// fallow-ignore-next-line complexity -- pre-existing; surfaced in this file's diff by an unrelated line shift
+// Core transform channels the panel ALWAYS reads live — even before a just-set
+// value (e.g. rotationX) has re-parsed into `gsapAnimations`. Without this the
+// cube + fields drop the prop and flicker to 0 on every commit; gsap.getProperty
+// reflects the in-place instant patch, so it's the true current value.
+const ALWAYS_READ_CHANNELS = [
+  "x",
+  "y",
+  "rotation",
+  "rotationX",
+  "rotationY",
+  "rotationZ",
+  "z",
+  "scale",
+  "transformPerspective",
+  "opacity",
+];
+
+/** Every property key the panel should read for an element: animated props + the
+ * always-read transform channels. */
+function collectPanelPropKeys(gsapAnimations: GsapAnimation[]): Set<string> {
+  const keys = new Set<string>(ALWAYS_READ_CHANNELS);
+  for (const anim of gsapAnimations) {
+    if (anim.keyframes) {
+      for (const kf of anim.keyframes.keyframes) {
+        for (const p of Object.keys(kf.properties)) keys.add(p);
+      }
+    }
+    for (const p of Object.keys(anim.properties)) keys.add(p);
+  }
+  return keys;
+}
+
 export function readGsapRuntimeValuesForPanel(
   gsapAnimId: string | null,
   gsapAnimations: GsapAnimation[],
@@ -505,15 +541,7 @@ export function readGsapRuntimeValuesForPanel(
     if (!gsap?.getProperty) return null;
     const el = iframe.contentDocument?.querySelector(selector);
     if (!el) return null;
-    const propKeys = new Set<string>();
-    for (const anim of gsapAnimations) {
-      if (anim.keyframes) {
-        for (const kf of anim.keyframes.keyframes) {
-          for (const p of Object.keys(kf.properties)) propKeys.add(p);
-        }
-      }
-      for (const p of Object.keys(anim.properties)) propKeys.add(p);
-    }
+    const propKeys = collectPanelPropKeys(gsapAnimations);
     const result: Record<string, number> = {};
     for (const prop of propKeys) {
       const v = Number(gsap.getProperty(el, prop));

package/src/components/editor/propertyPanelTimingSection.tsx

@@ -1,3 +1,4 @@
+import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
 import { Clock } from "../../icons/SystemIcons";
 import type { DomEditSelection } from "./domEditing";
 import { formatTimingValue, RESPONSIVE_GRID } from "./propertyPanelHelpers";
@@ -9,18 +10,45 @@ function parseTimingValue(input: string): number | null {
   return Number.isFinite(parsed) && parsed >= 0 ? parsed : null;
 }
 
+/**
+ * Derive a time range from the element's GSAP tweens (earliest start → latest
+ * end) so an element animated purely by GSAP — with no `data-start` /
+ * `data-duration` — still shows a meaningful Timing range instead of 0s.
+ */
+function deriveTimingFromAnimations(
+  animations: GsapAnimation[],
+): { start: number; duration: number } | null {
+  let lo = Infinity;
+  let hi = -Infinity;
+  for (const a of animations) {
+    const s = a.resolvedStart ?? (typeof a.position === "number" ? a.position : 0);
+    const d = a.duration ?? 0;
+    lo = Math.min(lo, s);
+    hi = Math.max(hi, s + d);
+  }
+  if (!Number.isFinite(lo) || !Number.isFinite(hi) || hi <= lo) return null;
+  return { start: lo, duration: hi - lo };
+}
+
 export function TimingSection({
   element,
+  animations = [],
   onSetAttribute,
 }: {
   element: DomEditSelection;
+  animations?: GsapAnimation[];
   onSetAttribute: (attr: string, value: string) => void | Promise<void>;
 }) {
-  const start = Number.parseFloat(element.dataAttributes.start ?? "0") || 0;
-  const duration =
+  const explicitStart = Number.parseFloat(element.dataAttributes.start ?? "0") || 0;
+  const explicitDuration =
     Number.parseFloat(
       element.dataAttributes.duration ?? element.dataAttributes["hf-authored-duration"] ?? "0",
     ) || 0;
+
+  // No authored clip timing → infer the range from the element's animations.
+  const derived = explicitDuration > 0 ? null : deriveTimingFromAnimations(animations);
+  const start = derived ? derived.start : explicitStart;
+  const duration = derived ? derived.duration : explicitDuration;
   const end = start + duration;
 
   const commitStart = (nextValue: string) => {
@@ -54,6 +82,11 @@ export function TimingSection({
           onCommit={commitDuration}
         />
       </div>
+      {derived && (
+        <p className="mt-2 text-[10px] leading-snug text-neutral-500">
+          Inferred from this element’s animation — edit to pin an explicit clip range.
+        </p>
+      )}
     </Section>
   );
 }