tempest-react-sdk 0.1.5 → 0.2.0

package/README.md

@@ -17,7 +17,7 @@ The goal is to start every new React frontend with the same opinionated foundati
 
 - [Recommended stack](#recommended-stack)
 - [Install](#install)
-  - [Peer dependencies](#peer-dependencies)
+  - [Peer & bundled dependencies](#peer--bundled-dependencies)
   - [CSS import](#css-import)
 - [What's inside](#whats-inside)
 - [Architecture overview](#architecture-overview)
@@ -109,28 +109,33 @@ Via `package.json`:
 
 Requires React `>=18` and Node `>=20.19` to build.
 
-### Peer dependencies
+### Peer & bundled dependencies
 
-`react` and `react-dom` are **required** peer dependencies. Everything else is **optional** — install only the packages the modules you import actually need. Importing `tempest-react-sdk` without an optional peer never throws; the failure surfaces only when you instantiate the helper that uses it.
+Only **react** and **react-dom** are peer dependencies — those must come from the host app so a single React copy lives in the tree.
 
-| Peer                                          | Required by                                                         | Status       |
-| --------------------------------------------- | ------------------------------------------------------------------- | ------------ |
-| `react`, `react-dom` (`^18.0.0 \|\| ^19.0.0`) | Everything                                                          | **Required** |
-| `@tanstack/react-query` (`^5`)                | `QueryProvider`, `createQueryKeys`                                  | Optional     |
-| `zod` (`^3.23 \|\| ^4`)                       | `parseResponse`, `validateForm`, `zodResolver`, `useZodForm`        | Optional     |
-| `zustand` (`^4 \|\| ^5`)                      | `createAuthStore`                                                   | Optional     |
-| `dexie` (`^4.4`)                              | `createOfflineStore`                                                | Optional     |
-| `react-hook-form` (`^7.76`)                   | `zodResolver`, `useZodForm`, masked inputs                          | Optional     |
-| `lucide-react` (`>=0.400`)                    | Component icons (`leftIcon`/`rightIcon` on `Input`, `Button`, etc.) | Optional     |
+Everything else (`zod`, `zustand`, `dexie`, `react-hook-form`, `@tanstack/react-query`, `lucide-react`) is a **direct dependency** of the SDK, installed automatically by `npm install tempest-react-sdk`. You never need to install them manually.
 
-Quick recipe for a "typical" app that uses HTTP + Query + Auth + Forms:
+| Package                               | Status              | Used by                                                             |
+| ------------------------------------- | ------------------- | ------------------------------------------------------------------- |
+| `react`, `react-dom` (`^18 \|\| ^19`) | **Peer (required)** | Everything                                                          |
+| `@tanstack/react-query` (`^5`)        | Direct dep (auto)   | `QueryProvider`, `createQueryKeys`                                  |
+| `zod` (`^3.23 \|\| ^4`)               | Direct dep (auto)   | `parseResponse`, `validateForm`, `zodResolver`, `useZodForm`        |
+| `zustand` (`^4 \|\| ^5`)              | Direct dep (auto)   | `createAuthStore`                                                   |
+| `dexie` (`^4.4`)                      | Direct dep (auto)   | `createOfflineStore`                                                |
+| `react-hook-form` (`^7.76`)           | Direct dep (auto)   | `zodResolver`, `useZodForm`, masked inputs                          |
+| `lucide-react` (`>=0.400`)            | Direct dep (auto)   | Component icons (`leftIcon`/`rightIcon` on `Input`, `Button`, etc.) |
+
+The minimum install is just:
 
 ```bash
-npm install tempest-react-sdk react react-dom \
-  @tanstack/react-query zod zustand react-hook-form lucide-react
+npm install tempest-react-sdk react react-dom
 ```
 
-If a module is missing its peer dep at runtime, the bundler will flag the missing import at build time — there is no "silent fallback" behaviour. Add only what you actually consume.
+**Bundle impact**: every bundled dep is externalised in the SDK's Rollup config, so the SDK's published bundle stays at ~104 KB ESM. Your app's bundler (Vite / webpack / Rspack) resolves these from `node_modules` and tree-shakes — if you never call `createOfflineStore`, Dexie never enters your final bundle.
+
+**Version conflicts**: if your app already pins (say) `zod@3.20`, npm dedupes when the range is compatible. If ranges diverge you get two copies — pin a single version in your own `package.json` to force one, or open an issue if the SDK's range is too tight.
+
+Adapters for external SDKs (`@sentry/browser`, `posthog-js`, `@growthbook/growthbook`, `launchdarkly-js-client-sdk`) are **not** bundled — install those only when you opt into the adapter. The caller passes the SDK instance to the factory.
 
 ### CSS import
 

package/dist/index.d.ts

@@ -28,6 +28,30 @@ import { UseFormProps } from 'react-hook-form';
 import { UseFormReturn } from 'react-hook-form';
 import { z } from 'zod';
 
+/**
+ * Inline alert / notice with tone (info/success/warning/danger) and appearance
+ * (soft/solid/outline). Accepts optional `icon`, `title`, `description` and
+ * a dismiss button via `onClose`.
+ */
+export declare function Alert({ variant, appearance, title, description, icon, onClose, closeLabel, className, children, ...props }: AlertProps): JSX.Element;
+
+export declare type AlertAppearance = "soft" | "solid" | "outline";
+
+export declare interface AlertProps extends Omit<HTMLAttributes<HTMLDivElement>, "title"> {
+    variant?: AlertVariant;
+    /** Visual style: soft (default tinted bg), solid (filled), outline (bordered). */
+    appearance?: AlertAppearance;
+    title?: ReactNode;
+    description?: ReactNode;
+    icon?: ReactNode;
+    /** Show a close button and invoke this when clicked. */
+    onClose?: () => void;
+    /** Custom close button label for screen readers. */
+    closeLabel?: string;
+}
+
+export declare type AlertVariant = "neutral" | "info" | "success" | "warning" | "danger";
+
 export declare interface ApiClient {
     request<T>(path: string, options?: RequestOptions): Promise<T>;
     get<T>(path: string, options?: RequestOptions): Promise<T>;
@@ -177,6 +201,30 @@ export declare interface BreadcrumbsProps {
     className?: string;
 }
 
+/**
+ * Breakpoint keys exposed by the SDK. Values mirror the CSS tokens
+ * `--tempest-bp-xs|sm|md|lg|xl|2xl` defined in `styles/colors.css`.
+ */
+export declare type Breakpoint = "xs" | "sm" | "md" | "lg" | "xl" | "2xl";
+
+export declare interface BreakpointHelpers {
+    /** Current breakpoint key (the largest one whose min-width is matched). */
+    current: Breakpoint;
+    /** Window width in pixels at last update. `0` when SSR. */
+    width: number;
+    /** True when viewport width is `>=` the given breakpoint. */
+    above: (bp: Breakpoint) => boolean;
+    /** True when viewport width is `<` the given breakpoint. */
+    below: (bp: Breakpoint) => boolean;
+    /** Convenience flags mapping to typical device shapes. */
+    isMobile: boolean;
+    isTablet: boolean;
+    isDesktop: boolean;
+}
+
+/** Pixel value paired with each breakpoint key. */
+export declare const BREAKPOINTS: Record<Breakpoint, number>;
+
 /**
  * Primary action button with variants, sizes and a loading state that
  * preserves layout via an absolutely-positioned spinner.
@@ -316,7 +364,10 @@ export declare const consoleSink: LoggerSink;
  */
 export declare const consoleTelemetryAdapter: TelemetryAdapter;
 
-/** Page-level horizontal container with a max-width preset and side padding. */
+/**
+ * Page-level horizontal container with a max-width preset and responsive
+ * side padding (`space-4` mobile / `space-6` tablet / `space-8` desktop).
+ */
 export declare function Container({ size, className, children, ...props }: ContainerProps): JSX.Element;
 
 export declare interface ContainerProps extends HTMLAttributes<HTMLDivElement> {
@@ -723,13 +774,34 @@ export declare interface DecodedJWT {
  */
 export declare function decodeJWT(token: string): DecodedJWT;
 
+/**
+ * Horizontal or vertical visual separator. When `label` is provided in
+ * horizontal mode the divider splits and centers the label between two lines.
+ */
+export declare function Divider({ orientation, variant, label, align, className, ...props }: DividerProps): JSX.Element;
+
+export declare type DividerAlign = "start" | "center" | "end";
+
+export declare type DividerOrientation = "horizontal" | "vertical";
+
+export declare interface DividerProps extends Omit<HTMLAttributes<HTMLDivElement>, "children"> {
+    orientation?: DividerOrientation;
+    variant?: DividerVariant;
+    /** Optional label rendered inside the divider (horizontal only). */
+    label?: ReactNode;
+    /** Label horizontal position (only when `label` provided). Defaults to `center`. */
+    align?: DividerAlign;
+}
+
+export declare type DividerVariant = "solid" | "dashed";
+
 export declare type DocumentVisibility = "visible" | "hidden";
 
 /**
  * Sliding side panel. Same building blocks as {@link Modal} but anchored to
  * an edge. Locks body scroll while open.
  */
-export declare function Drawer({ open, onClose, placement, title, children, footer, closeOnBackdrop, closeOnEsc, hideCloseButton, className, }: DrawerProps): ReactPortal | null;
+export declare function Drawer({ open, onClose, placement, title, children, footer, closeOnBackdrop, closeOnEsc, hideCloseButton, className, mobilePlacement, showHandle, }: DrawerProps): ReactPortal | null;
 
 export declare type DrawerPlacement = "right" | "left" | "top" | "bottom";
 
@@ -744,6 +816,14 @@ export declare interface DrawerProps {
     closeOnEsc?: boolean;
     hideCloseButton?: boolean;
     className?: string;
+    /**
+     * Auto-switch to bottom-sheet placement on mobile viewports (< md).
+     * Modern mobile apps default to bottom drawers; on desktop the original
+     * `placement` is preserved.
+     */
+    mobilePlacement?: DrawerPlacement;
+    /** Render a drag handle indicator at the leading edge (bottom-sheet style). */
+    showHandle?: boolean;
 }
 
 export declare interface ElementSize {
@@ -1062,10 +1142,10 @@ export declare interface GetInitialThemeOptions {
 export declare function Grid({ columns, gap, className, style, children, ...props }: GridProps): JSX.Element;
 
 export declare interface GridProps extends HTMLAttributes<HTMLDivElement> {
-    /** Number of columns or a custom `grid-template-columns` value. */
-    columns?: number | string;
-    /** Gap as a CSS length. Numbers map to a multiple of the 4px scale. */
-    gap?: number | string;
+    /** Number of columns or a custom `grid-template-columns` value. Accepts responsive object. */
+    columns?: ResponsiveValue<number | string>;
+    /** Gap as a CSS length. Numbers map to a multiple of the 4px scale. Accepts responsive object. */
+    gap?: ResponsiveValue<number | string>;
     children?: ReactNode;
 }
 
@@ -1080,6 +1160,19 @@ export declare interface GrowthBookLike {
     setRenderer?: (renderer: () => void) => void;
 }
 
+/** Inverse of `<Show>` — hides children when the condition matches. */
+export declare function Hide({ above, below, only, children }: HideProps): ReactNode;
+
+export declare interface HideProps {
+    /** Hide children when viewport width is `>=` this breakpoint. */
+    above?: Breakpoint;
+    /** Hide children when viewport width is `<` this breakpoint. */
+    below?: Breakpoint;
+    /** Hide on specific breakpoints. */
+    only?: Breakpoint | Breakpoint[];
+    children: ReactNode;
+}
+
 export declare interface I18n {
     /** Currently active locale. */
     locale: string;
@@ -1207,6 +1300,18 @@ export declare function isPushSupported(): boolean;
 /** True when the Web Share API is available in this environment. */
 export declare function isShareSupported(): boolean;
 
+/**
+ * Renders a `<kbd>` styled like a keyboard key — useful for shortcut hints.
+ * Compose multiple keys by rendering siblings: `<Kbd>Ctrl</Kbd> + <Kbd>K</Kbd>`.
+ */
+export declare function Kbd({ size, className, children, ...props }: KbdProps): JSX.Element;
+
+export declare interface KbdProps extends HTMLAttributes<HTMLElement> {
+    size?: KbdSize;
+}
+
+export declare type KbdSize = "sm" | "md" | "lg";
+
 export declare interface KeyboardShortcut {
     /** Key name (`"k"`, `"Enter"`, `"Escape"`, `"ArrowDown"`, etc.). Case-insensitive. */
     key: string;
@@ -1306,7 +1411,7 @@ export declare type Messages = Record<string, string>;
  * Portal-rendered modal dialog with backdrop, Esc handler, and slots for
  * header/body/footer. Locks body scroll while open.
  */
-export declare function Modal({ open, onClose, title, children, footer, size, closeOnBackdrop, closeOnEsc, className, hideCloseButton, }: ModalProps): ReactPortal | null;
+export declare function Modal({ open, onClose, title, children, footer, size, closeOnBackdrop, closeOnEsc, className, hideCloseButton, fullscreen, fullscreenOnMobile, }: ModalProps): ReactPortal | null;
 
 export declare interface ModalProps {
     open: boolean;
@@ -1319,9 +1424,13 @@ export declare interface ModalProps {
     closeOnEsc?: boolean;
     className?: string;
     hideCloseButton?: boolean;
+    /** Force fullscreen at all breakpoints. */
+    fullscreen?: boolean;
+    /** Auto-fullscreen on mobile viewports (< 640px). Default `false`. */
+    fullscreenOnMobile?: boolean;
 }
 
-export declare type ModalSize = "sm" | "md" | "lg" | "xl";
+export declare type ModalSize = "sm" | "md" | "lg" | "xl" | "2xl" | "3xl";
 
 /**
  * Currency-masked input. Stores the value as an integer number of cents to
@@ -1610,6 +1719,17 @@ declare interface ResolverOutput<T> {
     errors: Record<string, ResolverError | object>;
 }
 
+/**
+ * Responsive value — either a single value applied at all breakpoints, or
+ * an object with `mobile` / `tablet` / `desktop` overrides. Apps can mix
+ * any combination; `mobile` is the base, `tablet` / `desktop` cascade up.
+ */
+export declare type ResponsiveValue<T> = T | {
+    mobile?: T;
+    tablet?: T;
+    desktop?: T;
+};
+
 /**
  * Run `factory()` with exponential backoff. Each attempt awaits an
  * increasing delay capped at `maxDelay`. Throws the last error if every
@@ -1722,6 +1842,28 @@ export declare interface ShareResult {
     error?: unknown;
 }
 
+/**
+ * Conditionally render children based on the viewport breakpoint.
+ *
+ * - `above` — render when viewport width is `>=` the given breakpoint.
+ * - `below` — render when viewport width is `<` the given breakpoint.
+ * - `only` — render only on the listed breakpoint(s).
+ *
+ * SSR-safe: first render uses `xs` (renders mobile content first); the
+ * component re-renders once `useBreakpoint` has the real viewport width.
+ */
+export declare function Show({ above, below, only, children }: ShowProps): ReactNode;
+
+export declare interface ShowProps {
+    /** Render children only when viewport width is `>=` this breakpoint. */
+    above?: Breakpoint;
+    /** Render children only when viewport width is `<` this breakpoint. */
+    below?: Breakpoint;
+    /** Render only on specific breakpoints. Wins over `above`/`below` when set. */
+    only?: Breakpoint | Breakpoint[];
+    children: ReactNode;
+}
+
 /** Loading placeholder block. Use `variant="text"` for inline lines, `circle` for avatars. */
 export declare function Skeleton({ variant, width, height, className, style }: SkeletonProps): JSX.Element;
 
@@ -1739,7 +1881,7 @@ export declare interface SkeletonProps {
  */
 export declare function skipWaiting(worker: ServiceWorker): void;
 
-/** Loading spinner with three preset sizes. Provide `label` for screen readers. */
+/** Loading spinner with preset sizes (xs..xl). Provide `label` for screen readers. */
 export declare function Spinner({ size, className, label }: SpinnerProps): JSX.Element;
 
 export declare interface SpinnerProps {
@@ -1748,20 +1890,22 @@ export declare interface SpinnerProps {
     label?: string;
 }
 
-export declare type SpinnerSize = "sm" | "md" | "lg";
+export declare type SpinnerSize = "xs" | "sm" | "md" | "lg" | "xl";
 
 /** Flex-based vertical or horizontal stack with a numeric `gap`. */
 export declare function Stack({ direction, gap, align, justify, wrap, className, style, children, ...props }: StackProps): JSX.Element;
 
 export declare type StackAlign = "start" | "center" | "end" | "stretch";
 
+export declare type StackDirection = "vertical" | "horizontal";
+
 export declare type StackJustify = "start" | "center" | "end" | "between";
 
 export declare interface StackProps extends HTMLAttributes<HTMLDivElement> {
-    /** Direction. Default `vertical`. */
-    direction?: "vertical" | "horizontal";
-    /** Gap as a CSS length. Numbers map to a multiple of the 4px scale. */
-    gap?: number | string;
+    /** Direction. Accepts responsive object — e.g. `{ mobile: "vertical", desktop: "horizontal" }`. */
+    direction?: ResponsiveValue<StackDirection>;
+    /** Gap as a CSS length. Numbers map to a multiple of the 4px scale. Accepts responsive object. */
+    gap?: ResponsiveValue<number | string>;
     align?: StackAlign;
     justify?: StackJustify;
     wrap?: boolean;
@@ -1824,11 +1968,13 @@ export declare interface TabItem {
 }
 
 /**
- * Lightweight table that maps a list of rows through declarative `columns`.
- * Provide `rowKey` so React reconciliation works. Rows become clickable when
- * `onRowClick` is supplied.
+ * Lightweight table with declarative columns + mobile niceties.
+ *
+ * - `priority` per column lets less-important data hide on narrow viewports.
+ * - `stackOnMobile` re-renders each row as a label/value card on mobile,
+ *   avoiding horizontal scroll for dense data.
  */
-export declare function Table<T>({ columns, data, rowKey, onRowClick, emptyMessage, className, }: TableProps<T>): JSX.Element;
+export declare function Table<T>({ columns, data, rowKey, onRowClick, emptyMessage, className, stackOnMobile, }: TableProps<T>): JSX.Element;
 
 export declare type TableAlign = "left" | "right" | "center";
 
@@ -1840,8 +1986,15 @@ export declare interface TableColumn<T> {
     align?: TableAlign;
     width?: string | number;
     className?: string;
+    /**
+     * Visibility priority: `always` (default) shows on every viewport,
+     * `tablet` hides below md (< 768px), `desktop` hides below lg (< 1024px).
+     */
+    priority?: TablePriority;
 }
 
+export declare type TablePriority = "always" | "tablet" | "desktop";
+
 export declare interface TableProps<T> {
     columns: TableColumn<T>[];
     data: T[];
@@ -1849,6 +2002,11 @@ export declare interface TableProps<T> {
     onRowClick?: (row: T) => void;
     emptyMessage?: ReactNode;
     className?: string;
+    /**
+     * Stack mode — render rows as label/value cards on mobile (< md).
+     * Better than horizontal scroll when each row has 3+ columns of dense data.
+     */
+    stackOnMobile?: boolean;
 }
 
 /**
@@ -1983,15 +2141,19 @@ export declare interface ToastOptions {
     duration?: number;
 }
 
+export declare type ToastPosition = "top-right" | "top-left" | "top-center" | "bottom-right" | "bottom-left" | "bottom-center";
+
 /**
  * Renders a portalled toast container and exposes the imperative {@link useToast} API.
  */
-export declare function ToastProvider({ children, defaultDuration }: ToastProviderProps): JSX.Element;
+export declare function ToastProvider({ children, defaultDuration, position, }: ToastProviderProps): JSX.Element;
 
 export declare interface ToastProviderProps {
     children: ReactNode;
     /** Default auto-dismiss duration (ms). Default 4000. */
     defaultDuration?: number;
+    /** Stack position on screen. Default `"top-right"`. */
+    position?: ToastPosition;
 }
 
 export declare type ToastVariant = "success" | "warning" | "error" | "info";
@@ -2109,6 +2271,15 @@ export declare interface UseBeforeInstallPromptResult {
     prompt: () => Promise<"accepted" | "dismissed" | "unsupported">;
 }
 
+/**
+ * Reactive viewport-breakpoint hook.
+ *
+ * Returns the current breakpoint key plus `above` / `below` helpers and
+ * `isMobile` / `isTablet` / `isDesktop` flags. SSR-safe — returns `xs` /
+ * `width: 0` on the server, then updates after mount.
+ */
+export declare function useBreakpoint(): BreakpointHelpers;
+
 /**
  * Client-side filter helper. Performs a case-insensitive match on the listed
  * keys when no custom predicate is provided.