@bycrux/editor 0.8.7 → 0.8.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bycrux/editor",
-  "version": "0.8.7",
+  "version": "0.8.8",
   "private": false,
   "type": "module",
   "exports": {

package/src/ControlsInfoModal.tsx

@@ -0,0 +1,157 @@
+import { useEffect } from 'react'
+import { X } from 'lucide-react'
+
+/** A single control/shortcut row. `keys` renders as <kbd> chips; omit for a pure gesture. */
+export interface ControlEntry {
+  keys?: string[]
+  label: string
+}
+
+export interface ControlSection {
+  heading: string
+  entries: ControlEntry[]
+}
+
+export interface ControlsInfoModalProps {
+  title: string
+  sections: ControlSection[]
+  onClose: () => void
+}
+
+/**
+ * Read-only "how to drive this editor" modal. Content is passed in per editor
+ * (video vs carousel) so this component stays a dumb, themed renderer. Matches
+ * the backdrop/Esc/close conventions of the other editor modals (TranscriptModal
+ * et al.) and uses the shared `--editor-*` theme tokens.
+ */
+export default function ControlsInfoModal({ title, sections, onClose }: ControlsInfoModalProps) {
+  useEffect(() => {
+    const onKey = (e: globalThis.KeyboardEvent) => {
+      if (e.key === 'Escape') onClose()
+    }
+    window.addEventListener('keydown', onKey)
+    return () => window.removeEventListener('keydown', onKey)
+  }, [onClose])
+
+  return (
+    <div
+      role="dialog"
+      aria-modal="true"
+      aria-label={title}
+      className="fixed inset-0 z-50 flex items-center justify-center bg-black/70 backdrop-blur-sm"
+      onClick={onClose}
+    >
+      <div
+        className="relative mx-4 flex max-h-[80vh] w-full max-w-md flex-col overflow-hidden rounded-lg border shadow-2xl"
+        style={{
+          background: 'var(--editor-surface)',
+          borderColor: 'var(--editor-border)',
+          color: 'var(--editor-text)',
+        }}
+        onClick={(e) => e.stopPropagation()}
+      >
+        <div
+          className="flex shrink-0 items-center justify-between border-b px-4 py-3"
+          style={{ borderColor: 'var(--editor-border)' }}
+        >
+          <h2 className="text-sm font-semibold">{title}</h2>
+          <button
+            type="button"
+            onClick={onClose}
+            aria-label="Close"
+            className="cursor-pointer opacity-60 transition-opacity hover:opacity-100"
+          >
+            <X size={16} />
+          </button>
+        </div>
+
+        <div className="space-y-4 overflow-y-auto px-4 py-3">
+          {sections.map((section) => (
+            <div key={section.heading}>
+              <p className="mb-1.5 text-[11px] font-semibold uppercase tracking-wide opacity-50">
+                {section.heading}
+              </p>
+              <ul className="space-y-1.5">
+                {section.entries.map((entry, i) => (
+                  <li key={i} className="flex items-start justify-between gap-3 text-xs">
+                    <span className="opacity-80">{entry.label}</span>
+                    {entry.keys && entry.keys.length > 0 && (
+                      <span className="flex shrink-0 items-center gap-1">
+                        {entry.keys.map((k, j) => (
+                          <kbd
+                            key={j}
+                            className="rounded border px-1.5 py-0.5 font-mono text-[10px] leading-none"
+                            style={{ borderColor: 'var(--editor-border)', background: 'var(--editor-bg)' }}
+                          >
+                            {k}
+                          </kbd>
+                        ))}
+                      </span>
+                    )}
+                  </li>
+                ))}
+              </ul>
+            </div>
+          ))}
+        </div>
+      </div>
+    </div>
+  )
+}
+
+/** Controls reference for the video/timeline editor. Sourced from VideoEditor's
+ *  key handler (S / ⌘Z), the track-controls toolbar, and PreviewPlayer's
+ *  on-canvas transform (drag / corner-drag / scroll / rotate). */
+export const VIDEO_CONTROLS: ControlSection[] = [
+  {
+    heading: 'Preview',
+    entries: [
+      { label: 'Drag to move the selected clip or overlay' },
+      { label: 'Corner-drag or scroll to scale it' },
+      { label: 'Drag the rotate handle to turn an overlay' },
+    ],
+  },
+  {
+    heading: 'Timeline',
+    entries: [
+      { label: 'Drag a clip to reposition it' },
+      { label: "Drag a clip's edge to trim it" },
+      { label: 'Select a clip, then click ⓘ to inspect it' },
+    ],
+  },
+  {
+    heading: 'Toolbar',
+    entries: [
+      { label: 'Ripple: edits close the gap instead of leaving it' },
+      { label: 'Crop source: non-destructively crop the selected clip' },
+    ],
+  },
+  {
+    heading: 'Keyboard',
+    entries: [
+      { keys: ['S'], label: 'Split at the playhead' },
+      { keys: ['⌘/Ctrl', 'Z'], label: 'Undo' },
+    ],
+  },
+]
+
+/** Controls reference for the carousel editor. Sourced from CarouselEditor's key
+ *  handlers (undo/redo, Delete) and the canvas gesture hints. */
+export const CAROUSEL_CONTROLS: ControlSection[] = [
+  {
+    heading: 'Canvas',
+    entries: [
+      { label: 'Drag an element to reposition it' },
+      { label: 'Resize or rotate it via the handles' },
+      { label: 'Double-click text to edit it' },
+    ],
+  },
+  {
+    heading: 'Keyboard',
+    entries: [
+      { keys: ['⌘/Ctrl', 'Z'], label: 'Undo' },
+      { keys: ['⌘/Ctrl', '⇧', 'Z'], label: 'Redo' },
+      { keys: ['Delete'], label: 'Remove the selected element' },
+    ],
+  },
+]

package/src/__tests__/ControlsInfoModal.test.tsx

@@ -0,0 +1,62 @@
+import { describe, it, expect, vi, afterEach } from 'vitest'
+import { render, screen, fireEvent, cleanup } from '@testing-library/react'
+import ControlsInfoModal, {
+  VIDEO_CONTROLS,
+  CAROUSEL_CONTROLS,
+  type ControlSection,
+} from '../ControlsInfoModal'
+
+afterEach(() => cleanup())
+
+const SECTIONS: ControlSection[] = [
+  {
+    heading: 'Canvas',
+    entries: [
+      { label: 'Drag an element to reposition it' },
+      { keys: ['⌘/Ctrl', 'Z'], label: 'Undo' },
+    ],
+  },
+]
+
+describe('ControlsInfoModal', () => {
+  it('renders the title, section headings, entry labels, and kbd chips', () => {
+    render(<ControlsInfoModal title="Editor controls" sections={SECTIONS} onClose={vi.fn()} />)
+
+    expect(screen.getByRole('dialog', { name: 'Editor controls' })).toBeTruthy()
+    expect(screen.getByText('Canvas')).toBeTruthy()
+    expect(screen.getByText('Drag an element to reposition it')).toBeTruthy()
+    // Keys render as individual <kbd> chips.
+    expect(screen.getByText('⌘/Ctrl').tagName).toBe('KBD')
+    expect(screen.getByText('Z').tagName).toBe('KBD')
+  })
+
+  it('closes on Escape', () => {
+    const onClose = vi.fn()
+    render(<ControlsInfoModal title="Editor controls" sections={SECTIONS} onClose={onClose} />)
+    fireEvent.keyDown(window, { key: 'Escape' })
+    expect(onClose).toHaveBeenCalledTimes(1)
+  })
+
+  it('closes on backdrop click but not on panel click', () => {
+    const onClose = vi.fn()
+    render(<ControlsInfoModal title="Editor controls" sections={SECTIONS} onClose={onClose} />)
+
+    // Click inside the panel — should NOT close.
+    fireEvent.click(screen.getByText('Canvas'))
+    expect(onClose).not.toHaveBeenCalled()
+
+    // Click the backdrop (the dialog root) — should close.
+    fireEvent.click(screen.getByRole('dialog'))
+    expect(onClose).toHaveBeenCalledTimes(1)
+  })
+
+  it('ships real control content for both editors', () => {
+    // Guards against an empty/placeholder content regression.
+    const videoLabels = VIDEO_CONTROLS.flatMap((s) => s.entries.map((e) => e.label))
+    const carouselLabels = CAROUSEL_CONTROLS.flatMap((s) => s.entries.map((e) => e.label))
+    expect(videoLabels).toEqual(expect.arrayContaining(['Split at the playhead']))
+    expect(carouselLabels).toEqual(expect.arrayContaining(['Double-click text to edit it']))
+    expect(VIDEO_CONTROLS.length).toBeGreaterThan(0)
+    expect(CAROUSEL_CONTROLS.length).toBeGreaterThan(0)
+  })
+})

package/src/carousel/CarouselEditor.tsx

@@ -1,5 +1,5 @@
 import { useEffect, useRef, useState } from 'react'
-import { RefreshCw, AlertCircle, Download } from 'lucide-react'
+import { RefreshCw, AlertCircle, Download, Info } from 'lucide-react'
 import type { Project, Slide, CarouselElement, ImageElement, CarouselEditorProps, OverlayFactory } from '../types'
 import { applyTheme, defaultMontajTheme } from '../theme'
 import { useProjectState } from '../state/use-project-state'
@@ -7,6 +7,7 @@ import SlideCanvas from './SlideCanvas'
 import SlidePropertyPanel from './SlidePropertyPanel'
 import AddElementMenu from './AddElementMenu'
 import CarouselRenderModal from './CarouselRenderModal'
+import ControlsInfoModal, { CAROUSEL_CONTROLS } from '../ControlsInfoModal'
 import { Button } from '../ui'
 
 // Generic over the host's concrete project type `P` (default = the package's
@@ -167,6 +168,7 @@ export default function CarouselEditor<P extends Project = Project>({ project: i
 
   const [skillPath, setSkillPath] = useState<string | null>(null)
   const [copied, setCopied] = useState(false)
+  const [showControls, setShowControls] = useState(false)
   const [refreshing, setRefreshing] = useState(false)
   const [refreshState, setRefreshState] = useState<'idle' | 'err'>('idle')
   const [rendering, setRendering] = useState(false)
@@ -505,9 +507,20 @@ export default function CarouselEditor<P extends Project = Project>({ project: i
                 hiddenElementIds={hiddenElementIds}
               />
             </div>
-            <p className="flex-shrink-0 text-xs text-[var(--editor-text)]/60 text-center max-w-md">
-              Drag to reposition, resize/rotate via handles, double-click text to edit. Cmd/Ctrl+Z to undo.
-            </p>
+            <div className="flex-shrink-0 flex items-center justify-center gap-1.5 text-xs text-[var(--editor-text)]/60 max-w-md">
+              <span className="text-center">
+                Drag to reposition, resize/rotate via handles, double-click text to edit. Cmd/Ctrl+Z to undo.
+              </span>
+              <button
+                type="button"
+                onClick={() => setShowControls(true)}
+                title="Editor controls & shortcuts"
+                aria-label="Editor controls & shortcuts"
+                className="shrink-0 cursor-pointer opacity-60 transition-opacity hover:opacity-100"
+              >
+                <Info size={13} />
+              </button>
+            </div>
           </>
         ) : (
           <div className="text-[var(--editor-text)]/40 text-sm">No slides yet. Add one in the left panel.</div>
@@ -566,6 +579,14 @@ export default function CarouselEditor<P extends Project = Project>({ project: i
         </div>
       )}
 
+      {showControls && (
+        <ControlsInfoModal
+          title="Editor controls"
+          sections={CAROUSEL_CONTROLS}
+          onClose={() => setShowControls(false)}
+        />
+      )}
+
       {renderOpen && (
         <CarouselRenderModal
           projectId={project.id}

package/src/video/VideoEditor.tsx

@@ -1,7 +1,8 @@
 import { useCallback, useEffect, useRef, useState } from 'react'
-import { Crop, Magnet } from 'lucide-react'
+import { Crop, Info, Magnet } from 'lucide-react'
 import type { Project, VideoEditorProps } from '../types'
 import { VideoSourceCropModal } from '../crop/VideoSourceCropModal'
+import ControlsInfoModal, { VIDEO_CONTROLS } from '../ControlsInfoModal'
 import { getOverlayDesignCanvas } from './design-canvas'
 import { applyTheme, defaultMontajTheme } from '../theme'
 import { applyCutToItem, applyCutToTracks, collapseGaps, splitAtTime } from './cuts'
@@ -287,6 +288,7 @@ function ReviewSurface<P extends Project>({
   const [selectedIds, setSelectedIds] = useState<string[]>([])
   const primarySelectedId = selectedIds[0] ?? null
   const [rippleMode, setRippleMode]   = useState(false)
+  const [showControls, setShowControls] = useState(false)
   // Source-crop mode: when on, the VideoSourceCropModal opens for the selected
   // tracks[0] video item. Cleared when selection changes.
   const [cropMode, setCropMode]       = useState(false)
@@ -463,8 +465,16 @@ function ReviewSurface<P extends Project>({
           )}
         </div>
 
-        {/* Track controls bar — split + ripple + render */}
+        {/* Track controls bar — info + split + ripple + render */}
         <div className="shrink-0 flex items-center justify-end gap-1.5 px-3 py-1 border-t border-[var(--editor-border)] bg-[var(--editor-surface)]">
+          <button
+            onClick={() => setShowControls(true)}
+            title="Editor controls & shortcuts"
+            aria-label="Editor controls & shortcuts"
+            className="flex items-center justify-center w-5 h-5 rounded transition-colors text-[var(--editor-text)]/60 bg-transparent hover:text-[var(--editor-text)] mr-auto"
+          >
+            <Info size={12} />
+          </button>
           <button
             onClick={() => handleSplit()}
             title="Split at playhead (S) — selected item or all clips"
@@ -613,6 +623,15 @@ function ReviewSurface<P extends Project>({
         />
       )}
 
+      {/* Controls & shortcuts reference */}
+      {showControls && (
+        <ControlsInfoModal
+          title="Editor controls"
+          sections={VIDEO_CONTROLS}
+          onClose={() => setShowControls(false)}
+        />
+      )}
+
       {/* Render modal — adapter.render stream + host export controls */}
       {renderOpen && (
         <RenderModal