@servicetitan/anvil2-ext-common 0.3.20 → 0.5.0

package/dist/src/components/Suggestions/Suggestions.d.ts

@@ -0,0 +1,59 @@
+import { ReactNode } from 'react';
+type Handler = (...args: any[]) => void;
+type Handlers = Record<string, Handler | undefined>;
+export interface SuggestionsApi {
+    /**
+     * Props for a field that should be highlighted while it holds a suggested
+     * value. Returns `isHighlighted` plus copies of any handlers you pass, each
+     * wrapped to clear the highlight on the first user edit. Pass the handler
+     * under the field's own prop name (`onChange`, `onSelectedOptionChange`, ...).
+     *
+     * @example <TextField {...suggestable("city", { onChange: setCity })} />
+     */
+    suggestable: <O extends Handlers>(key: string, handlers?: O) => {
+        isHighlighted: boolean;
+    } & O;
+    /**
+     * Props for the field whose selection populates the others. Returns copies of
+     * the handlers you pass, each wrapped to first mark the suggestable fields as
+     * highlighted. Your handler still does the value population.
+     *
+     * @param keys which fields to highlight; defaults to every registered key.
+     * @example <TypeaheadTextField {...suggestor({ onSelectOption: apply })} />
+     */
+    suggestor: <O extends Handlers>(handlers?: O, keys?: string[]) => O;
+    /** Imperatively highlight fields (defaults to every registered key). */
+    markSuggested: (keys?: string[]) => void;
+    /** Imperatively clear a field's highlight. */
+    clearHighlight: (key: string) => void;
+    /** Whether a field is currently holding a suggested value. */
+    isHighlighted: (key: string) => boolean;
+}
+export interface SuggestionsProps {
+    children: (api: SuggestionsApi) => ReactNode;
+}
+/**
+ * Coordinates the "highlight fields populated by a suggestion until edited"
+ * behavior for a group of fields, without per-field state wiring.
+ *
+ * Relies on the fact that a controlled field's change handler fires only on
+ * user input, never when its `value` prop changes programmatically — so we
+ * track provenance per field rather than comparing values. A field stays
+ * un-highlighted after an edit even if the suggested value is re-entered,
+ * because typing still fires the handler.
+ *
+ * @example
+ * <Suggestions>
+ *   {({ suggestor, suggestable }) => (
+ *     <>
+ *       <TypeaheadTextField
+ *         {...suggestor({ onSelectOption: (opt) => applyAddress(opt.value) })}
+ *         loadOptions={lookupAddresses}
+ *       />
+ *       <TextField {...suggestable("city", { onChange: handleCity })} />
+ *     </>
+ *   )}
+ * </Suggestions>
+ */
+export declare function Suggestions({ children }: SuggestionsProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/src/components/Suggestions/index.d.ts

@@ -0,0 +1,2 @@
+export * from './Suggestions';
+export { Suggestions as default } from './Suggestions';

package/dist/src/components/index.d.ts

@@ -1 +1,2 @@
 export * from './ExampleComponent';
+export * from './Suggestions';

package/dist/src/form/components/Form.d.ts

@@ -0,0 +1,15 @@
+export declare const Form: {
+    TextField: ({ fieldState, disabled, ...props }: import('./FormTextField').FormTextFieldProps) => import("react/jsx-runtime").JSX.Element;
+    Textarea: ({ fieldState, disabled, ...props }: import('./FormTextarea').FormTextareaProps) => import("react/jsx-runtime").JSX.Element;
+    NumberField: ({ fieldState, disabled, ...props }: import('./FormNumberField').FormNumberFieldProps) => import("react/jsx-runtime").JSX.Element;
+    DateFieldSingle: ({ fieldState, disabled, ...props }: import('./FormDateFieldSingle').FormDateFieldSingleProps) => import("react/jsx-runtime").JSX.Element;
+    DateFieldRange: ({ fieldState, disabled, ...props }: import('./FormDateFieldRange').FormDateFieldRangeProps) => import("react/jsx-runtime").JSX.Element;
+    DateFieldYearless: ({ fieldState, disabled, ...props }: import('./FormDateFieldYearless').FormDateFieldYearlessProps) => import("react/jsx-runtime").JSX.Element;
+    DateFieldYearlessRange: ({ fieldState, disabled, ...props }: import('./FormDateFieldYearlessRange').FormDateFieldYearlessRangeProps) => import("react/jsx-runtime").JSX.Element;
+    TimeField: ({ fieldState, disabled, ...props }: import('./FormTimeField').FormTimeFieldProps) => import("react/jsx-runtime").JSX.Element;
+    Select: ({ fieldState, disabled, ...props }: import('./FormSelect').FormSelectProps) => import("react/jsx-runtime").JSX.Element;
+    MultiSelect: ({ fieldState, disabled, ...props }: import('./FormMultiSelect').FormMultiSelectProps) => import("react/jsx-runtime").JSX.Element;
+    TreeSelect: ({ fieldState, disabled, ...props }: import('./FormTreeSelect').FormTreeSelectProps) => import("react/jsx-runtime").JSX.Element;
+    RadioGroup: <T, G extends import('./FormRadioGroup').FormRadioGroupItem<T>>({ fieldState, items, disabled, ...props }: import('./FormRadioGroup').FormRadioGroupProps<T, G>) => import("react/jsx-runtime").JSX.Element;
+    CheckboxGroup: <T, G extends import('./FormCheckboxGroup').FormCheckboxGroupItem<T>>({ fieldState, items, disabled, ...props }: import('./FormCheckboxGroup').FormCheckboxGroupProps<T, G>) => import("react/jsx-runtime").JSX.Element;
+};

package/dist/src/form/components/FormCheckboxGroup/FormCheckboxGroup.d.ts

@@ -0,0 +1,13 @@
+import { ReactNode } from 'react';
+import { CheckboxGroupProps } from '@servicetitan/anvil2';
+import { SelectableOptionsArrayFieldState, OptionType } from '../../state';
+export interface FormCheckboxGroupItem<T> extends OptionType<T> {
+    label: ReactNode;
+}
+export interface FormCheckboxGroupProps<T, G extends FormCheckboxGroupItem<T>> extends Omit<CheckboxGroupProps, "error" | "warning" | "children"> {
+    fieldState: SelectableOptionsArrayFieldState<T, G>;
+    items: G[];
+}
+declare function FormCheckboxGroupInner<T, G extends FormCheckboxGroupItem<T>>({ fieldState, items, disabled, ...props }: FormCheckboxGroupProps<T, G>): import("react/jsx-runtime").JSX.Element;
+export declare const FormCheckboxGroup: typeof FormCheckboxGroupInner;
+export {};

package/dist/src/form/components/FormCheckboxGroup/index.d.ts

@@ -0,0 +1 @@
+export * from './FormCheckboxGroup';

package/dist/src/form/components/FormDateFieldRange/FormDateFieldRange.d.ts

@@ -0,0 +1,6 @@
+import { DateFieldRangeProps, DateFieldRangeValue } from '@servicetitan/anvil2';
+import { A2InputFieldState } from '../../state';
+export interface FormDateFieldRangeProps extends Omit<DateFieldRangeProps, "value" | "onChange" | "error" | "warning"> {
+    fieldState: A2InputFieldState<DateFieldRangeValue | null>;
+}
+export declare const FormDateFieldRange: ({ fieldState, disabled, ...props }: FormDateFieldRangeProps) => import("react/jsx-runtime").JSX.Element;

package/dist/src/form/components/FormDateFieldRange/index.d.ts

@@ -0,0 +1 @@
+export * from './FormDateFieldRange';

package/dist/src/form/components/FormDateFieldSingle/FormDateFieldSingle.d.ts

@@ -0,0 +1,6 @@
+import { DateFieldSingleProps } from '@servicetitan/anvil2';
+import { A2InputFieldState } from '../../state';
+export interface FormDateFieldSingleProps extends Omit<DateFieldSingleProps, "value" | "onChange" | "error" | "warning"> {
+    fieldState: A2InputFieldState<string | null>;
+}
+export declare const FormDateFieldSingle: ({ fieldState, disabled, ...props }: FormDateFieldSingleProps) => import("react/jsx-runtime").JSX.Element;

package/dist/src/form/components/FormDateFieldSingle/index.d.ts

@@ -0,0 +1 @@
+export * from './FormDateFieldSingle';

package/dist/src/form/components/FormDateFieldYearless/FormDateFieldYearless.d.ts

@@ -0,0 +1,6 @@
+import { DateFieldYearlessProps, YearlessDate } from '@servicetitan/anvil2';
+import { A2InputFieldState } from '../../state';
+export interface FormDateFieldYearlessProps extends Omit<DateFieldYearlessProps, "value" | "onChange" | "error" | "warning"> {
+    fieldState: A2InputFieldState<YearlessDate | null>;
+}
+export declare const FormDateFieldYearless: ({ fieldState, disabled, ...props }: FormDateFieldYearlessProps) => import("react/jsx-runtime").JSX.Element;

package/dist/src/form/components/FormDateFieldYearless/index.d.ts

@@ -0,0 +1 @@
+export * from './FormDateFieldYearless';

package/dist/src/form/components/FormDateFieldYearlessRange/FormDateFieldYearlessRange.d.ts

@@ -0,0 +1,6 @@
+import { DateFieldYearlessRangeProps, DateFieldYearlessRangeValue } from '@servicetitan/anvil2';
+import { A2InputFieldState } from '../../state';
+export interface FormDateFieldYearlessRangeProps extends Omit<DateFieldYearlessRangeProps, "value" | "onChange" | "error" | "warning"> {
+    fieldState: A2InputFieldState<DateFieldYearlessRangeValue>;
+}
+export declare const FormDateFieldYearlessRange: ({ fieldState, disabled, ...props }: FormDateFieldYearlessRangeProps) => import("react/jsx-runtime").JSX.Element;

package/dist/src/form/components/FormDateFieldYearlessRange/index.d.ts

@@ -0,0 +1 @@
+export * from './FormDateFieldYearlessRange';

package/dist/src/form/components/FormMultiSelect/FormMultiSelect.d.ts

@@ -0,0 +1,12 @@
+import { MultiSelectFieldOption, MultiSelectFieldProps } from '@servicetitan/anvil2/beta';
+import { A2InputFieldState, DistributiveOmit } from '../../state';
+/**
+ * FormMultiSelect wraps the beta MultiSelectField and binds it to an
+ * A2InputFieldState. Supports all loader modes (eager and all lazy variants)
+ * because the props type uses DistributiveOmit to preserve each union member's
+ * loader type.
+ */
+export type FormMultiSelectProps = DistributiveOmit<MultiSelectFieldProps, "value" | "onSelectedOptionsChange" | "error" | "warning"> & {
+    fieldState: A2InputFieldState<MultiSelectFieldOption[]>;
+};
+export declare const FormMultiSelect: ({ fieldState, disabled, ...props }: FormMultiSelectProps) => import("react/jsx-runtime").JSX.Element;

package/dist/src/form/components/FormMultiSelect/index.d.ts

@@ -0,0 +1 @@
+export * from './FormMultiSelect';

package/dist/src/form/components/FormNumberField/FormNumberField.d.ts

@@ -0,0 +1,6 @@
+import { NumberFieldProps } from '@servicetitan/anvil2';
+import { A2InputFieldState } from '../../state';
+export interface FormNumberFieldProps extends Omit<NumberFieldProps, "value" | "onChange" | "error" | "warning"> {
+    fieldState: A2InputFieldState<number | null>;
+}
+export declare const FormNumberField: ({ fieldState, disabled, ...props }: FormNumberFieldProps) => import("react/jsx-runtime").JSX.Element;

package/dist/src/form/components/FormNumberField/index.d.ts

@@ -0,0 +1 @@
+export * from './FormNumberField';

package/dist/src/form/components/FormRadioGroup/FormRadioGroup.d.ts

@@ -0,0 +1,13 @@
+import { ReactNode } from 'react';
+import { RadioGroupProps } from '@servicetitan/anvil2';
+import { SelectableOptionsFieldState, OptionType } from '../../state';
+export interface FormRadioGroupItem<T> extends OptionType<T> {
+    label: ReactNode;
+}
+export interface FormRadioGroupProps<T, G extends FormRadioGroupItem<T>> extends Omit<RadioGroupProps, "error" | "warning" | "children"> {
+    fieldState: SelectableOptionsFieldState<T, G>;
+    items: G[];
+}
+declare function FormRadioGroupInner<T, G extends FormRadioGroupItem<T>>({ fieldState, items, disabled, ...props }: FormRadioGroupProps<T, G>): import("react/jsx-runtime").JSX.Element;
+export declare const FormRadioGroup: typeof FormRadioGroupInner;
+export {};

package/dist/src/form/components/FormRadioGroup/index.d.ts

@@ -0,0 +1 @@
+export * from './FormRadioGroup';

package/dist/src/form/components/FormSelect/FormSelect.d.ts

@@ -0,0 +1,11 @@
+import { SelectFieldOption, SelectFieldProps } from '@servicetitan/anvil2/beta';
+import { A2InputFieldState, DistributiveOmit } from '../../state';
+/**
+ * FormSelect wraps the beta SelectField and binds it to an A2InputFieldState.
+ * Supports all loader modes (eager and all lazy variants) because the props
+ * type uses DistributiveOmit to preserve each union member's loader type.
+ */
+export type FormSelectProps = DistributiveOmit<SelectFieldProps, "value" | "onSelectedOptionChange" | "error" | "warning"> & {
+    fieldState: A2InputFieldState<SelectFieldOption | null>;
+};
+export declare const FormSelect: ({ fieldState, disabled, ...props }: FormSelectProps) => import("react/jsx-runtime").JSX.Element;

package/dist/src/form/components/FormSelect/index.d.ts

@@ -0,0 +1 @@
+export * from './FormSelect';

package/dist/src/form/components/FormTextField/FormTextField.d.ts

@@ -0,0 +1,6 @@
+import { TextFieldProps } from '@servicetitan/anvil2';
+import { A2InputFieldState } from '../../state';
+export interface FormTextFieldProps extends Omit<TextFieldProps, "value" | "onChange" | "error" | "warning"> {
+    fieldState: A2InputFieldState<string>;
+}
+export declare const FormTextField: ({ fieldState, disabled, ...props }: FormTextFieldProps) => import("react/jsx-runtime").JSX.Element;

package/dist/src/form/components/FormTextField/index.d.ts

@@ -0,0 +1 @@
+export * from './FormTextField';

package/dist/src/form/components/FormTextarea/FormTextarea.d.ts

@@ -0,0 +1,6 @@
+import { TextareaProps } from '@servicetitan/anvil2';
+import { A2InputFieldState } from '../../state';
+export interface FormTextareaProps extends Omit<TextareaProps, "value" | "onChange" | "error" | "warning"> {
+    fieldState: A2InputFieldState<string>;
+}
+export declare const FormTextarea: ({ fieldState, disabled, ...props }: FormTextareaProps) => import("react/jsx-runtime").JSX.Element;

package/dist/src/form/components/FormTextarea/index.d.ts

@@ -0,0 +1 @@
+export * from './FormTextarea';

package/dist/src/form/components/FormTimeField/FormTimeField.d.ts

@@ -0,0 +1,6 @@
+import { TimeFieldProps } from '@servicetitan/anvil2';
+import { A2InputFieldState } from '../../state';
+export interface FormTimeFieldProps extends Omit<TimeFieldProps, "value" | "onChange" | "error" | "warning"> {
+    fieldState: A2InputFieldState<string | null>;
+}
+export declare const FormTimeField: ({ fieldState, disabled, ...props }: FormTimeFieldProps) => import("react/jsx-runtime").JSX.Element;

package/dist/src/form/components/FormTimeField/index.d.ts

@@ -0,0 +1 @@
+export * from './FormTimeField';

package/dist/src/form/components/FormTreeSelect/FormTreeSelect.d.ts

@@ -0,0 +1,12 @@
+import { TreeSelectFieldValue, TreeSelectFieldProps } from '@servicetitan/anvil2/beta';
+import { A2InputFieldState } from '../../state';
+/**
+ * FormTreeSelect wraps the beta TreeSelectField and binds it to an
+ * A2InputFieldState. TreeSelectFieldProps is a flat (non-union) type so we can
+ * use Omit directly. The loadOptions signature is:
+ *   (searchValue: string, parentNode?: TreeSelectFieldNode) => TreeSelectFieldNode[] | Promise<TreeSelectFieldNode[]>
+ */
+export interface FormTreeSelectProps extends Omit<TreeSelectFieldProps, "value" | "onSelectedOptionsChange" | "error" | "warning"> {
+    fieldState: A2InputFieldState<TreeSelectFieldValue[]>;
+}
+export declare const FormTreeSelect: ({ fieldState, disabled, ...props }: FormTreeSelectProps) => import("react/jsx-runtime").JSX.Element;

package/dist/src/form/components/FormTreeSelect/index.d.ts

@@ -0,0 +1 @@
+export * from './FormTreeSelect';

package/dist/src/form/components/index.d.ts

@@ -0,0 +1,13 @@
+export * from './FormTextField';
+export * from './FormTextarea';
+export * from './FormNumberField';
+export * from './FormDateFieldSingle';
+export * from './FormDateFieldRange';
+export * from './FormDateFieldYearless';
+export * from './FormDateFieldYearlessRange';
+export * from './FormTimeField';
+export * from './FormSelect';
+export * from './FormMultiSelect';
+export * from './FormTreeSelect';
+export * from './FormRadioGroup';
+export * from './FormCheckboxGroup';

package/dist/src/form/index.d.ts

@@ -0,0 +1,3 @@
+export * from './state';
+export * from './components';
+export * from './components/Form';

package/dist/src/form/state/A2InputFieldState.d.ts

@@ -0,0 +1,54 @@
+import { FieldState } from 'formstate';
+import { ChangeEvent, SyntheticEvent } from 'react';
+import { UpdateMode, Validator, WarningValidator } from './types';
+/**
+ * Base field-state for Anvil2 form fields. Extends formstate's `FieldState` with
+ * non-blocking warnings, dynamic disablers, soft validation, hard-set helpers,
+ * an optional update-mode sub-field, and `@servicetitan/form`-compatible change
+ * handlers. Ported from the app's `A2InputFieldState` onto formstate directly.
+ */
+export declare class A2InputFieldState<T> extends FieldState<T> {
+    warning: string | undefined;
+    disabled: boolean;
+    /** Optional sub-field tracking how the value should be applied. */
+    updateMode?: FieldState<UpdateMode>;
+    private _warnings;
+    private _disablers;
+    private additionalValidations;
+    private _onReset;
+    constructor(initValue: T);
+    /** `@servicetitan/form`-compatible handler: `(event, { value })`. */
+    onChangeHandler: (_event: SyntheticEvent<HTMLInputElement>, data: {
+        value: T;
+    }) => void;
+    /** `@servicetitan/form`-compatible native handler: reads `event.currentTarget.value`. */
+    onChangeNativeHandler: (event: ChangeEvent<HTMLInputElement>) => void;
+    onChange(value: T): void;
+    validate(): Promise<{
+        hasError: true;
+    } | {
+        hasError: false;
+        value: T;
+    }>;
+    /** Run disablers + warnings without committing a full validation. */
+    softValidate(): Promise<void>;
+    /** Register a handler that runs after the field is reset. */
+    onReset(handler: () => void): this;
+    reset(value?: T): void;
+    hardSetValue: (value: T) => void;
+    hardConfirmValue: () => void;
+    seedValue: (value: T) => void;
+    /** Add a validator once per key (guards against double registration). */
+    addValidator(validationKey: string, validator: Validator<T>): void;
+    disablers(...validators: WarningValidator<T>[]): void;
+    checkDisablers: () => void;
+    warnings(...validators: WarningValidator<T>[]): void;
+    checkWarnings: () => void;
+    enableUpdateMode(initUpdateMode?: UpdateMode): void;
+    disableUpdateMode(): void;
+    hasValueChanged: () => boolean;
+    hasUpdateModeValueChanged: () => boolean;
+    /** The field's initial value (public so consumers can compare against it). */
+    get initValue(): T;
+    private getInitValue;
+}

package/dist/src/form/state/SelectableOptionsFieldState.d.ts

@@ -0,0 +1,20 @@
+import { A2InputFieldState } from './A2InputFieldState';
+import { OptionType, OptionValidationRule } from './types';
+export type SelectableOptionsConfig<T, G extends OptionType<T>> = {
+    validationRules?: OptionValidationRule<T, G>[];
+};
+export declare class SelectableOptionsFieldState<T, G extends OptionType<T>> extends A2InputFieldState<T> {
+    options: G[];
+    private validationTrackers;
+    private config?;
+    constructor(initValue: T, config?: SelectableOptionsConfig<T, G>);
+    setOptions(newOptions: G[]): void;
+}
+export declare class SelectableOptionsArrayFieldState<T, G extends OptionType<T>> extends A2InputFieldState<T[]> {
+    options: G[];
+    private validationTrackers;
+    private config?;
+    constructor(initValue: T[], config?: SelectableOptionsConfig<T, G>);
+    setOptions(newOptions: G[]): void;
+    hasValueChanged: () => boolean;
+}

package/dist/src/form/state/index.d.ts

@@ -0,0 +1,3 @@
+export * from './types';
+export * from './A2InputFieldState';
+export * from './SelectableOptionsFieldState';

package/dist/src/form/state/types.d.ts

@@ -0,0 +1,31 @@
+import { Validator } from 'formstate';
+/**
+ * How a value-update control should apply its value. Ported from the app's
+ * A2InputFieldState. Primarily useful for value-update controls.
+ */
+export declare enum UpdateMode {
+    Keep = "Keep",
+    Replace = "Replace",
+    Append = "Append",
+    Remove = "Remove",
+    Clear = "Clear"
+}
+/** A validator that returns a message string (truthy) or a falsy value when OK. */
+export type WarningValidator<T> = (value: T) => string | false | null | undefined;
+/** Minimal selectable option shape used by the SelectableOptions field states. */
+export type OptionType<T> = {
+    id: T;
+    disabled?: boolean;
+};
+/**
+ * Rule that flags a tracked option as invalid. When a selected value matches a
+ * tracked option, the field reports `errorCode` as its error.
+ */
+export type OptionValidationRule<T, G extends OptionType<T>> = {
+    /** Return true if this option should be tracked as a validation trigger. */
+    shouldTrack: (option: G) => boolean;
+    /** The error code/message returned when a tracked value is selected. */
+    errorCode: string;
+};
+export type { Validator };
+export type DistributiveOmit<T, K extends keyof never> = T extends unknown ? Omit<T, K> : never;

package/dist/src/index.d.ts

@@ -2,3 +2,4 @@ export * from './components';
 export * from './hooks';
 export * from './providers';
 export * from './types';
+export * from './form';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@servicetitan/anvil2-ext-common",
-  "version": "0.3.20",
+  "version": "0.5.0",
   "type": "module",
   "types": "./dist/src/index.d.ts",
   "main": "./dist/index.js",
@@ -31,16 +31,22 @@
     "tabbable": "^6.2.0",
     "tinycolor2": "^1.6.0",
     "uuid": "^14.0.0",
-    "@servicetitan/anvil2": "3.0.9"
+    "@servicetitan/anvil2": "^3.2.0"
   },
   "peerDependencies": {
     "@types/react": "^18 || ^19",
     "@types/react-dom": "^18 || ^19",
+    "formstate": "^2.1.0",
+    "mobx": "^6.9.0",
+    "mobx-react": "^9.2.0",
     "react": "^18 || ^19",
     "react-dom": "^18 || ^19"
   },
   "devDependencies": {
     "@chromatic-com/storybook": "^5.1.2",
+    "formstate": "2.1.0",
+    "mobx": "^6.9.0",
+    "mobx-react": "^9.2.0",
     "@storybook/addon-a11y": "10.3.5",
     "@storybook/addon-docs": "10.3.5",
     "@storybook/addon-links": "10.3.5",