@tight-embedded/react 6.3.1 → 6.4.0

package/dist/index.d.ts

@@ -1,6 +1,49 @@
+import { ComponentPropsWithoutRef } from 'react';
 import { JSX } from 'react/jsx-runtime';
 import { PropsWithChildren } from 'react';
 
+/**
+ * A valid anchor target string across all pages that define anchor sections.
+ *
+ * @see PAGE_ANCHOR_MAP
+ * @see AnchorFor
+ */
+export declare type Anchor = AnchorFor<keyof PageAnchorMap>;
+
+/**
+ * Extracts the valid anchor string values for a specific page `T`.
+ *
+ * @example
+ * ```TypeScript
+ * type BODAnchors = AnchorFor<"FinancialOverviewDashboard">;
+ * // = "conversations-section" | "transactions-section"
+ * ```
+ */
+declare type AnchorFor<T extends keyof PageAnchorMap> = T extends keyof PageAnchorMap ? PageAnchorMap[T][keyof PageAnchorMap[T]] : never;
+
+/**
+ * Props for the `<TightApp />` component.
+ *
+ * @see TightApp
+ * @see NavState
+ */
+declare type AppProps = {
+    /** The current navigation target. Controls which page, anchor, and drawer are active. */
+    navState: NavState;
+    /** Called when the user triggers an internal navigation event. The host must update `navState` in response. */
+    onNavigate: (navState: NavState) => void;
+    /** Bearer token used to authenticate API requests. Obtain one from the Tight Authentication Endpoint. */
+    accessToken: string;
+    /** Selects the Tight API environment. Defaults to `"PRODUCTION"`. Use `"SANDBOX"` for development and testing. */
+    environment?: Environment;
+};
+
+declare function BankAccountForm({ bankAccountId }: BankAccountFormProps): JSX.Element;
+
+declare type BankAccountFormProps = {
+    bankAccountId: string;
+};
+
 export declare function BanksAndIntegrations({ onPlaidLink }: BanksAndIntegrationsComponentProps): JSX.Element;
 
 declare type BanksAndIntegrationsComponentProps = {
@@ -13,6 +56,25 @@ declare type BanksAndIntegrationsOptions = {
     hideManualBanks?: boolean;
 };
 
+declare function BankTransactionForm({ transactionId, initialTab, initialType }: BankTransactionFormProps): JSX.Element | undefined;
+
+declare type BankTransactionFormProps = {
+    transactionId?: string;
+    initialTab?: FormTab;
+    initialType?: BankTransactionType;
+};
+
+declare type BankTransactionType = "EXPENSE" | "REVENUE" | "TRANSFER_IN" | "TRANSFER_OUT";
+
+/**
+ * A top-level page name within the Tight application.
+ *
+ * Each value corresponds to one of the primary dashboard views rendered by `<TightApp />`.
+ *
+ * @see NavState
+ */
+export declare type BasePage = "FinancialOverviewDashboard";
+
 export declare function BusinessOwnerDashboard(props: BusinessOwnerDashboardProps): JSX.Element;
 
 declare type BusinessOwnerDashboardProps = {
@@ -20,6 +82,43 @@ declare type BusinessOwnerDashboardProps = {
     onChangePeriod?: (period: Period) => void;
 };
 
+/**
+ * A standalone drawer for rendering a conversation that is not attached to an entity.
+ * @param conversationId
+ * @param defaultValues
+ * @constructor
+ */
+declare function ConversationDrawer({ conversationId, defaultValues }: ConversationDrawerProps): JSX.Element;
+
+declare type ConversationDrawerProps = {
+    conversationId: Nullable<string>;
+    defaultValues?: MessageFormValues;
+};
+
+export declare type DrawerNavObject = {
+    [K in DrawerRouteNames]: {
+        name: K;
+        props?: DrawerProps[K];
+    };
+}[DrawerRouteNames];
+
+declare type DrawerProps = {
+    BankTransactionForm: ComponentPropsWithoutRef<typeof BankTransactionForm>;
+    Conversation: ComponentPropsWithoutRef<typeof ConversationDrawer>;
+    MobileConversation: ComponentPropsWithoutRef<typeof MobileConversationDrawer>;
+    BankAccountForm: ComponentPropsWithoutRef<typeof BankAccountForm>;
+    NewConnection: EmptyObject;
+    FinancialSummary: ComponentPropsWithoutRef<typeof FinancialSummaryDrawer>;
+    BanksAndIntegrations: EmptyObject;
+    TransactionsFilterList: EmptyObject;
+    RevenueFilterList: EmptyObject;
+    ExpensesFilterList: EmptyObject;
+};
+
+declare type DrawerRouteNames = keyof DrawerProps;
+
+declare type EmptyObject = Record<string, never>;
+
 export declare type Environment = ValueOf<typeof Environments>;
 
 declare const Environments: {
@@ -42,6 +141,15 @@ declare type ExternalOptions = {
     banksAndIntegrations?: BanksAndIntegrationsOptions;
 };
 
+declare function FinancialSummaryDrawer({ summaryId, conversationId }: FinancialSummaryDrawerProps): JSX.Element;
+
+declare type FinancialSummaryDrawerProps = {
+    summaryId: string;
+    conversationId?: string;
+};
+
+declare type FormTab = "conversation" | "audit trail";
+
 export declare const IncomeDashboard: (props: IncomeDashboardProps) => JSX.Element;
 
 declare type IncomeDashboardProps = {
@@ -51,6 +159,60 @@ declare type IncomeDashboardProps = {
 
 declare type IntegrationIdentifier = typeof SUPPORTED_INTEGRATION_IDENTIFIERS[number];
 
+declare type MessageFormValues = {
+    message: {
+        text: string;
+        attachments: UploadedAttachmentInfo[];
+    };
+};
+
+declare function MobileConversationDrawer({ conversationId, transactionId }: MobileConversationDrawerProps): JSX.Element;
+
+declare type MobileConversationDrawerProps = {
+    conversationId: Nullable<string>;
+    transactionId: Nullable<string>;
+};
+
+/**
+ * Describes a navigation target within the Tight application.
+ *
+ * `NavState` is a discriminated union keyed on `page`. The `anchor` field is
+ * constrained to strings that are valid for the specified page — pages with no
+ * defined anchors do not accept an `anchor` value at all. The optional `drawer`
+ * field opens a specific drawer on top of the page when present.
+ *
+ * @example
+ * ```TypeScript
+ * // Navigate to a top-level page
+ * const nav: NavState = { page: "FinancialOverviewDashboard" };
+ *
+ * // Navigate to a specific anchor section
+ * const navWithAnchor: NavState = {
+ *   page: "FinancialOverviewDashboard",
+ *   anchor: "conversations-section",
+ * };
+ *
+ * // Navigate to a page with a drawer open
+ * const navWithDrawer: NavState = {
+ *   page: "TransactionsDashboard",
+ *   drawer: { name: "BankTransactionForm" },
+ * };
+ *
+ * // TypeScript error — "conversations-section" is not valid on this page
+ * const invalid: NavState = {
+ *   page: "TransactionsDashboard",
+ *   anchor: "conversations-section", // ← type error
+ * };
+ * ```
+ */
+export declare type NavState = {
+    [P in BasePage]: {
+        page: P;
+        anchor?: P extends keyof PageAnchorMap ? AnchorFor<P> : never;
+        drawer?: DrawerNavObject;
+    };
+}[BasePage];
+
 declare type Nullable<T> = T | null;
 
 declare type ObjectKey = string | number | symbol;
@@ -69,6 +231,41 @@ declare type OnPlaidLinkEventData = {
 
 declare type OptionSetter = (options: Partial<ExternalOptions>, replace?: boolean) => void;
 
+/**
+ * Maps each page to its available anchor targets, keyed by semantic name.
+ *
+ */
+declare const PAGE_ANCHOR_MAP: {
+    readonly FinancialOverviewDashboard: {
+        readonly CONVERSATIONS: "conversations-section";
+        readonly TRANSACTIONS: "transactions-section";
+    };
+};
+
+declare type PageAnchorMap = typeof PAGE_ANCHOR_MAP;
+
+/**
+ * Parses a URL string into a `NavObject` for use as the `navObject` prop on `<App />`.
+ *
+ * Returns `undefined` if the URL is malformed, the `bkPage` param is missing or
+ * invalid, or a drawer is specified but its required props are invalid.
+ *
+ * @param url - A fully-qualified URL string containing Tight navigation params.
+ * @returns A typed `NavObject`, or `undefined` if the URL cannot be parsed.
+ *
+ * @example
+ * ```TypeScript
+ * const nav = parseNavUrl("https://app.example.com?bkPage=FinancialOverviewDashboard");
+ * // nav = { page: "FinancialOverviewDashboard" }
+ *
+ * const navWithAnchor = parseNavUrl(
+ *   "https://app.example.com?bkPage=FinancialOverviewDashboard&bkAnchor=conversations-section"
+ * );
+ * // navWithAnchor = { page: "FinancialOverviewDashboard", anchor: "conversations-section" }
+ * ```
+ */
+export declare function parseNavUrl(url: string): NavState | undefined;
+
 declare type Period = {
     month: number;
     year: number;
@@ -88,6 +285,27 @@ declare const SUPPORTED_INTEGRATION_IDENTIFIERS: readonly ["UNIT", "STRIPE", "GU
 
 export declare function Tight({ children, environment, accessToken }: TightProps): JSX.Element;
 
+/**
+ * The root component of the Tight application.
+ *
+ * Wraps all dashboard views in a shared `MemoryRouter` and navigation context.
+ * Navigation state is driven externally via the `navState` prop, making the
+ * component fully controlled — the host application owns navigation state.
+ *
+ * @param accessToken - Bearer token used to authenticate API requests.
+ * @param environment - Selects the Tight API environment (`"PRODUCTION"` or `"SANDBOX"`). Defaults to `"PRODUCTION"`.
+ * @param navState - The current navigation target. Controls page, anchor, and open drawer.
+ * @param onNavigate - Callback fired when the user triggers an internal navigation event.
+ *
+ * @example
+ * ```TypeScript
+ * const [nav, setNav] = useState<NavState>({ page: "FinancialOverviewDashboard" });
+ *
+ * <TightApp accessToken={accessToken} navState={nav} onNavigate={setNav} />
+ * ```
+ */
+export declare function TightApp({ accessToken, environment, navState, onNavigate }: AppProps): JSX.Element;
+
 declare type TightProps = PropsWithChildren<{
     environment: Environment;
     accessToken: string;
@@ -117,14 +335,22 @@ declare const TransactionTableColumns: {
     readonly COMMENTS: "comments";
 };
 
+declare type UploadedAttachmentInfo = {
+    localId: string;
+    id: number | null;
+    file: File;
+    displayFileName: string;
+    displayText: string;
+    isPending: boolean;
+    hasError: boolean;
+    fileSize: Nullable<string>;
+    iconUrl: Nullable<string>;
+    publicFileUrl: Nullable<string>;
+};
+
 /**
  * Set library-wide options for various components.
  *
- * For Developers:
- * This hook subscribes a component to Tight Embedded's option store, which is shared across all Tight Components
- * The initial options passed into the hook will be set as the value of options on the hook's first render.
- * When a component modifies these options by calling setOptions, all subscribed components will re-render with the new options
- *
  * @param initialOptions - options to pass into the store on first render of this hook.
  *
  * @example