@conexus-x/next-view 1.0.0

package/.gitignore

@@ -0,0 +1,7 @@
+node_modules/
+.next/
+out/
+next-env.d.ts
+*.tsbuildinfo
+.env*.local
+.vercel

package/README.md

@@ -0,0 +1,107 @@
+# Conexus View
+
+A starter **custom view** for Conexus X: Next.js 16 + React 19, wired to `@conexus-x/sdk`.
+
+Copy this folder, rename it, and you have an app. It lists the records in whichever collection the person is looking at, completes them in place, and stays live while colleagues edit the same board.
+
+```bash
+npm install
+npm run dev        # http://localhost:5173
+```
+
+Running it directly in a browser tab shows **"Not connected to Conexus X"** — that is correct. A view is a page that expects to be framed by the board, which is where its context and its data come from.
+
+### Working against an unpublished SDK
+
+`npm install` resolves `@conexus-x/sdk` from the registry. If you are developing
+the SDK at the same time, link it instead of adding a path to `package.json` —
+a `file:` dependency committed here would break for everyone else:
+
+```bash
+cd ../conexus-x-sdk && npm run build && npm link
+cd -                 && npm link @conexus-x/sdk
+```
+
+`npm unlink @conexus-x/sdk && npm install` puts it back on the published version.
+Nothing in this repo records the link, which is the point.
+
+
+## Tailwind is already set up
+
+Tailwind v4 is installed and configured. There is no `tailwind.config.js` to
+create, no CLI to run, no PostCSS file to write — v4 does not use one. Add
+classes to your markup and they work.
+
+The theme lives in `app/globals.css`, as a small set of semantic colours:
+
+| Utility | Meaning |
+| --- | --- |
+| `bg-bg` / `bg-card` | page and surface |
+| `text-fg` / `text-muted` | body and secondary text |
+| `border-line` | dividers and borders |
+| `text-accent` / `bg-accent-soft` | the interactive colour |
+| `text-danger` / `bg-danger-soft` | errors |
+
+**These flip with the board's theme on their own**, so you almost never write
+`dark:`. The values swap under `[data-theme="dark"]`, which `ThemeSync` sets
+from the host — `bg-card text-fg` is already correct in both themes.
+
+A `dark:` variant is wired up for the cases where a whole utility has to change
+rather than a colour. It reads the host's `data-theme`, **not**
+`prefers-color-scheme`: someone may run Conexus X in dark while their OS is in
+light, and a view that follows the OS looks like a hole cut in the page.
+
+To change a colour, edit the two blocks at the top of `app/globals.css`. To add one, add it
+in both blocks and give it a name in `@theme inline`.
+
+## What is where
+
+| File | What it shows you |
+| --- | --- |
+| [app/page.tsx](app/page.tsx) | The whole view: connection state, context, a scoped read, host chrome |
+| [components/RecordRow.tsx](components/RecordRow.tsx) | A scoped write, and why it does not update local state on success |
+| [components/ThemeSync.tsx](components/ThemeSync.tsx) | Following the board theme without a flash of the wrong one |
+| [conexus.manifest.json](conexus.manifest.json) | What the app declares — views, settings, scopes, and why it wants them |
+| [next.config.ts](next.config.ts) | `frame-ancestors`, the header that decides whether this can be embedded at all |
+
+## The whole SDK surface, in one screen
+
+```tsx
+const { status, error } = useConnection();     // connecting | ready | error
+const context  = useViewContext();             // board, collection, user, theme, environment
+const settings = useSettings<ViewSettings>();  // what the person configured for this placement
+const canWrite = useScope("records:write");    // feature-detect, never assume
+const commands = useCommands();                // notice, openRecord, confirm, navigate, copy
+
+const { data, loading, error, refresh } = useRecords(context?.collectionId);
+
+useAutoResize();                               // grow the frame to fit
+```
+
+`useRecords` refetches on its own when the board changes — a colleague editing a cell, an automation moving a row, your own write coming back. There is no socket in this app and no polling; the host forwards what belongs to this board and the hook redraws.
+
+For anything the hooks do not cover:
+
+```tsx
+const cx = useConexus();
+await cx.api.values.forRecord(recordId);
+await cx.request({ method: "GET", path: "/columns/" + context.moduleId });
+```
+
+## Notice what is missing
+
+No `fetch` of the CRM API. No base URL. No token. No socket. The host owns all four and proxies every call with the signed-in user's own credentials, gated by the scopes your manifest asked for and an admin approved. That is why this app is a few hundred lines.
+
+## Deploying
+
+Any static or Node host works. On Vercel:
+
+```bash
+vercel --prod
+```
+
+Then set `entry` in `conexus.manifest.json` to the deployed URL, and set `CONEXUS_ORIGINS` on the deployment to the Conexus X origins allowed to frame you (comma-separated). Getting `frame-ancestors` wrong is the most common reason a working view renders as a blank rectangle.
+
+## Settings
+
+Fields declared in the manifest are rendered by the host, stored per placement, and delivered to `useSettings()`. Give every field a default in your code as well — a view mounted before anyone opened its settings pane receives an empty object.

package/app/globals.css

@@ -0,0 +1,92 @@
+@import "tailwindcss";
+
+/**
+ * TAILWIND IS ALREADY SET UP. There is nothing for you to configure.
+ *
+ * Tailwind v4 has no `tailwind.config.js` — the theme lives here, in CSS. The
+ * only other piece is postcss.config.mjs, which is three lines and already
+ * written. Add classes to your markup and they work.
+ */
+
+/**
+ * DARK MODE FOLLOWS THE BOARD, NOT THE OPERATING SYSTEM.
+ *
+ * Tailwind's stock `dark:` variant reads `prefers-color-scheme`, which is the
+ * wrong signal here: the person may run Conexus X in dark while their OS is in
+ * light, and a view that follows the OS looks like a hole cut in the page. The
+ * host tells us its theme and ThemeSync writes it to `<html data-theme>`, so
+ * the variant reads that instead.
+ *
+ * You rarely need `dark:` at all — the semantic colours below already flip.
+ * It is here for the cases where a whole utility has to change, not a colour.
+ */
+@custom-variant dark (&:where([data-theme="dark"], [data-theme="dark"] *));
+
+/**
+ * The palette, as two sets of the same names.
+ *
+ * Swapping the VALUES under `[data-theme]` rather than writing `dark:` on every
+ * element is what keeps the markup readable: `bg-card text-fg` is correct in
+ * both themes and there is one place to change a colour.
+ */
+@layer base {
+    :root {
+        --cx-bg: #ffffff;
+        --cx-card: #ffffff;
+        --cx-fg: #18181b;
+        --cx-muted: #71717a;
+        --cx-line: #e4e4e7;
+        --cx-accent: #2563eb;
+        --cx-accent-soft: #eff6ff;
+        --cx-danger: #b91c1c;
+        --cx-danger-soft: #fef2f2;
+
+        color-scheme: light;
+    }
+
+    [data-theme="dark"] {
+        --cx-bg: #18181b;
+        --cx-card: #1f1f23;
+        --cx-fg: #fafafa;
+        --cx-muted: #a1a1aa;
+        --cx-line: #3f3f46;
+        --cx-accent: #60a5fa;
+        --cx-accent-soft: #1e293b;
+        --cx-danger: #fca5a5;
+        --cx-danger-soft: #450a0a;
+
+        color-scheme: dark;
+    }
+
+    body {
+        background-color: var(--cx-bg);
+        color: var(--cx-fg);
+        font-family: var(--font-sans);
+        -webkit-font-smoothing: antialiased;
+    }
+}
+
+/**
+ * `inline` matters.
+ *
+ * It makes each utility emit `var(--cx-…)` directly instead of copying the
+ * value into a second variable. That is what lets the theme flip at runtime:
+ * the utility resolves the variable at paint time, under whatever `data-theme`
+ * is on the element.
+ *
+ * Every name here becomes a full set of utilities — `bg-card`, `text-muted`,
+ * `border-line`, `ring-accent`, and so on.
+ */
+@theme inline {
+    --color-bg: var(--cx-bg);
+    --color-card: var(--cx-card);
+    --color-fg: var(--cx-fg);
+    --color-muted: var(--cx-muted);
+    --color-line: var(--cx-line);
+    --color-accent: var(--cx-accent);
+    --color-accent-soft: var(--cx-accent-soft);
+    --color-danger: var(--cx-danger);
+    --color-danger-soft: var(--cx-danger-soft);
+
+    --font-sans: system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
+}

package/app/layout.tsx

@@ -0,0 +1,28 @@
+import type { Metadata } from "next";
+import type { ReactNode } from "react";
+
+import "./globals.css";
+
+export const metadata: Metadata = {
+    title: "Conexus View",
+    description: "A custom view running inside a Conexus X board."
+};
+
+/**
+ * No fonts, no analytics, no chrome.
+ *
+ * This document is drawn INSIDE someone board, a few hundred pixels tall,
+ * behind whatever the customer is actually working on. Every kilobyte here is
+ * paid for by a person who did not ask for it, and anything that looks like
+ * page furniture reads as a bug in the host.
+ */
+export default function RootLayout({ children }: { children: ReactNode }) {
+    return (
+        <html lang="en" suppressHydrationWarning>
+            {/* The theme is applied client-side from the host context — the
+                server cannot know it, and guessing produces a flash of the
+                wrong one on every mount. */}
+            <body>{children}</body>
+        </html>
+    );
+}

package/app/page.tsx

@@ -0,0 +1,143 @@
+"use client";
+
+/**
+ * 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.
+ *
+ * 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.
+ *
+ * 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
+ * their own, so almost nothing here needs a `dark:` variant.
+ */
+
+import {
+    useAutoResize,
+    useCommands,
+    useConnection,
+    useRecords,
+    useScope,
+    useSettings,
+    useViewContext
+} from "@conexus-x/sdk/react";
+
+import { RecordRow } from "@/components/RecordRow";
+import { ThemeSync } from "@/components/ThemeSync";
+
+interface ViewSettings {
+    title?: string;
+    showCompleted?: boolean;
+}
+
+export default function View() {
+    const { status, error } = useConnection();
+    const context = useViewContext();
+    const commands = useCommands();
+    const canWrite = useScope("records:write");
+
+    /**
+     * What the person configured for THIS placement of the view.
+     *
+     * The manifest declares the fields, the host renders the pane and stores
+     * the answers, and this type is the contract between the two — so a default
+     * belongs here as well, because a view mounted before anyone opened its
+     * settings receives an empty object.
+     */
+    const settings = useSettings<ViewSettings>();
+    const title = settings.title ?? "Records";
+    const showCompleted = settings.showCompleted ?? true;
+
+    const {
+        data: records,
+        loading,
+        error: recordsError,
+        refresh
+    } = useRecords(context?.collectionId);
+
+    // Grow the frame to fit the content. The host resizes the slot it gave us.
+    useAutoResize();
+
+    if (status === "connecting") {
+        return (
+            <main className="p-4">
+                <div className="mb-3 h-3.5 w-2/5 animate-pulse rounded bg-line" />
+                <div className="mb-2 h-3.5 w-full animate-pulse rounded bg-line" />
+                <div className="h-3.5 w-4/5 animate-pulse rounded bg-line" />
+            </main>
+        );
+    }
+
+    if (status === "error") {
+        return (
+            <main className="p-4">
+                <div className="rounded-lg border border-danger bg-danger-soft px-3.5 py-3 text-danger">
+                    <strong className="font-semibold">Not connected to Conexus X.</strong>
+                    <p className="mt-1.5">
+                        {error?.message ??
+                            "This page expects to run inside a Conexus X board."}
+                    </p>
+                </div>
+            </main>
+        );
+    }
+
+    return (
+        <main className="p-4">
+            <ThemeSync theme={context?.theme ?? "light"} />
+
+            <header className="mb-3 flex items-baseline justify-between gap-3">
+                <h1 className="text-[15px] font-semibold">{title}</h1>
+                <span className="text-[13px] text-muted">
+                    {context?.environment === "test" ? "Test environment" : null}
+                </span>
+            </header>
+
+            {!context?.collectionId ? (
+                <p className="text-[13px] text-muted">Open a collection to see its records.</p>
+            ) : recordsError ? (
+                <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}
+                </div>
+            ) : loading && !records ? (
+                <div className="h-3.5 w-full animate-pulse rounded bg-line" />
+            ) : (
+                <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>
+            )}
+
+            {records?.length === 0 && context?.collectionId ? (
+                <p className="text-[13px] text-muted">No records in this collection yet.</p>
+            ) : null}
+        </main>
+    );
+}

package/components/RecordRow.tsx

@@ -0,0 +1,81 @@
+"use client";
+
+import { useState } from "react";
+
+import { useConexus, type CxRecord } from "@conexus-x/sdk/react";
+
+interface RecordRowProps {
+    record: CxRecord;
+    canWrite: boolean;
+    onOpen: () => void;
+    onError: (message: string) => void;
+}
+
+/** Shared button look. Extracted because two buttons is where copies start. */
+const button =
+    "rounded-md border border-line px-2.5 py-[3px] text-[13px] text-accent " +
+    "transition-colors hover:bg-accent-soft disabled:cursor-not-allowed " +
+    "disabled:opacity-50 disabled:hover:bg-transparent";
+
+/**
+ * One row.
+ *
+ * The complete/reopen button does NOT update local state on success. The write
+ * comes back as a realtime change, `useRecords` refetches, and the row redraws
+ * from the server — which is the same path a colleague edit takes. Keeping one
+ * path means the view cannot end up showing a local guess that the board never
+ * accepted.
+ */
+export function RecordRow({ record, canWrite, onOpen, onError }: RecordRowProps) {
+    const cx = useConexus();
+    const [saving, setSaving] = useState(false);
+
+    const toggle = async () => {
+        setSaving(true);
+
+        try {
+            await cx.api.records.update(record._id, {
+                isCompleted: !record.isCompleted
+            });
+        } catch (error) {
+            onError(
+                error instanceof Error
+                    ? error.message
+                    : "Could not update that record."
+            );
+        } finally {
+            setSaving(false);
+        }
+    };
+
+    return (
+        <li className="flex items-center gap-2.5 border-b border-line py-2 last:border-b-0">
+            <span
+                className={
+                    record.isCompleted
+                        ? "min-w-0 flex-1 truncate text-muted line-through"
+                        : "min-w-0 flex-1 truncate"
+                }
+            >
+                {record.name}
+            </span>
+
+            <button type="button" onClick={onOpen} className={button}>
+                Open
+            </button>
+
+            <button
+                type="button"
+                onClick={toggle}
+                // Disabled rather than hidden when the scope is missing: a
+                // button that vanishes reads as a bug, one that is greyed out
+                // reads as a permission.
+                disabled={!canWrite || saving}
+                title={canWrite ? undefined : "This app cannot change records."}
+                className={button}
+            >
+                {saving ? "Saving…" : record.isCompleted ? "Reopen" : "Complete"}
+            </button>
+        </li>
+    );
+}

package/components/ThemeSync.tsx

@@ -0,0 +1,19 @@
+"use client";
+
+import { useEffect } from "react";
+
+/**
+ * Mirror the host theme onto <html data-theme>, where globals.css reads it.
+ *
+ * Written to the DOM in an effect rather than rendered as an attribute because
+ * the server has no idea which theme the board is in — rendering a guess and
+ * correcting it on hydration is a visible flash of the wrong colours on every
+ * single mount, and this view remounts whenever the person opens the tab.
+ */
+export function ThemeSync({ theme }: { theme: "light" | "dark" }) {
+    useEffect(() => {
+        document.documentElement.dataset.theme = theme;
+    }, [theme]);
+
+    return null;
+}

package/conexus.manifest.json

@@ -0,0 +1,42 @@
+{
+    "id": "conexus-next-view",
+    "name": "Conexus Next View",
+    "version": "1.0.0",
+    "description": "Starter custom view (Next.js) — lists the records in the current collection and completes them in place.",
+    "publisher": {
+        "name": "Conexus X",
+        "email": "apps@conexus-x.example",
+        "website": "https://conexus-x.example"
+    },
+    "entry": "https://conexus-next-view.vercel.app",
+    "views": [
+        {
+            "id": "records",
+            "name": "Records",
+            "surface": "module",
+            "defaultHeight": 480,
+            "settings": [
+                {
+                    "key": "title",
+                    "label": "Heading",
+                    "type": "text",
+                    "default": "Records"
+                },
+                {
+                    "key": "showCompleted",
+                    "label": "Include completed records",
+                    "type": "boolean",
+                    "default": true
+                }
+            ]
+        }
+    ],
+    "scopes": [
+        "records:read",
+        "records:write"
+    ],
+    "permissionsRationale": {
+        "records:read": "To list the records in the collection you are looking at.",
+        "records:write": "To tick a record complete from inside the view."
+    }
+}

package/next.config.ts

@@ -0,0 +1,53 @@
+import type { NextConfig } from "next";
+
+/**
+ * A view is meant to be framed. Say so explicitly.
+ *
+ * Most hosting defaults (and every security checklist) push you toward
+ * `X-Frame-Options: DENY`, which renders a custom view as a blank rectangle
+ * with an error only in the console — the single most common way an embedded
+ * app appears broken for a reason nobody can see. `frame-ancestors` is the
+ * modern control and it is an ALLOWLIST, not an opt-out: only the Conexus X
+ * origins named here may embed this app, so this is stricter than DENY plus a
+ * hole, not weaker.
+ *
+ * CONEXUS_ORIGINS is comma-separated so a deploy can add a preview domain
+ * without a code change.
+ */
+const conexusOrigins =
+    process.env.CONEXUS_ORIGINS ??
+    "http://localhost:3000 https://conexus-x.vercel.app";
+
+const nextConfig: NextConfig = {
+    /**
+     * NOT pinning `turbopack.root` here, deliberately.
+     *
+     * Turbopack warns when it infers a workspace root from a lockfile further
+     * up the tree, and the obvious fix is `turbopack: { root: import.meta.dirname }`.
+     * Do not add it while you are developing against a locally linked SDK
+     * (`npm link @conexus-x/sdk`): the link resolves to a folder OUTSIDE this
+     * one, and a pinned root refuses to look there, so the import stops
+     * resolving with an error that says nothing about linking.
+     *
+     * With `@conexus-x/sdk` installed normally from the registry, pinning the
+     * root is safe and silences the warning.
+     */
+    async headers() {
+        return [
+            {
+                source: "/:path*",
+                headers: [
+                    {
+                        key: "Content-Security-Policy",
+                        value: `frame-ancestors 'self' ${conexusOrigins.split(",").join(" ")};`
+                    },
+                    // The host passes context in the query string; nothing here
+                    // should be cached across two different mounts of the view.
+                    { key: "Cache-Control", value: "no-store" }
+                ]
+            }
+        ];
+    }
+};
+
+export default nextConfig;

package/package.json

@@ -0,0 +1,39 @@
+{
+    "name": "@conexus-x/next-view",
+    "version": "1.0.0",
+    "private": false,
+    "description": "Custom view for Conexus X — Next.js starter, wired to @conexus-x/sdk.",
+    "scripts": {
+        "dev": "next dev --port 5173",
+        "build": "next build",
+        "start": "next start --port 5173",
+        "lint": "eslint"
+    },
+    "dependencies": {
+        "@conexus-x/sdk": "^0.1.0",
+        "next": "16.2.10",
+        "react": "19.2.4",
+        "react-dom": "19.2.4"
+    },
+    "devDependencies": {
+        "@tailwindcss/postcss": "^4.3.3",
+        "@types/node": "^20",
+        "@types/react": "^19",
+        "@types/react-dom": "^19",
+        "tailwindcss": "^4.3.3",
+        "typescript": "^5"
+    },
+    "publishConfig": {
+        "access": "restricted"
+    },
+    "files": [
+        "app",
+        "components",
+        "next.config.ts",
+        "postcss.config.mjs",
+        "tsconfig.json",
+        "conexus.manifest.json",
+        "README.md",
+        ".gitignore"
+    ]
+}

package/postcss.config.mjs

@@ -0,0 +1,14 @@
+/**
+ * Tailwind v4 needs exactly this and nothing else.
+ *
+ * No `tailwind.config.js`, no `autoprefixer`, no `postcss-import` — v4 handles
+ * all three itself. If you have set Tailwind up before and this file looks too
+ * short, it is not missing anything.
+ */
+const config = {
+    plugins: {
+        "@tailwindcss/postcss": {}
+    }
+};
+
+export default config;

package/tsconfig.json

@@ -0,0 +1,41 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "lib": [
+      "dom",
+      "dom.iterable",
+      "esnext"
+    ],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "react-jsx",
+    "incremental": true,
+    "plugins": [
+      {
+        "name": "next"
+      }
+    ],
+    "paths": {
+      "@/*": [
+        "./*"
+      ]
+    }
+  },
+  "include": [
+    "next-env.d.ts",
+    "**/*.ts",
+    "**/*.tsx",
+    ".next/types/**/*.ts",
+    ".next/dev/types/**/*.ts"
+  ],
+  "exclude": [
+    "node_modules"
+  ]
+}