Environment connect

Preview

Install

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

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

Usage

"use client"

import * as React from "react"
import { EnvironmentConnect, type ConnectionHold } from "@/components/candor/environment-connect"

export default function Example() {
  // Signing in with the provider here stands for an install that an admin on the other side has to approve: the
  // panel says who and where, until Check again finds it approved or Back returns to the ways of connecting.
  const [hold, setHold] = React.useState<ConnectionHold | undefined>(undefined)
  return (
    <EnvironmentConnect
      className="max-w-md"
      environment={{ id: "e1", name: "Shop", detail: "staging", production: false, hue: 2, connection: "expired" }}
      oauth={{
        provider: "the provider",
        onStart: () => setHold({ kind: "waiting", who: "An admin of the Shop account", where: "Settings › Connected apps", askedAt: new Date().toISOString() }),
      }}
      hold={hold}
      onCheckAgain={async () => {
        await new Promise((r) => setTimeout(r, 500))
        setHold((h) => (h?.kind === "waiting" ? { ...h, checkedAt: new Date().toISOString() } : h))
      }}
      onBack={() => setHold(undefined)}
      fields={[
        { id: "url", label: "Instance URL", type: "url", placeholder: "https://shop.example.com" },
        { id: "clientId", label: "Client ID" },
        { id: "secret", label: "Client secret", type: "secret" },
      ]}
      values={{ url: "https://staging.shop.example.com", clientId: "agents-staging" }}
      onTest={async (v) => {
        await new Promise((r) => setTimeout(r, 500))
        return v.url?.startsWith("https://")
          ? { ok: true, checkedAt: new Date().toISOString(), detail: "Signed in as agents-staging; 3 of 3 permissions granted." }
          : { ok: false, checkedAt: new Date().toISOString(), reason: "The instance didn’t answer at that address." }
      }}
      onConnect={async () => {
        await new Promise((r) => setTimeout(r, 400))
      }}
      requireTest
    />
  )
}

<EnvironmentConnect>

Strings

Types

ConnectionHold

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; }

ConnectionField

A credential the environment needs, as the app defines it.

{ id: string; /** What it is, e.g. "Instance URL" or "Client secret". */ label: string; /** `secret` masks it and never shows a saved value back. Defaults to text. */ type?: "text" | "url" | "secret" | undefined; /** A line under the field: where to find it. */ hint?: string | undefined; placeholder?: string | undefined; /** Connect works without it. */ optional?: boolean | undefined; }

ConnectionTestResult

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 }

Types from other items

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

Environment from @/lib/candor/team

Where agents act: a CRM instance, a database, a repository, a project. The app names them; LocaleProvider's `nouns` sets what they're called ("project", "workspace").

{ id: string; /** The name shown everywhere, e.g. "Shop". */ name: string; /** What tells same-named ones apart, e.g. "dev-2" or "staging". */ detail?: string | undefined; /** Changes here reach real users, so components warn and ask for more care. */ production: boolean; /** A chart slot (1–5) so each environment keeps one colour everywhere it appears. */ hue?: 1 | 2 | 3 | 4 | 5 | undefined; connection: "connected" | "expired" | "not-connected"; }

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