calcsuite-react 1.0.0

package/dist/transport/fx.d.ts

@@ -0,0 +1,23 @@
+import type { FxRateProvider } from './types';
+export interface RateSnapshot {
+    base: string;
+    timestamp: string;
+    rates: Record<string, string>;
+    lastUpdated: number;
+    stale: boolean;
+}
+export interface FxCacheOptions {
+    ttlMs?: number;
+    /** Injected/offline seed: base → rates. Used when the provider can't be reached. */
+    seed?: Record<string, Record<string, string>>;
+    now?: () => number;
+}
+export declare function createFxCache(provider: FxRateProvider | undefined, options?: FxCacheOptions): {
+    getRates: (base: string, symbols: string[]) => Promise<RateSnapshot>;
+    /** Non-throwing peek at whatever is cached, if anything. */
+    peek: (base: string, symbols: string[]) => RateSnapshot | undefined;
+    readonly lastUpdated: Date | null;
+    isStale(base: string, symbols: string[]): boolean;
+    clear: () => void;
+};
+export type FxCache = ReturnType<typeof createFxCache>;

package/dist/transport/payload.d.ts

@@ -0,0 +1,21 @@
+import type { KeyCase, PayloadContext, PayloadEnvelope, PayloadField, SaveContext } from './types';
+/** Apply keyCase to each dot-path segment (so 'meta.tenantId' cases both). */
+export declare function caseKey(path: string, mode: KeyCase): string;
+export interface BuildResult {
+    body: Record<string, unknown>;
+    warnings: string[];
+}
+/**
+ * Assemble the outgoing body from PayloadField rows + envelope controls.
+ * Returns the body directly (not wrapped in a result object) so callers and
+ * tests can use it as-is; warnings are surfaced via console.warn.
+ */
+export declare function buildPayload(fields: PayloadField[], envelope: PayloadEnvelope, ctx: PayloadContext): Record<string, unknown>;
+/** True when this envelope will emit unsafe JS-number values. */
+export declare function hasNumberEncodingRisk(env: PayloadEnvelope): boolean;
+export declare const DEFAULT_ENVELOPE: PayloadEnvelope;
+/**
+ * Build the exact `POST {save}` body from §9.3. All numbers become strings so
+ * a Decimal never round-trips through a JSON float.
+ */
+export declare function buildSavePayload(ctx: SaveContext): Record<string, unknown>;

package/dist/transport/types.d.ts

@@ -0,0 +1,198 @@
+import type { Region, Settings } from '../settings/settings';
+export type ISODate = string;
+export interface TransportConfig {
+    baseUrl: string;
+    endpoints: {
+        save?: string;
+        update?: string;
+        get?: string;
+        list?: string;
+        delete?: string;
+        upload?: string;
+        uploadUrl?: string;
+        rates?: string;
+        settings?: string;
+    };
+    /** Auth is a callback so tokens are never stored by FinCalc. */
+    getAuth?: () => Promise<Record<string, string>> | Record<string, string>;
+    /** Host-supplied fetch so their interceptors, tracing and proxies apply. */
+    fetch?: typeof fetch;
+    headers?: Record<string, string> | (() => Record<string, string>);
+    credentials?: RequestCredentials;
+    timeoutMs?: number;
+    retry?: RetryConfig;
+    idempotency?: IdempotencyConfig;
+    offlineQueue?: OfflineQueueConfig;
+    upload: UploadConfig;
+    transformRequest?: (body: unknown, ctx: RequestCtx) => unknown;
+    transformResponse?: (raw: unknown, ctx: RequestCtx) => unknown;
+    onRequest?: (ctx: RequestCtx) => void;
+    onResponse?: (ctx: ResponseCtx) => void;
+    onError?: (err: TransportError, ctx: RequestCtx) => void;
+    onProgress?: (p: {
+        loaded: number;
+        total: number;
+        pct: number;
+    }) => void;
+}
+export interface RetryConfig {
+    attempts: number;
+    backoff: 'fixed' | 'exponential';
+    baseDelayMs: number;
+    retryOn: number[];
+    respectRetryAfter: boolean;
+}
+export interface IdempotencyConfig {
+    enabled: boolean;
+    headerName: string;
+    keyFrom: 'inputsHash' | 'uuid';
+}
+export interface OfflineQueueConfig {
+    enabled: boolean;
+    storage: 'memory' | 'localStorage' | 'indexedDB';
+    maxItems: number;
+    flushOn: 'reconnect' | 'manual' | 'interval';
+    intervalMs?: number;
+}
+export interface UploadConfig {
+    strategy: 'multipart' | 'presigned' | 'base64Json';
+    fieldName: string;
+    extraFields?: Record<string, string> | (() => Record<string, string>);
+    maxBytes: number;
+    accept: string[];
+    filenameTemplate: string;
+    chunked?: {
+        enabled: boolean;
+        chunkBytes: number;
+    };
+    checksum?: 'none' | 'sha256';
+    beforeUpload?: (file: Blob, meta: UploadMeta) => Promise<boolean> | boolean;
+}
+export interface UploadMeta {
+    calculationId?: string;
+    calculator: string;
+    kind: string;
+    inputsHash: string;
+    filename?: string;
+    contentType?: string;
+    bytes?: number;
+    checksum?: string;
+}
+export interface Attachment {
+    id: string;
+    kind: string;
+    filename: string;
+    bytes: number;
+    url: string | null;
+}
+export interface RequestCtx {
+    endpoint: string;
+    method: string;
+    url: string;
+    /** Headers with auth already redacted — safe to log. */
+    headers: Record<string, string>;
+    body?: unknown;
+    attempt: number;
+}
+export interface ResponseCtx extends RequestCtx {
+    status: number;
+    ok: boolean;
+    durationMs: number;
+    data: unknown;
+}
+export declare class TransportError extends Error {
+    code: string;
+    status: number;
+    /** The request that failed, auth redacted. */
+    request?: RequestCtx;
+    constructor(message: string, opts?: {
+        code: string;
+        status?: number;
+        request?: RequestCtx;
+    });
+}
+export interface FxRateProvider {
+    getRates(base: string, symbols: string[]): Promise<{
+        timestamp: string;
+        rates: Record<string, string>;
+    }>;
+    getHistorical?(base: string, symbols: string[], date: ISODate): Promise<{
+        timestamp: string;
+        rates: Record<string, string>;
+    }>;
+}
+export type PayloadSource = {
+    kind: 'static';
+    value: string | number | boolean | null;
+} | {
+    kind: 'input';
+    path: string;
+} | {
+    kind: 'output';
+    path: string;
+} | {
+    kind: 'setting';
+    path: string;
+} | {
+    kind: 'context';
+    path: string;
+} | {
+    kind: 'token';
+    name: string;
+} | {
+    kind: 'callback';
+    fn: (ctx: PayloadContext) => unknown;
+};
+export interface PayloadField {
+    key: string;
+    source: PayloadSource;
+    type: 'string' | 'number' | 'boolean' | 'date' | 'json';
+    required: boolean;
+    transform?: 'none' | 'toFixed2' | 'toMinorUnits' | 'upper' | 'lower' | 'trim';
+    omitWhenEmpty: boolean;
+}
+export type KeyCase = 'asIs' | 'camel' | 'snake' | 'kebab';
+export interface PayloadEnvelope {
+    mode: 'flat' | 'wrapped';
+    wrapperKey?: string;
+    keyCase: KeyCase;
+    dateFormat?: string;
+    nullHandling: 'omit' | 'null';
+    numberEncoding: 'string' | 'number';
+    include: {
+        inputs: boolean;
+        outputs: boolean;
+        schedule: boolean;
+        settingsSnapshot: boolean;
+        meta: boolean;
+    };
+}
+/** Everything the payload builder can read from. */
+export interface PayloadContext {
+    inputs: Record<string, unknown>;
+    outputs: Record<string, unknown>;
+    settings: Record<string, unknown>;
+    context: Record<string, unknown>;
+    tokens: Record<string, string>;
+    schedule?: unknown;
+}
+/** Input to the default §9.3 save-payload builder. */
+export interface SaveContext {
+    calculator: string;
+    region: Region;
+    settings: Settings;
+    inputs: Record<string, unknown>;
+    outputs: Record<string, string | number | null>;
+    inputsHash: string;
+    title?: string;
+    tags?: string[];
+    computedAt?: string;
+    formula?: string;
+    assumptions?: string[];
+    warnings?: string[];
+    attachments?: Attachment[];
+    coreVersion?: string;
+    clientId?: string;
+    locale?: string;
+    clientTz?: string;
+}

package/dist/ui/CalculatorPanel.d.ts

@@ -0,0 +1,14 @@
+import { type ComponentType } from 'react';
+import type { CalculatorDef, ResultView, Values } from '../core/kit';
+export declare function CalculatorPanel({ def: defProp, id, seed, customRegistry, onResult, actions, }: {
+    /** A calculator definition, or use `id` to resolve a registered one. */
+    def?: CalculatorDef;
+    /** Registered calculator id, e.g. "loan.emi", "invest.sip". Resolved via the registry. */
+    id?: string;
+    seed?: Values;
+    customRegistry?: Record<string, ComponentType<{
+        def: CalculatorDef;
+    }>>;
+    onResult?: (r: ResultView | null, values: Values) => void;
+    actions?: (r: ResultView | null, values: Values) => React.ReactNode;
+}): import("react").JSX.Element;

package/dist/ui/Chart.d.ts

@@ -0,0 +1,4 @@
+import type { ChartSeries } from '../core/kit';
+export declare function Chart({ chart }: {
+    chart: ChartSeries;
+}): import("react").JSX.Element;

package/dist/ui/CommandPalette.d.ts

@@ -0,0 +1,13 @@
+import type { CalculatorDef } from '../core/kit';
+export interface PaletteAction {
+    id: string;
+    label: string;
+    hint?: string;
+    run: () => void;
+}
+export declare function CommandPalette({ calculators, actions, onPick, onClose, }: {
+    calculators: CalculatorDef[];
+    actions: PaletteAction[];
+    onPick: (id: string) => void;
+    onClose: () => void;
+}): import("react").JSX.Element;

package/dist/ui/CurrencyConverter.d.ts

@@ -0,0 +1 @@
+export declare function CurrencyConverter(): import("react").JSX.Element;

package/dist/ui/Dialog.d.ts

@@ -0,0 +1,8 @@
+import { type ReactNode } from 'react';
+export declare function Dialog({ open, onClose, children, title, size, }: {
+    open: boolean;
+    onClose: () => void;
+    children: ReactNode;
+    title?: string;
+    size?: 'md' | 'lg' | 'xl' | 'full';
+}): import("react").JSX.Element | null;

package/dist/ui/ExportMenu.d.ts

@@ -0,0 +1,4 @@
+import { type ExportPayload } from '../export';
+export declare function ExportMenu({ payload }: {
+    payload: ExportPayload;
+}): import("react").JSX.Element;

package/dist/ui/HistoryPanel.d.ts

@@ -0,0 +1,6 @@
+import type { HistoryItem } from './history';
+export declare function HistoryPanel({ items, onRestore, onClear, }: {
+    items: HistoryItem[];
+    onRestore: (item: HistoryItem) => void;
+    onClear: () => void;
+}): import("react").JSX.Element;

package/dist/ui/IntegrationPanel.d.ts

@@ -0,0 +1,8 @@
+import type { TransportConfig } from '../transport/types';
+export interface IntegrationPanelProps {
+    /** Config the host passed as a prop — any field it set renders read-only. */
+    hostConfig?: Partial<TransportConfig>;
+    /** Host token resolver. When present the token row is read-only, never an input. */
+    getToken?: () => string | Promise<string>;
+}
+export declare function IntegrationPanel({ hostConfig, getToken }?: IntegrationPanelProps): import("react").JSX.Element;

package/dist/ui/Launcher.d.ts

@@ -0,0 +1,34 @@
+import { type CSSProperties, type ReactNode } from 'react';
+/** Handed to a custom `trigger` / function-child so you can open the dialog from any UI. */
+export interface LauncherApi {
+    open: boolean;
+    openDialog: () => void;
+    close: () => void;
+    toggle: () => void;
+}
+export interface LauncherProps {
+    /** 'fab' floating button · 'inline' in-flow button · 'headless' you render the trigger. */
+    variant?: 'fab' | 'inline' | 'headless';
+    position?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
+    hotkey?: string | null;
+    defaultOpen?: boolean;
+    /** Controlled open state (pair with `onOpenChange`). */
+    open?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    label?: string;
+    /** Any icon/content for the built-in button — an emoji, an <svg>, an <img>, a component. */
+    icon?: ReactNode;
+    /** Passthrough styling for the built-in button. */
+    className?: string;
+    style?: CSSProperties;
+    /**
+     * Render your OWN trigger (any button/element/UI). Receives `{ open, toggle, openDialog, close }`.
+     * When provided — or with `variant="headless"` and a function child — the built-in button is not rendered.
+     */
+    trigger?: (api: LauncherApi) => ReactNode;
+    children?: ReactNode | ((api: LauncherApi) => ReactNode);
+    /** Dialog sizing / title. */
+    dialogSize?: 'md' | 'lg' | 'xl' | 'full';
+    dialogTitle?: string;
+}
+export declare function Launcher({ variant, position, hotkey, defaultOpen, open: openProp, onOpenChange, label, icon, className, style, trigger, children, dialogSize, dialogTitle, }: LauncherProps): import("react").JSX.Element;

package/dist/ui/LoanEmiPanel.d.ts

@@ -0,0 +1 @@
+export declare function LoanEmiPanel(): import("react").JSX.Element;

package/dist/ui/ResultCard.d.ts

@@ -0,0 +1,4 @@
+import type { ResultView } from '../core/kit';
+export declare function ResultCard({ view }: {
+    view: ResultView;
+}): import("react").JSX.Element;

package/dist/ui/SaveButton.d.ts

@@ -0,0 +1,4 @@
+import { type HistoryItem } from './history';
+export declare function SaveButton({ item }: {
+    item: Omit<HistoryItem, 'at'>;
+}): import("react").JSX.Element;

package/dist/ui/ScheduleTable.d.ts

@@ -0,0 +1,4 @@
+import type { ScheduleView } from '../core/kit';
+export declare function ScheduleTable({ schedule }: {
+    schedule: ScheduleView;
+}): import("react").JSX.Element;

package/dist/ui/SciCalculator.d.ts

@@ -0,0 +1,4 @@
+import type { CalculatorDef } from '../core/kit';
+export declare function SciCalculator({ def }: {
+    def: CalculatorDef;
+}): import("react").JSX.Element;

package/dist/ui/SettingsPanel.d.ts

@@ -0,0 +1 @@
+export declare function SettingsPanel(): import("react").JSX.Element;

package/dist/ui/Shell.d.ts

@@ -0,0 +1,5 @@
+import type { CalculatorDef } from '../core/kit';
+export declare function Shell({ onClose }: {
+    onClose?: () => void;
+}): import("react").JSX.Element;
+export type { CalculatorDef };

package/dist/ui/fields.d.ts

@@ -0,0 +1,9 @@
+import type { FieldSchema, Values, FieldValue } from '../core/kit';
+import type { Region } from '../settings/settings';
+export declare function labelFor(f: FieldSchema, region: Region): string;
+export declare function Field({ f, value, onChange, values, }: {
+    f: FieldSchema;
+    value: FieldValue | undefined;
+    onChange: (v: FieldValue) => void;
+    values: Values;
+}): import("react").JSX.Element | null;

package/dist/ui/history.d.ts

@@ -0,0 +1,15 @@
+import type { Values } from '../core/kit';
+export interface HistoryItem {
+    id: string;
+    title: string;
+    primary: string;
+    values: Values;
+    at: number;
+}
+export declare function saveHistory(item: Omit<HistoryItem, 'at'>): void;
+export declare function clearHistory(): void;
+export declare function useHistory(): {
+    items: HistoryItem[];
+    save: (item: Omit<HistoryItem, "at">) => void;
+    clear: () => void;
+};

package/dist/ui/icons.d.ts

@@ -0,0 +1,8 @@
+type IconProps = {
+    size?: number;
+};
+export declare function GearIcon({ size }: IconProps): import("react").JSX.Element;
+export declare function SunIcon({ size }: IconProps): import("react").JSX.Element;
+export declare function MoonIcon({ size }: IconProps): import("react").JSX.Element;
+export declare function HistoryIcon({ size }: IconProps): import("react").JSX.Element;
+export {};

package/dist/ui/overlayStack.d.ts

@@ -0,0 +1,3 @@
+export declare const pushOverlay: () => void;
+export declare const popOverlay: () => void;
+export declare const hasOverlay: () => boolean;

package/dist/ui/themePresets.d.ts

@@ -0,0 +1,19 @@
+export type AccentPreset = 'default' | 'cyan' | 'purple' | 'blue' | 'orange' | 'gray';
+export interface Accent {
+    id: AccentPreset;
+    label: string;
+    main: string;
+    light: string;
+    dark: string;
+    ink: string;
+}
+export declare const ACCENTS: Accent[];
+export declare const accentByMain: (main: string) => Accent | undefined;
+export declare const FONT_FALLBACK = "-apple-system, 'Segoe UI', system-ui, sans-serif";
+export interface FontChoice {
+    id: string;
+    label: string;
+    stack: string;
+}
+export declare const FONTS: FontChoice[];
+export declare const fontStack: (id: string) => string;

package/package.json

@@ -0,0 +1,94 @@
+{
+  "name": "calcsuite-react",
+  "version": "1.0.0",
+  "description": "Decimal-exact, offline-first financial calculator library for React — India (₹) & US ($). ~55 calculators, scientific calculator, live FX, export, launcher/dialog. The financial-calculator module of AceCBM (Ace Cloud Business Management).",
+  "keywords": [
+    "finance",
+    "calculator",
+    "emi",
+    "loan",
+    "sip",
+    "tax",
+    "react",
+    "decimal",
+    "india",
+    "us",
+    "acecbm"
+  ],
+  "license": "MIT",
+  "author": "AceCBM (Ace Cloud Business Management)",
+  "homepage": "https://github.com/ashish13377/calcsuite#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ashish13377/calcsuite.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ashish13377/calcsuite/issues"
+  },
+  "type": "module",
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "main": "./dist/calcsuite.js",
+  "module": "./dist/calcsuite.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/calcsuite.js"
+    },
+    "./theme.css": "./src/theme.css"
+  },
+  "files": [
+    "dist",
+    "src/theme.css",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "dev": "vite",
+    "demo:build": "tsc -b && vite build",
+    "build": "vite build -c vite.lib.config.ts && npm run build:types",
+    "build:types": "tsc -p tsconfig.lib.json",
+    "preview": "vite preview",
+    "test": "vitest run",
+    "typecheck": "tsc -b",
+    "prepack": "npm run build",
+    "prepublishOnly": "npm run test"
+  },
+  "peerDependencies": {
+    "react": "^18.3.1 || ^19.0.0",
+    "react-dom": "^18.3.1 || ^19.0.0"
+  },
+  "peerDependenciesMeta": {
+    "jspdf": {
+      "optional": true
+    },
+    "xlsx": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "decimal.js": "^10.4.3"
+  },
+  "devDependencies": {
+    "@types/react": "^18.3.12",
+    "@types/react-dom": "^18.3.1",
+    "@vitejs/plugin-react": "^4.3.4",
+    "happy-dom": "^20.13.2",
+    "jspdf": "^4.2.1",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "typescript": "^5.6.3",
+    "vite": "^5.4.11",
+    "vitest": "^2.1.8",
+    "xlsx": "^0.18.5"
+  }
+}