@hyperframes/studio 0.7.92 → 0.7.93

package/src/player/components/TimelineClipDiamonds.tsx

@@ -10,10 +10,10 @@ import {
   subscribeTimelineKeyframeRetimePreview,
   type TimelineKeyframeRetimeHandle,
 } from "./useTimelineKeyframeHandlers";
+import { timelineKeyframeFocusId } from "./timelineNavigationIdentity";
 import {
   DIAMOND_RATIO,
-  KF_MAX_PCT,
-  KF_MIN_PCT,
+  keyframeTimeLabel,
   keyframeTarget,
   type TimelineClipDiamondsProps,
   type TimelineDiamondKeyframe,
@@ -68,13 +68,15 @@ export const TimelineDiamondLane = memo(function TimelineDiamondLane({
   keyframesData,
   clipWidthPx,
   clipHeightPx,
-  clipDuration,
   beatsActive,
   accentColor,
   isSelected,
   currentPercentage,
   elementId,
+  clipStart = 0,
+  clipDuration = 0,
   selectedKeyframes,
+  rovingTargetId = null,
   onClickKeyframe,
   onShiftClickKeyframe,
   onContextMenuKeyframe,
@@ -140,9 +142,14 @@ export const TimelineDiamondLane = memo(function TimelineDiamondLane({
   // (2.5.8) minimum and still fits the 28px lane. Beat-strip lanes keep the
   // shrunken box: 24px there would reach up into the beat strip.
   const hitHeight = beatsActive ? diamondSize : 24;
-  const sorted = keyframesData.keyframes
-    .filter((kf) => kf.percentage >= KF_MIN_PCT && kf.percentage <= KF_MAX_PCT)
-    .sort((a, b) => a.percentage - b.percentage);
+  // Keyframes authored outside the element's visible clip window are parked at
+  // the boundary rather than hidden: dropping them made the lane's count
+  // disagree with its diamonds and left users unable to inspect or remove state
+  // that still affects the clip once it appears.
+  const sorted = [...keyframesData.keyframes].sort((a, b) => a.percentage - b.percentage);
+  const beforeClip = sorted.filter((keyframe) => keyframe.percentage < 0);
+  const afterClip = sorted.filter((keyframe) => keyframe.percentage > 100);
+  const boundaryStep = Math.max(6, Math.round(diamondSize * 0.55));
   // The neighbour clamp bounds a dragged diamond between its immediate siblings
   // so a retime can't reorder the tween. Siblings means "keyframes of the SAME
   // tween": a merged row interleaves several animations, and two of them
@@ -175,16 +182,30 @@ export const TimelineDiamondLane = memo(function TimelineDiamondLane({
       clipPcts: row.map((s) => s.clipPct),
     });
   }
-  const centerXOf = (percentage: number) =>
-    Math.max(0, Math.min(clipWidthPx, (percentage / 100) * clipWidthPx));
+  const centerXOf = (keyframe: TimelineDiamondKeyframe, percentage = keyframe.percentage) => {
+    if (percentage < 0) {
+      const rank = beforeClip.indexOf(keyframe);
+      return -(beforeClip.length - Math.max(0, rank)) * boundaryStep;
+    }
+    if (percentage > 100) {
+      const rank = afterClip.indexOf(keyframe);
+      return clipWidthPx + (Math.max(0, rank) + 1) * boundaryStep;
+    }
+    return (percentage / 100) * clipWidthPx;
+  };
   // One record per diamond, carrying its own geometry, so the connector and
   // button passes below read neighbours as values instead of index lookups.
   const markers = sorted.map((keyframe, index) => {
-    const centerX = centerXOf(keyframe.percentage);
+    const centerX = centerXOf(keyframe);
+    // Parked diamonds sit on their own boundary spacing, so the in-clip
+    // neighbour-gap shrink would only make them unreadable.
+    if (keyframe.percentage < 0 || keyframe.percentage > 100) {
+      return { keyframe, centerX, hitWidth: diamondSize, visualSize: diamondSize };
+    }
     const previous = sorted[index - 1];
     const next = sorted[index + 1];
-    const previousGap = previous ? centerX - centerXOf(previous.percentage) : Infinity;
-    const nextGap = next ? centerXOf(next.percentage) - centerX : Infinity;
+    const previousGap = previous ? centerX - centerXOf(previous) : Infinity;
+    const nextGap = next ? centerXOf(next) - centerX : Infinity;
     const nearestGap = Math.max(1, Math.min(previousGap, nextGap));
     const hitWidth = Math.min(diamondSize, nearestGap);
     return {
@@ -226,6 +247,10 @@ export const TimelineDiamondLane = memo(function TimelineDiamondLane({
       <TimelineDiamondConnectors
         markers={markers}
         centerY={centerY}
+        elementId={elementId}
+        clipStart={clipStart}
+        clipDuration={clipDuration}
+        rovingTargetId={rovingTargetId}
         baseColor={baseColor}
         baseOpacity={baseOpacity}
         groupAware={groupAware}
@@ -237,7 +262,9 @@ export const TimelineDiamondLane = memo(function TimelineDiamondLane({
       {markers.map((marker, i) => {
         const kf = marker.keyframe;
         const target = keyframeTarget(kf);
+        const focusId = timelineKeyframeFocusId(elementId, target);
         const kfKey = timelineKeyframeSelectionKey(elementId, target);
+        const boundary = kf.percentage < 0 ? "before" : kf.percentage > 100 ? "after" : null;
         // Clamp against this keyframe's own tween, not the whole merged row.
         const siblingRow = siblingRows.get(kf.animationId);
         const siblingClipPcts = siblingRow?.clipPcts ?? [];
@@ -249,7 +276,7 @@ export const TimelineDiamondLane = memo(function TimelineDiamondLane({
         // The 0% diamond's left half lands in the reserved left gutter (the
         // content origin is inset past the label column, Figma-style) so it stays
         // fully visible instead of being clipped by the sticky label column.
-        const leftPx = (renderPct / 100) * clipWidthPx - marker.hitWidth / 2;
+        const leftPx = centerXOf(kf, renderPct) - marker.hitWidth / 2;
         const isKfSelected = selectedKeyframes.has(kfKey);
         const atPlayhead = kf === playheadKeyframe;
         const isHighlighted = isKfSelected || atPlayhead;
@@ -306,6 +333,7 @@ export const TimelineDiamondLane = memo(function TimelineDiamondLane({
             key={`${kf.animationId ?? i}:${kf.propertyGroup ?? ""}:${kf.tweenPercentage ?? kf.percentage}`}
             type="button"
             className="absolute"
+            data-timeline-focus-id={focusId}
             data-keyframe-group={groupAware ? kf.propertyGroup : undefined}
             data-keyframe-percentage={
               groupAware ? (kf.tweenPercentage ?? kf.percentage) : undefined
@@ -313,6 +341,9 @@ export const TimelineDiamondLane = memo(function TimelineDiamondLane({
             data-keyframe-at-playhead={String(atPlayhead)}
             data-keyframe-selected={String(isKfSelected)}
             aria-current={atPlayhead ? "time" : undefined}
+            data-keyframe-outside-clip={boundary ?? undefined}
+            tabIndex={focusId === rovingTargetId ? 0 : -1}
+            aria-label={`${kf.propertyGroup ?? "Motion"} keyframe at ${keyframeTimeLabel(clipStart, clipDuration, kf.percentage)}${boundary ? ` (${boundary} clip)` : ""}`}
             aria-pressed={isKfSelected}
             style={{
               left: leftPx,
@@ -335,6 +366,15 @@ export const TimelineDiamondLane = memo(function TimelineDiamondLane({
             onPointerDown={onPointerDown}
             onPointerMove={canDrag ? (e) => retimeHandleRef.current?.update(e) : undefined}
             onPointerUp={onPointerUp}
+            // Keyboard activation only (detail 0): pointer presses already
+            // resolve through the pointerup path above.
+            onClick={(e) => {
+              if (e.detail !== 0) return;
+              e.stopPropagation();
+              suppressNextClick();
+              if (e.shiftKey) onShiftClickKeyframe?.(target);
+              else onClickKeyframe?.(target);
+            }}
             onPointerCancel={
               canDrag
                 ? (e) => {
@@ -348,7 +388,7 @@ export const TimelineDiamondLane = memo(function TimelineDiamondLane({
               e.stopPropagation();
               onContextMenuKeyframe?.(e, target);
             }}
-            title={`${roundPct(kf.percentage)}%`}
+            title={`${roundPct(kf.percentage)}%${boundary ? ` · ${boundary} clip` : ""}`}
           >
             <svg
               width={marker.visualSize}

package/src/player/components/TimelineCompactDiamonds.tsx

@@ -0,0 +1,84 @@
+import type { KeyframeCacheEntry, TimelineElement } from "../store/playerStore";
+import { CLIP_Y } from "./timelineLayout";
+import type { TimelineLaneBaseProps } from "./timelineLaneProps";
+import { TimelineClipDiamonds } from "./TimelineClipDiamonds";
+
+interface TimelineCompactDiamondsProps extends Pick<
+  TimelineLaneBaseProps,
+  | "currentTime"
+  | "selectedKeyframes"
+  | "onClickKeyframe"
+  | "onShiftClickKeyframe"
+  | "onContextMenuKeyframe"
+  | "onMoveKeyframe"
+  | "onSelectSegment"
+  | "suppressClickRef"
+> {
+  element: TimelineElement;
+  elementId: string;
+  keyframesData: KeyframeCacheEntry;
+  pixelsPerSecond: number;
+  rowHeight: number;
+  beatsActive: boolean;
+  accentColor: string;
+  isSelected: boolean;
+  rovingTargetId: string | null;
+}
+
+/** Inline diamonds shown while the clip's property lanes are collapsed. */
+export function TimelineCompactDiamonds({
+  element,
+  elementId,
+  keyframesData,
+  pixelsPerSecond,
+  rowHeight,
+  beatsActive,
+  accentColor,
+  isSelected,
+  currentTime,
+  selectedKeyframes,
+  rovingTargetId,
+  onClickKeyframe,
+  onShiftClickKeyframe,
+  onContextMenuKeyframe,
+  onMoveKeyframe,
+  onSelectSegment,
+  suppressClickRef,
+}: TimelineCompactDiamondsProps) {
+  const width = Math.max(element.duration * pixelsPerSecond, 4);
+  return (
+    <div
+      className="absolute pointer-events-none"
+      style={{
+        left: element.start * pixelsPerSecond,
+        top: CLIP_Y,
+        width,
+        height: rowHeight - 2 * CLIP_Y,
+        zIndex: isSelected ? 11 : 6,
+      }}
+    >
+      <TimelineClipDiamonds
+        keyframesData={keyframesData}
+        clipWidthPx={width}
+        clipHeightPx={rowHeight - 2 * CLIP_Y}
+        beatsActive={beatsActive}
+        accentColor={accentColor}
+        isSelected={isSelected}
+        currentPercentage={
+          element.duration > 0 ? ((currentTime - element.start) / element.duration) * 100 : 0
+        }
+        elementId={elementId}
+        clipStart={element.start}
+        clipDuration={element.duration}
+        selectedKeyframes={selectedKeyframes}
+        rovingTargetId={rovingTargetId}
+        onClickKeyframe={(_id, target) => onClickKeyframe?.(element, target)}
+        onShiftClickKeyframe={onShiftClickKeyframe}
+        onContextMenuKeyframe={onContextMenuKeyframe}
+        onMoveKeyframe={onMoveKeyframe}
+        onSelectSegment={onSelectSegment}
+        suppressClickRef={suppressClickRef}
+      />
+    </div>
+  );
+}

package/src/player/components/TimelineDiamondConnectors.tsx

@@ -2,7 +2,8 @@ import { Fragment, useRef } from "react";
 import { KEYFRAME_DRAG_THRESHOLD_PX } from "../../components/editor/keyframeDrag";
 import { MiniCurveSvg } from "../../components/editor/EaseCurveSection";
 import type { TimelineKeyframeTarget } from "./timelineKeyframeIdentity";
-import type { TimelineDiamondKeyframe } from "./TimelineClipDiamonds";
+import { keyframeTimeLabel, type TimelineDiamondKeyframe } from "./timelineDiamondTypes";
+import { timelineEaseFocusId } from "./timelineNavigationIdentity";
 
 /** One diamond's geometry within its row, as computed by the lane. */
 export interface TimelineDiamondMarker {
@@ -21,6 +22,10 @@ export interface TimelineDiamondMarker {
 export function TimelineDiamondConnectors({
   markers,
   centerY,
+  elementId,
+  clipStart,
+  clipDuration,
+  rovingTargetId,
   baseColor,
   baseOpacity,
   groupAware,
@@ -30,6 +35,11 @@ export function TimelineDiamondConnectors({
 }: {
   markers: readonly TimelineDiamondMarker[];
   centerY: number;
+  elementId: string;
+  clipStart: number;
+  clipDuration: number;
+  /** Focus id of the one timeline control currently in the tab order. */
+  rovingTargetId: string | null;
   baseColor: string;
   baseOpacity: number;
   groupAware: boolean;
@@ -48,6 +58,7 @@ export function TimelineDiamondConnectors({
         if (x2 - x1 < 1) return null;
         const connectorLeft = x1 + previous.visualSize / 2;
         const connectorWidth = x2 - x1 - previous.visualSize / 2 - marker.visualSize / 2;
+        const target = keyframeTarget(kf);
         return (
           <Fragment key={`line-${i}-${previous.keyframe.percentage}-${kf.percentage}`}>
             <div
@@ -70,7 +81,14 @@ export function TimelineDiamondConnectors({
                 width={x2 - x1}
                 centerY={centerY}
                 ease={kf.ease ?? globalEase}
-                target={keyframeTarget(kf)}
+                target={target}
+                focusId={timelineEaseFocusId(elementId, target)}
+                rovingTargetId={rovingTargetId}
+                afterLabel={keyframeTimeLabel(
+                  clipStart,
+                  clipDuration,
+                  previous.keyframe.percentage,
+                )}
                 // connectorWidth is the clear span between the two diamonds'
                 // edges, so a 24x24 target centred in it overhangs a diamond as
                 // soon as the span is narrower than 24. The segment wrapper sits
@@ -111,6 +129,9 @@ function SegmentEaseControl({
   centerY,
   ease,
   target,
+  focusId,
+  rovingTargetId,
+  afterLabel,
   roomForFullTarget,
   onSelectSegment,
 }: {
@@ -119,6 +140,11 @@ function SegmentEaseControl({
   centerY: number;
   ease: string;
   target: TimelineKeyframeTarget;
+  focusId: string;
+  /** Focus id of the one timeline control currently in the tab order. */
+  rovingTargetId: string | null;
+  /** Time label of the keyframe this segment starts at, for the accessible name. */
+  afterLabel: string;
   roomForFullTarget: boolean;
   onSelectSegment: (target: TimelineKeyframeTarget) => void;
 }) {
@@ -151,7 +177,9 @@ function SegmentEaseControl({
       <button
         type="button"
         data-keyframe-ease-button=""
-        aria-label={`Edit ${ease} easing`}
+        data-timeline-focus-id={focusId}
+        tabIndex={focusId === rovingTargetId ? 0 : -1}
+        aria-label={`Edit ${ease} easing after ${afterLabel}`}
         title={`Edit ${ease} easing`}
         // A visible 24x24 badge would collide with the diamonds either side, so
         // the WCAG 2.2 (2.5.8) target is met with a centered transparent

package/src/player/components/TimelineLanes.test.tsx

@@ -9,6 +9,7 @@ import { getTrackStyle } from "./timelineIcons";
 import { defaultTimelineTheme } from "./timelineTheme";
 import { TRACK_H, getTimelineRowGeometry } from "./timelineLayout";
 import { createTimelineClipIndex } from "../lib/timelineClipIndex";
+import { buildTimelineLogicalRows } from "./timelineKeyboardNavigation";
 import { usePlayerStore, type TimelineElement } from "../store/playerStore";
 import type { MultiDragPreviewInput } from "./timelineMultiDragPreview";
 import type { TimelineEditCallbacks } from "./timelineCallbacks";
@@ -26,6 +27,17 @@ afterEach(() => {
 const TRACK_A = 1 / 6;
 const TRACK_B = 0.5;
 
+/** Every string a screen reader or a sighted user actually reads. */
+function visibleText(host: HTMLElement): string {
+  return host.textContent ?? "";
+}
+
+function ariaLabels(host: HTMLElement): string {
+  return Array.from(host.querySelectorAll("[aria-label]"))
+    .map((el) => el.getAttribute("aria-label") ?? "")
+    .join(" ");
+}
+
 function element(id: string, track: number): TimelineElement {
   return { id, label: id, tag: "div", start: 0, duration: 2, track };
 }
@@ -94,6 +106,16 @@ function renderLanes(options: RenderLanesOptions = {}): {
           rowGeometry={getTimelineRowGeometry(rowHeights)}
           virtualRows={displayTrackOrder.map((_, index) => ({ index, rowKey: index }))}
           rowsVirtualized={false}
+          focusedTargetId={null}
+          logicalRows={buildTimelineLogicalRows({
+            tracks,
+            displayTrackOrder,
+            laneCounts,
+            selectedElementId: null,
+            selectedElementIds: next.selectedElementIds ?? new Set(),
+            expandedClipIds: new Set(next.expandedClipIds ?? []),
+            gsapAnimations,
+          })}
           clipIndex={createTimelineClipIndex(tracks)}
           renderTimeRange={{ start: 0, end: Number.POSITIVE_INFINITY }}
           pinnedClipIdentities={new Set()}
@@ -152,7 +174,11 @@ describe("TimelineLanes track numbering", () => {
 
     expect(visibilityLabels(view.host)).toEqual(["Hide track 1", "Hide track 2"]);
     expect(view.host.querySelectorAll("[data-timeline-row]")).toHaveLength(2);
-    expect(view.host.innerHTML).not.toContain("0.16666666666666666");
+    // Only what a user reads. The fractional key still identifies the row in
+    // `id` / `data-` attributes, which is exactly where an opaque sort key
+    // belongs.
+    expect(visibleText(view.host)).not.toContain("0.16666666666666666");
+    expect(ariaLabels(view.host)).not.toContain("0.16666666666666666");
     act(() => view.root.unmount());
   });
 
@@ -179,11 +205,12 @@ describe("TimelineLanes track numbering", () => {
       onContextMenuLane,
     });
 
-    // Row children: [sticky header column, time-mapped track content]. The rows
-    // sit inside the lanes list, which is what carries the virtualization
-    // positioning context.
-    const rows = Array.from(view.host.querySelectorAll('[role="listitem"]'));
-    const secondTrackContent = rows[1]?.children.item(1);
+    // The lane's own content cell: the track row's second child, after the
+    // sticky header column.
+    const secondTrackContent = view.host
+      .querySelectorAll("[data-timeline-row]")[1]
+      ?.querySelector('[role="row"]')
+      ?.children.item(1);
     act(() => {
       secondTrackContent?.dispatchEvent(
         new MouseEvent("contextmenu", { bubbles: true, cancelable: true, clientX: 100 }),
@@ -238,9 +265,40 @@ describe("TimelineLanes disclosure target", () => {
       );
     const firstIds = idsFor(first.host);
     const secondIds = idsFor(second.host);
+    const cellIdsFor = (host: HTMLElement) =>
+      new Set(
+        Array.from(host.querySelectorAll<HTMLElement>("[data-property-group][id]"), (cell) =>
+          cell.getAttribute("id"),
+        ).filter((id): id is string => id !== null),
+      );
+    const ownedIdsFor = (host: HTMLElement) =>
+      Array.from(host.querySelectorAll("[aria-owns]"), (owner) =>
+        owner.getAttribute("aria-owns"),
+      ).filter((id): id is string => id !== null);
+    const firstCellIds = cellIdsFor(first.host);
+    const secondCellIds = cellIdsFor(second.host);
 
+    for (const { host } of [first, second]) {
+      const treegrid = host.querySelector<HTMLElement>('[role="treegrid"]');
+      expect(treegrid?.getAttribute("aria-colcount")).toBe("2");
+      expect(treegrid?.hasAttribute("aria-multiselectable")).toBe(false);
+      expect(
+        [...host.querySelectorAll('[role="rowheader"]')].every(
+          (cell) => cell.getAttribute("aria-colindex") === "1",
+        ),
+      ).toBe(true);
+      expect(
+        [...host.querySelectorAll('[role="gridcell"]')].every(
+          (cell) => cell.getAttribute("aria-colindex") === "2",
+        ),
+      ).toBe(true);
+    }
     expect(firstIds.length).toBeGreaterThan(0);
     expect(firstIds.some((id) => secondIds.includes(id))).toBe(false);
+    expect(firstCellIds.size).toBeGreaterThan(0);
+    expect([...firstCellIds].some((id) => secondCellIds.has(id))).toBe(false);
+    expect(ownedIdsFor(first.host).every((id) => firstCellIds.has(id))).toBe(true);
+    expect(ownedIdsFor(second.host).every((id) => secondCellIds.has(id))).toBe(true);
     // Still a legal CSS id selector: the aria-controls lookups above use `#id`.
     for (const id of [...firstIds, ...secondIds]) {
       expect(id).toMatch(/^[A-Za-z][\w-]*$/);