@g4rcez/components 4.0.1 → 4.1.1

package/ai/docs/FileUpload.md

@@ -0,0 +1,218 @@
+---
+title: FileUpload
+description: Drag-and-drop file upload area with file preview, modal viewer, and per-file deletion.
+package: "@g4rcez/components"
+export: "{ FileUpload }"
+import: "import { FileUpload } from '@g4rcez/components/file-upload'"
+category: form
+---
+
+# FileUpload
+
+Drag-and-drop file upload area with file preview, modal viewer, and per-file deletion.
+
+## Import
+
+```tsx
+import { FileUpload } from "@g4rcez/components/file-upload";
+```
+
+## Props
+
+| Prop               | Type                                 | Default         | Description                                                          |
+| ------------------ | ------------------------------------ | --------------- | -------------------------------------------------------------------- |
+| `files`            | `File[]`                             | -               | Controlled files array                                               |
+| `onDrop`           | `(files: File[]) => void`            | -               | Called when files are dropped or selected                            |
+| `onDeleteFile`     | `(file: File) => void`               | -               | Called when the delete button on a file item is clicked              |
+| `idle`             | `React.ReactElement`                 | Default idle UI | Content to show when no files are present and the area is not active |
+| `File`             | `React.FC<{ file: File }>`           | -               | Custom component rendered below each file's name/size row            |
+| `accept`           | `string \| Record<string, string[]>` | -               | Accepted file types (forwarded to `react-dropzone`)                  |
+| `multiple`         | `boolean`                            | `false`         | Allow selecting more than one file                                   |
+| `maxFiles`         | `number`                             | -               | Maximum number of files                                              |
+| `maxSize`          | `number`                             | -               | Maximum file size in bytes                                           |
+| `disabled`         | `boolean`                            | `false`         | Disable the drop zone                                                |
+| `name`             | `string`                             | -               | Name for the underlying `<input>`                                    |
+| `...DropzoneProps` |                                      |                 | All `react-dropzone` props are supported                             |
+
+## Design Tokens
+
+Tokens this component reads. Customize by overriding these CSS variables in your theme.
+
+| Token                | CSS Variable        | Purpose                                                         |
+| -------------------- | ------------------- | --------------------------------------------------------------- |
+| `border-card-border` | `--card-border`     | Border between file list items and default drop zone border     |
+| `bg-card-background` | `--card-background` | Drop zone background when files are present                     |
+| `text-foreground`    | `--foreground`      | General text color                                              |
+| `text-primary`       | `--primary`         | Folder icon color and "browse" link color in default idle state |
+| `text-danger`        | `--danger`          | Delete button hover color                                       |
+
+## Drag and Drop States
+
+| State         | Description                                                                |
+| ------------- | -------------------------------------------------------------------------- |
+| Idle (empty)  | Displays the `idle` prop or the default folder icon with an upload prompt  |
+| Drag active   | Replaces the idle UI with an open folder icon while dragging               |
+| Files present | Renders the file list; drop zone border becomes solid and background fills |
+
+## File Type Rendering
+
+The component automatically selects an icon based on file extension:
+
+| Extension(s)   | Icon                     |
+| -------------- | ------------------------ |
+| csv, xls, xlsx | `SheetIcon`              |
+| pdf, txt       | `FileTextIcon`           |
+| json           | `FileJsonIcon`           |
+| mp3            | `AudioLinesIcon`         |
+| mp4, mov       | `FileVideo2`             |
+| Images         | Inline `<img>` thumbnail |
+| Other          | Generic `FileIcon`       |
+
+Clicking a file thumbnail opens a `Modal` viewer with full-size preview for images, `<video>` player for videos, and `<audio>` player for audio files.
+
+## Examples
+
+### Controlled image upload
+
+```tsx
+import { FileUpload } from "@g4rcez/components/file-upload";
+
+function ImageUpload() {
+    const [images, setImages] = useState<File[]>([]);
+
+    return (
+        <FileUpload
+            files={images}
+            onDrop={(added) => setImages((prev) => [...prev, ...added])}
+            onDeleteFile={(file) => setImages((prev) => prev.filter((f) => f !== file))}
+            accept="image/*"
+            multiple
+            maxFiles={10}
+            maxSize={5 * 1024 * 1024}
+        />
+    );
+}
+```
+
+### Single file upload
+
+```tsx
+function AvatarUpload() {
+    const [file, setFile] = useState<File | null>(null);
+
+    return (
+        <FileUpload
+            files={file ? [file] : []}
+            onDrop={(files) => setFile(files[0])}
+            onDeleteFile={() => setFile(null)}
+            accept="image/jpeg,image/png"
+            multiple={false}
+            maxSize={2 * 1024 * 1024}
+        />
+    );
+}
+```
+
+### Custom idle state
+
+```tsx
+import { UploadSimpleIcon } from "@phosphor-icons/react";
+
+const CustomIdle = () => (
+    <div className="flex flex-col items-center gap-2 py-10">
+        <UploadSimpleIcon size={48} className="text-primary" />
+        <p className="text-foreground font-medium">Drop files here</p>
+        <p className="text-muted-foreground text-sm">PDF, DOCX, up to 10 MB each</p>
+    </div>
+);
+
+<FileUpload files={[]} onDrop={setFiles} idle={<CustomIdle />} accept="application/pdf,.docx" multiple />;
+```
+
+### Custom per-file renderer
+
+```tsx
+const ProgressRow = ({ file }: { file: File }) => {
+    const progress = useUploadProgress(file);
+    return (
+        <div className="flex flex-col gap-1 pb-2">
+            <div className="flex justify-between text-xs text-muted-foreground">
+                <span>{progress < 100 ? "Uploading..." : "Done"}</span>
+                <span>{progress}%</span>
+            </div>
+            <div className="h-1.5 rounded-full bg-muted overflow-hidden">
+                <div className="h-full rounded-full bg-primary transition-all" style={{ width: `${progress}%` }} />
+            </div>
+        </div>
+    );
+};
+
+<FileUpload files={files} onDrop={setFiles} File={ProgressRow} multiple />;
+```
+
+### Inside a form
+
+```tsx
+import { Form } from "@g4rcez/components/form";
+import { Button } from "@g4rcez/components/button";
+
+function SubmissionForm() {
+    const [attachments, setAttachments] = useState<File[]>([]);
+
+    const handleSubmit = (e: React.FormEvent<HTMLFormElement>) => {
+        const data = new FormData(e.currentTarget);
+        attachments.forEach((f) => data.append("attachments", f));
+        submitToServer(data);
+    };
+
+    return (
+        <Form onSubmit={handleSubmit} className="flex flex-col gap-base">
+            <FileUpload
+                name="attachments"
+                files={attachments}
+                onDrop={(added) => setAttachments((prev) => [...prev, ...added])}
+                onDeleteFile={(f) => setAttachments((prev) => prev.filter((x) => x !== f))}
+                accept="image/*,.pdf"
+                multiple
+                maxSize={10 * 1024 * 1024}
+            />
+            <Button theme="primary" type="submit">
+                Submit
+            </Button>
+        </Form>
+    );
+}
+```
+
+## Do
+
+- Always set `accept` to restrict uploads to the file types your server expects.
+- Set `maxSize` to provide immediate client-side feedback for oversized files.
+- Use `multiple` when batch uploads are expected.
+- Use the `File` prop to add progress bars, metadata, or custom actions below each file row.
+- Use design-token classes for wrapper elements (`bg-card-background`, `text-foreground`).
+
+## Don't
+
+- Don't pass raw Tailwind color classes (`bg-blue-500`, `text-white`, `border-gray-300`) — use theme props or design tokens instead.
+- Don't use arbitrary Tailwind values (`bg-[#abc]`, `bg-[--my-var]`) — override CSS variables in your `@theme` block instead.
+- Don't rely solely on client-side `maxSize`/`accept` — validate files server-side as well.
+- Don't skip `onDeleteFile` when `files` is controlled — without it, users cannot remove files they added.
+
+## Accessibility
+
+- The drop zone uses `react-dropzone`'s `getRootProps` and `getInputProps`, which include keyboard support (Enter/Space to open the file browser).
+- The hidden `<input type="file">` is accessible by assistive technologies.
+- Delete buttons include a `type="button"` to prevent accidental form submission.
+- The modal viewer opened for file preview is managed by the `Modal` component, which handles focus trapping and Escape to close.
+
+## Data Attributes
+
+- `data-active="true"` — on the drop zone wrapper when at least one file is present; used to switch between dashed (empty) and solid (filled) border styles.
+
+## Notes
+
+- When `files` is not provided, the component manages its own internal file state. Pass `files` for fully controlled behavior.
+- Object URLs created for previews are revoked on cleanup via `useEffect` to prevent memory leaks.
+- The `File` prop (custom renderer) is rendered inside the file list item, below the file name and size row, alongside the built-in delete button.
+- The component depends on `react-dropzone` and `pretty-bytes` as peer dependencies.

package/{dist/ai → ai}/docs/Form.md

@@ -21,12 +21,12 @@ import { Form } from "@g4rcez/components/form";
 
 `Form` accepts all standard HTML `<form>` attributes.
 
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `onSubmit` | `(event: React.FormEvent<HTMLFormElement>) => void` | - | Submit handler. `preventDefault()` is called before this. |
-| `children` | `React.ReactNode` | - | Form fields and other content. |
-| `className` | `string` | - | CSS classes for the `<form>` element. |
-| `...props` | `React.ComponentProps<"form">` | - | All standard form attributes (`action`, `method`, `noValidate`, etc.). |
+| Prop        | Type                                                | Default | Description                                                            |
+| ----------- | --------------------------------------------------- | ------- | ---------------------------------------------------------------------- |
+| `onSubmit`  | `(event: React.FormEvent<HTMLFormElement>) => void` | -       | Submit handler. `preventDefault()` is called before this.              |
+| `children`  | `React.ReactNode`                                   | -       | Form fields and other content.                                         |
+| `className` | `string`                                            | -       | CSS classes for the `<form>` element.                                  |
+| `...props`  | `React.ComponentProps<"form">`                      | -       | All standard form attributes (`action`, `method`, `noValidate`, etc.). |
 
 ## Design Tokens
 
@@ -42,18 +42,20 @@ import { Input } from "@g4rcez/components/input";
 import { Button } from "@g4rcez/components/button";
 
 function LoginForm() {
-  const handleSubmit = (e: React.FormEvent<HTMLFormElement>) => {
-    const data = new FormData(e.currentTarget);
-    console.log(Object.fromEntries(data));
-  };
-
-  return (
-    <Form onSubmit={handleSubmit} className="flex flex-col gap-base max-w-sm">
-      <Input name="email" type="email" title="Email" required />
-      <Input name="password" type="password" title="Password" required />
-      <Button theme="primary" type="submit">Log in</Button>
-    </Form>
-  );
+    const handleSubmit = (e: React.FormEvent<HTMLFormElement>) => {
+        const data = new FormData(e.currentTarget);
+        console.log(Object.fromEntries(data));
+    };
+
+    return (
+        <Form onSubmit={handleSubmit} className="flex flex-col gap-base max-w-sm">
+            <Input name="email" type="email" title="Email" required />
+            <Input name="password" type="password" title="Password" required />
+            <Button theme="primary" type="submit">
+                Log in
+            </Button>
+        </Form>
+    );
 }
 ```
 
@@ -61,26 +63,30 @@ function LoginForm() {
 
 ```tsx
 const handleSubmit = (e: React.FormEvent<HTMLFormElement>) => {
-  const formData = new FormData(e.currentTarget);
-  const payload = Object.fromEntries(formData);
-  await fetch("/api/contact", { method: "POST", body: JSON.stringify(payload) });
+    const formData = new FormData(e.currentTarget);
+    const payload = Object.fromEntries(formData);
+    await fetch("/api/contact", { method: "POST", body: JSON.stringify(payload) });
 };
 
 <Form onSubmit={handleSubmit} className="flex flex-col gap-base">
-  <Input name="name" title="Name" required />
-  <Input name="message" title="Message" />
-  <Button theme="primary" type="submit">Send</Button>
-</Form>
+    <Input name="name" title="Name" required />
+    <Input name="message" title="Message" />
+    <Button theme="primary" type="submit">
+        Send
+    </Button>
+</Form>;
 ```
 
 ### Multi-column layout
 
 ```tsx
 <Form className="grid grid-cols-2 gap-base max-w-2xl">
-  <Input name="firstName" title="First name" required />
-  <Input name="lastName" title="Last name" required />
-  <Input name="email" type="email" title="Email" container="col-span-2" required />
-  <Button type="submit" theme="primary" container="col-start-2">Save</Button>
+    <Input name="firstName" title="First name" required />
+    <Input name="lastName" title="Last name" required />
+    <Input name="email" type="email" title="Email" container="col-span-2" required />
+    <Button type="submit" theme="primary" container="col-start-2">
+        Save
+    </Button>
 </Form>
 ```
 

package/{dist/ai → ai}/docs/FormReset.md

@@ -20,14 +20,14 @@ import { formReset } from "@g4rcez/components";
 ## Signature
 
 ```ts
-function formReset(form?: HTMLFormElement | null): void
+function formReset(form?: HTMLFormElement | null): void;
 ```
 
 ## Parameters
 
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `form` | `HTMLFormElement \| null \| undefined` | The form element to reset. Safely no-ops if `null` or `undefined`. |
+| Parameter | Type                                   | Description                                                        |
+| --------- | -------------------------------------- | ------------------------------------------------------------------ |
+| `form`    | `HTMLFormElement \| null \| undefined` | The form element to reset. Safely no-ops if `null` or `undefined`. |
 
 ## How It Works
 
@@ -48,21 +48,23 @@ import { Button } from "@g4rcez/components/button";
 import { formReset } from "@g4rcez/components";
 
 function ContactForm() {
-  const formRef = useRef<HTMLFormElement>(null);
-
-  const handleSubmit = async (e: React.FormEvent<HTMLFormElement>) => {
-    const data = new FormData(e.currentTarget);
-    await submitToServer(Object.fromEntries(data));
-    formReset(formRef.current);
-  };
-
-  return (
-    <Form ref={formRef} onSubmit={handleSubmit} className="flex flex-col gap-base">
-      <Input name="name" title="Name" required />
-      <Input name="email" type="email" title="Email" required />
-      <Button theme="primary" type="submit">Send</Button>
-    </Form>
-  );
+    const formRef = useRef<HTMLFormElement>(null);
+
+    const handleSubmit = async (e: React.FormEvent<HTMLFormElement>) => {
+        const data = new FormData(e.currentTarget);
+        await submitToServer(Object.fromEntries(data));
+        formReset(formRef.current);
+    };
+
+    return (
+        <Form ref={formRef} onSubmit={handleSubmit} className="flex flex-col gap-base">
+            <Input name="name" title="Name" required />
+            <Input name="email" type="email" title="Email" required />
+            <Button theme="primary" type="submit">
+                Send
+            </Button>
+        </Form>
+    );
 }
 ```
 
@@ -70,24 +72,22 @@ function ContactForm() {
 
 ```tsx
 function EditForm({ defaultValues }: { defaultValues: Record<string, string> }) {
-  const formRef = useRef<HTMLFormElement>(null);
-
-  return (
-    <Form ref={formRef} onSubmit={handleSave} className="flex flex-col gap-base">
-      <Input name="title" title="Title" defaultValue={defaultValues.title} />
-      <Input name="description" title="Description" defaultValue={defaultValues.description} />
-      <div className="flex gap-sm">
-        <Button theme="primary" type="submit">Save</Button>
-        <Button
-          theme="ghost"
-          type="button"
-          onClick={() => formReset(formRef.current)}
-        >
-          Cancel
-        </Button>
-      </div>
-    </Form>
-  );
+    const formRef = useRef<HTMLFormElement>(null);
+
+    return (
+        <Form ref={formRef} onSubmit={handleSave} className="flex flex-col gap-base">
+            <Input name="title" title="Title" defaultValue={defaultValues.title} />
+            <Input name="description" title="Description" defaultValue={defaultValues.description} />
+            <div className="flex gap-sm">
+                <Button theme="primary" type="submit">
+                    Save
+                </Button>
+                <Button theme="ghost" type="button" onClick={() => formReset(formRef.current)}>
+                    Cancel
+                </Button>
+            </div>
+        </Form>
+    );
 }
 ```
 

package/{dist/ai → ai}/docs/Heading.md

@@ -19,9 +19,9 @@ import { Heading } from "@g4rcez/components";
 
 ## Props
 
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `children` | `React.ReactNode` | - | The content of the heading |
+| Prop       | Type              | Default | Description                |
+| ---------- | ----------------- | ------- | -------------------------- |
+| `children` | `React.ReactNode` | -       | The content of the heading |
 
 ## Design Tokens
 
@@ -54,9 +54,7 @@ import { Polymorph } from "@g4rcez/components";
 ### Applying Typography Styles
 
 ```tsx
-<Heading className="text-2xl font-bold text-foreground">
-  Dashboard Overview
-</Heading>
+<Heading className="text-2xl font-bold text-foreground">Dashboard Overview</Heading>
 ```
 
 ## Do

package/ai/docs/Input.md

@@ -0,0 +1,212 @@
+---
+title: Input
+description: Text input with optional masking for currencies, percentages, phone numbers, dates, and custom regex patterns.
+package: "@g4rcez/components"
+export: "{ Input }"
+import: "import { Input } from '@g4rcez/components/input'"
+category: form
+---
+
+# Input
+
+Text input with optional masking for currencies, percentages, phone numbers, dates, and custom regex patterns.
+
+## Import
+
+```tsx
+import { Input } from "@g4rcez/components/input";
+```
+
+## Props
+
+`Input` extends all standard HTML `<input>` attributes plus `InputField` layout props:
+
+| Prop             | Type                                                                   | Default | Description                                                                      |
+| ---------------- | ---------------------------------------------------------------------- | ------- | -------------------------------------------------------------------------------- |
+| `mask`           | `AllMasks \| Array<string \| RegExp> \| ((value: string) => AllMasks)` | -       | Input mask pattern                                                               |
+| `locale`         | `Locales`                                                              | -       | Locale for currency/number formatting                                            |
+| `currency`       | `CurrencyCode`                                                         | -       | Currency code when using `mask="currency"`                                       |
+| `error`          | `string`                                                               | -       | Error message shown below the field                                              |
+| `title`          | `string`                                                               | -       | Field label                                                                      |
+| `feedback`       | `Label`                                                                | -       | Success or neutral feedback text below the field                                 |
+| `left`           | `Label`                                                                | -       | Content rendered on the left inside the field border                             |
+| `right`          | `Label`                                                                | -       | Content rendered on the right inside the field border                            |
+| `required`       | `boolean`                                                              | `false` | Marks field as required; hides "Optional" label text                             |
+| `disabled`       | `boolean`                                                              | `false` | Disabled state                                                                   |
+| `loading`        | `boolean`                                                              | `false` | Loading state                                                                    |
+| `container`      | `string`                                                               | -       | Extra CSS classes for the outer `fieldset`                                       |
+| `labelClassName` | `string`                                                               | -       | Extra CSS classes for the label/border wrapper                                   |
+| `next`           | `string`                                                               | -       | `id` of the next field to focus when Enter is pressed with `enterKeyHint="next"` |
+| `hiddenLabel`    | `boolean`                                                              | `false` | Visually hides the label but keeps it for screen readers                         |
+| `...props`       | `React.InputHTMLAttributes<HTMLInputElement>`                          | -       | All standard input attributes                                                    |
+
+### Mask patterns
+
+| Pattern char | Matches           |
+| ------------ | ----------------- |
+| `9`          | Digit (0–9)       |
+| `A`          | Letter (a–z, A–Z) |
+| `S`          | Alphanumeric      |
+| `*`          | Any character     |
+
+### Special mask strings
+
+| Value          | Description                                            |
+| -------------- | ------------------------------------------------------ |
+| `"currency"`   | Currency formatting (requires `locale` and `currency`) |
+| `"percentage"` | Percentage input with `%` symbol                       |
+| `"decimal"`    | Decimal number formatting                              |
+
+## Design Tokens
+
+Tokens this component reads. Customize by overriding these CSS variables in your theme.
+
+| Token                          | CSS Variable         | Purpose                                          |
+| ------------------------------ | -------------------- | ------------------------------------------------ |
+| `h-input-height`               | `--input-height`     | Input height                                     |
+| `px-input-x`                   | `--input-x`          | Horizontal padding                               |
+| `py-input-y`                   | `--input-y`          | Vertical padding                                 |
+| `mt-input-gap`                 | `--input-gap`        | Gap between field border and error/feedback text |
+| `border-input-border`          | `--input-border`     | Default border color                             |
+| `text-field-label`             | `--field-label`      | Label text color                                 |
+| `text-foreground`              | `--foreground`       | Input text color                                 |
+| `text-primary`                 | `--primary`          | Focus ring, focus/hover border color             |
+| `text-danger`                  | `--danger`           | Error state border, text, and label color        |
+| `text-disabled`                | `--disabled`         | Disabled text and border color                   |
+| `placeholder-input-mask`       | `--input-mask`       | Placeholder text color                           |
+| `placeholder-input-mask-error` | `--input-mask-error` | Placeholder color in error state                 |
+
+## Examples
+
+### Basic text input
+
+```tsx
+import { Input } from "@g4rcez/components/input";
+
+<Input name="name" title="Full name" placeholder="Jane Smith" required />;
+```
+
+### Phone number mask
+
+```tsx
+<Input name="phone" title="Phone" mask="(99) 99999-9999" placeholder="(00) 00000-0000" />
+```
+
+### Currency input
+
+```tsx
+<Input name="price" title="Price" mask="currency" currency="USD" locale="en-US" placeholder="0.00" />
+```
+
+### Dynamic mask (CPF / CNPJ)
+
+```tsx
+const docMask = (value: string) => (value.replace(/\D/g, "").length <= 11 ? "999.999.999-99" : "99.999.999/9999-99");
+
+<Input name="document" title="CPF or CNPJ" mask={docMask} placeholder="000.000.000-00" />;
+```
+
+### Input with inline left/right slots
+
+```tsx
+import { MagnifyingGlassIcon } from "@phosphor-icons/react";
+
+<Input name="search" title="Search" left={<MagnifyingGlassIcon size={16} className="text-muted-foreground" />} placeholder="Type to search..." />;
+```
+
+### Input with error and feedback
+
+```tsx
+const [email, setEmail] = useState("");
+const error = email && !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email) ? "Enter a valid email address" : undefined;
+
+<Input
+    name="email"
+    type="email"
+    title="Email"
+    value={email}
+    onChange={(e) => setEmail(e.target.value)}
+    error={error}
+    feedback={!error && email ? "Looks good!" : undefined}
+/>;
+```
+
+### Enter-to-advance between fields
+
+```tsx
+<Input
+  name="first"
+  title="First name"
+  enterKeyHint="next"
+  next="last"
+/>
+<Input
+  name="last"
+  id="last"
+  title="Last name"
+  enterKeyHint="done"
+/>
+```
+
+### Inside a form
+
+```tsx
+import { Form } from "@g4rcez/components/form";
+import { Button } from "@g4rcez/components/button";
+
+function SignUpForm() {
+    const handleSubmit = (e: React.FormEvent<HTMLFormElement>) => {
+        const data = new FormData(e.currentTarget);
+        console.log(Object.fromEntries(data));
+    };
+
+    return (
+        <Form onSubmit={handleSubmit} className="flex flex-col gap-base max-w-md">
+            <Input name="name" title="Full name" required />
+            <Input name="email" type="email" title="Email" required />
+            <Input name="phone" title="Phone" mask="(99) 99999-9999" />
+            <Button theme="primary" type="submit">
+                Sign up
+            </Button>
+        </Form>
+    );
+}
+```
+
+## Do
+
+- Use `mask` patterns that match user expectations for the data type.
+- Provide a `placeholder` that shows the expected format (e.g., `"(00) 00000-0000"`).
+- Use the `error` prop to surface validation messages from your form library or manual validation.
+- Use the `next` prop with `enterKeyHint="next"` to create smooth keyboard flows on mobile.
+- Use design-token classes for wrapper elements (`bg-background`, `text-foreground`, `border-border`).
+
+## Don't
+
+- Don't pass raw Tailwind color classes (`bg-blue-500`, `text-white`, `border-gray-300`) — use theme props or design tokens instead.
+- Don't use arbitrary Tailwind values (`bg-[#abc]`, `bg-[--my-var]`) — override CSS variables in your `@theme` block instead.
+- Don't use a mask that blocks valid input variations — prefer dynamic masks for formats with variable length.
+- Don't forget that the mask formats the display value; if your backend expects raw data, strip formatting before sending.
+- Don't use `Input` for long-form text — use `Textarea` instead.
+
+## Accessibility
+
+- Renders a semantic `<input>` wrapped in a `<fieldset>` with an associated `<label>` (via `InputField`).
+- `aria-disabled`, `aria-readonly`, and `aria-busy` are set automatically from props.
+- Error messages appear as a visible `<p>` below the field after the user has interacted with it (`data-initialized="true"`).
+- Focus ring uses `focus:ring-primary` for consistent, visible keyboard indication.
+- The `hiddenLabel` prop keeps the label in the accessibility tree while hiding it visually.
+
+## Data Attributes
+
+- `data-initialized` — managed by `initializeInputDataset`; switches from `"false"` to `"true"` after first user interaction, enabling validation display.
+- `data-next` — set from the `next` prop; used to focus the next field on Enter.
+- `data-component="input"` — set on the outer `fieldset` by `InputField`.
+- `data-error` — on the `fieldset`: `"true"` when an `error` string is present.
+
+## Notes
+
+- Built on top of `the-mask-input`. All mask features from that library are available.
+- The component automatically manages cursor positioning during masked input.
+- Works with both controlled (`value` + `onChange`) and uncontrolled (`defaultValue`) patterns.
+- `Input` is created via the `createFreeText` factory, which also powers `Textarea`. Both share the same styling tokens.