@webority-technologies/mobile 0.0.22 → 0.0.24

package/lib/typescript/module/form/types.d.ts

@@ -0,0 +1,94 @@
+export type FormValues = Record<string, unknown>;
+export type FormErrors = Record<string, string | undefined>;
+export type FormTouched = Record<string, boolean>;
+export type ValidationResult = string | undefined | null | false;
+/**
+ * A single validation rule. Receives the field value and the whole values
+ * object (so cross-field rules work). Return an error message string when
+ * invalid, or any falsy value when valid. May be async — return a Promise for
+ * server-side checks ("is this email already registered?").
+ */
+export type ValidationRule<V = any, Values extends FormValues = FormValues> = (value: V, allValues: Values) => ValidationResult | Promise<ValidationResult>;
+export type FieldRules<V = any, Values extends FormValues = FormValues> = ValidationRule<V, Values> | ValidationRule<V, Values>[];
+/** Per-field rule map keyed by field path (e.g. `{ email: [rules.required(), rules.email()] }`). */
+export type ValidationSchema<Values extends FormValues = FormValues> = Record<string, FieldRules<any, Values>>;
+/** Form-level validate function returning an errors map keyed by field path. */
+export type FormValidateFn<Values extends FormValues = FormValues> = (values: Values) => FormErrors | Promise<FormErrors>;
+export type ValidateOn = 'change' | 'blur' | 'submit';
+export interface SubmitHelpers<Values extends FormValues = FormValues> {
+    setErrors: (errors: FormErrors) => void;
+    setFieldError: (name: string, error?: string) => void;
+    reset: (nextValues?: Partial<Values>) => void;
+    setSubmitting: (submitting: boolean) => void;
+}
+export interface FormConfig<Values extends FormValues = FormValues> {
+    initialValues: Values;
+    /** Either a per-field rule map or a single form-level validate function. */
+    validate?: ValidationSchema<Values> | FormValidateFn<Values>;
+    /** When validation first runs for a field. Library default: 'submit'. */
+    validateOn?: ValidateOn;
+    /** After a field has surfaced an error once, how it re-validates. Library default: 'change'. */
+    revalidateOn?: 'change' | 'blur';
+    onSubmit: (values: Values, helpers: SubmitHelpers<Values>) => void | Promise<void>;
+    /** Re-initialise values when `initialValues` changes (e.g. async-loaded edit form). Default: false. */
+    enableReinitialize?: boolean;
+}
+export interface FieldState<V = unknown> {
+    value: V;
+    /** Error the UI should show (gated by touched / submit). */
+    error: string | undefined;
+    /** Error regardless of touched — useful for `isValid`-style logic. */
+    rawError: string | undefined;
+    touched: boolean;
+    dirty: boolean;
+}
+/** Props an input needs to bind to a form field. Covers text and non-text controls. */
+export interface FieldInputProps<V = unknown> {
+    name: string;
+    value: V;
+    error: string | undefined;
+    touched: boolean;
+    /** Generic change handler (Select/Switch/DatePicker/Slider…). */
+    onChange: (value: V) => void;
+    /** Text-input alias of `onChange` (TextInput's `onChangeText`). */
+    onChangeText: (text: string) => void;
+    onBlur: () => void;
+    /** Marks this field as the focused one (drives KeyboardToolbar next/prev). */
+    onFocus: () => void;
+    setValue: (value: V, shouldValidate?: boolean) => void;
+}
+export interface FocusableNode {
+    focus?: () => void;
+    measureInWindow?: (cb: (x: number, y: number, w: number, h: number) => void) => void;
+}
+export interface FormApi<Values extends FormValues = FormValues> {
+    values: Values;
+    /** Touched/submit-gated errors — what the UI shows. */
+    errors: FormErrors;
+    /** Every current error regardless of touched. */
+    rawErrors: FormErrors;
+    touched: FormTouched;
+    dirty: boolean;
+    isValid: boolean;
+    isSubmitting: boolean;
+    isValidating: boolean;
+    submitCount: number;
+    setFieldValue: (name: string, value: unknown, shouldValidate?: boolean) => void;
+    setFieldTouched: (name: string, touched?: boolean, shouldValidate?: boolean) => void;
+    setFieldError: (name: string, error?: string) => void;
+    setValues: (next: Partial<Values> | ((prev: Values) => Values), shouldValidate?: boolean) => void;
+    setErrors: (errors: FormErrors) => void;
+    reset: (nextValues?: Partial<Values>) => void;
+    validate: () => Promise<FormErrors>;
+    validateField: (name: string) => Promise<string | undefined>;
+    submit: () => void;
+    getFieldState: (name: string) => FieldState;
+    getFieldProps: (name: string) => FieldInputProps;
+    handleBlur: (name: string) => void;
+    /** Move focus to the next / previous registered field (used by KeyboardToolbar). */
+    focusNext: () => void;
+    focusPrev: () => void;
+    /** Registers a focusable node so a failed submit can focus the first error. */
+    registerField: (name: string, node: FocusableNode | null) => void;
+}
+//# sourceMappingURL=types.d.ts.map

package/lib/typescript/module/form/useField.d.ts

@@ -0,0 +1,27 @@
+import type { FieldInputProps } from './types';
+/**
+ * Bind a single field by name. Returns everything an input needs; pick the
+ * handler your control uses:
+ *   const email = useField('email');
+ *   <Input value={email.value} onChangeText={email.onChangeText} onBlur={email.onBlur} error={email.error} />
+ *   <Select value={country.value} onChange={country.onChange} error={country.error} />
+ *   <Switch value={!!agree.value} onChange={agree.onChange} />
+ */
+export declare function useField<V = unknown>(name: string): FieldInputProps<V>;
+export interface FieldArrayApi<T = unknown> {
+    /** Current array value (empty array when unset). */
+    fields: T[];
+    length: number;
+    push: (item: T) => void;
+    remove: (index: number) => void;
+    insert: (index: number, item: T) => void;
+    move: (from: number, to: number) => void;
+    replace: (index: number, item: T) => void;
+}
+/**
+ * Manage a repeating list field (phone numbers, line items, etc.) by name.
+ * Each helper writes the whole array back through the form so validation and
+ * dirty-tracking stay correct.
+ */
+export declare function useFieldArray<T = unknown>(name: string): FieldArrayApi<T>;
+//# sourceMappingURL=useField.d.ts.map

package/lib/typescript/module/form/useForm.d.ts

@@ -0,0 +1,10 @@
+import type { FormApi, FormConfig, FormValues } from './types';
+/**
+ * Dependency-free form engine. Tracks values/errors/touched/dirty, runs
+ * synchronous and async validation (per-field rule maps or a form-level
+ * function), gates error display behind touched/submit, and on a failed submit
+ * focuses the first errored field. The returned object is rebuilt every render
+ * so `<Form>` consumers re-render on state changes.
+ */
+export declare function useForm<Values extends FormValues = FormValues>(config: FormConfig<Values>): FormApi<Values>;
+//# sourceMappingURL=useForm.d.ts.map

package/lib/typescript/module/hooks/index.d.ts

@@ -3,4 +3,7 @@ export type { UseToggleResult } from './useToggle';
 export { useDebounce } from './useDebounce';
 export { usePressAnimation } from './usePressAnimation';
 export type { UsePressAnimationOptions, UsePressAnimationResult } from './usePressAnimation';
+export { useReducedMotion } from './useReducedMotion';
+export { useControllableState } from './useControllableState';
+export type { UseControllableStateOptions } from './useControllableState';
 //# sourceMappingURL=index.d.ts.map

package/lib/typescript/module/hooks/useControllableState.d.ts

@@ -0,0 +1,17 @@
+export interface UseControllableStateOptions<T> {
+    /** Controlled value. When `undefined`, the hook manages state internally. */
+    value?: T;
+    /** Initial value used in uncontrolled mode. */
+    defaultValue: T;
+    /** Called on every change (both modes). */
+    onChange?: (value: T) => void;
+}
+/**
+ * Bridges controlled and uncontrolled usage for a value+onChange pair. When
+ * `value` is provided the component is controlled (the hook just forwards it
+ * and calls `onChange`); otherwise the hook owns the state, seeded from
+ * `defaultValue`. The controlled/uncontrolled decision is locked on first
+ * render so a component never flips modes mid-life.
+ */
+export declare function useControllableState<T>({ value, defaultValue, onChange }: UseControllableStateOptions<T>): [T, (next: T) => void];
+//# sourceMappingURL=useControllableState.d.ts.map

package/lib/typescript/module/hooks/useReducedMotion.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Tracks the OS "Reduce Motion" accessibility setting. The library's
+ * ThemeProvider uses this to collapse `theme.motion` (durations → 0, springs →
+ * near-instant) so animations don't trigger vestibular discomfort; consumers
+ * can also read it directly to swap an animated path for a static one.
+ */
+export declare const useReducedMotion: () => boolean;
+//# sourceMappingURL=useReducedMotion.d.ts.map

package/lib/typescript/module/index.d.ts

@@ -21,14 +21,16 @@ export { VersionCheck, useVersionCheck } from './versionCheck';
 export type { UpdateInfo, UpdateType, VersionData, VersionComparison, VersionCheckResult, VersionCheckType, ParsedVersion, Platform } from './versionCheck';
 export { ThemeProvider, useTheme, useThemeMode, setTheme, setColorMode, getColorMode, getTheme, resetTheme, subscribeTheme, mergeTheme, lightTheme, darkTheme } from './theme';
 export type { Theme, ThemeOverrides, ThemeProviderProps, IconRegistry, IconRenderer, ColorMode, ColorPalette, ColorSchemePreference, RadiusScale, ShadowDefinition, ShadowScale, SpacingScale, TypographyScale, MotionScale, DeepPartial } from './theme';
-export { useToggle, useDebounce, usePressAnimation } from './hooks';
-export type { UseToggleResult, UsePressAnimationOptions, UsePressAnimationResult } from './hooks';
+export { useToggle, useDebounce, usePressAnimation, useReducedMotion, useControllableState } from './hooks';
+export type { UseToggleResult, UsePressAnimationOptions, UsePressAnimationResult, UseControllableStateOptions } from './hooks';
 export { ScreenDimensions, Breakpoints, Responsive, isScreenSize, isTablet, Spacing, Padding, Margin, triggerHaptic, setHapticImplementation, shadowStyle, compressImage } from './utils';
 export type { BreakpointKey, SpacingToken, HapticType, CompressImageOptions } from './utils';
 export { formatDate, formatTime, formatDateTime, formatRelativeTime, formatPhone, normalizePhone, formatCurrency, formatNumber, formatPercent, formatCompactNumber, getInitials } from './formatters';
 export type { DateInput, DateStyle, TimeStyle, FormatCurrencyOptions } from './formatters';
 export { isNonEmpty, isEmail, isIndianMobile, isPhone, isUrl, isNumeric, isInteger, isAlphanumeric, isStrongPassword, isIndianPincode, isPan, isGstin, isAadhaar, isIfsc, isHexColor, isBetween, minLength, maxLength } from './validators';
 export type { PasswordRules } from './validators';
+export { useForm, useField, useFieldArray, Form, useFormContext, useOptionalFormContext, rules, getPath, setPath, deletePath } from './form';
+export type { FormApi, FormConfig, FormValues, FormErrors, FormTouched, FieldState, FieldInputProps, FocusableNode, ValidationRule, ValidationResult, FieldRules, ValidationSchema, FormValidateFn, ValidateOn, SubmitHelpers, FieldArrayApi } from './form';
 export { useNetworkStatus, getNetworkStatus, addNetworkStatusListener, NetworkStatusBanner } from './network';
 export type { NetworkStatus, NetworkConnectionType, NetworkStatusListener, NetworkStatusBannerProps } from './network';
 export { Permissions } from './permissions';

package/lib/typescript/module/theme/types.d.ts

@@ -39,6 +39,21 @@ export interface ColorPalette {
     warning: string;
     error: string;
     info: string;
+    /**
+     * Foreground (text/icon) colour to render ON a solid fill of each semantic
+     * tone. Solid Button / Badge / Chip / Banner backgrounds read these instead
+     * of assuming `text.inverse` (white) — white-on-pale (notably `warning`
+     * amber) fails contrast. Library defaults keep the historical white for
+     * primary/success/error/info, use dark ink for `warning`, and `text.primary`
+     * for the surface-like `secondary` tone. Override per-brand to match your
+     * palette's luminance.
+     */
+    onPrimary: string;
+    onSecondary: string;
+    onSuccess: string;
+    onWarning: string;
+    onError: string;
+    onInfo: string;
     text: {
         primary: string;
         secondary: string;
@@ -280,8 +295,6 @@ export interface DialogTokens {
     iconWrapperSize: number;
     iconWrapperBorderRadius: number;
     actionButtonMinHeight: number;
-    /** When true, fires a selection haptic on action-button press. Library default: false. */
-    actionHaptic?: boolean;
 }
 export interface ToastTokens {
     iconCircleSize: number;
@@ -322,43 +335,25 @@ export interface CheckboxSizeTokens {
 }
 export interface CheckboxTokens extends Partial<Record<ComponentSizeKey, CheckboxSizeTokens>> {
     labelGap?: number;
-    /** When true, fires a selection haptic on press by default. Library default: false. */
-    pressHaptic?: boolean;
-}
-export interface ChipTokens extends Partial<Record<ComponentSizeKey, ChipSizeTokens>> {
-    /** When true, fires a selection haptic when the chip itself is pressed. Library default: false. */
-    pressHaptic?: boolean;
-    /** When true, fires a selection haptic when the close (×) button is pressed. Library default: false. */
-    closeHaptic?: boolean;
-}
-export interface ListItemTokens extends Partial<Record<ComponentSizeKey, ListItemSizeTokens>> {
-    /** When true, fires a selection haptic on press. Library default: false. */
-    pressHaptic?: boolean;
 }
+export type ChipTokens = Partial<Record<ComponentSizeKey, ChipSizeTokens>>;
+export type ListItemTokens = Partial<Record<ComponentSizeKey, ListItemSizeTokens>>;
 export interface RadioSizeTokens {
     outer: number;
     inner: number;
 }
 export interface RadioTokens extends Partial<Record<ComponentSizeKey, RadioSizeTokens>> {
     labelGap?: number;
-    /** When true, fires a selection haptic on press by default. Library default: false. */
-    pressHaptic?: boolean;
 }
 export interface NumberInputTokens {
     /** Milliseconds before long-press auto-repeat kicks in. Library default: 500. */
     longPressDelayMs?: number;
     /** Milliseconds between auto-repeated step ticks while long-pressed. Library default: 80. */
     longPressIntervalMs?: number;
-    /** When true, fires a light impact haptic on every +/- press. Library default: false. */
-    pressHaptic?: boolean;
 }
 export interface OTPInputTokens extends Partial<Record<ComponentSizeKey, OTPInputSizeTokens>> {
     /** When true, the row shakes horizontally on first error transition. Library default: false. */
     shakeOnError?: boolean;
-    /** When true, fires an error haptic on first error transition. Library default: false. */
-    errorHaptic?: boolean;
-    /** When true, fires a selection haptic on each value change. Library default: false. */
-    selectionHaptic?: boolean;
 }
 export interface ProgressBarTokens {
     /** Duration in ms of the indeterminate-loop animation cycle. Library default: 1500. */
@@ -373,8 +368,6 @@ export interface RatingTokens {
     pulseOnPress?: boolean;
     /** Peak scale of the pulse animation. Library default: 1.2. */
     pulseScale?: number;
-    /** When true, fires a selection haptic on each rating change. Library default: false. */
-    pressHaptic?: boolean;
 }
 /**
  * Per-size dimensions for the unified field box (FieldBase). Every
@@ -515,8 +508,6 @@ export interface BottomNavigationTokens {
     underlineHeight?: number;
 }
 export interface DatePickerTokens {
-    /** Opt-in haptic feedback on month/year navigation and selection. Default: false. */
-    haptic?: boolean;
     /** Pixel offset for the month-slide animation. Default: 32. */
     monthSlideDistance?: number;
     /** Outgoing month-slide animation duration (ms). Default: theme.motion.duration.fast or 140. */
@@ -549,8 +540,6 @@ export interface DatePickerTokens {
     footerButtonMinHeight?: number;
 }
 export interface DateRangePickerTokens {
-    /** Opt-in haptic feedback on month navigation and selection. Default: false. */
-    haptic?: boolean;
     /** Pixel offset for the month-slide animation. Default: 32. */
     monthSlideDistance?: number;
     /** Outgoing month-slide animation duration (ms). Default: theme.motion.duration.fast or 140. */
@@ -567,8 +556,6 @@ export interface DateRangePickerTokens {
     footerButtonMinHeight?: number;
 }
 export interface TimePickerTokens {
-    /** Opt-in haptic feedback on wheel scroll and confirm/cancel. Default: false. */
-    haptic?: boolean;
     /** Debounce window between scroll-haptic ticks (ms). Default: 35. */
     hapticDebounceMs?: number;
     /** Width of the bottom-sheet drag handle. Default: 36. */
@@ -601,14 +588,10 @@ export interface AvatarTokens {
     fontWeight?: keyof TypographyScale['fontWeight'];
 }
 export interface AccordionTokens {
-    /** When true, fires a selection haptic on header press. Library default: false. */
-    pressHaptic?: boolean;
     /** Vertical padding inside the `card` variant container. Library default: 4. */
     cardPaddingVertical?: number;
 }
 export interface AppBarTokens {
-    /** When true, fires a selection haptic on action-button press. Library default: false. */
-    pressHaptic?: boolean;
     /** Min-width of the left/right side action slots. Library default: 48. */
     sideSlotMinWidth?: number;
     /** Translate-Y distance (px, negative) the large title travels when collapsing. Library default: -20. */
@@ -649,17 +632,11 @@ export interface BannerTokens {
     actionButtonPaddingVertical?: number;
     actionButtonRadius?: number;
 }
-export interface CardTokens {
-    /** When true, fires a selection haptic on interactive card press. Library default: false. */
-    pressHaptic?: boolean;
-}
 export interface DrawerTokens {
     /** Pixel velocity above which a fling closes the drawer. Library default: 1000. */
     closeVelocityThreshold?: number;
     /** Pixel drag distance before the gesture is recognised. Library default: 10. */
     dragActivationOffset?: number;
-    /** When true, fires a selection haptic on backdrop press. Library default: false. */
-    backdropPressHaptic?: boolean;
 }
 export interface FloatingActionButtonTokens {
     /** Horizontal inset from screen edge for bottomLeft/bottomRight positions. Library default: 24. */
@@ -670,8 +647,6 @@ export interface FloatingActionButtonTokens {
     secondaryGap?: number;
     /** Per-item stagger delay in ms when opening/closing the group. Library default: 50. */
     staggerMs?: number;
-    /** When true, fires impactLight on press / open / action. Library default: false. */
-    pressHaptic?: boolean;
 }
 export interface ImageGalleryTokens {
     /** Maximum pinch-zoom scale. Library default: 4. */
@@ -680,14 +655,10 @@ export interface ImageGalleryTokens {
     minScale?: number;
     /** Scale applied on double-tap at rest. Library default: 2. */
     doubleTapScale?: number;
-    /** When true, fires haptics on open/close/swipe/double-tap. Library default: false. */
-    pressHaptic?: boolean;
 }
 export interface ModalTokens {
     /** Initial scale value for the centred presentation enter animation. Library default: 0.9. */
     scaleStartValue?: number;
-    /** When true, fires a selection haptic on backdrop dismiss. Library default: false. */
-    backdropHaptic?: boolean;
 }
 export interface SegmentedControlSizeTokens {
     height?: number;
@@ -697,8 +668,6 @@ export interface SegmentedControlSizeTokens {
 export interface SegmentedControlTokens extends Partial<Record<'sm' | 'md', SegmentedControlSizeTokens>> {
     /** Padding between the track edge and the selected indicator. Library default: 2. */
     trackPadding?: number;
-    /** When true, fires a selection haptic on segment change. Library default: false. */
-    changeHaptic?: boolean;
 }
 export interface SliderSizeTokens {
     trackHeight?: number;
@@ -713,14 +682,6 @@ export interface SliderTokens extends Partial<Record<ComponentSizeKey, SliderSiz
     labelShowDuration?: number;
     /** Final opacity of the bubble label when visible. Library default: 1. */
     labelOpacity?: number;
-    /** When true, fires a selection haptic while dragging. Library default: false. */
-    dragHaptic?: boolean;
-    /** When true, fires a selection haptic each time the value crosses a step boundary. Library default: false. */
-    stepHaptic?: boolean;
-    /** When true, fires a selection haptic on track tap. Library default: false. */
-    tapHaptic?: boolean;
-    /** When true, fires a selection haptic on accessibility increment/decrement. Library default: false. */
-    a11yHaptic?: boolean;
 }
 export interface StepperTokens {
     /** Diameter of each step circle. Library default: 24. */
@@ -731,8 +692,6 @@ export interface StepperTokens {
     pulseDuration?: number;
     /** When true, the active step animates a continuous pulse ring. Library default: false. */
     pulseAnimation?: boolean;
-    /** When true, fires a selection haptic on step press. Library default: false. */
-    pressHaptic?: boolean;
 }
 export interface SwipeableTokens {
     /** Pixel distance after which a partial-swipe action commits on release. Library default: 64. */
@@ -751,12 +710,6 @@ export interface SwipeableTokens {
     springStiffness?: number;
     /** Spring mass for snap-back animation. */
     springMass?: number;
-    /** When true, fires a notification haptic on full-swipe commit. Library default: true. */
-    fullSwipeHaptic?: boolean;
-    /** When true, fires a selection haptic on action button press. Library default: true. */
-    actionPressHaptic?: boolean;
-    /** When true, fires a selection haptic on accessibility action. Library default: true. */
-    a11yActionHaptic?: boolean;
 }
 export interface TabsTokens {
     /** Horizontal padding of each tab. Library default: theme.spacing.lg. */
@@ -773,8 +726,6 @@ export interface TabsTokens {
     disabledOpacity?: number;
     /** Gap between label and inline badge. Library default: 6. */
     badgeGap?: number;
-    /** When true, fires a selection haptic on tab press. Library default: false. */
-    hapticOnPress?: boolean;
 }
 export interface TooltipTokens {
     /** Gap between trigger and tooltip card. Library default: 8. */
@@ -807,7 +758,6 @@ export interface ComponentTokens {
     badge?: BadgeTokens;
     bottomNavigation?: BottomNavigationTokens;
     bottomSheet?: BottomSheetTokens;
-    card?: CardTokens;
     checkbox?: CheckboxTokens;
     chip?: ChipTokens;
     datePicker?: DatePickerTokens;

package/lib/typescript/module/utils/hapticUtils.d.ts

@@ -1,4 +1,12 @@
 export type HapticType = 'selection' | 'impactLight' | 'impactMedium' | 'impactHeavy' | 'notificationSuccess' | 'notificationWarning' | 'notificationError';
 export declare const triggerHaptic: (type?: HapticType) => void;
 export declare const setHapticImplementation: (impl: ((type: HapticType) => void) | null) => void;
+/**
+ * Resolves a component's `haptic` prop to the type that should fire, or null
+ * when haptics are off. `false` disables; a `HapticType` overrides; `undefined`
+ * falls back to the component's sensible default. Pair with `triggerHaptic`:
+ *   const h = resolveHaptic(haptic, 'selection');
+ *   if (h) triggerHaptic(h);
+ */
+export declare const resolveHaptic: (haptic: HapticType | false | undefined, fallbackType: HapticType) => HapticType | null;
 //# sourceMappingURL=hapticUtils.d.ts.map

package/lib/typescript/module/utils/index.d.ts

@@ -2,7 +2,7 @@ export { ScreenDimensions, Breakpoints, Responsive, isScreenSize, isTablet } fro
 export type { BreakpointKey } from './responsive';
 export { Spacing, Padding, Margin } from './spacing';
 export type { SpacingToken } from './spacing';
-export { triggerHaptic, setHapticImplementation } from './hapticUtils';
+export { triggerHaptic, setHapticImplementation, resolveHaptic } from './hapticUtils';
 export type { HapticType } from './hapticUtils';
 export { shadowStyle } from './shadows';
 export { compressImage } from './imageCompression';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webority-technologies/mobile",
-  "version": "0.0.22",
+  "version": "0.0.24",
   "description": "Beautiful, animated, accessible React Native components plus API/auth/logging/network/storage utilities for Webority projects.",
   "keywords": [
     "react-native",