@t007/input 0.0.32 → 0.0.33

package/dist/index.d.ts

@@ -1,5 +1,73 @@
-import "@t007/utils";
-import { t007InputElement, BaseProps, CheckboxInputAddon, DateInputAddon, FileInputAddon, SelectElementAddon } from "../react";
+import React from 'react';
+
+/** Browser date-like input types supported by input field helpers. */
+declare const dateTypes = ["date", "time", "datetime-local", "month"] as const;
+
+/** Has native icon browser input types supported by input field helpers. */
+declare const nativeIconTypes = [...dateTypes];
+
+/** Union type for all input elements */
+type t007InputElement = HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement;
+
+/**  Define all possible `ValidityState` keys mapped to string messages */
+interface HelperTextMap extends Partial<Record<keyof ValidityState, string>> {
+  /** Informational helper text shown when there is no validation violation. */
+  info?: string;
+}
+
+interface BaseProps {
+  /** Wrap the field in its own container. */
+  isWrapper?: boolean;
+  /** Visible label text. */
+  label?: React.ReactNode;
+  /** Custom tokens for feature presets. */
+  custom?: "confirm_password" | "password" | "onward_date" | "past_date";
+  /** Class applied to the root field control. */
+  fieldClassName?: string;
+  /** Helper text shown under the field. */
+  helperText?: HelperTextMap | boolean;
+  /**  External resolver error text. When provided, the field is forced into error visuals even without native validity violations. */
+  error?: string;
+  /** Start icon rendered inside the field control. */
+  // startIcon?: React.ReactNode;
+  /** End icon rendered inside the field control. */
+  endIcon?: React.ReactNode;
+  // onFlagError?: (args: { violation: keyof ValidityState | null; helper: string }) => void;
+  /** Whether to activate bleeding edge CSS styles that augment native styles for input types, e.g. file, color, select, e.t.c */
+  bleedingEdge?: boolean;
+}
+interface FileInputAddon {
+  type: "file";
+  /** Maximum value length or count. */
+  maxSize?: number;
+  /** Minimum value length or count. */
+  minSize?: number;
+  /** Maximum total size allowed across the field value. */
+  maxTotalSize?: number;
+  /** Minimum total size allowed across the field value. */
+  minTotalSize?: number;
+}
+interface CheckboxInputAddon {
+  type: "checkbox";
+  /** Whether the checkbox is a multi-state checkbox. */
+  indeterminate?: boolean;
+}
+interface DateInputAddon {
+  type: DateType;
+  /** Native icon rendered by the browser control. */
+  nativeIcon?: React.ReactNode;
+}
+interface SelectElementAddon {
+  type: "select";
+  /** Options used by select-like fields. */
+  options?: string[] | readonly string[] | Array<{ value: string; option: string }>;
+}
+
+/** Union of all supported native date-like input types. */
+type DateType = (typeof dateTypes)[number];
+
+/** Union of all supported inputs with native icons types. */
+type NativeIconType = (typeof nativeIconTypes)[number];
 
 interface BaseOptions extends Omit<BaseProps, "error"> {
   /** Visible label text. */
@@ -8,20 +76,20 @@ interface BaseOptions extends Omit<BaseProps, "error"> {
   children?: HTMLElement;
 }
 type InputAttrs = Partial<Omit<HTMLInputElement, "type" | "children">>;
-type SelectAttrs = Partial<Omit<HTMLSelectElement, "type" | "children">>;
+type SelectAttrs = Partial<Omit<HTMLSelectElement, "type" | "children" | "options">>;
 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 GenericFieldOptions = BaseOptions & InputAttrs & { type?: Exclude<HTMLInputElement["type"], "password" | "file" | "checkbox" | DateType> };
 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;
+type FieldOptions = PasswordFieldOptions | FileFieldOptions | CheckboxFieldOptions | DateFieldOptions | GenericFieldOptions | TextareaFieldOptions | SelectFieldOptions;
 
 /** Form-level manager used to build and validate inputs. */
-export interface FormManager {
+interface FormManager {
   /** Live collection of managed forms. */
   forms: HTMLCollectionOf<HTMLFormElement>;
   /** Current validation violation keys. */
@@ -80,16 +148,16 @@ export interface FormManager {
 // BUNDLE EXPORTS & GLOBAL DECLARATIONS
 
 /** Shared field manager singleton exposed by the bundle. */
-export const formManager: FormManager;
+declare const formManager: FormManager;
 /** Create a field element from field options.
  * @param options Field configuration.
  * @returns Created field element.
  */
-export const field: FormManager["field"];
+declare const field: FormManager["field"];
 /** Attach validation hooks to a form element.
  * @param form Form element to validate.
  */
-export const handleFormValidation: FormManager["handleFormValidation"];
+declare const handleFormValidation: FormManager["handleFormValidation"];
 
 declare global {
   interface T007Namespace {
@@ -117,3 +185,5 @@ declare global {
     toggleGlobalError?(bool: boolean): void;
   }
 }
+
+export { type DateType, type FieldOptions, type FormManager, type NativeIconType, field, formManager, handleFormValidation };

package/dist/index.global.js

@@ -1,50 +1,40 @@
 "use strict";
 (() => {
-  // ../../../sia-reactor/dist/chunk-243U74PP.js
+  // ../../../sia-reactor/dist/chunk-ORK3EGB6.js
   function createEl(tag, props, dataset, styles, el = tag ? document?.createElement(tag) : null) {
     return assignEl(el, props, dataset, styles);
   }
-  function assignEl(el, props, dataset, styles) {
+  function assignEl(el, props, dataset, styles, nodiff = true) {
     if (!el) return null;
     if (props) {
-      for (const k of Object.keys(props)) if (props[k] !== void 0) el[k] = props[k];
+      for (const k of Object.keys(props)) if (props[k] !== void 0) {
+        if (nodiff || el[k] !== props[k]) el[k] = props[k];
+      }
     }
     if (dataset) {
-      for (const k of Object.keys(dataset)) if (dataset[k] !== void 0) el.dataset[k] = String(dataset[k]);
+      for (const k of Object.keys(dataset)) if (dataset[k] !== void 0) {
+        if (nodiff || el.dataset[k] !== dataset[k]) el.dataset[k] = String(dataset[k]);
+      }
     }
     if (styles) {
-      for (const k of Object.keys(styles)) if (styles[k] !== void 0) el.style[k] = styles[k];
+      for (const k of Object.keys(styles)) if (styles[k] !== void 0) {
+        if (nodiff || el.style[k] !== styles[k]) el.style[k] = styles[k];
+      }
     }
     return el;
   }
 
-  // ../../../sia-reactor/dist/chunk-2ZYYYSZ4.js
+  // ../../../sia-reactor/dist/chunk-SHWIAQD2.js
   var RTR_BATCH = "undefined" !== typeof window ? ("undefined" !== typeof queueMicrotask ? queueMicrotask : setTimeout).bind(window) : "undefined" !== typeof process && process.nextTick ? process.nextTick : setTimeout;
   var RTR_LOG = console.log.bind(console, "[S.I.A Reactor]");
   var NIL = Object.freeze({});
-  var CTX = {
-    /** Flag indicating whether the application is running in development mode. */
-    isDevEnv: "undefined" !== typeof process ? process.env.NODE_ENV !== "production" : true,
-    /** Flag indicating whether an operation is bypassing checks so reactors can allow all writes. */
-    usingForce: false,
-    /** Active `Autotracker` instance, override for automatic dependency collection on `Reactor` traps. */
-    autotracker: null,
-    /** Extensible meta context for payloads and cross-cutting concerns. */
-    meta: null,
-    /** Default configuration for new `Reactor` instances and also fallback for utils that need and are called without these options. */
-    defaults: {
-      crossRealms: false,
-      smartCloning: false,
-      eventBubbling: true,
-      eventCapturing: "auto",
-      lineageTracing: false,
-      preserveContext: false,
-      equalityFunction: Object.is,
-      batchingFunction: RTR_BATCH
-    }
-  };
+  var isDevEnv = false;
+  try {
+    isDevEnv = process.env.NODE_ENV !== "production";
+  } catch (e) {
+  }
 
-  // ../utils/dist/chunk-HGUYOV3P.js
+  // ../utils/dist/chunk-ZALPHCSJ.js
   var INTERACTIVE_SELECTOR = ":is(button,[href],input:not([type='hidden']),select,textarea,details>summary,[contenteditable],iframe,audio[controls],video[controls],[tabindex]):not([disabled],[tabindex='-1'],[data-focus-guard],[inert],[inert] *)";
   var VIRTUAL_RESOURCE = /* @__PURE__ */ Symbol.for("T007_VIRTUAL_RESOURCE");
   function loadResource(req, type = "style", { module, media, crossOrigin, integrity, referrerPolicy, nonce, fetchPriority, attempts = 3, retryKey = false } = {}, win = window) {

package/dist/react.d.ts

@@ -2,9 +2,113 @@ import React from 'react';
 
 /** Browser date-like input types supported by input field helpers. */
 declare const dateTypes: readonly ["date", "time", "datetime-local", "month"];
+
 /** Union of all supported native date-like input types. */
 type DateType = (typeof dateTypes)[number];
 
+interface BaseOptions extends Omit<BaseProps, "error"> {
+  /** Visible label text. */
+  label?: string;
+  /** Optional child element rendered inside the field wrapper. */
+  children?: HTMLElement;
+}
+type InputAttrs = Partial<Omit<HTMLInputElement, "type" | "children">>;
+type SelectAttrs = Partial<Omit<HTMLSelectElement, "type" | "children" | "options">>;
+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" | DateType> };
+type TextareaFieldOptions = BaseOptions & TextareaAttrs & { type: "textarea" };
+type SelectFieldOptions = BaseOptions & SelectAttrs & SelectElementAddon;
+/** Configuration accepted by the field() helper. */
+type FieldOptions = PasswordFieldOptions | FileFieldOptions | CheckboxFieldOptions | DateFieldOptions | GenericFieldOptions | TextareaFieldOptions | SelectFieldOptions;
+
+/** Form-level manager used to build and validate inputs. */
+interface FormManager {
+  /** Live collection of managed forms. */
+  forms: HTMLCollectionOf<HTMLFormElement>;
+  /** Current validation violation keys. */
+  violationKeys: string[];
+  /** Initialize DOM observers and field bindings. */
+  init(): void;
+  /** Observe the DOM for field changes. */
+  observeDOMForFields(): void;
+  /** Normalize and validate uploaded files.
+   * @param files Files selected by the user.
+   * @param opts Validation options.
+   * @returns Violation information and user-facing message.
+   */
+  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.
+   * @param base Size base, usually 1000 or 1024.
+   * @returns Human-readable size string.
+   */
+  formatSize(size: number, decimals?: number, base?: number): string;
+  /** Toggle an input between password and text mode.
+   * @param input Target password input.
+   */
+  togglePasswordType(input: HTMLInputElement): void;
+  /** Toggle the filled state on a supported field.
+   * @param input Supported form control.
+   */
+  toggleFilled(input: t007InputElement): void;
+  /** Attach a fallback helper node.
+   * @param field Field wrapper element.
+   */
+  setFallbackHelper(field: HTMLDivElement): void;
+  /** Wire listeners onto a managed field.
+   * @param field Field wrapper element.
+   */
+  setFieldListeners(field: HTMLDivElement): void;
+  /** Normalize field markup before use.
+   * @param field Field wrapper element.
+   */
+  setUpField(field: HTMLDivElement): void;
+  /** Create a field element from options.
+   * @param options Field configuration.
+   * @returns Created field element.
+   */
+  field(options: SelectFieldOptions): HTMLDivElement & { inputEl: HTMLSelectElement };
+  field(options: TextareaFieldOptions): HTMLDivElement & { inputEl: HTMLTextAreaElement };
+  field(options: PasswordFieldOptions | FileFieldOptions | CheckboxFieldOptions | DateFieldOptions | GenericFieldOptions): HTMLDivElement & { inputEl: HTMLInputElement };
+  field(options: FieldOptions): HTMLDivElement & { inputEl: t007InputElement };
+  /** Validate a form and attach the proper hooks.
+   * @param form Form element to validate.
+   */
+  handleFormValidation(form: HTMLFormElement): void;
+}
+
+declare global {
+  interface T007Namespace {
+    /** Form manager singleton attached by the bundle. */
+    FM: FormManager;
+    /** Public form manager singleton. */
+    formManager: FormManager;
+    /** Public field factory. */
+    field: FormManager["field"];
+    /** Public form validation helper. */
+    handleFormValidation: FormManager["handleFormValidation"];
+  }
+  interface Window {
+    field?: T007Namespace["field"];
+    handleFormValidation?: T007Namespace["handleFormValidation"];
+  }
+  interface HTMLFormElement {
+    /** 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;
+    /** Vanilla-only Check validation on the server. Assign custom server-side validation logic. */
+    validateOnServer?(): Promise<boolean>;
+    /** Vanilla-only Toggle the global error state. Reference to internals for manual use. */
+    toggleGlobalError?(bool: boolean): void;
+  }
+}
+
 /** React change event alias used by input helpers. */
 type CE<T> = React.ChangeEvent<T>;
 /** React input event alias used by input helpers. */
@@ -138,4 +242,4 @@ declare function useFormManager(onSubmit?: (e: React.FormEvent<HTMLFormElement>)
     fireInput: (el?: t007InputElement | null) => boolean | undefined;
 };
 
-export { type BaseProps, type CE, type CEH, type HelperTextMap, type IE, type IEH, Input, type InputProps, WordsInput, type WordsInputBaseProps, type WordsInputLenientModeProps, type WordsInputProps, type WordsInputStrictModeProps, type t007InputElement, useFormManager };
+export { type BaseProps, type CE, type CEH, type CheckboxInputAddon, type CheckboxInputProps, type DateInputAddon, type DateInputProps, type FileInputAddon, type FileInputProps, type GenericInputProps, type HelperTextMap, type IE, type IEH, Input, type InputAttributes, type InputProps, type PasswordInputAddon, type PasswordInputProps, type SelectAttributes, type SelectElementAddon, type SelectElementProps, type TextareaAttributes, type TextareaElementProps, WordsInput, type WordsInputBaseProps, type WordsInputLenientModeProps, type WordsInputProps, type WordsInputStrictModeProps, type t007InputElement, useFormManager };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@t007/input",
-  "version": "0.0.32",
+  "version": "0.0.33",
   "description": "A lightweight, pure JS input system.",
   "author": "Oketade Oluwatobiloba <tobioketade007@gmail.com>",
   "license": "MIT",
@@ -69,7 +69,7 @@
     "react-dom": "^18.3.1"
   },
   "dependencies": {
-    "@t007/utils": "^0.0.34"
+    "@t007/utils": "^0.0.35"
   },
   "peerDependencies": {
     "react": "^18.0.0"