@hyperframes/studio 0.6.73 → 0.6.75

package/src/components/editor/AnimationCard.tsx

@@ -9,13 +9,29 @@ import {
   METHOD_LABELS,
   METHOD_TOOLTIPS,
   PERCENT_PROPS,
+  PROP_CONSTRAINTS,
   PROP_LABELS,
   PROP_TOOLTIPS,
   PROP_UNITS,
+  clampPropertyValue,
 } from "./gsapAnimationConstants";
 import { buildTweenSummary } from "./gsapAnimationHelpers";
 import { EaseCurveSection } from "./EaseCurveSection";
 const BOOLEAN_PROPS = new Set(["visibility"]);
+const STRING_PROPS = new Set(["filter", "clipPath"]);
+
+const FILTER_PRESETS = [
+  { label: "Blur", value: "blur(4px)" },
+  { label: "Bright", value: "brightness(1.5)" },
+  { label: "Gray", value: "grayscale(1)" },
+  { label: "None", value: "none" },
+];
+
+const CLIP_PATH_PRESETS = [
+  { label: "Circle", value: "circle(50% at 50% 50%)" },
+  { label: "Inset", value: "inset(10%)" },
+  { label: "None", value: "none" },
+];
 
 function isPercentProp(prop: string): boolean {
   return PERCENT_PROPS.has(prop);
@@ -27,7 +43,11 @@ function displayValue(prop: string, val: number | string): string {
 }
 
 function adjustedValue(prop: string, raw: string): string {
-  if (isPercentProp(prop)) return String(Math.max(0, Math.min(1, Number(raw) / 100)));
+  if (isPercentProp(prop)) return String(clampPropertyValue(prop, Number(raw) / 100));
+  const num = Number(raw);
+  if (!Number.isNaN(num) && PROP_CONSTRAINTS[prop]) {
+    return String(clampPropertyValue(prop, num));
+  }
   return raw;
 }
 
@@ -90,6 +110,48 @@ function PropertyRow({
     );
   }
 
+  if (STRING_PROPS.has(prop)) {
+    const presets =
+      prop === "filter" ? FILTER_PRESETS : prop === "clipPath" ? CLIP_PATH_PRESETS : [];
+    return (
+      <div className="flex flex-col gap-1">
+        <div className="flex items-center gap-1">
+          <div className="min-w-0 flex-1 flex items-center gap-2 px-2 py-1 rounded-lg bg-neutral-900 border border-neutral-800">
+            <span className="flex-shrink-0 text-[11px] font-medium text-neutral-500">
+              {PROP_LABELS[prop] ?? prop}
+            </span>
+            <input
+              type="text"
+              defaultValue={String(val)}
+              className="flex-1 bg-transparent text-[11px] text-neutral-200 outline-none"
+              onBlur={(e) => onCommit(e.currentTarget.value)}
+              onKeyDown={(e) => {
+                if (e.key === "Enter") {
+                  e.currentTarget.blur();
+                }
+              }}
+            />
+          </div>
+          <RemoveButton onClick={onRemove} title={removeTitle} />
+        </div>
+        {presets.length > 0 && (
+          <div className="flex gap-1 pl-1">
+            {presets.map((p) => (
+              <button
+                key={p.value}
+                type="button"
+                onClick={() => onCommit(p.value)}
+                className="px-1.5 py-0.5 rounded text-[9px] font-medium text-neutral-500 bg-neutral-800/50 hover:bg-neutral-800 hover:text-neutral-300 transition-colors"
+              >
+                {p.label}
+              </button>
+            ))}
+          </div>
+        )}
+      </div>
+    );
+  }
+
   return (
     <div className="flex items-center gap-1">
       <div className="min-w-0 flex-1">
@@ -292,8 +354,10 @@ export const AnimationCard = memo(function AnimationCard({
           {methodLabel}
         </span>
         <span className="text-[11px] font-medium text-neutral-400" title="When this effect plays">
-          {typeof animation.position === "number" ? `${animation.position}s` : animation.position} –{" "}
-          {typeof endTime === "number" ? `${endTime.toFixed(1)}s` : endTime}
+          {typeof animation.position === "number"
+            ? `${parseFloat(animation.position.toFixed(3))}s`
+            : animation.position}{" "}
+          – {typeof endTime === "number" ? `${parseFloat(endTime.toFixed(3))}s` : endTime}
         </span>
         <span className="ml-auto text-[10px] text-neutral-500" title={easeName}>
           {easeLabel}
@@ -344,7 +408,7 @@ export const AnimationCard = memo(function AnimationCard({
                 value={
                   typeof animation.position === "string"
                     ? animation.position
-                    : String(Math.max(0, animation.position))
+                    : String(parseFloat(Math.max(0, animation.position).toFixed(3)))
                 }
                 suffix={typeof animation.position === "number" ? "s" : undefined}
                 tooltip="When this effect begins on the timeline"

package/src/components/editor/DomEditOverlay.tsx

@@ -1,4 +1,5 @@
-import { memo, useMemo, useRef, type RefObject } from "react";
+import { memo, useMemo, useRef, useState, type RefObject } from "react";
+import { useMountEffect } from "../../hooks/useMountEffect";
 import { type DomEditSelection } from "./domEditing";
 import { resolveDomEditGroupOverlayRect, toOverlayRect } from "./domEditOverlayGeometry";
 import {
@@ -10,6 +11,8 @@ import {
 } from "./domEditOverlayGestures";
 import { useDomEditOverlayRects } from "./useDomEditOverlayRects";
 import { createDomEditOverlayGestureHandlers } from "./useDomEditOverlayGestures";
+import { SnapGuideOverlay, type SnapGuidesState } from "./SnapGuideOverlay";
+import { GridOverlay } from "./GridOverlay";
 
 // Re-exports for external consumers — preserving existing import paths.
 export {
@@ -61,6 +64,8 @@ interface DomEditOverlayProps {
     next: { width: number; height: number },
   ) => Promise<void> | void;
   onRotationCommit: (selection: DomEditSelection, next: { angle: number }) => Promise<void> | void;
+  gridVisible?: boolean;
+  gridSpacing?: number;
 }
 
 export const DomEditOverlay = memo(function DomEditOverlay({
@@ -75,6 +80,8 @@ export const DomEditOverlay = memo(function DomEditOverlay({
   onCanvasPointerLeave,
   onSelectionChange,
   onBlockedMove,
+  gridVisible = false,
+  gridSpacing = 50,
   onManualDragStart,
   onPathOffsetCommit,
   onGroupPathOffsetCommit,
@@ -89,6 +96,7 @@ export const DomEditOverlay = memo(function DomEditOverlay({
   const suppressNextBoxClickRef = useRef(false);
   const suppressNextBoxMouseDownRef = useRef(false);
   const suppressNextOverlayMouseDownRef = useRef(false);
+  const snapGuidesRef = useRef<SnapGuidesState | null>(null);
   const rafPausedRef = useRef(false);
 
   const selectionRef = useRef(selection);
@@ -136,6 +144,50 @@ export const DomEditOverlay = memo(function DomEditOverlay({
     rafPausedRef,
   });
 
+  const [compRect, setCompRect] = useState({
+    left: 0,
+    top: 0,
+    width: 0,
+    height: 0,
+    scaleX: 1,
+    scaleY: 1,
+  });
+  useMountEffect(() => {
+    let frame = 0;
+    // fallow-ignore-next-line complexity
+    const update = () => {
+      frame = requestAnimationFrame(update);
+      const iframe = iframeRef.current;
+      const overlayEl = overlayRef.current;
+      if (!iframe || !overlayEl) return;
+      const iRect = iframe.getBoundingClientRect();
+      const oRect = overlayEl.getBoundingClientRect();
+      const left = iRect.left - oRect.left;
+      const top = iRect.top - oRect.top;
+      if (iRect.width <= 0 || iRect.height <= 0) return;
+      const doc = iframe.contentDocument;
+      const root = doc?.querySelector<HTMLElement>("[data-composition-id]") ?? doc?.documentElement;
+      const dw = Number.parseFloat(root?.getAttribute("data-width") ?? "");
+      const dh = Number.parseFloat(root?.getAttribute("data-height") ?? "");
+      const scaleX = dw > 0 ? iRect.width / dw : 1;
+      const scaleY = dh > 0 ? iRect.height / dh : 1;
+      setCompRect((prev) => {
+        if (
+          Math.abs(prev.left - left) < 0.5 &&
+          Math.abs(prev.top - top) < 0.5 &&
+          Math.abs(prev.width - iRect.width) < 0.5 &&
+          Math.abs(prev.height - iRect.height) < 0.5 &&
+          Math.abs(prev.scaleX - scaleX) < 0.001 &&
+          Math.abs(prev.scaleY - scaleY) < 0.001
+        )
+          return prev;
+        return { left, top, width: iRect.width, height: iRect.height, scaleX, scaleY };
+      });
+    };
+    frame = requestAnimationFrame(update);
+    return () => cancelAnimationFrame(frame);
+  });
+
   const gestures = createDomEditOverlayGestureHandlers({
     overlayRef,
     iframeRef,
@@ -158,6 +210,7 @@ export const DomEditOverlay = memo(function DomEditOverlay({
     onRotationCommitRef,
     onCanvasPointerMoveRef,
     onCanvasMouseDown,
+    snapGuidesRef,
   });
 
   const selectionKey = useMemo(() => {
@@ -192,6 +245,7 @@ export const DomEditOverlay = memo(function DomEditOverlay({
     }
   };
 
+  // fallow-ignore-next-line complexity
   const handleOverlayPointerDown = (event: React.PointerEvent<HTMLDivElement>) => {
     if (!allowCanvasMovement || event.button !== 0) return;
     if (event.shiftKey) {
@@ -387,6 +441,21 @@ export const DomEditOverlay = memo(function DomEditOverlay({
           </div>
         </>
       )}
+      <GridOverlay
+        visible={gridVisible}
+        spacing={gridSpacing}
+        scaleX={compRect.scaleX}
+        scaleY={compRect.scaleY}
+        compositionLeft={compRect.left}
+        compositionTop={compRect.top}
+        compositionWidth={compRect.width}
+        compositionHeight={compRect.height}
+      />
+      <SnapGuideOverlay
+        snapGuidesRef={snapGuidesRef}
+        overlayWidth={compRect.width}
+        overlayHeight={compRect.height}
+      />
     </div>
   );
 });

package/src/components/editor/GridOverlay.tsx

@@ -0,0 +1,50 @@
+// fallow-ignore-file unused-file
+import { memo } from "react";
+
+interface GridOverlayProps {
+  visible: boolean;
+  spacing: number;
+  scaleX: number;
+  scaleY: number;
+  compositionLeft: number;
+  compositionTop: number;
+  compositionWidth: number;
+  compositionHeight: number;
+}
+
+// fallow-ignore-next-line complexity
+export const GridOverlay = memo(function GridOverlay({
+  visible,
+  spacing,
+  scaleX,
+  scaleY,
+  compositionLeft,
+  compositionTop,
+  compositionWidth,
+  compositionHeight,
+}: GridOverlayProps) {
+  if (!visible || spacing <= 0) return null;
+
+  const overlaySpacingX = spacing * scaleX;
+  const overlaySpacingY = spacing * scaleY;
+
+  if (overlaySpacingX < 4 || overlaySpacingY < 4) return null;
+
+  return (
+    <div
+      aria-hidden="true"
+      className="pointer-events-none absolute"
+      style={{
+        left: compositionLeft,
+        top: compositionTop,
+        width: compositionWidth,
+        height: compositionHeight,
+        backgroundImage: [
+          `repeating-linear-gradient(90deg, rgba(255,255,255,0.12) 0px, rgba(255,255,255,0.12) 1px, transparent 1px, transparent ${overlaySpacingX}px)`,
+          `repeating-linear-gradient(0deg, rgba(255,255,255,0.12) 0px, rgba(255,255,255,0.12) 1px, transparent 1px, transparent ${overlaySpacingY}px)`,
+        ].join(", "),
+        backgroundSize: `${overlaySpacingX}px ${overlaySpacingY}px`,
+      }}
+    />
+  );
+});

package/src/components/editor/KeyframeDiamond.tsx

@@ -0,0 +1,49 @@
+import { memo } from "react";
+
+export type DiamondState = "active" | "inactive" | "ghost";
+
+interface KeyframeDiamondProps {
+  state: DiamondState;
+  onClick: () => void;
+  title?: string;
+  size?: number;
+}
+
+// fallow-ignore-next-line complexity
+export const KeyframeDiamond = memo(function KeyframeDiamond({
+  state,
+  onClick,
+  title,
+  size = 10,
+}: KeyframeDiamondProps) {
+  const isFilled = state === "active";
+  const opacity = state === "ghost" ? 0.25 : state === "inactive" ? 0.6 : 1;
+  const color = state === "active" ? "#3b82f6" : "#a3a3a3";
+
+  return (
+    <button
+      type="button"
+      onClick={(e) => {
+        e.stopPropagation();
+        onClick();
+      }}
+      className="flex-shrink-0 p-0.5 transition-opacity hover:opacity-100"
+      style={{ color, opacity }}
+      title={title}
+    >
+      <svg width={size} height={size} viewBox="0 0 10 10">
+        <rect
+          x="5"
+          y="0.7"
+          width="6"
+          height="6"
+          rx="1"
+          transform="rotate(45 5 0.7)"
+          fill={isFilled ? "currentColor" : "none"}
+          stroke="currentColor"
+          strokeWidth="1.2"
+        />
+      </svg>
+    </button>
+  );
+});

package/src/components/editor/KeyframeNavigation.tsx

@@ -0,0 +1,139 @@
+import { memo } from "react";
+import { KeyframeDiamond, type DiamondState } from "./KeyframeDiamond";
+
+interface KeyframeNavigationProps {
+  property: string;
+  /** All keyframes for this element's tween, or null if no keyframes exist */
+  keyframes: Array<{
+    percentage: number;
+    properties: Record<string, number | string>;
+    ease?: string;
+  }> | null;
+  /** Current playhead percentage within the element's lifetime (0-100) */
+  currentPercentage: number;
+  onSeek: (percentage: number) => void;
+  onAddKeyframe: (percentage: number) => void;
+  onRemoveKeyframe: (percentage: number) => void;
+  onConvertToKeyframes: () => void;
+}
+
+const TOLERANCE = 0.5;
+
+function ArrowLeft({ disabled }: { disabled: boolean }) {
+  return (
+    <svg
+      width="6"
+      height="10"
+      viewBox="0 0 6 10"
+      fill="none"
+      style={{ opacity: disabled ? 0.25 : 1 }}
+    >
+      <path
+        d="M5 1L1 5L5 9"
+        stroke="#a3a3a3"
+        strokeWidth="1.4"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      />
+    </svg>
+  );
+}
+
+function ArrowRight({ disabled }: { disabled: boolean }) {
+  return (
+    <svg
+      width="6"
+      height="10"
+      viewBox="0 0 6 10"
+      fill="none"
+      style={{ opacity: disabled ? 0.25 : 1 }}
+    >
+      <path
+        d="M1 1L5 5L1 9"
+        stroke="#a3a3a3"
+        strokeWidth="1.4"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      />
+    </svg>
+  );
+}
+
+// fallow-ignore-next-line complexity
+export const KeyframeNavigation = memo(function KeyframeNavigation({
+  property,
+  keyframes,
+  currentPercentage,
+  onSeek,
+  onAddKeyframe,
+  onRemoveKeyframe,
+  onConvertToKeyframes,
+}: KeyframeNavigationProps) {
+  // Find keyframes that contain this property
+  const propertyKeyframes = keyframes?.filter((kf) => property in kf.properties) ?? [];
+
+  const prevKf =
+    propertyKeyframes.filter((kf) => kf.percentage < currentPercentage - TOLERANCE).at(-1) ?? null;
+
+  const nextKf =
+    propertyKeyframes.find((kf) => kf.percentage > currentPercentage + TOLERANCE) ?? null;
+
+  const atCurrent =
+    propertyKeyframes.find((kf) => Math.abs(kf.percentage - currentPercentage) <= TOLERANCE) ??
+    null;
+
+  // Diamond state
+  let diamondState: DiamondState;
+  if (!keyframes || keyframes.length === 0) {
+    diamondState = "ghost";
+  } else if (atCurrent) {
+    diamondState = "active";
+  } else if (propertyKeyframes.length > 0) {
+    diamondState = "inactive";
+  } else {
+    diamondState = "ghost";
+  }
+
+  const handleDiamondClick = () => {
+    if (diamondState === "ghost") {
+      onConvertToKeyframes();
+    } else if (diamondState === "active") {
+      onRemoveKeyframe(currentPercentage);
+    } else {
+      onAddKeyframe(currentPercentage);
+    }
+  };
+
+  return (
+    <div className="flex h-5 items-center gap-0.5">
+      <button
+        type="button"
+        disabled={!prevKf}
+        onClick={() => prevKf && onSeek(prevKf.percentage)}
+        className="flex h-5 w-3 items-center justify-center disabled:cursor-default"
+      >
+        <ArrowLeft disabled={!prevKf} />
+      </button>
+      <KeyframeDiamond
+        state={diamondState}
+        onClick={handleDiamondClick}
+        size={9}
+        title={
+          diamondState === "ghost"
+            ? `Convert ${property} to keyframes`
+            : diamondState === "active"
+              ? `Remove ${property} keyframe`
+              : `Add ${property} keyframe`
+        }
+      />
+      <button
+        type="button"
+        disabled={!nextKf}
+        onClick={() => nextKf && onSeek(nextKf.percentage)}
+        className="flex h-5 w-3 items-center justify-center disabled:cursor-default"
+      >
+        <ArrowRight disabled={!nextKf} />
+      </button>
+    </div>
+  );
+});

package/src/components/editor/LayersPanel.test.ts

@@ -0,0 +1,135 @@
+// @vitest-environment happy-dom
+
+import { describe, expect, it } from "vitest";
+import { Window } from "happy-dom";
+import type { DomEditLayerItem } from "./domEditingTypes";
+import { sortLayersByZIndex } from "./LayersPanel";
+import { isLayerDraggable } from "./useLayerDrag";
+
+function makeLayer(
+  overrides: Partial<DomEditLayerItem> & { zIndex?: string; locked?: boolean },
+): DomEditLayerItem {
+  const win = new Window();
+  const doc = win.document;
+  const parent = doc.createElement("div") as unknown as HTMLElement;
+  if (overrides.locked) {
+    (parent as unknown as Element).setAttribute("data-timeline-locked", "true");
+  }
+  const el = doc.createElement("div") as unknown as HTMLElement;
+  parent.appendChild(el as unknown as Node);
+  if (overrides.zIndex != null) {
+    (el as unknown as { style: { zIndex: string } }).style.zIndex = overrides.zIndex;
+  }
+  if (overrides.id) {
+    (el as unknown as Element).setAttribute("id", overrides.id);
+  }
+  return {
+    key: overrides.key ?? `layer-${Math.random()}`,
+    element: el,
+    label: overrides.label ?? "div",
+    tagName: overrides.tagName ?? "div",
+    depth: overrides.depth ?? 0,
+    childCount: overrides.childCount ?? 0,
+    id: overrides.id,
+    selector: overrides.selector,
+    selectorIndex: overrides.selectorIndex,
+    sourceFile: overrides.sourceFile ?? "index.html",
+  };
+}
+
+describe("sortLayersByZIndex", () => {
+  it("sorts siblings by z-index descending", () => {
+    const a = makeLayer({ key: "a", zIndex: "1", depth: 0 });
+    const b = makeLayer({ key: "b", zIndex: "3", depth: 0 });
+    const c = makeLayer({ key: "c", zIndex: "2", depth: 0 });
+
+    const sorted = sortLayersByZIndex([a, b, c]);
+    expect(sorted.map((l) => l.key)).toEqual(["b", "c", "a"]);
+  });
+
+  it("preserves DOM order (reversed) for siblings with auto z-index", () => {
+    const a = makeLayer({ key: "a", depth: 0 });
+    const b = makeLayer({ key: "b", depth: 0 });
+    const c = makeLayer({ key: "c", depth: 0 });
+
+    const sorted = sortLayersByZIndex([a, b, c]);
+    expect(sorted.map((l) => l.key)).toEqual(["c", "b", "a"]);
+  });
+
+  it("sorts explicit z-index above auto, auto elements maintain reversed DOM order", () => {
+    const a = makeLayer({ key: "a", depth: 0 });
+    const b = makeLayer({ key: "b", zIndex: "5", depth: 0 });
+    const c = makeLayer({ key: "c", depth: 0 });
+
+    const sorted = sortLayersByZIndex([a, b, c]);
+    expect(sorted.map((l) => l.key)).toEqual(["b", "c", "a"]);
+  });
+
+  it("sorts children independently of their parent's siblings", () => {
+    const parent1 = makeLayer({ key: "p1", zIndex: "1", depth: 0, childCount: 2 });
+    const child1a = makeLayer({ key: "c1a", zIndex: "3", depth: 1 });
+    const child1b = makeLayer({ key: "c1b", zIndex: "1", depth: 1 });
+    const parent2 = makeLayer({ key: "p2", zIndex: "2", depth: 0, childCount: 1 });
+    const child2a = makeLayer({ key: "c2a", zIndex: "1", depth: 1 });
+
+    const sorted = sortLayersByZIndex([parent1, child1a, child1b, parent2, child2a]);
+    expect(sorted.map((l) => l.key)).toEqual(["p2", "c2a", "p1", "c1a", "c1b"]);
+  });
+
+  it("handles single-element groups without crash", () => {
+    const single = makeLayer({ key: "only", zIndex: "5", depth: 0 });
+    const sorted = sortLayersByZIndex([single]);
+    expect(sorted).toEqual([single]);
+  });
+
+  it("returns empty array for empty input", () => {
+    expect(sortLayersByZIndex([])).toEqual([]);
+  });
+
+  it("handles duplicate z-index values with reverse DOM order tiebreak", () => {
+    const a = makeLayer({ key: "a", zIndex: "2", depth: 0 });
+    const b = makeLayer({ key: "b", zIndex: "1", depth: 0 });
+    const c = makeLayer({ key: "c", zIndex: "2", depth: 0 });
+
+    const sorted = sortLayersByZIndex([a, b, c]);
+    expect(sorted.map((l) => l.key)).toEqual(["c", "a", "b"]);
+  });
+
+  it("preserves deeply nested structure with sorting at each level", () => {
+    const root = makeLayer({ key: "root", depth: 0, childCount: 2 });
+    const a = makeLayer({ key: "a", zIndex: "1", depth: 1, childCount: 2 });
+    const a1 = makeLayer({ key: "a1", zIndex: "10", depth: 2 });
+    const a2 = makeLayer({ key: "a2", zIndex: "20", depth: 2 });
+    const b = makeLayer({ key: "b", zIndex: "2", depth: 1 });
+
+    const sorted = sortLayersByZIndex([root, a, a1, a2, b]);
+    expect(sorted.map((l) => l.key)).toEqual(["root", "b", "a", "a2", "a1"]);
+  });
+});
+
+describe("isLayerDraggable", () => {
+  it("returns false for layers without id or selector", () => {
+    const layer = makeLayer({ key: "anon" });
+    expect(isLayerDraggable(layer)).toBe(false);
+  });
+
+  it("returns true for layers with an id", () => {
+    const layer = makeLayer({ key: "with-id", id: "my-el" });
+    expect(isLayerDraggable(layer)).toBe(true);
+  });
+
+  it("returns true for layers with a selector", () => {
+    const layer = makeLayer({ key: "with-sel", selector: ".my-class" });
+    expect(isLayerDraggable(layer)).toBe(true);
+  });
+
+  it("returns false for layers inside a locked composition", () => {
+    const layer = makeLayer({ key: "locked", id: "locked-el", locked: true });
+    expect(isLayerDraggable(layer)).toBe(false);
+  });
+
+  it("returns true for layers with id and no locked ancestor", () => {
+    const layer = makeLayer({ key: "free", id: "free-el" });
+    expect(isLayerDraggable(layer)).toBe(true);
+  });
+});