Integration connect

Preview

Install

First time? Get started sets up the registry and theme. Or with shadcn directly: npx shadcn@latest add @candor/integration-connect

Brings in: bidi, button, heading-level, heading-scope, input, locale, locked, relative-time, tokens, use-announcer, use-focus-within, utils · npm: lucide-react@^1.67.0

Usage

"use client"

import * as React from "react"
import { IntegrationConnect } from "@/components/candor/integration-connect"

const scopes = [
  { id: "events.read", label: "Read events on calendars shared with the app", required: true },
  { id: "events.write", label: "Create and move events", description: "Agents can book a meeting once you’ve approved it.", writes: true },
  { id: "freebusy.read", label: "See when people are free", description: "Free and busy times only, not what the events are." },
]

export default function Example() {
  const [state, setState] = React.useState<"connected" | "not-connected">("not-connected")
  const [granted, setGranted] = React.useState<string[]>([])
  const [connectedAt, setConnectedAt] = React.useState<string>()
  return (
    <IntegrationConnect
      className="max-w-lg"
      name="Calendar"
      by="Example Calendar Inc."
      state={state}
      account={state === "connected" ? "ops-bot@example.com" : undefined}
      connectedAt={state === "connected" ? connectedAt : undefined}
      scopes={scopes}
      granted={granted}
      reaches={["Events on calendars shared with the app", "Who is invited to them"]}
      notReaches={["Private events", "Calendars nobody shared", "Your email"]}
      oauth={{ provider: "Example ID", onStart: () => {} }}
      apiKey={{ placeholder: "cal_live_…" }}
      onTest={async (key) => {
        await new Promise((r) => setTimeout(r, 500))
        return key === undefined || key.startsWith("cal_")
          ? { ok: true, checkedAt: new Date().toISOString(), detail: "Signed in as ops-bot@example.com; 2 calendars shared." }
          : { ok: false, checkedAt: new Date().toISOString(), reason: "The key was refused. Keys start with cal_." }
      }}
      requireTest
      onConnect={async ({ scopes: ticked }) => {
        await new Promise((r) => setTimeout(r, 400))
        setGranted(ticked)
        setConnectedAt(new Date().toISOString())
        setState("connected")
      }}
      disconnect={{
        stops: ["New and moved events stop syncing", "Agents can no longer book meetings"],
        stays: ["Events already synced stay in the app until you delete them"],
        reconnect: "Connect again from this page; the access is asked for again.",
      }}
      onDisconnect={async () => {
        await new Promise((r) => setTimeout(r, 400))
        setState("not-connected")
      }}
    />
  )
}

<IntegrationConnect>

Strings

Types

IntegrationHold

The other system has to act before the connection can finish, as the app's server reports it: an admin there must approve the app (`waiting`), or their policy blocks it (`blocked`). Every string is the app's words, or the other system's, and is drawn as text.

{ kind: "waiting"; /** Who on the other side has to approve the app, e.g. "An admin of the Shop account". */ who: string; /** Where they approve it, e.g. "Settings › Connected apps". */ where: string; /** When the app asked, as an ISO time. Left out, no time is shown. */ askedAt?: string | undefined; /** When the app last checked whether they approved, as an ISO time. Left out, no time is shown. */ checkedAt?: string | undefined; } | { kind: "blocked"; /** What their policy blocks, e.g. "Apps from outside the company signing in with OAuth". */ what: string; /** Who can unblock it, e.g. "Their security team". */ who: string; }

IntegrationScope

One piece of access the integration asks for (an OAuth scope or the like), in plain words.

{ /** The scope as the provider names it ("calendar.read"); what the connect callbacks send back. */ id: string; /** What it allows, in plain words: "Read your calendar’s events". Shown in place of the id. */ label: string; /** More about it, when a sentence helps. */ description?: string | undefined; /** Connecting can’t work without it, so it isn’t a choice: it’s listed as Needed. Without this, the person ticks it to grant it; nothing starts ticked. */ required?: boolean | undefined; /** It lets the integration change or delete things, not only read. Marked so the person sees it. */ writes?: boolean | undefined; }

IntegrationTestResult

What a connection test found, as the app's server reports it.

| { ok: true; checkedAt: string; detail?: string | undefined } | { ok: false; checkedAt: string; reason: string }

IntegrationConnection

A connection made with a key: the key entered and the ids of the optional scopes the person ticked.

{ method: "api-key"; key: string; scopes: string[] }

IntegrationDisconnect

What disconnecting stops and what stays, in the app's words.

{ /** What stops once it's disconnected: "New events stop syncing", "Agents can no longer create issues". */ stops: string[]; /** What stays: "Events already synced stay in the app". */ stays?: string[] | undefined; /** How to connect again, when it isn't simply this card. */ reconnect?: string | undefined; }

Types from other items

The props above take these. Each is defined by another item; import it from the path shown.

HeadingLevel from @/lib/candor/heading-level

A heading's level in the page's outline: `1` is `<h1>`, `6` is `<h6>`. Every Candor item that draws a heading takes its `headingLevel` as this type; the level is where the heading sits in the outline, never how large it looks.

1 | 2 | 3 | 4 | 5 | 6