@gusto/embedded-react-sdk 0.55.5 → 0.55.7

package/dist/src/components/Payroll/helpers.d.ts

@@ -0,0 +1,223 @@
+import { Employee } from '@gusto/embedded-api/models/components/employee';
+import { FixedCompensations, Reimbursements as Reimbursement, PayrollEmployeeCompensationsType } from '@gusto/embedded-api/models/components/payrollemployeecompensationstype';
+import { PayrollUpdateReimbursements } from '@gusto/embedded-api/models/components/payrollupdate';
+import { PayrollFixedCompensationTypesType } from '@gusto/embedded-api/models/components/payrollfixedcompensationtypestype';
+import { TFunction } from 'i18next';
+import { PayScheduleShow as PayScheduleObject } from '@gusto/embedded-api/models/components/payscheduleshow';
+import { Payroll } from '@gusto/embedded-api/models/components/payrollshow';
+import { PayrollType } from './PayrollList/types';
+import { PayrollCategory } from './payrollTypes';
+/**
+ * The compensation fields the payroll math helpers operate on.
+ *
+ * @remarks
+ * These helpers run over both compensation representations the API returns: the
+ * prepared (base) shape used when editing a payroll and the calculated (show)
+ * shape rendered after calculation. The two are interchangeable for every field
+ * read here and differ only on `deductions`, which no helper touches. Omitting
+ * `deductions` lets a single input type accept either shape without a cast.
+ *
+ * @internal
+ */
+type EmployeeCompensationInput = Omit<PayrollEmployeeCompensationsType, 'deductions'>;
+/**
+ * Formats an employee's primary-job pay rate into a localized display string.
+ *
+ * @remarks
+ * Returns `null` when the employee has no jobs, the primary job has no compensations, or the rate is missing
+ * or zero.
+ *
+ * @param args - The employee, translation function, and locale to format against.
+ * @returns The formatted pay-rate string, or `null` when no usable rate is available.
+ * @internal
+ */
+export declare const formatEmployeePayRate: ({ employee, t, locale, }: {
+    employee?: Employee;
+    t: TFunction;
+    locale?: string;
+}) => string | null;
+/**
+ * Returns a memoized formatter that produces a localized pay-rate string from an employee's primary job.
+ *
+ * @returns A callback that takes an `Employee` and returns the formatted pay-rate string, or `null` when the
+ *   employee has no usable primary-job compensation.
+ * @internal
+ */
+export declare const useFormatEmployeePayRate: () => (employee?: Employee) => string | null;
+/**
+ * Sums hourly-compensation rows named `'regular hours'`.
+ *
+ * @param compensation - The employee compensation entry.
+ * @returns The total regular hours worked, or `0` when none are recorded.
+ * @internal
+ */
+export declare const getRegularHours: (compensation: EmployeeCompensationInput) => number;
+/**
+ * Sums the overtime hours (multiplier greater than `1`) from an employee compensation.
+ *
+ * @param compensation - The employee compensation entry.
+ * @returns The total overtime hours, or `0` when the compensation is excluded or has none.
+ * @internal
+ */
+export declare function getOvertimeHours(compensation: EmployeeCompensationInput): number;
+/**
+ * Sums the paid-time-off hours from an employee compensation.
+ *
+ * @param compensation - The employee compensation entry.
+ * @returns The total PTO hours, or `0` when none are recorded.
+ * @internal
+ */
+export declare const getTotalPtoHours: (compensation: EmployeeCompensationInput) => number;
+/**
+ * Sums fixed-compensation amounts excluding reimbursements and minimum-wage adjustments.
+ *
+ * @param compensation - The employee compensation entry.
+ * @returns The total additional earnings amount, or `0` when none qualify.
+ * @internal
+ */
+export declare const getAdditionalEarnings: (compensation: EmployeeCompensationInput) => number;
+/**
+ * Returns the total reimbursement amount for an employee compensation.
+ *
+ * @remarks
+ * Prefers the explicit `reimbursements` array when present; falls back to a fixed-compensation row named
+ * `'Reimbursement'` for older payroll shapes.
+ *
+ * @param compensation - The employee compensation entry.
+ * @returns The summed reimbursement amount, or `0` when none.
+ * @internal
+ */
+export declare const getReimbursements: (compensation: EmployeeCompensationInput) => number;
+/**
+ * Normalizes a reimbursement list for submission to the v2025-11-15 API.
+ *
+ * @remarks
+ * - Drops named rows that would be no-ops on the server (zero amount with no existing uuid).
+ * - Drops named rows with an existing uuid and zero amount — these are removals, and the backend's
+ *   `replace_itemized_reimbursements` deletes any persisted reimbursement whose uuid is omitted from the
+ *   incoming list.
+ * - Consolidates multiple unnamed (description-less) rows into a single unnamed entry, since the API rejects
+ *   more than one unnamed reimbursement per employee.
+ * - When the consolidated unnamed total is zero, sends no unnamed entry at all. The backend's full-replace
+ *   semantics then delete any persisted unnamed entry (unnamed entries never have uuids, so this is the only
+ *   way to remove them).
+ * - Maps the read shape (`description: string | null`) to the write shape (`description?: string`), omitting
+ *   the field when there is no description.
+ *
+ * @param reimbursements - The reimbursements pulled from the prepared payroll.
+ * @returns The normalized reimbursements ready to send on a payroll update.
+ * @internal
+ */
+export declare const cleanupReimbursements: (reimbursements: Reimbursement[]) => PayrollUpdateReimbursements[];
+/**
+ * Formats an hours value for display, rounding to two decimals and ensuring whole numbers render with `.0`.
+ *
+ * @param hours - The hours value to format.
+ * @returns A string like `'40.0'` or `'37.25'`.
+ * @internal
+ */
+export declare const formatHoursDisplay: (hours: number) => string;
+/**
+ * Whether an FLSA status is eligible for regular-rate-of-pay overtime.
+ *
+ * @remarks
+ * Only the nonexempt family (`Nonexempt`, `Salaried Nonexempt`,
+ * `Commission Only Nonexempt`) earns overtime premiums, so only those statuses
+ * warrant per-workweek breakdowns. `Exempt`, `Owner`, and
+ * `Commission Only Exempt` are never overtime-eligible. An unknown status
+ * returns `false` (treat as flat, never show meaningless workweek columns).
+ *
+ * @param flsaStatus - The employee's FLSA status, e.g. from `hourlyCompensations[].flsaStatus`.
+ * @returns `true` only for the three nonexempt statuses.
+ * @internal
+ */
+export declare const isOvertimeEligibleFlsaStatus: (flsaStatus: string | undefined) => boolean;
+/**
+ * Calculates an employee's gross pay for a payroll, combining regular and overtime pay,
+ * additional earnings, PTO pay, and any minimum-wage adjustment.
+ *
+ * @remarks
+ * Returns `0` when the compensation is excluded or the employee has no primary job compensation effective
+ * on the given date. The result is rounded to two decimal places.
+ *
+ * @param compensation - The employee compensation entry from the payroll.
+ * @param employee - The employee record (used to look up jobs and effective compensations).
+ * @param compensationEffectiveDateString - ISO date used to resolve the effective compensation; defaults to now.
+ * @param paySchedule - The pay schedule, used to derive expected hours per pay period.
+ * @param payrollCategory - The payroll category; off-cycle categories change how PTO hours are summed.
+ * @returns The gross pay amount.
+ * @internal
+ */
+export declare const calculateGrossPay: (compensation: EmployeeCompensationInput, employee: Employee, compensationEffectiveDateString?: string, paySchedule?: PayScheduleObject, payrollCategory?: PayrollCategory) => number;
+/**
+ * Returns the high-level payroll type — `'External'`, `'Off-Cycle'`, or `'Regular'`.
+ *
+ * @param payroll - The payroll whose type to classify.
+ * @returns The payroll type string.
+ * @internal
+ */
+export declare const getPayrollType: (payroll: {
+    external?: boolean;
+    offCycle?: boolean;
+}) => PayrollType;
+/**
+ * Returns whether an off-cycle reason indicates a dismissal payroll.
+ *
+ * @param offCycleReason - The payroll's off-cycle reason string.
+ * @returns `true` when the reason matches the dismissed-employee reason.
+ * @internal
+ */
+export declare const isDismissalPayroll: (offCycleReason?: string | null) => boolean;
+/**
+ * Returns a human-readable label describing the payroll type, mapping off-cycle reasons to display strings.
+ *
+ * @param payroll - The payroll whose type to describe.
+ * @returns `'External'`, `'Regular'`, `'Off-Cycle'`, or a label derived from the off-cycle reason
+ *   (e.g. `'Bonus'`, `'Dismissal'`).
+ * @internal
+ */
+export declare const getPayrollTypeLabel: (payroll: {
+    external?: boolean;
+    offCycle?: boolean;
+    offCycleReason?: string | null;
+}) => string;
+/**
+ * Merges existing fixed compensations with placeholder entries for any compensation types the employee
+ * doesn't yet have, then filters out excluded types and sorts the result alphabetically.
+ *
+ * @remarks
+ * Owners (FLSA status `Owner`) never receive placeholder entries. Placeholders are added with `amount: '0.00'`
+ * and the supplied `primaryJobUuid`.
+ *
+ * @param options - Inputs controlling which placeholder entries to add and which types to exclude.
+ * @returns The merged, filtered, and sorted list of fixed compensations.
+ * @internal
+ */
+export declare const getAdditionalEarningsCompensations: ({ flsaStatus, existingFixedCompensations, primaryJobUuid, fixedCompensationTypes, excludedTypes, }: {
+    flsaStatus: string | undefined;
+    existingFixedCompensations?: FixedCompensations[];
+    primaryJobUuid?: string;
+    fixedCompensationTypes?: PayrollFixedCompensationTypesType[];
+    excludedTypes?: string[];
+}) => FixedCompensations[];
+/**
+ * Sums gross pay, employer taxes, reimbursements, and benefits from a payroll's totals.
+ *
+ * @param payrollData - The payroll whose totals to sum.
+ * @returns The total payroll cost, or `0` when `payrollData.totals` is missing.
+ * @internal
+ */
+export declare const calculateTotalPayroll: (payrollData: Payroll) => number;
+/**
+ * Determines whether a payroll can be cancelled based on its status, deadline, and the 4:00 PM PT cutoff.
+ *
+ * @remarks
+ * Returns `true` only when the payroll has been processed, `payrollStatusMeta.cancellable` is not explicitly `false`,
+ * the payroll has a `payrollDeadline`, and the current time is before 4:00 PM Pacific Time on that deadline date.
+ *
+ * @param payroll - The payroll to evaluate.
+ * @returns `true` if the payroll is still cancellable, `false` otherwise.
+ * @internal
+ */
+export declare const canCancelPayroll: (payroll: Payroll) => boolean;
+export {};

package/dist/src/contexts/ApiProvider/apiVersion.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Single source of truth for the pinned Gusto Embedded API version.
+ *
+ * @remarks
+ * Bumping the API version is a two-line change: update {@link API_VERSION} here and
+ * repoint the `@gusto/embedded-api` alias target in `package.json`. Everything else —
+ * the `X-Gusto-API-Version` request header and every hand-written TanStack Query key —
+ * derives from this constant, so no per-file edits are required.
+ *
+ * @internal
+ */
+export declare const API_VERSION = "2026-06-15";
+/**
+ * SDK package name and version, sent on every request via the `X-Gusto-SDK-Version`
+ * header so backend traffic can be attributed to a specific SDK release.
+ *
+ * @remarks
+ * Read directly from `package.json` so it always matches the published package —
+ * no manual bump required.
+ *
+ * @internal
+ */
+export declare const SDK_VERSION: string;
+/**
+ * TanStack Query namespace the embedded-api client prefixes onto every generated
+ * query and mutation key (segment 1 of every key it emits).
+ *
+ * @remarks
+ * Must equal the resolved package name so hand-written keys used for targeted
+ * invalidation match the library-generated ones. Derived from {@link API_VERSION}.
+ *
+ * @internal
+ */
+export declare const API_QUERY_NAMESPACE: "@gusto/embedded-api-v-2026-06-15";

package/dist/src/contexts/UnstableFeaturesProvider/useUnstableFeature.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Opt-in flags for SDK functionality that is still in active development.
+ *
+ * @remarks
+ * Pass to {@link GustoProvider} via the `unstableFeatures` prop to enable a feature ahead of its
+ * public release. Every flag defaults to disabled when omitted. When a feature graduates to
+ * public release, its flag is deleted from this interface along with the conditional checks that
+ * read it — there is no deprecation step. This interface may have no flags at all at any given
+ * time — e.g. immediately after the last active flag graduates and before the next one is added —
+ * the opt-in mechanism itself is permanent even when nothing is currently gated behind it.
+ *
+ * @alpha
+ */
+export interface UnstableFeatures {
+    /** Enables recording past payments to contractors within the `ContractorManagement` flows. */
+    historicalPayments?: boolean;
+    /** Enables the in-development regular-rate-of-pay experience for editing an employee's payroll. */
+    payrollRegularRateOfPay?: boolean;
+}
+/**
+ * React context backing {@link useUnstableFeature}.
+ *
+ * @internal
+ */
+export declare const UnstableFeaturesContext: import('react').Context<UnstableFeatures>;
+/**
+ * Reads whether `feature` is enabled via {@link GustoProvider}'s `unstableFeatures` prop.
+ *
+ * @remarks
+ * With `throwIfDisabled: true`, call unconditionally at the top of an alpha component's body —
+ * not inside {@link WithUnstableFeature} — so mounting the component without opting in fails
+ * loudly and immediately. This throws in every environment, including production: using an alpha
+ * component without its flag is an integration mistake, not a runtime state, the same as
+ * {@link useComponentContext} throwing when called outside a `ComponentsProvider`.
+ *
+ * @param feature - The {@link UnstableFeatures} flag to read.
+ * @param options - Set `throwIfDisabled` to throw instead of returning `false` when `feature` is disabled.
+ * @throws When `options.throwIfDisabled` is set and `feature` is not enabled.
+ * @internal
+ */
+export declare const useUnstableFeature: (feature: keyof UnstableFeatures, options?: {
+    throwIfDisabled?: boolean;
+}) => boolean;

package/dist/src/helpers/dateFormatting.d.ts

@@ -0,0 +1,195 @@
+/**
+ * Normalizes any date input (string, Date, or undefined) to a Date object.
+ *
+ * @remarks Handles `YYYY-MM-DD` strings by parsing them in local time to avoid
+ * timezone drift. Also accepts ISO timestamp strings and existing `Date`
+ * instances. Returns `null` for nullish, empty, or unparseable input.
+ *
+ * @param dateInput - The date value to normalize.
+ * @returns A `Date` instance, or `null` if the input is missing or invalid.
+ * @internal
+ */
+export declare const normalizeToDate: (dateInput?: string | Date | null) => Date | null;
+/**
+ * Formats a date as a short weekday plus short month and day (e.g. `Mon, Jan 5`).
+ *
+ * @internal
+ */
+export declare const formatDateShortWithWeekday: (dateInput?: string | Date | null, locale?: string) => string;
+/**
+ * Formats a date as a short weekday, short month, day, and year (e.g. `Mon, Jan 5, 2025`).
+ *
+ * @internal
+ */
+export declare const formatDateShortWithWeekdayAndYear: (dateInput?: string | Date | null, locale?: string) => string;
+/**
+ * Formats a date as a short month and day (e.g. `Jan 5`).
+ *
+ * @internal
+ */
+export declare const formatDateShort: (dateInput?: string | Date | null, locale?: string) => string;
+/**
+ * Formats a date as a short month, day, and year (e.g. `Jan 5, 2025`).
+ *
+ * @internal
+ */
+export declare const formatDateShortWithYear: (dateInput?: string | Date | null, locale?: string) => string;
+/**
+ * Formats a date as a long month and day (e.g. `January 5`).
+ *
+ * @internal
+ */
+export declare const formatDateLong: (dateInput?: string | Date | null, locale?: string) => string;
+/**
+ * Formats a date as a long month, day, and year (e.g. `January 5, 2025`).
+ *
+ * @internal
+ */
+export declare const formatDateLongWithYear: (dateInput?: string | Date | null, locale?: string) => string;
+/**
+ * Splits a date into separate locale-formatted time and date strings.
+ *
+ * @param dateInput - The date value to format.
+ * @param locale - Optional BCP 47 locale tag passed to `toLocaleString`.
+ * @returns An object with `time` (e.g. `3:45 PM EST`) and `date` (e.g. `Mon, Jan 5`).
+ * Both fields are empty strings when the input cannot be parsed.
+ * @internal
+ */
+export declare const formatDateWithTime: (dateInput?: string | Date | null, locale?: string) => {
+    time: string;
+    date: string;
+};
+/**
+ * Formats a pay period start and end date for display as separate fields.
+ *
+ * @remarks Start date renders with the long month and day; end date renders
+ * with the short month, day, and year.
+ *
+ * @param startDateInput - Pay period start date.
+ * @param endDateInput - Pay period end date.
+ * @param locale - Optional BCP 47 locale tag passed to `toLocaleDateString`.
+ * @returns Formatted `startDate` and `endDate` strings. Both fields are empty
+ * strings when either input cannot be parsed.
+ * @internal
+ */
+export declare const formatPayPeriod: (startDateInput?: string | Date | null, endDateInput?: string | Date | null, locale?: string) => {
+    startDate: string;
+    endDate: string;
+};
+/**
+ * Formats a pay period as a single en-dash–separated range string.
+ *
+ * @param startDateInput - Pay period start date.
+ * @param endDateInput - Pay period end date.
+ * @param locale - Optional BCP 47 locale tag passed to `toLocaleDateString`.
+ * @param options - When `useShortMonth` is true, both ends use short month names.
+ * Otherwise the start uses the long month name and the end uses short.
+ * @returns The formatted range (e.g. `January 1–Jan 15, 2025`), or an empty
+ * string when either input cannot be parsed.
+ * @internal
+ */
+export declare const formatPayPeriodRange: (startDateInput?: string | Date | null, endDateInput?: string | Date | null, locale?: string, options?: {
+    useShortMonth?: boolean;
+}) => string;
+/**
+ * Formats a `Date` as a `YYYY-MM-DD` string using the local year, month, and day.
+ *
+ * @param date - The date to format.
+ * @returns A zero-padded `YYYY-MM-DD` string, or `null` when the input is an invalid date.
+ * @internal
+ */
+export declare const formatDateToStringDate: (date: Date) => string | null;
+/**
+ * Converts any parseable date string to a `YYYY-MM-DD` ISO string using local time.
+ *
+ * @remarks Reads the local year, month, and day so the calendar date is
+ * preserved regardless of the runtime timezone. Safe for dates parsed from
+ * locale-format strings (e.g. `4/16/1998`) or ISO strings, both of which land
+ * at local midnight when normalized.
+ *
+ * @param value - The date string to convert.
+ * @returns A `YYYY-MM-DD` string, or `''` for nullish, empty, or unparseable input.
+ * @internal
+ */
+export declare const normalizeToISOString: (value?: string | null) => string;
+/**
+ * Normalizes a `Date` to local midnight, stripping any time-of-day component.
+ *
+ * @param date - The date to normalize, or `null`.
+ * @returns A new `Date` at local midnight, or `null` when the input is missing or invalid.
+ * @internal
+ */
+export declare const normalizeDateToLocal: (date: Date | null) => Date | null;
+/**
+ * Number of milliseconds in one hour.
+ *
+ * @internal
+ */
+export declare const MS_PER_HOUR: number;
+/**
+ * Returns the number of hours from now until a deadline.
+ *
+ * @param deadline - Target date in the future (or past, for negative results).
+ * @returns Hours until `deadline` (fractional, negative if `deadline` is in
+ * the past), or `null` when the input cannot be parsed.
+ * @internal
+ */
+export declare const getHoursUntil: (deadline?: Date | string | null) => number | null;
+/**
+ * Returns the number of days from now until a deadline.
+ *
+ * @param deadline - Target date in the future (or past, for negative results).
+ * @returns Days until `deadline` (fractional, negative if `deadline` is in
+ * the past), or `null` when the input cannot be parsed.
+ * @internal
+ */
+export declare const getDaysUntil: (deadline?: Date | string | null) => number | null;
+/**
+ * Returns a new `Date` offset from the input by a given number of days.
+ *
+ * @param date - The base date. Not mutated.
+ * @param days - Number of days to add (negative values subtract).
+ * @returns A new `Date` shifted by `days`.
+ * @internal
+ */
+export declare const addDays: (date: Date, days: number) => Date;
+/**
+ * Returns a new `Date` offset by a given number of years.
+ *
+ * @param date - The base date. Not mutated.
+ * @param years - Number of years to add (negative values subtract).
+ * @returns A new `Date` shifted by `years`.
+ * @internal
+ */
+export declare const addYears: (date: Date, years: number) => Date;
+/**
+ * Returns a new `Date` offset by a given number of business days (Monday–Friday).
+ *
+ * @remarks Skips Saturdays and Sundays when counting. The result is normalized
+ * to local midnight. Does not account for holidays.
+ *
+ * @param startDate - The base date. Not mutated.
+ * @param businessDays - Number of business days to add.
+ * @returns A new `Date` shifted forward by `businessDays` weekdays.
+ * @internal
+ */
+export declare const addBusinessDays: (startDate: Date, businessDays: number) => Date;
+/**
+ * Formats numeric month and day as a zero-padded `MM-DD` string.
+ *
+ * @param month - Month number, 1–12.
+ * @param day - Day-of-month number, 1–31.
+ * @returns A `MM-DD` string, or `undefined` when either argument is missing.
+ * @internal
+ */
+export declare function formatMonthDay(month?: number, day?: number): string | undefined;
+/**
+ * Returns the number of days in a given month (1-indexed).
+ *
+ * @remarks Uses a non-leap year, so February always returns 28.
+ *
+ * @param month - Month number, 1–12.
+ * @returns The number of days in that month.
+ * @internal
+ */
+export declare function getDaysInMonth(month: number): number;

package/dist/src/helpers/formattedStrings.d.ts

@@ -0,0 +1,182 @@
+import { Location } from '@gusto/embedded-api/models/components/location';
+import { EmployeeAddress } from '@gusto/embedded-api/models/components/employeeaddress';
+import { TFunction } from 'i18next';
+/**
+ * Joins a first, middle initial, and last name into a single capitalized display string.
+ *
+ * @remarks Each name part is capitalized at its first character. A space is
+ * inserted before the middle initial and last name only when that part is
+ * present. Missing parts are treated as empty.
+ *
+ * @param name - Object with optional `first_name`, `middle_initial`, and `last_name` fields.
+ * @returns The combined name, e.g. `Jane M Doe`, `Jane Doe`, `Jane`, or `''`.
+ * @internal
+ */
+export declare const firstLastName: ({ first_name, middle_initial, last_name, }: {
+    first_name?: string | null;
+    middle_initial?: string | null;
+    last_name?: string | null;
+}) => string;
+/**
+ * Combines an address's two street lines with a comma separator.
+ *
+ * @remarks Each line is prefixed with a leading space when present, producing
+ * a string like ` 123 Main St, Apt 4`. Prefer {@link formatStreetForDisplay}
+ * for new display code; this function is retained for legacy callers.
+ *
+ * @param address - Address whose `street1` and `street2` are joined.
+ * @returns The joined street string.
+ * @internal
+ */
+export declare const getStreet: (address: EmployeeAddress | Location) => string;
+/**
+ * Joins an address's street lines with a comma for display.
+ *
+ * @remarks Trims each line and skips empty values, avoiding the leading-space
+ * and trailing-comma artifacts of {@link getStreet}.
+ *
+ * @param address - Address whose `street1` and `street2` are joined.
+ * @returns The display-formatted street string, e.g. `123 Main St, Apt 4`.
+ * @internal
+ */
+export declare const formatStreetForDisplay: (address: EmployeeAddress | Location) => string;
+/**
+ * Formats an address's city, state, and zip into a single display string.
+ *
+ * @param address - Address whose `city`, `state`, and `zip` are joined.
+ * @returns A `City, State Zip` string. Empty fields are skipped.
+ * @internal
+ */
+export declare const getCityStateZip: (address: EmployeeAddress | Location) => string;
+/**
+ * Formats a full address as a single inline string.
+ *
+ * @param address - The address to format.
+ * @returns The combined street and city/state/zip string.
+ * @internal
+ */
+export declare const addressInline: (address: EmployeeAddress | Location) => string;
+/**
+ * Formats a number as a USD currency string with two decimal places.
+ *
+ * @param amount - The numeric value to format.
+ * @param locale - Optional BCP 47 locale tag passed to `toLocaleString`.
+ * Defaults to `en-US`.
+ * @returns A `$1,234.56` style currency string.
+ * @internal
+ */
+export declare const formatNumberAsCurrency: (amount: number, locale?: string) => string;
+/**
+ * Formats a pay rate with its payment unit, annualizing weekly and monthly values.
+ *
+ * @remarks Hourly, yearly, and paycheck rates are displayed at the input
+ * value. Weekly rates are multiplied by 52 and monthly rates by 12 to express
+ * an annualized amount. Unknown payment units render as the currency value
+ * alone.
+ *
+ * @param args - Formatting inputs: `rate` (numeric value), `paymentUnit`
+ * (`Hour`, `Week`, `Month`, `Year`, or `Paycheck`), `t` (i18next translation
+ * function), and optional `locale` (BCP 47 tag, default `en-US`).
+ * @returns The translated, formatted pay rate string.
+ * @internal
+ */
+export declare const formatPayRate: ({ rate, paymentUnit, t, locale, }: {
+    rate: number;
+    paymentUnit: string;
+    t: TFunction;
+    locale?: string;
+}) => string;
+/**
+ * Formats a compensation rate as-is, without annualizing weekly or monthly values.
+ *
+ * @remarks Use for displaying compensation card data where the stored rate
+ * should be shown directly (e.g. `$950 per week`, `$3,500 per month`).
+ * Unknown payment units render as the currency value alone.
+ *
+ * @param args - Formatting inputs: `rate` (numeric value), `paymentUnit`
+ * (`Hour`, `Week`, `Month`, `Year`, or `Paycheck`), `t` (i18next translation
+ * function), and optional `locale` (BCP 47 tag, default `en-US`).
+ * @returns The translated, formatted compensation rate string.
+ * @internal
+ */
+export declare const formatCompensationRate: ({ rate, paymentUnit, t, locale, }: {
+    rate: number;
+    paymentUnit: string;
+    t: TFunction;
+    locale?: string;
+}) => string;
+/**
+ * Hook that returns a memoized {@link formatCompensationRate} bound to the active locale.
+ *
+ * @returns A callback `(rate, paymentUnit) => string`.
+ * @internal
+ */
+export declare const useFormatCompensationRate: () => (rate: number, paymentUnit: string) => string;
+/**
+ * Sanitizes an HTML string for use with React's `dangerouslySetInnerHTML`.
+ *
+ * @remarks Only `<a>`, `<b>`, and `<strong>` tags are allowed, and `<a>`
+ * elements may retain only `href` and `target` attributes. All other markup
+ * is stripped via DOMPurify.
+ *
+ * @param dirty - The raw HTML string to sanitize.
+ * @returns An object shaped for `dangerouslySetInnerHTML`. The `__html`
+ * field is `''` when the input is empty.
+ * @internal
+ */
+export declare function createMarkup(dirty: string): {
+    __html: string;
+};
+/**
+ * Removes all non-digit characters from a string.
+ *
+ * @param value - The string to filter.
+ * @returns The input with only the digit characters `0`–`9` retained.
+ * @internal
+ */
+export declare const removeNonDigits: (value: string) => string;
+/**
+ * Strips the trailing `.value` segment from an API error path.
+ *
+ * @remarks API validation errors target a `.value` field on the inner
+ * object, but react-hook-form registers the field under its bare name.
+ * Stripping `.value` aligns the error path with the form field name.
+ *
+ * @param errorKey - The dotted error path returned by the API.
+ * @returns The error key without a trailing `.value`.
+ * @internal
+ */
+export declare const normalizeErrorKeyForForm: (errorKey: string) => string;
+/**
+ * Converts a `snake_case` string to `camelCase`.
+ *
+ * @param s - The snake_case string to convert.
+ * @returns The camelCase equivalent.
+ * @internal
+ */
+export declare const snakeCaseToCamelCase: (s: string) => string;
+/**
+ * Converts a `camelCase` or `PascalCase` string to `snake_case`.
+ *
+ * @remarks Handles consecutive uppercase letters by inserting a separator
+ * before the final letter of a run that is followed by a lowercase letter
+ * (e.g. `HTMLParser` becomes `html_parser`).
+ *
+ * @param s - The camelCase or PascalCase string to convert.
+ * @returns The snake_case equivalent in lower case.
+ * @internal
+ */
+export declare const camelCaseToSnakeCase: (s: string) => string;
+/**
+ * Formats a US phone number as `NNN-NNN-NNNN` for display.
+ *
+ * @remarks Strips non-digit characters before formatting. A leading `1`
+ * country code on 11-digit inputs is dropped. Inputs that are not 10 or 11
+ * digits are returned as the raw digit string. Returns an empty string for
+ * nullish input.
+ *
+ * @param phoneNumber - The phone number to format.
+ * @returns The formatted phone number, the digit-only fallback, or `''`.
+ * @internal
+ */
+export declare const formatPhoneNumber: (phoneNumber: string | number | null | undefined) => string;