@g4rcez/components 4.0.1 → 4.1.1

package/dist/ai/docs/Dropdown.md

@@ -1,223 +0,0 @@
----
-title: Dropdown
-description: Floating dropdown panel with an optional title, arrow pointer, and automatic collision-aware positioning.
-package: "@g4rcez/components"
-export: "{ Dropdown }"
-import: "import { Dropdown } from '@g4rcez/components/dropdown'"
-category: floating
----
-
-# Dropdown
-
-Floating dropdown panel with an optional title, arrow pointer, and automatic collision-aware positioning.
-
-## Import
-
-```tsx
-import { Dropdown } from "@g4rcez/components/dropdown";
-```
-
-## Props
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `trigger` | `React.ReactElement \| React.ReactNode` | — | Element that toggles the dropdown on click |
-| `open` | `boolean` | — | Controlled open state |
-| `arrow` | `boolean` | `false` | Show an arrow pointer pointing at the trigger |
-| `title` | `React.ReactNode \| string` | — | Header title rendered inside the panel |
-| `restoreFocus` | `boolean` | `true` | Restore focus to the trigger when the panel closes |
-| `returnFocus` | `boolean` | `true` | Return focus to the trigger element |
-| `onChange` | `(nextValue: boolean) => void` | — | Callback fired when the open state changes |
-| `buttonProps` | `React.HTMLProps<"button">` | — | Additional props forwarded to the trigger `<button>` |
-| `children` | `React.ReactNode` | — | Panel content |
-
-## Design Tokens
-
-Tokens this component reads. Customize by overriding these CSS variables in your theme.
-
-| Token | CSS Variable | Purpose |
-|-------|-------------|---------|
-| `bg-floating-background` | `--floating-background` | Panel surface background |
-| `border-floating-border` | `--floating-border` | Panel border and arrow stroke |
-| `fill-floating-background` | `--floating-background` | Arrow fill color |
-| `z-floating` | `--z-floating` | Z-index for the floating panel |
-| `shadow-shadow-floating` | `--shadow-floating` | Panel drop shadow |
-| `rounded-lg` | — | Panel corner radius |
-
-## Examples
-
-### Simple Action Menu
-
-```tsx
-import { Dropdown } from "@g4rcez/components/dropdown";
-import { Button } from "@g4rcez/components/button";
-
-function SimpleDropdown() {
-  return (
-    <Dropdown
-      trigger={<Button theme="primary">Actions</Button>}
-    >
-      <div className="flex min-w-48 flex-col py-1">
-        <button className="w-full px-4 py-2 text-left text-foreground hover:bg-floating-hover">
-          Edit
-        </button>
-        <button className="w-full px-4 py-2 text-left text-foreground hover:bg-floating-hover">
-          Duplicate
-        </button>
-        <hr className="border-border my-1" />
-        <button className="w-full px-4 py-2 text-left text-danger hover:bg-floating-hover">
-          Delete
-        </button>
-      </div>
-    </Dropdown>
-  );
-}
-```
-
-### Dropdown with Title and Arrow
-
-```tsx
-import { UserIcon, CaretDownIcon } from "@phosphor-icons/react";
-import { Dropdown } from "@g4rcez/components/dropdown";
-
-function AccountDropdown() {
-  return (
-    <Dropdown
-      trigger={
-        <button className="flex items-center gap-2 px-3 py-2 rounded-button border border-border text-foreground">
-          <UserIcon size={16} />
-          Account
-          <CaretDownIcon size={16} />
-        </button>
-      }
-      title="Account Options"
-      arrow
-    >
-      <div className="flex min-w-48 flex-col py-1">
-        <button className="w-full px-4 py-2 text-left text-foreground hover:bg-floating-hover">
-          Profile Settings
-        </button>
-        <button className="w-full px-4 py-2 text-left text-foreground hover:bg-floating-hover">
-          Billing
-        </button>
-        <button className="w-full px-4 py-2 text-left text-foreground hover:bg-floating-hover">
-          Sign Out
-        </button>
-      </div>
-    </Dropdown>
-  );
-}
-```
-
-### Controlled Dropdown
-
-```tsx
-import { useState } from "react";
-import { Dropdown } from "@g4rcez/components/dropdown";
-
-function ControlledDropdown() {
-  const [isOpen, setIsOpen] = useState(false);
-
-  return (
-    <Dropdown
-      trigger={
-        <button className="px-4 py-2 rounded-button bg-muted text-foreground">
-          {isOpen ? "Close" : "Open"} Menu
-        </button>
-      }
-      open={isOpen}
-      onChange={setIsOpen}
-    >
-      <div className="min-w-48 p-4">
-        <p className="text-foreground">Controlled dropdown content</p>
-        <button
-          onClick={() => setIsOpen(false)}
-          className="mt-2 px-3 py-1 bg-primary text-primary-foreground rounded-button text-sm"
-        >
-          Close
-        </button>
-      </div>
-    </Dropdown>
-  );
-}
-```
-
-### Filter Dropdown with Form Content
-
-```tsx
-import { FunnelIcon } from "@phosphor-icons/react";
-import { Dropdown } from "@g4rcez/components/dropdown";
-
-function FilterDropdown() {
-  const [status, setStatus] = useState("");
-
-  return (
-    <Dropdown
-      trigger={
-        <button className="flex items-center gap-2 px-3 py-2 rounded-button border border-border text-foreground">
-          <FunnelIcon size={16} />
-          Filters
-          {status && <span className="h-2 w-2 rounded-full bg-primary" />}
-        </button>
-      }
-      title="Filter Options"
-    >
-      <div className="min-w-64 space-y-4 p-4">
-        <div>
-          <label className="block text-sm font-medium text-foreground mb-1">
-            Status
-          </label>
-          <select
-            value={status}
-            onChange={(e) => setStatus(e.target.value)}
-            className="w-full px-3 py-2 rounded-button border border-border bg-background text-foreground"
-          >
-            <option value="">All</option>
-            <option value="active">Active</option>
-            <option value="inactive">Inactive</option>
-          </select>
-        </div>
-        <div className="flex gap-2 pt-2">
-          <button
-            onClick={() => setStatus("")}
-            className="px-3 py-1 text-sm rounded-button border border-border text-foreground"
-          >
-            Clear
-          </button>
-          <button className="px-3 py-1 text-sm rounded-button bg-primary text-primary-foreground">
-            Apply
-          </button>
-        </div>
-      </div>
-    </Dropdown>
-  );
-}
-```
-
-## Do
-
-- Use design-token classes for dropdown item hover states (`hover:bg-floating-hover`, `text-foreground`) instead of raw color utilities.
-- Provide a `title` to help users understand the panel's context.
-- Use the `arrow` prop when the trigger is small and spatial context helps the user.
-- Group related items with separators for panels with more than 5 items.
-
-## Don't
-
-- Don't pass raw Tailwind color classes (`bg-blue-500`, `text-white`, `hover:bg-gray-100`) — use design-token classes.
-- Don't use arbitrary values (`bg-[#abc]`, `z-[9999]`) — override CSS variables in your `@theme` block.
-- Don't put more than 10–15 items in a single dropdown; consider `CommandPalette` or `Modal` instead.
-- Don't place critical destructive actions in a dropdown without a confirmation step.
-
-## Accessibility
-
-- The trigger is wrapped in a `<button>` element; pass `aria-label` via `buttonProps` when the trigger has no visible text.
-- The panel receives `aria-labelledby` pointing at the heading generated from `title`.
-- `FloatingFocusManager` traps focus within the panel and restores it to the trigger on close.
-- Clicking outside or pressing `Escape` closes the panel (handled by `useDismiss`).
-- Tab navigation works naturally within the panel content.
-
-## Notes
-
-- Built on `@floating-ui/react` with `flip`, `shift`, and `offset(10)` middleware. The panel flips to the opposite side if there is insufficient space.
-- When a child element has `data-floating="true"`, focus leaving to that element will not close the dropdown — useful for nested portals.
-- The `open` prop is synced to local state via `useEffect`; controlled and uncontrolled usage are both supported.

package/dist/ai/docs/FileUpload.md

@@ -1,225 +0,0 @@
----
-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/docs/Input.md

@@ -1,237 +0,0 @@
----
-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.