diff --git a/ui-kit/react/_docs-guidelines-v6/getting-started.md b/ui-kit/react/_docs-guidelines-v6/getting-started.md new file mode 100644 index 00000000..e3531157 --- /dev/null +++ b/ui-kit/react/_docs-guidelines-v6/getting-started.md @@ -0,0 +1,178 @@ +# React UI Kit v6 Documentation Guidelines (Getting Started pages) + +Use this template for framework setup pages like: + +- `ui-kit/react/react-js-integration.mdx` (React) +- `ui-kit/react/next-js-integration.mdx` (Next.js) +- `ui-kit/react/react-router-integration.mdx` (React Router) +- `ui-kit/react/astro-integration.mdx` (Astro) + +## Goal of a Getting Started page + +By the end, the reader should have: + +1. A new project created for the target framework +2. `@cometchat/chat-uikit-react` installed +3. UI Kit initialized (`CometChatUIKit.init(...)`) +4. A user logged in (Auth Key for POC or Auth Token for production) +5. A working screen that links to one of the chat experiences (Conversation + Messages, One-to-One, Tab-based) + +## Required sections (in this order) + +### 1) Intro (2–4 sentences) + +- What the UI Kit is +- What the reader will build on this page +- A link to the **framework-specific** chat experience pages they can follow next + +### 2) Prerequisites + +Must include: + +- CometChat app created in Dashboard +- Credentials list: App ID, Region, Auth Key (optional), Auth Token (recommended) +- Runtime requirements: Node.js + package manager +- Framework requirements: + - React: Vite or CRA + - Next.js: App Router vs Pages Router (state which is used) + - React Router: whether SSR is enabled by default in the chosen template + - Astro: whether React is used via integration + hydration mode + +### 3) Install + +Must include: + +- `npm` + `yarn` tabs (or `pnpm` if the ecosystem expects it) +- A single canonical package name: `@cometchat/chat-uikit-react` +- If the page requires additional packages (Calls SDK, etc.), include them here and explain why + +### 4) Import styles (theming baseline) + +The page must say (explicitly) that UI Kit styles come from the CSS variables file and where to import it: + +- Global import option (recommended) +- If framework has constraints (Next.js global CSS import rules), document the correct location + +Also include a **failure symptom**: “If you skip this step, the UI may render unstyled / broken.” + +### 5) Initialize the UI Kit (required) + +Rules: + +- Show a full snippet with: + - `CometChatUIKit` + - `UIKitSettingsBuilder` + - `setAppId`, `setRegion` + - `setAuthKey` (only when demonstrating Auth Key flow) + - `subscribePresenceForAllUsers` (or whichever presence setting is recommended) + - A `.catch(...)` that prints errors +- Add a `` that **Auth Key is POC/dev only**, and link to Auth Token login +- State clearly: initialize **exactly once** on app start + +### 6) Authenticate a user + +Include both flows: + +- **POC**: `CometChatUIKit.login(UID)` +- **Production**: `CometChatUIKit.loginWithAuthToken(AUTH_TOKEN)` (and explain server-side generation/storage at a high level) + +Also include: + +- How to avoid double-login by calling `getLoggedinUser()` first +- Example test UIDs (if they exist) or how to create a user + +### 7) Verify it works + +Include the exact commands and expected output: + +- Start dev server (`npm run dev`, `npm start`, etc.) +- What the reader should see (even one sentence is enough) +- A “common failure” list (wrong region, not initialized, missing CSS import) + +### 8) Next steps + +Link to: + +- `/ui-kit/react/react-conversation` +- `/ui-kit/react/react-one-to-one-chat` +- `/ui-kit/react/react-tab-based-chat` +- `/ui-kit/react/theme` +- `/ui-kit/react/methods` + +Framework variants should link to their equivalents (e.g., `next-conversation`, `react-router-conversation`, `astro-conversation`). + +## Framework-specific guidance (must call out) + +### Next.js + +- UI Kit uses browser APIs; ensure all UI Kit usage is **client-side**. +- If using App Router, say where `use client` is required (e.g., the component that calls init/login and renders UI Kit components). +- Mention SSR pitfalls succinctly: “Don’t run `CometChatUIKit.init` on the server.” + +### React Router / SSR templates + +- If the recommended starter renders on the server by default, add an explicit “Disable SSR for the chat route” section. +- Explain why in one paragraph (window/document/WebSockets usage). + +### Astro + +- State the chosen hydration directive (example: `client:only="react"` vs `client:load`) and why. +- Keep steps minimal and specific. + +## Code example rules + +- Prefer **TypeScript first**, then JavaScript if it adds value. +- Every multi-file example must use `` with tab titles that are **filenames**. +- Avoid repeating the same 100+ lines across framework pages—link to the base React page and document only the deltas. + +## Recommended Getting Started page template (MDX skeleton) + +```mdx +--- +title: "Getting Started With CometChat React UI Kit" +sidebarTitle: "Integration" +--- + + + +*** + +## Prerequisites + + +*** + +## Step 1: Create a project + + +*** + +## Step 2: Install dependencies + + +*** + +## Step 3: Import UI Kit styles + + +*** + +## Step 4: Initialize CometChat UI Kit + + +*** + +## Step 5: Login a user + + +*** + +## Verify + + +*** + +## Next steps + +``` + diff --git a/ui-kit/react/_docs-guidelines-v6/integration.md b/ui-kit/react/_docs-guidelines-v6/integration.md new file mode 100644 index 00000000..b9aaa486 --- /dev/null +++ b/ui-kit/react/_docs-guidelines-v6/integration.md @@ -0,0 +1,155 @@ +# React UI Kit v6 Documentation Guidelines (Integration pages) + +Use this structure for “build a chat experience” pages like: + +- `ui-kit/react/react-conversation.mdx` +- `ui-kit/react/react-one-to-one-chat.mdx` +- `ui-kit/react/react-tab-based-chat.mdx` +- and their framework variants (`next-*`, `react-router-*`, `astro-*`) + +## Goal of an Integration page + +The reader starts from a project that already completed Getting Started (init + login), and ends with a **specific UI Kit layout working end-to-end**. + +Each Integration page must answer four questions: + +1. What experience are we building and when should I choose it? +2. What UI Kit components are involved? +3. What files do I create/change (exact paths)? +4. What do I run and what should I see? + +## Required sections (in this order) + +### 1) Intro + “Try it” link + +Include: + +- 2–3 sentences describing the layout + best-fit use cases +- A single CodeSandbox/live demo link (if available) +- A one-line note telling the reader what to change (credentials) + +### 2) UI overview (visual) + +- Screenshot inside `` +- Short explanation of the major regions (sidebar, header, message list, composer, etc.) + +### 3) Prerequisites (keep it short) + +- Link back to the correct Getting Started page for the framework (v6) +- Mention required UI Kit styles import if the integration relies on them +- Mention any additional SDKs needed (Calls SDK for call pages, etc.) + +### 4) Step-by-step implementation + +Rules: + +- Use numbered steps (`Step 1`, `Step 2`, …) +- Every step has: + - a short “what/why” + - explicit file tree or file paths + - code blocks labeled with filenames +- Prefer small, composable files: + - `src/components/ChatLayout/...` + - `src/routes/chat/...` + - `src/styles/cometchat.css` + +### 5) Verify + +- Commands to run +- What should render +- 3–6 common issues and their fixes (init/login missing, unstyled UI, SSR crashes, invalid region) + +### 6) Next steps + +Link to relevant follow-ons, typically: + +- Theming: `/ui-kit/react/theme` +- Component reference: `/ui-kit/react/components-overview` +- Feature pages: `/ui-kit/react/core-features`, `/ui-kit/react/extensions` +- Guides: `/ui-kit/react/guide-overview` + +## Implementation guidance (what to standardize) + +### Prefer stable, explicit state flow + +Integration pages often need state for: + +- Selected conversation/user/group +- Route params (if deep-linking) +- Logged-in user session + +Guideline: + +- Keep state in one place (a parent layout component), then pass to UI Kit components via props. +- Avoid patterns that re-trigger effects unnecessarily (e.g., `useEffect(..., [loggedInUser])` when you set `loggedInUser` inside the effect). + +### SSR/CSR notes must be correct + +- React (Vite/CRA): no SSR section needed. +- Next.js / React Router SSR templates / Astro: explicitly call out client-only rendering requirements. +- If you add a “Disable SSR” step, state: + - where it applies (which file/route) + - why it is needed (browser APIs) + +### Styling guidance + +- Keep CSS overrides minimal and purposeful. +- Prefer theming via CSS variables over deep selector overrides. +- If you must include a long CSS file: + - add a short list of “what this CSS changes” + - isolate overrides under a wrapper class to avoid app-wide collisions + +## Code example rules + +- Use v6 package imports (`@cometchat/chat-uikit-react`). +- Ensure examples either: + - assume init/login is already done (and say so), or + - include a short “init/login snippet” and clearly mark it as shared setup. +- When you show multi-file implementations, keep the file list small and add a file tree. + +## Recommended Integration page template (MDX skeleton) + +```mdx +--- +title: "Building " +sidebarTitle: "