jattac.libs.web.zest-textbox 0.2.4 → 0.2.6

package/README.md

@@ -15,6 +15,7 @@ A delightful, feature-rich, and highly customizable React textbox component. Bui
   - [Password Input with Visibility Toggle](#password-input-with-visibility-toggle)
   - [Character Counter & Progress Bar](#character-counter--progress-bar)
   - [Enhanced Numeric Input](#enhanced-numeric-input)
+  - [Custom Parser & Validator](#custom-parser--validator)
   - [Sizing](#sizing)
   - [Theming (Light/Dark/System)](#theming-lightdarksystem)
   - [Multiline Textarea](#multiline-textarea)
@@ -35,6 +36,7 @@ A delightful, feature-rich, and highly customizable React textbox component. Bui
 *   **Password Visibility Toggle:** A crucial accessibility and usability feature for password fields.
 *   **Character Counter & Progress Bar:** Visual feedback on input length, with engaging animations as limits are approached.
 *   **Enhanced Numeric Input:** Intelligent filtering for numbers, decimals, and negative values.
+*   **Customizable Parsing & Validation:** Define how raw string input is converted to a desired type and validated, with context of the input `type`.
 *   **Engaging Animations:** Subtle, delightful micro-interactions on focus and input.
 *   **Accessible:** Built with `rem` units and best practices for inclusivity.
 *   **Centralized Configuration:** Easily manage default behaviors and styles across your application using React Context.
@@ -53,7 +55,7 @@ Get started with `ZestTextbox` in seconds. It behaves just like a standard HTML
 
 ```jsx
 import React from 'react';
-import { ZestTextbox } from 'jattac.libs.web.zest-textbox';
+import ZestTextbox from 'jattac.libs.web.zest-textbox';
 
 const App = () => {
   return (
@@ -76,37 +78,41 @@ export default App;
 | `zest`      | `ZestProps`                        | `undefined` | An object containing all custom configurations and behaviors specific to the ZestTextbox component. See `ZestProps` interface for details below. |
 | `className` | `string`                           | `""`        | A custom CSS class to apply to the main textbox element.                                                                                 |
 | `maxLength` | `number`                           | `undefined` | The maximum number of characters allowed. Enables the character counter and progress bar.                                                               |
-| `type`      | `string`                           | `'text'`    | The type of the input element. All standard HTML input types are supported. Special handling is applied for `password` and `number`.     |
+| `type`      | `HtmlInputType`                    | `'text'`    | The type of the input element. All standard HTML input types are supported. Special handling is applied for `password` and `number`.     |
 
 ### `ZestProps` Interface Details
 
 The `zest` prop is an object that encapsulates all the unique features of `ZestTextbox`. Its properties can accept primitive values, functions, or asynchronous functions (`ZestConfigValue<T>`) for dynamic configuration, especially useful with [Centralized Configuration](#centralized-configuration).
 
 ```typescript
-import { ZestTextboxSize, ZestConfigValue, HelperTextConfig } from 'jattac.libs.web.zest-textbox';
+import { ZestTextboxSize, ZestConfigValue, HelperTextConfig, InputParser, InputValidator, HtmlInputType } from 'jattac.libs.web.zest-textbox';
 
 interface ZestProps {
   helperTextConfig?: ZestConfigValue<HelperTextConfig>;
-  onTextChanged?: (value: string) => void; // Callback for text changes
+  onTextChanged?: <T>(value: T | undefined) => void; // Callback for parsed & validated text changes
   zSize?: ZestConfigValue<ZestTextboxSize>; // "sm" | "md" | "lg"
   stretch?: ZestConfigValue<boolean>; // Full width
   showProgressBar?: ZestConfigValue<boolean>; // Display character progress bar
   animatedCounter?: ZestConfigValue<boolean>; // Counter color changes
   theme?: ZestConfigValue<"light" | "dark" | "system">; // Color scheme
   isMultiline?: ZestConfigValue<boolean>; // Render as <textarea>
+  parser?: ZestConfigValue<InputParser<any>>; // Custom parser function
+  validator?: ZestConfigValue<InputValidator<any>>; // Custom validator function
 }
 ```
 
 | Property          | Type (`ZestConfigValue<T>`)                               | Default     | Description                                                                                                                              |
 | ----------------- | --------------------------------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
 | `helperTextConfig`| `ZestConfigValue<HelperTextConfig>`                       | `undefined` | Configuration for dynamic helper text displayed below the input. Can be an object, a function returning an object, or a promise of an object. |
-| `onTextChanged`   | `(value: string) => void`                                 | `undefined` | A callback function that is invoked whenever the textbox's value changes. Provides the raw string value.                                 |
+| `onTextChanged`   | `<T>(value: T | undefined) => void`                     | `undefined` | A callback function that is invoked whenever the textbox's value changes. Provides the *parsed and validated* value. `T` is the type returned by the `parser`.                                 |
 | `zSize`           | `ZestConfigValue<"sm" | "md" | "lg">`                   | `'md'`      | Sets the size of the textbox, affecting padding and font size.                                                                           |
 | `stretch`         | `ZestConfigValue<boolean>`                                | `false`     | If `true`, the component will stretch to the full width of its container.                                                                |
 | `showProgressBar` | `ZestConfigValue<boolean>`                                | `false`     | If `true`, a progress bar indicating character count vs. `maxLength` will be displayed. Requires `maxLength` to be set.                  |
 | `animatedCounter` | `ZestConfigValue<boolean>`                                | `false`     | If `true`, the character counter will change color as it approaches the `maxLength`. Requires `maxLength` to be set.                     |
 | `theme`           | `ZestConfigValue<"light" | "dark" | "system">`           | `'system'`  | Controls the component's color scheme. `'system'` automatically detects the OS/browser preference.                                       |
 | `isMultiline`     | `ZestConfigValue<boolean>`                                | `false`     | If `true`, the component will render as a `<textarea>`. If `false` or undefined, it renders as an `<input>`.                           |
+| `parser`          | `ZestConfigValue<InputParser<any>>`                       | `undefined` | A function to parse the raw string input into a desired type. Receives `(value: string, inputType?: HtmlInputType)`. Returns `undefined` if parsing fails. Default parsers are provided for `type="number"`. |
+| `validator`       | `ZestConfigValue<InputValidator<any>>`                    | `undefined` | A function to validate the parsed value. Receives `(value: T | undefined, inputType?: HtmlInputType)`. Returns `true` for valid, or a string error message for invalid. Default validators are provided for `type="number"`. |
 
 ## Feature Examples
 
@@ -118,7 +124,7 @@ Simply set the `type` prop to `"password"` to enable the built-in visibility tog
 
 ```jsx
 import React from 'react';
-import { ZestTextbox } from 'jattac.libs.web.zest-textbox';
+import ZestTextbox from 'jattac.libs.web.zest-textbox';
 
 const PasswordExample = () => {
   return (
@@ -138,7 +144,7 @@ Enable the character counter with `maxLength` and add a visual progress bar and
 
 ```jsx
 import React from 'react';
-import { ZestTextbox } from 'jattac.libs.web.zest-textbox';
+import ZestTextbox from 'jattac.libs.web.zest-textbox';
 
 const CounterExample = () => {
   const [text, setText] = React.useState('');
@@ -164,21 +170,33 @@ export default CounterExample;
 
 ### Enhanced Numeric Input
 
-Set `type="number"` for intelligent filtering that allows only digits, a single decimal point, and a single leading negative sign.
+Set `type="number"` for intelligent filtering that allows only digits, a single decimal point, and a single leading negative sign. The `onTextChanged` callback will now receive a `number | undefined`.
 
 ```jsx
 import React from 'react';
-import { ZestTextbox } from 'jattac.libs.web.zest-textbox';
+import ZestTextbox from 'jattac.libs.web.zest-textbox';
 
 const NumericExample = () => {
+  const [age, setAge] = React.useState<number | undefined>(undefined);
+  const [price, setPrice] = React.useState<number | undefined>(undefined);
+
   return (
     <div style={{ padding: '2rem', maxWidth: '400px', margin: '0 auto' }}>
-      <h2>Numeric Input</h2>
-      <ZestTextbox type="number" placeholder="Enter a number" />
-      <br /><br />
-      <ZestTextbox type="number" placeholder="Enter a decimal" defaultValue="3.14" />
+      <h2>Enhanced Numeric Input</h2>
+      <p>Age: {age === undefined ? 'N/A' : age}</p>
+      <ZestTextbox
+        type="number"
+        placeholder="Enter your age"
+        onTextChanged={setAge}
+      />
       <br /><br />
-      <ZestTextbox type="number" placeholder="Enter a negative number" defaultValue="-100" />
+      <p>Price: {price === undefined ? 'N/A' : `$${price.toFixed(2)}`}</p>
+      <ZestTextbox
+        type="number"
+        placeholder="Enter a price"
+        onTextChanged={setPrice}
+        defaultValue="19.99"
+      />
     </div>
   );
 };
@@ -186,13 +204,66 @@ const NumericExample = () => {
 export default NumericExample;
 ```
 
+### Custom Parser & Validator
+
+Define your own `parser` and `validator` functions to handle specific input requirements. The `inputType` is passed to these functions for context. Here, we'll create a custom parser and validator for a "positive integer" number input.
+
+```jsx
+import React from 'react';
+import ZestTextbox, { InputParser, InputValidator, HtmlInputType } from 'jattac.libs.web.zest-textbox';
+
+// Custom parser for positive integers
+const positiveIntegerParser: InputParser<number> = (value: string, inputType?: HtmlInputType) => {
+  if (inputType === 'number') {
+    const parsed = parseInt(value, 10);
+    return isNaN(parsed) ? undefined : parsed;
+  }
+  return undefined;
+};
+
+// Custom validator for positive integers
+const positiveIntegerValidator: InputValidator<number> = (parsedValue: number | undefined, inputType?: HtmlInputType) => {
+  if (inputType === 'number') {
+    if (parsedValue === undefined) {
+      return "Please enter a valid integer.";
+    }
+    if (parsedValue <= 0) {
+      return "Value must be a positive integer.";
+    }
+  }
+  return true;
+};
+
+const CustomNumericParserValidatorExample = () => {
+  const [quantity, setQuantity] = React.useState<number | undefined>(undefined);
+
+  return (
+    <div style={{ padding: '2rem', maxWidth: '400px', margin: '0 auto' }}>
+      <h2>Custom Numeric Parser & Validator</h2>
+      <p>Quantity: {quantity === undefined ? 'N/A' : quantity}</p>
+      <ZestTextbox
+        type="number"
+        placeholder="Enter positive quantity"
+        onTextChanged={setQuantity}
+        zest={{
+          parser: positiveIntegerParser,
+          validator: positiveIntegerValidator,
+        }}
+      />
+    </div>
+  );
+};
+
+export default CustomNumericParserValidatorExample;
+```
+
 ### Sizing
 
 Control the size of the textbox with the `zSize` property within the `zest` prop. Options are `"sm"`, `"md"` (default), and `"lg"`.
 
 ```jsx
 import React from 'react';
-import { ZestTextbox } from 'jattac.libs.web.zest-textbox';
+import ZestTextbox from 'jattac.libs.web.zest-textbox';
 
 const SizingExample = () => {
   return (
@@ -216,7 +287,7 @@ Force the component into a specific theme or let it adapt to the user's system p
 
 ```jsx
 import React from 'react';
-import { ZestTextbox } from 'jattac.libs.web.zest-textbox';
+import ZestTextbox from 'jattac.libs.web.zest-textbox';
 
 const ThemingExample = () => {
   return (
@@ -240,7 +311,7 @@ Render `ZestTextbox` as a `<textarea>` by setting `isMultiline` to `true` in the
 
 ```jsx
 import React from 'react';
-import { ZestTextbox } from 'jattac.libs.web.zest-textbox';
+import ZestTextbox from 'jattac.libs.web.zest-textbox';
 
 const MultilineExample = () => {
   return (
@@ -264,7 +335,7 @@ Provide dynamic helper text below the input using `helperTextConfig`. You can fo
 
 ```jsx
 import React from 'react';
-import { ZestTextbox } from 'jattac.libs.web.zest-textbox';
+import ZestTextbox from 'jattac.libs.web.zest-textbox';
 
 const HelperTextExample = () => {
   const [value, setValue] = React.useState('');
@@ -321,7 +392,7 @@ Make the textbox take up the full width of its parent container by setting `stre
 
 ```jsx
 import React from 'react';
-import { ZestTextbox } from 'jattac.libs.web.zest-textbox';
+import ZestTextbox from 'jattac.libs.web.zest-textbox';
 
 const StretchExample = () => {
   return (
@@ -346,11 +417,30 @@ To maintain consistency and reduce boilerplate, `ZestTextbox` supports centraliz
 
 ### Usage Example
 
-Here's how you can set up a global theme and size, and then override it for a specific component:
+Here's how you can set up a global theme and size, and then override it for a specific component. You can also define global default parsers and validators here.
 
 ```jsx
 import React from 'react';
-import { ZestTextbox, ZestTextboxConfigProvider } from 'jattac.libs.web.zest-textbox';
+import ZestTextbox, { ZestTextboxConfigProvider, InputParser, InputValidator, HtmlInputType } from 'jattac.libs.web.zest-textbox';
+
+// Global default parser for positive numbers
+const globalPositiveNumberParser: InputParser<number> = (value: string, inputType?: HtmlInputType) => {
+  if (inputType === 'number') {
+    const parsed = parseFloat(value);
+    return isNaN(parsed) || parsed <= 0 ? undefined : parsed;
+  }
+  return undefined;
+};
+
+// Global default validator for positive numbers
+const globalPositiveNumberValidator: InputValidator<number> = (parsedValue: number | undefined, inputType?: HtmlInputType) => {
+  if (inputType === 'number') {
+    if (parsedValue === undefined) {
+      return "Please enter a valid positive number.";
+    }
+  }
+  return true;
+};
 
 const AppWithCentralConfig = () => {
   // Define your global default ZestProps
@@ -358,15 +448,20 @@ const AppWithCentralConfig = () => {
     theme: "dark", // All textboxes will be dark by default
     zSize: () => "lg", // All textboxes will be large by default (function example)
     animatedCounter: Promise.resolve(true), // Async example
+    parser: globalPositiveNumberParser, // Apply global positive number parser
+    validator: globalPositiveNumberValidator, // Apply global positive number validator
   };
 
+  const [amount, setAmount] = React.useState<number | undefined>(undefined);
+
   return (
     <ZestTextboxConfigProvider value={globalDefaultZestProps}>
       <div style={{ padding: '2rem', maxWidth: '600px', margin: '0 auto' }}>
         <h1>Centralized Configuration Example</h1>
 
         <h3>Default ZestTextbox (inherits global defaults)</h3>
-        <ZestTextbox placeholder="I'm large, dark, and animated!" />
+        <ZestTextbox placeholder="I'm large, dark, animated, and expect positive numbers!" type="number" onTextChanged={setAmount} />
+        <p>Amount: {amount === undefined ? 'N/A' : amount}</p>
         <br /><br />
 
         <h3>Overridden ZestTextbox (component props take precedence)</h3>
@@ -377,7 +472,7 @@ const AppWithCentralConfig = () => {
         <br /><br />
 
         <h3>Another Default ZestTextbox</h3>
-        <ZestTextbox placeholder="I'm also large, dark, and animated!" />
+        <ZestTextbox placeholder="I'm also large, dark, animated, and expect positive numbers!" type="number" />
       </div>
     </ZestTextboxConfigProvider>
   );
@@ -399,10 +494,10 @@ The resolution order for `ZestProps` is as follows:
 The `ZestTextbox` component has been refactored internally for improved maintainability, readability, and reusability. Its core logic is now distributed across several custom React hooks and smaller, focused sub-components. This internal restructuring does **not** introduce any breaking changes to the public API.
 
 The internal structure now includes:
-*   `UI/hooks/`: Contains custom React hooks (e.g., `useThemeDetector`, `usePasswordVisibility`, `useCharacterCounter`, `useHelperText`, `useZestTextboxConfig`).
+*   `UI/hooks/`: Contains custom React hooks (e.g., `useThemeDetector`, `usePasswordVisibility`, `useCharacterCounter`, `useHelperText`, `useZestTextboxConfig`, `useParsedAndValidatedInput`).
 *   `UI/components/`: Contains smaller, focused UI components (e.g., `PasswordToggleButton`, `CharacterCounter`, `ProgressBar`, `HelperTextDisplay`).
-*   `UI/utils/`: Contains utility functions (e.g., `numericInputFilter`).
-*   `UI/types.ts`: Defines shared TypeScript interfaces and types.
+*   `UI/utils/`: Contains utility functions (e.g., `numericInputFilter`, `defaultParsersAndValidators`).
+*   `UI/types.ts`: Defines shared TypeScript interfaces and types (e.g., `HtmlInputType`, `InputParser`, `InputValidator`, `ZestConfigValue`, `ResolvedZestProps`).
 *   `UI/contexts/`: Contains React Contexts and Providers (e.g., `ZestTextboxConfigContext`, `ZestTextboxConfigProvider`).
 
 ## Breaking Changes

package/dist/contexts/ZestTextboxConfigContext.d.ts

@@ -1,12 +1,11 @@
 import React, { ReactNode } from "react";
 import { ZestProps } from "../types";
-interface ZestTextboxConfigContextType {
-    defaultZestProps: ZestProps;
-}
-interface ZestTextboxConfigProviderProps {
+interface ZestTextboxConfigProviderProps<T = string> {
     children: ReactNode;
-    value?: ZestProps;
+    value?: ZestProps<T>;
 }
-export declare const ZestTextboxConfigProvider: React.FC<ZestTextboxConfigProviderProps>;
-export declare const useZestTextboxConfig: () => ZestTextboxConfigContextType;
+export declare const ZestTextboxConfigProvider: React.FC<ZestTextboxConfigProviderProps<any>>;
+export declare const useZestTextboxConfig: <T = string>() => {
+    defaultZestProps: ZestProps<T>;
+};
 export {};

package/dist/hooks/useZestTextboxConfig.d.ts

@@ -1,2 +1,2 @@
 import { ZestProps, ResolvedZestProps, HtmlInputType } from "../types";
-export declare const useZestTextboxConfig: (componentZestProps: ZestProps | undefined, inputType?: HtmlInputType) => ResolvedZestProps;
+export declare const useZestTextboxConfig: <T = string>(componentZestProps: ZestProps<T> | undefined, inputType?: HtmlInputType) => ResolvedZestProps<T>;

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
 import React, { ReactNode } from 'react';
 
 type ZestTextboxSize = "sm" | "md" | "lg";
@@ -27,7 +28,7 @@ interface HelperTextConfig {
      */
     className?: string;
 }
-interface ZestProps {
+interface ZestProps<T = string> {
     /**
      * An object to configure the dynamic helper text displayed below the input.
      * @see HelperTextConfig
@@ -38,7 +39,7 @@ interface ZestProps {
      * This is a convenience prop to avoid using `event.target.value` and manual parsing/validation.
      * @param value The current parsed and validated value of the input, or `undefined` if parsing failed.
      */
-    onTextChanged?: <T>(value: T | undefined) => void;
+    onTextChanged?: (value: T | undefined) => void;
     /**
      * Sets the size of the textbox, affecting padding and font size.
      * @default 'md'
@@ -77,21 +78,20 @@ interface ZestProps {
      * A function to parse the raw string input into a desired type.
      * Returns `undefined` if parsing fails.
      */
-    parser?: ZestConfigValue<InputParser<any>>;
+    parser?: ZestConfigValue<InputParser<T>>;
     /**
      * A function to validate the parsed value.
      * Returns `true` for valid, or a string error message for invalid.
      */
-    validator?: ZestConfigValue<InputValidator<any>>;
+    validator?: ZestConfigValue<InputValidator<T>>;
 }
-
-type SharedProps = {
+type SharedProps<T> = {
     /**
      * An object containing all custom configurations and behaviors specific to the ZestTextbox component.
      * This encapsulates all non-native HTML input/textarea props for better discoverability and DX.
      * @see ZestProps
      */
-    zest?: ZestProps;
+    zest?: ZestProps<T>;
     /**
      * A custom CSS class to apply to the main textbox element.
      */
@@ -108,14 +108,17 @@ type SharedProps = {
      */
     type?: HtmlInputType;
 };
-type InputOnlyProps = SharedProps & Omit<React.InputHTMLAttributes<HTMLInputElement>, "size" | "onChange"> & {
+type InputOnlyProps<T> = SharedProps<T> & // Made InputOnlyProps generic
+Omit<React.InputHTMLAttributes<HTMLInputElement>, "size" | "onChange"> & {
     onChange?: React.ChangeEventHandler<HTMLInputElement>;
 };
-type TextareaOnlyProps = SharedProps & Omit<React.TextareaHTMLAttributes<HTMLTextAreaElement>, "onChange"> & {
+type TextareaOnlyProps<T> = SharedProps<T> & // Made TextareaOnlyProps generic
+Omit<React.TextareaHTMLAttributes<HTMLTextAreaElement>, "onChange"> & {
     onChange?: React.ChangeEventHandler<HTMLTextAreaElement>;
 };
-type ZestTextboxProps = InputOnlyProps | TextareaOnlyProps;
-declare const ZestTextbox: React.FC<ZestTextboxProps>;
+type ZestTextboxProps<T = string> = InputOnlyProps<T> | TextareaOnlyProps<T>;
+
+declare const ZestTextbox: <T = string>(props: ZestTextboxProps<T>) => react_jsx_runtime.JSX.Element;
 
 interface PasswordToggleButtonProps {
     isPassword: boolean;
@@ -146,11 +149,11 @@ interface HelperTextDisplayProps {
 }
 declare const HelperTextDisplay: React.FC<HelperTextDisplayProps>;
 
-interface ZestTextboxConfigProviderProps {
+interface ZestTextboxConfigProviderProps<T = string> {
     children: ReactNode;
-    value?: ZestProps;
+    value?: ZestProps<T>;
 }
-declare const ZestTextboxConfigProvider: React.FC<ZestTextboxConfigProviderProps>;
+declare const ZestTextboxConfigProvider: React.FC<ZestTextboxConfigProviderProps<any>>;
 
 export { CharacterCounter, HelperTextDisplay, PasswordToggleButton, ProgressBar, ZestTextbox, ZestTextboxConfigProvider };
 export type { HelperTextConfig, ZestProps, ZestTextboxSize };

package/dist/index.esm.js

@@ -247,9 +247,9 @@ var useZestTextboxConfig$1 = function () {
     if (context === undefined) {
         // This error will be caught by the useZestTextboxConfig hook in ZestTextbox.tsx
         // if the component is used outside of a provider.
-        return { defaultZestProps: {} };
+        return { defaultZestProps: {} }; // Cast to generic T
     }
-    return context;
+    return context; // Cast to generic T
 };
 
 var defaultNumberParser = function (value, inputType) {
@@ -311,21 +311,21 @@ var defaultResolvedZestProps = {
     validator: undefined,
 };
 var useZestTextboxConfig = function (componentZestProps, inputType) {
-    var contextDefaultZestProps = useZestTextboxConfig$1().defaultZestProps;
-    var _a = useState(defaultResolvedZestProps), resolvedZestProps = _a[0], setResolvedZestProps = _a[1];
+    var contextDefaultZestProps = useZestTextboxConfig$1().defaultZestProps; // Pass generic T
+    var _a = useState(defaultResolvedZestProps), resolvedZestProps = _a[0], setResolvedZestProps = _a[1]; // Cast to generic type
     // Memoize the merged props to avoid unnecessary re-renders
     var mergedZestProps = useMemo(function () {
         // Start with hardcoded defaults
-        var currentMergedProps = __assign({}, defaultResolvedZestProps);
+        var currentMergedProps = __assign({}, defaultResolvedZestProps); // Cast
         // Apply context defaults
-        currentMergedProps = __assign(__assign({}, currentMergedProps), contextDefaultZestProps);
+        currentMergedProps = __assign(__assign({}, currentMergedProps), contextDefaultZestProps); // No longer need cast here
         // Apply type-specific defaults if not already overridden by context
         if (inputType === "number") {
             if (currentMergedProps.parser === undefined) {
-                currentMergedProps.parser = defaultNumberParser;
+                currentMergedProps.parser = defaultNumberParser; // Cast
             }
             if (currentMergedProps.validator === undefined) {
-                currentMergedProps.validator = defaultNumberValidator;
+                currentMergedProps.validator = defaultNumberValidator; // Cast
             }
         }
         // Apply component-level props (highest precedence)