@conexus-x/next-view 1.0.3 → 1.0.4

package/app/dev/AddBoardForm.tsx

@@ -0,0 +1,44 @@
+"use client";
+
+import { useActionState } from "react";
+
+import { createBoard, type CreateBoardState } from "./actions";
+
+const initialState: CreateBoardState = { error: null };
+
+/**
+ * Add a board to the pinned workspace, without leaving this page.
+ *
+ * `useActionState` gives the pending state and the returned error for free —
+ * the action itself does the actual POST, entirely on the server (see
+ * actions.ts). This form never sees the API key.
+ */
+export default function AddBoardForm({ workspaceId }: { workspaceId: string }) {
+    const [state, formAction, pending] = useActionState(createBoard, initialState);
+
+    return (
+        <form action={formAction} className="mb-4 flex items-center gap-2">
+            <input type="hidden" name="workspaceId" value={workspaceId} />
+
+            <input
+                name="name"
+                placeholder="New board name"
+                required
+                disabled={pending}
+                className="min-w-0 flex-1 rounded-lg border border-line bg-card px-3 py-1.5 text-[13px] outline-none transition placeholder:text-muted focus:border-accent disabled:opacity-60"
+            />
+
+            <button
+                type="submit"
+                disabled={pending}
+                className="shrink-0 rounded-lg bg-accent px-3 py-1.5 text-[13px] font-medium text-white transition hover:bg-accent-hover disabled:cursor-not-allowed disabled:opacity-60"
+            >
+                {pending ? "Adding…" : "Add board"}
+            </button>
+
+            {state.error ? (
+                <span className="text-[12px] text-danger">{state.error}</span>
+            ) : null}
+        </form>
+    );
+}

package/app/dev/CopyId.tsx

@@ -0,0 +1,30 @@
+"use client";
+
+import { useState } from "react";
+
+/**
+ * Copies a workspace or board id.
+ *
+ * The one piece of this page that has to run in the browser — clipboard access
+ * has no server-side equivalent — so it is its own tiny client component rather
+ * than turning the whole page client-side and losing the guarantee that the
+ * API key never ships to the browser.
+ */
+export default function CopyId({ value }: { value: string }) {
+    const [copied, setCopied] = useState(false);
+
+    return (
+        <button
+            type="button"
+            onClick={async () => {
+                await navigator.clipboard.writeText(value);
+                setCopied(true);
+                setTimeout(() => setCopied(false), 1500);
+            }}
+            title={copied ? "Copied" : `Copy ${value}`}
+            className="shrink-0 rounded-md border border-line px-2 py-0.5 font-mono text-[11px] text-muted transition hover:border-accent hover:text-accent"
+        >
+            {copied ? "Copied" : value}
+        </button>
+    );
+}

package/app/dev/actions.ts

@@ -0,0 +1,73 @@
+"use server";
+
+/**
+ * The one write the developer page needs: creating a board.
+ *
+ * A SERVER ACTION, for the same reason page.tsx is a Server Component — the
+ * function body, including every reference to `process.env.API_KEY`, stays on
+ * the server. Next compiles the client side down to an action id plus a
+ * dispatcher; the key it captures is never serialised into that reference.
+ * See node_modules/next/dist/docs/01-app/02-guides/server-actions.md
+ * "Closure variable encryption" for the mechanism this relies on.
+ *
+ * Deliberately the ONLY write on this page. Renaming or deleting a board from
+ * a debug screen is a bigger blast radius than a debug screen should carry —
+ * creating one is reversible in one click from Conexus X itself.
+ */
+
+import { revalidatePath } from "next/cache";
+
+const PLACEHOLDER = "Conexus_x_api_key";
+
+export interface CreateBoardState {
+    error: string | null;
+}
+
+export async function createBoard(
+    _previous: CreateBoardState,
+    formData: FormData
+): Promise<CreateBoardState> {
+    const apiKey = process.env.API_KEY;
+    const workspaceId = String(formData.get("workspaceId") ?? "").trim();
+    const name = String(formData.get("name") ?? "").trim();
+
+    if (!apiKey || apiKey === PLACEHOLDER) {
+        return { error: "API_KEY in .env is missing or still the placeholder." };
+    }
+
+    if (!workspaceId) {
+        return { error: "No workspace is pinned. Set WORKSPACE_ID in .env first." };
+    }
+
+    if (!name) {
+        return { error: "Give the board a name." };
+    }
+
+    const apiUrl = (process.env.CONEXUS_API_URL ?? "http://localhost:4040/api").replace(/\/$/, "");
+
+    try {
+        const response = await fetch(`${apiUrl}/modules/${workspaceId}`, {
+            method: "POST",
+            headers: {
+                "x-api-key": apiKey,
+                "Content-Type": "application/json"
+            },
+            body: JSON.stringify({ name })
+        });
+
+        if (!response.ok) {
+            const detail = await response.text();
+            return { error: `The API answered ${response.status}: ${detail.slice(0, 200)}` };
+        }
+    } catch (error) {
+        return {
+            error: `Could not reach the API — ${error instanceof Error ? error.message : String(error)}`
+        };
+    }
+
+    // Re-renders /dev with the fresh board list, in the SAME response as this
+    // action — the developer sees the new board without a manual reload.
+    revalidatePath("/dev");
+
+    return { error: null };
+}

package/app/dev/page.tsx

@@ -1,5 +1,8 @@
 import { notFound } from "next/navigation";
 
+import AddBoardForm from "./AddBoardForm";
+import CopyId from "./CopyId";
+
 /**
  * DEVELOPER MODE — http://localhost:5173/dev
  *
@@ -188,11 +191,12 @@ export default async function DevPage() {
                                         <div className="truncate font-medium">
                                             {membership.workspace?.name ?? "Untitled workspace"}
                                         </div>
-                                        <div className="mt-0.5 font-mono text-[12px] text-muted">
-                                            {membership.workspace?._id}
-                                        </div>
                                     </div>
 
+                                    {membership.workspace?._id ? (
+                                        <CopyId value={membership.workspace._id} />
+                                    ) : null}
+
                                     {membership.role ? (
                                         <span className="shrink-0 rounded-md border border-line px-2 py-0.5 text-[12px] text-muted">
                                             {membership.role}
@@ -214,11 +218,10 @@ export default async function DevPage() {
                             <div className="truncate text-[15px] font-semibold">
                                 {state.workspace.name ?? "Untitled workspace"}
                             </div>
-                            <div className="mt-0.5 font-mono text-[12px] text-muted">
-                                {state.workspace._id}
-                            </div>
                         </div>
 
+                        <CopyId value={state.workspace._id} />
+
                         {state.role ? (
                             <span className="shrink-0 rounded-md border border-line px-2 py-0.5 text-[12px] text-muted">
                                 {state.role}
@@ -226,6 +229,8 @@ export default async function DevPage() {
                         ) : null}
                     </div>
 
+                    <AddBoardForm workspaceId={state.workspace._id} />
+
                     {state.boards.length === 0 ? (
                         <p className="text-[13px] text-muted">
                             This workspace has no boards yet. Create one in Conexus X and
@@ -242,11 +247,11 @@ export default async function DevPage() {
                                         <div className="truncate font-medium">
                                             {board.name ?? "Untitled board"}
                                         </div>
-                                        <div className="mt-0.5 font-mono text-[12px] text-muted">
-                                            {board._id}
-                                        </div>
                                     </div>
 
+.0000000000000000000000000000000000000000000000000000000000000000006+++++++++++++++++++++++++++++++++++++++++++++++++++++++++4
+                                    <CopyId value={board._id} />
+
                                     {board.visibility ? (
                                         <span className="shrink-0 rounded-md border border-line px-2 py-0.5 text-[12px] text-muted">
                                             {board.visibility}

package/app/page.tsx

@@ -3,13 +3,20 @@
 /**
  * The starter view.
  *
- * Lists the records in whichever collection the person is looking at, lets them
- * tick one complete, and stays live while colleagues edit the same board. It is
- * the smallest thing that exercises every part of the SDK worth knowing:
- * context, a scoped read, a scoped write, host chrome, and realtime.
+ * It renders WHATEVER THE HOST GAVE IT, which is the single most important
+ * thing to copy from this file:
  *
- * Note what is NOT here: no fetch, no API base URL, no token, no socket. The
- * host owns all four, which is why this file is short.
+ *   mounted on a workspace  -> the boards in that workspace
+ *   mounted on a board      -> the records in the collection in view
+ *
+ * The first version only ever listed records, so a view mounted at workspace
+ * level — which is what the CRM preview does — sat there saying "open a
+ * collection" and looked broken. A view must read `context` and show what is
+ * actually there.
+ *
+ * Note what is NOT here: no fetch, no API base URL, no token, no socket, and no
+ * workspace id of its own. The host owns all of it and hands over context with
+ * the permissions of whoever is looking, which is why this file is short.
  *
  * Styling is Tailwind, already configured — see app/globals.css. The colour
  * names (`bg-card`, `text-muted`, `border-line`) flip with the board's theme on
@@ -20,6 +27,7 @@ import {
     useAutoResize,
     useCommands,
     useConnection,
+    useModules,
     useRecords,
     useScope,
     useSettings,
@@ -34,6 +42,10 @@ interface ViewSettings {
     showCompleted?: boolean;
 }
 
+const Skeleton = () => (
+    <div className="h-3.5 w-full animate-pulse rounded bg-line" />
+);
+
 export default function View() {
     const { status, error } = useConnection();
     const context = useViewContext();
@@ -49,12 +61,20 @@ export default function View() {
      * settings receives an empty object.
      */
     const settings = useSettings<ViewSettings>();
-    const title = settings.title ?? "Records";
     const showCompleted = settings.showCompleted ?? true;
 
+    /**
+     * Both queries are declared, and only the applicable one runs.
+     *
+     * Each is disabled when its id is missing, so the board list costs nothing
+     * on a board-level mount and the record list costs nothing above one. Hooks
+     * cannot be called conditionally; queries can be skipped.
+     */
+    const boards = useModules(context?.collectionId ? undefined : context?.workspaceId);
+
     const {
         data: records,
-        loading,
+        loading: recordsLoading,
         error: recordsError,
         refresh
     } = useRecords(context?.collectionId);
@@ -86,6 +106,10 @@ export default function View() {
         );
     }
 
+    const onBoard = Boolean(context?.collectionId);
+    const title = settings.title ?? (onBoard ? "Records" : "Boards");
+    const failure = onBoard ? recordsError : boards.error;
+
     return (
         <main className="p-4">
             <ThemeSync theme={context?.theme ?? "light"} />
@@ -97,47 +121,76 @@ export default function View() {
                 </span>
             </header>
 
-            {!context?.collectionId ? (
-                <p className="text-[13px] text-muted">Open a collection to see its records.</p>
-            ) : recordsError ? (
+            {failure ? (
                 <div className="rounded-lg border border-danger bg-danger-soft px-3.5 py-3 text-danger">
-                    {recordsError.code === "scope_denied"
-                        ? "This app was not granted permission to read records."
-                        : recordsError.message}
+                    {failure.code === "scope_denied"
+                        ? `This app was not granted permission to read ${onBoard ? "records" : "boards"}.`
+                        : failure.message}
                 </div>
-            ) : loading && !records ? (
-                <div className="h-3.5 w-full animate-pulse rounded bg-line" />
+            ) : onBoard ? (
+                /* ---- mounted on a board: the records in view ---- */
+                recordsLoading && !records ? (
+                    <Skeleton />
+                ) : records?.length === 0 ? (
+                    <p className="text-[13px] text-muted">
+                        No records in this collection yet.
+                    </p>
+                ) : (
+                    <ul>
+                        {(records ?? [])
+                            .filter((record) => showCompleted || !record.isCompleted)
+                            .map((record) => (
+                                <RecordRow
+                                    key={record._id}
+                                    record={record}
+                                    canWrite={canWrite}
+                                    onOpen={() =>
+                                        commands
+                                            .openRecord(record._id)
+                                            .catch(() =>
+                                                commands.notice(
+                                                    "This board cannot open records from a view.",
+                                                    "info"
+                                                )
+                                            )
+                                    }
+                                    onError={(message) => {
+                                        void commands.notice(message, "error");
+                                        refresh();
+                                    }}
+                                />
+                            ))}
+                    </ul>
+                )
+            ) : /* ---- mounted on a workspace: the boards in it ---- */
+            boards.loading && !boards.data ? (
+                <Skeleton />
+            ) : boards.data?.length === 0 ? (
+                <p className="text-[13px] text-muted">
+                    This workspace has no boards yet.
+                </p>
             ) : (
                 <ul>
-                    {(records ?? [])
-                        .filter((record) => showCompleted || !record.isCompleted)
-                        .map((record) => (
-                            <RecordRow
-                                key={record._id}
-                                record={record}
-                                canWrite={canWrite}
-                                onOpen={() =>
-                                    commands
-                                        .openRecord(record._id)
-                                        .catch(() =>
-                                            commands.notice(
-                                                "This board cannot open records from a view.",
-                                                "info"
-                                            )
-                                        )
-                                }
-                                onError={(message) => {
-                                    void commands.notice(message, "error");
-                                    refresh();
-                                }}
-                            />
-                        ))}
+                    {(boards.data ?? []).map((board) => (
+                        <li
+                            key={board._id}
+                            className="flex items-center gap-2.5 border-b border-line py-2 last:border-b-0"
+                        >
+                            <span className="min-w-0 flex-1 truncate">{board.name}</span>
+
+                            {board.visibility && board.visibility !== "workspace" ? (
+                                <span className="shrink-0 rounded-md border border-line px-1.5 py-0.5 text-[11px] text-muted">
+                                    {board.visibility}
+                                </span>
+                            ) : null}
+
+                            <span className="shrink-0 text-[13px] text-muted">
+                                {board.totalRecords ?? 0} records
+                            </span>
+                        </li>
+                    ))}
                 </ul>
             )}
-
-            {records?.length === 0 && context?.collectionId ? (
-                <p className="text-[13px] text-muted">No records in this collection yet.</p>
-            ) : null}
         </main>
     );
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@conexus-x/next-view",
-    "version": "1.0.3",
+    "version": "1.0.4",
     "private": false,
     "description": "Custom view for Conexus X — Next.js starter, wired to @conexus-x/sdk.",
     "scripts": {
@@ -11,7 +11,7 @@
         "tunnel": "npx -y cloudflared tunnel --url http://localhost:5173"
     },
     "dependencies": {
-        "@conexus-x/sdk": "^0.1.0",
+        "@conexus-x/sdk": "^0.1.2",
         "next": "16.2.10",
         "react": "19.2.4",
         "react-dom": "19.2.4"