@stagecliplk/remotion-template 1.0.0

package/README.md

@@ -0,0 +1,396 @@
+# @stageclip/remotion-template
+
+[![npm version](https://img.shields.io/npm/v/@stageclip/remotion-template.svg)](https://www.npmjs.com/package/@stageclip/remotion-template)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A powerful, reusable React component for editing and previewing Remotion video templates. Built with TypeScript and
+designed for production use.
+
+## **Features**
+
+✅ **Rich Template Editor** - Full-featured UI for customizing video templates  
+✅ **Real-time Preview** - Integrated Remotion player for instant feedback  
+✅ **TypeScript Support** - Fully typed for excellent DX  
+✅ **Flexible API** - Props-based, no global state  
+✅ **Modular** - Import only what you need  
+✅ **Production Ready** - Battle-tested in StageClip's production environment
+
+---
+
+## **Installation**
+
+### **Prerequisites**
+
+- React >= 18.0.0
+- Node.js >= 18.18.0
+
+### **Install from Azure Artifacts**
+
+1. **Configure `.npmrc`** in your project root:
+
+```ini
+registry=https://pkgs.dev.azure.com/YOUR_ORG/_packaging/YOUR_FEED/npm/registry/
+always-auth=true
+```
+
+2. **Install the package:**
+
+```bash
+npm install @stageclip/remotion-template
+```
+
+Or with yarn:
+
+```bash
+yarn add @stageclip/remotion-template
+```
+
+**Note:** Peer dependencies (`react`, `react-dom`, `remotion`, `@remotion/player`, `@remotion/media-utils`) will be
+installed automatically if not present.
+
+---
+
+## **Quick Start**
+
+```tsx
+import React, { useState } from 'react';
+import { TemplateEditor, RemotionPlayer, VideoTemplate } from '@stageclip/remotion-template';
+
+function App() {
+  const [template, setTemplate] = useState<VideoTemplate>({
+    compositionDefaults: {
+      fps: 30,
+      width: 1920,
+      height: 1080,
+      aspectRatio: '16:9',
+      totalFrames: 300,
+    },
+    globalBranding: {
+      institutionName: 'My Institution',
+      brandColor1: '#00802b',
+      brandColor2: '#005a1e',
+      brandColor3: '#00cc44',
+      fontFamily: 'Inter',
+      fontSize: 48,
+      lineSpacing: 1.2,
+      logoPrimary: '',
+      logoSecondary: '',
+      socialMedia: {
+        websiteUrl: '',
+        contactLine: '',
+        instagramHandle: '',
+        hashtag: '',
+      },
+      musicUrl: '',
+      musicVolume: 0.3,
+    },
+    timeline: [],
+  });
+
+  return (
+    <div style={{ display: 'flex', gap: 20 }}>
+      <TemplateEditor
+        template={template}
+        selectedSceneId={null}
+        onTemplateChange={setTemplate}
+        onClearSelection={() => {}}
+      />
+      <RemotionPlayer template={template} />
+    </div>
+  );
+}
+
+export default App;
+```
+
+---
+
+## **Core Components**
+
+### **TemplateEditor**
+
+Main component for editing video templates.
+
+```tsx
+<TemplateEditor
+  template={template}
+  selectedSceneId={selectedSceneId}
+  onTemplateChange={handleTemplateChange}
+  onClearSelection={handleClearSelection}
+  onOpenMediaLibrary={handleOpenMediaLibrary}
+  onAspectRatioChange={handleAspectRatioChange}
+/>
+```
+
+**Props:**
+
+- `template: VideoTemplate` - Current template configuration
+- `selectedSceneId: string | null` - ID of selected scene
+- `onTemplateChange: (template: VideoTemplate) => void` - Callback when template changes
+- `onClearSelection: () => void` - Callback to clear selection
+- `onOpenMediaLibrary?: (sceneId, propPath, mediaType, options) => void` - Optional media picker
+- `onAspectRatioChange?: (aspectRatio: '16:9' | '9:16') => void` - Optional aspect ratio handler
+
+---
+
+### **RemotionPlayer**
+
+Component for previewing video templates.
+
+```tsx
+<RemotionPlayer template={template} width={1280} height={720} />
+```
+
+**Props:**
+
+- `template: VideoTemplate` - Template to preview
+- `width?: number` - Player width (optional)
+- `height?: number` - Player height (optional)
+
+---
+
+## **Exported Components**
+
+```typescript
+// Main components
+import { TemplateEditor, RemotionPlayer } from '@stageclip/remotion-template';
+
+// Sub-components
+import { ColorPicker, RangeSlider, DualRangeSlider, LogoPicker, SceneTimeline } from '@stageclip/remotion-template';
+
+// Types
+import type {
+  VideoTemplate,
+  CompositionDefaults,
+  GlobalBranding,
+  SocialMedia,
+  ParticipantData,
+  GoogleFont,
+  LogoOption,
+} from '@stageclip/remotion-template';
+
+// Utilities
+import {
+  GOOGLE_FONTS,
+  loadGoogleFont,
+  getFontFamilyString,
+  calculateSceneDuration,
+  colors,
+  fontFamily,
+} from '@stageclip/remotion-template';
+```
+
+---
+
+## **TypeScript**
+
+Full TypeScript support included. All types are exported:
+
+```typescript
+import type { VideoTemplate } from '@stageclip/remotion-template';
+
+const myTemplate: VideoTemplate = {
+  // Fully typed!
+};
+```
+
+---
+
+## **Documentation**
+
+- **[Usage Guide](./USAGE.md)** - Comprehensive usage examples and patterns
+- **[Publishing Guide](./PUBLISHING.md)** - How to publish updates to Azure Artifacts
+- **[API Reference](./USAGE.md#api-reference)** - Complete API documentation
+
+---
+
+## **Examples**
+
+### **With Media Library Integration**
+
+```tsx
+function VideoEditorWithMediaLibrary() {
+  const [template, setTemplate] = useState<VideoTemplate>(initialTemplate);
+  const [selectedSceneId, setSelectedSceneId] = useState<string | null>(null);
+
+  const handleOpenMediaLibrary = (sceneId, propPath, mediaType, options) => {
+    // Open your media library modal
+    // Update template with selected media
+  };
+
+  return (
+    <TemplateEditor
+      template={template}
+      selectedSceneId={selectedSceneId}
+      onTemplateChange={setTemplate}
+      onClearSelection={() => setSelectedSceneId(null)}
+      onOpenMediaLibrary={handleOpenMediaLibrary}
+    />
+  );
+}
+```
+
+### **With Auto-Save**
+
+```tsx
+import { useDebounce } from 'use-debounce';
+
+function VideoEditorWithAutoSave() {
+  const [template, setTemplate] = useState<VideoTemplate>(initialTemplate);
+  const [debouncedTemplate] = useDebounce(template, 1000);
+
+  useEffect(() => {
+    // Auto-save to backend
+    saveToBackend(debouncedTemplate);
+  }, [debouncedTemplate]);
+
+  return (
+    <TemplateEditor
+      template={template}
+      selectedSceneId={null}
+      onTemplateChange={setTemplate}
+      onClearSelection={() => {}}
+    />
+  );
+}
+```
+
+---
+
+## **Styling**
+
+The component uses inline styles with a built-in theme. You can wrap it in a container for additional styling:
+
+```tsx
+import { colors } from '@stageclip/remotion-template';
+
+<div
+  style={{
+    backgroundColor: colors.bgPaper,
+    padding: 20,
+    borderRadius: 8,
+  }}
+>
+  <TemplateEditor {...props} />
+</div>;
+```
+
+**Available theme colors:**
+
+- `colors.primary` - Primary brand color
+- `colors.textPrimary` - Main text color
+- `colors.bgDefault` - Default background
+- `colors.bgPaper` - Paper/card background
+- And more...
+
+---
+
+## **Browser Support**
+
+- Chrome (latest)
+- Firefox (latest)
+- Safari (latest)
+- Edge (latest)
+
+---
+
+## **Requirements**
+
+### **Peer Dependencies**
+
+```json
+{
+  "react": ">=18",
+  "react-dom": ">=18",
+  "remotion": ">=4",
+  "@remotion/player": "^4.0.400",
+  "@remotion/media-utils": "^4.0.400",
+  "@remotion/transitions": "^4.0.400"
+}
+```
+
+---
+
+## **Development**
+
+This package is developed inside the StageClip Producer monorepo.
+
+```bash
+# Navigate to package directory
+cd src/shared/remotion-template
+
+# Install dependencies
+npm install
+
+# Type check
+npm run typecheck
+
+# Build
+npm run build
+
+# Clean build artifacts
+npm run clean
+```
+
+---
+
+## **Publishing**
+
+Publishing is handled through Azure Artifacts. See [PUBLISHING.md](./PUBLISHING.md) for detailed instructions.
+
+**Quick publish:**
+
+```bash
+cd src/shared/remotion-template
+
+# Bump version
+npm version patch  # or minor, major
+
+# Build and publish
+npm publish
+```
+
+---
+
+## **Versioning**
+
+We follow [Semantic Versioning](https://semver.org/):
+
+- **MAJOR** - Breaking changes
+- **MINOR** - New features (backward compatible)
+- **PATCH** - Bug fixes
+
+---
+
+## **License**
+
+MIT © StageClip
+
+---
+
+## **Support**
+
+For issues, questions, or feature requests:
+
+- **Internal:** Contact the StageClip development team
+- **External:** Create an issue in the repository
+
+---
+
+## **Changelog**
+
+### **v1.0.0** (Initial Release)
+
+- ✨ TemplateEditor component with full editing capabilities
+- ✨ RemotionPlayer for video preview
+- ✨ Sub-components: ColorPicker, LogoPicker, RangeSlider, etc.
+- ✨ Complete TypeScript support
+- ✨ Google Fonts integration
+- ✨ Scene duration calculator utility
+- 📚 Comprehensive documentation
+
+---
+
+## **Contributors**
+
+Built and maintained by the StageClip team.