@onexapis/cli 1.1.36 → 1.1.37

package/dist/preview/preview-app.tsx

@@ -455,6 +455,14 @@ function PreviewApp() {
   >("disconnected");
   const [error, setError] = useState<string | null>(null);
   const wsRef = useRef<WebSocket | null>(null);
+  const [isEditing, setIsEditing] = useState(() => {
+    if (typeof window !== "undefined") {
+      return (
+        new URLSearchParams(window.location.search).get("editing") === "true"
+      );
+    }
+    return false;
+  });
 
   // Load theme bundle
   const loadTheme = useCallback(async (timestamp?: number) => {
@@ -701,7 +709,7 @@ function PreviewApp() {
         section={section}
         schema={schema}
         template={template}
-        isEditing={false}
+        isEditing={isEditing}
         data={sectionData}
       />
     );
@@ -712,16 +720,16 @@ function PreviewApp() {
       {/* Inject theme CSS variables (Gap 2) */}
       {themeCSS && <style dangerouslySetInnerHTML={{ __html: themeCSS }} />}
 
-      {/* Header (Gap 1) */}
-      {headerSections.length > 0 && (
+      {/* Header — hidden if page config sets hideHeader: true */}
+      {headerSections.length > 0 && !currentPage.config?.hideHeader && (
         <header>{headerSections.map(renderSection)}</header>
       )}
 
       {/* Page sections */}
       <main>{pageSections.map(renderSection)}</main>
 
-      {/* Footer (Gap 1) */}
-      {footerSections.length > 0 && (
+      {/* Footer — hidden if page config sets hideFooter: true */}
+      {footerSections.length > 0 && !currentPage.config?.hideFooter && (
         <footer>{footerSections.map(renderSection)}</footer>
       )}
     </>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onexapis/cli",
-  "version": "1.1.36",
+  "version": "1.1.37",
   "description": "CLI tool for OneX theme development - scaffolds themes using @onexapis/core",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",

package/templates/default/AUTH_AND_PROFILE.md

@@ -0,0 +1,167 @@
+# Authentication & Profile — Default Theme
+
+This document covers the built-in authentication and profile sections included in the default theme template.
+
+## Overview
+
+When you initialize a theme with `onexthm init`, it comes with 5 auth/profile sections and their corresponding hooks ready to use:
+
+| Section              | Path               | Description                                  |
+| -------------------- | ------------------ | -------------------------------------------- |
+| Auth Login           | `/login`           | Username/email + password sign-in            |
+| Auth Register        | `/register`        | Email, username, password, confirm password  |
+| Auth Forgot Password | `/forgot-password` | Request verification code via email/username |
+| Auth Verify Code     | `/verify-code`     | 6-digit OTP input with resend + countdown    |
+| Profile              | `/profile`         | View/edit profile + change password          |
+
+## Architecture
+
+```
+Theme Section (UI only)
+  └── Theme Hook (form state, validation)
+        └── useAuth() from @onexapis/core/hooks (Zustand store)
+              └── AuthService (API calls)
+                    └── ApiClient (HTTP client with token management)
+```
+
+### Hooks
+
+All hooks live in `hooks/` and use `useAuth` from `@onexapis/core/hooks`:
+
+| Hook                    | Uses                                                          | Manages                                              |
+| ----------------------- | ------------------------------------------------------------- | ---------------------------------------------------- |
+| `useLoginForm`          | `useAuth().login()`                                           | Username, password, show/hide toggle, validation     |
+| `useRegisterForm`       | `useAuth().signup()`                                          | Email, username, password, confirm, validation       |
+| `useForgotPasswordForm` | `useAuth().forgotPassword()`                                  | Username/email input, validation                     |
+| `useVerifyCodeForm`     | `useAuth().verifyCode()`, `verifyCodeReset()`, `resendCode()` | 6-digit OTP, auto-focus, paste, countdown            |
+| `useProfileForm`        | `useAuth().updateProfile()`, `changePassword()`, `logout()`   | Profile fields, dirty tracking, change password form |
+
+### API Endpoints
+
+The `AuthService` in `@onexapis/core` handles all API calls:
+
+| Action              | Method | Endpoint                            |
+| ------------------- | ------ | ----------------------------------- |
+| Login               | POST   | `/auth/login`                       |
+| Register            | POST   | `/auth/register`                    |
+| Forgot Password     | POST   | `/auth/forgot`                      |
+| Verify Code         | POST   | `/auth/confirm`                     |
+| Verify Code (reset) | POST   | `/auth/confirm_reset_password_code` |
+| Resend Code         | POST   | `/auth/resend_code`                 |
+| Reset Password      | POST   | `/auth/new_password`                |
+| Change Password     | POST   | `/auth/change_password`             |
+| Get User Info       | GET    | `/auth/user_info`                   |
+| Update Profile      | POST   | `/auth/user_info`                   |
+
+### Token Handling
+
+- **IdToken** → `Authorization: Bearer {IdToken}` header
+- **AccessToken** → `?access_token={AccessToken}` query parameter
+- **Tokens stored** in `localStorage` under key `auth_tokens`
+- **Signup** auto-injects `company_id` (from `initializeOnex()` config) and `is_customer: true`
+
+## Editable Settings
+
+All sections expose these layout settings via the editor sidebar:
+
+| Setting            | Type   | Default   | Description                          |
+| ------------------ | ------ | --------- | ------------------------------------ |
+| `backgroundColor`  | color  | `#F9FAFB` | Page background                      |
+| `cardBackground`   | color  | `#FFFFFF` | Card/form container background       |
+| `primaryColor`     | color  | `#2563EB` | Buttons and links                    |
+| `textColor`        | color  | `#111827` | Heading text color                   |
+| `cardBorderRadius` | select | `2xl`     | Card corner rounding (lg/xl/2xl/3xl) |
+
+Plus all text labels, placeholders, button text, and URLs are customizable per section.
+
+## Auth Flow
+
+```
+Register → Verify Code → Login → Profile
+                ↑                    │
+Forgot Password → Verify Code (reset) → Reset Password
+```
+
+1. **Register**: User fills email, username, password → `signup()` → redirects to `/verify-code?username=...`
+2. **Verify Code**: User enters 6-digit OTP → `verifyCode()` → redirects to `/login`
+3. **Login**: User signs in → `login()` → tokens stored → redirects to `/`
+4. **Forgot Password**: User enters email → `forgotPassword()` → redirects to `/verify-code?mode=reset&username=...`
+5. **Verify Code (reset)**: OTP → `verifyCodeReset()` → returns session → redirects to `/reset-password?session=...`
+6. **Profile**: View/edit name, phone, address → `updateProfile()`. Change password → `changePassword()`
+
+## Configuration
+
+### Required Environment Variables
+
+```env
+NEXT_PUBLIC_API_URL=https://api-dev.onexeos.com
+NEXT_PUBLIC_COMPANY_ID=your-company-id
+```
+
+These are read by `initializeOnex()` which creates the `AuthService` and registers it with the `useAuth` Zustand store.
+
+## Testing Locally
+
+### Preview mode (UI only)
+
+```bash
+onexthm dev
+# Visit http://localhost:3456/login
+```
+
+### Preview with editing mode
+
+```bash
+onexthm dev
+# Visit http://localhost:3456/login?editing=true
+```
+
+### Preview with real API (requires .env)
+
+Create `.env` in your theme directory:
+
+```env
+NEXT_PUBLIC_API_URL=https://api-dev.onexeos.com
+NEXT_PUBLIC_COMPANY_ID=your-company-id
+```
+
+Then run `onexthm dev` — login/register/verify will make real API calls.
+
+## File Structure
+
+```
+hooks/
+  index.ts
+  use-login-form.ts
+  use-register-form.ts
+  use-forgot-password-form.ts
+  use-verify-code-form.ts
+  use-profile-form.ts
+sections/
+  auth-login/
+    auth-login-default.tsx    # Login form UI
+    auth-login.schema.ts      # Editable settings
+    index.ts
+  auth-register/
+    auth-register-default.tsx
+    auth-register.schema.ts
+    index.ts
+  auth-forgot-password/
+    auth-forgot-password-default.tsx
+    auth-forgot-password.schema.ts
+    index.ts
+  auth-verify-code/
+    auth-verify-code-default.tsx
+    auth-verify-code.schema.ts
+    index.ts
+  profile/
+    profile-default.tsx
+    profile.schema.ts
+    index.ts
+pages/
+  login.ts
+  register.ts
+  forgot-password.ts
+  verify-code.ts
+  profile.ts
+```

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/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,
+  };
+}