@bootnodedev/canton-dappbooster 0.3.0

package/dist/index.d.ts

@@ -0,0 +1,704 @@
+import { a as Token, i as InstrumentId, n as InstrumentBalance, o as UseTokenListResult, r as sumHoldings, t as Holding } from "./sumHoldings-BS0bHl7z.js";
+import { AnchorHTMLAttributes, FocusEventHandler, HTMLAttributes, InputHTMLAttributes, ReactElement, ReactNode } from "react";
+//#region src/components/ExplorerLink/index.d.ts
+/**
+ * Props for {@link ExplorerLink}. The label and the href are both required: the only content is an
+ * `aria-hidden` icon, and a link with nowhere to go is not rendered.
+ *
+ * @example
+ * const href = explorerLink(partyId)
+ * href !== undefined && <ExplorerLink href={href} aria-label="View party id in explorer" />
+ *
+ * @category Components
+ */
+interface ExplorerLinkProps extends Omit<AnchorHTMLAttributes<HTMLAnchorElement>, "href" | "rel" | "target"> {
+  "aria-label": string;
+  href: string;
+}
+/**
+ * An icon-only external link to a block explorer. Composes no URLs; pair it with `useExplorerLink`
+ * or `getExplorerLink`, which turn an identifier into an href.
+ *
+ * Reach for it directly when the link stands alone. Inside `Identifier` it is already the `href`
+ * slot, so pass the href there instead of nesting one.
+ *
+ * @example
+ * <ExplorerLink href="https://scan.example/party/nico" aria-label="View party id in explorer" />
+ *
+ * @see [anatomy.ts](https://github.com/BootNodeDev/canton-dappbooster/blob/main/canton-dappbooster/src/components/ExplorerLink/anatomy.ts) for the part classes and state attributes the theme selects.
+ *
+ * @category Components
+ */
+declare const ExplorerLink: ({ className, href, ...rest }: ExplorerLinkProps) => ReactElement;
+//#endregion
+//#region src/components/Identifier/truncate.d.ts
+/**
+ * Character counts overriding the display defaults of {@link truncateIdentifier}: how much to keep
+ * either side of the ellipsis, the segment length below which nothing is cut, and the bound on a
+ * party id's hint, which is otherwise kept whole however long it is.
+ *
+ * @example
+ * truncateIdentifier(partyId, { head: 4, tail: 4, threshold: 22 })
+ * truncateIdentifier(partyId, { hint: 12 })
+ *
+ * @category Utilities
+ */
+interface TruncateOptions {
+  head?: number;
+  tail?: number;
+  threshold?: number;
+  hint?: number;
+}
+/**
+ * Truncates an identifier for display. A Canton party id is `hint::fingerprint`, so the hint
+ * survives whole and only the fingerprint shrinks, unless `hint` bounds it too. Anything else is
+ * middle-truncated as one segment, never longer than the input, and cut on UTF-16 code units, so a
+ * non-ASCII value can split a surrogate pair.
+ *
+ * Reach for this over `<Identifier>` inside a sentence or another `<button>`, where the copy
+ * control would nest a button in a button. Pass `hint` where the result must fit a bounded width.
+ *
+ * @example
+ * truncateIdentifier('nico::1220df946c5b01ad0f2d2b480f1f43b1d1f2e498f5a49c2f0b1cbb46')
+ * // 'nico::1220df…0b1cbb46'
+ * truncateIdentifier('treasury-operations::1220df94…', { hint: 12 })
+ * // 'treasury-ope…::1220df94…'
+ *
+ * @category Utilities
+ */
+declare const truncateIdentifier: (value: string, options?: TruncateOptions) => string;
+/**
+ * The readable half of a party id. Returns the whole value when there is no separator. Reach for
+ * this over {@link truncateIdentifier} where the fingerprint should be dropped rather than
+ * shortened, such as a table column or a chart label.
+ *
+ * @example
+ * partyHint('nico::1220df94') // 'nico'
+ *
+ * @category Utilities
+ */
+declare const partyHint: (value: string) => string;
+//#endregion
+//#region src/hooks/useCopyToClipboard.d.ts
+/**
+ * Transient result of the last copy, for styling an affordance. Returns to `idle` on a timer.
+ *
+ * @example
+ * <button data-state={state}>{state === 'copied' ? <CheckIcon /> : <CopyIcon />}</button>
+ *
+ * @category Hooks
+ */
+type CopyState = "idle" | "copied" | "error";
+/**
+ * Result of one copy call. A rejected clipboard write is an outcome, not a thrown error.
+ *
+ * @example
+ * const outcome = await copy(partyId)
+ * if (!outcome.ok) toast.error(outcome.error.message)
+ *
+ * @category Hooks
+ */
+type CopyOutcome = {
+  ok: true;
+  value: string;
+} | {
+  ok: false;
+  error: Error;
+};
+/**
+ * How long {@link useCopyToClipboard} holds `copied`/`error` before returning to `idle`. Omitted
+ * fields fall back to a 1200 ms reset.
+ *
+ * @example
+ * useCopyToClipboard({ resetMs: 4000 }) // hold `copied` long enough to read a toast alongside it
+ *
+ * @category Hooks
+ */
+interface UseCopyToClipboardOptions {
+  resetMs?: number;
+}
+/**
+ * Return shape of {@link useCopyToClipboard}, held by callers rendering their own copy control.
+ * `<Identifier>` consumes it internally.
+ *
+ * @example
+ * const clipboard: UseCopyToClipboardResult = useCopyToClipboard()
+ * <CopyButton {...clipboard} value={partyId} />
+ *
+ * @category Hooks
+ */
+interface UseCopyToClipboardResult {
+  state: CopyState;
+  copy: (value: string) => Promise<CopyOutcome>;
+}
+/**
+ * Clipboard write with a transient result state. Callers that need their own feedback (a toast,
+ * say) use the returned outcome; callers that only need an affordance style off `state`.
+ *
+ * Reach for this over `<Identifier>` when the copy control must be a sibling of the value rather
+ * than a child of it.
+ *
+ * @example
+ * const { state, copy } = useCopyToClipboard({ resetMs: 500 })
+ * <button onClick={() => void copy(partyId)} data-state={state}>Copy</button>
+ *
+ * @category Hooks
+ */
+declare const useCopyToClipboard: (options?: UseCopyToClipboardOptions) => UseCopyToClipboardResult;
+//#endregion
+//#region src/components/Identifier/index.d.ts
+/**
+ * Props for {@link Identifier}. `label` is the accessible noun the controls are named after, and
+ * `onCopy` is the clipboard outcome, not the DOM clipboard event.
+ *
+ * @example
+ * <Identifier value={partyId} label="party id" truncate={{ head: 4, tail: 4 }} />
+ *
+ * @category Components
+ */
+interface IdentifierProps extends Omit<HTMLAttributes<HTMLSpanElement>, "onCopy"> {
+  announce?: boolean;
+  copy?: boolean;
+  href?: string;
+  label?: string;
+  onCopy?: (outcome: CopyOutcome) => void;
+  truncate?: false | TruncateOptions;
+  value: string;
+}
+/**
+ * Displays a Canton identifier: truncated for reading, copyable in full, optionally linked to an
+ * explorer. Copy always writes the whole value, never the truncated display value. The href is
+ * built by the caller; this component composes no URLs. Renders a `span`, so it is legal anywhere
+ * inline text is.
+ *
+ * @example
+ * <Identifier value={partyId} label="party id" href={explorerLink(partyId)} announce={false} />
+ *
+ * @see [anatomy.ts](https://github.com/BootNodeDev/canton-dappbooster/blob/main/canton-dappbooster/src/components/Identifier/anatomy.ts) for the part classes and state attributes the theme selects.
+ *
+ * @category Components
+ */
+declare const Identifier: ({ value, label, truncate, copy, announce, href, onCopy, className, ...rest }: IdentifierProps) => ReactElement;
+//#endregion
+//#region src/utils/partyId.d.ts
+/**
+ * Why a value is not a well-formed party id. Codes rather than sentences: L2 ships no user-facing
+ * copy, so the consumer maps these to their own wording.
+ *
+ * @example
+ * const MESSAGES: Record<PartyIdError, string> = {
+ *   'missing-separator': 'Use hint::fingerprint',
+ *   'invalid-hint': 'The hint cannot be blank or contain spaces',
+ *   'invalid-fingerprint': 'The fingerprint is 68 hex characters',
+ * }
+ *
+ * @category Utilities
+ */
+type PartyIdError = "missing-separator" | "invalid-hint" | "invalid-fingerprint";
+/**
+ * Checks the shape of a party id: a non-blank hint, the `::` separator, and a 68-character hex
+ * fingerprint. Returns `undefined` when nothing is wrong. Shape only — whether the party exists is
+ * the ledger's answer, not this function's.
+ *
+ * Reach for this over {@link isValidPartyId} when the caller needs to say what went wrong.
+ *
+ * @example
+ * validatePartyId('nico:1220df94') // 'missing-separator'
+ * validatePartyId('nico::1220df94') // 'invalid-fingerprint': 8 hex characters, not 68
+ *
+ * @category Utilities
+ */
+declare const validatePartyId: (value: string) => PartyIdError | undefined;
+/**
+ * Whether a party id is well-formed. Reach for {@link validatePartyId} instead where the reason
+ * matters.
+ *
+ * @example
+ * isValidPartyId(partyId) // true
+ * isValidPartyId('nico::1220df94') // false: 8 hex characters where 68 are required
+ *
+ * @category Utilities
+ */
+declare const isValidPartyId: (value: string) => boolean;
+//#endregion
+//#region src/components/PartyIdInput/index.d.ts
+/**
+ * Props for {@link PartyIdInput}. `onChange` reports the reason alongside the value, so the app can
+ * word the message and place it where it wants.
+ *
+ * @example
+ * <PartyIdInput
+ *   value={receiver}
+ *   onChange={(next, error) => { setReceiver(next); setError(error) }}
+ * />
+ *
+ * @category Components
+ */
+interface PartyIdInputProps extends Omit<InputHTMLAttributes<HTMLInputElement>, "onChange" | "type" | "value"> {
+  onChange: (value: string, error: PartyIdError | undefined) => void;
+  value: string;
+}
+/**
+ * A controlled text field for a Canton party id.
+ *
+ * It flags a malformed value with `aria-invalid` and hands the reason to `onChange`. Pass
+ * `aria-invalid` to flag the field for a reason the kit cannot know, such as a party the app
+ * rejects.
+ *
+ * @example
+ * <PartyIdInput value={receiver} onChange={setReceiver} aria-describedby="receiver-error" />
+ *
+ * @see [anatomy.ts](https://github.com/BootNodeDev/canton-dappbooster/blob/main/canton-dappbooster/src/components/PartyIdInput/anatomy.ts) for the part classes and state attributes the theme selects.
+ *
+ * @category Components
+ */
+declare const PartyIdInput: ({ "aria-invalid": ariaInvalid, className, onBlur, onChange, value, ...rest }: PartyIdInputProps) => ReactElement;
+//#endregion
+//#region src/utils/tokenAmount.d.ts
+/**
+ * Decimal places Daml `Decimal` (`Numeric 10`) accepts. Pass a smaller one where a token's own
+ * precision is tighter.
+ *
+ * @example
+ * parseAmount('1.5', DEFAULT_PRECISION)
+ *
+ * @category Utilities
+ */
+declare const DEFAULT_PRECISION = 10;
+/**
+ * Why an amount is not usable. Codes rather than sentences: L2 ships no user-facing copy, so the
+ * consumer maps these to their own wording.
+ *
+ * @example
+ * const MESSAGES: Record<TokenAmountError, string> = {
+ *   'not-a-number': 'Enter an amount',
+ *   'too-many-decimals': 'At most 10 decimal places',
+ *   'too-large': 'Larger than the ledger can hold',
+ *   'above-max': 'More than you hold',
+ *   'invalid-max': 'Balance unavailable',
+ * }
+ *
+ * @category Utilities
+ */
+type TokenAmountError = "not-a-number" | "too-many-decimals" | "too-large" | "above-max" | "invalid-max";
+/**
+ * Scales a decimal string to an integer at `precision`, which is the only exact way to compare two
+ * amounts. `undefined` when the value is not a decimal or carries more places than `precision` can
+ * hold, since dropping a digit would silently change the amount.
+ *
+ * Reach for {@link validateAmount} instead where the caller needs to say what went wrong.
+ *
+ * @example
+ * parseAmount('1.5') // 15000000000n
+ *
+ * @category Utilities
+ */
+declare const parseAmount: (value: string, precision?: number) => bigint | undefined;
+/**
+ * The inverse of {@link parseAmount}: a scaled integer back to a canonical decimal string with no
+ * trailing zeros.
+ *
+ * @example
+ * formatScaled(15000000000n) // '1.5'
+ *
+ * @category Utilities
+ */
+declare const formatScaled: (scaled: bigint, precision?: number) => string;
+/**
+ * Groups the integer part for reading and leaves the fraction verbatim, so a value still being
+ * typed (`1.`, `1.50`) survives. `Intl` is handed the string unparsed, which formats it exactly
+ * where the float would drift. The grouping and decimal separators are the locale's, so
+ * {@link sanitizeAmountInput} has to read the result back under the same locale.
+ *
+ * @example
+ * formatAmount('8421337.1234567891') // '8,421,337.1234567891'
+ *
+ * @category Utilities
+ */
+declare const formatAmount: (value: string, locale?: string) => string;
+/**
+ * Reduces raw field input to a decimal: grouping separators and anything that can never belong to
+ * an amount are dropped rather than flagged, so a paste of `1,234.5` lands as `1234.5`. A sign or
+ * an exponent is kept instead of stripped, so `-5` and `1.5e3` reach {@link validateAmount} as
+ * `not-a-number` rather than being salvaged into an amount nobody entered.
+ *
+ * The inverse of {@link formatAmount}, and it must be passed the same `locale`: under a
+ * comma-decimal locale a mismatched pair reads a value a thousand times too small.
+ *
+ * @example
+ * sanitizeAmountInput('.5') // '0.5'
+ *
+ * @category Utilities
+ */
+declare const sanitizeAmountInput: (input: string, locale?: string) => string;
+/**
+ * Checks an amount against the token's precision, the `Numeric 38,10` ceiling, and an optional
+ * range. Returns `undefined` when nothing is wrong, including for the empty string: empty is empty,
+ * and required-ness belongs to the form. A `max` that is not itself a decimal returns `invalid-max`
+ * rather than reading as no ceiling, so a malformed balance cannot silently uncap the amount.
+ *
+ * @example
+ * validateAmount('1.5000000001', { max: '1.5' }) // 'above-max'
+ *
+ * @category Utilities
+ */
+declare const validateAmount: (value: string, { precision, max }?: {
+  precision?: number;
+  max?: string;
+}) => TokenAmountError | undefined;
+//#endregion
+//#region src/components/TokenInput/index.d.ts
+/**
+ * The token an amount is denominated in: what the field renders, and no more. A `Token` off the
+ * list provider satisfies it, so a pick goes straight back into the field. `onTokenSelect` hands
+ * back the whole `Token`, identity included, because that is what the picker resolved.
+ *
+ * @example
+ * const CC: TokenMeta = { symbol: 'CC', logo: <CantonCoinIcon /> }
+ *
+ * @category Components
+ */
+interface TokenMeta {
+  symbol: string;
+  logo?: ReactNode;
+}
+/** @inline */
+interface TokenInputOwnProps extends Omit<HTMLAttributes<HTMLDivElement>, "aria-errormessage" | "aria-required" | "autoCapitalize" | "autoCorrect" | "autoFocus" | "children" | "enterKeyHint" | "inputMode" | "onBlur" | "onChange" | "onFocus" | "spellCheck" | "tabIndex"> {
+  balance?: string;
+  balanceState?: "loading" | "error";
+  disabled?: boolean;
+  favoriteIds?: readonly InstrumentId[];
+  label?: string;
+  onBlur?: FocusEventHandler<HTMLInputElement>;
+  onChange: (value: string, error: TokenAmountError | undefined) => void;
+  onFocus?: FocusEventHandler<HTMLInputElement>;
+  onTokenSelect?: (token: Token) => void;
+  token: TokenMeta;
+  usdValue?: string;
+  value: string;
+}
+/**
+ * Props for {@link TokenInput}.
+ *
+ * @example
+ * <TokenInput label="Amount" token={{ symbol: 'CC' }} value={amount} balance={balance}
+ *   usdValue="0.10" onChange={(next, error) => { setAmount(next); setError(error) }} />
+ *
+ * @category Components
+ */
+type TokenInputProps = TokenInputOwnProps & ({
+  label: string;
+} | {
+  "aria-label": string;
+} | {
+  "aria-labelledby": string;
+});
+/**
+ * A controlled field for a Canton token amount. The value stays a decimal string end to end, since
+ * a `number` cannot carry `Numeric 10` without losing digits; grouping separators are added for
+ * reading and stripped on the way back. Max fills from `balance`, which is also the ceiling
+ * `onChange` validates against, so the button never offers more than the field will accept.
+ * Passing `onTokenSelect` turns the symbol into a picker over the `TokenListProvider` list.
+ *
+ * @example
+ * <TokenInput label="Amount" token={{ symbol: 'CC' }} value={amount} balance={balance}
+ *   onChange={(next, error) => { setAmount(next); setError(error) }} />
+ *
+ * @see [anatomy.ts](https://github.com/BootNodeDev/canton-dappbooster/blob/main/canton-dappbooster/src/components/TokenInput/anatomy.ts) for the part classes and state attributes the theme selects.
+ *
+ * @category Components
+ */
+declare const TokenInput: ({ "aria-describedby": describedBy, "aria-invalid": ariaInvalid, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, balance, balanceState, className, disabled, favoriteIds, id, label, onBlur, onChange, onFocus, onTokenSelect, usdValue, token, value, ...rest }: TokenInputProps) => ReactElement;
+//#endregion
+//#region src/components/TokenInput/formatFigure.d.ts
+/**
+ * Overrides for {@link formatFigure}: the decimal places to round to, 2 by default and clamped to
+ * what a ledger amount holds, and the locale whose grouping and decimal separators to use, the
+ * runtime's own by default.
+ *
+ * @example
+ * formatFigure('1234.5', { places: 4, locale: 'de-DE' }) // '1.234,5000'
+ *
+ * @category Utilities
+ */
+interface FormatFigureOptions {
+  locale?: string;
+  places?: number;
+}
+/**
+ * Rounds an amount to a fixed number of decimals and groups it for reading, so a column of figures
+ * compares at a glance where {@link formatAmount} keeps every digit the ledger carries. An amount
+ * it cannot read formats to nothing rather than to a zero that would read as a real balance.
+ *
+ * @example
+ * formatFigure('1234.5') // '1,234.50'
+ * formatFigure('abc') // undefined
+ *
+ * @category Utilities
+ */
+declare const formatFigure: (value: string | undefined, { locale, places }?: FormatFigureOptions) => string | undefined;
+//#endregion
+//#region src/hooks/useExplorerLink.d.ts
+/**
+ * What an identifier points at. `update` is the ledger transaction, which scans label as one.
+ *
+ * @example
+ * getExplorerLink({ explorer, value: contractId, entity: 'contract' })
+ *
+ * @category Utilities
+ */
+type ExplorerEntity = "party" | "contract" | "update";
+/**
+ * Canton has no chain registry and no canonical explorer: scans are per-environment and per-SV,
+ * so the app resolves the base url once from its own config and hands it over.
+ *
+ * @example
+ * const explorer: ExplorerConfig = { baseUrl: 'https://scan.example' }
+ *
+ * @category Utilities
+ */
+interface ExplorerConfig {
+  baseUrl: string;
+}
+/**
+ * Arguments for {@link getExplorerLink}.
+ *
+ * @example
+ * getExplorerLink({ explorer, value: partyId })
+ *
+ * @category Utilities
+ */
+interface GetExplorerLinkParams {
+  explorer: ExplorerConfig;
+  value: string;
+  entity?: ExplorerEntity;
+}
+/**
+ * Builds an explorer URL for a Canton identifier. Returns `undefined` whenever no link can be made.
+ *
+ * @throws when `explorer.baseUrl` is empty or blank, which is a misconfigured app rather than a
+ * missing link.
+ *
+ * @example
+ * getExplorerLink({ explorer, value: partyId })
+ * // 'https://scan.example/party/…', the party shape having matched on its own
+ * getExplorerLink({ explorer, value: '1220df94a1', entity: 'update' })
+ * // 'https://scan.example/update/1220df94a1', the entity overriding a shape that matched nothing
+ * getExplorerLink({ explorer, value: 'nico' })
+ * // undefined: no shape matched, and no entity said otherwise
+ *
+ * @category Utilities
+ */
+declare const getExplorerLink: ({ explorer, value, entity }: GetExplorerLinkParams) => string | undefined;
+/**
+ * Holds an explorer config so call sites pass only an identifier, and returns
+ * {@link getExplorerLink} bound to it.
+ *
+ * @throws on render when `explorer.baseUrl` is empty or blank, as {@link getExplorerLink} does.
+ *
+ * @example
+ * const explorerLink = useExplorerLink({ baseUrl: 'https://scan.example' })
+ * <Identifier value={partyId} href={explorerLink(partyId)} />
+ * <Identifier value={cid} href={explorerLink(cid, 'contract')} />
+ * // no href at all where the value matched no shape and no entity said otherwise
+ *
+ * @category Hooks
+ */
+declare const useExplorerLink: (explorer: ExplorerConfig) => ((value: string, entity?: ExplorerEntity) => string | undefined);
+//#endregion
+//#region src/providers/ThemeProvider/index.d.ts
+/**
+ * Props for {@link ThemeProvider}. `storageKey` isolates two apps sharing an origin; it is read on
+ * mount, so changing it later moves where writes go without re-reading the new key.
+ *
+ * @example
+ * <ThemeProvider storageKey="vesting-theme">{children}</ThemeProvider>
+ *
+ * @category Components
+ */
+interface ThemeProviderProps {
+  children: ReactNode;
+  storageKey?: string;
+}
+/**
+ * Owns the light / dark / system choice: persists it, follows the OS while on `system`, tracks the
+ * key across tabs, and writes the resolved value to `data-theme` on `<html>`, which is what
+ * `@bootnodedev/canton-theme` keys its dark values on. Renders no DOM of its own.
+ *
+ * The attribute lands before the tree below it paints, but not before the page background; that
+ * flash is accepted, and `architecture.md` has the reasoning. Client-only, because it reads the OS
+ * preference while picking its initial state, so a server render throws.
+ *
+ * @see [anatomy.ts](https://github.com/BootNodeDev/canton-dappbooster/blob/main/canton-dappbooster/src/providers/ThemeProvider/anatomy.ts) for the state attribute the theme selects.
+ *
+ * @example
+ * createRoot(el).render(
+ *   <ThemeProvider>
+ *     <App />
+ *   </ThemeProvider>,
+ * )
+ *
+ * @category Components
+ */
+declare const ThemeProvider: ({ children, storageKey }: ThemeProviderProps) => ReactElement;
+//#endregion
+//#region src/providers/ThemeProvider/context.d.ts
+/**
+ * What the user picked. `system` defers to the OS and keeps following it.
+ *
+ * @example
+ * setMode('system') // keeps following the OS afterwards, unlike setMode(resolved)
+ *
+ * @category Hooks
+ */
+type ThemeMode = "light" | "dark" | "system";
+/**
+ * What is actually on the document: `system` resolved against the OS preference.
+ *
+ * @example
+ * const sheet: Record<ResolvedTheme, string> = { light: lightSheet, dark: darkSheet }
+ *
+ * @category Hooks
+ */
+type ResolvedTheme = "light" | "dark";
+/**
+ * Return shape of {@link useTheme}. `toggle` is a two-way switch: it leaves `system` for the
+ * opposite of what is showing.
+ *
+ * @example
+ * const { mode, resolved } = useTheme()
+ * mode === 'system' ? `Auto (${resolved})` : mode // 'Auto (dark)' vs 'light'
+ *
+ * @category Hooks
+ */
+interface UseThemeResult {
+  mode: ThemeMode;
+  resolved: ResolvedTheme;
+  setMode: (mode: ThemeMode) => void;
+  toggle: () => void;
+}
+//#endregion
+//#region src/providers/ThemeProvider/useTheme.d.ts
+/**
+ * Reads and sets the theme mode.
+ *
+ * @throws with no {@link ThemeProvider} above it. There is no ambient fallback, because a control
+ * that silently fails to switch is worse than one that throws in dev.
+ *
+ * @example
+ * const { resolved, toggle } = useTheme()
+ * <button onClick={toggle}>{resolved === 'dark' ? 'Light' : 'Dark'} mode</button>
+ *
+ * @category Hooks
+ */
+declare const useTheme: () => UseThemeResult;
+//#endregion
+//#region src/providers/TokenListProvider/index.d.ts
+/**
+ * Props for {@link TokenListProvider}. `tokens` is read by identity, so hoist the array or memoise
+ * it; a fresh one on every render rebuilds the lookup map.
+ *
+ * @example
+ * <TokenListProvider tokens={mockTokens}>{children}</TokenListProvider>
+ *
+ * @category Components
+ */
+interface TokenListProviderProps {
+  children: ReactNode;
+  tokens: readonly Token[];
+}
+/**
+ * Supplies the token list every picker in the tree chooses from.
+ *
+ * @example
+ * <TokenListProvider tokens={tokens}>
+ *   <TokenInput label="Amount" token={selected} value={amount} onChange={setAmount}
+ *     onTokenSelect={setSelected} />
+ * </TokenListProvider>
+ *
+ * @category Components
+ */
+declare const TokenListProvider: ({ children, tokens }: TokenListProviderProps) => ReactElement;
+//#endregion
+//#region src/providers/TokenListProvider/useTokenList.d.ts
+/**
+ * Reads the token list a {@link TokenListProvider} supplies. Reach for it where a screen renders
+ * its own token UI; `<TokenInput onTokenSelect>` already reads it itself.
+ *
+ * @throws with no {@link TokenListProvider} above it.
+ *
+ * @example
+ * const { tokens } = useTokenList()
+ * tokens.map((token) => <TokenRow key={tokenKey(token.instrumentId)} token={token} />)
+ *
+ * @category Hooks
+ */
+declare const useTokenList: () => UseTokenListResult;
+//#endregion
+//#region src/utils/mergeTokens.d.ts
+/**
+ * What one source knows about a token: its instrument id, and whichever fields it can fill.
+ *
+ * @example
+ * const fromRegistry: PartialToken[] = [{ instrumentId, name: 'Canton Coin', symbol: 'CC' }]
+ *
+ * @category Utilities
+ */
+type PartialToken = Partial<Omit<Token, "instrumentId">> & {
+  instrumentId: InstrumentId;
+};
+/**
+ * Builds one row per instrument out of every source that knows about it, later sources winning
+ * field by field. A row is a token the picker can offer, so the union is the catalogue and a
+ * holdings source only annotates it: a token nobody holds is still a row, and one nothing named is
+ * a row under its own id.
+ *
+ * @example
+ * mergeTokens([[{ instrumentId, symbol: 'CC' }], sumHoldings(holdings)])
+ *
+ * @category Utilities
+ */
+declare const mergeTokens: (sources: readonly (readonly PartialToken[])[]) => readonly Token[];
+//#endregion
+//#region src/utils/readInstruments.d.ts
+/**
+ * What a registry says about one instrument it administers. No logo: the metadata API serves none,
+ * so artwork comes from the app or from a curated list.
+ *
+ * @example
+ * const [{ name, symbol }] = await readInstruments(registryUrl)
+ *
+ * @category Utilities
+ */
+interface Instrument {
+  decimals: number;
+  instrumentId: InstrumentId;
+  name: string;
+  symbol: string;
+}
+/**
+ * Reads a registry's instrument metadata, following its pages up to a limit of 100, so the answer
+ * is the registry's whole catalogue and a registry that will not stop paging cannot hang the caller.
+ *
+ * @throws where either request answers anything but 200, or the reply is not JSON.
+ *
+ * @example
+ * const instruments = await readInstruments('https://registry.example/api')
+ *
+ * @category Utilities
+ */
+declare const readInstruments: (registryUrl: string) => Promise<readonly Instrument[]>;
+//#endregion
+//#region src/utils/tokenKey.d.ts
+/**
+ * The string identity of an instrument, for a map key, a React key or an equality check. Compare
+ * these rather than the `id` alone: two registries can both issue a `USDC`.
+ *
+ * @example
+ * tokenKey({ admin: 'DSO::1220ab', id: 'Amulet' }) // 'DSO::1220ab/Amulet'
+ *
+ * @category Utilities
+ */
+declare const tokenKey: ({ admin, id }: InstrumentId) => string;
+//#endregion
+export { type CopyOutcome, type CopyState, DEFAULT_PRECISION, type ExplorerConfig, type ExplorerEntity, ExplorerLink, type ExplorerLinkProps, type FormatFigureOptions, type GetExplorerLinkParams, type Holding, Identifier, type IdentifierProps, type Instrument, type InstrumentBalance, type InstrumentId, type PartialToken, type PartyIdError, PartyIdInput, type PartyIdInputProps, type ResolvedTheme, type ThemeMode, ThemeProvider, type ThemeProviderProps, type Token, type TokenAmountError, TokenInput, type TokenInputProps, TokenListProvider, type TokenListProviderProps, type TokenMeta, type TruncateOptions, type UseCopyToClipboardOptions, type UseCopyToClipboardResult, type UseThemeResult, type UseTokenListResult, formatAmount, formatFigure, formatScaled, getExplorerLink, isValidPartyId, mergeTokens, parseAmount, partyHint, readInstruments, sanitizeAmountInput, sumHoldings, tokenKey, truncateIdentifier, useCopyToClipboard, useExplorerLink, useTheme, useTokenList, validateAmount, validatePartyId };