@npm-zenwork/tax-remittance-ui 0.7.0 → 0.9.0

package/dist/components/tax-forms/states/west-virginia/WVWithholding.shared.d.ts

@@ -0,0 +1,170 @@
+import { AmountParts } from '../../../../lib/fieldRules';
+import { StateFormSubmitResponse } from '../../../../api/stateForms';
+import { EntityDetailsResponse } from '../../../../types/entity';
+/**
+ * Ids the backend issues once a return exists, sent back on submit so it
+ * updates that record. Absent (`null`) for a new return. Never shown. The
+ * same for all four forms.
+ */
+export interface WVBoundData {
+    payerDetailId?: number | null;
+    formRecordId?: number | null;
+    statePayrollFormId?: number | null;
+}
+/** The props every WV form takes — the same shape every other state form's component takes. */
+export interface WVFormProps<V> {
+    data: WVBoundData;
+    /** Starting entries — anything omitted starts blank. */
+    initialValues?: Partial<V>;
+    /** Fires on every change with the complete set of entries. */
+    onValuesChange?: (values: V) => void;
+    /** Leaves the form. Omit to hide the Back button. */
+    onBack?: () => void;
+    /** Fires after a successful submit, with the API's response. */
+    onSubmitted?: (response: StateFormSubmitResponse) => void;
+}
+export declare function buildIdsPayload(data: WVBoundData): {
+    payerDetailId: number | null;
+    formRecordId: number | null;
+    statePayrollFormId: number | null;
+};
+/** `(path, ok, message)` — how every WV schema's `superRefine` reports an issue. */
+export type Check = (path: (string | number)[], ok: boolean, message: string) => void;
+/** WV withholding account number: 8 digits (STATE_PAYMENT_VALIDATION_GUIDE.md). */
+export declare const WV_ACCOUNT_NUMBER_PATTERN: RegExp;
+/** 1099-only filers may use their FEIN instead. */
+export declare const WV_FEIN_PATTERN: RegExp;
+export declare const WV_ACCOUNT_NUMBER_MAX_LENGTH = 10;
+export declare function checkAccountNumber(value: string, check: Check, { allowFein }?: {
+    allowFein?: boolean;
+}): void;
+export interface WVBusinessValues {
+    /** The chosen Dashboard entity. `null` until one is chosen. */
+    payerId: number | null;
+    name: string;
+    address: string;
+    city: string;
+    state: string;
+    zipCode: string;
+}
+export declare const EMPTY_WV_BUSINESS_VALUES: WVBusinessValues;
+/** Every field an entity fills — cleared from the error list as soon as one is chosen. */
+export declare const WV_ENTITY_FIELDS: string[];
+/**
+ * The business block + signature line's share of the backend's canonical auto-fill JSON
+ * (`TaxFormService.BuildAutoFillJson`) — every WV withholding form's own `.autofill.ts` calls
+ * these for its common fields, then adds whatever its own worksheet needs.
+ */
+export interface WVWithholdingAutoFillJson {
+    entityId?: number;
+    payer?: {
+        firstName?: string;
+        lastName?: string;
+        tradeName?: string | null;
+        accountType?: string;
+        address1?: string;
+        address2?: string | null;
+        city?: string;
+        state?: string;
+        zipCode?: string;
+        phone?: string;
+        email?: string;
+    };
+    payment?: {
+        taxYear?: string;
+        taxPeriod?: string | null;
+        paymentDate?: string | null;
+        stateAccountId?: string | null;
+        amount?: number;
+    };
+    authorization?: {
+        signerName?: string | null;
+        title?: string | null;
+        signature?: string | null;
+        signatureDate?: string | null;
+    };
+}
+export declare function wvBusinessFieldsFromAutoFill(autoFill: WVWithholdingAutoFillJson): WVBusinessValues;
+export declare function wvSignerFieldsFromAutoFill(autoFill: WVWithholdingAutoFillJson): Partial<WVSignerValues>;
+export declare function wvBusinessFieldsFromEntity(entity: EntityDetailsResponse): WVBusinessValues;
+/** These come only from the entity, so a gap means the entity needs editing — not this return. */
+export declare function checkBusiness(values: WVBusinessValues, check: Check): void;
+export declare function buildBusinessPayload(values: WVBusinessValues): {
+    payerId: number;
+    business: {
+        name: string;
+        address: string;
+        city: string;
+        state: string;
+        zipCode: string;
+    };
+};
+export interface WVStoppedWagesValues {
+    hasStoppedWages: boolean;
+    /** MM/DD/YYYY — the final date wages were paid. */
+    finalWagesDate: string;
+}
+export declare const EMPTY_WV_STOPPED_WAGES_VALUES: WVStoppedWagesValues;
+export declare function checkStoppedWages(values: WVStoppedWagesValues, check: Check): void;
+export interface WVSignerValues {
+    signature: string;
+    signerName: string;
+    title: string;
+    signatureDate: string;
+    contactPerson: string;
+    contactPhone: string;
+    /** Printed on IT-101A and IT-103 only. */
+    email: string;
+    preparerSignature: string;
+    preparerAddress: string;
+    preparerDate: string;
+}
+export declare const EMPTY_WV_SIGNER_VALUES: WVSignerValues;
+export declare const SIGNER_MAX_LENGTH = 60;
+/**
+ * "An unsigned return is not a valid return!" — signature, name, title, date
+ * and a telephone number are required. The preparer line is all-or-nothing:
+ * blank is fine, but once any of it is filled the signature and date are
+ * needed.
+ */
+export declare function checkSigner(values: WVSignerValues, check: Check, { withEmail }: {
+    withEmail: boolean;
+}): void;
+export declare function buildSignerPayload(values: WVSignerValues, { withEmail }: {
+    withEmail: boolean;
+}): {
+    declaration: {
+        signature: string;
+        name: string;
+        title: string;
+        signatureDate: string;
+        contactPerson: string;
+        contactPhone: string;
+        email: string | null;
+    };
+    preparer: {
+        signature: string;
+        address: string;
+        date: string;
+    } | null;
+};
+export declare const COUNT_MAX_LENGTH = 7;
+/** "If none, enter zero" — WV's amount lines are required, and 0.00 is a valid entry. */
+export declare function checkAmount(path: (string | number)[], amount: AmountParts, label: string, check: Check, { required }?: {
+    required?: boolean | undefined;
+}): void;
+/** A whole-number count box ("Number of employees…"). Blank is rejected; 0 is fine. */
+export declare function checkCount(key: string, value: string, label: string, check: Check, { required }?: {
+    required?: boolean | undefined;
+}): void;
+export declare const MIN_TAX_YEAR = 2000;
+export declare function checkTaxYear(key: string, value: string, check: Check, label?: string): void;
+/** `"monthLiability.1"` -> message, the first issue per field. Amount issues point at `.dollars`, which is dropped. */
+export declare function toFieldErrors(issues: {
+    path: PropertyKey[];
+    message: string;
+}[]): Record<string, string>;
+export declare function formatDollars(cents: number): string;
+/** `MM/DD/YYYY`. */
+export declare function formatDate(date: Date): string;
+export declare const dollars: (cents: number) => number;

package/dist/components/tax-forms/states/west-virginia/WVWithholdingParts.d.ts

@@ -0,0 +1,129 @@
+import { ReactNode } from 'react';
+import { FormMode } from '../stateFormKit';
+import { EntityDetailsResponse } from '../../../../types/entity';
+import { WVSignerValues } from './WVWithholding.shared';
+export interface InputProps {
+    value: string;
+    placeholder?: string;
+    onChange?: (value: string) => void;
+    onBlur?: () => void;
+    error?: string;
+    maxLength?: number;
+    inputMode?: 'numeric' | 'text' | 'email' | 'tel';
+}
+export interface DateProps {
+    value: string;
+    onChange?: (value: string) => void;
+    onBlur?: () => void;
+    error?: string;
+}
+export declare function FieldError({ message }: {
+    message?: string;
+}): import("react").JSX.Element | null;
+/** `STATE OF WEST VIRGINIA / State Tax Department …` over `WV/IT-101Q  WEST VIRGINIA EMPLOYER'S …`. */
+export declare function FormMasthead({ formNumber, title, subtitle }: {
+    formNumber: string;
+    title: string;
+    subtitle?: ReactNode;
+}): import("react").JSX.Element;
+/** A typed-in box — live input in edit mode, plain text in preview (or when the value comes from the entity). */
+export declare function TextBox({ ariaLabel, value, placeholder, onChange, onBlur, error, maxLength, inputMode }: InputProps & {
+    ariaLabel: string;
+}): import("react").JSX.Element;
+/** Caption over a `TextBox` — the header cells ("Account #:", "Tax Year Ending:"). */
+export declare function LabeledBox({ label, className, ...props }: InputProps & {
+    label: string;
+    className?: string;
+}): import("react").JSX.Element;
+/** A date entry — the calendar picker while editing, plain text otherwise. */
+export declare function DateBox({ ariaLabel, value, onChange, onBlur, error }: DateProps & {
+    ariaLabel: string;
+}): import("react").JSX.Element;
+/** A read-only header value — "Quarter Ending", "Due Date" — derived from the period. */
+export declare function HeaderValue({ label, value, placeholder }: {
+    label: string;
+    value: string | null;
+    placeholder: string;
+}): import("react").JSX.Element;
+export declare function CheckBox({ checked, onToggle, label }: {
+    checked: boolean;
+    onToggle?: () => void;
+    label: ReactNode;
+}): import("react").JSX.Element;
+/** The grey bar each part starts with — "Part 1: Complete Lines 1-10". */
+export declare function PartHeading({ children }: {
+    children: ReactNode;
+}): import("react").JSX.Element;
+/** The ruled box the parts sit in. */
+export declare function FormBox({ children }: {
+    children: ReactNode;
+}): import("react").JSX.Element;
+/**
+ * `2. Wages, tips and other compensation for the quarter │ [ amount ]` — one
+ * ruled row, the entry in the right-hand column as the return prints it. On
+ * a phone the entry drops below the label.
+ */
+export declare function LineRow({ number, label, hint, children }: {
+    number?: number | string;
+    label: ReactNode;
+    hint?: ReactNode;
+    children?: ReactNode;
+}): import("react").JSX.Element;
+/**
+ * Name / Address / City · State · Zip — filled from the "Filing for" entity
+ * and read-only here (the entity is edited from its own screen, never from a
+ * return), with the Account # the filer types beside it.
+ */
+export declare function BusinessBlock({ payerId, onSelectEntity, entityError, fields, accountNumber, accountNumberPlaceholder, }: {
+    payerId: number | null;
+    onSelectEntity: (entity: EntityDetailsResponse) => void;
+    entityError?: string;
+    fields: Record<'name' | 'address' | 'city' | 'state' | 'zipCode', {
+        value: string;
+        error?: string;
+    }>;
+    accountNumber: InputProps;
+    accountNumberPlaceholder?: string;
+}): import("react").JSX.Element;
+/** Part 2 — "If your business has stopped paying wages, check here and enter final date you paid wages". */
+export declare function StoppedWagesRow({ checked, onToggle, date }: {
+    checked: boolean;
+    onToggle?: () => void;
+    date: DateProps;
+}): import("react").JSX.Element;
+/**
+ * Part 3 — the declaration, then the three rows of signature lines with their
+ * captions beneath. `bind` is the form's own field binder (the hook's `text`),
+ * so each entry saves, validates and locks like every other field.
+ */
+export declare function SignBlock({ bind, withEmail, }: {
+    bind: (key: keyof WVSignerValues, format?: (value: string) => string) => InputProps;
+    /** IT-101A and IT-103 print an E-mail address line; IT-101Q doesn't. */
+    withEmail: boolean;
+}): import("react").JSX.Element;
+/** The boxed "MAIL TO" panel at the foot of the page. */
+export declare function MailToBox({ poBox, note }: {
+    poBox?: string;
+    note?: ReactNode;
+}): import("react").JSX.Element;
+/** The summary box every WV form closes its sheet with — totals and the due date. */
+export declare function SummaryBox({ children }: {
+    children: ReactNode;
+}): import("react").JSX.Element;
+/**
+ * The page around a return: its heading, the white sheet, the "Fix the
+ * highlighted fields" line and the Back / Edit / Submit bar.
+ */
+export declare function WVFormFrame({ heading, form, children, }: {
+    heading: string;
+    form: {
+        mode: FormMode;
+        hasErrors: boolean;
+        isSubmitting: boolean;
+        startEditing: () => void;
+        cancelEditing: () => void;
+        submitForm: () => void;
+        onBack?: () => void;
+    };
+    children: ReactNode;
+}): import("react").JSX.Element;

package/dist/components/tax-forms/states/west-virginia/useWVWithholdingForm.d.ts

@@ -0,0 +1,62 @@
+import { z } from 'zod';
+import { StateFormSubmitResponse } from '../../../../api/stateForms';
+import { AmountParts, FormMode } from '../stateFormKit';
+import { EntityDetailsResponse } from '../../../../types/entity';
+import { WVBusinessValues } from './WVWithholding.shared';
+/** The keys of `V` whose values are a `T` — e.g. every text box, every amount line. */
+type KeysOfType<V, T> = {
+    [K in keyof V]: V[K] extends T ? K : never;
+}[keyof V] & string;
+interface FieldOptions {
+    /** `false` locks the field even while editing — e.g. a date whose check box is unticked. */
+    enabled?: boolean;
+    /** Other fields whose rules depend on this one, re-checked when it's left. */
+    alsoCheck?: string[];
+}
+interface Options<V extends WVBusinessValues, P extends {
+    formCode: string;
+    state: string;
+}> {
+    formLabel: string;
+    schema: z.ZodType;
+    initialValues: V;
+    buildPayload: (values: V) => P;
+    /** Clears whatever the new entries switch off (e.g. a date whose checkbox was unticked) before they're saved. */
+    normalize?: (values: V) => V;
+    onValuesChange?: (values: V) => void;
+    onSubmitted?: (response: StateFormSubmitResponse) => void;
+}
+export declare function useWVWithholdingForm<V extends WVBusinessValues, P extends {
+    formCode: string;
+    state: string;
+}>({ formLabel, schema, initialValues, buildPayload, normalize, onValuesChange, onSubmitted, }: Options<V, P>): {
+    values: V;
+    mode: FormMode;
+    isEditing: boolean;
+    fieldErrors: Record<string, string>;
+    hasErrors: boolean;
+    commit: (raw: V) => void;
+    validateOnBlur: (...keys: string[]) => () => void;
+    text: (key: KeysOfType<V, string>, { format, enabled, alsoCheck }?: FieldOptions & {
+        format?: (value: string) => string;
+    }) => {
+        value: string;
+        onChange: ((value: string) => void) | undefined;
+        onBlur: () => void;
+        error: string;
+    };
+    amount: (key: KeysOfType<V, AmountParts>, label: string, { enabled, alsoCheck }?: FieldOptions) => {
+        label: string;
+        amount: AmountParts;
+        onChange: ((next: AmountParts) => void) | undefined;
+        onBlur: () => void;
+        error: string;
+    };
+    toggle: (key: KeysOfType<V, boolean>, enabled?: boolean) => (() => void) | undefined;
+    applyEntity: (entity: EntityDetailsResponse) => void;
+    startEditing: () => void;
+    cancelEditing: () => void;
+    submitForm: () => void;
+    isSubmitting: boolean;
+};
+export {};

package/dist/components/tax-forms/taxFormReason.d.ts

@@ -0,0 +1,9 @@
+/**
+ * `StatePayrollForm.reason` comes back as the catalog's display label ("Withholding Tax"), not its
+ * code ("WITHHOLDING_TAX") — `StatePaymentDetails.ReasonForPayment` is persisted as the label (see
+ * `StatePaymentService`'s `reasonLabel`). Normalizing the same way `StatePaymentCatalog.
+ * NormalizeReasonCode` does lets either form match.
+ */
+export declare function normalizeReasonCode(reason: string): string;
+/** Estimated/Income Tax reasons — the ones a payment-status-derived badge applies to (see `TaxFormStatusBadge`). */
+export declare function isReadOnlyFormReason(reason: string): boolean;

package/dist/components/tax-forms/taxFormRegistry.d.ts

@@ -0,0 +1,45 @@
+import { ReactNode } from 'react';
+import { StateFormSubmitResponse } from '../../api/stateForms';
+export interface UsState {
+    code: string;
+    name: string;
+}
+/** The 50 states plus DC, alphabetical by name. */
+export declare const US_STATES: UsState[];
+/**
+ * `individual` — a person's own income tax (estimated payments).
+ * `business` — a business's own income tax (corporate estimated payments).
+ * `withholding` — an employer's returns/payments of tax withheld from employees.
+ */
+export type TaxFormCategory = 'individual' | 'business' | 'withholding';
+export interface TaxFormListing {
+    /** URL-safe id, used in `?form=`. */
+    id: string;
+    stateCode: string;
+    category: TaxFormCategory;
+    formNumber: string;
+    /**
+     * The exact code `StatePayrollForm.formCode` resolves to (`StatePaymentFormReferenceCatalog`'s
+     * seeded `FormName`), when it differs from `formNumber`'s display spelling — e.g. a voucher
+     * covering multiple return types ("120/165ES") that the catalog only ever resolves to one of
+     * them ("120ES"). `TaxFormRecordView` matches on this before falling back to `formNumber`.
+     */
+    formCode?: string;
+    title: string;
+    description: string;
+    /** How often it's filed, shown as a pill. */
+    frequency: string;
+    /** Catalog browsing (preview-bound) — see TaxFormsCatalogBrowser in TaxFormsPage.tsx. */
+    render: (onBack: () => void) => ReactNode;
+    /**
+     * A real, created tax form record, bound to its actual data — see `TaxFormRecordView.tsx`.
+     * Optional while each form gets its own auto-fill mapper (see `AL40ESForm.autofill.ts`);
+     * a listing without one falls back to the generic `TaxFormDetailPanel`.
+     */
+    renderBound?: (ids: {
+        payerDetailId: number | null;
+        formRecordId: number | null;
+        statePayrollFormId: number | null;
+    }, autoFillJson: unknown, onBack: () => void, onSubmitted: (response: StateFormSubmitResponse) => void) => ReactNode;
+}
+export declare const TAX_FORM_LISTINGS: TaxFormListing[];

package/dist/components/ui/CalendarPicker.d.ts

@@ -0,0 +1,17 @@
+export interface CalendarPickerProps {
+    /** The field's current text, in whatever format the caller's `parseValue`/`formatValue` use. */
+    value: string;
+    onChange: (value: string) => void;
+    onBlur?: () => void;
+    /** Turns the display text into a `Date`; return `null`/`undefined` while it isn't a complete valid date yet. */
+    parseValue: (value: string) => Date | null | undefined;
+    /** Turns a picked calendar day back into the display text. */
+    formatValue: (date: Date) => string;
+    placeholder?: string;
+    disabled?: boolean;
+    hasError?: boolean;
+    /** Grays out and disallows picking a date the caller doesn't consider valid (e.g. weekends, an out-of-range date). */
+    isDateSelectable?: (date: Date) => boolean;
+    monthLabel?: (year: number, monthIndex: number) => string;
+}
+export declare function CalendarPicker({ value, onChange, onBlur, parseValue, formatValue, placeholder, disabled, hasError, isDateSelectable, monthLabel, }: CalendarPickerProps): import("react").JSX.Element;