@nyuccl/smile 0.2.0-beta.0

package/dist/runtime/composables/useColorMode.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Creates a color mode manager for different UI contexts
+ * @param {string} scope - Either 'global' or 'experiment' to specify which scope to manage
+ * @param {object} options - Configuration options
+ * @returns {object} Color mode management object
+ */
+export function useSmileColorMode(scope?: string, _options?: {}): object;
+/**
+ * Get the current color mode for a specific scope without creating a new instance
+ * @param {string} scope - Either 'global' or 'experiment'
+ * @returns {string} Current color mode ('auto', 'light', or 'dark')
+ */
+export function getColorMode(scope?: string): string;
+/**
+ * Set the color mode for a specific scope
+ * @param {string} scope - Either 'global' or 'experiment'
+ * @param {string} mode - Color mode ('auto', 'light', or 'dark')
+ */
+export function setColorMode(scope: string, mode: string): void;

package/dist/runtime/composables/useColorMode.js

@@ -0,0 +1,292 @@
+/**
+ * Custom color mode composable for SMILE UI
+ * Manages separate color modes for different UI contexts:
+ * - 'global': Applies to html element (SmileAppSidebar button)
+ * - 'experiment': Applies to experiment containers only (dev tools buttons)
+ */
+
+import { computed, watch, nextTick } from 'vue'
+import { usePreferredDark } from '@vueuse/core'
+import useAPI from './useAPI.js'
+
+// Lazy initialization — useAPI() requires an active Pinia instance,
+// which isn't available at module scope during SSR. We defer init
+// until one of the exported functions is called inside a Vue context.
+let _initialized = false
+let api, globalColorMode, experimentColorMode
+
+function ensureInit() {
+  if (_initialized) return
+  _initialized = true
+  api = useAPI()
+  globalColorMode = computed({
+    get: () => api.store.dev.globalColorMode,
+    set: (value) => {
+      api.store.dev.globalColorMode = value
+    },
+  })
+  experimentColorMode = computed({
+    get: () => api.store.dev.experimentColorMode,
+    set: (value) => {
+      api.store.dev.experimentColorMode = value
+    },
+  })
+}
+
+// Global MutationObserver for portaled elements
+let portalObserver = null
+const portalSelectors = [
+  '[data-slot="popover-content"]',
+  '[data-slot="select-content"]',
+  '[data-slot="dialog-content"]',
+  '[data-slot="tooltip-content"]',
+  '[data-slot="dropdown-menu-content"]',
+  '[data-slot="context-menu-content"]',
+  '[data-slot="menubar-content"]',
+]
+
+// Global set to track experiment portal triggers
+const experimentPortalTriggers = new Set()
+
+// Function to check if an element is within an experiment context
+// eslint-disable-next-line no-unused-vars
+const _isInExperimentContext = (element) => {
+  // Check if the element or its ancestors have experiment-related selectors
+  const experimentSelectors = [
+    '#main-app',
+    '.device-container',
+    '.fullscreen-container',
+    '.dev-color-mode .device-wrapper',
+    '[data-experiment-scope]', // We can add this attribute to experiment containers
+  ]
+
+  return experimentSelectors.some((selector) => {
+    const container = document.querySelector(selector)
+    return container && container.contains(element)
+  })
+}
+
+// Function to apply color mode to experiment-scoped portaled elements only
+const applyColorModeToExperimentPortals = (mode) => {
+  portalSelectors.forEach((selector) => {
+    document.querySelectorAll(selector).forEach((el) => {
+      // Only apply to portaled elements that have a data attribute marking them as experiment-scoped
+      if (el.hasAttribute('data-experiment-portal')) {
+        el.classList.remove('light', 'dark')
+        if (mode === 'dark' || mode === 'light') {
+          el.classList.add(mode)
+        }
+      }
+    })
+  })
+}
+
+// Set up MutationObserver for dynamically created portaled elements
+const setupPortalObserver = () => {
+  if (portalObserver || typeof window === 'undefined') return
+
+  portalObserver = new MutationObserver((mutations) => {
+    mutations.forEach((mutation) => {
+      mutation.addedNodes.forEach((node) => {
+        if (node.nodeType === Node.ELEMENT_NODE) {
+          // Check if the added node or any of its descendants match our portal selectors
+          portalSelectors.forEach((selector) => {
+            const matchingElements = []
+
+            if (node.matches && node.matches(selector)) {
+              matchingElements.push(node)
+            }
+            // Also check descendants
+            if (node.querySelectorAll) {
+              matchingElements.push(...node.querySelectorAll(selector))
+            }
+
+            matchingElements.forEach((el) => {
+              // Check if this portal element should be treated as experiment-scoped
+              // We'll look for triggers within experiment containers
+              if (shouldBeExperimentPortal(el)) {
+                el.setAttribute('data-experiment-portal', 'true')
+
+                // Apply current experiment color mode
+                const currentMode
+                  = experimentColorMode.value === 'auto'
+                    ? usePreferredDark().value
+                      ? 'dark'
+                      : 'light'
+                    : experimentColorMode.value
+
+                el.classList.remove('light', 'dark')
+                if (currentMode === 'dark' || currentMode === 'light') {
+                  el.classList.add(currentMode)
+                }
+              }
+            })
+          })
+        }
+      })
+    })
+  })
+
+  portalObserver.observe(document.body, {
+    childList: true,
+    subtree: true,
+  })
+}
+
+// Function to determine if a portaled element should use experiment color mode
+// eslint-disable-next-line no-unused-vars
+const shouldBeExperimentPortal = (_portalElement) => {
+  // Simple approach: check if any experiment containers exist and have focus/active elements
+  const experimentContainer = document.querySelector('[data-experiment-scope]')
+  if (!experimentContainer) return false
+
+  // Check if there are any open popover/select triggers within the experiment container
+  const openTriggers = experimentContainer.querySelectorAll('[data-state="open"], [aria-expanded="true"]')
+  return openTriggers.length > 0
+}
+
+// Setup click tracking to identify experiment-originating portals
+const setupExperimentPortalTracking = () => {
+  if (typeof window === 'undefined') return
+
+  document.addEventListener(
+    'click',
+    (event) => {
+      const target = event.target
+      const experimentScope = target.closest('[data-experiment-scope]')
+
+      if (experimentScope) {
+        // Mark this as a potential experiment portal trigger
+        experimentPortalTriggers.add(target)
+
+        // Clean up old triggers after a delay
+        setTimeout(() => {
+          experimentPortalTriggers.delete(target)
+        }, 1000)
+      }
+    },
+    true,
+  ) // Use capture phase to catch before portal creation
+}
+
+/**
+ * Creates a color mode manager for different UI contexts
+ * @param {string} scope - Either 'global' or 'experiment' to specify which scope to manage
+ * @param {object} options - Configuration options
+ * @returns {object} Color mode management object
+ */
+// eslint-disable-next-line no-unused-vars
+export function useSmileColorMode(scope = 'experiment', _options = {}) {
+  ensureInit()
+  const preferredDark = usePreferredDark()
+
+  // Determine which mode ref to use based on scope
+  const modeRef = scope === 'global' ? globalColorMode : experimentColorMode
+
+  // System computed value
+  const system = computed(() => (preferredDark.value ? 'dark' : 'light'))
+
+  // Actual resolved state (auto -> system preference)
+  const state = computed(() => (modeRef.value === 'auto' ? system.value : modeRef.value))
+
+  // Function to apply color mode to specific selector
+  const applyColorMode = (selector, mode) => {
+    const el = document.querySelector(selector)
+    if (!el) return
+
+    // Remove existing mode classes
+    el.classList.remove('light', 'dark')
+
+    // Add the new mode class
+    if (mode === 'dark' || mode === 'light') {
+      el.classList.add(mode)
+    }
+  }
+
+  // Watch for changes and apply to appropriate selectors
+  watch(
+    state,
+    (newMode) => {
+      nextTick(() => {
+        if (scope === 'global') {
+          // Apply to html element for global theming
+          applyColorMode('html', newMode)
+          // Also apply to elements with global-color-mode class
+          applyColorMode('.global-color-mode', newMode)
+        }
+        else if (scope === 'experiment') {
+          // Apply to experiment containers only
+          applyColorMode('.device-container', newMode)
+          applyColorMode('.dev-color-mode', newMode)
+          applyColorMode('.device-wrapper', newMode)
+
+          // Apply to experiment-scoped portaled UI components and set up observer for new ones
+          applyColorModeToExperimentPortals(newMode)
+          setupPortalObserver()
+          setupExperimentPortalTracking()
+        }
+      })
+    },
+    { immediate: true },
+  )
+
+  return {
+    // Reactive color mode value (can be 'auto', 'light', or 'dark')
+    mode: modeRef,
+
+    // System preference
+    system,
+
+    // Resolved state (never 'auto', always 'light' or 'dark')
+    state,
+
+    // Convenience setter functions
+    setLight: () => {
+      modeRef.value = 'light'
+    },
+    setDark: () => {
+      modeRef.value = 'dark'
+    },
+    setAuto: () => {
+      modeRef.value = 'auto'
+    },
+
+    // Toggle function
+    toggle: () => {
+      if (modeRef.value === 'auto') {
+        modeRef.value = 'light'
+      }
+      else if (modeRef.value === 'light') {
+        modeRef.value = 'dark'
+      }
+      else {
+        modeRef.value = 'auto'
+      }
+    },
+  }
+}
+
+/**
+ * Get the current color mode for a specific scope without creating a new instance
+ * @param {string} scope - Either 'global' or 'experiment'
+ * @returns {string} Current color mode ('auto', 'light', or 'dark')
+ */
+export function getColorMode(scope = 'experiment') {
+  ensureInit()
+  return scope === 'global' ? globalColorMode.value : experimentColorMode.value
+}
+
+/**
+ * Set the color mode for a specific scope
+ * @param {string} scope - Either 'global' or 'experiment'
+ * @param {string} mode - Color mode ('auto', 'light', or 'dark')
+ */
+export function setColorMode(scope, mode) {
+  ensureInit()
+  if (scope === 'global') {
+    globalColorMode.value = mode
+  }
+  else {
+    experimentColorMode.value = mode
+  }
+}

package/dist/runtime/composables/useStepper.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @class StepperAPI
+ * @description Wraps a Stepper instance to provide a consistent API for managing multi-step processes
+ */
+/**
+ * Creates or retrieves a stepper instance for the current view
+ * @function useStepper
+ * @param {string} view - The view name to create/retrieve the stepper for
+ * @returns {object} The stepper instance for the current view
+ * @description This composable manages stepper instances on a per-view basis.
+ * It ensures that:
+ * - Each view has its own stepper instance stored in the global smilestore
+ * - The dev bar is notified that the view provides a trial stepper
+ * - Stepper instances are reused when revisiting a view
+ * The stepper provides functionality for managing multi-step processes and
+ * tracking state within experiment views.
+ */
+export function useStepper(view: string): object;
+export default useStepper;

package/dist/runtime/composables/useStepper.js

@@ -0,0 +1,71 @@
+/**
+ * @module useStepper
+ * @description Manages stepper instances on a per-view basis.
+ * Provides functionality for:
+ * - Creating or retrieving a stepper instance for the current view
+ * - Setting the viewProvidesStepper flag  in the dev store
+ * - Storing the stepper instance in the global smilestore
+ */
+import Stepper from '../core/stepper/Stepper.js'
+import useSmileStore from '../stores/smilestore.js'
+import useLog from '../stores/log.js'
+/**
+ * @class StepperAPI
+ * @description Wraps a Stepper instance to provide a consistent API for managing multi-step processes
+ */
+
+/**
+ * Creates or retrieves a stepper instance for the current view
+ * @function useStepper
+ * @param {string} view - The view name to create/retrieve the stepper for
+ * @returns {object} The stepper instance for the current view
+ * @description This composable manages stepper instances on a per-view basis.
+ * It ensures that:
+ * - Each view has its own stepper instance stored in the global smilestore
+ * - The dev bar is notified that the view provides a trial stepper
+ * - Stepper instances are reused when revisiting a view
+ * The stepper provides functionality for managing multi-step processes and
+ * tracking state within experiment views.
+ */
+export function useStepper(view) {
+  const smilestore = useSmileStore()
+  const log = useLog()
+
+  // Set viewProvidesStepper to true for the dev bar
+  if (smilestore.dev) {
+    smilestore.dev.viewProvidesStepper = true
+  }
+
+  // Check if stepper already exists in global state
+  let stepper = smilestore.browserEphemeral.steppers?.[view]
+
+  if (!stepper) {
+    // Create new stepper instance if none exists
+    const savedState = smilestore.getStepper(view)?.data
+    if (savedState) {
+      try {
+        log.debug('STEPPER: Loading saved stepper state from smilestore for view', view)
+        stepper = new Stepper({ serializedState: savedState.stepperState, store: smilestore })
+      }
+      catch (error) {
+        log.error('STEPPER: Failed to load saved state, creating new stepper:', error.message)
+        stepper = new Stepper({ id: '/', parent: null, data: { gvars: {} }, store: smilestore })
+      }
+    }
+    else {
+      log.debug('STEPPER: Initializing stepper for view', view)
+      stepper = new Stepper({ id: '/', parent: null, data: { gvars: {} }, store: smilestore })
+    }
+    stepper.name = view
+    // Register stepper if not already registered
+    // console.log('STEPPER: Registering stepper for view', stepper.name)
+    if (view) {
+      stepper = smilestore.registerStepper(view, stepper)
+    }
+  }
+
+  // Return the StepperAPI instance
+  return stepper
+}
+
+export default useStepper

package/dist/runtime/composables/useTimeline.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Timeline management composable for handling view navigation
+ * @function useTimeline
+ * @returns {object} Timeline methods and utilities
+ */
+export default function useTimeline(): object;

package/dist/runtime/composables/useTimeline.js

@@ -0,0 +1,188 @@
+/**
+ * @module useTimeline
+ * @description Timeline management composable for handling view navigation in the SMILE framework.
+ * Provides functionality for:
+ * - Sequential navigation between views
+ * - Route metadata handling
+ * - Navigation state management
+ * - Next/previous view lookups
+ *
+ * In the Nuxt module, experiment routes are NOT registered with Vue Router
+ * (they all hit the catch-all route). So route metadata (next, prev, etc.)
+ * is looked up from $timeline.getViewForPath() instead of route.meta.
+ *
+ * Route paths under /dev/ and /presentation/ are transparently handled:
+ * the prefix is stripped for timeline lookups and re-added for navigation.
+ */
+import { useRoute, useRouter, useNuxtApp, navigateTo as nuxtNavigateTo } from '#imports'
+import useSmileStore from '../stores/smilestore.js'
+import useLog from '../stores/log.js'
+
+/**
+ * Timeline management composable for handling view navigation
+ * @function useTimeline
+ * @returns {object} Timeline methods and utilities
+ */
+export default function useTimeline() {
+  const smilestore = useSmileStore()
+  const route = useRoute()
+  // eslint-disable-next-line no-unused-vars
+  const _router = useRouter()
+  const log = useLog()
+
+  /**
+   * Detects the current route prefix ('/dev', '/presentation', or '').
+   * @returns {string} The prefix string
+   */
+  const _getRoutePrefix = () => {
+    const path = route.path
+    if (path.startsWith('/dev/') || path === '/dev') return '/dev'
+    if (path.startsWith('/presentation/') || path === '/presentation') return '/presentation'
+    return ''
+  }
+
+  /**
+   * Strips /dev or /presentation prefix from a path to get the experiment path.
+   * @param {string} path - The full route path
+   * @returns {string} The experiment path without prefix
+   */
+  const _stripPrefix = (path) => {
+    return path.replace(/^\/(dev|presentation)(\/|$)/, '/') || '/'
+  }
+
+  /**
+   * Gets the timeline route config for the current path.
+   * Strips /dev or /presentation prefix before lookup.
+   * Falls back to null if $timeline isn't available yet.
+   */
+  const _getTimelineRoute = () => {
+    const nuxtApp = useNuxtApp()
+    const timeline = nuxtApp.$timeline
+    if (!timeline) return null
+    const experimentPath = _stripPrefix(route.path)
+    return timeline.getViewForPath(experimentPath)
+  }
+
+  /**
+   * Looks up the next route in the navigation sequence for a given route name
+   * @param {string} routeName - The name of the route to look up the next route for
+   * @returns {object | null} Route object with path and query params, or null if no next route found
+   */
+  const lookupNext = (routeName) => {
+    const nuxtApp = useNuxtApp()
+    const timeline = nuxtApp.$timeline
+    if (!timeline) return null
+
+    const currentRoute = timeline.getRouteByName(routeName)
+    if (!currentRoute) return null
+
+    if (currentRoute.meta?.next) {
+      const nextRoute = timeline.getRouteByName(currentRoute.meta.next)
+      if (nextRoute) {
+        const prefix = _getRoutePrefix()
+        return {
+          path: prefix + nextRoute.path,
+          query: route.query,
+        }
+      }
+    }
+    return null
+  }
+
+  /**
+   * Gets the next view in the navigation sequence based on current route metadata
+   * @returns {object | null} Route object with path and query params, or null if no next view
+   */
+  const nextView = () => {
+    const config = _getTimelineRoute()
+    if (config?.meta?.next) {
+      const nuxtApp = useNuxtApp()
+      const timeline = nuxtApp.$timeline
+      const nextRoute = timeline?.getRouteByName(config.meta.next)
+      if (nextRoute) {
+        const prefix = _getRoutePrefix()
+        return { path: prefix + nextRoute.path, query: route.query }
+      }
+    }
+    return null
+  }
+
+  /**
+   * Gets the previous view in the navigation sequence based on current route metadata
+   * @returns {object | null} Route object with path and query params, or null if no previous view
+   */
+  const prevView = () => {
+    const config = _getTimelineRoute()
+    if (config?.meta?.prev) {
+      const nuxtApp = useNuxtApp()
+      const timeline = nuxtApp.$timeline
+      const prevRoute = timeline?.getRouteByName(config.meta.prev)
+      if (prevRoute) {
+        const prefix = _getRoutePrefix()
+        return { path: prefix + prevRoute.path, query: route.query }
+      }
+    }
+    return null
+  }
+
+  /**
+   * Navigates to a specific view with optional force parameter
+   * @param {string} view - Name of the view to navigate to
+   * @param {boolean} [force] - Whether to force navigation by temporarily disabling navigation guards
+   * @returns {Promise<void>}
+   */
+  const goToView = async (view, force = true) => {
+    // Look up path from timeline since experiment routes aren't in Vue Router
+    const nuxtApp = useNuxtApp()
+    const timeline = nuxtApp.$timeline
+    const targetRoute = timeline?.getRouteByName(view)
+    const basePath = targetRoute ? targetRoute.path : `/${view}`
+    const prefix = _getRoutePrefix()
+    const target = prefix + basePath
+
+    if (force) {
+      smilestore.browserEphemeral.forceNavigate = true
+      await nuxtNavigateTo(target)
+      smilestore.browserEphemeral.forceNavigate = false
+    }
+    else {
+      await nuxtNavigateTo(target)
+    }
+  }
+
+  /**
+   * Internal navigation handler that manages state updates and data saving
+   * @private
+   * @param {object} goto - Route object to navigate to (with path, not name)
+   */
+  const _doNavigate = (goto) => {
+    // sets the current page as done
+    smilestore.browserEphemeral.currentViewDone = true
+
+    if (smilestore.config.autoSave) {
+      log.log('TIMELINE STEPPER: Attempting auto saving on navigation')
+      smilestore.saveData() // automatically saves data
+    }
+    if (goto) nuxtNavigateTo(goto)
+  }
+
+  /**
+   * Navigates to the next view in sequence, optionally executing a callback first
+   * @param {Function} [fn] - Optional callback to execute before navigation
+   */
+  const goNextView = (fn) => {
+    if (fn) fn()
+    _doNavigate(nextView())
+  }
+
+  /**
+   * Navigates to the previous view in sequence, optionally executing a callback first
+   * @param {Function} [fn] - Optional callback to execute before navigation
+   */
+  const goPrevView = (fn) => {
+    if (fn) fn()
+    _doNavigate(prevView())
+  }
+
+  return { goNextView, goPrevView, goToView, lookupNext, nextView, prevView }
+}