@allternit/gizzi-code 1.0.0

package/src/utils/fullscreen.ts

@@ -0,0 +1,382 @@
+/**
+ * @fileoverview Fullscreen utilities for gizzi-code integration
+ * @module utils/fullscreen
+ *
+ * Provides utilities for managing fullscreen mode in browser environments.
+ * Includes support for the standard Fullscreen API with vendor prefixes
+ * for cross-browser compatibility.
+ */
+
+/**
+ * Fullscreen change event handler type
+ * @typedef {Function} FullscreenChangeHandler
+ */
+export type FullscreenChangeHandler = (isFullscreen: boolean) => void;
+
+/**
+ * Extended document interface with vendor-prefixed fullscreen properties
+ * @interface FullscreenDocument
+ */
+interface FullscreenDocument extends Document {
+  readonly webkitFullscreenElement?: Element | null;
+  readonly mozFullScreenElement?: Element | null;
+  readonly msFullscreenElement?: Element | null;
+  readonly webkitIsFullScreen?: boolean;
+  readonly mozFullScreen?: boolean;
+  readonly msIsFullScreen?: boolean;
+  webkitExitFullscreen?: () => Promise<void>;
+  mozCancelFullScreen?: () => Promise<void>;
+  msExitFullscreen?: () => Promise<void>;
+}
+
+/**
+ * Extended HTML element interface with vendor-prefixed fullscreen methods
+ * @interface FullscreenElement
+ */
+interface FullscreenElement extends HTMLElement {
+  webkitRequestFullscreen?: (options?: FullscreenOptions) => Promise<void>;
+  mozRequestFullScreen?: (options?: FullscreenOptions) => Promise<void>;
+  msRequestFullscreen?: () => Promise<void>;
+}
+
+/**
+ * Checks if the Fullscreen API is supported in the current environment
+ *
+ * @returns {boolean} True if fullscreen is supported
+ * @example
+ * ```typescript
+ * if (isFullscreenSupported()) {
+ *   enterFullscreen();
+ * }
+ * ```
+ */
+export function isFullscreenSupported(): boolean {
+  if (typeof document === 'undefined') {
+    return false;
+  }
+
+  const doc = document as FullscreenDocument;
+  const elem = document.documentElement as FullscreenElement;
+
+  return !!(
+    doc.fullscreenEnabled ??
+    (doc as unknown as { webkitFullscreenEnabled?: boolean }).webkitFullscreenEnabled ??
+    (doc as unknown as { mozFullScreenEnabled?: boolean }).mozFullScreenEnabled ??
+    (doc as unknown as { msFullscreenEnabled?: boolean }).msFullscreenEnabled ??
+    elem.requestFullscreen ??
+    elem.webkitRequestFullscreen ??
+    elem.mozRequestFullScreen ??
+    elem.msRequestFullscreen
+  );
+}
+
+/**
+ * Checks if the document is currently in fullscreen mode
+ *
+ * @returns {boolean} True if currently in fullscreen
+ * @example
+ * ```typescript
+ * if (isFullscreen()) {
+ *   console.log('Currently in fullscreen mode');
+ * }
+ * ```
+ */
+export function isFullscreen(): boolean {
+  if (typeof document === 'undefined') {
+    return false;
+  }
+
+  const doc = document as FullscreenDocument;
+
+  return !!(
+    doc.fullscreenElement ??
+    doc.webkitFullscreenElement ??
+    doc.mozFullScreenElement ??
+    doc.msFullscreenElement ??
+    doc.webkitIsFullScreen ??
+    doc.mozFullScreen ??
+    doc.msIsFullScreen
+  );
+}
+
+/**
+ * Enters fullscreen mode for the specified element or document
+ *
+ * @param {HTMLElement} [element] - Element to make fullscreen (defaults to document.documentElement)
+ * @param {FullscreenOptions} [options] - Fullscreen options
+ * @returns {Promise<void>} Promise that resolves when fullscreen is entered
+ * @throws {Error} If fullscreen is not supported or permission is denied
+ * @example
+ * ```typescript
+ * // Make entire page fullscreen
+ * await enterFullscreen();
+ *
+ * // Make specific element fullscreen
+ * const video = document.getElementById('myVideo');
+ * await enterFullscreen(video);
+ *
+ * // With navigation UI hidden
+ * await enterFullscreen(undefined, { navigationUI: 'hide' });
+ * ```
+ */
+export async function enterFullscreen(
+  element?: HTMLElement,
+  options?: FullscreenOptions
+): Promise<void> {
+  if (typeof document === 'undefined') {
+    return Promise.reject(new Error('Fullscreen not available in server environment'));
+  }
+
+  const target = (element ?? document.documentElement) as FullscreenElement;
+
+  // Try standard method first
+  if (target.requestFullscreen) {
+    return target.requestFullscreen(options);
+  }
+
+  // Vendor prefixed fallbacks
+  if (target.webkitRequestFullscreen) {
+    return target.webkitRequestFullscreen(options);
+  }
+
+  if (target.mozRequestFullScreen) {
+    return target.mozRequestFullScreen(options);
+  }
+
+  if (target.msRequestFullscreen) {
+    return target.msRequestFullscreen();
+  }
+
+  throw new Error('Fullscreen API is not supported in this browser');
+}
+
+/**
+ * Exits fullscreen mode
+ *
+ * @returns {Promise<void>} Promise that resolves when fullscreen is exited
+ * @throws {Error} If not in fullscreen or API not supported
+ * @example
+ * ```typescript
+ * await exitFullscreen();
+ * console.log('Exited fullscreen');
+ * ```
+ */
+export async function exitFullscreen(): Promise<void> {
+  if (typeof document === 'undefined') {
+    return Promise.reject(new Error('Fullscreen not available in server environment'));
+  }
+
+  if (!isFullscreen()) {
+    return Promise.resolve();
+  }
+
+  const doc = document as FullscreenDocument;
+
+  // Try standard method first
+  if (document.exitFullscreen) {
+    return document.exitFullscreen();
+  }
+
+  // Vendor prefixed fallbacks
+  if (doc.webkitExitFullscreen) {
+    return doc.webkitExitFullscreen();
+  }
+
+  if (doc.mozCancelFullScreen) {
+    return doc.mozCancelFullScreen();
+  }
+
+  if (doc.msExitFullscreen) {
+    return doc.msExitFullscreen();
+  }
+
+  throw new Error('Fullscreen API is not supported in this browser');
+}
+
+/**
+ * Toggles fullscreen mode for the specified element
+ *
+ * @param {HTMLElement} [element] - Element to toggle (defaults to document.documentElement)
+ * @param {FullscreenOptions} [options] - Fullscreen options
+ * @returns {Promise<boolean>} Promise that resolves to new fullscreen state
+ * @example
+ * ```typescript
+ * const isFullscreen = await toggleFullscreen();
+ * console.log('Fullscreen active:', isFullscreen);
+ * ```
+ */
+export async function toggleFullscreen(
+  element?: HTMLElement,
+  options?: FullscreenOptions
+): Promise<boolean> {
+  if (isFullscreen()) {
+    await exitFullscreen();
+    return false;
+  } else {
+    await enterFullscreen(element, options);
+    return true;
+  }
+}
+
+/**
+ * Subscribes to fullscreen change events
+ *
+ * @param {FullscreenChangeHandler} handler - Callback fired when fullscreen state changes
+ * @returns {() => void} Unsubscribe function
+ * @example
+ * ```typescript
+ * const unsubscribe = onFullscreenChange((isFullscreen) => {
+ *   console.log('Fullscreen changed:', isFullscreen);
+ * });
+ *
+ * // Later: unsubscribe();
+ * ```
+ */
+export function onFullscreenChange(
+  handler: FullscreenChangeHandler
+): () => void {
+  if (typeof document === 'undefined') {
+    return () => {
+      // No-op in server environment
+    };
+  }
+
+  const handleChange = (): void => {
+    handler(isFullscreen());
+  };
+
+  // Standard event
+  document.addEventListener('fullscreenchange', handleChange);
+  // Vendor prefixed events
+  document.addEventListener('webkitfullscreenchange', handleChange);
+  document.addEventListener('mozfullscreenchange', handleChange);
+  document.addEventListener('MSFullscreenChange', handleChange);
+
+  // Return unsubscribe function
+  return () => {
+    document.removeEventListener('fullscreenchange', handleChange);
+    document.removeEventListener('webkitfullscreenchange', handleChange);
+    document.removeEventListener('mozfullscreenchange', handleChange);
+    document.removeEventListener('MSFullscreenChange', handleChange);
+  };
+}
+
+/**
+ * Gets the current fullscreen element
+ *
+ * @returns {Element | null} The element currently in fullscreen, or null
+ * @example
+ * ```typescript
+ * const element = getFullscreenElement();
+ * if (element) {
+ *   console.log('Fullscreen element:', element.tagName);
+ * }
+ * ```
+ */
+export function getFullscreenElement(): Element | null {
+  if (typeof document === 'undefined') {
+    return null;
+  }
+
+  const doc = document as FullscreenDocument;
+
+  return (
+    doc.fullscreenElement ??
+    doc.webkitFullscreenElement ??
+    doc.mozFullScreenElement ??
+    doc.msFullscreenElement ??
+    null
+  );
+}
+
+/**
+ * Locks screen orientation when in fullscreen (mobile devices)
+ *
+ * @param {OrientationLockType} orientation - Orientation to lock to
+ * @returns {Promise<void>} Promise that resolves when orientation is locked
+ * @example
+ * ```typescript
+ * await lockOrientation('landscape');
+ * await enterFullscreen();
+ * ```
+ */
+/**
+ * Valid orientation lock types
+ * @typedef {string} OrientationLockType
+ */
+type OrientationLockType = 'any' | 'natural' | 'landscape' | 'portrait' | 'portrait-primary' | 'portrait-secondary' | 'landscape-primary' | 'landscape-secondary';
+
+/**
+ * Locks screen orientation when in fullscreen (mobile devices)
+ *
+ * @param {OrientationLockType} orientation - Orientation to lock to
+ * @returns {Promise<void>} Promise that resolves when orientation is locked
+ * @example
+ * ```typescript
+ * await lockOrientation('landscape');
+ * await enterFullscreen();
+ * ```
+ */
+export async function lockOrientation(
+  orientation: OrientationLockType
+): Promise<void> {
+  if (typeof screen === 'undefined' || !screen.orientation) {
+    return Promise.reject(new Error('Screen Orientation API not supported'));
+  }
+
+  // Type assertion for lock method which may not be in all TypeScript lib versions
+  const orientationApi = screen.orientation as {
+    lock?(orientation: OrientationLockType): Promise<void>;
+    unlock?(): void;
+  };
+
+  if (!orientationApi.lock) {
+    return Promise.reject(new Error('Screen orientation lock not supported'));
+  }
+
+  try {
+    await orientationApi.lock(orientation);
+  } catch (error) {
+    return Promise.reject(error);
+  }
+}
+
+/**
+ * Unlocks screen orientation
+ *
+ * @returns {Promise<void>} Promise that resolves when orientation is unlocked
+ * @example
+ * ```typescript
+ * await unlockOrientation();
+ * ```
+ */
+export async function unlockOrientation(): Promise<void> {
+  if (typeof screen === 'undefined' || !screen.orientation) {
+    return Promise.resolve();
+  }
+
+  // Type assertion for unlock method which may not be in all TypeScript lib versions
+  const orientationApi = screen.orientation as {
+    lock?(orientation: OrientationLockType): Promise<void>;
+    unlock?(): void;
+  };
+
+  try {
+    orientationApi.unlock?.();
+  } catch {
+    // Ignore unlock errors
+  }
+}
+
+// Default export
+export default {
+  isFullscreenSupported,
+  isFullscreen,
+  enterFullscreen,
+  exitFullscreen,
+  toggleFullscreen,
+  onFullscreenChange,
+  getFullscreenElement,
+  lockOrientation,
+  unlockOrientation,
+};

package/src/utils/sessionStorage.d.ts

@@ -0,0 +1,210 @@
+/**
+ * @fileoverview Session storage utilities for gizzi-code integration
+ * @module utils/sessionStorage
+ *
+ * Provides session persistence, storage management, and user type detection
+ * with safe fallbacks for environments without storage access.
+ */
+import type { UserSession } from '../state/AppStateStore';
+import type { TypedMessage } from '../types/message';
+/**
+ * Storage keys used throughout the application
+ * @constant {Record<string, string>}
+ */
+export declare const STORAGE_KEYS: {
+    readonly SESSION: "gizzi_session";
+    readonly USER_TYPE: "gizzi_user_type";
+    readonly MESSAGES: "gizzi_messages";
+    readonly PREFERENCES: "gizzi_preferences";
+    readonly LAST_ACTIVITY: "gizzi_last_activity";
+    readonly SESSION_METADATA: "gizzi_session_metadata";
+};
+/**
+ * User type categories
+ * @typedef {'anonymous' | 'free' | 'pro' | 'enterprise' | 'admin'} UserType
+ */
+export type UserType = 'anonymous' | 'free' | 'pro' | 'enterprise' | 'admin';
+/**
+ * Valid user types for runtime validation
+ * @constant {readonly UserType[]}
+ */
+export declare const VALID_USER_TYPES: readonly UserType[];
+/**
+ * Session metadata stored alongside the session
+ * @interface SessionMetadata
+ */
+export interface SessionMetadata {
+    /** When the session was created */
+    readonly createdAt: string;
+    /** Last activity timestamp (ISO string) */
+    readonly lastActivity: string;
+    /** Number of messages in this session */
+    readonly messageCount: number;
+    /** Session version for migration purposes */
+    readonly version: number;
+    /** Device/browser information */
+    readonly deviceInfo?: {
+        readonly userAgent: string;
+        readonly platform: string;
+        readonly language: string;
+    };
+}
+/**
+ * Complete session data structure
+ * @interface SessionData
+ */
+export interface SessionData {
+    /** User session information */
+    readonly session: UserSession;
+    /** Session metadata */
+    readonly metadata: SessionMetadata;
+    /** Persisted messages */
+    readonly messages: readonly TypedMessage[];
+    /** User preferences */
+    readonly preferences: Readonly<Record<string, unknown>>;
+}
+/**
+ * Storage operation result
+ * @interface StorageResult
+ */
+export interface StorageResult<T> {
+    /** Whether the operation succeeded */
+    readonly success: boolean;
+    /** The data if successful, null otherwise */
+    readonly data: T | null;
+    /** Error message if failed */
+    readonly error: string | null;
+}
+/**
+ * Saves the current session to storage
+ *
+ * @param {UserSession} session - The session to save
+ * @param {Object} [options] - Save options
+ * @param {TypedMessage[]} [options.messages] - Messages to persist
+ * @param {Record<string, unknown>} [options.preferences] - Preferences to persist
+ * @returns {StorageResult<void>} Result of the save operation
+ * @example
+ * ```typescript
+ * const result = saveSession(session, { messages, preferences });
+ * if (!result.success) {
+ *   console.error('Failed to save session:', result.error);
+ * }
+ * ```
+ */
+export declare function saveSession(session: UserSession, options?: {
+    messages?: TypedMessage[];
+    preferences?: Record<string, unknown>;
+}): StorageResult<void>;
+/**
+ * Loads the session from storage
+ *
+ * @returns {StorageResult<SessionData>} The loaded session data or error
+ * @example
+ * ```typescript
+ * const result = loadSession();
+ * if (result.success && result.data) {
+ *   const { session, messages } = result.data;
+ *   // Restore session...
+ * }
+ * ```
+ */
+export declare function loadSession(): StorageResult<SessionData>;
+/**
+ * Clears all session data from storage
+ *
+ * @returns {boolean} True if successful
+ * @example
+ * ```typescript
+ * clearSession(); // Logs out the user
+ * ```
+ */
+export declare function clearSession(): boolean;
+/**
+ * Gets the user type from storage
+ * Returns 'anonymous' if no user type is stored or on error
+ *
+ * @returns {UserType} The stored user type or 'anonymous'
+ * @example
+ * ```typescript
+ * const userType = getUserType();
+ * if (userType === 'pro') {
+ *   // Show pro features
+ * }
+ * ```
+ */
+export declare function getUserType(): UserType;
+/**
+ * Saves messages to session storage
+ *
+ * @param {TypedMessage[]} messages - Messages to save
+ * @returns {StorageResult<void>} Result of the operation
+ */
+export declare function saveMessages(messages: TypedMessage[]): StorageResult<void>;
+/**
+ * Loads messages from session storage
+ *
+ * @returns {StorageResult<TypedMessage[]>} The loaded messages or error
+ */
+export declare function loadMessages(): StorageResult<TypedMessage[]>;
+/**
+ * Saves user preferences to storage
+ *
+ * @param {Record<string, unknown>} preferences - Preferences to save
+ * @returns {StorageResult<void>} Result of the operation
+ */
+export declare function savePreferences(preferences: Record<string, unknown>): StorageResult<void>;
+/**
+ * Loads user preferences from storage
+ *
+ * @returns {StorageResult<Record<string, unknown>>} The loaded preferences or error
+ */
+export declare function loadPreferences(): StorageResult<Record<string, unknown>>;
+/**
+ * Gets the timestamp of the last user activity
+ *
+ * @returns {Date | null} The last activity date or null if not found
+ */
+export declare function getLastActivity(): Date | null;
+/**
+ * Updates the last activity timestamp to now
+ *
+ * @returns {boolean} True if successful
+ */
+export declare function updateLastActivity(): boolean;
+/**
+ * Checks if there is an active session in storage
+ *
+ * @returns {boolean} True if a valid session exists
+ */
+export declare function hasActiveSession(): boolean;
+/**
+ * Type guard to check if a value is a valid UserType
+ *
+ * @param {unknown} value - The value to check
+ * @returns {boolean} True if the value is a valid UserType
+ */
+export declare function isUserType(value: unknown): value is UserType;
+declare const _default: {
+    STORAGE_KEYS: {
+        readonly SESSION: "gizzi_session";
+        readonly USER_TYPE: "gizzi_user_type";
+        readonly MESSAGES: "gizzi_messages";
+        readonly PREFERENCES: "gizzi_preferences";
+        readonly LAST_ACTIVITY: "gizzi_last_activity";
+        readonly SESSION_METADATA: "gizzi_session_metadata";
+    };
+    VALID_USER_TYPES: readonly UserType[];
+    saveSession: typeof saveSession;
+    loadSession: typeof loadSession;
+    clearSession: typeof clearSession;
+    getUserType: typeof getUserType;
+    saveMessages: typeof saveMessages;
+    loadMessages: typeof loadMessages;
+    savePreferences: typeof savePreferences;
+    loadPreferences: typeof loadPreferences;
+    getLastActivity: typeof getLastActivity;
+    updateLastActivity: typeof updateLastActivity;
+    hasActiveSession: typeof hasActiveSession;
+    isUserType: typeof isUserType;
+};
+export default _default;