@karni/ui 0.3.1 → 0.4.0

package/dist/src/lib/roles.d.ts

@@ -8,12 +8,12 @@
  * duplicate via a static scan of these call sites.
  *
  * Conventions:
- * - The `role` argument MUST be a string literal — the build-time scan rejects
+ * - The `role` argument MUST be a string literal. The build-time scan rejects
  *   any non-literal first argument.
  * - Same role + same component name is idempotent (modules re-evaluate under
  *   HMR and across test files).
  * - Replacing on purpose is explicit and must carry a reason:
- *   `{ replace: true, reason: "<why>" }` — an empty reason throws.
+ *   `{ replace: true, reason: "<why>" }`. An empty reason throws.
  * - Under Vite HMR (`import.meta.hot`) an accidental conflict logs a
  *   console.error and replaces instead of throwing, so a rename mid-edit does
  *   not kill the dev server.
@@ -22,11 +22,11 @@
 export interface RegisterComponentRoleOptions {
     /** Replace an existing registration on purpose. Requires `reason`. */
     replace?: boolean;
-    /** Why the replacement is intentional — required with `replace: true`. */
+    /** Why the replacement is intentional. Required with `replace: true`. */
     reason?: string;
 }
 /**
- * Test-only override for HMR detection; pass `null` to restore the default.
+ * Test-only override for HMR detection. Pass `null` to restore the default.
  * Not exported from the package barrel.
  * @internal
  */

package/dist/src/lib/variants.d.ts

@@ -2,7 +2,7 @@
  * Hand-rolled cva-style variant utility (no extra dependency).
  *
  * Every class string appears whole in source (contract D7): a variant map
- * value is a complete Tailwind class list, selected — never concatenated —
+ * value is a complete Tailwind class list, selected (never concatenated)
  * at call time and merged through cn().
  */
 /** A map of variant group name → allowed value → whole Tailwind class string. */

package/dist/src/primitives/registry.d.ts

@@ -0,0 +1,81 @@
+import { ButtonProps } from '../components/primitives/button';
+import { CheckboxProps } from '../components/primitives/checkbox';
+import { InputProps } from '../components/primitives/input';
+import { LabelProps } from '../components/primitives/label';
+import { SkeletonProps } from '../components/primitives/skeleton';
+import { SwitchProps } from '../components/primitives/switch';
+import { TextareaProps } from '../components/primitives/textarea';
+/**
+ * The primitive registry: a project renders Karni's components with its own
+ * design system's primitives.
+ *
+ *   <KarniProvider client={client} primitives={{ button: Button, input: Input }}>
+ *
+ * Every Karni primitive (Button, Input, Select's parts, ...) looks itself up
+ * here before rendering, so ResourceTable, ResourceForm and the rest render
+ * the project's button and inputs while keeping their schema-driven
+ * behaviour. A role that is not registered renders Karni's own.
+ *
+ * Contracts: a registered component receives exactly the props Karni's
+ * primitive takes (ButtonProps, InputProps, ...) and the ref. shadcn/ui's
+ * components match them as they are. Any other design system registers a
+ * small adapter. `select` is a family: Radix parts share a context, so its
+ * parts are replaced together or not at all.
+ *
+ * A registered component may wrap Karni's own (`(props) => <Button
+ * className="..." {...props} />`): inside it, that role resolves to Karni's
+ * primitive again, so the wrapper does not call itself.
+ */
+import type * as SelectPrimitive from "@radix-ui/react-select";
+import * as React from "react";
+type WithRef<P, T> = React.ComponentType<P & React.RefAttributes<T>>;
+/** The parts of a Radix-compatible select (what shadcn/ui's select.tsx exports). */
+export interface KarniSelectParts {
+    Root: React.ComponentType<SelectPrimitive.SelectProps>;
+    Trigger: WithRef<SelectPrimitive.SelectTriggerProps, HTMLButtonElement>;
+    Value: WithRef<SelectPrimitive.SelectValueProps, HTMLSpanElement>;
+    Content: WithRef<SelectPrimitive.SelectContentProps, HTMLDivElement>;
+    Item: WithRef<SelectPrimitive.SelectItemProps, HTMLDivElement>;
+    Group: WithRef<SelectPrimitive.SelectGroupProps, HTMLDivElement>;
+    Label: WithRef<SelectPrimitive.SelectLabelProps, HTMLDivElement>;
+    Separator: WithRef<SelectPrimitive.SelectSeparatorProps, HTMLDivElement>;
+}
+/** Every role a project can fill with its own component. */
+export interface KarniPrimitives {
+    button: WithRef<ButtonProps, HTMLButtonElement>;
+    input: WithRef<InputProps, HTMLInputElement>;
+    textarea: WithRef<TextareaProps, HTMLTextAreaElement>;
+    checkbox: WithRef<CheckboxProps, HTMLButtonElement>;
+    switch: WithRef<SwitchProps, HTMLButtonElement>;
+    label: WithRef<LabelProps, HTMLLabelElement>;
+    skeleton: WithRef<SkeletonProps, HTMLDivElement>;
+    select: KarniSelectParts;
+}
+/** A role that is one component (not a family of parts). */
+export type KarniPrimitiveRole = Exclude<keyof KarniPrimitives, "select">;
+/** The project's replacements: any subset of the roles. */
+export type KarniPrimitiveOverrides = Partial<KarniPrimitives>;
+export interface KarniPrimitivesProviderProps {
+    /** Role -> the project's component. Merged over any registry above it. */
+    value: KarniPrimitiveOverrides;
+    children?: React.ReactNode;
+}
+/**
+ * Registers the project's primitives for everything inside it. KarniProvider
+ * renders one from its `primitives` prop, and you can nest another to change
+ * a subtree.
+ */
+export declare function KarniPrimitivesProvider({ value, children, }: KarniPrimitivesProviderProps): React.ReactElement;
+/** The registered primitives in scope (the roles the project replaced). */
+export declare function useKarniPrimitives(): KarniPrimitiveOverrides;
+/**
+ * Makes a Karni primitive defer to the registry.
+ * @internal
+ */
+export declare function overridable<P extends object, T>(role: KarniPrimitiveRole, Default: React.ForwardRefExoticComponent<React.PropsWithoutRef<P> & React.RefAttributes<T>>): React.ForwardRefExoticComponent<React.PropsWithoutRef<P> & React.RefAttributes<T>>;
+/**
+ * Makes one part of Karni's select defer to a registered `select` family.
+ * @internal
+ */
+export declare function overridableSelectPart<K extends keyof KarniSelectParts, C extends KarniSelectParts[K]>(part: K, Default: C): C;
+export {};

package/dist/src/schema/client.d.ts

@@ -1,19 +1,19 @@
 /**
- * createKarniClient — the typed fetch wrapper every @karni/ui layer sits on
+ * createKarniClient: the typed fetch wrapper every @karni/ui layer sits on
  * (contract "Schema client" + D6).
  *
  * Responsibilities:
  * - URL joining + query-string serialization (arrays become repeated keys,
  *   null/undefined are dropped),
- * - JSON request/response handling; a FormData body is passed through
+ * - JSON request/response handling. A FormData body is passed through
  *   untouched with NO manual Content-Type (the D2 multipart rule),
  * - DRF error passthrough: non-2xx responses throw KarniApiError carrying the
  *   parsed body (field errors / detail / non_field_errors) verbatim,
  * - auth hook points per D6's client-owns-tokens design: the auth layer (not
  *   React) registers token injection, extra headers (session CSRF),
  *   credentials mode and a 401 handler via `setAuthHooks`. The client calls
- *   `onUnauthorized` at most ONCE per request and retries at most ONCE — a
- *   request that 401s again after a successful refresh is surfaced, never
+ *   `onUnauthorized` at most ONCE per request and retries at most ONCE. A
+ *   request that 401s again after a successful refresh is surfaced and never
  *   re-triggers refresh (the single-flight refresh promise itself lives in
  *   the auth layer behind this hook).
  */
@@ -27,7 +27,7 @@ export interface KarniClientOptions {
     baseUrl: string;
     /** Path of the OpenAPI document. Default "/api/schema/". */
     schemaUrl?: string;
-    /** Initial access-token getter; `setAuthHooks` can replace it later (D6). */
+    /** Initial access-token getter. `setAuthHooks` can replace it later (D6). */
     getAccessToken?: () => string | null;
     /** Custom fetch implementation (tests, SSR). Resolved per request. */
     fetch?: typeof globalThis.fetch;
@@ -50,10 +50,10 @@ export interface KarniRequestOptions {
 /**
  * Hook points the auth layer registers on the client (D6). Keys present in
  * the object passed to `setAuthHooks` override the current value (an explicit
- * `undefined` clears one); absent keys are kept.
+ * `undefined` clears one). Absent keys are kept.
  */
 export interface KarniAuthHooks {
-    /** Called before every request; a non-null return is sent as Bearer. */
+    /** Called before every request. A non-null return is sent as Bearer. */
     getAccessToken?: () => string | null;
     /**
      * Called once when a request gets a 401 (unless `skipAuthRefresh`). Return
@@ -63,10 +63,10 @@ export interface KarniAuthHooks {
     onUnauthorized?: (error: KarniApiError) => Promise<boolean>;
     /** Extra headers merged into every request (session-mode X-CSRFToken). */
     getHeaders?: () => Record<string, string>;
-    /** fetch credentials mode; session mode sets "include". */
+    /** fetch credentials mode. Session mode sets "include". */
     credentials?: RequestCredentials;
 }
-/** Thrown for non-2xx responses; `data` carries the parsed DRF error body. */
+/** Thrown for non-2xx responses, with the parsed DRF error body in `data`. */
 export declare class KarniApiError extends Error {
     readonly status: number;
     /** Parsed body when JSON (field errors, detail, non_field_errors), else text. */
@@ -79,7 +79,7 @@ export interface KarniClient {
     request<T>(path: string, options?: KarniRequestOptions): Promise<T>;
     /**
      * The same request (auth, query, 401 retry) returning the raw `Response`
-     * instead of a parsed body — for file downloads (`GET /<resource>/export/`).
+     * instead of a parsed body, for file downloads (`GET /<resource>/export/`).
      * Non-2xx responses still throw `KarniApiError` with the parsed error body.
      */
     requestRaw(path: string, options?: KarniRequestOptions): Promise<Response>;

package/dist/src/schema/parse.d.ts

@@ -74,12 +74,12 @@ export interface OpenApiDocument {
     "x-karni-auth-mode"?: string;
     [extension: string]: unknown;
 }
-/** "starts_at" → "Starts at"; "is_public" → "Is public". */
+/** "starts_at" → "Starts at", "is_public" → "Is public". */
 export declare function humanize(name: string): string;
 /**
  * Resolves $ref chains and unwraps single-member allOf, merging siblings over
  * the resolved target (so `{allOf: [$ref StatusEnum], readOnly: true}` yields
- * the enum schema plus readOnly). Cycle-guarded; a cycle resolves to {}.
+ * the enum schema plus readOnly). Cycle-guarded: a cycle resolves to {}.
  */
 export declare function resolveSchema(doc: OpenApiDocument, schema: SchemaObject | undefined, seen?: readonly string[]): SchemaObject | undefined;
 /**

package/dist/src/schema/provider.d.ts

@@ -1,13 +1,20 @@
 import { QueryClient } from '@tanstack/react-query';
 import { ReactElement, ReactNode } from 'react';
+import { KarniPrimitiveOverrides } from '../primitives/registry';
 import { KarniClient } from './client';
 export interface KarniProviderProps {
     client: KarniClient;
-    /** Bring your own QueryClient; one is created (once) when omitted. */
+    /** Bring your own QueryClient. One is created (once) when omitted. */
     queryClient?: QueryClient;
+    /**
+     * The project's own primitives, by role: `{ button: Button, input: Input }`.
+     * Every Karni component then renders them in place of Karni's (see
+     * KarniPrimitivesProvider for the contract).
+     */
+    primitives?: KarniPrimitiveOverrides;
     children?: ReactNode;
 }
-/** Provides the Karni client and a TanStack QueryClient to everything inside it; render it once at the app root. */
+/** Rendered once at the app root, it provides the Karni client and a TanStack QueryClient to everything inside it. */
 export declare function KarniProvider(props: KarniProviderProps): ReactElement;
-/** Returns the Karni client from `KarniProvider`; throws a descriptive error outside one. */
+/** Returns the Karni client from `KarniProvider` and throws a descriptive error outside one. */
 export declare function useKarniClient(): KarniClient;

package/dist/src/schema/types.d.ts

@@ -3,7 +3,7 @@
  *
  * The OpenAPI document served by the karni backend (drf-spectacular, OAS 3.0.3,
  * COMPONENT_SPLIT_REQUEST=True per api contract B14) is parsed ONCE into these
- * shapes; every generic component consumes FieldDef/ResourceSchema, never raw
+ * shapes. Every generic component consumes FieldDef/ResourceSchema, never raw
  * OpenAPI.
  */
 export type FieldKind = "string" | "text" | "number" | "integer" | "boolean" | "date" | "datetime" | "enum" | "relation" | "file" | "json" | "array" | "unknown";
@@ -24,7 +24,7 @@ export interface FieldDef {
     /** Flagged writeOnly OR present only in the request component (D1). */
     writeOnly: boolean;
     nullable: boolean;
-    /** Enum members; BlankEnum's "" and NullEnum's null are never members (D1/D3). */
+    /** Enum members. BlankEnum's "" and NullEnum's null are never members (D1/D3). */
     enumValues?: ReadonlyArray<string | number>;
     /** Choice labels by value, from drf-spectacular's "* `value` - Label" description lines. */
     enumLabels?: Readonly<Record<string, string>>;
@@ -40,23 +40,32 @@ export interface FieldDef {
     relation?: RelationRef;
     /**
      * Underlying pk value type of a relation field, derived from the property's
-     * own emitted type/format — never assumed (D3). Drives zodFor's relation
+     * own emitted type/format, never assumed (D3). Drives zodFor's relation
      * value schema (uuid string vs integer).
      */
     relationValueType?: "uuid" | "integer" | "string";
     /** Declaration order in the schema (response props first, request-only appended). */
     order: number;
 }
+/**
+ * An operation's `x-karni-access` rule as the backend publishes it: the access
+ * predicate governing the operation, e.g. `{"role": ["staff"]}`,
+ * `{"owned": "organizer"}`, `{"any": [...]}`. A display hint only: the server
+ * enforces it.
+ */
+export type KarniAccessRule = Readonly<Record<string, unknown>>;
 export interface OperationDef {
     path: string;
     method: "get" | "post" | "put" | "patch" | "delete";
     operationId?: string;
-    /** Declared query parameter names — the filter bar derives from these (D5). */
+    /** Declared query parameter names. The filter bar derives from these (D5). */
     queryParams: readonly string[];
     /** Allowed expand keys when the expand param declares an enum (D5). */
     expandEnum?: readonly string[];
     /** True when the operation declares a `search` query parameter (api B14). */
     hasSearch?: boolean;
+    /** The operation's `x-karni-access` rule, when the backend published one. */
+    access?: KarniAccessRule;
 }
 export interface ResourceSchema {
     /** Router prefix, e.g. "events" (from x-karni-resource). */
@@ -67,18 +76,18 @@ export interface ResourceSchema {
         create?: OperationDef;
         update?: OperationDef;
         remove?: OperationDef;
-        /** `GET /<resource>/export/` — the list as a CSV/XLSX file (karni.transfer, P6). */
+        /** `GET /<resource>/export/`: the list as a CSV/XLSX file (karni.transfer, P6). */
         export?: OperationDef;
-        /** `POST /<resource>/import/` — the import flow (upload, preview, commit). */
+        /** `POST /<resource>/import/`: the import flow (upload, preview, commit). */
         import?: OperationDef;
     };
-    /** Ordered by declaration; unknown constructs land as kind "unknown". */
+    /** Ordered by declaration. Unknown constructs land as kind "unknown". */
     fields: readonly FieldDef[];
 }
-/** The whole parsed registry; produced once per schema fetch by parseOpenApi. */
+/** The whole parsed registry, produced once per schema fetch by parseOpenApi. */
 export interface ParsedSchema {
     /** Keyed by router prefix (x-karni-resource). */
     resources: Record<string, ResourceSchema>;
-    /** From the schema root's x-karni-auth-mode (api B14); undefined when absent. */
+    /** From the schema root's x-karni-auth-mode (api B14). Undefined when absent. */
     authMode?: "jwt" | "session";
 }

package/dist/src/schema/useSchema.d.ts

@@ -4,7 +4,7 @@ import { ParsedSchema, ResourceSchema } from './types';
 export declare const SCHEMA_QUERY_KEY: readonly ["karni", "$schema"];
 /**
  * The whole parsed registry (resources + root x-karni-auth-mode). Internal to
- * the package — the auth layer reads `data.authMode` from here; apps use
+ * the package: the auth layer reads `data.authMode` from here. Apps use
  * useSchema(resource).
  */
 export declare function useParsedSchema(): UseQueryResult<ParsedSchema>;
@@ -12,6 +12,10 @@ export interface UseSchemaResult {
     data: ResourceSchema | undefined;
     isLoading: boolean;
     error: unknown;
+    /** Fetches the schema document again: what a "Try again" after a failed load calls. */
+    refetch?: () => void;
+    /** True while the schema document is being fetched (the first load or a retry). */
+    isFetching?: boolean;
 }
 /** Returns one resource's parsed schema (fields, types, relations, operations) from the backend's OpenAPI document, fetched once per app. */
 export declare function useSchema(resource: string): UseSchemaResult;

package/dist/src/states/ErrorState.d.ts

@@ -0,0 +1,43 @@
+import { KarniErrorContext } from './describe-error';
+import * as React from "react";
+export interface ErrorStateProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "title"> {
+    /** What failed: a KarniApiError, a fetch failure, anything. */
+    error: unknown;
+    /** What the user was doing, so the message names it ("You can't delete events"). */
+    context?: KarniErrorContext;
+    /** Offered when trying again can succeed. */
+    onRetry?: () => void;
+    /** True while the retry runs: the button shows progress after ~500ms. */
+    retrying?: boolean;
+    /** More actions next to Retry (a sign-in link, "Back to the list"). */
+    actions?: React.ReactNode;
+    /** "panel" (a bordered block, the default) or "inline" (one compact row). */
+    variant?: "panel" | "inline";
+}
+/**
+ * What a component's `Error` slot receives: every Karni component that loads
+ * data takes `slots={{ Error: YourPanel }}` with these props.
+ */
+export type ErrorSlotProps = Pick<ErrorStateProps, "error" | "context" | "onRetry" | "retrying">;
+/**
+ * What failed and what to do, in plain words (see describeError). Never shows
+ * a raw status code, but shows the server's own explanation when it gave one.
+ * Announced to screen readers when it appears.
+ */
+export declare const ErrorState: React.ForwardRefExoticComponent<ErrorStateProps & React.RefAttributes<HTMLDivElement>>;
+export interface PermissionDeniedProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "title"> {
+    /** The action that is not allowed: "create", "delete", "export". */
+    action?: string;
+    /** What it applies to: "events", "this booking". */
+    resource?: string;
+    /** Replaces the default "Ask an administrator" sentence. */
+    description?: React.ReactNode;
+    /** A way forward ("Back to the list"). */
+    actions?: React.ReactNode;
+}
+/**
+ * Says, in plain words, which action the user's role does not allow, both
+ * on screens that know before asking the server (a role check) and after
+ * a 403.
+ */
+export declare const PermissionDenied: React.ForwardRefExoticComponent<PermissionDeniedProps & React.RefAttributes<HTMLDivElement>>;

package/dist/src/states/PendingButton.d.ts

@@ -0,0 +1,16 @@
+import { ButtonProps } from '../components/primitives/button';
+import * as React from "react";
+export interface PendingButtonProps extends ButtonProps {
+    /** True while the action runs: the button is disabled and, after ~500ms, shows progress. */
+    pending?: boolean;
+    /** Announced to screen readers while pending ("Saving…"). */
+    pendingLabel?: string;
+}
+/**
+ * A button for work that takes time. While `pending` it is disabled and
+ * `aria-busy`. Once the work is slow (500ms), a spinner covers the label,
+ * which stays in the layout, so the button never changes width or freezes
+ * silently. Renders the registered `button` primitive, so it follows the
+ * project's design system.
+ */
+export declare const PendingButton: React.ForwardRefExoticComponent<PendingButtonProps & React.RefAttributes<HTMLButtonElement>>;

package/dist/src/states/describe-error.d.ts

@@ -0,0 +1,25 @@
+export type KarniErrorKind = "offline" | "network" | "unauthenticated" | "forbidden" | "not-found" | "validation" | "conflict" | "rate-limited" | "timeout" | "server" | "unknown";
+/** What the user was doing, so the message can name it ("You can't delete events."). */
+export interface KarniErrorContext {
+    /** A verb: "view", "create", "edit", "delete", "export", "import", or your own. */
+    action?: string;
+    /** What it was done to, as the sentence needs it: "events", "this event". */
+    resource?: string;
+}
+export interface KarniErrorDescription {
+    kind: KarniErrorKind;
+    /** A short headline in plain words. */
+    title: string;
+    /** What to do next. */
+    description: string;
+    /** Whether the same request can succeed if tried again. */
+    retryable: boolean;
+    /** The server's own explanation, when it gave one worth showing (never for 5xx). */
+    detail?: string;
+    /** The HTTP status, for logs and project code. Never shown to the user. */
+    status?: number;
+}
+/** Classifies `error` and words it for the person using the app. */
+export declare function describeError(error: unknown, context?: KarniErrorContext): KarniErrorDescription;
+/** `describeError(...).title`, capitalised, for one-line contexts (toasts, inline text). */
+export declare function errorSummary(error: unknown, context?: KarniErrorContext): string;

package/dist/src/states/hooks.d.ts

@@ -0,0 +1,10 @@
+/** How long a request may run before Karni shows progress (ms). */
+export declare const SLOW_AFTER_MS = 500;
+/**
+ * True once `active` has stayed true for `delayMs` (default 500ms), false as
+ * soon as it turns false. Show progress only for slow work, so a fast request
+ * never flashes a spinner.
+ */
+export declare function useDelayedFlag(active: boolean, delayMs?: number): boolean;
+/** Returns whether the browser reports a network connection and re-renders when it changes. */
+export declare function useOnlineStatus(): boolean;

package/dist/src/theme/script.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The theme's pre-paint script, with no React: shared by ThemeProvider and
+ * the `@karni/ui/vite` plugin, which runs in Node at build time.
+ */
+/** The localStorage key ThemeProvider keeps the user's choice under. */
+export declare const THEME_STORAGE_KEY = "karni-theme";
+/**
+ * Inline script for index.html's `<head>`: applies the stored (or system) theme
+ * before the first paint. Uses the default storage key. In a Vite app,
+ * `karniTheme()` from `@karni/ui/vite` puts it there.
+ */
+export declare const KARNI_THEME_SCRIPT = "(function(){try{var t=localStorage.getItem(\"karni-theme\");var d=t===\"dark\"||((t===null||t===\"system\")&&matchMedia(\"(prefers-color-scheme: dark)\").matches);document.documentElement.classList.toggle(\"dark\",d);document.documentElement.style.colorScheme=d?\"dark\":\"light\"}catch(e){}})();";

package/dist/src/theme/theme.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Light, dark or the system's choice, for the whole app.
+ *
+ *   <ThemeProvider>           // follows the system until the user picks
+ *     <App />                 // <ThemeToggle /> anywhere lets them pick
+ *   </ThemeProvider>
+ *
+ * The choice is kept per browser (localStorage) and applied as the `dark`
+ * class on <html>, which is what @karni/ui's tokens switch on. Put
+ * KARNI_THEME_SCRIPT in index.html's <head> (in a Vite app, `karniTheme()`
+ * from `@karni/ui/vite` does) so the first paint already has the right
+ * theme (no light flash before React starts).
+ */
+import * as React from "react";
+export type ThemePreference = "light" | "dark" | "system";
+export type ResolvedTheme = "light" | "dark";
+export { KARNI_THEME_SCRIPT, THEME_STORAGE_KEY } from './script';
+interface ThemeContextValue {
+    /** What the user chose ("system" follows the operating system). */
+    theme: ThemePreference;
+    /** What is applied right now. */
+    resolvedTheme: ResolvedTheme;
+    setTheme: (theme: ThemePreference) => void;
+}
+export interface ThemeProviderProps {
+    /** Used until the user chooses, "system" by default. */
+    defaultTheme?: ThemePreference;
+    /** localStorage key for the user's choice. Change it to keep apps on one origin apart. */
+    storageKey?: string;
+    /** The element that gets the `dark` class, <html> by default. */
+    target?: () => HTMLElement;
+    children?: React.ReactNode;
+}
+/** Rendered once around the app, it applies the user's theme choice and keeps it. */
+export declare function ThemeProvider({ defaultTheme, storageKey, target, children, }: ThemeProviderProps): React.ReactElement;
+/** Returns the theme choice and a setter, and throws a descriptive error outside ThemeProvider. */
+export declare function useTheme(): ThemeContextValue;
+export interface ThemeToggleProps {
+    className?: string;
+}
+/**
+ * One button that cycles Light → Dark → System. Its accessible name says the
+ * current choice and the next one ("Theme: Dark. Switch to System").
+ */
+export declare function ThemeToggle({ className }: ThemeToggleProps): React.ReactElement;