UI kit reference

zidane-ui/approvals

import { … } from 'zidane-ui/approvals'ui/src/approvals/index.ts

Components#

`ApprovalBar`Component#

Renders the first pending approval of a session: the inline ApprovalCard, or the file-edit review for the tools that write files. While the inline card shows, esc denies (not from inside the code editor, where it clears the selection), ⌘↵ allows once and ⌘⇧↵ always allows. Renders nothing when the session has no pending approval.

TypeScript

function ApprovalBar(props: ApprovalBarProps): Element | null

Parameters

Parameters
Name	Type	Description
props	`ApprovalBarProps`	The `sessionId`, an optional `onFileEdit`, `renderFrame`, `className` and `style`.

Returns

Element | null

Props

ApprovalBar props
Name	Type	Description
className?	`string`	Extra classes on the inline card's root.
onFileEdit?	`(request: WireApprovalRequest) => void`	Opens the file-edit review for an `edit`, `multi_edit` or `write_file` approval on the app's modal layer (once per request; the bar then renders nothing). Absent: the bar renders `FileEditApproval` in place.
renderFrame?	`(props: ApprovalFrameProps) => ReactElement`	Draws the inline card's surface. See `ApprovalCardProps.renderFrame`.
sessionId	`string \| null`	The session whose first pending approval shows. `null`: nothing shows.
style?	`CSSProperties`	Inline styles on the inline card's root.

ui/src/approvals/ApprovalBar.tsx:194

`ApprovalCard`Component#

Renders the inline approval card: the tool, what worried the decision model, the command or input (scrolling inside a capped body while the title and actions stay on screen), and the decisions. Once per request, focus lands on the card itself, never on a button, unless the user is typing somewhere.

TypeScript

function ApprovalCard(props: ApprovalCardProps): Element

Parameters

Parameters
Name	Type	Description
props	`ApprovalCardProps`	The `request`, `onResolve`, an optional `renderFrame`, `className` and `style`.

Returns

Element

Props

ApprovalCard props
Name	Type	Description
className?	`string`	Extra classes on the root (the `alertdialog`).
onResolve?	`(requestId: string, decision: ApprovalDecision) => void`	Called with the user's decision. Absent: the card shows the request without its buttons.
renderFrame?	`(props: ApprovalFrameProps) => ReactElement`	Draws the card's surface (an app's own dock card). Default: a raised card tinted with the warn color.
request	`WireApprovalRequest`	The pending approval to show.
style?	`CSSProperties`	Inline styles on the root.

ui/src/approvals/ApprovalBar.tsx:86

`ApprovalConcern`Component#

Renders what worried the decision model about a call it handed to the user.

TypeScript

function ApprovalConcern(props: ApprovalConcernProps): Element

Parameters

Parameters
Name	Type	Description
props	`ApprovalConcernProps`	The `concern`, plus `className` and `style`.

Returns

Element

Props

ApprovalConcern props
Name	Type	Description
className?	`string`	Extra classes on the line.
concern	`ModelApproval`	The decision model's verdict, from the request's `concern`.
style?	`CSSProperties`	Inline styles on the line.

ui/src/approvals/ApprovalConcern.tsx:25

`ApprovalShell`Component#

Renders a titled panel with a body and an optional footer, as a dialog named by its title.

TypeScript

function ApprovalShell(props: ApprovalShellProps): Element

Parameters

Parameters
Name	Type	Description
props	`ApprovalShellProps`	The `title`, `description`, `onClose`, `footer`, `children`, `className` and `style`.

Returns

Element

Props

ApprovalShell props
Name	Type	Description
children	`ReactNode`	The body.
className?	`string`	Extra classes on the panel.
description?	`string`	A line under the heading.
footer?	`ReactNode`	The actions row under the body.
onClose?	`() => void`	Called by the close button (the file-edit review denies). Absent: no close button.
style?	`CSSProperties`	Inline styles on the panel.
title	`string`	The panel's heading.

ui/src/approvals/ApprovalShell.tsx:36

`ApprovalsProvider`Component#

Provides an ApprovalsHost and optional label overrides to the approval components below it.

TypeScript

function ApprovalsProvider(props: ApprovalsProviderProps): Element

Parameters

Parameters
Name	Type	Description
props	`ApprovalsProviderProps`	Provider props: the `host`, optional `labels`, and the `children` to render.

Returns

Element

Props

ApprovalsProvider props
Name	Type	Description
children	`ReactNode`	The components that read from `host`.
host	`ApprovalsHost`	The host the approval components read pending approvals from and send decisions to.
labels?	Partial<{ approvalAllow: string; approvalAllowForSession: string; approvalAllowNoneSelected: string; approvalAllowOnce: string; approvalAlwaysAllow: string; approvalApplySelected: (selected: number, total: number) => string; approvalClose: string; approvalConcern: (concern: ModelApproval) => string; approvalCwd: (cwd: string) => string; approvalDeny: string; approvalFileEditNoPath: string; approvalFileEditReview: string; approvalFileEditTitle: (tool: string, path: string \| null) => string; approvalFromSubagent: (label: string) => string; approvalRunAfter: string; approvalRunBefore: string; approvalsError: (error: ApprovalsError) => string; approvalTimeout: (timeout: string) => string; hunkAdded: (count: number) => string; hunkAmbiguous: (matches: number) => string; hunkAmbiguousHint: (matches: number) => string; hunkFile: string; hunkInclude: (index: number, total: number) => string; hunkNewFile: string; hunkNotInFile: string; hunkNotInFileHint: string; hunkRemoved: (count: number) => string; hunkReplaceAll: string; hunksClear: string; hunksOf: string; hunksSelectAll: string; hunksSelected: string; hunksSomeMissing: string; hunkTitle: (index: number, total: number) => string; hunkVia: (via: string) => string; hunkViaHint: (via: string) => string; safelistCount: (count: number) => string; safelistDescription: string; safelistEmpty: string; safelistEmptyHint: string; safelistLoading: string; safelistProject: string; safelistRevoke: string; safelistRevoking: string; safelistTitle: string }>	Overrides for the approval components' strings. Keys you leave out keep the default English label.

ui/src/approvals/ApprovalsProvider.tsx:50

`FileEditApproval`Component#

Renders the file-edit review of a pending approval: the path, the subagent that asked, what worried the decision model, the diff (or the per-hunk checklist), and the decisions with their a / s / p / d keys. Esc and a click on the modal scrim deny. Focus starts on Allow.

TypeScript

function FileEditApproval(props: FileEditApprovalProps): Element

Parameters

Parameters
Name	Type	Description
props	`FileEditApprovalProps`	The `request`, `onDone`, an optional `renderShell`, `className` and `style`.

Returns

Element

Props

FileEditApproval props
Name	Type	Description
className?	`string`	Extra classes on the default shell.
onDone?	`() => void`	Called once the user decided, or when the request was answered elsewhere: close the modal that holds the review.
renderShell?	`(props: ApprovalShellProps) => ReactNode`	Draws the panel around the review (an app's own modal shell). It receives the title, description, body, footer and `onClose` (which denies). Default: `ApprovalShell`.
request	`WireApprovalRequest`	The pending `edit`, `multi_edit` or `write_file` approval.
style?	`CSSProperties`	Inline styles on the default shell.

ui/src/approvals/FileEditApproval.tsx:80

`SafelistPanel`Component#

Renders the safelist: each project's "Always allow" entries with a Revoke button (when the host offers safelist.remove), the empty state, and read or revoke errors. Renders nothing when the host has no safelist.

TypeScript

function SafelistPanel(props: SafelistPanelProps): Element | null

Parameters

Parameters
Name	Type	Description
props	`SafelistPanelProps`	An optional `renderShell`, `className` and `style`.

Returns

Element | null

Props

SafelistPanel props
Name	Type	Description
className?	`string`	Extra classes on the default shell.
renderShell?	`(props: ApprovalShellProps) => ReactNode`	Draws the panel around the list (an app's own modal shell). It receives the title, description and body. Default: `ApprovalShell`.
style?	`CSSProperties`	Inline styles on the default shell.

ui/src/approvals/SafelistPanel.tsx:33

Functions#

`useApprovalsHost`Function#

Returns the ApprovalsHost from the nearest ApprovalsProvider. Throws when called outside one.

TypeScript

function useApprovalsHost(): ApprovalsHost

Returns

ApprovalsHost

ui/src/approvals/ApprovalsProvider.tsx:69

`useApprovalsLabels`Function#

Returns the approval components' strings: the defaults merged with any overrides given to ApprovalsProvider or LabelsProvider.

TypeScript

function useApprovalsLabels(): { approvalAllow: string; approvalAllowForSession: string; approvalAllowNoneSelected: string; approvalAllowOnce: string; approvalAlwaysAllow: string; approvalApplySelected: (selected: number, total: number) => string; approvalClose: string; approvalConcern: (concern: ModelApproval) => string; approvalCwd: (cwd: string) => string; approvalDeny: string; approvalFileEditNoPath: string; approvalFileEditReview: string; approvalFileEditTitle: (tool: string, path: string | null) => string; approvalFromSubagent: (label: string) => string; approvalRunAfter: string; approvalRunBefore: string; approvalsError: (error: ApprovalsError) => string; approvalTimeout: (timeout: string) => string; hunkAdded: (count: number) => string; hunkAmbiguous: (matches: number) => string; hunkAmbiguousHint: (matches: number) => string; hunkFile: string; hunkInclude: (index: number, total: number) => string; hunkNewFile: string; hunkNotInFile: string; hunkNotInFileHint: string; hunkRemoved: (count: number) => string; hunkReplaceAll: string; hunksClear: string; hunksOf: string; hunksSelectAll: string; hunksSelected: string; hunksSomeMissing: string; hunkTitle: (index: number, total: number) => string; hunkVia: (via: string) => string; hunkViaHint: (via: string) => string; safelistCount: (count: number) => string; safelistDescription: string; safelistEmpty: string; safelistEmptyHint: string; safelistLoading: string; safelistProject: string; safelistRevoke: string; safelistRevoking: string; safelistTitle: string }

Returns

{ approvalAllow: string; approvalAllowForSession: string; approvalAllowNoneSelected: string; approvalAllowOnce: string; approvalAlwaysAllow: string; approvalApplySelected: (selected: number, total: number) => string; approvalClose: string; approvalConcern: (concern: ModelApproval) => string; approvalCwd: (cwd: string) => string; approvalDeny: string; approvalFileEditNoPath: string; approvalFileEditReview: string; approvalFileEditTitle: (tool: string, path: string | null) => string; approvalFromSubagent: (label: string) => string; approvalRunAfter: string; approvalRunBefore: string; approvalsError: (error: ApprovalsError) => string; approvalTimeout: (timeout: string) => string; hunkAdded: (count: number) => string; hunkAmbiguous: (matches: number) => string; hunkAmbiguousHint: (matches: number) => string; hunkFile: string; hunkInclude: (index: number, total: number) => string; hunkNewFile: string; hunkNotInFile: string; hunkNotInFileHint: string; hunkRemoved: (count: number) => string; hunkReplaceAll: string; hunksClear: string; hunksOf: string; hunksSelectAll: string; hunksSelected: string; hunksSomeMissing: string; hunkTitle: (index: number, total: number) => string; hunkVia: (via: string) => string; hunkViaHint: (via: string) => string; safelistCount: (count: number) => string; safelistDescription: string; safelistEmpty: string; safelistEmptyHint: string; safelistLoading: string; safelistProject: string; safelistRevoke: string; safelistRevoking: string; safelistTitle: string }

ui/src/approvals/ApprovalsProvider.tsx:107

`usePendingApprovals`Function#

Returns every pending approval, oldest first. Re-renders on every change to the queue.

TypeScript

function usePendingApprovals(): readonly WireApprovalRequest[]

Returns

readonly WireApprovalRequest[]

ui/src/approvals/ApprovalsProvider.tsx:74

`useResolveApproval`Function#

Returns resolve: answers a pending approval through the host, ignoring a failed send (the request already left the queue). undefined when the host can't answer approvals.

TypeScript

function useResolveApproval(): ((requestId: string, decision: ApprovalDecision) => void) | undefined

Returns

((requestId: string, decision: ApprovalDecision) => void) | undefined

ui/src/approvals/ApprovalsProvider.tsx:95

`useSessionApprovalHead`Function#

Returns the first pending approval of sessionId, or null. Re-renders only when that session's first approval changes, so rows of other sessions stay still.

TypeScript

function useSessionApprovalHead(sessionId: string | null): WireApprovalRequest | null

Parameters

Parameters
Name	Type	Description
sessionId	`string \| null`	The session, or `null` for none.

Returns

WireApprovalRequest | null

ui/src/approvals/ApprovalsProvider.tsx:84

Interfaces#

`ApprovalBarProps`Interface#

Props for ApprovalBar.

TypeScript

interface ApprovalBarProps

Properties

ApprovalBarProps properties
Name	Type	Description
className?	`string`	Extra classes on the inline card's root.
onFileEdit?	`(request: WireApprovalRequest) => void`	Opens the file-edit review for an `edit`, `multi_edit` or `write_file` approval on the app's modal layer (once per request; the bar then renders nothing). Absent: the bar renders `FileEditApproval` in place.
renderFrame?	`(props: ApprovalFrameProps) => ReactElement`	Draws the inline card's surface. See `ApprovalCardProps.renderFrame`.
sessionId	`string \| null`	The session whose first pending approval shows. `null`: nothing shows.
style?	`CSSProperties`	Inline styles on the inline card's root.

ui/src/approvals/ApprovalBar.tsx:169

`ApprovalCardProps`Interface#

Props for ApprovalCard.

TypeScript

interface ApprovalCardProps

Properties

ApprovalCardProps properties
Name	Type	Description
className?	`string`	Extra classes on the root (the `alertdialog`).
onResolve?	`(requestId: string, decision: ApprovalDecision) => void`	Called with the user's decision. Absent: the card shows the request without its buttons.
renderFrame?	`(props: ApprovalFrameProps) => ReactElement`	Draws the card's surface (an app's own dock card). Default: a raised card tinted with the warn color.
request	`WireApprovalRequest`	The pending approval to show.
style?	`CSSProperties`	Inline styles on the root.

ui/src/approvals/ApprovalBar.tsx:65

`ApprovalConcernProps`Interface#

Props for ApprovalConcern.

TypeScript

interface ApprovalConcernProps

Properties

ApprovalConcernProps properties
Name	Type	Description
className?	`string`	Extra classes on the line.
concern	`ModelApproval`	The decision model's verdict, from the request's `concern`.
style?	`CSSProperties`	Inline styles on the line.

ui/src/approvals/ApprovalConcern.tsx:11

`ApprovalFrameProps`Interface#

What ApprovalCardProps.renderFrame receives: the card's layout classes and its content.

TypeScript

interface ApprovalFrameProps

Properties

ApprovalFrameProps properties
Name	Type	Description
children	`ReactNode`	The card's content.
className	`string`	The card's layout classes (a column, capped in height), to put on the frame.
tone	`'attention'`	Always `attention`: the frame of something waiting for the user.

ui/src/approvals/ApprovalBar.tsx:33

`ApprovalShellProps`Interface#

What a shell receives: the panel's title, description, content and footer, and how to close it.

TypeScript

interface ApprovalShellProps

Properties

ApprovalShellProps properties
Name	Type	Description
children	`ReactNode`	The body.
className?	`string`	Extra classes on the panel.
description?	`string`	A line under the heading.
footer?	`ReactNode`	The actions row under the body.
onClose?	`() => void`	Called by the close button (the file-edit review denies). Absent: no close button.
style?	`CSSProperties`	Inline styles on the panel.
title	`string`	The panel's heading.

ui/src/approvals/ApprovalShell.tsx:14

`ApprovalsProviderProps`Interface#

Props for ApprovalsProvider.

TypeScript

interface ApprovalsProviderProps

Properties

ApprovalsProviderProps properties
Name	Type	Description
children	`ReactNode`	The components that read from `host`.
host	`ApprovalsHost`	The host the approval components read pending approvals from and send decisions to.
labels?	Partial<{ approvalAllow: string; approvalAllowForSession: string; approvalAllowNoneSelected: string; approvalAllowOnce: string; approvalAlwaysAllow: string; approvalApplySelected: (selected: number, total: number) => string; approvalClose: string; approvalConcern: (concern: ModelApproval) => string; approvalCwd: (cwd: string) => string; approvalDeny: string; approvalFileEditNoPath: string; approvalFileEditReview: string; approvalFileEditTitle: (tool: string, path: string \| null) => string; approvalFromSubagent: (label: string) => string; approvalRunAfter: string; approvalRunBefore: string; approvalsError: (error: ApprovalsError) => string; approvalTimeout: (timeout: string) => string; hunkAdded: (count: number) => string; hunkAmbiguous: (matches: number) => string; hunkAmbiguousHint: (matches: number) => string; hunkFile: string; hunkInclude: (index: number, total: number) => string; hunkNewFile: string; hunkNotInFile: string; hunkNotInFileHint: string; hunkRemoved: (count: number) => string; hunkReplaceAll: string; hunksClear: string; hunksOf: string; hunksSelectAll: string; hunksSelected: string; hunksSomeMissing: string; hunkTitle: (index: number, total: number) => string; hunkVia: (via: string) => string; hunkViaHint: (via: string) => string; safelistCount: (count: number) => string; safelistDescription: string; safelistEmpty: string; safelistEmptyHint: string; safelistLoading: string; safelistProject: string; safelistRevoke: string; safelistRevoking: string; safelistTitle: string }>	Overrides for the approval components' strings. Keys you leave out keep the default English label.

ui/src/approvals/ApprovalsProvider.tsx:36

`FileEditApprovalProps`Interface#

Props for FileEditApproval.

TypeScript

interface FileEditApprovalProps

Properties

FileEditApprovalProps properties
Name	Type	Description
className?	`string`	Extra classes on the default shell.
onDone?	`() => void`	Called once the user decided, or when the request was answered elsewhere: close the modal that holds the review.
renderShell?	`(props: ApprovalShellProps) => ReactNode`	Draws the panel around the review (an app's own modal shell). It receives the title, description, body, footer and `onClose` (which denies). Default: `ApprovalShell`.
request	`WireApprovalRequest`	The pending `edit`, `multi_edit` or `write_file` approval.
style?	`CSSProperties`	Inline styles on the default shell.

ui/src/approvals/FileEditApproval.tsx:57

`SafelistPanelProps`Interface#

Props for SafelistPanel.

TypeScript

interface SafelistPanelProps

Properties

SafelistPanelProps properties
Name	Type	Description
className?	`string`	Extra classes on the default shell.
renderShell?	`(props: ApprovalShellProps) => ReactNode`	Draws the panel around the list (an app's own modal shell). It receives the title, description and body. Default: `ApprovalShell`.
style?	`CSSProperties`	Inline styles on the default shell.

ui/src/approvals/SafelistPanel.tsx:17

Components#

ApprovalBarComponent#

Parameters

Returns

Props

ApprovalCardComponent#

Parameters

Returns

Props

ApprovalConcernComponent#

Parameters

Returns

Props

ApprovalShellComponent#

Parameters

Returns

Props

ApprovalsProviderComponent#

Parameters

Returns

Props

FileEditApprovalComponent#

Parameters

Returns

Props

SafelistPanelComponent#

Parameters

Returns

Props

Functions#

useApprovalsHostFunction#

Returns

useApprovalsLabelsFunction#

Returns

usePendingApprovalsFunction#

Returns

useResolveApprovalFunction#

Returns

useSessionApprovalHeadFunction#

Parameters

Returns

Interfaces#

ApprovalBarPropsInterface#

Properties

ApprovalCardPropsInterface#

Properties

ApprovalConcernPropsInterface#

Properties

ApprovalFramePropsInterface#

Properties

ApprovalShellPropsInterface#

Properties

ApprovalsProviderPropsInterface#

Properties

FileEditApprovalPropsInterface#

Properties

SafelistPanelPropsInterface#

Properties

`ApprovalBar`Component#

`ApprovalCard`Component#

`ApprovalConcern`Component#

`ApprovalShell`Component#

`ApprovalsProvider`Component#

`FileEditApproval`Component#

`SafelistPanel`Component#

`useApprovalsHost`Function#

`useApprovalsLabels`Function#

`usePendingApprovals`Function#

`useResolveApproval`Function#

`useSessionApprovalHead`Function#

`ApprovalBarProps`Interface#

`ApprovalCardProps`Interface#

`ApprovalConcernProps`Interface#

`ApprovalFrameProps`Interface#

`ApprovalShellProps`Interface#

`ApprovalsProviderProps`Interface#

`FileEditApprovalProps`Interface#

`SafelistPanelProps`Interface#