@g4rcez/components 3.0.0 → 3.0.1

package/dist/ai/docs/FileUpload.md

@@ -0,0 +1,225 @@
+---
+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 { UploadCloudIcon } from "lucide-react";
+
+const CustomIdle = () => (
+  <div className="flex flex-col items-center gap-2 py-10">
+    <UploadCloudIcon 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/docs/Form.md

@@ -0,0 +1,107 @@
+---
+title: Form
+description: Thin wrapper around the HTML form element that calls preventDefault automatically before invoking onSubmit.
+package: "@g4rcez/components"
+export: "{ Form }"
+import: "import { Form } from '@g4rcez/components/form'"
+category: form
+---
+
+# Form
+
+Thin wrapper around the HTML `<form>` element that calls `preventDefault` automatically before invoking `onSubmit`.
+
+## Import
+
+```tsx
+import { Form } from "@g4rcez/components/form";
+```
+
+## Props
+
+`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.). |
+
+## Design Tokens
+
+`Form` has no direct token usage. Tokens are applied by the child components (`Input`, `Button`, etc.) placed inside it.
+
+## Examples
+
+### Login form
+
+```tsx
+import { Form } from "@g4rcez/components/form";
+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>
+  );
+}
+```
+
+### Reading FormData on submit
+
+```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) });
+};
+
+<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>
+```
+
+### 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>
+</Form>
+```
+
+## Do
+
+- Use `Form` instead of a raw `<form>` to avoid calling `e.preventDefault()` in every submit handler.
+- Always include a `<Button type="submit">` or `<button type="submit">` so keyboard users can submit with Enter.
+- Use design-token layout utilities (`gap-base`, `gap-sm`) for consistent spacing between fields.
+
+## Don't
+
+- Don't pass raw Tailwind color classes (`bg-blue-500`, `text-white`, `border-gray-300`) to `Form` — use theme props or design tokens instead.
+- Don't use arbitrary Tailwind values (`bg-[#abc]`) — override CSS variables in your `@theme` block instead.
+- Don't use `Form` when you need a traditional server-rendered full-page reload; use a plain `<form>` with `action` and `method` instead.
+
+## Accessibility
+
+- Renders a semantic `<form>` element, correctly identified by assistive technologies.
+- Ensure every field inside the form has an associated label (the `Input`, `Select`, and other components in this library do this automatically via `InputField`).
+
+## Notes
+
+- `Form` is intentionally minimal — it has no state, no validation logic, and no styling. All field-level behavior is delegated to child components.
+- The `e.persist()` call inside the wrapper ensures the synthetic event remains accessible in async submit handlers.

package/dist/ai/docs/FormReset.md

@@ -0,0 +1,117 @@
+---
+title: formReset
+description: Utility function that resets all inputs and selects in a form to their default values and clears their initialization state.
+package: "@g4rcez/components"
+export: "{ formReset }"
+import: "import { formReset } from '@g4rcez/components'"
+category: form
+---
+
+# formReset
+
+Utility function that resets all inputs and selects in a form to their default values and clears their initialization state.
+
+## Import
+
+```tsx
+import { formReset } from "@g4rcez/components";
+```
+
+## Signature
+
+```ts
+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`. |
+
+## How It Works
+
+1. Iterates over all elements in the form (`form.elements`).
+2. For `<input>` elements: sets `input.value` to `input.defaultValue`.
+3. For `<select>` elements: sets `select.value` to `""`.
+4. On every processed field: sets `data-initialized="false"`, which tells components like `Input` and `Autocomplete` to treat the field as untouched (suppressing validation messages).
+
+## Examples
+
+### Reset after successful submission
+
+```tsx
+import { useRef } from "react";
+import { Form } from "@g4rcez/components/form";
+import { Input } from "@g4rcez/components/input";
+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>
+  );
+}
+```
+
+### Cancel button that resets the form
+
+```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>
+  );
+}
+```
+
+## Do
+
+- Use `formReset` (instead of `form.reset()`) when the form contains library components — it also resets the `data-initialized` flag that controls validation UI.
+- Pass a valid `HTMLFormElement` ref.
+
+## Don't
+
+- Don't expect `formReset` to fire `onChange` events — it modifies `value` directly in the DOM without dispatching React synthetic events.
+- Don't use `formReset` to reset a single field; use standard DOM methods or React state for that.
+- Don't use `formReset` as a substitute for React-controlled state management in complex forms.
+
+## Accessibility
+
+No direct accessibility implications. After a reset, validation error messages will disappear because `data-initialized="false"` prevents them from being shown again until the user interacts with each field.
+
+## Data Attributes
+
+- Sets `data-initialized="false"` on every `INPUT` and `SELECT` element in the form. This attribute is read by `InputField` to decide whether to display validation feedback.
+
+## Notes
+
+- Safe to call with `null` or `undefined` — the function returns early without throwing.
+- Only processes elements with `tagName === "INPUT"` or `tagName === "SELECT"`. `<textarea>` elements are not currently reset by this utility.
+- This is a plain function, not a React component or hook. It works on DOM references directly.

package/dist/ai/docs/Heading.md

@@ -0,0 +1,88 @@
+---
+title: Heading
+description: A minimal heading wrapper that renders as h2 by default, delegating to Polymorph for element flexibility.
+package: "@g4rcez/components"
+export: "{ Heading }"
+import: "import { Heading } from '@g4rcez/components'"
+category: core
+---
+
+# Heading
+
+A minimal heading wrapper that renders as `h2` by default. It delegates to `Polymorph` internally, so all children are forwarded without additional styling or tokens.
+
+## Import
+
+```tsx
+import { Heading } from "@g4rcez/components";
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `React.ReactNode` | - | The content of the heading |
+
+## Design Tokens
+
+None — `Heading` itself applies no styles. Style via `className` passed to the component or global heading rules in your theme.
+
+## Examples
+
+### Default Usage
+
+```tsx
+<Heading>Section Title</Heading>
+```
+
+### Custom Heading Level
+
+The current implementation always renders as `h2`. Use the `Polymorph` component directly if you need a different heading level.
+
+```tsx
+import { Polymorph } from "@g4rcez/components";
+
+<Polymorph as="h1" className="text-3xl font-bold tracking-tight text-foreground">
+  Page Title
+</Polymorph>
+
+<Polymorph as="h3" className="text-lg font-semibold text-foreground">
+  Subsection Title
+</Polymorph>
+```
+
+### Applying Typography Styles
+
+```tsx
+<Heading className="text-2xl font-bold text-foreground">
+  Dashboard Overview
+</Heading>
+```
+
+## Do
+
+- Use `Heading` for `h2`-level section titles throughout your app to ensure a consistent element
+- Use design-token classes for color (`text-foreground`, `text-muted-foreground`) — never raw color utilities
+- Pair with `PageHeader` or `PageTitle` from the Typography components for full page structure
+
+## Don't
+
+- Don't pass raw Tailwind color classes (`text-gray-900`, `text-black`) — use `text-foreground` instead
+- Don't use arbitrary Tailwind values (`text-[#333]`) — override CSS variables in your `@theme` block
+- Don't skip heading hierarchy — if you need `h1` or `h3`, use `Polymorph as="h1"` rather than misusing `Heading`
+- Don't use `Heading` for non-heading content purely for visual sizing
+
+## Accessibility
+
+- Renders as `<h2>` by default, providing semantic structure for screen readers and document outline tools
+- Pass `className` for visual styling without altering the semantic element
+- Ensure each page has a single `h1` (use `Polymorph as="h1"`) before using `Heading` (`h2`) for section titles
+
+## Data Attributes
+
+- `data-component="polymorph"`: Inherited from the underlying `Polymorph` component
+
+## Notes
+
+- `Heading` is a thin wrapper — it accepts `children` only; all other styling is done via `className`
+- If you need an `as` prop for dynamic heading levels, use `Polymorph` directly