@stevederico/skateboard-ui 1.4.1 → 1.5.0

package/App.jsx

@@ -22,6 +22,7 @@ import ErrorBoundary from './ErrorBoundary.jsx';
 import { useAppSetup, initializeUtilities, validateConstants } from './Utilities.js';
 import { ContextProvider } from './Context.jsx';
 import Toast from './Toast.jsx';
+import AuthOverlay from './AuthOverlay.jsx';
 
 function App({ constants, appRoutes, defaultRoute, landingPage }) {
   const location = useLocation();
@@ -59,12 +60,26 @@ function App({ constants, appRoutes, defaultRoute, landingPage }) {
 }
 
 /**
+ * Bootstrap and render a skateboard-ui application.
+ *
+ * Sets up routing, authentication, layout, theming, and toast notifications.
+ * Mounts the app to the #root DOM element.
+ *
  * @param {Object} config
- * @param {Object} config.constants - App constants from constants.json
- * @param {Array} config.appRoutes - Array of route objects with path and element
- * @param {string} [config.defaultRoute] - Default route path under /app
- * @param {JSX.Element} [config.landingPage] - Custom landing page element for the "/" route. Defaults to built-in LandingView.
+ * @param {Object} config.constants - App constants (see README for required fields)
+ * @param {Array<{path: string, element: JSX.Element}>} config.appRoutes - Routes rendered under /app
+ * @param {string} [config.defaultRoute] - Default route path under /app (defaults to first route)
+ * @param {JSX.Element} [config.landingPage] - Custom landing page for "/". Defaults to LandingView.
  * @param {React.ComponentType} [config.wrapper] - Optional wrapper component around the router
+ *
+ * @example
+ * import { createSkateboardApp } from '@stevederico/skateboard-ui/App';
+ * import constants from './constants.json';
+ *
+ * createSkateboardApp({
+ *   constants,
+ *   appRoutes: [{ path: 'home', element: <HomeView /> }]
+ * });
  */
 export function createSkateboardApp({ constants, appRoutes, defaultRoute = appRoutes[0]?.path || 'home', landingPage, wrapper: Wrapper }) {
   // Validate constants before initialization
@@ -81,6 +96,7 @@ export function createSkateboardApp({ constants, appRoutes, defaultRoute = appRo
       <ThemeProvider attribute="class" defaultTheme="system" enableSystem>
         <Toast />
         <ContextProvider constants={constants}>
+          <AuthOverlay />
           {Wrapper ? (
             <Wrapper>
               <Router>

package/AppSidebar.jsx

@@ -18,6 +18,19 @@ import {
 // Use this if your DynamicIcon import isn't working
 const DynamicIconComponent = DynamicIcon
 
+/**
+ * Desktop navigation sidebar.
+ *
+ * Renders app pages from constants.pages with icons, tooltips when collapsed,
+ * and a settings link in the footer. Uses shadcn Sidebar primitives.
+ *
+ * @returns {JSX.Element} Sidebar navigation
+ *
+ * @example
+ * import AppSidebar from '@stevederico/skateboard-ui/AppSidebar';
+ *
+ * <AppSidebar />
+ */
 export default function AppSidebar() {
   const { open, setOpen } = useSidebar();
   const navigate = useNavigate();

package/AuthOverlay.jsx

@@ -0,0 +1,291 @@
+import React, { useState, useEffect, useRef } from 'react';
+import { Dialog, DialogContent } from './shadcn/ui/dialog.jsx';
+import { Input } from './shadcn/ui/input.jsx';
+import DynamicIcon from './DynamicIcon.jsx';
+import { getState } from './Context.jsx';
+import { getBackendURL } from './Utilities.js';
+
+/**
+ * Modal authentication overlay with sign-in and sign-up forms.
+ *
+ * Rendered at the app root and controlled via context state.
+ * Opens when SHOW_AUTH_OVERLAY is dispatched (typically via useAuthGate).
+ * On successful auth, runs the pending callback and closes.
+ *
+ * @returns {JSX.Element} Auth dialog overlay
+ *
+ * @example
+ * import AuthOverlay from '@stevederico/skateboard-ui/AuthOverlay';
+ *
+ * // Rendered automatically by createSkateboardApp
+ * <AuthOverlay />
+ */
+export default function AuthOverlay() {
+  const { state, dispatch } = getState();
+  const constants = state.constants;
+  const { visible } = state.authOverlay;
+
+  const [mode, setMode] = useState('signin');
+  const [email, setEmail] = useState('');
+  const [password, setPassword] = useState('');
+  const [name, setName] = useState('');
+  const [errorMessage, setErrorMessage] = useState('');
+  const [isSubmitting, setIsSubmitting] = useState(false);
+  const firstInputRef = useRef(null);
+
+  // Reset form when dialog opens
+  useEffect(() => {
+    if (visible) {
+      setMode('signin');
+      setEmail('');
+      setPassword('');
+      setName('');
+      setErrorMessage('');
+      setIsSubmitting(false);
+    }
+  }, [visible]);
+
+  // Focus first input when dialog opens or mode changes
+  useEffect(() => {
+    if (visible && firstInputRef.current) {
+      // Small delay to let dialog animation finish
+      const t = setTimeout(() => firstInputRef.current?.focus(), 100);
+      return () => clearTimeout(t);
+    }
+  }, [visible, mode]);
+
+  function handleClose() {
+    dispatch({ type: 'HIDE_AUTH_OVERLAY' });
+  }
+
+  async function handleSignIn(e) {
+    e.preventDefault();
+    if (isSubmitting) return;
+    setIsSubmitting(true);
+    try {
+      const response = await fetch(`${getBackendURL()}/signin`, {
+        method: 'POST',
+        credentials: 'include',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ email, password })
+      });
+
+      if (response.ok) {
+        const data = await response.json();
+        dispatch({ type: 'SET_USER', payload: data });
+        dispatch({ type: 'AUTH_OVERLAY_SUCCESS' });
+      } else {
+        setErrorMessage('Invalid Credentials');
+      }
+    } catch (error) {
+      setErrorMessage('Server Error');
+    } finally {
+      setIsSubmitting(false);
+    }
+  }
+
+  async function handleSignUp(e) {
+    e.preventDefault();
+    if (isSubmitting) return;
+    if (password.length < 6) {
+      setErrorMessage('Password must be at least 6 characters');
+      return;
+    }
+    if (password.length > 72) {
+      setErrorMessage('Password must be 72 characters or less');
+      return;
+    }
+    setIsSubmitting(true);
+    try {
+      const response = await fetch(`${getBackendURL()}/signup`, {
+        method: 'POST',
+        credentials: 'include',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ email, password, name })
+      });
+
+      if (response.ok) {
+        const data = await response.json();
+        // Save CSRF token
+        const csrfCookie = document.cookie.split('; ').find(row => row.startsWith('csrf_token='));
+        const csrfToken = csrfCookie ? csrfCookie.split('=')[1] : data.csrfToken;
+        if (csrfToken) {
+          const appName = constants.appName || 'skateboard';
+          const csrfKey = `${appName.toLowerCase().replace(/\s+/g, '-')}_csrf`;
+          localStorage.setItem(csrfKey, csrfToken);
+        }
+        dispatch({ type: 'SET_USER', payload: data });
+        dispatch({ type: 'AUTH_OVERLAY_SUCCESS' });
+      } else {
+        setErrorMessage('Invalid Credentials');
+      }
+    } catch (error) {
+      setErrorMessage('Server Error');
+    } finally {
+      setIsSubmitting(false);
+    }
+  }
+
+  const inputClass = "py-7 px-4 placeholder:text-gray-400 rounded-lg border-2 bg-secondary dark:bg-secondary dark:border-secondary";
+  const inputStyle = { fontSize: '20px' };
+
+  const buttonGradient = `linear-gradient(to bottom right,
+    var(--color-app),
+    oklch(from var(--color-app) calc(l - 0.05) c h),
+    oklch(from var(--color-app) calc(l - 0.08) c h),
+    oklch(from var(--color-app) calc(l - 0.12) c h))`;
+
+  const buttonGradientHover = `linear-gradient(to bottom right,
+    oklch(from var(--color-app) calc(l - 0.05) c h),
+    oklch(from var(--color-app) calc(l - 0.08) c h),
+    oklch(from var(--color-app) calc(l - 0.12) c h),
+    oklch(from var(--color-app) calc(l - 0.16) c h))`;
+
+  const buttonShadow = '0 25px 50px -12px color-mix(in srgb, var(--color-app) 40%, transparent 60%)';
+
+  return (
+    <Dialog open={visible} onOpenChange={(open) => { if (!open) handleClose(); }}>
+      <DialogContent className="sm:max-w-lg p-6 overflow-auto max-h-[90vh]">
+        <div className="flex flex-col gap-6">
+          {/* App branding */}
+          <div className="flex flex-row items-center justify-center">
+            <div className="bg-app dark:bg-app dark:border dark:border-gray-700 rounded-2xl flex aspect-square size-12 items-center justify-center">
+              <DynamicIcon name={constants.appIcon} size={24} color="white" strokeWidth={2} />
+            </div>
+            <div className="font-bold ml-3 text-3xl text-gray-900 dark:text-white">{constants.appName}</div>
+          </div>
+
+          {errorMessage && (
+            <div className="bg-red-50 dark:bg-red-900/20 border border-red-200 dark:border-red-800 text-red-700 dark:text-red-400 px-4 py-3 rounded-lg text-sm text-center">
+              {errorMessage}
+            </div>
+          )}
+
+          {mode === 'signin' ? (
+            /* Sign In Form */
+            <form onSubmit={handleSignIn} className="flex flex-col gap-4">
+              <Input
+                ref={firstInputRef}
+                id="overlay-email"
+                type="email"
+                placeholder="Email"
+                className={inputClass}
+                style={inputStyle}
+                required
+                value={email}
+                onChange={(e) => { setEmail(e.target.value); setErrorMessage(''); }}
+              />
+              <Input
+                id="overlay-password"
+                type="password"
+                placeholder="Password"
+                className={inputClass}
+                style={inputStyle}
+                required
+                value={password}
+                onChange={(e) => setPassword(e.target.value)}
+              />
+              <button
+                type="submit"
+                className="relative group w-full text-white px-8 py-4 rounded-xl font-semibold text-lg transition-all duration-300 shadow-xl backdrop-blur-sm overflow-hidden cursor-pointer"
+                disabled={isSubmitting}
+                style={{ backgroundImage: buttonGradient, boxShadow: buttonShadow }}
+                onMouseEnter={(e) => { if (!isSubmitting) { e.currentTarget.style.backgroundImage = buttonGradientHover; } }}
+                onMouseLeave={(e) => { if (!isSubmitting) { e.currentTarget.style.backgroundImage = buttonGradient; } }}
+              >
+                <span className="relative z-20 flex items-center justify-center gap-2 drop-shadow-sm">
+                  <DynamicIcon name="sparkles" size={16} color="currentColor" strokeWidth={2} className="animate-pulse" />
+                  {isSubmitting ? 'Signing in...' : 'Sign In'}
+                </span>
+                <div className="absolute inset-0 bg-gradient-to-r from-transparent via-white/15 to-transparent -translate-x-full group-hover:translate-x-full transition-transform duration-800 skew-x-12"></div>
+              </button>
+              <div className="mt-2 text-center text-base">
+                <span className="text-gray-600 dark:text-gray-400 italic">Don't have an account?</span>{' '}
+                <span
+                  onClick={() => { setMode('signup'); setErrorMessage(''); }}
+                  className="cursor-pointer hover:underline text-gray-900 dark:text-white"
+                >
+                  Sign Up
+                </span>
+              </div>
+            </form>
+          ) : (
+            /* Sign Up Form */
+            <form onSubmit={handleSignUp} className="flex flex-col gap-4">
+              <Input
+                ref={firstInputRef}
+                id="overlay-name"
+                placeholder="Name"
+                className={inputClass}
+                style={inputStyle}
+                required
+                value={name}
+                onChange={(e) => { setName(e.target.value); setErrorMessage(''); }}
+              />
+              <Input
+                id="overlay-signup-email"
+                type="email"
+                placeholder="Email"
+                className={inputClass}
+                style={inputStyle}
+                required
+                value={email}
+                onChange={(e) => { setEmail(e.target.value); setErrorMessage(''); }}
+              />
+              <div className="flex flex-col gap-1">
+                <Input
+                  id="overlay-signup-password"
+                  type="password"
+                  placeholder="Password"
+                  className={inputClass}
+                  style={inputStyle}
+                  required
+                  minLength={6}
+                  maxLength={72}
+                  value={password}
+                  onChange={(e) => { setPassword(e.target.value); setErrorMessage(''); }}
+                />
+                <p className="text-xs text-gray-500 dark:text-gray-400 ml-1">Minimum 6 characters</p>
+              </div>
+              <button
+                type="submit"
+                className="relative group w-full text-white px-8 py-4 rounded-xl font-semibold text-lg transition-all duration-300 shadow-xl backdrop-blur-sm overflow-hidden cursor-pointer"
+                disabled={isSubmitting}
+                style={{ backgroundImage: buttonGradient, boxShadow: buttonShadow }}
+                onMouseEnter={(e) => { if (!isSubmitting) { e.currentTarget.style.backgroundImage = buttonGradientHover; } }}
+                onMouseLeave={(e) => { if (!isSubmitting) { e.currentTarget.style.backgroundImage = buttonGradient; } }}
+              >
+                <span className="relative z-20 flex items-center justify-center gap-2 drop-shadow-sm">
+                  <DynamicIcon name="sparkles" size={16} color="currentColor" strokeWidth={2} className="animate-pulse" />
+                  {isSubmitting ? 'Signing up...' : 'Sign Up'}
+                </span>
+                <div className="absolute inset-0 bg-gradient-to-r from-transparent via-white/15 to-transparent -translate-x-full group-hover:translate-x-full transition-transform duration-800 skew-x-12"></div>
+              </button>
+              <div className="mt-2 text-center text-base">
+                <span className="text-gray-600 dark:text-gray-400 italic">Already have an account?</span>{' '}
+                <span
+                  onClick={() => { setMode('signin'); setErrorMessage(''); }}
+                  className="cursor-pointer hover:underline text-gray-900 dark:text-white"
+                >
+                  Sign In
+                </span>
+              </div>
+              <div className="mt-2 text-center text-sm text-gray-600 dark:text-gray-400">
+                By registering you agree to our
+                <a href="/terms" target="_blank" rel="noopener noreferrer" className="ml-1 underline underline-offset-4 whitespace-nowrap text-gray-900 dark:text-white">
+                  Terms of Service
+                </a>,
+                <a href="/eula" target="_blank" rel="noopener noreferrer" className="ml-1 underline underline-offset-4 whitespace-nowrap text-gray-900 dark:text-white">
+                  EULA
+                </a>,
+                <a href="/privacy" target="_blank" rel="noopener noreferrer" className="ml-1 underline underline-offset-4 whitespace-nowrap text-gray-900 dark:text-white">
+                  Privacy Policy
+                </a>
+              </div>
+            </form>
+          )}
+        </div>
+      </DialogContent>
+    </Dialog>
+  );
+}

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # CHANGELOG
 
+1.5.0
+
+  Add AuthOverlay component
+  Add useAuthGate hook
+  Add auth overlay state
+  Add noProtectedRoutes support
+  Add JSDoc comments
+  Update README documentation
+
 1.4.1
 
   Add landingPage param

package/Context.jsx

@@ -116,6 +116,10 @@ export function ContextProvider({ children, constants }) {
       sidebarVisible: true,
       tabBarVisible: true
     },
+    authOverlay: {
+      visible: false,
+      pendingCallback: null
+    },
     constants
   };
 
@@ -148,6 +152,18 @@ export function ContextProvider({ children, constants }) {
       case 'SET_UI_VISIBILITY': {
         return { ...state, ui: { ...state.ui, ...action.payload } };
       }
+      case 'SHOW_AUTH_OVERLAY': {
+        return { ...state, authOverlay: { visible: true, pendingCallback: action.payload || null } };
+      }
+      case 'HIDE_AUTH_OVERLAY': {
+        return { ...state, authOverlay: { visible: false, pendingCallback: null } };
+      }
+      case 'AUTH_OVERLAY_SUCCESS': {
+        if (state.authOverlay.pendingCallback) {
+          try { state.authOverlay.pendingCallback(); } catch (e) { console.error('Auth callback error:', e); }
+        }
+        return { ...state, authOverlay: { visible: false, pendingCallback: null } };
+      }
       default:
         return state;
     }

package/DynamicIcon.jsx

@@ -1,7 +1,25 @@
 import React from "react";
 import * as LucideIcons from "lucide-react";
 
-// Dynamic Icon Component
+/**
+ * Render a Lucide icon by name string.
+ *
+ * Accepts kebab-case, snake_case, or PascalCase icon names and resolves
+ * them to the matching lucide-react component.
+ *
+ * @param {Object} props
+ * @param {string} props.name - Icon name (e.g. "home", "arrow-right", "Settings")
+ * @param {number} [props.size=24] - Icon size in pixels
+ * @param {string} [props.color='currentColor'] - Icon stroke color
+ * @param {number} [props.strokeWidth=2] - Stroke width
+ * @returns {JSX.Element|null} Rendered icon or null if name not found
+ *
+ * @example
+ * import DynamicIcon from '@stevederico/skateboard-ui/DynamicIcon';
+ *
+ * <DynamicIcon name="home" size={24} />
+ * <DynamicIcon name="arrow-right" size={20} color="red" />
+ */
 const DynamicIcon = ({ name, size = 24, color = 'currentColor', strokeWidth = 2, ...props }) => {
   const toPascalCase = (str) => str.split(/[-_\s]/).map(word => word.charAt(0).toUpperCase() + word.slice(1).toLowerCase()).join('');
   const possibleNames = [name, toPascalCase(name), name.charAt(0).toUpperCase() + name.slice(1)];

package/ErrorBoundary.jsx

@@ -1,5 +1,23 @@
 import React from 'react';
 
+/**
+ * Top-level error boundary that catches render errors, unhandled promise
+ * rejections, and global errors.
+ *
+ * Displays a fallback UI with "Try Again" and "Reload Page" buttons.
+ * Wrap your app root with this component.
+ *
+ * @param {Object} props
+ * @param {React.ReactNode} props.children - Child components to protect
+ * @returns {JSX.Element} Children or error fallback UI
+ *
+ * @example
+ * import ErrorBoundary from '@stevederico/skateboard-ui/ErrorBoundary';
+ *
+ * <ErrorBoundary>
+ *   <App />
+ * </ErrorBoundary>
+ */
 class ErrorBoundary extends React.Component {
   constructor(props) {
     super(props);

package/Header.jsx

@@ -1,3 +1,22 @@
+/**
+ * App header bar with title and optional action button.
+ *
+ * @param {Object} props
+ * @param {string} props.title - Header title text
+ * @param {string} [props.buttonTitle] - Action button label (omit to hide button)
+ * @param {Function} [props.onButtonTitleClick] - Button click handler
+ * @param {string} [props.buttonClass] - Additional CSS classes for the button
+ * @returns {JSX.Element} Header bar
+ *
+ * @example
+ * import Header from '@stevederico/skateboard-ui/Header';
+ *
+ * <Header
+ *   title="Dashboard"
+ *   buttonTitle="Add"
+ *   onButtonTitleClick={() => console.log('clicked')}
+ * />
+ */
 function Header(props) {
     return (
       <div className="flex w-full bg-background pb-4 pt-5 px-4 border-b ">

package/LandingView.jsx

@@ -13,6 +13,21 @@ const DynamicIcon = ({ name, size = 24, color = 'currentColor', strokeWidth = 2,
   return LucideIcon ? React.createElement(LucideIcon, { size, color, strokeWidth, ...props }) : null;
 };
 
+/**
+ * Default landing page with hero section, features grid, pricing card,
+ * CTA section, and footer.
+ *
+ * Reads app branding, tagline, features, and pricing from constants.
+ * Uses the app's --color-app CSS variable for theming.
+ *
+ * @returns {JSX.Element} Full landing page
+ *
+ * @example
+ * import LandingView from '@stevederico/skateboard-ui/LandingView';
+ *
+ * // Used automatically by createSkateboardApp, or pass as landingPage prop:
+ * createSkateboardApp({ constants, appRoutes, landingPage: <LandingView /> });
+ */
 export default function LandingView() {
   const { state } = getState();
   const constants = state.constants;

package/Layout.jsx

@@ -5,6 +5,25 @@ import AppSidebar from "./AppSidebar"
 import { useEffect } from 'react';
 import { getState } from './Context.jsx';
 
+/**
+ * Page layout wrapper with sidebar and tab bar.
+ *
+ * Renders AppSidebar (desktop) and TabBar (mobile) based on constants
+ * configuration and programmatic visibility state. Wraps child routes
+ * via react-router Outlet.
+ *
+ * @param {Object} props
+ * @param {React.ReactNode} [props.children] - Child content (unused, Outlet renders routes)
+ * @returns {JSX.Element} Layout with sidebar, main content, and tab bar
+ *
+ * @example
+ * import Layout from '@stevederico/skateboard-ui/Layout';
+ *
+ * // Used internally by createSkateboardApp route config
+ * <Route element={<Layout />}>
+ *   <Route path="home" element={<HomeView />} />
+ * </Route>
+ */
 export default function Layout({ children }) {
   const { state } = getState();
   const { sidebarVisible, tabBarVisible } = state.ui;

package/NotFound.jsx

@@ -1,3 +1,13 @@
+/**
+ * 404 page displayed for unmatched routes.
+ *
+ * @returns {JSX.Element} Not found message
+ *
+ * @example
+ * import NotFound from '@stevederico/skateboard-ui/NotFound';
+ *
+ * <Route path="*" element={<NotFound />} />
+ */
 export default function NotFound() {
 
   return (

package/PaymentView.jsx

@@ -13,6 +13,19 @@ function isAllowedRedirect(path) {
   return ALLOWED_REDIRECT_PREFIXES.some(prefix => path.startsWith(prefix));
 }
 
+/**
+ * Post-payment redirect handler.
+ *
+ * Processes Stripe checkout success/cancel/portal return query params,
+ * refreshes user data on successful payment, then redirects back to
+ * the page the user was on before checkout.
+ *
+ * @returns {JSX.Element} Redirect loading screen
+ *
+ * @example
+ * // Used internally by createSkateboardApp at /app/payment
+ * <Route path="payment" element={<PaymentView />} />
+ */
 export default function PaymentView() {
   const { state, dispatch } = getState();
   const constants = state.constants;

package/ProtectedRoute.jsx

@@ -2,17 +2,38 @@ import { useState, useEffect } from 'react';
 import { Navigate, Outlet } from 'react-router-dom';
 import { isAuthenticated, apiRequest, getAppKey, getConstants } from './Utilities';
 
+/**
+ * Route guard that validates authentication before rendering child routes.
+ *
+ * Checks client-side auth via isAuthenticated(), then validates the
+ * session with the backend via /me. Redirects to /signin if invalid.
+ * Bypassed when constants.noProtectedRoutes is true (for lazy auth).
+ * Bypassed when constants.noLogin is true (no auth required).
+ *
+ * @returns {JSX.Element} Outlet if authenticated, Navigate to /signin otherwise
+ *
+ * @example
+ * import ProtectedRoute from '@stevederico/skateboard-ui/ProtectedRoute';
+ *
+ * <Route path="/app" element={<ProtectedRoute />}>
+ *   <Route path="home" element={<HomeView />} />
+ * </Route>
+ */
 const ProtectedRoute = () => {
-    const [status, setStatus] = useState('checking'); // 'checking' | 'valid' | 'invalid'
+    const constants = getConstants();
+    const skipProtection = constants.noProtectedRoutes === true;
+    const [status, setStatus] = useState(skipProtection ? 'valid' : 'checking');
 
     useEffect(() => {
+        if (skipProtection) return;
+
         if (!isAuthenticated()) {
             setStatus('invalid');
             return;
         }
 
         // Skip backend validation for noLogin apps
-        if (getConstants().noLogin === true) {
+        if (constants.noLogin === true) {
             setStatus('valid');
             return;
         }
@@ -31,7 +52,7 @@ const ProtectedRoute = () => {
     }, []);
 
     if (status === 'checking') {
-        return null; // Or a loading spinner
+        return null;
     }
 
     return status === 'valid' ? <Outlet /> : <Navigate to="/signin" replace />;

package/README.md

@@ -97,6 +97,7 @@ const constants = {
 
   // Optional: Authentication
   noLogin: false,  // Set true to disable authentication
+  noProtectedRoutes: false,  // Set true to allow unauthenticated access to /app routes (use with useAuthGate)
 
   // Optional: Payments (Stripe)
   stripeProducts: [
@@ -177,6 +178,13 @@ Quick overview:
 | TextView | `@stevederico/skateboard-ui/TextView` | Legal pages |
 | NotFound | `@stevederico/skateboard-ui/NotFound` | 404 page |
 
+### Auth Overlay (Lazy Authentication)
+
+| Export | Import | Description |
+|--------|--------|-------------|
+| AuthOverlay | `@stevederico/skateboard-ui/AuthOverlay` | Modal sign-in/sign-up dialog |
+| useAuthGate | `@stevederico/skateboard-ui/useAuthGate` | Hook to gate actions behind auth |
+
 ### Enhanced Components (New in v1.3.0)
 
 | Component | Import | Description |
@@ -383,6 +391,53 @@ Import base theme and override as needed:
 
 Dark mode is automatic via CSS custom properties.
 
+## Lazy Authentication (Auth Overlay)
+
+Let users explore `/app` without signing in — prompt them only when they perform a protected action.
+
+### Setup
+
+Set `noProtectedRoutes: true` in your constants to allow unauthenticated access to `/app` routes:
+
+```json
+{
+  "noProtectedRoutes": true
+}
+```
+
+The `AuthOverlay` component is rendered automatically by `createSkateboardApp` — no additional wiring needed.
+
+### Usage
+
+```javascript
+import { useAuthGate } from '@stevederico/skateboard-ui/useAuthGate';
+
+function SaveButton() {
+  const requireAuth = useAuthGate();
+
+  function handleSave() {
+    requireAuth(() => {
+      // Only runs if user is authenticated
+      // If not signed in, auth overlay appears first
+      saveThing();
+    });
+  }
+
+  return <button onClick={handleSave}>Save</button>;
+}
+```
+
+### How it works
+
+1. User clicks a protected action (Save, Like, Post, etc.)
+2. `requireAuth()` checks if user is signed in
+3. If signed in — callback runs immediately
+4. If not — a modal dialog appears with sign-in/sign-up forms
+5. After successful auth, the original callback executes automatically
+6. User stays on the same page throughout — no navigation
+
+The dialog supports toggling between sign-in and sign-up modes inline, and can be dismissed with the X button (cancels the action).
+
 ## Protected Routes
 
 ```javascript

package/SettingsView.jsx

@@ -17,6 +17,20 @@ import {
 } from './shadcn/ui/alert-dialog.jsx';
 import { showCheckout, showManage } from './Utilities';
 
+/**
+ * User settings page with account info, sign out, support contact,
+ * and billing management.
+ *
+ * Shows subscription status and provides upgrade/manage buttons
+ * for Stripe billing. Hidden when constants.noLogin is true.
+ *
+ * @returns {JSX.Element} Settings page
+ *
+ * @example
+ * import SettingsView from '@stevederico/skateboard-ui/SettingsView';
+ *
+ * <Route path="settings" element={<SettingsView />} />
+ */
 export default function SettingsView() {
   const { state, dispatch } = getState();
   const constants = state.constants;

package/Sheet.jsx

@@ -6,6 +6,34 @@ import {
   DrawerTitle,
 } from "./shadcn/ui/drawer"
 
+/**
+ * Bottom sheet (drawer) component with imperative open/close API.
+ *
+ * Use a ref to control visibility programmatically.
+ *
+ * @param {Object} props
+ * @param {string} [props.title=""] - Sheet header title
+ * @param {string} [props.minHeight="auto"] - Minimum sheet height CSS value
+ * @param {React.ReactNode} props.children - Sheet body content
+ * @param {React.Ref} ref - Ref exposing { show, hide, open, close, toggle }
+ * @returns {JSX.Element} Drawer sheet
+ *
+ * @example
+ * import { useRef } from 'react';
+ * import Sheet from '@stevederico/skateboard-ui/Sheet';
+ *
+ * function MyComponent() {
+ *   const sheetRef = useRef();
+ *   return (
+ *     <>
+ *       <button onClick={() => sheetRef.current.show()}>Open</button>
+ *       <Sheet ref={sheetRef} title="Details">
+ *         <p>Sheet content</p>
+ *       </Sheet>
+ *     </>
+ *   );
+ * }
+ */
 const MySheet = forwardRef(function MySheet(props, ref) {
   const { title = "", minHeight = "auto", children } = props;
   const [isOpen, setIsOpen] = useState(false);

package/SignInView.jsx

@@ -15,6 +15,21 @@ import { useNavigate } from 'react-router-dom';
 import { getState } from "./Context.jsx";
 import { getBackendURL } from './Utilities'
 
+/**
+ * Full-page sign-in form.
+ *
+ * Authenticates via POST to /signin, dispatches SET_USER on success,
+ * and navigates to /app. Shows app branding and a link to sign up.
+ *
+ * @param {Object} props
+ * @param {string} [props.className] - Additional CSS classes
+ * @returns {JSX.Element} Sign-in page
+ *
+ * @example
+ * import SignInView from '@stevederico/skateboard-ui/SignInView';
+ *
+ * <Route path="/signin" element={<SignInView />} />
+ */
 export default function LoginForm({
   className,
   ...props

package/SignOutView.jsx

@@ -2,6 +2,19 @@ import { useEffect } from 'react';
 import { useNavigate } from 'react-router-dom';
 import { getBackendURL, getCSRFToken } from './Utilities';
 
+/**
+ * Sign-out handler page.
+ *
+ * Calls POST /signout on mount to clear the server session,
+ * then redirects to /signin.
+ *
+ * @returns {JSX.Element} Sign-out loading screen
+ *
+ * @example
+ * import SignOutView from '@stevederico/skateboard-ui/SignOutView';
+ *
+ * <Route path="/signout" element={<SignOutView />} />
+ */
 function SignOutView() {
   const navigate = useNavigate();
 

package/SignUpView.jsx

@@ -13,6 +13,22 @@ import { useNavigate } from 'react-router-dom';
 import { getState } from "./Context.jsx";
 import { getBackendURL } from './Utilities'
 
+/**
+ * Full-page sign-up form.
+ *
+ * Creates account via POST to /signup with name, email, and password.
+ * Validates password length (6-72 chars), dispatches SET_USER on success,
+ * and navigates to /app. Includes legal agreement links.
+ *
+ * @param {Object} props
+ * @param {string} [props.className] - Additional CSS classes
+ * @returns {JSX.Element} Sign-up page
+ *
+ * @example
+ * import SignUpView from '@stevederico/skateboard-ui/SignUpView';
+ *
+ * <Route path="/signup" element={<SignUpView />} />
+ */
 export default function LoginForm({
   className,
   ...props

package/SkeletonLoader.jsx

@@ -1,5 +1,15 @@
 import { Skeleton } from './shadcn/ui/skeleton.jsx';
 
+/**
+ * Card-shaped loading skeleton with three lines of varying width.
+ *
+ * @returns {JSX.Element} Card skeleton placeholder
+ *
+ * @example
+ * import { CardSkeleton } from '@stevederico/skateboard-ui/SkeletonLoader';
+ *
+ * {loading ? <CardSkeleton /> : <Card data={data} />}
+ */
 export function CardSkeleton() {
   return (
     <div className="space-y-3">
@@ -10,6 +20,18 @@ export function CardSkeleton() {
   );
 }
 
+/**
+ * Table loading skeleton with configurable row count.
+ *
+ * @param {Object} props
+ * @param {number} [props.rows=5] - Number of skeleton rows
+ * @returns {JSX.Element} Table skeleton placeholder
+ *
+ * @example
+ * import { TableSkeleton } from '@stevederico/skateboard-ui/SkeletonLoader';
+ *
+ * {loading ? <TableSkeleton rows={3} /> : <Table data={data} />}
+ */
 export function TableSkeleton({ rows = 5 }) {
   return (
     <div className="space-y-2">
@@ -20,10 +42,30 @@ export function TableSkeleton({ rows = 5 }) {
   );
 }
 
+/**
+ * Circular avatar loading skeleton.
+ *
+ * @returns {JSX.Element} Avatar skeleton placeholder
+ *
+ * @example
+ * import { AvatarSkeleton } from '@stevederico/skateboard-ui/SkeletonLoader';
+ *
+ * {loading ? <AvatarSkeleton /> : <Avatar user={user} />}
+ */
 export function AvatarSkeleton() {
   return <Skeleton className="h-12 w-12 rounded-full" />;
 }
 
+/**
+ * Form loading skeleton with label and input placeholders.
+ *
+ * @returns {JSX.Element} Form skeleton placeholder
+ *
+ * @example
+ * import { FormSkeleton } from '@stevederico/skateboard-ui/SkeletonLoader';
+ *
+ * {loading ? <FormSkeleton /> : <MyForm />}
+ */
 export function FormSkeleton() {
   return (
     <div className="space-y-4">

package/TabBar.jsx

@@ -3,6 +3,20 @@ import { Link, useLocation } from 'react-router-dom';
 import DynamicIcon from './DynamicIcon';
 import { getState } from './Context.jsx';
 
+/**
+ * Mobile bottom tab bar navigation.
+ *
+ * Renders page icons from constants.pages plus a settings tab.
+ * Only visible on mobile (hidden on md+ screens via Layout).
+ *
+ * @returns {JSX.Element} Bottom tab bar
+ *
+ * @example
+ * import TabBar from '@stevederico/skateboard-ui/TabBar';
+ *
+ * // Used internally by Layout component
+ * <TabBar />
+ */
 export default function TabBar() {
   const location = useLocation();
   const { state } = getState();

package/TextView.jsx

@@ -1,6 +1,21 @@
 import { getState } from "./Context.jsx";
 
 
+/**
+ * Legal/text document viewer.
+ *
+ * Renders a plain-text document with placeholder replacement for
+ * _COMPANY_, _WEBSITE_, and _EMAIL_ using values from constants.
+ *
+ * @param {Object} props
+ * @param {string} props.details - Raw text content with optional placeholders
+ * @returns {JSX.Element} Formatted text page
+ *
+ * @example
+ * import TextView from '@stevederico/skateboard-ui/TextView';
+ *
+ * <Route path="/terms" element={<TextView details={constants.termsOfService} />} />
+ */
 export default function TextView({ details }) {
   const { state } = getState();
   const constants = state.constants;

package/ThemeToggle.jsx

@@ -9,6 +9,24 @@ const DynamicIcon = ({ name, size = 24, color = 'currentColor', strokeWidth = 2,
   return LucideIcon ? React.createElement(LucideIcon, { size, color, strokeWidth, ...props }) : null;
 };
 
+/**
+ * Dark/light mode toggle button.
+ *
+ * Renders a sun/moon icon that toggles the theme via next-themes.
+ * Supports two visual variants: "settings" (minimal) and "landing" (boxed).
+ *
+ * @param {Object} props
+ * @param {string} [props.className=""] - Additional CSS classes
+ * @param {number} [props.iconSize=24] - Icon size in pixels
+ * @param {string} [props.variant="settings"] - Visual style ("settings" | "landing")
+ * @returns {JSX.Element|null} Toggle button or null before mount
+ *
+ * @example
+ * import ThemeToggle from '@stevederico/skateboard-ui/ThemeToggle';
+ *
+ * <ThemeToggle />
+ * <ThemeToggle variant="landing" iconSize={18} />
+ */
 export default function ThemeToggle({ className = "", iconSize = 24, variant = "settings" }) {
   const { theme, setTheme } = useTheme();
   const [mounted, setMounted] = React.useState(false);

package/Toast.jsx

@@ -1,5 +1,23 @@
 import { Toaster } from './shadcn/ui/sonner.jsx';
 
+/**
+ * Global toast notification container.
+ *
+ * Renders the Sonner Toaster in the top-right with rich colors
+ * and close buttons enabled. Rendered once at the app root.
+ *
+ * @returns {JSX.Element} Toast container
+ *
+ * @example
+ * import Toast from '@stevederico/skateboard-ui/Toast';
+ *
+ * // Rendered automatically by createSkateboardApp
+ * <Toast />
+ *
+ * // Trigger toasts from anywhere:
+ * import { toast } from 'sonner';
+ * toast.success('Saved!');
+ */
 export default function Toast() {
   return (
     <Toaster

package/UpgradeSheet.jsx

@@ -9,6 +9,31 @@ import { getState } from "./Context.jsx";
 import { showCheckout } from './Utilities.js';
 import { Sparkles } from 'lucide-react';
 
+/**
+ * Premium upgrade bottom sheet with pricing and checkout button.
+ *
+ * Displays the first Stripe product from constants with price,
+ * features list, and a checkout button. Controlled via ref.
+ *
+ * @param {Object} props
+ * @param {string} [props.userEmail=""] - User email for Stripe checkout
+ * @param {React.Ref} ref - Ref exposing { show, hide, open, close, toggle }
+ * @returns {JSX.Element} Upgrade drawer
+ *
+ * @example
+ * import { useRef } from 'react';
+ * import UpgradeSheet from '@stevederico/skateboard-ui/UpgradeSheet';
+ *
+ * function MyComponent() {
+ *   const upgradeRef = useRef();
+ *   return (
+ *     <>
+ *       <button onClick={() => upgradeRef.current.show()}>Upgrade</button>
+ *       <UpgradeSheet ref={upgradeRef} userEmail={user.email} />
+ *     </>
+ *   );
+ * }
+ */
 const UpgradeSheet = forwardRef(function UpgradeSheet(props, ref) {
   const { userEmail = "" } = props;
   const [isOpen, setIsOpen] = useState(false);

package/Utilities.js

@@ -97,6 +97,15 @@ export function initializeUtilities(constants) {
     }
 }
 
+/**
+ * Get the app constants object.
+ *
+ * Returns constants from window.__SKATEBOARD_CONSTANTS__ (handles Vite
+ * module duplication) or the module-level variable.
+ *
+ * @returns {Object} App constants
+ * @throws {Error} If initializeUtilities() hasn't been called
+ */
 export function getConstants() {
     // Check window object first (handles module duplication)
     if (typeof window !== 'undefined' && window.__SKATEBOARD_CONSTANTS__) {
@@ -109,6 +118,14 @@ export function getConstants() {
     return _constants;
 }
 
+/**
+ * Read a browser cookie by name.
+ *
+ * For the "token" cookie, automatically prefixes with the app name.
+ *
+ * @param {string} name - Cookie name
+ * @returns {string|null} Cookie value or null
+ */
 export function getCookie(name) {
     // For token cookies, use app-specific name
     let cookieName = name;
@@ -216,6 +233,11 @@ export function getBackendURL() {
     return result
 }
 
+/**
+ * Check if the app is running inside a native WebKit wrapper (iOS/macOS).
+ *
+ * @returns {boolean} True if webkit.messageHandlers is available
+ */
 export function isAppMode() {
     let a = !!(
         typeof window !== 'undefined' &&
@@ -225,6 +247,18 @@ export function isAppMode() {
     return a
 }
 
+/**
+ * Fetch the current authenticated user from the backend.
+ *
+ * Calls GET /me with credentials and CSRF token.
+ * Returns an empty object if constants.noLogin is true.
+ *
+ * @returns {Promise<Object|null>} User object or null on error
+ *
+ * @example
+ * const user = await getCurrentUser();
+ * if (user) dispatch({ type: 'SET_USER', payload: user });
+ */
 export async function getCurrentUser() {
 
     if (getConstants().noLogin == true) {
@@ -254,6 +288,14 @@ export async function getCurrentUser() {
     }
 }
 
+/**
+ * Check if the current user has an active subscription.
+ *
+ * Calls GET /isSubscriber with credentials.
+ * Returns false if constants.noLogin is true.
+ *
+ * @returns {Promise<boolean>} True if user is an active subscriber
+ */
 export async function isSubscriber() {
     if (getConstants().noLogin == true) {
         return false
@@ -285,10 +327,25 @@ export async function isSubscriber() {
     }
 }
 
+/**
+ * Log an analytics event. Stub for custom analytics integration.
+ *
+ * @param {string} event - Event name to log
+ * @returns {Promise<void>}
+ */
 export async function logEvent(event) {
     //insert analytics code here
 }
 
+/**
+ * Open the Stripe billing portal for subscription management.
+ *
+ * Saves the current URL for redirect-back after portal return,
+ * then redirects the browser to the Stripe portal URL.
+ *
+ * @param {string} stripeID - Stripe customer ID
+ * @returns {Promise<void>}
+ */
 export async function showManage(stripeID) {
     try {
         const csrfToken = getCSRFToken();
@@ -319,6 +376,16 @@ export async function showManage(stripeID) {
     }
 }
 
+/**
+ * Start a Stripe checkout session.
+ *
+ * Creates a checkout session via POST /checkout, saves the current URL
+ * for redirect-back, then redirects to the Stripe checkout page.
+ *
+ * @param {string} email - Customer email for Stripe
+ * @param {number} [productIndex=0] - Index into constants.stripeProducts
+ * @returns {Promise<boolean>} True if redirect initiated, false on error
+ */
 export async function showCheckout(email, productIndex = 0) {
     try {
         const csrfToken = getCSRFToken();
@@ -361,6 +428,15 @@ export async function showCheckout(email, productIndex = 0) {
     }
 }
 
+/**
+ * Check remaining usage quota for a given action.
+ *
+ * Calls POST /usage with operation "check".
+ * Returns unlimited usage (-1) if constants.noLogin is true.
+ *
+ * @param {string} action - Action type to check usage for
+ * @returns {Promise<{remaining: number, total: number, isSubscriber: boolean}>}
+ */
 export async function getRemainingUsage(action) {
     if (getConstants().noLogin === true) {
         return { remaining: -1, total: -1, isSubscriber: true };
@@ -390,6 +466,16 @@ export async function getRemainingUsage(action) {
     }
 }
 
+/**
+ * Track (decrement) usage for a given action.
+ *
+ * Calls POST /usage with operation "track".
+ * Returns unlimited usage (-1) if constants.noLogin is true.
+ * Returns usage data even when rate limited (HTTP 429).
+ *
+ * @param {string} action - Action type to track
+ * @returns {Promise<{remaining: number, total: number, isSubscriber: boolean}>}
+ */
 export async function trackUsage(action) {
     if (getConstants().noLogin === true) {
         return { remaining: -1, total: -1, isSubscriber: true };
@@ -425,6 +511,16 @@ export async function trackUsage(action) {
     }
 }
 
+/**
+ * Show the upgrade sheet if the user is not a subscriber.
+ *
+ * Checks subscription status from localStorage user data.
+ * Does nothing for active subscribers. Falls back to navigation
+ * if the ref is unavailable.
+ *
+ * @param {React.RefObject} upgradeSheetRef - Ref to UpgradeSheet component
+ * @returns {Promise<void>}
+ */
 export async function showUpgradeSheet(upgradeSheetRef) {
     // Check subscription from user data in localStorage instead of API call
     const appName = getConstants().appName || 'skateboard';
@@ -456,6 +552,20 @@ export async function showUpgradeSheet(upgradeSheetRef) {
     }
 }
 
+/**
+ * Convert a timestamp or Date to a formatted string.
+ *
+ * Handles both seconds and milliseconds timestamps, and Date objects.
+ *
+ * @param {number|Date} input - Unix timestamp (seconds or ms) or Date
+ * @param {string} [format="DOB"] - Format: "DOB" | "ISO" | "ago" | "day-month-time" | "day" | "time" | "full" | "DOBT"
+ * @returns {string} Formatted date string
+ *
+ * @example
+ * timestampToString(1700000000, 'ago')    // "2 months ago"
+ * timestampToString(Date.now(), 'DOBT')   // "3:45 PM"
+ * timestampToString(new Date(), 'full')   // "Monday, November 13 2023 10:00 AM"
+ */
 export function timestampToString(input, format = "DOB") {
 
     let seconds = 0
@@ -555,6 +665,11 @@ export function timestampToString(input, format = "DOB") {
     }
 }
 
+/**
+ * Hook that sets the document title and removes dark mode on non-app pages.
+ *
+ * @param {Object} location - react-router location object
+ */
 export function useAppSetup(location) {
     useEffect(() => {
         document.title = getConstants().appName;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@stevederico/skateboard-ui",
   "private": false,
-  "version": "1.4.1",
+  "version": "1.5.0",
   "type": "module",
   "exports": {
     "./AppSidebar": {
@@ -100,6 +100,14 @@
       "import": "./Toast.jsx",
       "default": "./Toast.jsx"
     },
+    "./AuthOverlay": {
+      "import": "./AuthOverlay.jsx",
+      "default": "./AuthOverlay.jsx"
+    },
+    "./useAuthGate": {
+      "import": "./useAuthGate.js",
+      "default": "./useAuthGate.js"
+    },
     "./SkeletonLoader": {
       "import": "./SkeletonLoader.jsx",
       "default": "./SkeletonLoader.jsx"

package/useAuthGate.js

@@ -0,0 +1,37 @@
+import { useCallback } from 'react';
+import { getState } from './Context.jsx';
+
+/**
+ * Hook that gates actions behind authentication.
+ *
+ * If the user is authenticated, the callback runs immediately.
+ * If not, the auth overlay is shown and the callback runs after successful auth.
+ *
+ * @returns {Function} requireAuth - Call with a callback to gate behind auth
+ *
+ * @example
+ * import { useAuthGate } from '@stevederico/skateboard-ui/useAuthGate';
+ *
+ * function MyComponent() {
+ *   const requireAuth = useAuthGate();
+ *
+ *   function handleSave() {
+ *     requireAuth(() => {
+ *       saveThing();
+ *     });
+ *   }
+ * }
+ */
+export function useAuthGate() {
+  const { state, dispatch } = getState();
+
+  const requireAuth = useCallback((callback) => {
+    if (state.user) {
+      callback();
+    } else {
+      dispatch({ type: 'SHOW_AUTH_OVERLAY', payload: callback });
+    }
+  }, [state.user, dispatch]);
+
+  return requireAuth;
+}