@t007/input 0.0.23 → 0.0.24

package/README.md

@@ -65,6 +65,13 @@ Beautiful floating labels with native error state handling.
 - **Horizontal Scroll Assist**: Built-in helper for long error messages overflowing the container.
 - **Tree-Shakeable**: Import only the utilities you need.
 
+### Vanilla Perks & Hooks
+
+- **`form.onSubmit`**: Optional callback on a form that runs instead of `form.submit()` when provided, allowing custom JS submission flows.
+- **`form.validateOnServer`**: Async hook; if defined the form will await its result before proceeding. Returning `false` prevents submission and shows a global error.
+- **`form.validateOnClient`**: Reference to the internal client-side validation function, allowing you to trigger validation manually or integrate it into custom UI flows.
+- **`form.toggleGlobalError(bool)`**: Programmatic API to display a form-level error state and shake all fields, used internally if `form.validateOnServer` returns false.
+
 ---
 
 ## Tech Stack
@@ -122,6 +129,25 @@ myForm.appendChild(emailInput);
 handleFormValidation(myForm);
 ```
 
+### React
+
+```tsx
+import { Input, WordsInput, useFormManager } from "@t007/input/react";
+
+export function SignupForm() {
+  const formRef = useRef<HTMLFormElement>(null); // use in a non-form setup or for manual `validate` triggers
+  const { handleSubmit, validate, fireInput } = useFormManager((e) => console.log("submitted"), formRef); // first in line to replace browser behaviour effectively
+
+  return (
+    <form noValidate className="t007-input-form" onSubmit={handleSubmit} ref={formRef}>
+      <Input type="email" label="Email" required helperText={{ typeMismatch: "Enter a valid email." }} />
+      <WordsInput type="textarea" label="Bio" maxCount={120} />
+      <button type="submit">Submit</button>
+    </form>
+  );
+}
+```
+
 ### CDN / Browser (Global)
 
 When loaded via a `<script>` tag, the library automatically scans the DOM for forms with the class `.t007-input-form` and initializes them.
@@ -190,7 +216,7 @@ The core object injected into the global namespace containing utility functions
 
 ### File Validation
 
-The library extends native file inputs with custom attributes for strict size enforcement:
+The library extends native file inputs with custom attributes for strict size enforcement, and the same validation logic is available directly through `t007.FM.getFilesHelper(files, opts)`:
 
 ```javascript
 const fileUploader = field({
@@ -204,6 +230,23 @@ const fileUploader = field({
 });
 ```
 
+To use the helper directly, map the same fields into `getFilesHelper` and feed the returned message into your own resolver or `helperText` path:
+
+```javascript
+const { violation, message } = t007.FM.getFilesHelper(input.files, {
+  accept: input.accept, // -> typeMismatch
+  multiple: input.multiple, // respects file count limits
+  maxSize: input.maxSize, // -> rangeOverflow
+  minSize: input.minSize, // -> rangeUnderflow
+  maxTotalSize: input.maxTotalSize, // -> rangeOverflow
+  minTotalSize: input.minTotalSize, // -> rangeUnderflow
+  maxLength: input.maxLength, // -> tooLong
+  minLength: input.minLength, // -> tooShort
+});
+
+if (message) input.setCustomValidity(message);
+```
+
 ### Password Management
 
 Setting an input's custom attribute to `password` or `confirm_password` automatically links their validation states.
@@ -216,13 +259,15 @@ field({ type: 'password', custom: 'password', label: 'Password' });
 field({ type: 'password', custom: 'confirm_password', label: 'Confirm Password' });
 ```
 
+There's other custom features like `onward_date`, `past_date`.
+
 -----
 
 ## Customization
 
 You can deeply customize the look and feel by overriding the built-in CSS variables or targeting the specific classes.
 
-### Important Selectors
+### CSS Selectors & Variables
 
   - `.t007-input`: The actual `<input>` element.
   - `.t007-input-floating-label`: The label text.
@@ -230,6 +275,23 @@ You can deeply customize the look and feel by overriding the built-in CSS variab
   - `[data-error]`: Attribute added dynamically on validation failure.
   - `.t007-input-password-strength-meter`: The container for the 4 strength bars.
 
+#### Override Starter
+
+```css
+.t007-input-field {
+  --t007-input-color: var(--app-theme-color);
+  /* ...check source code for all variables... */
+}
+```
+
+#### Specificity Note
+
+- Start with `:root` for shared input tokens.
+- If a token does not apply, override directly on `.t007-input-field`.
+- For precise control, target element selectors like `.t007-input`, `.t007-input-floating-label`, and `.t007-input-outline`.
+- For strong app themes (e.g. `html[data-theme="dark"]`), use equal/stronger selectors like `html[data-theme="dark"] .t007-input-field`.
+- Check source code for more details.
+
 -----
 
 ## Author

package/dist/index.css

@@ -5,7 +5,7 @@
   --t007-input-width: 100%;
   --t007-input-height: 3rem;
   --t007-input-font-size: 1rem;
-  --t007-input-floating-label-scale: 0.75;
+  --t007-input-floating-label-scale: 0.85;
   --t007-input-border-width: 1px;
   --t007-input-focused-border-width: 2px;
   --t007-input-border-style: solid;
@@ -58,9 +58,9 @@
   --t007-input-icon-stroke: unset;
   --t007-input-padding: calc(var(--t007-input-height) / 4);
   --t007-input-floating-label-font-size: calc(var(--t007-input-font-size) * var(--t007-input-floating-label-scale));
-  --t007-input-helper-font-size: calc(var(--t007-input-font-size) * 0.7);
+  --t007-input-helper-font-size: calc(var(--t007-input-font-size) * var(--t007-input-floating-label-scale));
   --t007-input-border-radius: calc(var(--t007-input-height) / 12);
-  --t007-input-p-meter-font-size: calc(var(--t007-input-font-size) * 0.75);
+  --t007-input-p-meter-font-size: calc(var(--t007-input-font-size) * var(--t007-input-floating-label-scale));
   --t007-input-p-meter-gap: calc(var(--t007-input-font-size) * 0.25);
   --t007-input-p-meter-height: calc(var(--t007-input-font-size) * 0.25);
   --t007-input-checkbox-font-size: calc(var(--t007-input-font-size) * 0.9);
@@ -275,7 +275,9 @@
 .t007-input-floating-label {
   position: relative;
   top: calc(var(--t007-input-height) / 2);
-  display: block;
+  display: flex;
+  align-items: center;
+  gap: calc(var(--t007-input-font-size) / 3);
   max-width: 100%;
   transform: translateY(-50%);
   color: var(--t007-input-current-label-color);

package/dist/index.d.ts

@@ -1,52 +1,24 @@
 import "@t007/utils";
+import { BaseProps, CheckboxInputAddon, DateInputAddon, FileInputAddon, SelectElementAddon } from "../react";
 
-/** Configuration accepted by the field() helper. */
-export interface FieldOptions extends Partial<
-  Omit<HTMLInputElement, "type" | "className" | "children">
-> {
-  /** Wrap the field in its own container. */
-  isWrapper?: boolean;
+interface BaseOptions extends Omit<BaseProps, "error"> {
   /** Visible label text. */
   label?: string;
-  /** Input type to render. */
-  type?: string;
-  /** Placeholder text. */
-  placeholder?: string;
-  /** Custom CSS class or class list. */
-  custom?: string;
-  /** Minimum value length or count. */
-  minSize?: number;
-  /** Maximum value length or count. */
-  maxSize?: number;
-  /** Minimum total size allowed across the field value. */
-  minTotalSize?: number;
-  /** Maximum total size allowed across the field value. */
-  maxTotalSize?: number;
-  /** Options used by select-like fields. */
-  options?: Array<string | { value: string; option: string }>;
-  /** Whether the checkbox is partially selected. */
-  indeterminate?: boolean;
-  /** Show the password visibility toggler. */
-  eyeToggler?: boolean;
-  /** Enable the password strength meter. */
-  passwordMeter?: boolean;
-  /** Helper text shown under the field. */
-  helperText?: false | Record<string, string>;
-  /** Class applied to the root field element. */
-  className?: string;
-  /** Class applied to the inner field control. */
-  fieldClassName?: string;
   /** Optional child element rendered inside the field wrapper. */
   children?: HTMLElement;
-  /** End icon rendered inside the field control. */
-  endIcon?: string;
-  /** Native icon rendered by the browser control. */
-  nativeIcon?: string;
-  /** Icon shown when the password is visible. */
-  passwordVisibleIcon?: string;
-  /** Icon shown when the password is hidden. */
-  passwordHiddenIcon?: string;
 }
+type InputAttrs = Partial<Omit<HTMLInputElement, "type" | "children">>;
+type SelectAttrs = Partial<Omit<HTMLSelectElement, "type" | "children">>;
+type TextareaAttrs = Partial<Omit<HTMLTextAreaElement, "type" | "children">>;
+type PasswordFieldOptions = BaseOptions & InputAttrs & Omit<FileInputAddon, "passwordVisibleIcon" | "passwordHiddenIcon"> & { passwordVisibleIcon?: HTMLElement; passwordHiddenIcon?: HTMLElement };
+type FileFieldOptions = BaseOptions & InputAttrs & FileInputAddon;
+type CheckboxFieldOptions = BaseOptions & InputAttrs & CheckboxInputAddon;
+type DateFieldOptions = BaseOptions & InputAttrs & DateInputAddon;
+type GenericFieldOptions = BaseOptions & InputAttrs & { type?: Exclude<HTMLInputElement["type"], "password" | "file" | "checkbox" | NativeType> };
+type TextareaFieldOptions = BaseOptions & TextareaAttrs & { type: "textarea" };
+type SelectFieldOptions = BaseOptions & SelectAttrs & SelectElementAddon;
+/** Configuration accepted by the field() helper. */
+export type FieldOptions = PasswordFieldOptions | FileFieldOptions | CheckboxFieldOptions | DateFieldOptions | GenericFieldOptions | TextareaFieldOptions | SelectFieldOptions;
 
 /** Form-level manager used to build and validate inputs. */
 export interface FormManager {
@@ -63,10 +35,7 @@ export interface FormManager {
    * @param opts Validation options.
    * @returns Violation information and user-facing message.
    */
-  getFilesHelper(
-    files: FileList | File[],
-    opts: any,
-  ): { violation: string | null; message: string };
+  getFilesHelper(files: FileList | File[], opts: any): { violation: string | null; message: string };
   /** Format a file size for display.
    * @param size Size in bytes.
    * @param decimals Decimal precision.
@@ -135,13 +104,13 @@ declare global {
     handleFormValidation?: T007Namespace["handleFormValidation"];
   }
   interface HTMLFormElement {
-    /** Client-side submit hook. */
-    onSubmit?(): void;
-    /** Check validation on the client. */
+    /** Vanilla-only Client-side submit hook. Use instead of `onsubmit` to escape browser behavior. */
+    onSubmit?(e: Event): void;
+    /** Vanilla-only Check validation on the client. Reference to internals for manual use. */
     validateOnClient?(): boolean;
-    /** Check validation on the server. */
+    /** Vanilla-only Check validation on the server. Assign custom server-side validation logic. */
     validateOnServer?(): Promise<boolean>;
-    /** Toggle the global error state. */
+    /** Vanilla-only Toggle the global error state. Reference to internals for manual use. */
     toggleGlobalError?(bool: boolean): void;
   }
 }