@stevederico/skateboard-ui 1.2.16 → 1.2.18

package/CHANGELOG.md

@@ -1,4 +1,16 @@
 # CHANGELOG
+1.2.18
+
+  Add authentication documentation
+  Add JSDoc comments
+  Update README configuration
+  Create docs folder
+
+1.2.17
+
+  Fix SignIn layout positioning
+  Fix SignUp layout positioning
+
 1.2.14
 
   Fix isAuthenticated validation

package/Context.jsx

@@ -5,6 +5,22 @@ const context = createContext();
 // Store dispatch reference for programmatic access outside components
 let _dispatch = null;
 
+/**
+ * Get dispatch function for programmatic state updates outside components.
+ *
+ * Useful for updating state from non-React code (event handlers, utilities).
+ * Returns null if ContextProvider hasn't mounted yet.
+ *
+ * @returns {Function|null} Dispatch function or null
+ *
+ * @example
+ * import { getDispatch } from '@stevederico/skateboard-ui/Context';
+ *
+ * const dispatch = getDispatch();
+ * if (dispatch) {
+ *   dispatch({ type: 'CLEAR_USER' });
+ * }
+ */
 export function getDispatch() {
   return _dispatch;
 }
@@ -58,6 +74,24 @@ function safeLSRemoveItem(key) {
   }
 }
 
+/**
+ * Global state provider for skateboard-ui.
+ *
+ * Manages user authentication state and UI visibility (sidebar, tabbar).
+ * Persists user data to localStorage using app-specific keys.
+ *
+ * @param {Object} props
+ * @param {Object} props.constants - App configuration
+ * @param {string} props.constants.appName - Used for localStorage key namespacing
+ * @param {React.ReactNode} props.children - Child components
+ *
+ * @example
+ * import { ContextProvider } from '@stevederico/skateboard-ui/Context';
+ *
+ * <ContextProvider constants={constants}>
+ *   <App />
+ * </ContextProvider>
+ */
 export function ContextProvider({ children, constants }) {
   const getStorageKey = () => {
     const appName = constants.appName || 'skateboard';
@@ -133,6 +167,24 @@ export function ContextProvider({ children, constants }) {
   );
 }
 
+/**
+ * Hook to access skateboard-ui state.
+ *
+ * Returns { state, dispatch } where state contains:
+ * - user: Current user object or null
+ * - ui: { sidebarVisible, tabBarVisible }
+ *
+ * @returns {{ state: Object, dispatch: Function }}
+ *
+ * @example
+ * import { getState } from '@stevederico/skateboard-ui/Context';
+ *
+ * function MyComponent() {
+ *   const { state, dispatch } = getState();
+ *   console.log(state.user);
+ *   dispatch({ type: 'SET_USER', payload: userData });
+ * }
+ */
 export function getState() {
   return useContext(context);
 }

package/README.md

@@ -25,6 +25,92 @@ createSkateboardApp({ constants, appRoutes });
 
 That's it! You get routing, auth, layout, landing page, settings, and payments.
 
+## Configuration
+
+skateboard-ui requires a `constants` object that configures your application:
+
+```javascript
+// constants.json or constants.js
+const constants = {
+  // Required: Backend URLs (include /api prefix)
+  devBackendURL: "http://localhost:8000/api",
+  backendURL: "https://api.myapp.com/api",
+
+  // Required: App identity
+  appName: "MyApp",
+  appIcon: "🛹",
+
+  // Required: Landing page content
+  tagline: "Build apps faster with skateboard-ui",
+  cta: "Get Started",
+
+  // Required: Features section
+  features: {
+    title: "Everything you need",
+    items: [
+      { icon: "Zap", title: "Fast", description: "Built for speed" },
+      { icon: "Shield", title: "Secure", description: "Authentication included" }
+    ]
+  },
+
+  // Required: Company information
+  companyName: "Your Company",
+  companyWebsite: "https://yourcompany.com",
+  companyEmail: "hello@yourcompany.com",
+
+  // Optional: Authentication
+  noLogin: false,  // Set true to disable authentication
+
+  // Optional: Payments (Stripe)
+  stripeProducts: [
+    {
+      name: "Pro Plan",
+      priceId: "price_123",
+      price: "$10/month",
+      lookup_key: "pro_plan"
+    }
+  ],
+
+  // Optional: Legal documents
+  termsOfService: "Your terms of service...",
+  privacyPolicy: "Your privacy policy...",
+
+  // Optional: UI visibility
+  hideSidebar: false,
+  hideTabBar: false
+}
+```
+
+### Backend URL Pattern
+
+The `devBackendURL` and `backendURL` should include your full API base path (including the `/api` prefix):
+
+```javascript
+const constants = {
+  devBackendURL: "http://localhost:8000/api",  // Include /api prefix
+  backendURL: "https://api.myapp.com/api",
+}
+```
+
+Endpoints are relative to this base URL:
+- `${getBackendURL()}/signup` → `http://localhost:8000/api/signup`
+- `${getBackendURL()}/me` → `http://localhost:8000/api/me`
+- `${getBackendURL()}/deals` → `http://localhost:8000/api/deals`
+
+**Tip:** Include API versioning in the base URL (e.g., `/api/v2`) rather than in each endpoint path.
+
+### Authentication Setup
+
+skateboard-ui uses a hybrid cookie + localStorage authentication system. Your backend must implement specific endpoints and cookie handling.
+
+**See [AUTHENTICATION.md](./docs/AUTHENTICATION.md) for complete backend setup requirements.**
+
+Quick overview:
+- Session token stored in HttpOnly cookie for security
+- CSRF token in localStorage for request validation
+- Backend validates cookies on protected endpoints
+- Client-side `isAuthenticated()` checks localStorage for fast validation
+
 ## Components
 
 ### Core Components
@@ -253,6 +339,10 @@ import ProtectedRoute from '@stevederico/skateboard-ui/ProtectedRoute';
 
 Used internally by createSkateboardApp. Redirects to /signin if not authenticated.
 
+## Documentation
+
+- **[Authentication Guide](./docs/AUTHENTICATION.md)** - Complete guide to the hybrid cookie + localStorage authentication system, including backend requirements, security considerations, and Express.js implementation examples
+
 ## Dependencies
 
 - React 19.1+

package/SignInView.jsx

@@ -73,7 +73,7 @@ export default function LoginForm({
   }
 
   return (
-    <div className="min-h-screen bg-white dark:bg-black transition-colors duration-300">
+    <div className="fixed inset-0 bg-white dark:bg-black transition-colors duration-300 overflow-auto">
       <div className={cn("flex flex-col gap-6 p-4 max-w-lg mx-auto mt-20", className)} {...props}>
       <div className="flex flex-row items-center justify-center mb-4">
         <div className="bg-app dark:bg-app dark:border dark:border-gray-700 rounded-2xl flex aspect-square size-16 items-center justify-center">

package/SignUpView.jsx

@@ -75,7 +75,7 @@ export default function LoginForm({
   }
 
   return (
-    <div className="min-h-screen bg-white dark:bg-black transition-colors duration-300">
+    <div className="fixed inset-0 bg-white dark:bg-black transition-colors duration-300 overflow-auto">
       <div className={cn("flex flex-col gap-6 p-4 max-w-lg mx-auto mt-20", className)} {...props}>
       <div className="flex flex-row items-center justify-center mb-4">
         <div className="bg-app dark:bg-app dark:border dark:border-gray-700 rounded-2xl flex aspect-square size-16 items-center justify-center">

package/Utilities.js

@@ -65,6 +65,27 @@ function safeRemoveItem(key) {
     }
 }
 
+/**
+ * Initialize skateboard-ui utilities with app constants.
+ *
+ * MUST be called before any utility functions are used, including
+ * before React components render. Stores constants in both module-level
+ * variable and window.__SKATEBOARD_CONSTANTS__ to handle Vite module
+ * duplication issues.
+ *
+ * @param {Object} constants - App configuration object
+ * @param {string} constants.appName - Application name
+ * @param {string} constants.devBackendURL - Development API base URL (include /api prefix)
+ * @param {string} constants.backendURL - Production API base URL (include /api prefix)
+ * @throws {Error} If constants is null/undefined
+ *
+ * @example
+ * initializeUtilities({
+ *   appName: "MyApp",
+ *   devBackendURL: "http://localhost:8000/api",
+ *   backendURL: "https://api.myapp.com/api"
+ * });
+ */
 export function initializeUtilities(constants) {
     if (!constants) {
         throw new Error('initializeUtilities called with null/undefined constants');
@@ -102,17 +123,66 @@ export function getCookie(name) {
     return null;
 }
 
+/**
+ * Get CSRF token from localStorage.
+ *
+ * Returns the CSRF token saved during signin/signup. This token
+ * should be sent in the X-CSRF-Token header for state-changing requests.
+ *
+ * @returns {string|null} CSRF token or null if not found
+ *
+ * @example
+ * const csrfToken = getCSRFToken();
+ * fetch('/api/endpoint', {
+ *   headers: { 'X-CSRF-Token': csrfToken }
+ * });
+ */
 export function getCSRFToken() {
     const appName = getConstants().appName || 'skateboard';
     const csrfKey = `${appName.toLowerCase().replace(/\s+/g, '-')}_csrf`;
     return safeGetItem(csrfKey);
 }
 
+/**
+ * Generate app-specific localStorage key.
+ *
+ * Creates namespaced keys using app name: `{appName}_{suffix}`
+ * App name is normalized (lowercase, hyphens replace spaces)
+ *
+ * @param {string} suffix - Key suffix (e.g., 'csrf', 'user', 'theme')
+ * @returns {string} Namespaced key
+ *
+ * @example
+ * getAppKey('csrf')  // "myapp_csrf"
+ * getAppKey('user')  // "myapp_user"
+ * getAppKey('theme') // "myapp_theme"
+ */
 export function getAppKey(suffix) {
     const appName = getConstants().appName || 'skateboard';
     return `${appName.toLowerCase().replace(/\s+/g, '-')}_${suffix}`;
 }
 
+/**
+ * Check if user is authenticated.
+ *
+ * Uses localStorage (NOT cookies) for fast client-side validation.
+ * Checks for both CSRF token and user data in localStorage.
+ * If constants.noLogin is true, always returns true.
+ *
+ * Note: This is a client-side check only. ProtectedRoute performs
+ * additional server-side validation via /me endpoint.
+ *
+ * @returns {boolean} True if authenticated or noLogin mode
+ *
+ * @see {@link ProtectedRoute} for server-side validation
+ *
+ * @example
+ * if (isAuthenticated()) {
+ *   // Show authenticated UI
+ * } else {
+ *   // Redirect to signin
+ * }
+ */
 export function isAuthenticated() {
     if (getConstants().noLogin === true) {
         return true;
@@ -122,6 +192,19 @@ export function isAuthenticated() {
     return Boolean(safeGetItem(csrfKey)) && Boolean(safeGetItem(userKey));
 }
 
+/**
+ * Get the backend API base URL based on environment.
+ *
+ * Returns devBackendURL in development mode, backendURL in production.
+ * Endpoints should be concatenated: `${getBackendURL()}/endpoint`
+ *
+ * @returns {string} Base URL including /api prefix
+ *
+ * @example
+ * const url = `${getBackendURL()}/signup`;
+ * // Dev:  "http://localhost:8000/api/signup"
+ * // Prod: "https://api.myapp.com/api/signup"
+ */
 export function getBackendURL() {
     let result = import.meta.env.DEV ? getConstants().devBackendURL : getConstants().backendURL;
     return result