# Access ask

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.

- Registry name: `access-ask` (`@candor/access-ask`)
- Tier: Pro. Installing it needs a Pro, Premium or Team licence key: the person runs `npx candor-ui key <key>` themselves; never ask for the key in chat or write it to a file.
- Docs: https://candor.themethodic.com/docs/access-ask

## Install

```bash
npx candor-ui@4 add access-ask
```

Run `npx candor-ui@latest init` once first (https://candor.themethodic.com/get-started.md). Without the CLI: `npx shadcn@latest add @candor/access-ask`.
It brings in: agent-avatar, bidi, button, chat, heading-level, heading-scope, locale, locked, relative-time, tokens, use-announcer, use-focus-within, utils.
npm packages: lucide-react@^1.67.0.

## Example

```tsx
"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>

Props:

- `agent: AgentIdentity`: The agent asking, named by the app.
- `title: string`: What is asked, in the app's words: "Use the camera on supplier.example", "Reconnect the test account". Drawn as text.
- `why: 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.
- `actionLabel: 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` (default `"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 (`accessAsk`)

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

- `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.

```ts
"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

Import: `import type { AgentIdentity } from "@/lib/candor/chat"` (item `chat`, https://candor.themethodic.com/docs/chat.md)

```ts
{
  id: string;
  /** The displayed name, e.g. "Architect agent". Never derived from model output. */
  name: string;
  role: AgentRole;
  specialty?: string | undefined;
}
```

### HeadingLevel

Import: `import type { HeadingLevel } from "@/lib/candor/heading-level"` (item `heading-level`, https://candor.themethodic.com/docs/heading-level.md)

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.

```ts
1 | 2 | 3 | 4 | 5 | 6
```

### AgentRole

Import: `import type { AgentRole } from "@/lib/candor/chat"` (item `chat`, https://candor.themethodic.com/docs/chat.md)

What an agent does: "assistant", "coder", "reviewer"… The app registers each role's glyph and hue (AgentRolesProvider).

```ts
string
```

## Rules for using Candor UI

- Components take plain typed data. Never pass model output as HTML or render it as a link; messages are typed blocks.
- A control that can't be used says why: wrap it in `<Locked reason="…">`, don't just disable it.
- Don't show a value you don't have: leave it out (it renders as —) rather than guess. An estimate is labelled as one.
- Nothing is pre-selected in a decision a person makes, and the agent is named from your app's data, never from model output.
- Your app's words go in `LocaleProvider`: its fixed strings in `strings`, its nouns in `nouns`; entity kinds and agent roles in `EntityKindsProvider` and `AgentRolesProvider`.
