promptslide 0.2.0

package/src/core/transitions.ts

@@ -0,0 +1,200 @@
+/**
+ * Slide transition variants for the slide deck framework.
+ * These define how slides enter and exit during navigation.
+ */
+
+import type { Variants } from "framer-motion"
+
+import {
+  EASE_MORPH,
+  MORPH_DURATION,
+  SLIDE_DISTANCE,
+  SLIDE_TRANSITION,
+  SLIDE_TRANSITION_DURATION
+} from "./animation-config"
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+export type SlideTransitionType =
+  | "fade"
+  | "slide-left"
+  | "slide-right"
+  | "slide-up"
+  | "slide-down"
+  | "zoom"
+  | "zoom-fade"
+  | "morph"
+  | "none"
+
+export interface SlideTransitionConfig {
+  /** The transition type */
+  type: SlideTransitionType
+  /** Optional custom duration (overrides default) */
+  duration?: number
+  /** Whether to use directional transitions based on navigation direction */
+  directional?: boolean
+}
+
+// =============================================================================
+// STATIC VARIANTS (non-directional)
+// =============================================================================
+
+const fadeVariants: Variants = {
+  enter: { opacity: 0 },
+  center: { opacity: 1 },
+  exit: { opacity: 0 }
+}
+
+const slideLeftVariants: Variants = {
+  enter: { x: SLIDE_DISTANCE, opacity: 0 },
+  center: { x: 0, opacity: 1 },
+  exit: { x: -SLIDE_DISTANCE, opacity: 0 }
+}
+
+const slideRightVariants: Variants = {
+  enter: { x: -SLIDE_DISTANCE, opacity: 0 },
+  center: { x: 0, opacity: 1 },
+  exit: { x: SLIDE_DISTANCE, opacity: 0 }
+}
+
+const slideUpVariants: Variants = {
+  enter: { y: SLIDE_DISTANCE, opacity: 0 },
+  center: { y: 0, opacity: 1 },
+  exit: { y: -SLIDE_DISTANCE, opacity: 0 }
+}
+
+const slideDownVariants: Variants = {
+  enter: { y: -SLIDE_DISTANCE, opacity: 0 },
+  center: { y: 0, opacity: 1 },
+  exit: { y: SLIDE_DISTANCE, opacity: 0 }
+}
+
+const zoomVariants: Variants = {
+  enter: { scale: 0.8, opacity: 0 },
+  center: { scale: 1, opacity: 1 },
+  exit: { scale: 1.2, opacity: 0 }
+}
+
+const zoomFadeVariants: Variants = {
+  enter: { scale: 0.95, opacity: 0 },
+  center: { scale: 1, opacity: 1 },
+  exit: { scale: 1.05, opacity: 0 }
+}
+
+const morphVariants: Variants = {
+  enter: {
+    opacity: 0,
+    zIndex: 1
+  },
+  center: {
+    opacity: 1,
+    zIndex: 1,
+    transition: {
+      opacity: { delay: 0.05, duration: 0.25 }
+    }
+  },
+  exit: {
+    opacity: 0,
+    zIndex: 0,
+    transition: {
+      opacity: { duration: MORPH_DURATION, ease: EASE_MORPH }
+    }
+  }
+}
+
+const noneVariants: Variants = {
+  enter: {},
+  center: {},
+  exit: {}
+}
+
+// =============================================================================
+// VARIANT REGISTRY
+// =============================================================================
+
+export const SLIDE_VARIANTS: Record<SlideTransitionType, Variants> = {
+  fade: fadeVariants,
+  "slide-left": slideLeftVariants,
+  "slide-right": slideRightVariants,
+  "slide-up": slideUpVariants,
+  "slide-down": slideDownVariants,
+  zoom: zoomVariants,
+  "zoom-fade": zoomFadeVariants,
+  morph: morphVariants,
+  none: noneVariants
+}
+
+// =============================================================================
+// DIRECTIONAL VARIANTS (based on navigation direction)
+// =============================================================================
+
+export function createDirectionalVariants(axis: "x" | "y" = "x"): (direction: number) => Variants {
+  return (direction: number) => ({
+    enter: {
+      [axis]: direction > 0 ? SLIDE_DISTANCE : -SLIDE_DISTANCE,
+      opacity: 0
+    },
+    center: {
+      [axis]: 0,
+      opacity: 1
+    },
+    exit: {
+      [axis]: direction < 0 ? SLIDE_DISTANCE : -SLIDE_DISTANCE,
+      opacity: 0
+    }
+  })
+}
+
+/** Horizontal directional slide (left/right based on direction) */
+export const directionalSlideX = createDirectionalVariants("x")
+
+/** Vertical directional slide (up/down based on direction) */
+export const directionalSlideY = createDirectionalVariants("y")
+
+// =============================================================================
+// HELPER FUNCTIONS
+// =============================================================================
+
+export function getSlideVariants(
+  config: SlideTransitionConfig | SlideTransitionType,
+  direction: number = 1
+): Variants {
+  const type = typeof config === "string" ? config : config.type
+  const directional = typeof config === "object" ? config.directional : false
+
+  if (directional && (type === "slide-left" || type === "slide-right")) {
+    return directionalSlideX(direction)
+  }
+
+  if (directional && (type === "slide-up" || type === "slide-down")) {
+    return directionalSlideY(direction)
+  }
+
+  return SLIDE_VARIANTS[type]
+}
+
+export function getSlideTransition(config?: SlideTransitionConfig | SlideTransitionType): {
+  duration: number
+  ease: typeof SLIDE_TRANSITION.ease
+} {
+  if (!config) return SLIDE_TRANSITION
+
+  const type = typeof config === "string" ? config : config.type
+
+  const defaultDuration = type === "morph" ? MORPH_DURATION : SLIDE_TRANSITION_DURATION
+
+  const duration = typeof config === "object" && config.duration ? config.duration : defaultDuration
+
+  return {
+    ...SLIDE_TRANSITION,
+    duration
+  }
+}
+
+// =============================================================================
+// DEFAULT EXPORT
+// =============================================================================
+
+export const DEFAULT_SLIDE_TRANSITION: SlideTransitionType = "fade"

package/src/core/types.ts

@@ -0,0 +1,136 @@
+/**
+ * Shared types for the slide deck framework.
+ */
+
+import type { SlideTransitionType } from "./transitions"
+
+// =============================================================================
+// SLIDE CONFIGURATION TYPES
+// =============================================================================
+
+/**
+ * Props that all slide components receive.
+ */
+export interface SlideProps {
+  slideNumber: number
+  totalSlides: number
+}
+
+/**
+ * A React component that renders a slide.
+ */
+export type SlideComponent = React.ComponentType<SlideProps>
+
+/**
+ * Configuration for a single slide including its animation step count.
+ * The `steps` property declares how many animation steps the slide has,
+ * eliminating the need for runtime step discovery.
+ */
+export interface SlideConfig {
+  /** The slide component to render */
+  component: SlideComponent
+  /** Number of animation steps (0 = no animations). This is the max step number used in <Animated step={N}> */
+  steps: number
+  /** Display name for grid view thumbnails, navigation, and accessibility */
+  title?: string
+  /** Speaker notes (not rendered on slide, shown in notes panel) */
+  notes?: string
+  /** Per-slide transition override (falls back to deck-level transition) */
+  transition?: SlideTransitionType
+  /** Section/chapter name for grouping slides in grid view */
+  section?: string
+}
+
+// =============================================================================
+// NAVIGATION TYPES
+// =============================================================================
+
+/**
+ * Direction of slide navigation.
+ * - 1: Forward (next slide)
+ * - -1: Backward (previous slide)
+ * - 0: Direct jump (no direction)
+ */
+export type NavigationDirection = -1 | 0 | 1
+
+// =============================================================================
+// THEME CONFIGURATION TYPES
+// =============================================================================
+
+/**
+ * Logo variants for different contexts.
+ */
+export interface ThemeLogos {
+  /** Full logo (default, used in footers) */
+  full?: string
+  /** Icon-only mark (used in compact spaces) */
+  icon?: string
+  /** Light version for dark backgrounds */
+  fullLight?: string
+  /** Light icon for dark backgrounds */
+  iconLight?: string
+}
+
+/**
+ * Brand color overrides using OKLCH strings.
+ * Injected as CSS custom properties at runtime.
+ * If omitted, the existing globals.css values apply.
+ */
+export interface ThemeColors {
+  primary?: string
+  primaryForeground?: string
+  secondary?: string
+  secondaryForeground?: string
+  accent?: string
+  accentForeground?: string
+}
+
+/**
+ * Corporate visual assets (paths relative to public/).
+ */
+export interface ThemeAssets {
+  /** Background image URL (e.g. for title slides) */
+  backgroundImage?: string
+  /** Subtle pattern overlay URL */
+  patternImage?: string
+}
+
+/**
+ * Typography preferences. Font names must be loaded via
+ * <link> in index.html or @font-face in globals.css.
+ */
+export interface ThemeFonts {
+  heading?: string
+  body?: string
+}
+
+/**
+ * Full theme configuration.
+ */
+export interface ThemeConfig {
+  /** Company/product name (shown in footers) */
+  name: string
+  /** Optional tagline */
+  tagline?: string
+  /** Logo configuration */
+  logo?: ThemeLogos
+  /** Brand color overrides (OKLCH strings) */
+  colors?: ThemeColors
+  /** Corporate visual assets */
+  assets?: ThemeAssets
+  /** Typography preferences */
+  fonts?: ThemeFonts
+}
+
+// =============================================================================
+// LAYOUT BASE PROPS
+// =============================================================================
+
+/**
+ * Base props shared by all layout components.
+ */
+export interface LayoutBaseProps extends SlideProps {
+  children?: React.ReactNode
+  hideFooter?: boolean
+  className?: string
+}

package/src/core/use-slide-navigation.ts

@@ -0,0 +1,142 @@
+import { useCallback, useEffect, useState } from "react"
+
+import type { NavigationDirection, SlideConfig } from "./types"
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+type NavigationStatus = "idle" | "transitioning"
+
+type QueuedAction = "advance" | "goBack" | null
+
+interface NavigationState {
+  status: NavigationStatus
+  direction: NavigationDirection
+}
+
+export interface UseSlideNavigationOptions {
+  slides: SlideConfig[]
+  initialSlide?: number
+  onSlideChange?: (slideIndex: number) => void
+}
+
+export interface UseSlideNavigationReturn {
+  currentSlide: number
+  animationStep: number
+  totalSteps: number
+  direction: NavigationDirection
+  isTransitioning: boolean
+  showAllAnimations: boolean
+  advance: () => void
+  goBack: () => void
+  goToSlide: (index: number) => void
+  onTransitionComplete: () => void
+}
+
+// =============================================================================
+// HOOK
+// =============================================================================
+
+export function useSlideNavigation({
+  slides,
+  initialSlide = 0,
+  onSlideChange
+}: UseSlideNavigationOptions): UseSlideNavigationReturn {
+  const [currentSlide, setCurrentSlide] = useState(initialSlide)
+  const [animationStep, setAnimationStep] = useState(0)
+
+  const [navState, setNavState] = useState<NavigationState>({
+    status: "idle",
+    direction: 0
+  })
+
+  const [queuedAction, setQueuedAction] = useState<QueuedAction>(null)
+
+  const totalSteps = slides[currentSlide]?.steps ?? 0
+
+  const onTransitionComplete = useCallback(() => {
+    setNavState(prev => {
+      if (prev.status === "transitioning") {
+        return { status: "idle", direction: 0 }
+      }
+      return prev
+    })
+  }, [])
+
+  const advance = useCallback(() => {
+    if (navState.status === "transitioning") {
+      setQueuedAction("advance")
+      return
+    }
+
+    const currentTotalSteps = slides[currentSlide]?.steps ?? 0
+
+    if (animationStep >= currentTotalSteps) {
+      const nextSlide = (currentSlide + 1) % slides.length
+      setNavState({ status: "transitioning", direction: 1 })
+      setAnimationStep(0)
+      setCurrentSlide(nextSlide)
+      onSlideChange?.(nextSlide)
+    } else {
+      setAnimationStep(prev => prev + 1)
+    }
+  }, [navState.status, animationStep, currentSlide, slides, onSlideChange])
+
+  const goBack = useCallback(() => {
+    if (navState.status === "transitioning") {
+      setQueuedAction("goBack")
+      return
+    }
+
+    if (animationStep <= 0) {
+      const prevSlide = (currentSlide - 1 + slides.length) % slides.length
+      const prevSlideSteps = slides[prevSlide]?.steps ?? 0
+      setNavState({ status: "transitioning", direction: -1 })
+      setAnimationStep(prevSlideSteps)
+      setCurrentSlide(prevSlide)
+      onSlideChange?.(prevSlide)
+    } else {
+      setAnimationStep(prev => prev - 1)
+    }
+  }, [navState.status, animationStep, currentSlide, slides, onSlideChange])
+
+  const goToSlide = useCallback(
+    (index: number) => {
+      if (index < 0 || index >= slides.length || index === currentSlide) {
+        return
+      }
+
+      const direction = index > currentSlide ? 1 : -1
+      setNavState({ status: "transitioning", direction })
+      setAnimationStep(0)
+      setCurrentSlide(index)
+      onSlideChange?.(index)
+    },
+    [currentSlide, slides.length, onSlideChange]
+  )
+
+  useEffect(() => {
+    if (navState.status === "idle" && queuedAction !== null) {
+      setQueuedAction(null)
+      if (queuedAction === "advance") {
+        advance()
+      } else if (queuedAction === "goBack") {
+        goBack()
+      }
+    }
+  }, [navState.status, queuedAction, advance, goBack])
+
+  return {
+    currentSlide,
+    animationStep,
+    totalSteps,
+    direction: navState.direction,
+    isTransitioning: navState.status !== "idle",
+    showAllAnimations: navState.direction === -1 && navState.status === "transitioning",
+    advance,
+    goBack,
+    goToSlide,
+    onTransitionComplete
+  }
+}

package/src/core/utils.ts

@@ -0,0 +1,8 @@
+import type { ClassValue } from "clsx"
+
+import { clsx } from "clsx"
+import { twMerge } from "tailwind-merge"
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs))
+}

package/src/index.mjs

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+
+import { readFileSync } from "node:fs"
+import { join, dirname } from "node:path"
+import { fileURLToPath } from "node:url"
+
+import { bold, dim, red } from "./utils/ansi.mjs"
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = dirname(__filename)
+
+function getVersion() {
+  const pkg = JSON.parse(readFileSync(join(__dirname, "..", "package.json"), "utf-8"))
+  return pkg.version
+}
+
+function printHelp() {
+  console.log()
+  console.log(`  ${bold("promptslide")} ${dim(`v${getVersion()}`)}`)
+  console.log()
+  console.log(`  ${bold("Commands:")}`)
+  console.log(`    create ${dim("<dir>")}   Scaffold a new slide deck project`)
+  console.log(`    studio          Start the development studio`)
+  console.log(`    build           Build for production`)
+  console.log(`    preview         Preview the production build`)
+  console.log()
+  console.log(`  ${bold("Options:")}`)
+  console.log(`    --help, -h      Show this help message`)
+  console.log(`    --version, -v   Show version number`)
+  console.log()
+}
+
+const command = process.argv[2]
+const args = process.argv.slice(3)
+
+switch (command) {
+  case "create": {
+    const { create } = await import("./commands/create.mjs")
+    await create(args)
+    break
+  }
+  case "studio": {
+    const { studio } = await import("./commands/studio.mjs")
+    await studio(args)
+    break
+  }
+  case "build": {
+    const { build } = await import("./commands/build.mjs")
+    await build(args)
+    break
+  }
+  case "preview": {
+    const { preview } = await import("./commands/preview.mjs")
+    await preview(args)
+    break
+  }
+  case "--help":
+  case "-h":
+  case undefined:
+    printHelp()
+    break
+  case "--version":
+  case "-v":
+    console.log(getVersion())
+    break
+  default:
+    console.error(`  ${red("Error:")} Unknown command "${command}"`)
+    printHelp()
+    process.exit(1)
+}

package/src/utils/ansi.mjs

@@ -0,0 +1,5 @@
+export const bold = s => `\x1b[1m${s}\x1b[0m`
+export const green = s => `\x1b[32m${s}\x1b[0m`
+export const cyan = s => `\x1b[36m${s}\x1b[0m`
+export const red = s => `\x1b[31m${s}\x1b[0m`
+export const dim = s => `\x1b[2m${s}\x1b[0m`

package/src/utils/colors.mjs

@@ -0,0 +1,44 @@
+export function hexToOklch(hex) {
+  hex = hex.replace("#", "")
+  const r = parseInt(hex.slice(0, 2), 16) / 255
+  const g = parseInt(hex.slice(2, 4), 16) / 255
+  const b = parseInt(hex.slice(4, 6), 16) / 255
+
+  // sRGB → linear RGB
+  const toLinear = c => (c <= 0.04045 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4))
+  const lr = toLinear(r)
+  const lg = toLinear(g)
+  const lb = toLinear(b)
+
+  // Linear RGB → LMS
+  const l = 0.4122214708 * lr + 0.5363325363 * lg + 0.0514459929 * lb
+  const m = 0.2119034982 * lr + 0.6806995451 * lg + 0.1073969566 * lb
+  const s = 0.0883024619 * lr + 0.2817188376 * lg + 0.6299787005 * lb
+
+  // LMS → OKLAB
+  const l_ = Math.cbrt(l)
+  const m_ = Math.cbrt(m)
+  const s_ = Math.cbrt(s)
+  const L = 0.2104542553 * l_ + 0.793617785 * m_ - 0.0040720468 * s_
+  const a = 1.9779984951 * l_ - 2.428592205 * m_ + 0.4505937099 * s_
+  const bv = 0.0259040371 * l_ + 0.7827717662 * m_ - 0.808675766 * s_
+
+  // OKLAB → OKLCH
+  const C = Math.sqrt(a * a + bv * bv)
+  let H = Math.atan2(bv, a) * (180 / Math.PI)
+  if (H < 0) H += 360
+
+  const round = (n, d = 3) => +n.toFixed(d)
+  return `oklch(${round(L)} ${round(C)} ${round(H)})`
+}
+
+export function hexToOklchDark(hex) {
+  const oklch = hexToOklch(hex)
+  const match = oklch.match(/oklch\(([\d.]+) ([\d.]+) ([\d.]+)\)/)
+  const L = Math.min(1, parseFloat(match[1]) + 0.05)
+  return `oklch(${+L.toFixed(3)} ${match[2]} ${match[3]})`
+}
+
+export function isValidHex(hex) {
+  return /^#?[0-9a-fA-F]{6}$/.test(hex)
+}

package/src/utils/prompts.mjs

@@ -0,0 +1,50 @@
+import { createInterface } from "node:readline"
+
+import { dim } from "./ansi.mjs"
+
+let _rl = null
+let _closed = false
+
+function getRL() {
+  if (!_rl && !_closed) {
+    _rl = createInterface({ input: process.stdin, output: process.stdout })
+    _rl.on("close", () => {
+      _rl = null
+      _closed = true
+    })
+  }
+  return _rl
+}
+
+export function closePrompts() {
+  if (_rl) {
+    _rl.close()
+    _rl = null
+  }
+}
+
+export function prompt(question, defaultValue) {
+  const rl = getRL()
+  if (!rl) return Promise.resolve(defaultValue || "")
+  return new Promise(resolve => {
+    const suffix = defaultValue ? ` ${dim(`(${defaultValue})`)} ` : " "
+    rl.question(`  ${question}${suffix}`, answer => {
+      resolve(answer.trim() || defaultValue || "")
+    })
+    rl.once("close", () => resolve(defaultValue || ""))
+  })
+}
+
+export function confirm(question, defaultYes = true) {
+  const rl = getRL()
+  if (!rl) return Promise.resolve(defaultYes)
+  return new Promise(resolve => {
+    const hint = defaultYes ? "Y/n" : "y/N"
+    rl.question(`  ${question} ${dim(`(${hint})`)} `, answer => {
+      const a = answer.trim().toLowerCase()
+      if (!a) return resolve(defaultYes)
+      resolve(a === "y" || a === "yes")
+    })
+    rl.once("close", () => resolve(defaultYes))
+  })
+}

package/src/utils/tsconfig.mjs

@@ -0,0 +1,35 @@
+import { writeFileSync } from "node:fs"
+import { join } from "node:path"
+
+export function ensureTsConfig(cwd) {
+  const tsconfigPath = join(cwd, "tsconfig.json")
+
+  const tsconfig = {
+    compilerOptions: {
+      target: "ES2020",
+      useDefineForClassFields: true,
+      lib: ["ES2020", "DOM", "DOM.Iterable"],
+      module: "ESNext",
+      skipLibCheck: true,
+      moduleResolution: "bundler",
+      allowImportingTsExtensions: true,
+      isolatedModules: true,
+      moduleDetection: "force",
+      noEmit: true,
+      jsx: "react-jsx",
+      strict: true,
+      noUnusedLocals: true,
+      noUnusedParameters: true,
+      noFallthroughCasesInSwitch: true,
+      noUncheckedIndexedAccess: true,
+      baseUrl: ".",
+      paths: {
+        "@/*": ["./src/*"],
+        "promptslide": ["./node_modules/promptslide/src/core/index.ts"]
+      }
+    },
+    include: ["src"]
+  }
+
+  writeFileSync(tsconfigPath, JSON.stringify(tsconfig, null, 2) + "\n")
+}