@apotech-os/ui-sdk 0.3.0 → 0.6.0

package/dist/index.d.cts

@@ -22,6 +22,12 @@ interface AppContextValue {
     pagePath: string;
     /** The active space id, when applicable. */
     spaceId?: string;
+    /**
+     * The current user's grant role on this app context, when the shell knows it.
+     * Settings pages use it to render read-only fields below ADMIN instead of
+     * letting the user discover the 403 at save time.
+     */
+    role?: 'VIEWER' | 'EDITOR' | 'ADMIN';
 }
 declare const AppContextProvider: React.Provider<AppContextValue | null>;
 /** Returns context info for the current app page (appSlug, pagePath, spaceId). */
@@ -36,6 +42,10 @@ interface AppApiClient {
      * Perform a POST request to a platform-data endpoint.
      */
     post<T>(path: string, body?: unknown): Promise<T>;
+    /**
+     * Perform a PUT request to a platform-data endpoint (e.g. write app settings).
+     */
+    put<T>(path: string, body?: unknown): Promise<T>;
     /**
      * Perform a PATCH request to a platform-data endpoint (e.g. update a record).
      */
@@ -44,6 +54,34 @@ interface AppApiClient {
      * Perform a DELETE request to a platform-data endpoint (e.g. delete a record).
      */
     delete<T>(path: string): Promise<T>;
+    /**
+     * Run one of this app's `uiInvoke` functions and get its return value back.
+     *
+     * This is the ONLY way a page can reach an integration: the action endpoint
+     * requires an app token and refuses a browser session. The platform mints the
+     * token server-side and runs the handler in-process.
+     *
+     * The function must be declared `trigger: { type: 'uiInvoke' }` in the
+     * manifest, and the caller must hold its `minRole` (default EDITOR).
+     *
+     * Pass `idempotencyKey` for anything that must not run twice on a double
+     * click — a concurrent duplicate is rejected with 409 INVOCATION_IN_FLIGHT.
+     *
+     * Throws AppInvokeError. `code === 'FUNCTION_REJECTED'` carries an app-authored
+     * message that is safe to show the user; every other failure is generic on
+     * purpose (raw provider errors can leak tokens or PII).
+     */
+    invoke<TResult, TInput = Record<string, unknown>>(functionName: string, input?: TInput, opts?: {
+        idempotencyKey?: string;
+        signal?: AbortSignal;
+    }): Promise<TResult>;
+}
+/** Thrown by AppApiClient.invoke. */
+declare class AppInvokeError extends Error {
+    readonly status: number;
+    readonly code?: string | undefined;
+    readonly invocationId?: string | undefined;
+    constructor(status: number, message: string, code?: string | undefined, invocationId?: string | undefined);
 }
 declare const AppApiProvider: React.Provider<AppApiClient | null>;
 /**
@@ -51,6 +89,26 @@ declare const AppApiProvider: React.Provider<AppApiClient | null>;
  * Requests go to /api/data/* with the session cookie (RBAC applies server-side).
  */
 declare function useAppApi(): AppApiClient;
+/**
+ * Reads and writes this app's settings (GET/PUT /data/apps/:appSlug/settings).
+ *
+ * The app slug comes from the surrounding AppContext, so a settings page only
+ * has to describe its form. Values are the ones the server merged with the
+ * `settings.fields` defaults declared in the manifest.
+ *
+ * Reading requires VIEWER, writing requires ADMIN. `save` never throws: it
+ * reports through `saveError`, which carries the raw failure (422
+ * SETTINGS_VALIDATION_FAILED with its per-key errors, or 403) so the page can
+ * map it back onto its fields. A failed save leaves `settings` untouched.
+ */
+declare function useAppSettings<T = Record<string, unknown>>(): {
+    settings: T | undefined;
+    isLoading: boolean;
+    error: unknown;
+    save: (patch: Partial<T>) => Promise<void>;
+    isSaving: boolean;
+    saveError: unknown;
+};
 
 declare const buttonVariants: (props?: ({
     variant?: "default" | "secondary" | "outline" | "ghost" | "destructive" | null | undefined;
@@ -139,5 +197,101 @@ interface DateRangePickerProps {
 }
 /** Minimal controlled date-range picker using two native date inputs. */
 declare function DateRangePicker({ value, onChange, className, disabled }: DateRangePickerProps): React.JSX.Element;
+type TextareaProps = React.TextareaHTMLAttributes<HTMLTextAreaElement>;
+declare const Textarea: React.ForwardRefExoticComponent<TextareaProps & React.RefAttributes<HTMLTextAreaElement>>;
+interface CheckboxProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, 'type' | 'onChange'> {
+    checked?: boolean;
+    /** Preferred over onChange — receives the boolean directly. */
+    onCheckedChange?: (checked: boolean) => void;
+    label?: React.ReactNode;
+}
+declare const Checkbox: React.ForwardRefExoticComponent<CheckboxProps & React.RefAttributes<HTMLInputElement>>;
+interface SidePanelProps {
+    open: boolean;
+    onClose: () => void;
+    title?: React.ReactNode;
+    description?: React.ReactNode;
+    children: React.ReactNode;
+    className?: string;
+}
+/**
+ * Blocking slide-over — reach for it when a task has more fields than a `Modal`
+ * can show without an inner scrollbar. Full height, so the body scrolls once and
+ * a footer can stay pinned; `Modal` centres a box and does no height management.
+ *
+ * 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.
+ */
+declare function SidePanel({ open, onClose, title, description, children, className, }: SidePanelProps): React.JSX.Element | null;
+interface CopyButtonProps {
+    value: string;
+    label?: string;
+    copiedLabel?: string;
+    variant?: ButtonProps['variant'];
+    size?: ButtonProps['size'];
+    className?: string;
+}
+/**
+ * Copy-to-clipboard button with inline feedback. On failure it says so rather
+ * than silently doing nothing — keep the copyable text selectable so manual
+ * copy stays the fallback.
+ */
+declare function CopyButton({ value, label, copiedLabel, variant, size, className, }: CopyButtonProps): React.JSX.Element;
+interface PopoverProps {
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+    trigger: React.ReactNode;
+    children: React.ReactNode;
+    align?: 'start' | 'end';
+    className?: string;
+}
+/** Anchored panel. Controlled — the caller owns `open`. Closes on outside click
+ *  and Escape, which is what a filter pill needs and a Modal is too heavy for. */
+declare function Popover({ open, onOpenChange, trigger, children, align, className, }: PopoverProps): React.JSX.Element;
+interface DropdownMenuItem {
+    label: React.ReactNode;
+    onSelect: () => void;
+    disabled?: boolean;
+    destructive?: boolean;
+}
+interface DropdownMenuProps {
+    trigger: React.ReactNode;
+    items: DropdownMenuItem[];
+    align?: 'start' | 'end';
+    className?: string;
+}
+/** Uncontrolled menu built on Popover. Selecting an item closes it. */
+declare function DropdownMenu({ trigger, items, align, className }: DropdownMenuProps): React.JSX.Element;
+
+/**
+ * Browser helpers for app pages.
+ *
+ * App bundles get react, react-dom and this SDK from the shell's import map and
+ * bundle everything else themselves — so without these here, every app would
+ * reimplement clipboard handling and CSV escaping, and get the edge cases wrong
+ * in its own way.
+ */
+/**
+ * Copy text to the clipboard.
+ *
+ * Returns `false` instead of throwing when the clipboard is unavailable (non
+ * secure context, permission refused) so the caller can render inline feedback.
+ * No `document.execCommand('copy')` fallback: it is deprecated, and the shell
+ * only ever runs on https or localhost, both secure contexts.
+ */
+declare function copyToClipboard(text: string): Promise<boolean>;
+/** Trigger a browser download of a Blob via a throwaway object URL + `<a>` click. */
+declare function downloadBlob(blob: Blob, filename: string): void;
+/** Serialize rows (header included) into an RFC 4180 CSV string. */
+declare function toCsv(rows: string[][]): string;
+/**
+ * Serialize + download in one call.
+ *
+ * The BOM is the whole reason this helper exists: without it Excel on Windows
+ * reads the file as latin-1 and mangles every accented character.
+ */
+declare function downloadCsv(rows: string[][], filename: string): void;
 
-export { type AppApiClient, AppApiProvider, AppContextProvider, type AppContextValue, Badge, type BadgeProps, Button, type ButtonProps, Card, CardContent, CardHeader, CardTitle, type DateRange, DateRangePicker, type DateRangePickerProps, Input, Link, type LinkProps, Modal, type ModalProps, Select, type SelectProps, Spinner, type SpinnerProps, Switch, type SwitchProps, Table, TableBody, TableCell, TableHead, TableHeader, TableRow, Tabs, TabsContent, TabsList, type TabsProps, TabsTrigger, cn, useAppApi, useAppContext };
+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 };

package/dist/index.d.ts

@@ -22,6 +22,12 @@ interface AppContextValue {
     pagePath: string;
     /** The active space id, when applicable. */
     spaceId?: string;
+    /**
+     * The current user's grant role on this app context, when the shell knows it.
+     * Settings pages use it to render read-only fields below ADMIN instead of
+     * letting the user discover the 403 at save time.
+     */
+    role?: 'VIEWER' | 'EDITOR' | 'ADMIN';
 }
 declare const AppContextProvider: React.Provider<AppContextValue | null>;
 /** Returns context info for the current app page (appSlug, pagePath, spaceId). */
@@ -36,6 +42,10 @@ interface AppApiClient {
      * Perform a POST request to a platform-data endpoint.
      */
     post<T>(path: string, body?: unknown): Promise<T>;
+    /**
+     * Perform a PUT request to a platform-data endpoint (e.g. write app settings).
+     */
+    put<T>(path: string, body?: unknown): Promise<T>;
     /**
      * Perform a PATCH request to a platform-data endpoint (e.g. update a record).
      */
@@ -44,6 +54,34 @@ interface AppApiClient {
      * Perform a DELETE request to a platform-data endpoint (e.g. delete a record).
      */
     delete<T>(path: string): Promise<T>;
+    /**
+     * Run one of this app's `uiInvoke` functions and get its return value back.
+     *
+     * This is the ONLY way a page can reach an integration: the action endpoint
+     * requires an app token and refuses a browser session. The platform mints the
+     * token server-side and runs the handler in-process.
+     *
+     * The function must be declared `trigger: { type: 'uiInvoke' }` in the
+     * manifest, and the caller must hold its `minRole` (default EDITOR).
+     *
+     * Pass `idempotencyKey` for anything that must not run twice on a double
+     * click — a concurrent duplicate is rejected with 409 INVOCATION_IN_FLIGHT.
+     *
+     * Throws AppInvokeError. `code === 'FUNCTION_REJECTED'` carries an app-authored
+     * message that is safe to show the user; every other failure is generic on
+     * purpose (raw provider errors can leak tokens or PII).
+     */
+    invoke<TResult, TInput = Record<string, unknown>>(functionName: string, input?: TInput, opts?: {
+        idempotencyKey?: string;
+        signal?: AbortSignal;
+    }): Promise<TResult>;
+}
+/** Thrown by AppApiClient.invoke. */
+declare class AppInvokeError extends Error {
+    readonly status: number;
+    readonly code?: string | undefined;
+    readonly invocationId?: string | undefined;
+    constructor(status: number, message: string, code?: string | undefined, invocationId?: string | undefined);
 }
 declare const AppApiProvider: React.Provider<AppApiClient | null>;
 /**
@@ -51,6 +89,26 @@ declare const AppApiProvider: React.Provider<AppApiClient | null>;
  * Requests go to /api/data/* with the session cookie (RBAC applies server-side).
  */
 declare function useAppApi(): AppApiClient;
+/**
+ * Reads and writes this app's settings (GET/PUT /data/apps/:appSlug/settings).
+ *
+ * The app slug comes from the surrounding AppContext, so a settings page only
+ * has to describe its form. Values are the ones the server merged with the
+ * `settings.fields` defaults declared in the manifest.
+ *
+ * Reading requires VIEWER, writing requires ADMIN. `save` never throws: it
+ * reports through `saveError`, which carries the raw failure (422
+ * SETTINGS_VALIDATION_FAILED with its per-key errors, or 403) so the page can
+ * map it back onto its fields. A failed save leaves `settings` untouched.
+ */
+declare function useAppSettings<T = Record<string, unknown>>(): {
+    settings: T | undefined;
+    isLoading: boolean;
+    error: unknown;
+    save: (patch: Partial<T>) => Promise<void>;
+    isSaving: boolean;
+    saveError: unknown;
+};
 
 declare const buttonVariants: (props?: ({
     variant?: "default" | "secondary" | "outline" | "ghost" | "destructive" | null | undefined;
@@ -139,5 +197,101 @@ interface DateRangePickerProps {
 }
 /** Minimal controlled date-range picker using two native date inputs. */
 declare function DateRangePicker({ value, onChange, className, disabled }: DateRangePickerProps): React.JSX.Element;
+type TextareaProps = React.TextareaHTMLAttributes<HTMLTextAreaElement>;
+declare const Textarea: React.ForwardRefExoticComponent<TextareaProps & React.RefAttributes<HTMLTextAreaElement>>;
+interface CheckboxProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, 'type' | 'onChange'> {
+    checked?: boolean;
+    /** Preferred over onChange — receives the boolean directly. */
+    onCheckedChange?: (checked: boolean) => void;
+    label?: React.ReactNode;
+}
+declare const Checkbox: React.ForwardRefExoticComponent<CheckboxProps & React.RefAttributes<HTMLInputElement>>;
+interface SidePanelProps {
+    open: boolean;
+    onClose: () => void;
+    title?: React.ReactNode;
+    description?: React.ReactNode;
+    children: React.ReactNode;
+    className?: string;
+}
+/**
+ * Blocking slide-over — reach for it when a task has more fields than a `Modal`
+ * can show without an inner scrollbar. Full height, so the body scrolls once and
+ * a footer can stay pinned; `Modal` centres a box and does no height management.
+ *
+ * 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.
+ */
+declare function SidePanel({ open, onClose, title, description, children, className, }: SidePanelProps): React.JSX.Element | null;
+interface CopyButtonProps {
+    value: string;
+    label?: string;
+    copiedLabel?: string;
+    variant?: ButtonProps['variant'];
+    size?: ButtonProps['size'];
+    className?: string;
+}
+/**
+ * Copy-to-clipboard button with inline feedback. On failure it says so rather
+ * than silently doing nothing — keep the copyable text selectable so manual
+ * copy stays the fallback.
+ */
+declare function CopyButton({ value, label, copiedLabel, variant, size, className, }: CopyButtonProps): React.JSX.Element;
+interface PopoverProps {
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+    trigger: React.ReactNode;
+    children: React.ReactNode;
+    align?: 'start' | 'end';
+    className?: string;
+}
+/** Anchored panel. Controlled — the caller owns `open`. Closes on outside click
+ *  and Escape, which is what a filter pill needs and a Modal is too heavy for. */
+declare function Popover({ open, onOpenChange, trigger, children, align, className, }: PopoverProps): React.JSX.Element;
+interface DropdownMenuItem {
+    label: React.ReactNode;
+    onSelect: () => void;
+    disabled?: boolean;
+    destructive?: boolean;
+}
+interface DropdownMenuProps {
+    trigger: React.ReactNode;
+    items: DropdownMenuItem[];
+    align?: 'start' | 'end';
+    className?: string;
+}
+/** Uncontrolled menu built on Popover. Selecting an item closes it. */
+declare function DropdownMenu({ trigger, items, align, className }: DropdownMenuProps): React.JSX.Element;
+
+/**
+ * Browser helpers for app pages.
+ *
+ * App bundles get react, react-dom and this SDK from the shell's import map and
+ * bundle everything else themselves — so without these here, every app would
+ * reimplement clipboard handling and CSV escaping, and get the edge cases wrong
+ * in its own way.
+ */
+/**
+ * Copy text to the clipboard.
+ *
+ * Returns `false` instead of throwing when the clipboard is unavailable (non
+ * secure context, permission refused) so the caller can render inline feedback.
+ * No `document.execCommand('copy')` fallback: it is deprecated, and the shell
+ * only ever runs on https or localhost, both secure contexts.
+ */
+declare function copyToClipboard(text: string): Promise<boolean>;
+/** Trigger a browser download of a Blob via a throwaway object URL + `<a>` click. */
+declare function downloadBlob(blob: Blob, filename: string): void;
+/** Serialize rows (header included) into an RFC 4180 CSV string. */
+declare function toCsv(rows: string[][]): string;
+/**
+ * Serialize + download in one call.
+ *
+ * The BOM is the whole reason this helper exists: without it Excel on Windows
+ * reads the file as latin-1 and mangles every accented character.
+ */
+declare function downloadCsv(rows: string[][], filename: string): void;
 
-export { type AppApiClient, AppApiProvider, AppContextProvider, type AppContextValue, Badge, type BadgeProps, Button, type ButtonProps, Card, CardContent, CardHeader, CardTitle, type DateRange, DateRangePicker, type DateRangePickerProps, Input, Link, type LinkProps, Modal, type ModalProps, Select, type SelectProps, Spinner, type SpinnerProps, Switch, type SwitchProps, Table, TableBody, TableCell, TableHead, TableHeader, TableRow, Tabs, TabsContent, TabsList, type TabsProps, TabsTrigger, cn, useAppApi, useAppContext };
+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 };