@arctura/atomics 0.0.1

package/dist/src/form/Form.d.ts

@@ -0,0 +1,168 @@
+import type { FC, FormHTMLAttributes, JSX, ReactNode, Ref, SubmitEvent } from 'react';
+import type { IconDefinition } from '@fortawesome/free-solid-svg-icons';
+/**
+ * A form adornment can be either a FontAwesome `IconDefinition` or an image descriptor.
+ * - When an `IconDefinition` is passed, the component renders a FontAwesome icon.
+ * - When an object is passed it should provide a `src` (image `src`) and optional `alt` text.
+ */
+type FormAdornment = IconDefinition | {
+    src: string;
+    alt?: string;
+};
+/**
+ * Theme color options accepted by the form for adornments and text.
+ *
+ * - 'accent' | 'primary' | 'secondary' | 'subtle' map to theme token names.
+ * - 'black' | 'white' | 'inverse' are additional semantic colors used by the UI.
+ */
+type FormColor = 'accent' | 'black' | 'inverse' | 'primary' | 'secondary' | 'subtle' | 'white';
+/**
+ * Class names for the disclaimer sub-elements.
+ */
+interface DisclaimerClasses {
+    /** Classes applied to the disclaimer adornment (icon or image). */
+    adornment?: string;
+    /** Classes applied to the disclaimer container wrapper. */
+    container?: string;
+    /** Classes applied to the disclaimer text element. */
+    text?: string;
+}
+/**
+ * Top-level class overrides for the `Form` component parts.
+ *
+ * Each property is optional and, when provided, will be merged with the
+ * component's internal class names.
+ */
+interface FormClasses {
+    /** Classes applied to the header/start adornment. */
+    adornment?: string;
+    /** Classes applied to the main body wrapper containing form children. */
+    body?: string;
+    /** Classes for the disclaimer sub-elements. */
+    disclaimer?: DisclaimerClasses;
+    /** Classes applied to the form header. */
+    header?: string;
+    /** Classes applied to the form footer. */
+    footer?: string;
+    /** Classes applied to the wrapper that contains the footer action buttons. */
+    footerButtonsContainer?: string;
+    /** Classes applied to the root `<form>` element. */
+    form?: string;
+    /** Classes applied to the submit button container. */
+    submitButton?: string;
+}
+/**
+ * Descriptor for the optional disclaimer shown in the form footer.
+ *
+ * - `adornment`: optional `FormAdornment` to display beside the text.
+ * - `text`: the disclaimer string to render.
+ */
+type FormDisclaimer = {
+    adornment?: FormAdornment;
+    text?: string;
+};
+/**
+ * Props accepted by the `Form` component.
+ *
+ * Extends native `FormHTMLAttributes<HTMLFormElement>` (excluding
+ * `className`) and exposes additional configuration used by the component
+ * such as adornments, color tokens, class overrides, and an optional
+ * disclaimer rendered in the footer.
+ */
+interface FormProps extends Omit<FormHTMLAttributes<HTMLFormElement>, 'className' | 'onChange' | 'onSubmit'> {
+    /** Accessible label for the form (maps to `aria-label`). */
+    'aria-label'?: string;
+    /** ID of an element that labels the form (maps to `aria-labelledby`). */
+    'aria-labelledby'?: string;
+    /** Native HTML `action` attribute (submission URL). */
+    action?: JSX.IntrinsicElements['form']['action'];
+    /** Color used for adornments and accents inside the form (maps to theme tokens). */
+    adornmentColor?: FormColor;
+    /** Child nodes to render inside the form (inputs, buttons, etc.). */
+    children?: ReactNode;
+    /** Additional CSS classes to apply to the form container. */
+    classes?: FormClasses;
+    /** Color used for text elements in the form and disclaimer (maps to theme tokens). */
+    color?: FormColor;
+    /** Optional disclaimer shown in the form footer; includes an optional adornment and text. */
+    disclaimer?: FormDisclaimer;
+    /** Encoding type for the form, e.g. `multipart/form-data` for file uploads. */
+    encType?: JSX.IntrinsicElements['form']['encType'];
+    /** Optional adornment to render at the end of the form header (icon or image). */
+    endAdornment?: FormAdornment;
+    /** Controlled error state for the form, derived from child field validation. */
+    error?: boolean;
+    /** `id` attribute for the form element. */
+    id?: string;
+    /** HTTP method used when submitting the form (`get` | `post`). */
+    method?: JSX.IntrinsicElements['form']['method'];
+    /** `name` attribute for the form. */
+    name?: string;
+    /** When true, disables the browser's native validation (`noValidate`). */
+    noValidate?: boolean;
+    /** Change event handler for the form element. */
+    onChange?: (values: FormValue[], error: boolean) => void;
+    /** Reset event handler for the form element. */
+    onReset?: (event: SubmitEvent<HTMLFormElement>) => void;
+    /** Submit event handler for the form element. */
+    onSubmit?: (event: SubmitEvent<HTMLFormElement>, values?: FormValue[], error?: boolean) => void;
+    /** Ref to access the underlying HTML form element. */
+    ref?: Ref<HTMLFormElement>;
+    /** Optional adornment to render at the start of the form header (icon or image). */
+    startAdornment?: FormAdornment;
+    /** Optional title displayed next to adornments in the form header. */
+    title?: string;
+    /** Initial values for form fields, used to populate internal state. */
+    value?: FormValue[];
+}
+/**
+ * Internal representation of a form field's value used for mapping children
+ * into a predictable, typed state structure.
+ *
+ * - `key`: unique identifier generated for the field when mapping children.
+ * - `type`: discriminant for the field component type (`TextInput` or `TextArea`).
+ * - `value`: current string value for the field.
+ * - `error`: optional boolean flag indicating the field has a validation error.
+ */
+interface FormValue {
+    /** Whether the field currently has a validation error. */
+    error?: boolean;
+    /** Unique key generated when mapping children into form state. */
+    key?: string;
+    /** Component type of the field (`TextInput` or `TextArea`). */
+    type?: 'TextInput' | 'TextArea';
+    /** Current string value for the field. */
+    value?: string;
+}
+/**
+ * Form component - a wrapper around the native HTML `<form>` element.
+ *
+ * Renders optional `startAdornment` and `endAdornment` (icons or images) with
+ * an optional `title`, then renders `children` which should contain form
+ * controls. All standard HTML form attributes are forwarded via `...rest`.
+ *
+ * @param {FormProps} props - Configuration props for the form component.
+ * @returns {JSX.Element} The rendered form element.
+ * @example
+ * ```tsx
+ * import { Form, Button } from '@/src';
+ * import { faPaperPlane } from '@fortawesome/free-solid-svg-icons';
+ *
+ * const MyForm = () => (
+ *  <Form
+ *    action="/submit"
+ *    method="post"
+ *    title="Contact Us"
+ *    startAdornment={faPaperPlane}
+ *  >
+ *    <input type="text" name="name" placeholder="Your Name" required />
+ *    <input type="email" name="email" placeholder="Your Email" required />
+ *    <Button type="submit">Send</Button>
+ *  </Form>
+ * );
+ * ```
+ */
+declare const Form: FC<FormProps>;
+export { Form };
+export type { FormValue };
+//# sourceMappingURL=Form.d.ts.map

package/dist/src/form/Form.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Form.d.ts","sourceRoot":"","sources":["../../../src/form/Form.tsx"],"names":[],"mappings":"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"}

package/dist/src/form/TextArea.d.ts

@@ -0,0 +1,266 @@
+import type { ChangeEvent, FC, FocusEvent, InputEvent, KeyboardEvent, MouseEvent, ReactNode, TextareaHTMLAttributes } from 'react';
+import type { IconDefinition } from '@fortawesome/free-solid-svg-icons';
+/**
+ * An adornment that can be rendered inside the `TextArea`.
+ * It can be:
+ * - custom React `children` (e.g. text or elements),
+ * - an image specified by `src`/`alt`,
+ * - or an icon (FontAwesome `IconDefinition`).
+ * Each variant may include an optional `onClick` handler.
+ */
+type TextAreaAdornment = {
+    children: ReactNode;
+    onClick?: (event: MouseEvent) => void;
+} | {
+    alt?: string;
+    src: string;
+    onClick?: (event: MouseEvent) => void;
+} | {
+    icon: IconDefinition;
+    onClick?: (event: MouseEvent) => void;
+};
+/**
+ * Colors available for adornments and label text.
+ *
+ * Allowed values:
+ * - 'accent': Accent color from the theme.
+ * - 'black': Standard black color.
+ * - 'inverse': Inverted color for dark backgrounds.
+ * - 'primary': Primary theme color.
+ * - 'secondary': Secondary theme color.
+ * - 'subtle': Subtle color for less emphasis.
+ * - 'white': White color for dark backgrounds.
+ * Note: 'inverse' and 'white' are intended for use on dark backgrounds, while 'accent', 'black', 'primary', 'secondary', and 'subtle' are for light backgrounds.
+ */
+type TextAreaAdornmentColor = 'accent' | 'black' | 'inverse' | 'primary' | 'secondary' | 'subtle' | 'white';
+/**
+ * Text color variants for the textarea content.
+ *
+ * Allowed values:
+ * - 'black': Standard black text.
+ * - 'inverse': Inverted color for dark backgrounds.
+ * - 'primary': Primary theme color.
+ * - 'white': White text for dark backgrounds.
+ * Note: 'inverse' and 'white' are intended for use on dark backgrounds, while 'black' and 'primary' are for light backgrounds.
+ */
+type TextAreaColor = 'black' | 'inverse' | 'primary' | 'white';
+/**
+ * Size presets for the textarea: 'sm', 'md', or 'lg'.
+ * These control the width and height of the textarea, unless `fullWidth` is true.
+ * - sm: Small size.
+ * - md: Medium size.
+ * - lg: Large size.
+ */
+type TextAreaSize = 'sm' | 'md' | 'lg';
+/**
+ * Visual status states that affect border and label coloring.
+ * - 'error': Indicates an error state, typically with red styling.
+ * - 'success': Indicates a successful state, typically with green styling.
+ * - 'warning': Indicates a warning state, typically with yellow/orange styling.
+ */
+type TextAreaStatus = 'error' | 'success' | 'warning';
+/**
+ * Optional CSS class overrides for `TextArea` sub-elements.
+ * Provide any of these to customize styling or to merge with the default classes.
+ * - `adornment`: class applied to each adornment element (icons/buttons).
+ * - `adornmentContainer`: class applied to the wrapper that contains adornments.
+ * - `container`: class applied to the root container of the component.
+ * - `label`: class applied to the label element.
+ * - `textarea`: class applied to the underlying `<textarea>` element.
+ */
+interface TextAreaClasses {
+    adornment?: string;
+    adornmentContainer?: string;
+    container?: string;
+    label?: string;
+    textarea?: string;
+}
+/**
+ * Props for the `TextArea` component.
+ * Extends native `TextareaHTMLAttributes` except `cols`, `onError`, and `rows` to
+ * provide a controlled API tailored for this component.
+ * @extends {Omit<TextareaHTMLAttributes<HTMLTextAreaElement>, 'cols' | 'onError' | 'rows'>}
+ */
+interface TextAreaProps extends Omit<TextareaHTMLAttributes<HTMLTextAreaElement>, 'cols' | 'onError' | 'rows'> {
+    /**
+     * ID of the element that describes this textarea (for `aria-describedby`).
+     */
+    'aria-describedby'?: string;
+    /**
+     * Accessible label for the textarea (for `aria-label`).
+     */
+    'aria-label'?: string;
+    /**
+     * Whether the textarea is in an invalid state (for `aria-invalid`).
+     */
+    'aria-invalid'?: boolean;
+    /**
+     * Color used for adornments and label text.
+     */
+    adornmentColor?: TextAreaAdornmentColor;
+    /**
+     * Whether the textarea should receive focus automatically on mount.
+     */
+    autoFocus?: boolean;
+    /**
+     * Override or extend CSS classes for internal sub-elements.
+     */
+    classes?: TextAreaClasses;
+    /**
+     * Show a clear button to reset the textarea value.
+     */
+    clearable?: boolean;
+    /**
+     * Text color variant for the textarea content.
+     */
+    color?: TextAreaColor;
+    /**
+     * Number of columns (width) for the textarea.
+     */
+    cols?: number;
+    /**
+     * Initial uncontrolled value for the textarea.
+     */
+    defaultValue?: string;
+    /**
+     * Disable the textarea.
+     */
+    disabled?: boolean;
+    /**
+     * Adornments rendered at the end of the textarea (icons, images, or nodes).
+     */
+    endAdornments?: TextAreaAdornment[];
+    /**
+     * Mark the textarea as showing an error state.
+     */
+    error?: boolean;
+    /**
+     * Make the textarea take full width of its container.
+     */
+    fullWidth?: boolean;
+    /**
+     * The `id` attribute for the textarea.
+     */
+    id?: string;
+    /**
+     * Optional label text displayed above the textarea.
+     */
+    label?: string;
+    /**
+     * Maximum allowed length of the value.
+     */
+    maxLength?: number;
+    /**
+     * Minimum required length of the value.
+     */
+    minLength?: number;
+    /**
+     * The `name` attribute for form submission.
+     */
+    name?: string;
+    /**
+     * Change event handler for controlled usage.
+     */
+    onChange?: (event: ChangeEvent<HTMLTextAreaElement>) => void;
+    /**
+     * Handler invoked when the clear button is clicked.
+     */
+    onClear?: (event: MouseEvent<HTMLButtonElement>) => void;
+    /**
+     * Input event handler.
+     */
+    onInput?: (event: InputEvent<HTMLTextAreaElement>) => void;
+    /**
+     * Blur event handler.
+     */
+    onBlur?: (event: FocusEvent<HTMLTextAreaElement>) => void;
+    /**
+     * Focus event handler.
+     */
+    onFocus?: (event: FocusEvent<HTMLTextAreaElement>) => void;
+    /**
+     * Key down event handler.
+     */
+    onKeyDown?: (event: KeyboardEvent<HTMLTextAreaElement>) => void;
+    /**
+     * Key up event handler.
+     */
+    onKeyUp?: (event: KeyboardEvent<HTMLTextAreaElement>) => void;
+    /**
+     * Mouse down handler on the textarea element.
+     */
+    onMouseDown?: (event: MouseEvent<HTMLTextAreaElement>) => void;
+    /**
+     * Placeholder text shown when the textarea is empty.
+     */
+    placeholder?: string;
+    /**
+     * Render the textarea as read-only.
+     */
+    readonly?: boolean;
+    /**
+     * Whether the field is required.
+     */
+    required?: boolean;
+    /**
+     * Number of visible rows for the textarea.
+     */
+    rows?: number;
+    /**
+     * Size preset controlling width/height when not fullWidth.
+     */
+    size?: TextAreaSize;
+    /**
+     * Whether spell checking is enabled.
+     */
+    spellCheck?: boolean;
+    /**
+     * Adornments rendered at the start of the textarea.
+     */
+    startAdornments?: TextAreaAdornment[];
+    /**
+     * Visual status (error, success, warning) to style the control.
+     */
+    status?: TextAreaStatus;
+    /**
+     * Controlled value for the textarea.
+     */
+    value?: string;
+}
+/**
+ * `TextArea` — a controlled/uncontrolled textarea with optional adornments.
+ *
+ * Features:
+ * - Supports `value` (controlled) or `defaultValue` (uncontrolled) handled via `useControlled`.
+ * - `startAdornments` and `endAdornments` accept icons, images, or custom children.
+ * - `clearable` renders a clear button that resets the value or calls `onClear`.
+ * - Accepts `classes` to override internal element classNames and `adornmentColor`, `color`, `size`, `status` to adjust styling.
+ * - Preserves native textarea attributes (placeholder, rows, spellCheck, keyboard handlers, etc.).
+ *
+ * Accessibility:
+ * - Supports `aria-label`, `aria-describedby`, and `aria-invalid` props.
+ *
+ * @param props - `TextAreaProps` describing appearance, behavior, and event handlers.
+ * @returns A JSX element rendering the styled textarea with optional adornments.
+ * @example
+ * ```tsx
+ * import { TextArea } from '@/src';
+ *
+ * const MyTextArea = () => (
+ *  <TextArea
+ *   label="Your Message"
+ *   placeholder="Type your message here..."
+ *   adornmentColor="primary"
+ *   color="primary"
+ *   size="md"
+ *   clearable
+ *   startAdornments={[{ icon: faCoffee, onClick: () => alert('Start adornment clicked!') }]}
+ *   endAdornments={[{ children: 'End', onClick: () => alert('End adornment clicked!') }]}
+ *   onChange={(e) => console.log('TextArea value:', e.target.value)}
+ *  />
+ * );
+ * ```
+ */
+declare const TextArea: FC<TextAreaProps>;
+export { TextArea };
+//# sourceMappingURL=TextArea.d.ts.map

package/dist/src/form/TextArea.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TextArea.d.ts","sourceRoot":"","sources":["../../../src/form/TextArea.tsx"],"names":[],"mappings":"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"}

package/dist/src/form/TextInput.d.ts

@@ -0,0 +1,200 @@
+import type { ChangeEvent, FC, FocusEvent, InputEvent, InputHTMLAttributes, JSX, KeyboardEvent, MouseEvent, Ref } from 'react';
+import type { IconDefinition } from '@fortawesome/free-solid-svg-icons';
+/**
+ * Adornment for `TextInput` — either a FontAwesome `IconDefinition`
+ * or an image object `{ src, alt? }`.
+ */
+type TextInputAdornment = IconDefinition | {
+    src: string;
+    alt?: string;
+};
+/**
+ * Colors available for adornments and small text styles.
+ * Allowed values:
+ * - 'primary'
+ * - 'secondary'
+ * - 'accent'
+ * - 'subtle'
+ * - 'inverse'
+ * - 'black'
+ * - 'white'
+ */
+type TextInputAdornmentColor = 'primary' | 'secondary' | 'accent' | 'subtle' | 'inverse' | 'black' | 'white';
+/**
+ * Optional class overrides for `TextInput` sub-elements.
+ * Use these to merge or replace default styles on internal parts.
+ */
+interface TextInputClasses {
+    /** Root container for the component. */
+    container?: string;
+    /** Class applied to the clear button/icon. */
+    clearButton?: string;
+    /** Class applied to the end adornment element. */
+    endAdornment?: string;
+    /** Class applied to the helper text element. */
+    helper?: string;
+    /** Class applied to the native input element. */
+    input?: string;
+    /** Class applied to the input container (border/wrapper). */
+    inputContainer?: string;
+    /** Class applied to the label element. */
+    label?: string;
+    /** Class applied to the start adornment element. */
+    startAdornment?: string;
+    /** Class applied to the toggle button (e.g., show password). */
+    toggleButton?: string;
+}
+/**
+ * Text color variants for the input element.
+ * Allowed values:
+ * - 'black': Standard black text
+ * - 'inverse': Inverted color for dark backgrounds
+ * - 'primary': Primary theme color
+ * - 'white': White text for dark backgrounds
+ */
+type TextInputColor = 'black' | 'inverse' | 'primary' | 'white';
+/**
+ * Size presets for the input.
+ * Allowed values:
+ * - 'sm': Small size with reduced padding and font size
+ * - 'md': Medium size (default) with balanced padding and font size
+ * - 'lg': Large size with increased padding and font size for better readability
+ */
+type TextInputSize = 'sm' | 'md' | 'lg';
+/**
+ * Visual status variants used for border/helper coloring.
+ * Allowed values: 'success', 'warning', 'error'
+ */
+type TextInputStatus = 'success' | 'warning' | 'error';
+/**
+ * Supported input `type` values for this component.
+ * This excludes non-textual types; the component supports common textual
+ * types such as 'text', 'email', 'tel', 'url', 'number', 'password', 'search', etc.
+ */
+type TextInputType = Exclude<JSX.IntrinsicElements['input']['type'], 'button' | 'checkbox' | 'date' | 'datetime-local' | 'month' | 'radio' | 'range' | 'time' | 'week'>;
+/**
+ * Props for `TextInput`.
+ * Extends native input attributes (omitting component-controlled `size`, `pattern`, `onError`).
+ */
+interface TextInputProps extends Omit<InputHTMLAttributes<HTMLInputElement>, 'size' | 'pattern' | 'onError'> {
+    /** ID of the element that describes this input (helper or error message). */
+    'aria-describedby'?: string;
+    /** Accessible label for the input when a visible label is not present. */
+    'aria-label'?: string;
+    /** Indicates the input has a validation error (true/false). */
+    'aria-invalid'?: boolean;
+    /** Color theme to use for adornments and small text. */
+    adornmentColor?: TextInputAdornmentColor;
+    /** Native `autocomplete` value (e.g., 'on', 'off', 'email'). */
+    autoComplete?: string;
+    /** Autofocus the input on mount. */
+    autoFocus?: boolean;
+    /** Class overrides for component sub-elements. */
+    classes?: TextInputClasses;
+    /** Show a clear button inside the input. */
+    clearable?: boolean;
+    /** Text color variant for the input. */
+    color?: TextInputColor;
+    /** Default (uncontrolled) value for the input. */
+    defaultValue?: string;
+    /** Disable the input. */
+    disabled?: boolean;
+    /** Adornment to render at the end of the input. */
+    endAdornment?: TextInputAdornment;
+    /** External error state (controlled). */
+    error?: boolean;
+    /** When true, input expands to fill available width. */
+    fullWidth?: boolean;
+    /** Helper or error text displayed below the input. */
+    helperText?: string;
+    /** Element id attribute. */
+    id?: string;
+    /** Native `inputmode` value hinting the type of virtual keyboard. */
+    inputMode?: JSX.IntrinsicElements['input']['inputMode'];
+    /** Visible label text for the input. */
+    label?: string;
+    /** Maximum allowed length of the input value. */
+    maxLength?: number;
+    /** Minimum allowed length of the input value. */
+    minLength?: number;
+    /** Name attribute for form submission. */
+    name?: string;
+    /** Validation pattern (RegExp) applied client-side. */
+    pattern?: RegExp;
+    /** Placeholder text shown when the input is empty. */
+    placeholder?: string;
+    /** Make the input read-only. */
+    readOnly?: boolean;
+    /** Forwarded ref to the native input element. */
+    ref?: Ref<HTMLInputElement>;
+    /** Whether the input is required. */
+    required?: boolean;
+    /** Show a toggle for password visibility when `type='password'`. */
+    showPasswordToggle?: boolean;
+    /** Size variant of the input. */
+    size?: TextInputSize;
+    /** Visual status for styling (affects border/helper color). */
+    status?: TextInputStatus;
+    /** Enable browser spell checking. */
+    spellCheck?: boolean;
+    /** Adornment to render at the start of the input. */
+    startAdornment?: TextInputAdornment;
+    /** Input `type` (textual types only). */
+    type?: TextInputType;
+    /** Change event handler. */
+    onChange?: (event: ChangeEvent<HTMLInputElement>) => void;
+    /** Clear button click handler. Receives the event and current error state. */
+    onClear?: (event: MouseEvent<HTMLButtonElement>, error: boolean) => void;
+    /** Callback invoked when the error state changes. */
+    onError?: (error: boolean) => void;
+    /** Low-level input event handler. */
+    onInput?: (event: InputEvent<HTMLInputElement>) => void;
+    /** Blur event handler. */
+    onBlur?: (event: FocusEvent<HTMLInputElement>) => void;
+    /** Focus event handler. */
+    onFocus?: (event: FocusEvent<HTMLInputElement>) => void;
+    /** Key down handler. */
+    onKeyDown?: (event: KeyboardEvent<HTMLInputElement>) => void;
+    /** Key up handler. */
+    onKeyUp?: (event: KeyboardEvent<HTMLInputElement>) => void;
+    /** Key down handler for the input element. */
+    onMouseDown?: (event: MouseEvent<HTMLInputElement>) => void;
+    /** Controlled value for the input. */
+    value?: string;
+}
+/**
+ * `TextInput` — a fully featured, accessible text input component.
+ *
+ * Features:
+ * - Optional `label`, `helperText`, and required marker
+ * - Start / end adornments (icons or images)
+ * - Optional clear button (`clearable`) and password visibility toggle
+ * - Controlled or uncontrolled usage via `value` / `defaultValue` and `useControlled`
+ * - Visual `status` variants (`success` | `warning` | `error`) and per-prop `adornmentColor`
+ *
+ * Accessibility:
+ * - Supports `aria-describedby`, `aria-label`, and `aria-invalid` props
+ * - Uses `type='password'` toggle with accessible labels on toggle button
+ * - Leaves focus styling to `:focus-visible` (keyboard focus) and exposes classes via `classes` prop
+ *
+ * @param props - Props for the `TextInput` component, extending native input attributes with additional features.
+ * @returns JSX element representing the `TextInput` component.
+ * @example
+ * ```tsx
+ * import { TextInput } from '@/src';
+ *
+ * const MyTextInput = () => (
+ *  <TextInput
+ *    label="Username"
+ *    placeholder="Enter your username"
+ *    helperText="Must be 4-16 characters"
+ *    required
+ *    pattern={/^[a-zA-Z0-9]{4,16}$/}
+ *    onError={(error) => console.log('Validation error:', error)}
+ *  />
+ * );
+ * ```
+ */
+declare const TextInput: FC<TextInputProps>;
+export { TextInput };
+//# sourceMappingURL=TextInput.d.ts.map

package/dist/src/form/TextInput.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TextInput.d.ts","sourceRoot":"","sources":["../../../src/form/TextInput.tsx"],"names":[],"mappings":"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"}

package/dist/src/form/index.d.ts

@@ -0,0 +1,7 @@
+import { Form } from './Form';
+import type { FormValue } from './Form';
+import { TextArea } from './TextArea';
+import { TextInput } from './TextInput';
+export { Form, TextArea, TextInput };
+export type { FormValue };
+//# sourceMappingURL=index.d.ts.map

package/dist/src/form/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/form/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAC9B,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAC;AACxC,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAExC,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC;AACrC,YAAY,EAAE,SAAS,EAAE,CAAC"}