astro-tractstack 2.0.0-rc.0

package/templates/src/constants.ts

@@ -0,0 +1,274 @@
+import type { GotoTargets } from './types/tractstack';
+import type { WidgetMeta } from './types/compositorTypes';
+import type { ToolAddMode } from './types/compositorTypes';
+
+export const IMPRESSIONS_DELAY = 5000;
+export const THRESHOLD_GLOSSED = 7000; // 7 seconds in ms
+export const THRESHOLD_READ = 42000; // 42 seconds in ms
+export const MAX_ANALYTICS_HOURS = 672;
+
+export const reservedSlugs = [
+  `api`,
+  `collections`,
+  `create`,
+  `edit`,
+  `concierge`,
+  `context`,
+  `products`,
+  `storykeep`,
+  `cart`,
+  `404`,
+  `transcribe`,
+  `sitemap`,
+  `robots`,
+  `llm`,
+];
+
+export const colors = [
+  '#61AFEF',
+  '#98C379',
+  '#C678DD',
+  '#E06C75',
+  '#56B6C2',
+  '#D19A66',
+  '#BE5046',
+  '#98C379',
+  '#E5C07B',
+  '#528BFF',
+  '#FF6B6B',
+  '#4EC9B0',
+];
+
+export const collections = ['kCz'];
+
+export const GOTO_TARGETS: GotoTargets = {
+  storykeep: {
+    name: 'StoryKeep',
+    subcommands: ['dashboard', 'settings', 'login', 'logout'],
+    description: 'Navigate to StoryKeep sections',
+  },
+  home: {
+    name: 'Home Page',
+    description: 'Navigate to the home page',
+  },
+  concierge: {
+    name: 'Concierge',
+    subcommands: ['profile'],
+    description: 'Navigate to concierge sections',
+  },
+  context: {
+    name: 'Context',
+    requiresParam: true,
+    paramLabel: 'Context Slug',
+    description: 'Navigate to a context page',
+  },
+  storyFragment: {
+    name: 'Story Fragment',
+    requiresParam: true,
+    paramLabel: 'StoryFragment Slug',
+    description: 'Navigate to a story fragment',
+  },
+  storyFragmentPane: {
+    name: 'Story Fragment Pane',
+    requiresParam: true,
+    requiresSecondParam: true,
+    paramLabel: 'StoryFragment Slug',
+    param2Label: 'Pane Slug',
+    description: 'Navigate to specific pane in a story fragment',
+  },
+  bunny: {
+    name: 'Goto Bunny Video',
+    requiresParam: true,
+    requiresSecondParam: true,
+    requiresThirdParam: true,
+    paramLabel: 'StoryFragment Slug',
+    param2Label: 'Time (seconds)',
+    param3Label: 'Video ID',
+    description: 'Play a Bunny video at specified time',
+  },
+  url: {
+    name: 'External URL',
+    requiresParam: true,
+    paramLabel: 'URL',
+    description: 'Navigate to external URL',
+    placeholder: 'https://...',
+  },
+};
+
+export const isTemplateToolAddModes = [
+  'p',
+  'h2',
+  'h3',
+  'h4',
+  'img',
+  'bunny',
+  'yt',
+] as const;
+
+export const toolAddModes = [
+  'p',
+  'h2',
+  'h3',
+  'h4',
+  'img',
+  'signup',
+  'yt',
+  'bunny',
+  'belief',
+  'identify',
+  'toggle',
+  //"aside",
+] as const;
+
+export const toolAddModeTitles: Record<ToolAddMode, string> = {
+  p: 'Paragraph',
+  h2: 'Heading 2',
+  h3: 'Heading 3',
+  h4: 'Heading 4',
+  img: 'Image',
+  signup: 'Email Sign-up Widget',
+  yt: 'YouTube Video',
+  bunny: 'Bunny Video',
+  belief: 'Belief Select',
+  identify: 'Identity As',
+  toggle: 'Toggle Belief',
+  //aside: "Aside Text",
+};
+
+export const toolAddModeInsertDefault: Record<ToolAddMode, string> = {
+  p: '...',
+  h2: '## title',
+  h3: '### subtitle',
+  h4: '#### section title',
+  img: '![Descriptive title](filename)', // on initial insert must wrap in ul
+  signup: '* `signup(Major Updates Only|Keep in touch!|false)`',
+  yt: '* `youtube(tag|title)`',
+  bunny: '* `bunny(id|title)`',
+  belief: '* `belief(BeliefTag|likert|prompt)`',
+  identify: '* `identifyAs(BeliefTag|TARGET_VALUE|prompt)`',
+  toggle: '* `toggle(BeliefTag|prompt)`',
+  //aside: "...", // on initial insert must wrap in ol
+};
+
+export const toolAddModesIcons: Record<ToolAddMode, string> = {
+  p: 'text.svg',
+  h2: 'h2.svg',
+  h3: 'h3.svg',
+  h4: 'h4.svg',
+  img: 'image.svg',
+  yt: '',
+  bunny: '',
+  signup: '',
+  identify: '',
+  toggle: '',
+  belief: '',
+  //aside: "",
+};
+
+export const widgetMeta: WidgetMeta = {
+  belief: {
+    title: `Belief Widget`,
+    parameters: [
+      {
+        label: 'Belief Tag',
+        defaultValue: 'BELIEF',
+        type: 'string',
+        isBeliefTag: true,
+      },
+      { label: 'Scale', defaultValue: 'yn', type: 'scale' },
+      { label: 'Question Prompt', defaultValue: 'Prompt', type: 'string' },
+    ],
+    isBelief: true,
+  },
+  identifyAs: {
+    title: `Identify As Widget`,
+    parameters: [
+      {
+        label: 'Belief Tag',
+        defaultValue: 'BELIEF',
+        type: 'string',
+        isBeliefTag: true,
+      },
+      {
+        label: 'Belief Matching Value(s)',
+        defaultValue: '*',
+        type: 'multi-string',
+      },
+      { label: 'Question Prompt', defaultValue: 'Prompt', type: 'string' },
+    ],
+    isBelief: true,
+  },
+  toggle: {
+    title: `Toggle Belief Widget`,
+    parameters: [
+      {
+        label: 'Belief Tag',
+        defaultValue: 'BELIEF',
+        type: 'string',
+        isBeliefTag: true,
+      },
+      { label: 'Question Prompt', defaultValue: 'Prompt', type: 'string' },
+    ],
+    isBelief: true,
+  },
+  youtube: {
+    title: `YouTube Video Embed`,
+    parameters: [
+      { label: 'Embed Code', defaultValue: '*', type: 'string' },
+      { label: 'Title', defaultValue: 'Descriptive Title', type: 'string' },
+    ],
+  },
+  bunny: {
+    title: `BunnyCDN Video Embed`,
+    parameters: [
+      { label: 'Embed URL', defaultValue: '*', type: 'string' },
+      { label: 'Title', defaultValue: 'Descriptive Title', type: 'string' },
+    ],
+  },
+  resource: {
+    title: `Not yet implemented`,
+    parameters: [
+      { label: 'Type', defaultValue: '?', type: 'string' },
+      { label: 'Variation', defaultValue: '?', type: 'string' },
+    ],
+  },
+  signup: {
+    title: `Email Sign Up Widget`,
+    parameters: [
+      {
+        label: 'Contact Persona',
+        defaultValue: 'Major Updates Only',
+        type: 'string',
+      },
+      { label: 'Prompt Text', defaultValue: 'Keep in touch!', type: 'string' },
+      { label: 'Clarify Consent', defaultValue: 'false', type: 'boolean' },
+    ],
+  },
+};
+
+export const contactPersona = [
+  {
+    id: 'major',
+    title: 'Major Updates Only',
+    description: 'Will only send major updates and do so infrequently.',
+    disabled: false,
+  },
+  {
+    id: 'all',
+    title: 'All Updates',
+    description: 'Be fully in the know!',
+    disabled: false,
+  },
+  {
+    id: 'open',
+    title: 'DMs open',
+    description: "Leave your contact details and we'll get in touch!",
+    disabled: false,
+  },
+  {
+    id: 'none',
+    title: 'None',
+    description: 'Disables all communications from us.',
+    disabled: false,
+  },
+];

package/templates/src/hooks/useFormState.ts

@@ -0,0 +1,203 @@
+import { useState, useCallback, useMemo, useEffect, useRef } from 'react';
+
+// Form validation error types
+export interface FieldErrors {
+  [fieldName: string]: string | undefined;
+}
+
+// Save operation states
+export type SaveState = 'idle' | 'saving' | 'success' | 'error';
+
+// Unsaved changes options
+export interface UnsavedChangesOptions {
+  /**
+   * Message to show in browser dialog when user tries to leave
+   */
+  browserWarningMessage?: string;
+
+  /**
+   * Whether to show browser warning dialog on page unload
+   */
+  enableBrowserWarning?: boolean;
+}
+
+// Generic form state configuration
+export interface FormStateConfig<T> {
+  initialData: T;
+  validator?: (state: T) => FieldErrors;
+  interceptor?: (newState: T, field: keyof T, value: any) => T;
+  onSave: (data: T) => Promise<T | void> | T | void; // Now supports returning updated state or void
+  unsavedChanges?: UnsavedChangesOptions;
+}
+
+// Return type for the useFormState hook
+export interface FormStateReturn<T> {
+  state: T;
+  originalState: T;
+  updateField: (field: keyof T, value: any) => void;
+  save: () => Promise<void>;
+  cancel: () => void;
+  resetToState: (newState: T) => void; // NEW: Reset form to new baseline state
+  isDirty: boolean;
+  isValid: boolean;
+  errors: FieldErrors;
+  saveState: SaveState; // NEW: Track save operation state
+  errorMessage: string | null; // NEW: Save error message
+}
+
+/**
+ * useFormState - Enhanced form state management with proper save state synchronization
+ *
+ * Provides complete save/cancel/validation workflow with interceptor support
+ * and the ability to reset to a new baseline state after successful saves.
+ *
+ * @param config - Form configuration object
+ * @returns Form state management object
+ */
+export function useFormState<T>(
+  config: FormStateConfig<T>
+): FormStateReturn<T> {
+  const { initialData, validator, interceptor, onSave, unsavedChanges } =
+    config;
+
+  // Core state management
+  const [state, setState] = useState<T>(initialData);
+  const [originalState, setOriginalState] = useState<T>(initialData);
+
+  // Save operation state tracking
+  const [saveState, setSaveState] = useState<SaveState>('idle');
+  const [errorMessage, setErrorMessage] = useState<string | null>(null);
+
+  // Ref to track if we're currently saving to prevent double-saves
+  const isSaving = useRef(false);
+
+  // Validation errors
+  const errors = useMemo(() => {
+    return validator ? validator(state) : {};
+  }, [state, validator]);
+
+  // Computed properties
+  const isDirty = useMemo(() => {
+    return JSON.stringify(state) !== JSON.stringify(originalState);
+  }, [state, originalState]);
+
+  const isValid = useMemo(() => {
+    return Object.keys(errors).length === 0;
+  }, [errors]);
+
+  // Browser warning for unsaved changes
+  useEffect(() => {
+    if (!unsavedChanges?.enableBrowserWarning) return;
+
+    const handleBeforeUnload = (event: BeforeUnloadEvent) => {
+      if (isDirty && saveState !== 'saving') {
+        const message =
+          unsavedChanges.browserWarningMessage ||
+          'You have unsaved changes. Are you sure you want to leave?';
+        event.preventDefault();
+        return message;
+      }
+    };
+
+    if (isDirty && saveState !== 'saving') {
+      window.addEventListener('beforeunload', handleBeforeUnload);
+    }
+
+    return () => {
+      window.removeEventListener('beforeunload', handleBeforeUnload);
+    };
+  }, [isDirty, saveState, unsavedChanges]);
+
+  // Update field with optional interceptor
+  const updateField = useCallback(
+    (field: keyof T, value: any) => {
+      // Clear any previous save state when user makes changes
+      if (saveState !== 'idle') {
+        setSaveState('idle');
+        setErrorMessage(null);
+      }
+
+      setState((currentState) => {
+        const newState = {
+          ...currentState,
+          [field]: value,
+        };
+
+        // Apply interceptor if provided
+        if (interceptor) {
+          return interceptor(newState, field, value);
+        }
+
+        return newState;
+      });
+    },
+    [interceptor, saveState]
+  );
+
+  // Enhanced save function with state management
+  const save = useCallback(async () => {
+    // Prevent double-saves
+    if (!isValid || isSaving.current || saveState === 'saving') {
+      return;
+    }
+
+    isSaving.current = true;
+    setSaveState('saving');
+    setErrorMessage(null);
+
+    try {
+      // Call the save function
+      const result = await onSave(state);
+
+      // If onSave returns updated state, use it; otherwise use current state
+      const updatedState = result && result !== undefined ? result : state;
+
+      // Set success state briefly
+      setSaveState('success');
+
+      // Reset to idle after success feedback period
+      setTimeout(() => {
+        // Reset form to the new baseline state
+        setOriginalState(updatedState);
+        setState(updatedState);
+        setSaveState('idle');
+      }, 2000);
+    } catch (error) {
+      setSaveState('error');
+      const message = error instanceof Error ? error.message : 'Save failed';
+      setErrorMessage(message);
+      console.error('Save failed:', error);
+    } finally {
+      isSaving.current = false;
+    }
+  }, [state, isValid, onSave, saveState]);
+
+  // Cancel function - revert to original state
+  const cancel = useCallback(() => {
+    setState(originalState);
+    setSaveState('idle');
+    setErrorMessage(null);
+  }, [originalState]);
+
+  // NEW: Reset to new state (for external state updates)
+  const resetToState = useCallback((newState: T) => {
+    setOriginalState(newState);
+    setState(newState);
+    setSaveState('idle');
+    setErrorMessage(null);
+  }, []);
+
+  return {
+    state,
+    originalState,
+    updateField,
+    save,
+    cancel,
+    resetToState,
+    isDirty,
+    isValid,
+    errors,
+    saveState,
+    errorMessage,
+  };
+}