@apotech-os/ui-sdk 0.8.0 → 0.10.0

package/dist/index.d.ts

@@ -1,6 +1,8 @@
 import { ClassValue } from 'clsx';
 import * as React from 'react';
-import { AppErrorCode } from '@apotech-os/app-kit';
+import { ReactNode } from 'react';
+import { AppErrorCode, AppRunRecord, AppRunStatus } from '@apotech-os/app-kit';
+export { AppRunRecord, AppRunStatus } from '@apotech-os/app-kit';
 import * as class_variance_authority_types from 'class-variance-authority/types';
 import { VariantProps } from 'class-variance-authority';
 
@@ -100,6 +102,46 @@ declare function useAppSettings<T = Record<string, unknown>>(): {
     isSaving: boolean;
     saveError: unknown;
 };
+/**
+ * Follows a single run until it reaches a terminal status.
+ *
+ * Polling uses a recursive `setTimeout` (never `setInterval`, which piles up
+ * requests when the API slows down), starting at `intervalMs` (default 1 s)
+ * and multiplying by 1.5 each tick up to `maxIntervalMs` (default 5 s). The
+ * backoff resets to `intervalMs` whenever `progress` or `message` changes —
+ * an actively-progressing run is polled fast, a stalled one is polled slowly.
+ *
+ * `runId === null` puts the hook to sleep: no request is ever sent. This lets
+ * a page call the hook unconditionally with a run id that may not exist yet
+ * (e.g. before the triggering `uiInvoke` has returned).
+ */
+declare function useAppRun(runId: string | null, opts?: {
+    intervalMs?: number;
+    maxIntervalMs?: number;
+}): {
+    run: AppRunRecord | undefined;
+    isPolling: boolean;
+    error: unknown;
+    refresh: () => Promise<void>;
+};
+/**
+ * Lists the latest runs of a `kind` — used to re-attach the UI after a page
+ * reload, where the runId returned by `invoke()` is lost, and to follow a run
+ * by its business `key` rather than by its id.
+ */
+declare function useAppRuns(opts: {
+    kind?: string;
+    key?: string;
+    status?: AppRunStatus[];
+    limit?: number;
+    /** Keeps refreshing while a non-terminal run is present. Default: true. */
+    follow?: boolean;
+}): {
+    runs: AppRunRecord[];
+    isLoading: boolean;
+    error: unknown;
+    refresh: () => Promise<void>;
+};
 
 declare const buttonVariants: (props?: ({
     variant?: "default" | "secondary" | "outline" | "ghost" | "destructive" | null | undefined;
@@ -109,7 +151,7 @@ interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement>, Var
 }
 declare const Button: React.ForwardRefExoticComponent<ButtonProps & React.RefAttributes<HTMLButtonElement>>;
 declare const badgeVariants: (props?: ({
-    variant?: "outline" | "neutral" | "brand" | "success" | "warning" | "danger" | "info" | null | undefined;
+    variant?: "success" | "outline" | "neutral" | "brand" | "warning" | "danger" | "info" | null | undefined;
 } & class_variance_authority_types.ClassProp) | undefined) => string;
 interface BadgeProps extends React.HTMLAttributes<HTMLSpanElement>, VariantProps<typeof badgeVariants> {
     dot?: boolean;
@@ -118,7 +160,9 @@ declare function Badge({ className, variant, dot, children, ...props }: BadgePro
 declare function Card({ className, ...props }: React.HTMLAttributes<HTMLDivElement>): React.JSX.Element;
 declare function CardHeader({ className, ...props }: React.HTMLAttributes<HTMLDivElement>): React.JSX.Element;
 declare function CardTitle({ className, ...props }: React.HTMLAttributes<HTMLHeadingElement>): React.JSX.Element;
+declare function CardDescription({ className, ...props }: React.HTMLAttributes<HTMLParagraphElement>): React.JSX.Element;
 declare function CardContent({ className, ...props }: React.HTMLAttributes<HTMLDivElement>): React.JSX.Element;
+declare function CardFooter({ className, ...props }: React.HTMLAttributes<HTMLDivElement>): React.JSX.Element;
 declare const Input: React.ForwardRefExoticComponent<React.InputHTMLAttributes<HTMLInputElement> & React.RefAttributes<HTMLInputElement>>;
 declare function Table({ className, ...props }: React.HTMLAttributes<HTMLTableElement>): React.JSX.Element;
 declare function TableHeader({ className, ...props }: React.HTMLAttributes<HTMLTableSectionElement>): React.JSX.Element;
@@ -150,7 +194,7 @@ declare function TabsContent({ value, className, children, }: {
     value: string;
     className?: string;
     children: React.ReactNode;
-}): React.JSX.Element | null;
+}): React.JSX.Element;
 interface ModalProps {
     open: boolean;
     onClose: () => void;
@@ -158,7 +202,8 @@ interface ModalProps {
     children: React.ReactNode;
     className?: string;
 }
-declare function Modal({ open, onClose, title, children, className }: ModalProps): React.JSX.Element | null;
+/** Centred blocking dialog. Base UI owns the focus trap, focus restore and Escape. */
+declare function Modal({ open, onClose, title, children, className }: ModalProps): React.JSX.Element;
 interface SpinnerProps {
     className?: string;
     size?: 'sm' | 'md' | 'lg';
@@ -168,6 +213,10 @@ interface LinkProps extends React.AnchorHTMLAttributes<HTMLAnchorElement> {
     variant?: 'default' | 'muted';
 }
 declare const Link: React.ForwardRefExoticComponent<LinkProps & React.RefAttributes<HTMLAnchorElement>>;
+/**
+ * Do not pass `aria-label` when the switch sits inside a `<label>`: the label
+ * already names it, and the two naming sources cancel out into no name at all.
+ */
 interface SwitchProps {
     checked?: boolean;
     onCheckedChange?: (checked: boolean) => void;
@@ -213,9 +262,10 @@ interface SidePanelProps {
  * Children are laid out in a flex column filling the panel: put the scrollable
  * region in a `min-h-0 flex-1 overflow-y-auto` child and the footer after it.
  *
- * NOTE: no focus management. Autofocus the primary action yourself.
+ * Focus is trapped inside while open and restored to the opener on close — Base
+ * UI's dialog does both, which is what the hand-rolled version never did.
  */
-declare function SidePanel({ open, onClose, title, description, children, className, }: SidePanelProps): React.JSX.Element | null;
+declare function SidePanel({ open, onClose, title, description, children, className, }: SidePanelProps): React.JSX.Element;
 interface CopyButtonProps {
     value: string;
     label?: string;
@@ -253,9 +303,45 @@ interface DropdownMenuProps {
     align?: 'start' | 'end';
     className?: string;
 }
-/** Uncontrolled menu built on Popover. Selecting an item closes it. */
+/** Uncontrolled menu. Selecting an item closes it; arrow keys move between them. */
 declare function DropdownMenu({ trigger, items, align, className }: DropdownMenuProps): React.JSX.Element;
 
+interface ToastInput {
+    title: string;
+    description?: string;
+    /** `info` exists because Pilotage's own stack had it — a neutral outcome is not a success. */
+    variant?: 'success' | 'error' | 'info';
+}
+/** Returns a `toast({ title, description?, variant? })` function. */
+declare function useToast(): (toast: ToastInput) => void;
+/** Fixed bottom-right stack, auto-dismissing. */
+declare function ToastProvider({ children }: {
+    children: ReactNode;
+}): React.JSX.Element;
+
+/**
+ * Hover tooltip, lifted from the shell.
+ *
+ * Deliberately CSS-only (`group-hover`) rather than another Base UI surface: it
+ * carries no focus, no dismissal and no state, so a portal and a positioner would
+ * be weight for nothing. If a tooltip ever needs to be keyboard-reachable or to
+ * survive a scroll container, that is the moment to move it onto Base UI's.
+ */
+
+declare const SIDES: {
+    readonly top: "bottom-full left-1/2 -translate-x-1/2 mb-1.5";
+    readonly right: "left-full top-1/2 -translate-y-1/2 ml-1.5";
+    readonly bottom: "top-full left-1/2 -translate-x-1/2 mt-1.5";
+    readonly left: "right-full top-1/2 -translate-y-1/2 mr-1.5";
+};
+interface TooltipProps {
+    label: React.ReactNode;
+    children: React.ReactNode;
+    side?: keyof typeof SIDES;
+    className?: string;
+}
+declare function Tooltip({ label, children, side, className }: TooltipProps): React.JSX.Element;
+
 /**
  * Browser helpers for app pages.
  *
@@ -285,4 +371,4 @@ declare function toCsv(rows: string[][]): string;
  */
 declare function downloadCsv(rows: string[][], filename: string): void;
 
-export { type AppApiClient, AppApiProvider, AppContextProvider, type AppContextValue, AppInvokeError, Badge, type BadgeProps, Button, type ButtonProps, Card, CardContent, CardHeader, CardTitle, Checkbox, type CheckboxProps, CopyButton, type CopyButtonProps, type DateRange, DateRangePicker, type DateRangePickerProps, DropdownMenu, type DropdownMenuItem, type DropdownMenuProps, Input, Link, type LinkProps, Modal, type ModalProps, Popover, type PopoverProps, Select, type SelectProps, SidePanel, type SidePanelProps, Spinner, type SpinnerProps, Switch, type SwitchProps, Table, TableBody, TableCell, TableHead, TableHeader, TableRow, Tabs, TabsContent, TabsList, type TabsProps, TabsTrigger, Textarea, type TextareaProps, cn, copyToClipboard, downloadBlob, downloadCsv, toCsv, useAppApi, useAppContext, useAppSettings };
+export { type AppApiClient, AppApiProvider, AppContextProvider, type AppContextValue, AppInvokeError, Badge, type BadgeProps, Button, type ButtonProps, Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, Checkbox, type CheckboxProps, CopyButton, type CopyButtonProps, type DateRange, DateRangePicker, type DateRangePickerProps, DropdownMenu, type DropdownMenuItem, type DropdownMenuProps, Input, Link, type LinkProps, Modal, type ModalProps, Popover, type PopoverProps, Select, type SelectProps, SidePanel, type SidePanelProps, Spinner, type SpinnerProps, Switch, type SwitchProps, Table, TableBody, TableCell, TableHead, TableHeader, TableRow, Tabs, TabsContent, TabsList, type TabsProps, TabsTrigger, Textarea, type TextareaProps, type ToastInput, ToastProvider, Tooltip, type TooltipProps, badgeVariants, buttonVariants, cn, copyToClipboard, downloadBlob, downloadCsv, toCsv, useAppApi, useAppContext, useAppRun, useAppRuns, useAppSettings, useToast };