Skip to content
Tier

Access ask

Pro

An access request in the app's environment: a website permission, or an account to reconnect or sign in to. It says what access is wanted (title) and why, what the access allows and doesn't allow, and offers the worded action (actionLabel, "Reconnect the test account…"), Not now and Decline, side by side and with the same weight: none is focused, pre-selected or drawn as the default. Decline says, before it is pressed, what the agent goes on assuming without the access, and onDecline is called with those words for the app to record.

It is headed "Access request", as ConnectionPicker is, so it is never taken for a question about the work. For an acknowledgement the person must tick before a data flow starts, use ConsentCeremony; to pick one of the person's existing connections, ConnectionPicker; for an agent asking the person to take the screen, TurnRequest.

state is the app's: "connected" only once the service confirmed it (while the person signs in it says it is waiting); "refused" shows the service's reason; "ending" and "ended" read endsAt as a relative time against the clock, and say when isn't known rather than guess. "connected" or "ending" with an endsAt that has passed, when the card mounts or as the clock ticks on, is drawn as "ended": "Access ended …" with the action to renew it. A state change is announced once while the card is shown, and focus that was on an action that went moves to the title. Nothing is announced on mount.

Markdown

Preview

Loading the preview

Install

With the Candor CLI

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

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

Usage

TSX · The example above
"use client"

import * as React from "react"
import { AccessAsk, type AccessAskState } from "@/components/candor/access-ask"

const agent = { id: "builder", name: "Builder", role: "dev" }

/** Reconnect, Not now and Decline are equal; Decline says what the agent will assume before it is pressed. */
export default function Example() {
  const [state, setState] = React.useState<AccessAskState>("asked")
  return (
    <div className="max-w-lg">
      <AccessAsk
        agent={agent}
        title="Reconnect Acme sandbox"
        why="The sandbox's sign-in ran out, and the next step deploys there."
        can={["Read records", "Deploy changes to the sandbox"]}
        cannot={["Reach production", "Change users or permissions"]}
        actionLabel="Reconnect…"
        state={state}
        onGrant={() => {
          setState("signing-in")
          // The app sets "connected" once the service confirms the sign-in.
          setTimeout(() => setState("connected"), 1500)
        }}
        onNotNow={() => setState("not-now")}
        onDecline={() => setState("declined")}
        declineAssumption="the deploy waits, and the build goes on without it"
      />
    </div>
  )
}

<AccessAsk>

PropTypeDefaultDescription
agentrequiredAgentIdentity—The agent asking, named by the app.
titlerequiredstring—What is asked, in the app's words: "Use the camera on supplier.example", "Reconnect the test account". Drawn as text.
whyrequiredstring—Why the agent asks, in the app's or the agent's words. Drawn as text.
canreadonly string[] | undefined—What the access allows, each in plain words. Left out or empty, it says the app hasn't said.
cannotreadonly string[] | undefined—What it doesn't allow, each in plain words. Left out or empty, the list isn't drawn.
actionLabelrequiredstring—The words of the button that grants or renews it, the app's: "Allow camera", "Sign in to the shop…", "Reconnect…". A worded action, never only "OK".
onGrant(() => void) | undefined—Shows the action; called when it's pressed. Start the sign-in or ask the browser from here, then set `state` "signing-in".
grantLockedstring | null | undefined—Why the person can't grant it, if they can't. The button stays and says so. `null` or unset means they can.
onNotNow(() => void) | undefined—Shows Not now; called when it's pressed. Set `state` "not-now" from here.
onDecline((assumption: string) => void) | undefined—Shows Decline, with `declineAssumption`; called with that assumption when it's pressed, for the app to record (an AnswerReceipt, say). Set `state` "declined" from here.
declineAssumptionstring | undefined—What the agent goes on assuming if the person declines, in the app's words: "the camera stays off and the supplier is checked by email". Shown before Decline is pressed. Decline is drawn only with it.
stateAccessAskState | undefined"asked"Where the ask is. Defaults to "asked".
reasonstring | undefined—With "refused": the service's reason, drawn as text. Left out, it says the service gave none.
endsAtstring | undefined—When access ends, as an ISO time from the service: with "connected" or "ending", "Access ends in 6 days"; with "ended", "Access ended 2 days ago". A time already past reads as ended, in every one of the three, with the action (`onGrant`) to renew it. Left out, nothing is guessed.
classNamestring | undefined—Classes, merged with Candor's.
headingLevelHeadingLevel | undefined—The level of its title. Defaults to one below the nearest `HeadingScope`, else 2. Its list headings sit one below.

Strings

The fixed words, in English by default. Change any of them under accessAsk in <LocaleProvider strings={{ … }}>; the table is exported as accessAskStrings.

KeyEnglish
kindAccess request
askedByAsked by {agent}
whyWhy
canWhat it allows
cannotWhat it doesn’t allow
canUnknownThe app hasn’t said what this access allows.
notNowNot now
declineDecline
declineNoteIf you decline, {agent} goes on assuming: {assumption}
signingInWaiting for the sign-in to finish. Nothing is connected until it does.
signingInLockedThe sign-in is still running.
connectedConnected
refusedAccess was refused.
refusedNoReasonThe service gave no reason.
notNowDonePut off. Nothing was connected.
endsAccess ends {time}
endedAccess ended {time}
endingUnknownAccess is ending. When isn’t known.
endedUnknownAccess has ended.
declinedDeclined. {agent} goes on assuming: {assumption}
declinedPlainDeclined. Nothing was connected.

Types

AccessAskState
Where an access ask is, as the app knows it: asked; the person is signing in; connected (only once the service confirmed it); refused by the service; put off ("not now"); access ending soon or ended; or declined.
"asked" | "signing-in" | "connected" | "refused" | "not-now" | "ending" | "ended" | "declined"

Types from other items

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

AgentIdentity from @/lib/candor/chat
{ id: string; /** The displayed name, e.g. "Architect agent". Never derived from model output. */ name: string; role: AgentRole; specialty?: string | undefined; }
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
AgentRole from @/lib/candor/chat
What an agent does: "assistant", "coder", "reviewer"… The app registers each role's glyph and hue (AgentRolesProvider).
string