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

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jattac.libs.web.zest-textbox",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "description": "A delightful, feature-rich, and highly customizable React textbox component. Packed with features like automatic theme detection, password visibility toggle, character counters, and engaging animations.",
   "main": "dist/index.js",
   "module": "dist/index.esm.js",