@onexapis/cli 1.1.38 → 1.1.39

package/templates/default/LAYOUT.md

@@ -0,0 +1,195 @@
+# Header & Footer Layout — Default Theme
+
+This document covers the built-in header and footer sections that render on every page via `theme.layout.ts`.
+
+## How It Works
+
+Header and footer are **layout-level sections** — they're defined once in `theme.layout.ts` and rendered on every page automatically. Individual pages can opt out using `hideHeader` / `hideFooter`.
+
+```
+theme.layout.ts
+  ├── headerSections[] ──→ rendered as <header> on every page
+  └── footerSections[] ──→ rendered as <footer> on every page
+
+Page config
+  ├── hideHeader: true  ──→ skips header for this page
+  └── hideFooter: true  ──→ skips footer for this page
+```
+
+## Header Section
+
+### Smart Scroll Behavior (default: on)
+
+The header auto-hides when scrolling down and reappears when scrolling up. This is fully customizable via schema settings:
+
+| Setting              | Type     | Default     | Description                                   |
+| -------------------- | -------- | ----------- | --------------------------------------------- |
+| `sticky`             | checkbox | `true`      | Pin header to top of viewport                 |
+| `autoHide`           | checkbox | `true`      | Hide on scroll down, show on scroll up        |
+| `scrollThreshold`    | number   | `10`        | Pixels of scroll needed to trigger hide/show  |
+| `showShadowOnScroll` | checkbox | `true`      | Add drop shadow when page is scrolled         |
+| `transparentOnTop`   | checkbox | `false`     | Transparent background when at top of page    |
+| `headerHeight`       | select   | `16` (64px) | Compact (48px) / Default (64px) / Tall (80px) |
+
+### Behavior Presets
+
+**Default (sticky + auto-hide):**
+
+```ts
+// theme.layout.ts
+settings: {
+  sticky: true,
+  autoHide: true,
+  showShadowOnScroll: true,
+  transparentOnTop: false,
+}
+```
+
+**Always visible (no auto-hide):**
+
+```ts
+settings: {
+  sticky: true,
+  autoHide: false,    // ← stays visible at all times
+  showShadowOnScroll: true,
+}
+```
+
+**Transparent hero overlay:**
+
+```ts
+settings: {
+  sticky: true,
+  autoHide: true,
+  transparentOnTop: true,  // ← transparent at top, solid on scroll
+  showShadowOnScroll: true,
+}
+```
+
+**Static (not sticky):**
+
+```ts
+settings: {
+  sticky: false,      // ← scrolls away with the page
+  autoHide: false,
+}
+```
+
+### Other Header Settings
+
+| Setting           | Type  | Default               | Description                               |
+| ----------------- | ----- | --------------------- | ----------------------------------------- |
+| `logoText`        | text  | `"My Site"`           | Logo text (fallback if no logo component) |
+| `navigationItems` | array | Home, About, Showcase | Navigation links `[{ label, href }]`      |
+| `ctaText`         | text  | `"Contact"`           | CTA button text                           |
+| `ctaLink`         | url   | `"#contact"`          | CTA button link                           |
+| `backgroundColor` | color | `#FFFFFF`             | Header background                         |
+| `textColor`       | color | `#111827`             | Navigation text color                     |
+| `primaryColor`    | color | `#2563EB`             | CTA button color                          |
+
+### How Auto-Hide Works
+
+The header uses `requestAnimationFrame` for smooth 60fps scroll detection:
+
+1. **Scroll down > threshold** (and past 80px from top) → header slides up (`translateY(-100%)`)
+2. **Scroll up > threshold** → header slides back down (`translateY(0)`)
+3. **At very top** (scrollY = 0) → always visible
+4. **In editor** (`isEditing = true`) → auto-hide disabled, always visible
+5. CSS transition: `duration-300 ease-in-out` for smooth animation
+
+## Footer Section
+
+### Settings
+
+| Setting            | Type     | Default                    | Description                     |
+| ------------------ | -------- | -------------------------- | ------------------------------- |
+| `companyName`      | text     | `"My Site"`                | Company name                    |
+| `description`      | textarea | `"A clean and minimal..."` | Company description             |
+| `showAboutColumn`  | checkbox | `true`                     | Show/hide about links column    |
+| `aboutColumnTitle` | text     | `"About"`                  | About column heading            |
+| `aboutLinks`       | array    | About Us, Contact          | About links `[{ label, href }]` |
+| `showLinksColumn`  | checkbox | `true`                     | Show/hide quick links column    |
+| `linksColumnTitle` | text     | `"Quick Links"`            | Links column heading            |
+| `quickLinks`       | array    | Home, Showcase             | Quick links `[{ label, href }]` |
+| `copyrightText`    | text     | `"My Site. All rights..."` | Copyright text                  |
+| `backgroundColor`  | color    | `#111827`                  | Footer background               |
+| `textColor`        | color    | `#9CA3AF`                  | Body text color                 |
+| `primaryColor`     | color    | `#FFFFFF`                  | Heading color                   |
+
+## Per-Page Visibility
+
+Auth pages (login, register, forgot-password, verify-code) have `hideHeader: true` and `hideFooter: true` by default since they're full-screen.
+
+### Hide header/footer on a page
+
+```ts
+// pages/my-page.ts
+export const myPageConfig = {
+  title: "My Page",
+  handle: "my-page",
+  path: "/my-page",
+  hideHeader: true, // ← no header on this page
+  hideFooter: true, // ← no footer on this page
+  // ...
+};
+```
+
+### Pages with header/footer (default)
+
+Pages without `hideHeader`/`hideFooter` get both automatically:
+
+| Page                                 | Header | Footer |
+| ------------------------------------ | ------ | ------ |
+| Home (`/`)                           | Yes    | Yes    |
+| About (`/about`)                     | Yes    | Yes    |
+| Showcase (`/showcase`)               | Yes    | Yes    |
+| Profile (`/profile`)                 | Yes    | Yes    |
+| Login (`/login`)                     | No     | No     |
+| Register (`/register`)               | No     | No     |
+| Forgot Password (`/forgot-password`) | No     | No     |
+| Verify Code (`/verify-code`)         | No     | No     |
+
+## Customizing in the Editor
+
+In the visual editor:
+
+1. Go to **Theme Settings** (gear icon)
+2. Open **Header Sections** or **Footer Sections** accordion
+3. Click on the section to edit its settings
+4. Changes apply to all pages that show the header/footer
+
+## File Structure
+
+```
+sections/
+  header/
+    header-default.tsx     # Component with smart scroll behavior
+    header.schema.ts       # All settings including scroll behavior
+    index.ts
+  footer/
+    footer-default.tsx     # 3-column footer
+    footer.schema.ts       # Company info, links, copyright settings
+    index.ts
+theme.layout.ts            # References header/footer with default settings
+```
+
+## Extending
+
+### Adding a second header template
+
+```ts
+// sections/header/header-centered.tsx
+export function HeaderCentered({ section, schema, isEditing }) { ... }
+
+// sections/header/index.ts
+export const headerComponents = {
+  default: HeaderDefault,
+  centered: HeaderCentered,   // ← new template
+};
+```
+
+Then in `theme.layout.ts`, change `template: "centered"`.
+
+### Custom scroll behavior
+
+Override the `useHeaderScroll` hook logic in `header-default.tsx`, or create a new template with different behavior. All scroll settings are passed via schema — no code changes needed for basic customization.

package/templates/default/bundle-entry.ts

@@ -16,3 +16,8 @@ export { default as layoutConfig } from "./theme.layout";
 export { default as homePageConfig } from "./pages/home";
 export { default as aboutPageConfig } from "./pages/about";
 export { default as showcasePageConfig } from "./pages/showcase";
+export { default as loginPageConfig } from "./pages/login";
+export { default as registerPageConfig } from "./pages/register";
+export { default as forgotPasswordPageConfig } from "./pages/forgot-password";
+export { default as verifyCodePageConfig } from "./pages/verify-code";
+export { default as profilePageConfig } from "./pages/profile";

package/templates/default/esbuild.config.js

@@ -0,0 +1,20 @@
+const { build } = require("esbuild");
+const path = require("path");
+
+build({
+  entryPoints: [path.resolve(__dirname, "bundle-entry.ts")],
+  bundle: true,
+  outfile: path.resolve(__dirname, "dist/bundle.mjs"),
+  format: "esm",
+  target: "es2020",
+  platform: "browser",
+  jsx: "automatic",
+  external: ["react", "react-dom", "@onexapis/core", "@onexapis/core/*"],
+  sourcemap: true,
+  minify: process.env.NODE_ENV === "production",
+  define: {
+    "process.env.NODE_ENV": JSON.stringify(
+      process.env.NODE_ENV || "development"
+    ),
+  },
+}).catch(() => process.exit(1));

package/templates/default/hooks/index.ts

@@ -0,0 +1,26 @@
+/**
+ * Theme Hooks
+ * Re-exports all authentication form hooks
+ */
+
+export { useLoginForm } from "./use-login-form";
+export type { LoginFormData, UseLoginFormReturn } from "./use-login-form";
+
+export { useRegisterForm } from "./use-register-form";
+export type {
+  RegisterFormData,
+  UseRegisterFormReturn,
+} from "./use-register-form";
+
+export { useForgotPasswordForm } from "./use-forgot-password-form";
+export type { UseForgotPasswordFormReturn } from "./use-forgot-password-form";
+
+export { useVerifyCodeForm } from "./use-verify-code-form";
+export type { UseVerifyCodeFormReturn } from "./use-verify-code-form";
+
+export { useProfileForm } from "./use-profile-form";
+export type {
+  ProfileFormData,
+  ChangePasswordData,
+  UseProfileFormReturn,
+} from "./use-profile-form";

package/templates/default/hooks/use-forgot-password-form.ts

@@ -0,0 +1,90 @@
+/**
+ * Forgot Password Form Hook
+ * Manages form state, validation, and submission via useAuth
+ */
+
+"use client";
+
+import { useState, useCallback } from "react";
+import { useAuth } from "@onexapis/core/hooks";
+
+export interface UseForgotPasswordFormReturn {
+  username: string;
+  error: string | null;
+  isPending: boolean;
+  setUsername: (value: string) => void;
+  handleUsernameChange: (e: React.ChangeEvent<HTMLInputElement>) => void;
+  handleSubmit: (e: React.FormEvent) => void;
+  clearError: () => void;
+}
+
+export function useForgotPasswordForm(): UseForgotPasswordFormReturn {
+  const [username, setUsername] = useState("");
+  const [error, setError] = useState<string | null>(null);
+  const [isPending, setIsPending] = useState(false);
+
+  const { forgotPassword } = useAuth();
+
+  const handleUsernameChange = useCallback(
+    (e: React.ChangeEvent<HTMLInputElement>) => {
+      setUsername(e.target.value);
+      setError(null);
+    },
+    []
+  );
+
+  const handleSubmit = useCallback(
+    async (e: React.FormEvent) => {
+      e.preventDefault();
+      if (!username) {
+        setError("Please enter your email or username");
+        return;
+      }
+      if (
+        username.includes("@") &&
+        !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(username)
+      ) {
+        setError("Invalid email format");
+        return;
+      }
+
+      setError(null);
+      setIsPending(true);
+      try {
+        await forgotPassword({ username });
+        // Store countdown and redirect to verify-code
+        if (typeof window !== "undefined") {
+          const expiryTimestamp = Date.now() + 60 * 1000;
+          localStorage.setItem(
+            `resend_countdown_${username}`,
+            expiryTimestamp.toString()
+          );
+          window.location.href = `/verify-code?mode=reset&username=${encodeURIComponent(username)}`;
+        }
+      } catch (err) {
+        const message =
+          err instanceof Error
+            ? err.message
+            : "Failed to send verification code";
+        setError(message);
+      } finally {
+        setIsPending(false);
+      }
+    },
+    [username, forgotPassword]
+  );
+
+  const clearError = useCallback(() => {
+    setError(null);
+  }, []);
+
+  return {
+    username,
+    error,
+    isPending,
+    setUsername,
+    handleUsernameChange,
+    handleSubmit,
+    clearError,
+  };
+}

package/templates/default/hooks/use-login-form.ts

@@ -0,0 +1,102 @@
+/**
+ * Login Form Hook
+ * Manages form state, validation, and submission via useAuth
+ */
+
+"use client";
+
+import { useState, useCallback } from "react";
+import { useAuth } from "@onexapis/core/hooks";
+
+export interface LoginFormData {
+  username: string;
+  password: string;
+}
+
+export interface UseLoginFormReturn {
+  formData: LoginFormData;
+  errors: Record<string, string>;
+  showPassword: boolean;
+  isPending: boolean;
+  handleInputChange: (e: React.ChangeEvent<HTMLInputElement>) => void;
+  handleSubmit: (e: React.FormEvent) => void;
+  toggleShowPassword: () => void;
+  clearError: (field: string) => void;
+}
+
+export function useLoginForm(): UseLoginFormReturn {
+  const [formData, setFormData] = useState<LoginFormData>({
+    username: "",
+    password: "",
+  });
+  const [errors, setErrors] = useState<Record<string, string>>({});
+  const [showPassword, setShowPassword] = useState(false);
+  const [isPending, setIsPending] = useState(false);
+
+  const { login } = useAuth();
+
+  const handleInputChange = useCallback(
+    (e: React.ChangeEvent<HTMLInputElement>) => {
+      const { name, value } = e.target;
+      setFormData((prev) => ({ ...prev, [name]: value }));
+      if (errors[name]) {
+        setErrors((prev) => ({ ...prev, [name]: "" }));
+      }
+    },
+    [errors]
+  );
+
+  const validateForm = useCallback((): boolean => {
+    const newErrors: Record<string, string> = {};
+
+    if (!formData.username) {
+      newErrors.username = "Please enter your username or email";
+    }
+    if (!formData.password) {
+      newErrors.password = "Please enter your password";
+    }
+
+    setErrors(newErrors);
+    return Object.keys(newErrors).length === 0;
+  }, [formData]);
+
+  const handleSubmit = useCallback(
+    async (e: React.FormEvent) => {
+      e.preventDefault();
+      if (!validateForm()) return;
+
+      setIsPending(true);
+      try {
+        await login({
+          username: formData.username,
+          password: formData.password,
+        });
+      } catch (error) {
+        const message = error instanceof Error ? error.message : "Login failed";
+        setErrors({ form: message });
+      } finally {
+        setIsPending(false);
+      }
+    },
+    [validateForm, login, formData]
+  );
+
+  const toggleShowPassword = useCallback(() => {
+    setShowPassword((prev) => !prev);
+  }, []);
+
+  const clearError = useCallback((field: string) => {
+    setErrors((prev) => ({ ...prev, [field]: "" }));
+  }, []);
+
+  return {
+    formData,
+    errors,
+    showPassword,
+    isPending,
+    handleInputChange,
+    handleSubmit,
+    toggleShowPassword,
+    clearError,
+  };
+}

package/templates/default/hooks/use-profile-form.ts

@@ -0,0 +1,255 @@
+/**
+ * Profile Form Hook
+ * Manages profile form state, dirty tracking, and submission via useAuth
+ */
+
+"use client";
+
+import { useState, useEffect, useCallback, useRef } from "react";
+import { useAuth } from "@onexapis/core/hooks";
+
+export interface ProfileFormData {
+  name: string;
+  email: string;
+  phone: string;
+  address: string;
+}
+
+export interface ChangePasswordData {
+  currentPassword: string;
+  newPassword: string;
+  confirmPassword: string;
+}
+
+export interface UseProfileFormReturn {
+  // User state
+  isAuthenticated: boolean;
+  isLoading: boolean;
+
+  // Form state
+  formData: ProfileFormData;
+  handleFieldChange: (field: keyof ProfileFormData, value: string) => void;
+  isDirty: boolean;
+  isSubmitting: boolean;
+  submitError: string | null;
+  handleSubmit: (e?: React.FormEvent) => Promise<void>;
+
+  // Change password
+  passwordData: ChangePasswordData;
+  handlePasswordFieldChange: (
+    field: keyof ChangePasswordData,
+    value: string
+  ) => void;
+  showCurrentPassword: boolean;
+  showNewPassword: boolean;
+  showConfirmPassword: boolean;
+  toggleCurrentPassword: () => void;
+  toggleNewPassword: () => void;
+  toggleConfirmPassword: () => void;
+  passwordErrors: Record<string, string>;
+  isChangingPassword: boolean;
+  showPasswordForm: boolean;
+  setShowPasswordForm: (show: boolean) => void;
+  handlePasswordSubmit: (e?: React.FormEvent) => Promise<void>;
+
+  // Logout
+  handleLogout: () => Promise<void>;
+}
+
+export function useProfileForm(): UseProfileFormReturn {
+  const {
+    user,
+    isAuthenticated,
+    isLoading,
+    updateProfile,
+    changePassword,
+    logout,
+    initialize,
+  } = useAuth();
+
+  const [formData, setFormData] = useState<ProfileFormData>({
+    name: "",
+    email: "",
+    phone: "",
+    address: "",
+  });
+  const [isSubmitting, setIsSubmitting] = useState(false);
+  const [submitError, setSubmitError] = useState<string | null>(null);
+  const initialDataRef = useRef<ProfileFormData | null>(null);
+
+  // Password form
+  const [passwordData, setPasswordData] = useState<ChangePasswordData>({
+    currentPassword: "",
+    newPassword: "",
+    confirmPassword: "",
+  });
+  const [showCurrentPassword, setShowCurrentPassword] = useState(false);
+  const [showNewPassword, setShowNewPassword] = useState(false);
+  const [showConfirmPassword, setShowConfirmPassword] = useState(false);
+  const [passwordErrors, setPasswordErrors] = useState<Record<string, string>>(
+    {}
+  );
+  const [isChangingPassword, setIsChangingPassword] = useState(false);
+  const [showPasswordForm, setShowPasswordForm] = useState(false);
+
+  // Initialize auth on mount
+  useEffect(() => {
+    initialize();
+  }, [initialize]);
+
+  // Populate form from user data
+  useEffect(() => {
+    if (user) {
+      const data: ProfileFormData = {
+        name: user.name || "",
+        email: user.email || "",
+        phone: user.phone_number || "",
+        address: user.address || "",
+      };
+      setFormData(data);
+      initialDataRef.current = data;
+    }
+  }, [user]);
+
+  const handleFieldChange = useCallback(
+    (field: keyof ProfileFormData, value: string) => {
+      setFormData((prev) => ({ ...prev, [field]: value }));
+      setSubmitError(null);
+    },
+    []
+  );
+
+  const isDirty =
+    initialDataRef.current !== null &&
+    (formData.name !== initialDataRef.current.name ||
+      formData.phone !== initialDataRef.current.phone ||
+      formData.address !== initialDataRef.current.address);
+
+  const handleSubmit = useCallback(
+    async (e?: React.FormEvent) => {
+      e?.preventDefault();
+      if (!isDirty) return;
+
+      setIsSubmitting(true);
+      setSubmitError(null);
+      try {
+        await updateProfile({
+          name: formData.name,
+          phone_number: formData.phone,
+          address: formData.address,
+        });
+        // Update initial data ref to new values
+        initialDataRef.current = { ...formData };
+      } catch (error) {
+        const message =
+          error instanceof Error ? error.message : "Failed to update profile";
+        setSubmitError(message);
+      } finally {
+        setIsSubmitting(false);
+      }
+    },
+    [isDirty, formData, updateProfile]
+  );
+
+  // Password handlers
+  const handlePasswordFieldChange = useCallback(
+    (field: keyof ChangePasswordData, value: string) => {
+      setPasswordData((prev) => ({ ...prev, [field]: value }));
+      if (passwordErrors[field]) {
+        setPasswordErrors((prev) => ({ ...prev, [field]: "" }));
+      }
+    },
+    [passwordErrors]
+  );
+
+  const validatePassword = useCallback((): boolean => {
+    const errors: Record<string, string> = {};
+
+    if (!passwordData.currentPassword) {
+      errors.currentPassword = "Please enter your current password";
+    }
+    if (!passwordData.newPassword) {
+      errors.newPassword = "Please enter a new password";
+    } else if (passwordData.newPassword.length < 8) {
+      errors.newPassword = "Password must be at least 8 characters";
+    } else if (
+      !/(?=.*[a-z])(?=.*[A-Z])(?=.*\d)/.test(passwordData.newPassword)
+    ) {
+      errors.newPassword =
+        "Password must contain uppercase, lowercase, and a number";
+    } else if (passwordData.newPassword === passwordData.currentPassword) {
+      errors.newPassword =
+        "New password must be different from current password";
+    }
+    if (!passwordData.confirmPassword) {
+      errors.confirmPassword = "Please confirm your new password";
+    } else if (passwordData.newPassword !== passwordData.confirmPassword) {
+      errors.confirmPassword = "Passwords do not match";
+    }
+
+    setPasswordErrors(errors);
+    return Object.keys(errors).length === 0;
+  }, [passwordData]);
+
+  const handlePasswordSubmit = useCallback(
+    async (e?: React.FormEvent) => {
+      e?.preventDefault();
+      if (!validatePassword()) return;
+
+      setIsChangingPassword(true);
+      try {
+        await changePassword({
+          oldPassword: passwordData.currentPassword,
+          newPassword: passwordData.newPassword,
+        });
+        // Reset form on success
+        setPasswordData({
+          currentPassword: "",
+          newPassword: "",
+          confirmPassword: "",
+        });
+        setShowPasswordForm(false);
+        setPasswordErrors({});
+      } catch (error) {
+        const message =
+          error instanceof Error ? error.message : "Failed to change password";
+        setPasswordErrors({ form: message });
+      } finally {
+        setIsChangingPassword(false);
+      }
+    },
+    [validatePassword, changePassword, passwordData]
+  );
+
+  const handleLogout = useCallback(async () => {
+    await logout();
+    if (typeof window !== "undefined") {
+      window.location.href = "/login";
+    }
+  }, [logout]);
+
+  return {
+    isAuthenticated,
+    isLoading,
+    formData,
+    handleFieldChange,
+    isDirty,
+    isSubmitting,
+    submitError,
+    handleSubmit,
+    passwordData,
+    handlePasswordFieldChange,
+    showCurrentPassword,
+    showNewPassword,
+    showConfirmPassword,
+    toggleCurrentPassword: () => setShowCurrentPassword((p) => !p),
+    toggleNewPassword: () => setShowNewPassword((p) => !p),
+    toggleConfirmPassword: () => setShowConfirmPassword((p) => !p),
+    passwordErrors,
+    isChangingPassword,
+    showPasswordForm,
+    setShowPasswordForm,
+    handlePasswordSubmit,
+    handleLogout,
+  };
+}