import type { ColorToken } from './color-token';
/**
 * Resolves CSS custom properties to literal colors for canvas and imperative APIs.
 *
 * @description
 * Lives in `shared` rather than beside the map because it is not about maps: any
 * surface that draws outside CSS — a canvas graph, a Google Maps overlay, an
 * exported image — needs a literal color and needs it to change when the theme
 * does. The map family re-exports these under their original `useMapTokenColor`
 * names, so its public API is unchanged.
 */
/**
 * Last-resort color when a token is undefined and no fallback was supplied.
 * A neutral gray reads as "unstyled" rather than impersonating a semantic state.
 */
export declare const TOKEN_COLOR_FALLBACK = "#71717A";
/**
 * Normalizes a resolved CSS color into a form the Google Maps API accepts.
 *
 * Tokens in this library resolve to either `rgba(...)` (`styles/xertica/tokens.css`)
 * or `#hex` (`contexts/theme-data.ts`). The alpha channel is deliberately
 * dropped: Google Maps applies `fillOpacity`/`strokeOpacity` on top of the
 * color, so an alpha-bearing color would be composited twice and render
 * washed out. Opacity stays the exclusive job of the opacity props.
 *
 * Anything this function cannot parse is returned untouched — Google accepts
 * most CSS3 color syntaxes, and passing the original through is better than
 * guessing wrong.
 */
export declare function normalizeCanvasColor(input: string): string;
/**
 * Resolves a CSS custom property to a literal color the Google Maps API can use,
 * and re-resolves it whenever the theme changes.
 *
 * @description
 * The Maps API consumes literal colors, so `"var(--destructive)"` never resolves
 * in `fillColor`/`strokeColor`/`iconColor`. Four consumer applications shipped
 * their own copy of this resolver to work around that, and because each resolved
 * once at mount, none of them followed a light/dark switch while the rest of the
 * interface did. This hook is the design system's answer to both halves of that
 * problem.
 *
 * @param token - Custom property name, e.g. `'--chart-1'`.
 * @param fallback - Literal color used when the token is undefined or unreadable.
 *
 * @example
 * ```tsx
 * const fill = useTokenColor('--destructive');
 * new google.maps.Circle({ fillColor: fill, fillOpacity: 0.2 });
 * ```
 */
export declare function useTokenColor(token: ColorToken, fallback?: string): string;
/**
 * Batch form of {@link useTokenColor}, for array-driven props.
 *
 * @description
 * `markers[]`, `polygons[]` and friends carry one token per entry, and a hook
 * cannot be called inside a loop. This resolves a whole set in one pass and
 * shares the same subscription and cache as the single-token hook.
 *
 * @returns A record keyed by the token names that were passed in.
 *
 * @example
 * ```tsx
 * const colors = useTokenColors(markers.map(m => m.colorToken ?? '--primary'));
 * // colors['--chart-1'] -> '#635bff'
 * ```
 */
export declare function useTokenColors(tokens: ColorToken[], fallback?: string): Record<string, string>;
/**
 * Imperative escape hatch: a stable resolver that re-identifies on theme change.
 *
 * @description
 * Useful where tokens are discovered during render — a GeoJSON choropleth whose
 * class count is data-driven, for instance — and collecting them into an array
 * ahead of the hook call would be contrived. Because the returned function's
 * identity changes with the theme, it is safe to list in a `useEffect`
 * dependency array to re-apply colors after a theme switch.
 */
export declare function useTokenColorResolver(): (token: ColorToken, fallback?: string) => string;
/**
 * Applies an alpha channel to a resolved color, producing `#rrggbbaa`.
 *
 * @description
 * DOM overlays (proportional marker discs, legend swatches) need translucency
 * baked into the color itself, because unlike `google.maps.Circle` they have no
 * separate `fillOpacity` channel — and a CSS `opacity` would fade the border and
 * the label along with the fill.
 *
 * @param color - Any value `normalizeCanvasColor` can parse; others pass through.
 * @param alpha - 0–1. Values outside the range are clamped.
 */
export declare function withAlpha(color: string, alpha: number): string;