@karni/ui 0.3.1 → 0.4.0

package/dist/manifest.json

@@ -16,16 +16,23 @@
     "DropdownMenuSeparator",
     "DropdownMenuTrigger",
     "EmptyState",
+    "EmptyValue",
+    "ErrorState",
     "FileUpload",
     "Input",
     "KarniMark",
+    "KarniPrimitivesProvider",
     "KarniProvider",
     "Label",
     "Layout",
     "LoginForm",
     "Modal",
     "ModalClose",
+    "ModalDescription",
+    "ModalTitle",
     "Page",
+    "PendingButton",
+    "PermissionDenied",
     "ResourceDetail",
     "ResourceForm",
     "ResourceImport",
@@ -48,21 +55,28 @@
     "TabsList",
     "TabsTrigger",
     "Textarea",
+    "ThemeProvider",
+    "ThemeToggle",
     "Toaster"
   ],
   "hooks": [
     "useAuth",
     "useChangeHistory",
+    "useDelayedFlag",
     "useImportActions",
     "useImportDescribe",
     "useImportJob",
     "useKarniClient",
+    "useKarniPrimitives",
+    "useOnlineStatus",
     "usePermission",
     "useResourceItem",
     "useResourceList",
     "useResourceMutations",
     "useSchema",
-    "useToast"
+    "useTheme",
+    "useToast",
+    "useUnsavedChangesGuard"
   ],
   "roles": {
     "async-select": "ResourceSelect",
@@ -72,14 +86,17 @@
     "data-table": "ResourceTable",
     "detail-view": "ResourceDetail",
     "empty-state": "EmptyState",
+    "error-state": "ErrorState",
     "file-upload": "FileUpload",
     "layout-shell": "Layout",
     "login-form": "LoginForm",
     "modal": "Modal",
     "page-shell": "Page",
+    "permission-denied": "PermissionDenied",
     "resource-form": "ResourceForm",
     "resource-import": "ResourceImport",
     "stat": "Stat",
+    "theme-toggle": "ThemeToggle",
     "toast": "Toaster"
   }
 }

package/dist/script-BVJ9BbPm.cjs

@@ -0,0 +1,2 @@
+var e=`karni-theme`,t=`(function(){try{var t=localStorage.getItem("${e}");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){}})();`;Object.defineProperty(exports,"n",{enumerable:!0,get:function(){return e}}),Object.defineProperty(exports,"t",{enumerable:!0,get:function(){return t}});
+//# sourceMappingURL=script-BVJ9BbPm.cjs.map

package/dist/script-BVJ9BbPm.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"script-BVJ9BbPm.cjs","names":["THEME_STORAGE_KEY","KARNI_THEME_SCRIPT"],"sources":["../src/theme/script.ts"],"sourcesContent":["/**\n * The theme's pre-paint script, with no React: shared by ThemeProvider and\n * the `@karni/ui/vite` plugin, which runs in Node at build time.\n */\n\n/** The localStorage key ThemeProvider keeps the user's choice under. */\nexport const THEME_STORAGE_KEY = \"karni-theme\";\n\n/**\n * Inline script for index.html's `<head>`: applies the stored (or system) theme\n * before the first paint. Uses the default storage key. In a Vite app,\n * `karniTheme()` from `@karni/ui/vite` puts it there.\n */\nexport const KARNI_THEME_SCRIPT = `(function(){try{var t=localStorage.getItem(\"${THEME_STORAGE_KEY}\");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){}})();`;\n"],"mappings":"AAMA,IAAaA,EAAoB,cAOpBC,EAAqB,+CAA+CD,EAAkB,qO"}

package/dist/script-D1fn4Dm4.js

@@ -0,0 +1,6 @@
+//#region src/theme/script.ts
+var e = "karni-theme", t = `(function(){try{var t=localStorage.getItem("${e}");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){}})();`;
+//#endregion
+export { e as n, t };
+
+//# sourceMappingURL=script-D1fn4Dm4.js.map

package/dist/script-D1fn4Dm4.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"script-D1fn4Dm4.js","names":["THEME_STORAGE_KEY","KARNI_THEME_SCRIPT"],"sources":["../src/theme/script.ts"],"sourcesContent":["/**\n * The theme's pre-paint script, with no React: shared by ThemeProvider and\n * the `@karni/ui/vite` plugin, which runs in Node at build time.\n */\n\n/** The localStorage key ThemeProvider keeps the user's choice under. */\nexport const THEME_STORAGE_KEY = \"karni-theme\";\n\n/**\n * Inline script for index.html's `<head>`: applies the stored (or system) theme\n * before the first paint. Uses the default storage key. In a Vite app,\n * `karniTheme()` from `@karni/ui/vite` puts it there.\n */\nexport const KARNI_THEME_SCRIPT = `(function(){try{var t=localStorage.getItem(\"${THEME_STORAGE_KEY}\");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){}})();`;\n"],"mappings":";AAMA,IAAaA,IAAoB,eAOpBC,IAAqB,+CAA+CD,EAAkB"}

package/dist/src/auth/AuthGuard.d.ts

@@ -1,12 +1,77 @@
 import { ReactElement, ReactNode } from 'react';
+import { KarniUser } from './types';
+/**
+ * <AuthGuard> renders children only for authenticated users (optionally
+ * holding one of the given roles). Otherwise it renders a fallback or says
+ * why, in plain words (contract "Hooks + auth").
+ *
+ * Two different refusals: with `explain`, a visitor who is not signed in sees
+ * a sign-in prompt (the `Anonymous` slot: a LoginForm, so signing in reveals
+ * the content in place) and a signed-in user whose role lacks access sees
+ * PermissionDenied (the `Denied` slot). `anonymous` / `denied` render your own
+ * node for one of them, and `fallback` (one node for both) keeps working.
+ *
+ * Deprecation (0.4 → 1.0): a guard with none of `explain`, `fallback`,
+ * `anonymous`, `denied` or `slots` renders nothing when it refuses, as in
+ * 0.3, and warns once in development. 1.0 makes `explain` the default. A
+ * guard that hides a piece of UI passes `fallback={null}`.
+ *
+ * While the initial auth state resolves, the `loading` slot renders
+ * (default: nothing) so protected content never flashes a login screen
+ * during session restore.
+ */
+import * as React from "react";
+/** What the `Anonymous` slot receives: nobody is signed in. */
+export interface AuthGuardAnonymousProps {
+    /** The roles the content needs, when the guard names some. */
+    roles: readonly string[];
+    className?: string;
+}
+/** What the `Denied` slot receives: someone is signed in, and no role of theirs is in `roles`. */
+export interface AuthGuardDeniedProps {
+    user: KarniUser;
+    /** The roles the content needs. */
+    roles: readonly string[];
+    className?: string;
+}
+/**
+ * The replaceable refusals of AuthGuard. Pass any subset as `slots`.
+ * `defaultAuthGuardSlots` holds Karni's own, to wrap them.
+ */
+export interface AuthGuardSlots {
+    /** Not signed in: a sign-in prompt. */
+    Anonymous: React.ComponentType<AuthGuardAnonymousProps>;
+    /** Signed in without the role: PermissionDenied. */
+    Denied: React.ComponentType<AuthGuardDeniedProps>;
+}
 export interface AuthGuardProps {
     /** Grant access when the user holds AT LEAST ONE of these role names. */
     roles?: string[];
-    /** Rendered for anonymous users and role mismatches; default nothing. */
+    /**
+     * Rendered for anonymous users and role mismatches alike. `anonymous` and
+     * `denied` (or `slots`) are preferred: they say which of the two it is.
+     * `null` renders nothing.
+     */
     fallback?: ReactNode;
-    /** Rendered while the auth status is still "loading"; default nothing. */
+    /** Rendered for a visitor who is not signed in (wins over `fallback`). */
+    anonymous?: ReactNode;
+    /** Rendered for a signed-in user whose role lacks access (wins over `fallback`). */
+    denied?: ReactNode;
+    /** Rendered while the auth status is still "loading". Default: nothing. */
     loading?: ReactNode;
+    /** Replace the default refusals: Anonymous (sign-in prompt), Denied (PermissionDenied). */
+    slots?: Partial<AuthGuardSlots>;
+    /**
+     * Say why instead of rendering nothing: the sign-in prompt for a visitor,
+     * PermissionDenied for a role mismatch. It is the default from 1.0. Until
+     * then a guard with no fallback and no `explain` renders nothing (and warns).
+     */
+    explain?: boolean;
+    /** Merged onto the default refusal's root. */
+    className?: string;
     children?: ReactNode;
 }
-/** Renders its children only for a signed-in user, optionally with one of the given roles; otherwise its `fallback`. */
-export declare function AuthGuard({ roles, fallback, loading, children, }: AuthGuardProps): ReactElement | null;
+/** Karni's own slots, exported so a project can wrap one instead of rewriting it. */
+export declare const defaultAuthGuardSlots: AuthGuardSlots;
+/** Renders its children only for a signed-in user, optionally with one of the given roles, and otherwise says why. */
+export declare function AuthGuard(props: AuthGuardProps): ReactElement | null;

package/dist/src/auth/LoginForm.d.ts

@@ -1,29 +1,63 @@
+import { KarniErrorDescription } from '../states/describe-error';
+import { ErrorSlotProps } from '../states/ErrorState';
 import { KarniUser } from './types';
 /**
- * LoginForm — the sign-in form every app needs (contract: auth).
+ * LoginForm is the sign-in form every app needs (contract: auth).
  *
  * Email + password against `useAuth().login`, with the error inline. On
  * success it calls `onSuccess(user)` (navigate there). When the backend's
  * 2FA gate fires, `on2FA` receives the ephemeral token so the app can render
- * its code step (`POST <authBasePath>/2fa/login/`); without a handler the
+ * its code step (`POST <authBasePath>/2fa/login/`). Without a handler the
  * form explains that a code is required. Render it inside `AuthProvider`,
  * e.g. as `AuthGuard`'s `fallback`.
  */
 import * as React from "react";
+/** What the `Error` slot receives: ErrorSlotProps plus the message, already worded for sign-in. */
+export interface LoginFormErrorProps extends ErrorSlotProps {
+    /** Put this id on the message's root: the inputs' `aria-describedby` points at it. */
+    id: string;
+    /**
+     * The failure in plain words: wrong credentials ("That email and password
+     * do not match"), throttling ("Wait 42 seconds"), offline, a server error.
+     */
+    described: KarniErrorDescription;
+}
+/**
+ * The replaceable parts of LoginForm. Pass any subset as `slots`.
+ * `defaultLoginFormSlots` holds Karni's own, to wrap them.
+ */
+export interface LoginFormSlots {
+    /** The message under the fields when signing in fails (announced as an alert). */
+    Error: React.ComponentType<LoginFormErrorProps>;
+}
 export interface LoginFormProps {
-    /** Called with the signed-in user; navigate from here. */
+    /** Called with the signed-in user. Navigate from here. */
     onSuccess?: (user: KarniUser) => void;
     /** Called when the account needs a second factor (the token completes it). */
     on2FA?: (ephemeralToken: string) => void;
-    /** Heading above the fields; `null` renders none. Default "Sign in". */
+    /** Heading above the fields. `null` renders none. Default "Sign in". */
     title?: React.ReactNode;
     /** Text under the heading (demo logins, a signup link, ...). */
     description?: React.ReactNode;
     /** The submit button's label. Default "Sign in". */
     submitLabel?: React.ReactNode;
-    /** Shown while the auth status is "loading" is irrelevant here; this disables the form. */
+    /** Disables the form (e.g. while the auth status is still "loading"). */
     disabled?: boolean;
+    /** Focus the email field when the form appears. Default true: signing in is the page's purpose. */
+    autoFocus?: boolean;
+    /** Replace parts of the form: Error. */
+    slots?: Partial<LoginFormSlots>;
     className?: string;
 }
-/** Email and password sign-in form with inline errors and a callback for the two-factor step. */
-export declare function LoginForm({ onSuccess, on2FA, title, description, submitLabel, disabled, className, }: LoginFormProps): React.JSX.Element;
+/** Karni's own slots, exported so a project can wrap one instead of rewriting it. */
+export declare const defaultLoginFormSlots: LoginFormSlots;
+/**
+ * Email and password sign-in form with inline errors and a callback for the two-factor step.
+ *
+ * Wrong credentials, throttling, a dropped connection and a server error each
+ * read differently. The message is announced, both fields point at it
+ * (`aria-describedby`) and are marked invalid when they are the problem.
+ * After a failure the email stays. Wrong credentials clear the password and
+ * focus it. Escape hatch: `slots.Error`.
+ */
+export declare function LoginForm({ onSuccess, on2FA, title, description, submitLabel, disabled, autoFocus, slots, className, }: LoginFormProps): React.JSX.Element;

package/dist/src/auth/engine.d.ts

@@ -14,8 +14,9 @@ export interface AuthEngineOptions {
     /** Path prefix of the auth endpoints, relative to the client's baseUrl. */
     authBasePath?: string;
     /**
-     * Reads whatever the schema loader cached under karniKeys.schema() —
-     * consulted (shape-guarded) for `authMode` before fetching the document.
+     * Reads whatever the schema loader cached under karniKeys.schema(). The
+     * engine consults it (shape-guarded) for `authMode` before fetching the
+     * document.
      */
     readCachedSchema?: () => unknown;
 }
@@ -49,16 +50,16 @@ export declare class AuthEngine {
     /** Registers the D6 hook points on the client. Idempotent. */
     attach(): void;
     /**
-     * Clears every hook this engine registered (including a `getAccessToken`
-     * the app passed to createKarniClient — an unmounted AuthProvider leaves
-     * the client fully unauthenticated by design).
+     * Clears every hook this engine registered, including a `getAccessToken`
+     * the app passed to createKarniClient. An unmounted AuthProvider leaves
+     * the client fully unauthenticated by design.
      */
     detach(): void;
     private csrfHeaders;
     /**
      * The client calls this at most once per 401-ing request (D6). Returning
      * true makes the client retry that request exactly once with
-     * freshly-injected credentials; the retry's outcome is always surfaced.
+     * freshly-injected credentials. The retry's outcome is always surfaced.
      */
     private handleUnauthorized;
     readonly subscribe: (listener: () => void) => (() => void);
@@ -68,16 +69,16 @@ export declare class AuthEngine {
     ensureInitialized(): Promise<void>;
     private initialize;
     private fetchSchemaAuthMode;
-    /** Fetches `/me/` and mirrors the result; any failure means anonymous. */
+    /** Fetches `/me/` and mirrors the result. Any failure means anonymous. */
     private syncUser;
     /**
      * Reads the CSRF cookie, bootstrapping it via `GET <authBasePath>/csrf/`
      * when absent (A4). Returns null when the cookie stays unreadable (e.g.
-     * CSRF_COOKIE_HTTPONLY) — requests then go out without the header and the
+     * CSRF_COOKIE_HTTPONLY). Requests then go out without the header and the
      * backend's 403 surfaces, which is the honest failure mode.
      */
     private ensureCsrfToken;
-    /** ONE shared in-flight refresh; resolves true on success. */
+    /** ONE shared in-flight refresh. Resolves true on success. */
     private ensureRefresh;
     private performRefresh;
     login(email: string, password: string): Promise<LoginResult>;
@@ -85,10 +86,11 @@ export declare class AuthEngine {
     /** Best-effort server logout, then always clears local state (anonymous). */
     logout(): Promise<void>;
     /**
-     * Adopts tokens issued out of band — what `@karni/impersonation-ui` does
-     * when a support user starts or stops impersonating (the backend answers
-     * with tokens for the other identity). JWT mode only; in session mode the
-     * server-side session already changed, so this just re-syncs `/me/`.
+     * Adopts tokens issued out of band, which is what
+     * `@karni/impersonation-ui` does when a support user starts or stops
+     * impersonating (the backend answers with tokens for the other identity).
+     * JWT mode only. In session mode the server-side session already changed,
+     * so this just re-syncs `/me/`.
      */
     adoptTokens(access: string | null, refresh: string | null): Promise<void>;
     /**

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

@@ -3,18 +3,18 @@ import { TokenStorage } from './storage';
 import { AuthStatus, KarniUser, LoginResult } from './types';
 export interface AuthProviderProps {
     /**
-     * "jwt" | "session"; when omitted, the mode comes from the schema root's
+     * "jwt" | "session". When omitted, the mode comes from the schema root's
      * x-karni-auth-mode (D6), falling back to "jwt" when the schema does not
      * declare one.
      */
     mode?: "jwt" | "session";
-    /** JWT mode refresh-token storage; default localStorage adapter. */
+    /** JWT mode refresh-token storage. Defaults to the localStorage adapter. */
     tokenStorage?: TokenStorage;
-    /** Session mode CSRF cookie name; default "csrftoken" (D6/A4). */
+    /** Session mode CSRF cookie name. Default "csrftoken" (D6/A4). */
     csrfCookieName?: string;
-    /** Session mode CSRF header name; default "X-CSRFToken" (D6/A4). */
+    /** Session mode CSRF header name. Default "X-CSRFToken" (D6/A4). */
     csrfHeaderName?: string;
-    /** Path prefix of the auth endpoints relative to baseUrl; default "/auth". */
+    /** Path prefix of the auth endpoints relative to baseUrl. Default "/auth". */
     authBasePath?: string;
     children?: ReactNode;
 }
@@ -26,18 +26,18 @@ export interface AuthContextValue {
     logout(): Promise<void>;
     refresh(): Promise<void>;
     /**
-     * Adopts tokens issued out of band (JWT mode; session mode re-syncs `/me/`),
-     * e.g. after starting or stopping an impersonated session.
+     * Adopts tokens issued out of band (JWT mode, or a `/me/` re-sync in session
+     * mode), e.g. after starting or stopping an impersonated session.
      */
     adoptTokens(access: string | null, refresh: string | null): Promise<void>;
 }
 /**
  * The React mirror of the auth engine's state. Exported for advanced
- * composition (stories, tests, custom providers); application code should
+ * composition (stories, tests, custom providers). Application code should
  * use <AuthProvider> + useAuth().
  */
 export declare const AuthContext: import('react').Context<AuthContextValue | null>;
-/** Holds the signed-in user and attaches credentials (JWT or session) to every request; render it inside `KarniProvider`. */
+/** Rendered inside `KarniProvider`, it holds the signed-in user and attaches credentials (JWT or session) to every request. */
 export declare function AuthProvider({ mode, tokenStorage, csrfCookieName, csrfHeaderName, authBasePath, children, }: AuthProviderProps): ReactElement;
-/** Returns the signed-in user, auth status, `login` and `logout`; throws a descriptive error outside `AuthProvider`. */
+/** Returns the signed-in user, auth status, `login` and `logout`, and throws a descriptive error outside `AuthProvider`. */
 export declare function useAuth(): AuthContextValue;

package/dist/src/auth/storage.d.ts

@@ -13,7 +13,7 @@ export interface TokenStorage {
     clear(): void;
 }
 /**
- * Keeps the refresh token in localStorage; the default storage. `key` defaults to "karni.refreshToken". Every storage
+ * The default storage, which keeps the refresh token in localStorage. `key` defaults to "karni.refreshToken". Every storage
  * access is guarded: when localStorage is unavailable (SSR, private windows,
  * blocked site data) the adapter degrades to a no-op that returns `null`
  * instead of throwing.

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

@@ -3,7 +3,7 @@
  */
 /**
  * Shape of the `/api/auth/me/` response. The accounts contract (A15)
- * guarantees `roles: string[]` on MeSerializer; every other field the
+ * guarantees `roles: string[]` on MeSerializer. Every other field the
  * backend's user serializer exposes rides along via the index signature.
  */
 export interface KarniUser {
@@ -19,8 +19,8 @@ export interface KarniUser {
 export type AuthStatus = "loading" | "authenticated" | "anonymous";
 /**
  * Discriminated login result (D6). When the backend's 2FA gate fires
- * (accounts A6), `login()` resolves `{ requires2fa, ephemeralToken }` —
- * the 2FA UI is out of scope in v0.1, so consumers exchange the ephemeral
+ * (accounts A6), `login()` resolves `{ requires2fa, ephemeralToken }`.
+ * The 2FA UI is out of scope in v0.1, so consumers exchange the ephemeral
  * token themselves via `POST /api/auth/2fa/login/`.
  */
 export type LoginResult = {

package/dist/src/components/brand/karni-mark.d.ts

@@ -4,17 +4,17 @@ export interface KarniMarkProps extends Omit<React.SVGAttributes<SVGSVGElement>,
     size?: number;
     /**
      * Which drawing: the full mark, the small-size variant, or `auto` (the
-     * default) — the small variant at 32px and below, the full mark above.
+     * default): the small variant at 32px and below, the full mark above.
      */
     variant?: "auto" | "full" | "simple";
-    /** Accessible name; pass an empty string to hide a purely decorative mark. */
+    /** Accessible name. Pass an empty string to hide a purely decorative mark. */
     title?: string;
 }
 /**
- * The Karni mark, inline SVG — no asset to load or bundle.
+ * The Karni mark as inline SVG, so there is no asset to load or bundle.
  *
  * It is the default content of `<Layout>`'s `sidebarHeader` slot so a bare
- * shell is never nameless; a project replaces it by passing its own
+ * shell is never nameless. A project replaces it by passing its own
  * `sidebarHeader` (the scaffold already does). Do not recolour or restyle it:
  * the mark is Karni's, see assets/brand/README.md in the repository.
  */

package/dist/src/components/chart/data-chart.d.ts

@@ -3,14 +3,16 @@ import * as React from "react";
  * In-house SVG chart (contract: no chart dependency).
  *
  * Accessibility model (contract D10): the SVG is a labelled image
- * (role="img" + aria-label + <title>/<desc>); the REAL accessible data
- * surface is a visually-hidden <table> rendered next to it. The hover
- * tooltip is a visual-only affordance rendered OUTSIDE the role="img"
- * element and hidden from assistive tech.
+ * (role="img" + aria-label + <title>/<desc>) described by a generated
+ * summary (the range of each series). The REAL accessible data surface is a
+ * visually-hidden <table> rendered next to it. The tooltip is rendered
+ * OUTSIDE the role="img" element and hidden from assistive tech. The SVG is
+ * focusable, the arrow keys move the tooltip from point to point, and each
+ * point is announced through a polite live region.
  *
  * Colors come exclusively from the --karni-chart-1..5 tokens, via the
  * Tailwind preset's chart color scale (stroke-chart-N / fill-chart-N /
- * bg-chart-N classes — whole class names, per contract D7).
+ * bg-chart-N classes, whole class names per contract D7).
  */
 export type DataChartKind = "line" | "bar";
 export interface DataChartPoint {
@@ -31,23 +33,64 @@ export interface DataChartTooltipContext {
         swatchClassName: string;
     }>;
 }
+/** What the `Tooltip` slot receives: the hovered (or keyboard-selected) category. */
+export interface DataChartTooltipProps extends DataChartTooltipContext {
+    valueFormatter: (value: number) => string;
+}
+/** What the `Legend` slot receives. */
+export interface DataChartLegendProps {
+    series: ReadonlyArray<{
+        name: string;
+        swatchClassName: string;
+    }>;
+}
+/** What the `Empty` slot receives (no plottable data). */
+export interface DataChartEmptyProps {
+    /** The chart's title, for screen readers. */
+    title: string;
+    /** The `emptyLabel` prop. */
+    label: React.ReactNode;
+}
+/** What the `Loading` slot receives (`loading` is true). */
+export interface DataChartLoadingProps {
+    title: string;
+    /** The viewBox size, for a placeholder of the chart's proportions. */
+    width: number;
+    height: number;
+}
+/** The parts of the chart a project can replace (`slots={{ Tooltip: MyTooltip }}`). */
+export interface DataChartSlots {
+    /** The tooltip's content (the positioned box around it stays the chart's). */
+    Tooltip: React.ComponentType<DataChartTooltipProps>;
+    /** The series legend, decorative (the hidden table carries the names). */
+    Legend: React.ComponentType<DataChartLegendProps>;
+    /** Shown instead of the chart when there is nothing to plot. */
+    Empty: React.ComponentType<DataChartEmptyProps>;
+    /** Shown instead of the chart while `loading`. */
+    Loading: React.ComponentType<DataChartLoadingProps>;
+}
 export interface DataChartProps {
     kind: DataChartKind;
     /** Single-series shorthand (ignored when `series` is given). */
     data?: readonly DataChartPoint[];
-    /** Multi-series data; series cycle through --karni-chart-1..5. */
+    /** Multi-series data. Series cycle through --karni-chart-1..5. */
     series?: readonly DataChartSeries[];
     /** Chart title: SVG <title>, aria-label and the hidden table's caption. */
     title: string;
     /** Longer description for the SVG <desc>. */
     description?: string;
+    /**
+     * What screen readers hear after the title and description. Default: a
+     * generated summary (each series' lowest and highest value). "" omits it.
+     */
+    summary?: string;
     /** Formats values in the tooltip, y-axis ticks and the hidden table. */
     valueFormatter?: (value: number) => string;
     /** Formats x-axis tick labels (default: the category label itself). */
     xTickFormatter?: (label: string) => string;
-    /** Escape hatch: fully custom tooltip content. */
+    /** Fully custom tooltip content. Prefer the `Tooltip` slot. */
     renderTooltip?: (context: DataChartTooltipContext) => React.ReactNode;
-    /** viewBox width (default 640) — rendered size is responsive. */
+    /** viewBox width (default 640). The rendered size is responsive. */
     width?: number;
     /** viewBox height (default 240). */
     height?: number;
@@ -55,20 +98,32 @@ export interface DataChartProps {
     yTickCount?: number;
     /** Show the series legend (default: only for 2+ series). */
     showLegend?: boolean;
-    /** Show the hover tooltip (default true). */
+    /** Show the tooltip on hover and keyboard focus (default true). */
     showTooltip?: boolean;
     /** Column header of the hidden table's category column (default "Label"). */
     categoryHeader?: string;
     /** Text shown when there is no plottable data. */
     emptyLabel?: string;
+    /** True while the data loads: a placeholder of the chart's size replaces it. */
+    loading?: boolean;
+    /** Replaces the Tooltip, Legend, Empty or Loading. See DataChartSlots. */
+    slots?: Partial<DataChartSlots>;
     className?: string;
 }
+/** The default pieces of the chart, for wrapping one. */
+export declare const defaultDataChartSlots: DataChartSlots;
 /**
  * Minimal line/bar chart driven by `{label, value}` points or named series.
  *
- * Escape hatches: `valueFormatter`/`xTickFormatter`, `renderTooltip`,
+ * Keyboard and screen readers: the chart is an image named by `title`,
+ * described by `description` and a generated summary, with every value in a
+ * visually-hidden table. Tab focuses it. The arrow keys (Home, End) move the
+ * tooltip from category to category and announce each one. Escape hides it.
+ *
+ * Escape hatches: `slots` (replaces the Tooltip, Legend, Empty or Loading
+ * pieces), `valueFormatter`/`xTickFormatter`, `summary`, `renderTooltip`,
  * `width`/`height`/`yTickCount`, legend and tooltip toggles, `className`
  * (merged via cn()). Colors are only themeable through the
  * --karni-chart-1..5 CSS variables.
  */
-export declare function DataChart({ kind, data, series, title, description, valueFormatter, xTickFormatter, renderTooltip, width, height, yTickCount, showLegend, showTooltip, categoryHeader, emptyLabel, className, }: DataChartProps): React.ReactElement;
+export declare function DataChart({ kind, data, series, title, description, summary, valueFormatter, xTickFormatter, renderTooltip, width, height, yTickCount, showLegend, showTooltip, categoryHeader, emptyLabel, loading, slots, className, }: DataChartProps): React.ReactElement;

package/dist/src/components/empty-state/empty-state.d.ts

@@ -1,4 +1,19 @@
 import * as React from "react";
+/** What each EmptyState slot receives: the matching prop. */
+export interface EmptyStateSlotProps {
+    children: React.ReactNode;
+}
+/** The parts of the placeholder a project can replace (`slots={{ Title: MyHeading }}`). */
+export interface EmptyStateSlots {
+    /** Wraps `icon`. It is decorative and hidden from assistive tech. */
+    Icon: React.ComponentType<EmptyStateSlotProps>;
+    /** The headline. The default is an <h3>. */
+    Title: React.ComponentType<EmptyStateSlotProps>;
+    /** The supporting copy. */
+    Description: React.ComponentType<EmptyStateSlotProps>;
+    /** Wraps `action`. */
+    Actions: React.ComponentType<EmptyStateSlotProps>;
+}
 export interface EmptyStateProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "title"> {
     /** Optional illustration/icon slot, rendered above the title. */
     icon?: React.ReactNode;
@@ -8,13 +23,18 @@ export interface EmptyStateProps extends Omit<React.HTMLAttributes<HTMLDivElemen
     description?: React.ReactNode;
     /** Slot for a call to action (e.g. a "Create" button). */
     action?: React.ReactNode;
+    /** Replaces the Icon, Title, Description or Actions. See EmptyStateSlots. */
+    slots?: Partial<EmptyStateSlots>;
     children?: React.ReactNode;
 }
+/** The default pieces of the placeholder, for wrapping one. */
+export declare const defaultEmptyStateSlots: EmptyStateSlots;
 /**
  * Centered placeholder for empty collections: icon, title, description and
  * an action slot. Used by ResourceTable's `empty` slot and reusable anywhere.
  *
- * Escape hatches: every visual part is a slot; `className` merges via cn();
- * extra children render under the action.
+ * Escape hatches: `slots` replaces the Icon, Title (an <h3> by default: swap
+ * it for the heading level your page needs), Description or Actions.
+ * `className` merges via cn(), and extra children render under the action.
  */
 export declare const EmptyState: React.ForwardRefExoticComponent<EmptyStateProps & React.RefAttributes<HTMLDivElement>>;