@tappify/extension-sdk 2.1.0-beta.1 → 2.1.0

package/dist/index.d.ts

@@ -1,9 +1,11 @@
-export { u as useTap } from './context-Cr93B05o.js';
-export { T as TAP_ERROR_CODES, a as TapError, b as TapErrorCode, c as TapServerError } from './errors-Cqh0wrqt.js';
-import { T as Tap, a as TapFilters, b as TapSize, c as TapHostEvents, d as TapQuery, e as TapResult, f as TapProcedureName, g as TapProcedureInput, h as TapProcedureOutput, i as TapSingletonName, j as TapSingletonDocument } from './types-BYGcp5pZ.js';
-export { A as ActionId, k as ActionInput, P as PromptId, l as PromptInput, m as TapActionMap, n as TapActionRun, o as TapApp, p as TapChangeKey, q as TapChatCard, r as TapCollection, s as TapComparisonSide, t as TapConfirmOptions, u as TapCrashIssue, v as TapCrashesResult, w as TapCredentialValues, x as TapCredentials, y as TapDateRange, z as TapFormatters, B as TapHostEventMap, C as TapInternals, D as TapKeyword, E as TapKeywordsResult, F as TapListing, G as TapListingResult, H as TapPageProps, I as TapPath, J as TapPlatform, K as TapPlatformFilter, L as TapProcedureMap, M as TapProcedures, N as TapProjectResult, O as TapPromptMap, Q as TapRelease, R as TapRevenueResult, S as TapReview, U as TapReviewsResult, V as TapRowActionProps, W as TapSeriesMetric, X as TapSeriesPoint, Y as TapSeriesResult, Z as TapSettings, _ as TapSettingsProps, $ as TapSettingsValues, a0 as TapSingleton, a1 as TapStorage, a2 as TapStorageMap, a3 as TapTabProps, a4 as TapTableColumn, a5 as TapTelemetryEvents, a6 as TapToastTone, a7 as TapToolMap, a8 as TapWebhookMap, a9 as TapWidgetProps, aa as TelemetryEvent, ab as ToolId, ac as ToolInput, ad as WebhookName, ae as WebhookPayload } from './types-BYGcp5pZ.js';
-export { D as DataQueryKind, H as HostEventName, a as HostPage, S as ScopeKey, b as SlotId } from './constants-BAimnqOK.js';
-import 'react';
+export { u as useTap } from './context-Ml7k_V14.js';
+export { T as TAP_ERROR_CODES, a as TapError, b as TapErrorCode, c as TapServerError } from './errors-COsBh7kd.js';
+import { T as Tap, a as TapFilters, b as TapSize, c as TapHostEvents, d as TapQuery, e as TapResult, f as TapProcedureName, g as TapProcedureInput, h as TapProcedureOutput, i as TapSingletonName, j as TapSingletonDocument } from './types-DDAGLpov.js';
+export { A as ActionId, k as ActionInput, P as PromptId, l as PromptInput, m as TapActionMap, n as TapActionRun, o as TapApp, p as TapChangeKey, q as TapChatCard, r as TapCollection, s as TapComparisonSide, t as TapConfirmOptions, u as TapCrashIssue, v as TapCrashesResult, w as TapCredentialValues, x as TapCredentials, y as TapDateRange, z as TapFormatters, B as TapHostEventMap, C as TapInternals, D as TapKeyword, E as TapKeywordsResult, F as TapListing, G as TapListingResult, H as TapPageProps, I as TapPath, J as TapPlatform, K as TapPlatformFilter, L as TapProcedureMap, M as TapProcedures, N as TapProjectResult, O as TapPromptMap, Q as TapRelease, R as TapRevenueResult, S as TapReview, U as TapReviewsResult, V as TapRowActionProps, W as TapSeriesMetric, X as TapSeriesPoint, Y as TapSeriesResult, Z as TapSettings, _ as TapSettingsProps, $ as TapSettingsValues, a0 as TapSingleton, a1 as TapStorage, a2 as TapStorageMap, a3 as TapTabProps, a4 as TapTableColumn, a5 as TapTelemetryEvents, a6 as TapToastTone, a7 as TapToolMap, a8 as TapWebhookMap, a9 as TapWidgetProps, aa as TelemetryEvent, ab as ToolId, ac as ToolInput, ad as WebhookName, ae as WebhookPayload } from './types-DDAGLpov.js';
+import { ClassValue as ClassValue$1 } from 'clsx';
+import { ButtonHTMLAttributes, ReactElement, ReactNode, InputHTMLAttributes, TextareaHTMLAttributes, SelectHTMLAttributes } from 'react';
+import { J as JsonSchema } from './constants-DJ_KgZpN.js';
+export { D as DataQueryKind, H as HostEventName, a as HostPage, S as ScopeKey, b as SlotId } from './constants-DJ_KgZpN.js';
 
 /**
  * Returns the install token, the signed-in teammate, the workspace id, the
@@ -16,13 +18,12 @@ import 'react';
  *
  * @example
  * ```tsx
- * import { useTapAuth } from '@tappify/extension-sdk';
- * import { EmptyState } from '@tappify/extension-sdk/ui';
+ * import { TapEmptyState, useTapAuth } from '@tappify/extension-sdk';
  *
  * function RevenuePanel() {
  *   const auth = useTapAuth();
  *   if (!auth.can('revenue:read')) {
- *     return <EmptyState title="Revenue is not shared with this extension" />;
+ *     return <TapEmptyState title="Revenue is not shared with this extension" />;
  *   }
  *   return <span>Signed in as {auth.user.id}</span>;
  * }
@@ -108,30 +109,17 @@ declare function useTapTheme(): Tap['theme'];
  *
  * @example
  * ```tsx
- * import { useTapSize } from '@tappify/extension-sdk';
- * import {
- *   Table,
- *   TableBody,
- *   TableCell,
- *   TableHead,
- *   TableHeader,
- *   TableRow,
- * } from '@tappify/extension-sdk/ui';
+ * import { TapTable, useTapSize } from '@tappify/extension-sdk';
  *
  * function Keywords({ rows }: { rows: { term: string }[] }) {
  *   const size = useTapSize();
  *   const shown = size === 'slot' ? rows.slice(0, 3) : rows;
  *   return (
- *     <Table>
- *       <TableHeader>
- *         <TableRow variant="header"><TableHead>Term</TableHead></TableRow>
- *       </TableHeader>
- *       <TableBody>
- *         {shown.map(row => (
- *           <TableRow key={row.term}><TableCell>{row.term}</TableCell></TableRow>
- *         ))}
- *       </TableBody>
- *     </Table>
+ *     <TapTable
+ *       columns={[{ key: 'term', label: 'Term' }]}
+ *       rows={shown}
+ *       rowKey={row => row.term}
+ *     />
  *   );
  * }
  * ```
@@ -194,15 +182,14 @@ declare function useTapContext(): Record<string, unknown>;
  *
  * @example
  * ```tsx
- * import { useTapState } from '@tappify/extension-sdk';
- * import { Button } from '@tappify/extension-sdk/ui';
+ * import { TapButton, useTapState } from '@tappify/extension-sdk';
  *
  * function StepPicker() {
  *   const [step, setStep] = useTapState<string>('selectedStep');
  *   return (
- *     <Button onClick={() => setStep('install')}>
+ *     <TapButton onClick={() => setStep('install')}>
  *       {step ?? 'Pick a step'}
- *     </Button>
+ *     </TapButton>
  *   );
  * }
  * ```
@@ -338,8 +325,7 @@ declare function procedurePrefix(installId: string, name: string): unknown[];
  *
  * @example
  * ```tsx
- * import { useTapFilters, useTapQuery } from '@tappify/extension-sdk';
- * import { Metric } from '@tappify/extension-sdk/ui';
+ * import { TapStat, useTapFilters, useTapQuery } from '@tappify/extension-sdk';
  *
  * function Downloads() {
  *   const filters = useTapFilters();
@@ -349,41 +335,25 @@ declare function procedurePrefix(installId: string, name: string): unknown[];
  *   );
  *   const points = downloads.data?.points ?? [];
  *   const total = points.reduce((sum, point) => sum + point.value, 0);
- *   return <Metric label="Downloads" value={total} />;
+ *   return <TapStat label="Downloads" value={total} />;
  * }
  * ```
  *
  * @example
  * ```tsx
- * import { useTapQuery } from '@tappify/extension-sdk';
- * import {
- *   Table,
- *   TableBody,
- *   TableCell,
- *   TableHead,
- *   TableHeader,
- *   TableRow,
- * } from '@tappify/extension-sdk/ui';
+ * import { TapTable, useTapQuery } from '@tappify/extension-sdk';
  *
  * function Keywords() {
  *   const keywords = useTapQuery({ kind: 'keywords' });
  *   return (
- *     <Table>
- *       <TableHeader>
- *         <TableRow variant="header">
- *           <TableHead>Term</TableHead>
- *           <TableHead>Rank</TableHead>
- *         </TableRow>
- *       </TableHeader>
- *       <TableBody>
- *         {(keywords.data?.keywords ?? []).map(keyword => (
- *           <TableRow key={keyword.id}>
- *             <TableCell>{keyword.term}</TableCell>
- *             <TableCell>{keyword.position}</TableCell>
- *           </TableRow>
- *         ))}
- *       </TableBody>
- *     </Table>
+ *     <TapTable
+ *       columns={[
+ *         { key: 'term', label: 'Term' },
+ *         { key: 'position', label: 'Rank', align: 'end' },
+ *       ]}
+ *       rows={keywords.data?.keywords ?? []}
+ *       rowKey={keyword => keyword.id}
+ *     />
  *   );
  * }
  * ```
@@ -404,8 +374,7 @@ declare function useTapQuery<Q extends TapQuery>(query: Q, options?: TapQueryOpt
  *
  * @example
  * ```tsx
- * import { useTapFilters, useTapServer } from '@tappify/extension-sdk';
- * import { Button, ErrorState } from '@tappify/extension-sdk/ui';
+ * import { TapButton, TapErrorState, useTapFilters, useTapServer } from '@tappify/extension-sdk';
  *
  * function Summary() {
  *   const filters = useTapFilters();
@@ -415,9 +384,9 @@ declare function useTapQuery<Q extends TapQuery>(query: Q, options?: TapQueryOpt
  *     { invalidateOn: ['settings.changed'] },
  *   );
  *   if (summary.error !== null) {
- *     return <ErrorState title="The summary did not load" description={summary.error.message} />;
+ *     return <TapErrorState title="The summary did not load" description={summary.error.message} />;
  *   }
- *   return <Button loading={summary.isLoading} onClick={summary.refetch}>Refresh</Button>;
+ *   return <TapButton loading={summary.isLoading} onClick={summary.refetch}>Refresh</TapButton>;
  * }
  * ```
  */
@@ -437,22 +406,611 @@ declare function useTapServer<N extends TapProcedureName>(name: N, input: TapPro
  *
  * @example
  * ```tsx
- * import { useTapStorage } from '@tappify/extension-sdk';
- * import { Button } from '@tappify/extension-sdk/ui';
+ * import { TapButton, useTapStorage } from '@tappify/extension-sdk';
  *
  * function CompactToggle() {
  *   const preferences = useTapStorage('preferences');
  *   return (
- *     <Button
+ *     <TapButton
  *       loading={preferences.isLoading}
  *       onClick={() => void preferences.patch({ compact: true })}
  *     >
  *       Compact
- *     </Button>
+ *     </TapButton>
  *   );
  * }
  * ```
  */
 declare function useTapStorage<C extends TapSingletonName>(collection: C): TapStorageResult<TapSingletonDocument<C>>;
 
-export { Tap, TapFilters, TapHostEvents, TapProcedureInput, TapProcedureName, TapProcedureOutput, TapQuery, type TapQueryOptions, type TapQueryResult, TapResult, TapSingletonDocument, TapSingletonName, TapSize, type TapStorageResult, dataQueryKey, installPrefix, procedurePrefix, procedureQueryKey, storageQueryKey, useTapAuth, useTapContext, useTapFilters, useTapParams, useTapProject, useTapQuery, useTapServer, useTapSize, useTapState, useTapStorage, useTapTheme };
+/**
+ * Anything `cn` accepts: a class string, a number, an array of these, a map of
+ * class name to condition, or a value to drop.
+ */
+type ClassValue = ClassValue$1;
+/**
+ * Joins class names, dropping the ones that are `false`, `null` or `undefined`.
+ *
+ * @remarks
+ * This is `clsx`, re-exported so a vendor surface needs no class-name dependency
+ * of its own. It does not merge conflicting utility classes.
+ *
+ * @example
+ * ```tsx
+ * import { cn } from '@tappify/extension-sdk';
+ *
+ * function Row({ compact }: { compact: boolean }) {
+ *   return <div className={cn('starter-row', compact && 'starter-row--compact')} />;
+ * }
+ * ```
+ */
+declare function cn(...values: ClassValue[]): string;
+
+/** The props `TapButton` takes, on top of the native button attributes. */
+interface TapButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+    /** Defaults to `primary`. */
+    variant?: 'primary' | 'secondary' | 'ghost' | 'danger';
+    /** Defaults to `md`. */
+    size?: 'sm' | 'md';
+    /** Disables the button and marks it `aria-busy`. */
+    loading?: boolean;
+}
+/**
+ * Renders a button in the host's styling, in one of four variants.
+ *
+ * @remarks
+ * Draws on `--tap-accent` and `--tap-accent-fg` for `primary`, `--bg-raised`,
+ * `--fg-default` and `--divider` for `secondary`, `--fg-muted` for `ghost` and
+ * `--tap-danger` for `danger`, and takes its radius from `--tap-radius`. The
+ * element defaults to `type="button"`, so a button inside a `TapForm` does not
+ * submit it unless you pass `type="submit"`. `loading` disables the button, so a
+ * click cannot land twice.
+ *
+ * @example
+ * ```tsx
+ * import { TapButton } from '@tappify/extension-sdk';
+ *
+ * function ExportRow({ busy, onExport }: { busy: boolean; onExport: () => void }) {
+ *   return (
+ *     <TapButton variant="secondary" size="sm" loading={busy} onClick={onExport}>
+ *       Export
+ *     </TapButton>
+ *   );
+ * }
+ * ```
+ */
+declare function TapButton({ variant, size, loading, disabled, className, children, ...rest }: TapButtonProps): ReactElement;
+/** The props `TapCard` takes. */
+interface TapCardProps {
+    /** Rendered in the header, which appears only with a `title` or an `action`. */
+    title?: ReactNode;
+    /** Sits at the end of the header, for a button or a link. */
+    action?: ReactNode;
+    /** Rendered under a divider below the body. */
+    footer?: ReactNode;
+    className?: string;
+    children: ReactNode;
+}
+/**
+ * Renders the bordered surface a widget, tab or page section sits in.
+ *
+ * @remarks
+ * Renders as a `section` on `--bg-raised` with a `--divider` border and the
+ * `--tap-radius` corner, and the footer in `--fg-muted`. The header appears only
+ * when `title` or `action` is given, and the body carries its own padding, so
+ * nest content directly rather than wrapping it in another padded box. A widget
+ * belongs in one card.
+ *
+ * @example
+ * ```tsx
+ * import { TapButton, TapCard, TapStat } from '@tappify/extension-sdk';
+ *
+ * function InstallSummary() {
+ *   return (
+ *     <TapCard
+ *       title="Install summary"
+ *       action={<TapButton variant="ghost" size="sm">Compact</TapButton>}
+ *       footer={<span>Last seven days</span>}
+ *     >
+ *       <TapStat label="Installs" value="1,260" delta={0.087} />
+ *     </TapCard>
+ *   );
+ * }
+ * ```
+ */
+declare function TapCard({ title, action, footer, className, children, }: TapCardProps): ReactElement;
+/** The props `TapPageHeader` takes. */
+interface TapPageHeaderProps {
+    title: ReactNode;
+    description?: ReactNode;
+    /** Laid out in a row at the end of the header. */
+    actions?: ReactNode;
+}
+/**
+ * Renders the title, description and actions at the top of a tab, a page or a
+ * settings panel.
+ *
+ * @remarks
+ * The title renders as an `h2`, because the host owns the page's `h1`. The
+ * description follows `--fg-muted` and the rule under the header follows
+ * `--divider`. Under 360 pixels of mount width the actions stack under the title.
+ * A widget in a slot uses `TapCard`'s own header instead.
+ *
+ * @example
+ * ```tsx
+ * import { TapButton, TapPageHeader } from '@tappify/extension-sdk';
+ *
+ * function FunnelsHeader() {
+ *   return (
+ *     <TapPageHeader
+ *       title="Funnels"
+ *       description="Every step from impression to install."
+ *       actions={<TapButton size="sm">New funnel</TapButton>}
+ *     />
+ *   );
+ * }
+ * ```
+ */
+declare function TapPageHeader({ title, description, actions, }: TapPageHeaderProps): ReactElement;
+/** The props `TapSkeleton` takes. */
+interface TapSkeletonProps {
+    /** How many bars to draw. Defaults to one. */
+    lines?: number;
+    /** A CSS width for every bar. Left out, each bar is 12% shorter than the last. */
+    width?: string;
+    className?: string;
+}
+/**
+ * Renders the placeholder bars that stand in for content while a read is in
+ * flight.
+ *
+ * @remarks
+ * The bars are `aria-hidden`, so a screen reader is not told about them, and they
+ * take their tone from `--bg-subtle`. The pulse stops under
+ * `prefers-reduced-motion`. Render this while `isLoading` is `true`, in place of
+ * the content rather than beside it.
+ *
+ * @example
+ * ```tsx
+ * import { TapSkeleton, TapStat, useTapQuery } from '@tappify/extension-sdk';
+ *
+ * function Keywords() {
+ *   const keywords = useTapQuery({ kind: 'keywords' });
+ *   if (keywords.isLoading) return <TapSkeleton lines={3} />;
+ *   return <TapStat label="Tracked" value={keywords.data?.keywords.length ?? 0} />;
+ * }
+ * ```
+ */
+declare function TapSkeleton({ lines, width, className, }: TapSkeletonProps): ReactElement;
+/** The props `TapEmptyState` takes. */
+interface TapEmptyStateProps {
+    title: string;
+    description?: string;
+    /** Rendered under the text, for the one thing the owner can do next. */
+    action?: ReactNode;
+}
+/**
+ * Renders the centred message that stands in for content when there is nothing to
+ * show.
+ *
+ * @remarks
+ * Centres its text in `--fg-muted` with the title in `--fg-default`. Use it for an
+ * empty result or a surface the install has not been granted; a failure belongs in
+ * `TapErrorState`, which carries a retry and announces itself as an alert.
+ *
+ * @example
+ * ```tsx
+ * import { TapEmptyState, useTapQuery } from '@tappify/extension-sdk';
+ *
+ * function Reviews() {
+ *   const reviews = useTapQuery({
+ *     kind: 'reviews',
+ *     range: { from: '2026-09-01', to: '2026-09-08' },
+ *   });
+ *   if (reviews.data?.total === 0) {
+ *     return <TapEmptyState title="No reviews in this range" />;
+ *   }
+ *   return <span>{reviews.data?.total ?? 0} reviews</span>;
+ * }
+ * ```
+ */
+declare function TapEmptyState({ title, description, action, }: TapEmptyStateProps): ReactElement;
+/** The props `TapErrorState` takes. */
+interface TapErrorStateProps {
+    title: string;
+    /** The failure's own message, which is what a caller shows the owner. */
+    description?: string;
+    /** An error code, rendered small in `--font-mono` under the description. */
+    code?: string;
+    /** Renders a Retry button, and is called by it. */
+    onRetry?: () => void;
+}
+/**
+ * Renders the centred failure message a surface shows in place of its content.
+ *
+ * @remarks
+ * Carries `role="alert"`, so the host announces it, and draws the title in
+ * `--tap-danger`. The Retry button appears only with `onRetry`; wire it to the
+ * `refetch` of every read the surface needs. Pass the failure's own `message` as
+ * the description — an error from `useTapServer` carries the text your server sent
+ * the owner — and the `code` of a `TapError` or `TapServerError` as `code`.
+ *
+ * @example
+ * ```tsx
+ * import { TapErrorState, useTapQuery } from '@tappify/extension-sdk';
+ *
+ * function Crashes() {
+ *   const crashes = useTapQuery({
+ *     kind: 'crashes',
+ *     range: { from: '2026-09-01', to: '2026-09-08' },
+ *   });
+ *   if (crashes.error !== null) {
+ *     return (
+ *       <TapErrorState
+ *         title="Crashes did not load"
+ *         description={crashes.error.message}
+ *         onRetry={crashes.refetch}
+ *       />
+ *     );
+ *   }
+ *   return <span>{crashes.data?.issues.length ?? 0} issues</span>;
+ * }
+ * ```
+ */
+declare function TapErrorState({ title, description, code, onRetry, }: TapErrorStateProps): ReactElement;
+/** The props `TapStat` takes. */
+interface TapStatProps {
+    label: string;
+    value: ReactNode;
+    /** A share of the previous period, so `0.087` renders as `+9%`. */
+    delta?: number;
+    /** A line of context under the number. */
+    hint?: string;
+}
+/**
+ * Renders one labelled number, with an optional change against the previous
+ * period.
+ *
+ * @remarks
+ * The label is uppercased in `--fg-muted` and the number uses tabular figures, so
+ * a row of stats stays aligned as values change. `delta` is a ratio, not a
+ * percentage: it renders as whole percent with a plus in front when it is above
+ * zero, and is coloured `--tap-danger` below zero and `--tap-accent` at or above
+ * it. Format `value`
+ * yourself with `tap.format.number` or `tap.format.currency`, so it follows the
+ * owner's locale.
+ *
+ * @example
+ * ```tsx
+ * import { TapStat, useTap } from '@tappify/extension-sdk';
+ *
+ * function Installs({ installs, delta }: { installs: number; delta: number }) {
+ *   const tap = useTap();
+ *   return (
+ *     <TapStat
+ *       label="Installs"
+ *       value={tap.format.number(installs)}
+ *       delta={delta}
+ *       hint="Against the previous seven days"
+ *     />
+ *   );
+ * }
+ * ```
+ */
+declare function TapStat({ label, value, delta, hint, }: TapStatProps): ReactElement;
+/**
+ * The `TapInput` props for a single-line control, on top of the native input
+ * attributes minus `size`.
+ */
+interface TapSingleLineInputProps extends Omit<InputHTMLAttributes<HTMLInputElement>, 'size'> {
+    /** Rendered as a `label` bound to the control by id. */
+    label?: string;
+    /** Marks the control invalid and renders the message under it. */
+    error?: string;
+    /** A line of guidance under the control, referenced by `aria-describedby`. */
+    hint?: string;
+}
+/**
+ * The `TapInput` props for a multiline control, on top of the native textarea
+ * attributes.
+ */
+interface TapTextareaProps extends TextareaHTMLAttributes<HTMLTextAreaElement> {
+    /** Rendered as a `label` bound to the control by id. */
+    label?: string;
+    /** Marks the control invalid and renders the message under it. */
+    error?: string;
+    /** A line of guidance under the control, referenced by `aria-describedby`. */
+    hint?: string;
+}
+/**
+ * The props `TapInput` takes: the single-line set, or the textarea set behind
+ * `multiline`.
+ */
+type TapInputProps = ({
+    multiline?: false;
+} & TapSingleLineInputProps) | ({
+    multiline: true;
+} & TapTextareaProps);
+/**
+ * Renders a labelled text control with its hint and error, as an input or, with
+ * `multiline`, a textarea.
+ *
+ * @remarks
+ * Generates an id when none is passed and binds the label, the hint and the error
+ * to the control, so the field is announced whole; an `error` also sets
+ * `aria-invalid` and the `--tap-danger` border. The textarea starts at four rows
+ * and is resizable in height. Pass `type="checkbox"` with
+ * `className="tap-control--checkbox"` for a boolean, which is what `TapForm`
+ * does.
+ *
+ * @example
+ * ```tsx
+ * import { TapInput } from '@tappify/extension-sdk';
+ *
+ * function TermField({ term, onTerm }: { term: string; onTerm: (next: string) => void }) {
+ *   return (
+ *     <TapInput
+ *       label="Keyword"
+ *       hint="One term per row in the report."
+ *       value={term}
+ *       onChange={event => onTerm(event.target.value)}
+ *     />
+ *   );
+ * }
+ * ```
+ */
+declare function TapInput(props: TapInputProps): ReactElement;
+/** The props `TapSelect` takes, on top of the native select attributes. */
+interface TapSelectProps extends SelectHTMLAttributes<HTMLSelectElement> {
+    /** Rendered as a `label` bound to the control by id. */
+    label?: string;
+    /** Marks the control invalid and renders the message under it. */
+    error?: string;
+    /** A line of guidance under the control, referenced by `aria-describedby`. */
+    hint?: string;
+    /** Rendered in order; the component adds no empty option of its own. */
+    options: {
+        value: string;
+        label: string;
+    }[];
+}
+/**
+ * Renders a labelled select over a list of options, with its hint and error.
+ *
+ * @remarks
+ * Carries the same label, hint, error and `aria-describedby` wiring as
+ * `TapInput`. Add your own empty option when the field starts unset — `TapForm`
+ * puts a `Choose one` option in front of a schema's enum values.
+ *
+ * @example
+ * ```tsx
+ * import { TapSelect } from '@tappify/extension-sdk';
+ *
+ * function PlatformPicker({ value, onPick }: { value: string; onPick: (next: string) => void }) {
+ *   return (
+ *     <TapSelect
+ *       label="Platform"
+ *       value={value}
+ *       options={[
+ *         { value: 'ios', label: 'iOS' },
+ *         { value: 'android', label: 'Android' },
+ *       ]}
+ *       onChange={event => onPick(event.target.value)}
+ *     />
+ *   );
+ * }
+ * ```
+ */
+declare function TapSelect({ label, error, hint, options, className, id, ...rest }: TapSelectProps): ReactElement;
+/** One column of a `TapTable`. */
+interface TapTableColumnDef<T> {
+    /** The key read from each row when there is no `render`. */
+    key: string;
+    label: string;
+    /** `end` right-aligns the column and gives it tabular figures. */
+    align?: 'start' | 'end';
+    /** Draws the cell. Without it the cell shows the row's own string or number. */
+    render?(row: T): ReactNode;
+}
+/** The props `TapTable` takes. */
+interface TapTableProps<T> {
+    columns: TapTableColumnDef<T>[];
+    rows: T[];
+    /** Returns a stable key per row, which React uses for reconciliation. */
+    rowKey: (row: T) => string;
+    /** Rendered in place of the whole table when `rows` is empty. */
+    empty?: ReactNode;
+    /** Makes each row clickable and focusable, and is called on click or Enter. */
+    onRowClick?: (row: T) => void;
+}
+/**
+ * Renders rows under column headers, scrolling sideways inside the mount rather
+ * than widening it.
+ *
+ * @remarks
+ * A cell with no `render` shows the row's own value under `key` when that value is
+ * a string, number, boolean or bigint, and nothing otherwise, so an object or an
+ * array needs a `render`. With `empty` and no rows, the table is replaced whole by
+ * that node. With `onRowClick` each row becomes focusable and answers Enter and
+ * Space as well as a click, and hovers on `--bg-subtle`; the headers and rules
+ * follow `--fg-muted` and `--divider`.
+ *
+ * @example
+ * ```tsx
+ * import { TapEmptyState, TapTable, useTapQuery } from '@tappify/extension-sdk';
+ *
+ * function Keywords() {
+ *   const keywords = useTapQuery({ kind: 'keywords' });
+ *   return (
+ *     <TapTable
+ *       columns={[
+ *         { key: 'term', label: 'Term' },
+ *         { key: 'position', label: 'Rank', align: 'end' },
+ *       ]}
+ *       rows={keywords.data?.keywords ?? []}
+ *       rowKey={keyword => keyword.id}
+ *       empty={<TapEmptyState title="No keywords tracked yet" />}
+ *     />
+ *   );
+ * }
+ * ```
+ */
+declare function TapTable<T>({ columns, rows, rowKey, empty, onRowClick, }: TapTableProps<T>): ReactElement;
+
+/** The props `TapDialog` takes. */
+interface TapDialogProps {
+    /** The dialog renders nothing while this is `false`. */
+    open: boolean;
+    /** Rendered in the header, and used as the dialog's accessible name. */
+    title: string;
+    /** Called by Escape, by a click on the scrim, and by the host's close event. */
+    onClose: () => void;
+    /** Rendered under a divider at the end, for the dialog's buttons. */
+    footer?: ReactNode;
+    children: ReactNode;
+    /** The id of your own heading, when the accessible name is not the title. */
+    labelledBy?: string;
+}
+/**
+ * Renders a modal dialog into the mount's own portal node, so it covers the
+ * surface without leaving the extension.
+ *
+ * @remarks
+ * Rendered outside a Tappify mount it throws `TAP_OUTSIDE_HOST`, from the `useTap`
+ * above it. Inside a mount whose shadow root has no portal node yet, opening it
+ * throws `TapError` with code `TAP_NO_PORTAL`; `renderWithTap` provides that node
+ * in tests. While open it traps Tab
+ * inside itself, moves focus to the first focusable element and returns focus
+ * where it was on close, and answers Escape and a click on the scrim with
+ * `onClose`. The scrim follows `--tap-scrim` and the panel `--bg-raised`,
+ * `--divider` and `--tap-radius`; the panel is at most 520 pixels wide. The
+ * component keeps no open state of its own.
+ *
+ * @example
+ * ```tsx
+ * import { TapButton, TapDialog } from '@tappify/extension-sdk';
+ * import { useState } from 'react';
+ *
+ * function ExportDialog() {
+ *   const [open, setOpen] = useState(false);
+ *   return (
+ *     <>
+ *       <TapButton onClick={() => setOpen(true)}>Export</TapButton>
+ *       <TapDialog
+ *         open={open}
+ *         title="Export keywords"
+ *         onClose={() => setOpen(false)}
+ *         footer={<TapButton onClick={() => setOpen(false)}>Done</TapButton>}
+ *       >
+ *         <span>The report covers the range in the filter bar.</span>
+ *       </TapDialog>
+ *     </>
+ *   );
+ * }
+ * ```
+ */
+declare function TapDialog({ open, title, onClose, footer, children, labelledBy, }: TapDialogProps): ReactElement | null;
+
+/** The control a schema property maps to. */
+type TapFormFieldKind = 'text' | 'textarea' | 'date' | 'number' | 'boolean' | 'enum';
+/** One control `TapForm` renders, as `formFields` reads it off a schema. */
+interface TapFormField {
+    /** The property name in the schema, and the key in the submitted value. */
+    name: string;
+    /** The property's `title`, or the name spaced and capitalised. */
+    label: string;
+    kind: TapFormFieldKind;
+    /** Whether the schema lists the property under `required`. */
+    required: boolean;
+    /** The property's `description`. */
+    hint?: string;
+    /** Set for an `enum` property: one option per string value. */
+    options?: {
+        value: string;
+        label: string;
+    }[];
+}
+/**
+ * Reads a JSON Schema object and returns the list of controls `TapForm` renders
+ * from it.
+ *
+ * @remarks
+ * One field per declared property, in the order the schema lists them; a schema
+ * with no `properties` object returns an empty list, and a property that is not an
+ * object is skipped. An `enum` becomes a select and keeps only its string values;
+ * otherwise the kind comes from `type` — `boolean`, `number` and `integer` — and
+ * then from `format`, where `textarea` and `date` are recognised and anything else
+ * falls back to a single-line text control. Nested objects and arrays get a text
+ * control, so render those yourself. Call it when you want the fields without the
+ * form.
+ *
+ * @example
+ * ```ts
+ * import { formFields } from '@tappify/extension-sdk';
+ *
+ * const fields = formFields({
+ *   type: 'object',
+ *   properties: { refreshMinutes: { type: 'integer', title: 'Refresh minutes' } },
+ *   required: ['refreshMinutes'],
+ * });
+ * const names = fields.map(field => field.name);
+ * ```
+ */
+declare function formFields(schema: JsonSchema): TapFormField[];
+/** The props `TapForm` takes. */
+interface TapFormProps<T> {
+    /** The object schema to render, one control per declared property. */
+    schema: JsonSchema;
+    /** The value the fields start at; later changes to it do not reset the form. */
+    value?: Partial<T>;
+    /** Defaults to `Submit`. */
+    submitLabel?: string;
+    /** Defaults to `Cancel`. */
+    cancelLabel?: string;
+    /** Marks the submit button busy and disables it while a submit is in flight. */
+    busy?: boolean;
+    /** Called with the cleaned value once validation passes. */
+    onSubmit: (value: T) => void | Promise<void>;
+    /** Renders a cancel button next to submit, and is called by it. */
+    onCancel?: () => void;
+}
+/**
+ * Renders a JSON Schema as a form in the host's styling, validates it on submit
+ * and hands back the value.
+ *
+ * @remarks
+ * Point it at the same schema file the manifest references, so the form and the
+ * handler change together. Submit drops the fields left blank, then checks what
+ * remains against the whole schema, so a `minimum`, `pattern` or `maxLength`
+ * lands under the control it belongs to; a required field left empty is reported
+ * without reaching the schema. A schema this SDK's Zod version cannot compile
+ * still renders and still enforces required fields. `onSubmit` runs only when
+ * nothing failed, and the form holds its own values, so a change to `value` after
+ * the first render does not reset it. A form with no `value` has nothing to infer
+ * `T` from, so annotate the handler's parameter.
+ *
+ * @example
+ * ```tsx
+ * import { TapForm, type TapSettingsProps } from '@tappify/extension-sdk';
+ *
+ * const schema = {
+ *   type: 'object',
+ *   properties: { refreshMinutes: { type: 'integer', title: 'Refresh minutes' } },
+ *   required: ['refreshMinutes'],
+ * };
+ *
+ * function Settings({ values, onChange }: TapSettingsProps) {
+ *   return (
+ *     <TapForm
+ *       schema={schema}
+ *       value={values}
+ *       submitLabel="Save"
+ *       onSubmit={next => onChange(next)}
+ *     />
+ *   );
+ * }
+ * ```
+ */
+declare function TapForm<T>({ schema, value, submitLabel, cancelLabel, busy, onSubmit, onCancel, }: TapFormProps<T>): ReactElement;
+
+export { type ClassValue, Tap, TapButton, type TapButtonProps, TapCard, type TapCardProps, TapDialog, type TapDialogProps, TapEmptyState, type TapEmptyStateProps, TapErrorState, type TapErrorStateProps, TapFilters, TapForm, type TapFormField, type TapFormFieldKind, type TapFormProps, TapHostEvents, TapInput, type TapInputProps, TapPageHeader, type TapPageHeaderProps, TapProcedureInput, TapProcedureName, TapProcedureOutput, TapQuery, type TapQueryOptions, type TapQueryResult, TapResult, TapSelect, type TapSelectProps, type TapSingleLineInputProps, TapSingletonDocument, TapSingletonName, TapSize, TapSkeleton, type TapSkeletonProps, TapStat, type TapStatProps, type TapStorageResult, TapTable, type TapTableColumnDef, type TapTableProps, type TapTextareaProps, cn, dataQueryKey, formFields, installPrefix, procedurePrefix, procedureQueryKey, storageQueryKey, useTapAuth, useTapContext, useTapFilters, useTapParams, useTapProject, useTapQuery, useTapServer, useTapSize, useTapState, useTapStorage, useTapTheme };