Access ask
ProAn 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.
Preview
Loading the preview
Install
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
"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>
| Prop | Type | Default | Description |
|---|---|---|---|
| agentrequired | AgentIdentity | — | The agent asking, named by the app. |
| titlerequired | string | — | What is asked, in the app's words: "Use the camera on supplier.example", "Reconnect the test account". Drawn as text. |
| whyrequired | string | — | Why the agent asks, in the app's or the agent's words. Drawn as text. |
| can | readonly string[] | undefined | — | What the access allows, each in plain words. Left out or empty, it says the app hasn't said. |
| cannot | readonly string[] | undefined | — | What it doesn't allow, each in plain words. Left out or empty, the list isn't drawn. |
| actionLabelrequired | string | — | 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". |
| grantLocked | string | 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. |
| declineAssumption | string | 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. |
| state | AccessAskState | undefined | "asked" | Where the ask is. Defaults to "asked". |
| reason | string | undefined | — | With "refused": the service's reason, drawn as text. Left out, it says the service gave none. |
| endsAt | string | 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. |
| className | string | undefined | — | Classes, merged with Candor's. |
| headingLevel | HeadingLevel | 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.
| Key | English |
|---|---|
| kind | Access request |
| askedBy | Asked by {agent} |
| why | Why |
| can | What it allows |
| cannot | What it doesn’t allow |
| canUnknown | The app hasn’t said what this access allows. |
| notNow | Not now |
| decline | Decline |
| declineNote | If you decline, {agent} goes on assuming: {assumption} |
| signingIn | Waiting for the sign-in to finish. Nothing is connected until it does. |
| signingInLocked | The sign-in is still running. |
| connected | Connected |
| refused | Access was refused. |
| refusedNoReason | The service gave no reason. |
| notNowDone | Put off. Nothing was connected. |
| ends | Access ends {time} |
| ended | Access ended {time} |
| endingUnknown | Access is ending. When isn’t known. |
| endedUnknown | Access has ended. |
| declined | Declined. {agent} goes on assuming: {assumption} |
| declinedPlain | Declined. 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