@editframe/create 0.44.0 → 0.45.0

package/dist/skills/editframe-editor-gui/references/timeline-ruler.md

@@ -0,0 +1,489 @@
+---
+title: Timeline Ruler Element
+description: Time ruler with zoom-aware frame markers and time labels for precise timeline navigation in editor interfaces.
+type: reference
+nav:
+  parent: "Timeline"
+  priority: 14
+api:
+  attributes:
+    - name: duration-ms
+      type: number
+      description: Total duration in milliseconds
+    - name: fps
+      type: number
+      default: 30
+      description: Frame rate for frame marker display
+    - name: content-width
+      type: number
+      description: Total width of timeline content in pixels
+  methods:
+    - name: quantizeToFrameTimeMs
+      signature: quantizeToFrameTimeMs(timeMs, fps) => number
+      description: Round time to nearest frame boundary
+      returns: Time in milliseconds aligned to frame boundary
+    - name: calculateFrameIntervalMs
+      signature: calculateFrameIntervalMs(fps) => number
+      description: Calculate duration of one frame
+      returns: Frame duration in milliseconds
+    - name: calculatePixelsPerFrame
+      signature: calculatePixelsPerFrame(frameIntervalMs, pixelsPerMs) => number
+      description: Calculate pixel width of one frame at current zoom
+      returns: Frame width in pixels
+    - name: shouldShowFrameMarkers
+      signature: shouldShowFrameMarkers(pixelsPerFrame, minSpacing?) => boolean
+      description: Determine if frame markers should be visible at current zoom
+      returns: True if frames have enough space to display
+react:
+  generate: true
+  componentName: TimelineRuler
+  importPath: "@editframe/react"
+  propMapping:
+    duration-ms: durationMs
+    content-width: containerWidth
+  additionalProps:
+    - name: zoomScale
+      type: number
+      description: Zoom level multiplier
+    - name: scrollContainerSelector
+      type: string
+      description: CSS selector for scroll container element
+    - name: scrollContainerRef
+      type: React.RefObject<HTMLElement>
+      description: Ref to scroll container element for scroll synchronization
+    - name: className
+      type: string
+      description: CSS classes for styling
+  nav:
+    parent: "Tools"
+    priority: 45
+    related: ["timeline", "filmstrip"]
+---
+
+<!-- html-only -->
+# ef-timeline-ruler
+<!-- /html-only -->
+<!-- react-only -->
+# TimelineRuler
+<!-- /react-only -->
+
+Time ruler showing time labels and frame markers. Automatically adapts marker density based on zoom level.
+
+<!-- react-only -->
+## Import
+
+```tsx
+import { TimelineRuler } from "@editframe/react";
+```
+<!-- /react-only -->
+
+## Basic Usage
+
+<!-- html-only -->
+Ruler displays time markers and optional frame markers.
+
+```html live
+<ef-timegroup mode="contain" class="w-[720px] h-[480px] bg-black" id="ruler-demo">
+  <ef-video src="https://assets.editframe.com/bars-n-tone.mp4" class="size-full object-contain"></ef-video>
+</ef-timegroup>
+<div class="mt-4">
+  <div class="h-[24px] bg-gray-900 rounded-t-lg overflow-hidden relative">
+    <ef-timeline-ruler
+      duration-ms="10000"
+      fps="30"
+      content-width="400"
+    ></ef-timeline-ruler>
+  </div>
+  <div class="p-4 bg-gray-800 rounded-b-lg">
+    <ef-controls target="ruler-demo" class="flex gap-4 items-center">
+      <ef-toggle-play class="px-3 py-1 bg-blue-600 text-white rounded"></ef-toggle-play>
+      <ef-time-display class="text-white font-mono"></ef-time-display>
+    </ef-controls>
+  </div>
+</div>
+```
+<!-- /html-only -->
+<!-- react-only -->
+The ruler is typically used inside Timeline or Filmstrip components, but can be used standalone:
+
+```tsx
+import { TimelineRuler } from "@editframe/react";
+
+<div className="h-6 bg-gray-900 relative">
+  <TimelineRuler
+    durationMs={10000}
+    fps={30}
+    className="w-full h-full"
+  />
+</div>
+```
+<!-- /react-only -->
+
+<!-- html-only -->
+## Frame Markers at High Zoom
+
+Frame markers appear when zoomed in enough for precision editing.
+
+```html live
+<ef-timegroup mode="contain" class="w-[720px] h-[480px] bg-black" id="frames-demo">
+  <ef-video src="https://assets.editframe.com/bars-n-tone.mp4" sourcein="0s" sourceout="3s" class="size-full object-contain"></ef-video>
+</ef-timegroup>
+<div class="mt-4 space-y-4">
+  <div>
+    <div class="text-white text-sm mb-2">Standard zoom - no frame markers:</div>
+    <div class="h-[24px] bg-gray-900 rounded-lg overflow-auto">
+      <ef-timeline-ruler
+        duration-ms="3000"
+        fps="30"
+        content-width="120"
+      ></ef-timeline-ruler>
+    </div>
+  </div>
+  <div>
+    <div class="text-white text-sm mb-2">High zoom - frame markers visible:</div>
+    <div class="h-[24px] bg-gray-900 rounded-lg overflow-auto">
+      <ef-timeline-ruler
+        duration-ms="3000"
+        fps="30"
+        content-width="600"
+      ></ef-timeline-ruler>
+    </div>
+  </div>
+</div>
+```
+<!-- /html-only -->
+
+<!-- react-only -->
+## With Custom FPS
+
+Show frame markers at different frame rates:
+
+```tsx
+{/* 24fps cinema */}
+<TimelineRuler
+  durationMs={10000}
+  fps={24}
+  className="w-full h-6"
+/>
+
+{/* 60fps high frame rate */}
+<TimelineRuler
+  durationMs={10000}
+  fps={60}
+  className="w-full h-6"
+/>
+```
+
+## With Scroll Container
+
+Sync ruler with scrollable timeline:
+
+```tsx
+import { useRef } from "react";
+import { TimelineRuler } from "@editframe/react";
+
+export const ScrollableRuler = () => {
+  const scrollRef = useRef<HTMLDivElement>(null);
+
+  return (
+    <div className="flex flex-col">
+      {/* Ruler */}
+      <div className="h-6 bg-gray-900">
+        <TimelineRuler
+          durationMs={30000}
+          fps={30}
+          scrollContainerRef={scrollRef}
+          className="w-full h-full"
+        />
+      </div>
+
+      {/* Scrollable content */}
+      <div
+        ref={scrollRef}
+        className="overflow-x-auto h-64 bg-gray-800"
+      >
+        <div style={{ width: '3000px' }}>
+          {/* Timeline content */}
+        </div>
+      </div>
+    </div>
+  );
+};
+```
+<!-- /react-only -->
+
+## Used in Timeline
+
+<!-- html-only -->
+Ruler is automatically included in `ef-timeline` and `ef-filmstrip`.
+
+```html live
+<ef-timegroup mode="contain" class="w-[720px] h-[480px] bg-black" id="timeline-ruler">
+  <ef-video src="https://assets.editframe.com/bars-n-tone.mp4" class="size-full object-contain"></ef-video>
+  <ef-text class="absolute bottom-4 left-4 text-white text-2xl">
+    Timeline with Ruler
+  </ef-text>
+</ef-timegroup>
+<div class="mt-4 h-[300px] bg-gray-900 rounded-lg overflow-hidden">
+  <ef-timeline target="timeline-ruler"></ef-timeline>
+</div>
+```
+<!-- /html-only -->
+<!-- react-only -->
+Ruler is automatically included in Timeline:
+
+```tsx
+import { Timeline, Timegroup, Video } from "@editframe/react";
+
+{/* Timeline includes ruler by default */}
+<Timeline className="w-full h-96" />
+
+{/* Hide ruler if not needed */}
+<Timeline
+  showRuler={false}
+  className="w-full h-96"
+/>
+```
+<!-- /react-only -->
+
+## Adaptive Time Labels
+
+Time labels automatically adjust spacing based on zoom level. The ruler shows appropriate intervals:
+
+- **High zoom** — 0.1s, 0.25s, 0.5s intervals
+- **Medium zoom** — 1s, 2s, 5s intervals
+- **Low zoom** — 10s, 30s, 60s intervals
+
+Labels format as "Xs" or "X.Xs" depending on precision needed.
+
+## Frame Marker Behavior
+
+Frame markers appear when:
+1. Zoom level is high enough (each frame is at least 5px wide by default)
+2. FPS is set (defaults to 30fps)
+
+Frame markers are lighter than time markers to distinguish hierarchy.
+
+At very high zoom, you can see individual frame boundaries for frame-accurate editing.
+
+<!-- react-only -->
+```tsx
+import { useState } from "react";
+import { TimelineRuler } from "@editframe/react";
+
+export const ZoomableRuler = () => {
+  const [zoom, setZoom] = useState(0.04);
+
+  return (
+    <div>
+      <div className="mb-2 flex gap-2">
+        <button onClick={() => setZoom(zoom * 2)}>Zoom In</button>
+        <button onClick={() => setZoom(zoom / 2)}>Zoom Out</button>
+        <span className="text-sm">
+          {zoom >= 0.1 ? "Frame markers visible" : "Zoom in to see frames"}
+        </span>
+      </div>
+
+      <div className="h-6 bg-gray-900">
+        <TimelineRuler
+          durationMs={10000}
+          fps={30}
+          zoomScale={zoom * 1000}
+          className="w-full h-full"
+        />
+      </div>
+    </div>
+  );
+};
+```
+<!-- /react-only -->
+
+## Virtualization
+
+The ruler uses canvas virtualization for performance with long timelines:
+- Only renders visible region plus buffer
+- Maximum canvas width of 2000px
+- Smooth scrolling with 200px buffer on each side
+
+This allows timelines of any length without performance degradation.
+
+<!-- react-only -->
+```tsx
+{/* Handles long timelines efficiently */}
+<TimelineRuler
+  durationMs={600000} // 10 minutes
+  fps={30}
+  className="w-full h-6"
+/>
+```
+<!-- /react-only -->
+
+<!-- html-only -->
+## Helper Functions
+
+The module exports utility functions for working with frames:
+
+### quantizeToFrameTimeMs
+
+Round time to the nearest frame boundary.
+
+```typescript
+import { quantizeToFrameTimeMs } from '@editframe/elements';
+
+const fps = 30;
+const rawTime = 1234; // 1.234 seconds
+const frameTime = quantizeToFrameTimeMs(rawTime, fps);
+// Returns: 1233 (exactly 37 frames at 30fps)
+```
+
+### calculateFrameIntervalMs
+
+Get the duration of one frame.
+
+```typescript
+import { calculateFrameIntervalMs } from '@editframe/elements';
+
+const fps = 30;
+const frameDuration = calculateFrameIntervalMs(fps);
+// Returns: 33.333... (1000ms / 30fps)
+```
+
+### calculatePixelsPerFrame
+
+Calculate pixel width of a frame at current zoom.
+
+```typescript
+import { calculatePixelsPerFrame } from '@editframe/elements';
+
+const frameIntervalMs = 33.33; // 30fps
+const pixelsPerMs = 0.2; // zoom level
+const frameWidth = calculatePixelsPerFrame(frameIntervalMs, pixelsPerMs);
+// Returns: 6.666 pixels per frame
+```
+
+### shouldShowFrameMarkers
+
+Determine if frame markers should be visible.
+
+```typescript
+import { shouldShowFrameMarkers } from '@editframe/elements';
+
+const pixelsPerFrame = 6.5;
+const shouldShow = shouldShowFrameMarkers(pixelsPerFrame);
+// Returns: true (frame is wider than 5px minimum)
+
+const pixelsPerFrame = 2;
+const shouldShow = shouldShowFrameMarkers(pixelsPerFrame);
+// Returns: false (frame too narrow to display markers)
+```
+<!-- /html-only -->
+
+## CSS Custom Properties
+
+Ruler appearance uses theme variables:
+
+```css
+ef-timeline-ruler {
+  --ef-color-text-muted: #9ca3af;
+  --ef-color-border-subtle: #6b7280;
+}
+```
+
+<!-- react-only -->
+## Custom Styling
+
+Style the ruler appearance:
+
+```tsx
+<TimelineRuler
+  durationMs={20000}
+  fps={30}
+  className="w-full h-8 bg-gradient-to-b from-gray-900 to-gray-800"
+  style={{
+    '--ef-color-text-muted': 'rgb(156, 163, 175)',
+    '--ef-color-border-subtle': 'rgb(107, 114, 128)',
+  } as React.CSSProperties}
+/>
+```
+
+## Time Label Format
+
+Time labels automatically adjust format:
+
+```tsx
+<div className="space-y-4">
+  {/* Short duration: shows decimals */}
+  <TimelineRuler durationMs={5000} fps={30} className="w-full h-6 bg-gray-900" />
+
+  {/* Medium duration: shows seconds */}
+  <TimelineRuler durationMs={30000} fps={30} className="w-full h-6 bg-gray-900" />
+
+  {/* Long duration: shows minutes */}
+  <TimelineRuler durationMs={300000} fps={30} className="w-full h-6 bg-gray-900" />
+</div>
+```
+
+## Marker Visibility
+
+Frame markers only appear when there's enough space:
+
+```tsx
+import { TimelineRuler } from "@editframe/react";
+
+<div className="space-y-4">
+  <div>
+    <p className="text-sm mb-1">Zoomed out - only time labels</p>
+    <TimelineRuler
+      durationMs={30000}
+      fps={30}
+      zoomScale={40}
+      className="w-full h-6 bg-gray-900"
+    />
+  </div>
+
+  <div>
+    <p className="text-sm mb-1">Zoomed in - time labels and frame markers</p>
+    <TimelineRuler
+      durationMs={30000}
+      fps={30}
+      zoomScale={200}
+      className="w-full h-6 bg-gray-900"
+    />
+  </div>
+</div>
+```
+
+## Responsive Ruler
+
+Ruler adapts to container width:
+
+```tsx
+<div className="w-full max-w-4xl mx-auto">
+  <TimelineRuler
+    durationMs={15000}
+    fps={30}
+    className="w-full h-6 bg-gray-900 rounded"
+  />
+</div>
+```
+<!-- /react-only -->
+
+## Usage Context
+
+The ruler is typically used as part of larger timeline components rather than standalone. It automatically reads zoom and scroll state from timeline context.
+
+<!-- html-only -->
+For custom timeline implementations, provide `duration-ms`, `fps`, and `content-width` explicitly.
+<!-- /html-only -->
+
+## Notes
+
+- Ruler is typically used within Timeline or Filmstrip
+- Frame markers appear automatically at high zoom levels
+- Uses virtualized rendering for performance with long timelines
+- Time labels adjust format based on duration and zoom
+- Minimum spacing prevents marker overlap
+<!-- react-only -->
+- Syncs with scroll container via ref or selector
+<!-- /react-only -->
+- Canvas-based rendering for smooth performance