@twick/timeline 0.14.2 → 0.14.4

package/README.md

@@ -1,5 +1,40 @@
 # @twick/timeline
 
+Timeline management and editing capabilities for video projects.
+
+## Overview
+
+This package provides a comprehensive timeline editor with CRUD operations for managing video tracks and elements. It uses the visitor pattern to handle different element types consistently and offers a fluent interface for timeline manipulation.
+
+## Installation
+
+```bash
+npm install @twick/timeline
+# or
+pnpm add @twick/timeline
+```
+
+## Quick Start
+
+```typescript
+import { TimelineEditor, TimelineOperationContext } from '@twick/timeline';
+
+// Create editor with context
+const context: TimelineOperationContext = {
+  contextId: 'my-editor',
+  setTotalDuration: (duration) => console.log('Duration:', duration),
+  setPresent: (data) => console.log('Present:', data),
+  handleUndo: () => console.log('Undo'),
+  handleRedo: () => console.log('Redo'),
+  handleResetHistory: () => console.log('Reset History'),
+  setLatestProjectVersion: (version) => console.log('Version:', version),
+  setTimelineAction: (action, payload) => console.log('Action:', action, payload),
+};
+
+const editor = new TimelineEditor(context);
+const track = editor.addTrack('My Video Track');
+```
+
 ## Timeline Editor CRUD Operations
 
 The TimelineEditor provides a clean interface for managing tracks and elements using the visitor pattern.
@@ -172,4 +207,55 @@ function MyComponent() {
 }
 ```
 
+## API Reference
+
+### Core Classes
+
+- `TimelineEditor`: Main timeline editor class
+- `TextElement`: Text element implementation
+- `VideoElement`: Video element implementation
+- `ImageElement`: Image element implementation
+- `AudioElement`: Audio element implementation
+
+### Hooks
+
+- `useTimelineContext`: React hook for timeline context
+
+### Utility Functions
+
+- `getCurrentElements`: Get elements at specific time
+- `getTotalDuration`: Calculate total timeline duration
+- `generateShortUuid`: Generate unique IDs
+- `isElementId`: Check if ID is element type
+- `isTrackId`: Check if ID is track type
+
+### Types
+
+- `TimelineOperationContext`: Context interface for timeline operations
+- `TrackElement`: Base track element interface
+
+For complete API documentation, refer to the generated documentation.
+
+## Browser Support
+
+This package requires a browser environment with support for:
+- Modern JavaScript features (ES2020+)
+- Promise and async/await support
+
+## Documentation
+
+For complete documentation, refer to the project documentation site.
+
+## License
+
+This package is licensed under the **Sustainable Use License (SUL) Version 1.0**.
+
+- Free for use in commercial and non-commercial apps
+- Can be modified and self-hosted
+- Cannot be sold, rebranded, or distributed as a standalone SDK
+
+For commercial licensing inquiries, contact: contact@kifferai.com
+
+For full license terms, see the main LICENSE.md file in the project root.
+
 

package/dist/context/timeline-context.d.ts

@@ -1,33 +1,142 @@
 import { Track } from '../core/track/track';
 import { TrackElement } from '../core/elements/base.element';
-import { ProjectJSON, TrackJSON } from '../types';
+import { ProjectJSON, Size, TrackJSON } from '../types';
 import { TimelineEditor } from '../core/editor/timeline.editor';
 
+/**
+ * Type definition for the Timeline context.
+ * Contains all the state and functions needed to manage a timeline instance.
+ * Provides access to the timeline editor, selected items, undo/redo functionality,
+ * and timeline actions.
+ *
+ * @example
+ * ```js
+ * const {
+ *   editor,
+ *   selectedItem,
+ *   totalDuration,
+ *   canUndo,
+ *   canRedo,
+ *   setSelectedItem,
+ *   setTimelineAction
+ * } = useTimelineContext();
+ * ```
+ */
 export type TimelineContextType = {
+    /** Unique identifier for this timeline context */
     contextId: string;
+    /** The timeline editor instance for this context */
     editor: TimelineEditor;
+    /** Currently selected track or element */
     selectedItem: Track | TrackElement | null;
+    /** Change counter for tracking modifications */
     changeLog: number;
+    /** Current timeline action being performed */
     timelineAction: {
         type: string;
         payload: any;
     };
+    /** Resolution of the video */
+    videoResolution: Size;
+    /** Total duration of the timeline in seconds */
     totalDuration: number;
+    /** Current project state */
     present: ProjectJSON | null;
+    /** Whether undo operation is available */
     canUndo: boolean;
+    /** Whether redo operation is available */
     canRedo: boolean;
+    /** Function to set the selected item */
     setSelectedItem: (item: Track | TrackElement | null) => void;
+    /** Function to set timeline actions */
     setTimelineAction: (type: string, payload: any) => void;
+    /** Function to set the video resolution */
+    setVideoResolution: (size: Size) => void;
 };
+/**
+ * Props for the TimelineProvider component.
+ * Defines the configuration options for timeline context initialization.
+ *
+ * @example
+ * ```jsx
+ * <TimelineProvider
+ *   contextId="my-timeline"
+ *   initialData={{ tracks: [], version: 1 }}
+ *   undoRedoPersistenceKey="timeline-state"
+ *   maxHistorySize={50}
+ * >
+ *   <YourApp />
+ * </TimelineProvider>
+ * ```
+ */
 export interface TimelineProviderProps {
+    /** React children to wrap with timeline context */
     children: React.ReactNode;
+    /** Unique identifier for this timeline context */
     contextId: string;
+    /** resolution of the video */
+    resolution?: Size;
+    /** Initial timeline data to load */
     initialData?: {
         tracks: TrackJSON[];
         version: number;
     };
+    /** Key for persisting undo/redo state */
     undoRedoPersistenceKey?: string;
+    /** Maximum number of history states to keep */
     maxHistorySize?: number;
 }
-export declare const TimelineProvider: ({ contextId, children, initialData, undoRedoPersistenceKey, maxHistorySize, }: TimelineProviderProps) => import("react/jsx-runtime").JSX.Element;
+/**
+ * Provider component for the Timeline context.
+ * Wraps the timeline functionality with PostHog analytics and undo/redo support.
+ * Manages the global state for timeline instances including tracks, elements,
+ * playback state, and history management.
+ *
+ * @param props - Timeline provider configuration
+ * @returns Context provider with timeline state management
+ *
+ * @example
+ * ```jsx
+ * <TimelineProvider
+ *   contextId="my-timeline"
+ *   initialData={{ tracks: [], version: 1 }}
+ *   undoRedoPersistenceKey="timeline-state"
+ * >
+ *   <YourApp />
+ * </TimelineProvider>
+ * ```
+ */
+export declare const TimelineProvider: ({ contextId, children, resolution, initialData, undoRedoPersistenceKey, maxHistorySize, }: TimelineProviderProps) => import("react/jsx-runtime").JSX.Element;
+/**
+ * Hook to access the Timeline context.
+ * Provides access to timeline state, editor instance, and timeline management functions.
+ * Must be used within a TimelineProvider component.
+ *
+ * @returns TimelineContextType object with all timeline state and controls
+ * @throws Error if used outside of TimelineProvider
+ *
+ * @example
+ * ```js
+ * const {
+ *   editor,
+ *   selectedItem,
+ *   totalDuration,
+ *   canUndo,
+ *   canRedo,
+ *   setSelectedItem,
+ *   setTimelineAction
+ * } = useTimelineContext();
+ *
+ * // Access the timeline editor
+ * const tracks = editor.getTracks();
+ *
+ * // Check if undo is available
+ * if (canUndo) {
+ *   editor.undo();
+ * }
+ *
+ * // Set timeline action
+ * setTimelineAction(TIMELINE_ACTION.SET_PLAYER_STATE, { playing: true });
+ * ```
+ */
 export declare const useTimelineContext: () => TimelineContextType;

package/dist/core/addOns/animation.d.ts

@@ -3,6 +3,7 @@ import { Animation } from '../../types';
 export declare class ElementAnimation {
     private name;
     private interval?;
+    private duration?;
     private intensity?;
     private animate?;
     private mode?;
@@ -10,11 +11,13 @@ export declare class ElementAnimation {
     constructor(name: string);
     getName(): string;
     getInterval(): number | undefined;
+    getDuration(): number | undefined;
     getIntensity(): number | undefined;
     getAnimate(): "enter" | "exit" | "both" | undefined;
     getMode(): "in" | "out" | undefined;
     getDirection(): "left" | "center" | "right" | "up" | "down" | undefined;
     setInterval(interval?: number): this;
+    setDuration(duration?: number): this;
     setIntensity(intensity?: number): this;
     setAnimate(animate?: "enter" | "exit" | "both"): this;
     setMode(mode?: "in" | "out"): this;

package/dist/core/editor/timeline.editor.d.ts

@@ -33,7 +33,7 @@ export declare class TimelineEditor {
     getTimelineData(): TimelineTrackData | null;
     getLatestVersion(): number;
     protected setTimelineData(tracks: Track[], version?: number): TimelineTrackData;
-    addTrack(name: string): Track;
+    addTrack(name: string, type?: string): Track;
     getTrackById(id: string): Track | null;
     getTrackByName(name: string): Track | null;
     removeTrackById(id: string): void;
@@ -58,9 +58,9 @@ export declare class TimelineEditor {
     /**
      * Update an element in a specific track using the visitor pattern
      * @param element The updated element
-     * @returns boolean true if element was updated successfully
+     * @returns TrackElement the updated element
      */
-    updateElement(element: TrackElement): boolean;
+    updateElement(element: TrackElement): TrackElement;
     /**
      * Split an element at a specific time point using the visitor pattern
      * @param element The element to split

package/dist/core/elements/base.element.d.ts

@@ -23,6 +23,8 @@ export declare abstract class TrackElement {
     getName(): string;
     getAnimation(): ElementAnimation | undefined;
     getPosition(): Position;
+    getRotation(): number;
+    getOpacity(): number;
     setId(id: string): this;
     setType(type: string): this;
     setStart(s: number): this;
@@ -31,5 +33,7 @@ export declare abstract class TrackElement {
     setName(name: string): this;
     setAnimation(animation?: ElementAnimation): this;
     setPosition(position: Position): this;
+    setRotation(rotation: number): this;
+    setOpacity(opacity: number): this;
     setProps(props: Record<string, any>): this;
 }

package/dist/core/elements/circle.element.d.ts

@@ -7,7 +7,11 @@ export declare class CircleElement extends TrackElement {
     constructor(fill: string, radius: number);
     getFill(): string;
     getRadius(): number;
+    getStrokeColor(): string;
+    getLineWidth(): number;
     setFill(fill: string): this;
     setRadius(radius: number): this;
+    setStrokeColor(strokeColor: string): this;
+    setLineWidth(lineWidth: number): this;
     accept<T>(visitor: ElementVisitor<T>): T;
 }

package/dist/core/elements/icon.element.d.ts

@@ -1,9 +1,14 @@
 import { TrackElement } from './base.element';
 import { ElementVisitor } from '../visitor/element-visitor';
-import { IconProps, Size } from '../../types';
+import { Size } from '../../types';
 
 export declare class IconElement extends TrackElement {
-    protected props: IconProps;
-    constructor(src: string, size: Size);
+    constructor(src: string, size: Size, fill?: string);
+    getSrc(): string;
+    getFill(): string;
+    getSize(): Size | undefined;
+    setSrc(src: string): this;
+    setFill(fill: string): this;
+    setSize(size: Size): this;
     accept<T>(visitor: ElementVisitor<T>): T;
 }

package/dist/core/elements/rect.element.d.ts

@@ -5,7 +5,15 @@ import { ElementVisitor } from '../visitor/element-visitor';
 export declare class RectElement extends TrackElement {
     protected props: RectProps;
     constructor(fill: string, size: Size);
+    getFill(): string;
     setFill(fill: string): this;
+    getSize(): Size;
+    getCornerRadius(): number;
+    getStrokeColor(): string;
+    getLineWidth(): number;
     setSize(size: Size): this;
+    setCornerRadius(cornerRadius: number): this;
+    setStrokeColor(strokeColor: string): this;
+    setLineWidth(lineWidth: number): this;
     accept<T>(visitor: ElementVisitor<T>): T;
 }