@g4rcez/components 4.0.1 → 4.1.1

package/dist/ai/docs/Alert.md

@@ -1,167 +0,0 @@
----
-title: Alert
-description: Collapsible, themed alert banner for displaying important messages and status updates.
-package: "@g4rcez/components"
-export: "{ Alert }"
-import: "import { Alert } from '@g4rcez/components/alert'"
-category: display
----
-
-# Alert
-
-Collapsible, themed alert banner for displaying important messages and status updates.
-
-## Import
-
-```tsx
-import { Alert } from "@g4rcez/components/alert";
-```
-
-## Props
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `theme` | `"primary" \| "secondary" \| "info" \| "warn" \| "danger" \| "success" \| "neutral"` | `"neutral"` | Visual theme variant |
-| `title` | `string` | — | Alert heading text |
-| `Icon` | `React.ReactElement` | — | Custom icon element (overrides default theme icon) |
-| `open` | `boolean` | `true` | Controls visibility with collapse animation |
-| `onClose` | `(nextState: boolean) => void` | — | Callback when close button is clicked; omit to hide the button |
-| `container` | `string` | — | Additional classes for the outer wrapper |
-| `as` | `React.ElementType` | `"div"` | Polymorphic root element |
-| `className` | `string` | — | Additional classes for the alert element |
-| `children` | `React.ReactNode` | — | Alert body content |
-
-## Design Tokens
-
-Tokens this component reads. Customize by overriding these CSS variables in your theme.
-
-| Token | CSS Variable | Purpose |
-|-------|-------------|---------|
-| `bg-alert-{theme}-bg` | `--alert-{theme}-bg` | Background per theme |
-| `text-alert-{theme}-text` | `--alert-{theme}-text` | Text color per theme |
-| `border-alert-{theme}-border` | `--alert-{theme}-border` | Border color per theme |
-| `border-card-border` | `--card-border` | Border for `neutral` theme |
-| `text-foreground` | `--foreground` | Close button color |
-| `text-danger` | `--danger` | Close button hover color |
-
-Themes: `primary`, `secondary`, `info`, `warn`, `danger`, `success`, `neutral`.
-
-## Themes
-
-Each theme maps to a set of `bg-alert-{theme}-*` tokens and provides default icons for some variants:
-
-| Theme | Default Icon |
-|-------|-------------|
-| `success` | `CheckCircleIcon` |
-| `info` | `InfoIcon` |
-| `danger` | `TriangleAlertIcon` |
-| `warn` | — |
-| `primary` / `secondary` / `neutral` | — |
-
-## Examples
-
-### Basic Variants
-
-```tsx
-<Alert theme="info" title="Information">
-  This is an informational message.
-</Alert>
-
-<Alert theme="success" title="Success">
-  Your changes have been saved successfully.
-</Alert>
-
-<Alert theme="warn" title="Warning">
-  Please review your input before proceeding.
-</Alert>
-
-<Alert theme="danger" title="Error">
-  Something went wrong. Please try again.
-</Alert>
-```
-
-### With Custom Icon
-
-```tsx
-import { BellIcon } from "@phosphor-icons/react";
-
-<Alert theme="info" title="Notification" Icon={<BellIcon size={20} />}>
-  You have new messages.
-</Alert>
-```
-
-### Dismissible Alert
-
-```tsx
-const [showAlert, setShowAlert] = useState(true);
-
-<Alert
-  theme="success"
-  title="Welcome!"
-  open={showAlert}
-  onClose={() => setShowAlert(false)}
->
-  Thanks for joining our platform.
-</Alert>
-```
-
-### Rich Content
-
-```tsx
-import { Button } from "@g4rcez/components/button";
-
-<Alert theme="info" title="Update Available">
-  <p>A new version of the application is available.</p>
-  <div className="mt-3 flex gap-2">
-    <Button theme="primary" size="small">Update Now</Button>
-    <Button theme="neutral" size="small">Later</Button>
-  </div>
-</Alert>
-```
-
-### Form Validation
-
-```tsx
-const [errors, setErrors] = useState<string[]>([]);
-
-<Alert theme="danger" title="Validation Errors" open={errors.length > 0}>
-  <ul className="list-disc list-inside space-y-1">
-    {errors.map((error, index) => (
-      <li key={index}>{error}</li>
-    ))}
-  </ul>
-</Alert>
-```
-
-## Do
-
-- Use `theme` to match message severity (`danger` for errors, `success` for completions, `warn` for cautions).
-- Provide a concise, descriptive `title` so users immediately understand the alert.
-- Supply `onClose` when the alert should be user-dismissible.
-- Use design-token classes for any wrapper elements (`bg-background`, `border-border`).
-
-## Don't
-
-- Don't pass raw Tailwind color classes (`bg-blue-500`, `text-white`, `border-gray-300`) — use `theme` 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 `danger` for non-critical information; use `warn` or `info` instead.
-- Don't omit `onClose` if the alert must be dismissible — the close button only renders when the prop is provided.
-
-## Accessibility
-
-- Renders with `role="alert"` for immediate screen reader announcement.
-- Title uses a semantic `h4` element for proper heading hierarchy.
-- Close button is keyboard accessible and uses a visible icon.
-- The `aria-hidden` attribute on the collapse wrapper prevents interaction with hidden content.
-
-## Data Attributes
-
-- `data-component="alert"` — outer wrapper element.
-- `data-theme` — current theme variant (e.g. `"danger"`).
-- `data-open` — current visibility state (`"true"` / `"false"`).
-
-## Notes
-
-- Animation uses Framer Motion (`motion/react`): 0.7 s collapse/expand with spring easing.
-- When `open` becomes `false`, the alert collapses and is removed from the DOM via `AnimatePresence`.
-- The component is polymorphic — pass `as="section"` or any other element type via the `as` prop.

package/dist/ai/docs/AnimatedList.md

@@ -1,205 +0,0 @@
----
-title: AnimatedList
-description: Animated list that expands each item into a floating detail overlay on click.
-package: "@g4rcez/components"
-export: "{ AnimatedList, AnimatedListItem }"
-import: "import { AnimatedList, AnimatedListItem } from '@g4rcez/components'"
-category: display
----
-
-# AnimatedList
-
-Animated list that expands each item into a floating detail overlay on click.
-
-## Import
-
-```tsx
-import { AnimatedList, AnimatedListItem } from "@g4rcez/components";
-```
-
-## Props
-
-### AnimatedList
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `children` | `React.ReactNode` | — | One or more `AnimatedListItem` elements. |
-
-### AnimatedListItem
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `title` | `Label` | — | Primary heading shown in the list row and the overlay header. |
-| `description` | `Label` | — | Secondary text shown below the title in both the row and overlay header. |
-| `children` | `Label` | — | Content rendered inside the expanded overlay below the header. |
-| `avatar` | `Label` | — | Optional node (icon, image, or element) shown at the leading edge of the row. |
-| `leading` | `React.FC<{ open: () => void }>` | — | Optional render-prop component placed at the trailing edge of the row. Receives an `open` function to trigger the overlay programmatically. |
-
-`Label` is `string | number | ReactNode`.
-
-## Design Tokens
-
-Tokens this component reads. Customize by overriding these CSS variables in your theme.
-
-| Token | CSS Variable | Purpose |
-|-------|-------------|---------|
-| `border-card-border` | `--card-border` | Row separator border and overlay border |
-| `bg-card-background` | `--card-background` | Overlay card background |
-| `rounded-card` | `--radius-card` | Overlay card border radius |
-| `shadow-shadow-card` | `--shadow-card` | Overlay card drop shadow |
-| `text-foreground` | `--foreground` | Default row and overlay text color |
-| `text-secondary` | `--secondary` | Description text color in rows and overlay |
-| `text-primary` | `--primary` | Row title hover color |
-| `text-danger` | `--danger` | Close button hover color |
-| `bg-floating-overlay` | `--floating-overlay` | Overlay backdrop tint (used at 70% opacity) |
-| `z-floating` | `--z-floating` | `z-index` for the overlay (value: 22) |
-| `z-overlay` | `--z-overlay` | `z-index` for the backdrop scrim |
-
-## Examples
-
-### Basic list
-
-```tsx
-import { AnimatedList, AnimatedListItem } from "@g4rcez/components";
-
-const items = [
-  { id: "1", name: "Alice Johnson", role: "Engineering" },
-  { id: "2", name: "Bob Smith", role: "Design" },
-];
-
-export function TeamList() {
-  return (
-    <AnimatedList>
-      {items.map((member) => (
-        <AnimatedListItem
-          key={member.id}
-          title={member.name}
-          description={member.role}
-        >
-          <p className="text-foreground">
-            Full profile details for {member.name}.
-          </p>
-        </AnimatedListItem>
-      ))}
-    </AnimatedList>
-  );
-}
-```
-
-### With avatar
-
-```tsx
-import { AnimatedList, AnimatedListItem } from "@g4rcez/components";
-import { UserCircleIcon } from "@phosphor-icons/react";
-
-export function UserDirectory() {
-  return (
-    <AnimatedList>
-      <AnimatedListItem
-        title="Carol White"
-        description="Product Manager"
-        avatar={<UserCircleIcon size={40} className="text-muted-foreground" />}
-      >
-        <div className="flex flex-col gap-2 text-foreground">
-          <p>Department: Product</p>
-          <p>Location: San Francisco</p>
-        </div>
-      </AnimatedListItem>
-    </AnimatedList>
-  );
-}
-```
-
-### With trailing action using `leading`
-
-```tsx
-import { AnimatedList, AnimatedListItem } from "@g4rcez/components";
-import { Button } from "@g4rcez/components/button";
-
-export function OrderList({ orders }: { orders: Order[] }) {
-  return (
-    <AnimatedList>
-      {orders.map((order) => (
-        <AnimatedListItem
-          key={order.id}
-          title={`Order #${order.id}`}
-          description={`Total: ${order.total}`}
-          leading={({ open }) => (
-            <Button size="small" theme="ghost-muted" onClick={open}>
-              View details
-            </Button>
-          )}
-        >
-          <OrderDetailContent order={order} />
-        </AnimatedListItem>
-      ))}
-    </AnimatedList>
-  );
-}
-```
-
-### Activity feed
-
-```tsx
-import { AnimatedList, AnimatedListItem } from "@g4rcez/components";
-import { BellIcon, CheckCircleIcon, WarningIcon } from "@phosphor-icons/react";
-
-const activities = [
-  { id: "a1", icon: <CheckCircleIcon size={20} className="text-success" />, title: "Deployment succeeded", description: "2 minutes ago", detail: "All 3 services started." },
-  { id: "a2", icon: <WarningIcon size={20} className="text-warn" />, title: "High memory usage", description: "15 minutes ago", detail: "Instance i-0ab2c was at 91%." },
-];
-
-export function ActivityFeed() {
-  return (
-    <AnimatedList>
-      {activities.map((a) => (
-        <AnimatedListItem
-          key={a.id}
-          title={a.title}
-          description={a.description}
-          avatar={a.icon}
-        >
-          <p className="text-sm text-muted-foreground">{a.detail}</p>
-        </AnimatedListItem>
-      ))}
-    </AnimatedList>
-  );
-}
-```
-
-## Do
-
-- Keep `title` and `description` concise — they share one row and truncation is not automatic.
-- Provide meaningful `children` content in the overlay; it should justify opening the detail view.
-- Use `leading` to surface a primary call-to-action without forcing the user to click the title.
-- Use design-token classes for any content inside the overlay (`bg-card-background`, `text-foreground`, `border-card-border`).
-
-## Don't
-
-- Don't pass raw Tailwind color classes (`bg-blue-500`, `text-white`, `border-gray-300`) — use 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 `AnimatedList` for purely informational lists with no actionable detail — use a plain `<ul>` or the `List` component instead.
-- Don't embed full sub-applications inside the overlay `children`; keep the detail view focused and lightweight.
-- Don't rely on `AnimatedListItem` rendering its `children` directly — it renders nothing on its own; all rendering is managed by the parent `AnimatedList`.
-
-## Accessibility
-
-- The list renders as a semantic `<ul role="list">`.
-- Each item's title/description area is a `<button>` that triggers the overlay, making it keyboard accessible.
-- The overlay uses `FloatingFocusManager` to trap focus and `FloatingOverlay` with `lockScroll` to prevent background interaction.
-- Pressing `Escape` or clicking outside the overlay dismisses it.
-- The close button inside the overlay is a focusable `<button>` element.
-- `MotionConfig reducedMotion="user"` respects the user's system-level reduced-motion preference.
-
-## Data Attributes
-
-- `data-component="collapse"` — internal animation wrapper (referenced in motion layout animations).
-- `layoutId="item-{id}"` — shared between the list row and the overlay card to drive the expand/collapse shared-element animation.
-- `layoutId="toast-{id}"` — inner content wrapper used for coordinated layout transitions.
-
-## Notes
-
-- Animations use `motion/react` shared layout (`layoutId`) so the item smoothly expands from its row position into the centered overlay.
-- The overlay is rendered in a `FloatingPortal`, outside the normal DOM tree, to avoid stacking-context issues.
-- Only one item can be open at a time; opening a new item first closes the current one.
-- `AnimatedListItem` is a thin shell component — it returns `Fragment` and holds no state. All logic lives in `AnimatedList`, which reads child `props` via `React.Children.toArray`.

package/dist/ai/docs/Autocomplete.md

@@ -1,225 +0,0 @@
----
-title: Autocomplete
-description: Searchable select with fuzzy matching, virtualized options, keyboard navigation, and dynamic option creation.
-package: "@g4rcez/components"
-export: "{ Autocomplete }"
-import: "import { Autocomplete } from '@g4rcez/components/autocomplete'"
-category: form
----
-
-# Autocomplete
-
-Searchable select with fuzzy matching, virtualized options, keyboard navigation, and dynamic option creation.
-
-## Import
-
-```tsx
-import { Autocomplete } from "@g4rcez/components/autocomplete";
-```
-
-## Props
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `title` | `string` | - | Field label |
-| `value` | `string` | - | Controlled selected value |
-| `options` | `AutocompleteItemProps[]` | - | List of selectable options |
-| `emptyMessage` | `Label` | - | Message displayed when no options match |
-| `dynamicOption` | `boolean` | `false` | Allow creating new options from typed text |
-| `onChange` | `(e: React.ChangeEvent<HTMLInputElement>) => void` | - | Change handler |
-| `error` | `string` | - | Error message displayed below the field |
-| `feedback` | `Label` | - | Success/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" text |
-| `disabled` | `boolean` | `false` | Disables the field |
-| `loading` | `boolean` | `false` | Shows loading state |
-| `container` | `string` | - | Extra CSS classes for the outer `fieldset` |
-| `labelClassName` | `string` | - | Extra CSS classes for the label/border wrapper |
-
-### AutocompleteItemProps
-
-```tsx
-type AutocompleteItemProps = {
-  value: string;
-  label?: string;
-  hidden?: boolean;
-  disabled?: boolean;
-  "data-dynamic"?: string;
-  Render?: React.FC<OptionProps>;
-} & Record<`data-${string}`, string>;
-```
-
-## 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 input padding |
-| `py-input-y` | `--input-y` | Vertical input padding |
-| `border-input-border` | `--input-border` | Default field border color |
-| `placeholder-input-mask` | `--input-mask` | Placeholder text color |
-| `placeholder-input-mask-error` | `--input-mask-error` | Placeholder color in error state |
-| `text-foreground` | `--foreground` | Input text color |
-| `text-danger` | `--danger` | Text color in error state |
-| `text-primary` | `--primary` | Focus/hover border and ring color |
-| `bg-floating-background` | `--floating-background` | Dropdown background |
-| `border-floating-border` | `--floating-border` | Dropdown border color |
-| `bg-floating-hover` | `--floating-hover` | Option background on hover/keyboard focus |
-| `text-disabled` | `--disabled` | Empty message text color |
-| `border-tooltip-border` | `--tooltip-border` | Separator inside dropdown |
-| `z-floating` | `--z-floating` | Z-index for the floating panel |
-| `shadow-floating` | `--shadow-floating` | Drop shadow for the floating panel |
-
-## Examples
-
-### Basic usage
-
-```tsx
-import { Autocomplete } from "@g4rcez/components/autocomplete";
-
-const options = [
-  { value: "react", label: "React" },
-  { value: "vue", label: "Vue" },
-  { value: "svelte", label: "Svelte" },
-];
-
-function FrameworkPicker() {
-  const [value, setValue] = useState("");
-
-  return (
-    <Autocomplete
-      title="Framework"
-      placeholder="Search frameworks..."
-      options={options}
-      value={value}
-      onChange={(e) => setValue(e.target.value)}
-    />
-  );
-}
-```
-
-### Dynamic option creation
-
-```tsx
-function TagPicker() {
-  const [value, setValue] = useState("");
-  const [tags, setTags] = useState([
-    { value: "typescript", label: "TypeScript" },
-    { value: "javascript", label: "JavaScript" },
-  ]);
-
-  const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
-    const next = e.target.value;
-    setValue(next);
-    if (next && !tags.find((t) => t.value === next)) {
-      setTags((prev) => [...prev, { value: next, label: next }]);
-    }
-  };
-
-  return (
-    <Autocomplete
-      title="Tag"
-      placeholder="Search or create a tag..."
-      options={tags}
-      value={value}
-      onChange={handleChange}
-      dynamicOption
-      emptyMessage="Type to create a new tag"
-    />
-  );
-}
-```
-
-### Custom option renderer
-
-```tsx
-type UserOption = AutocompleteItemProps & { email: string; role: string };
-
-const UserRow = ({ value, label, ...props }: UserOption) => (
-  <div className="flex flex-col gap-0.5 py-1">
-    <span className="font-medium text-sm text-foreground">{label}</span>
-    <span className="text-xs text-muted-foreground">{props.email}</span>
-  </div>
-);
-
-const users: UserOption[] = [
-  { value: "alice", label: "Alice", email: "alice@example.com", role: "admin", Render: UserRow },
-  { value: "bob", label: "Bob", email: "bob@example.com", role: "member", Render: UserRow },
-];
-
-<Autocomplete title="Assign to" options={users} value="" onChange={() => {}} />;
-```
-
-### Form integration
-
-```tsx
-import { Form } from "@g4rcez/components/form";
-import { Button } from "@g4rcez/components/button";
-
-const countries = [
-  { value: "br", label: "Brazil" },
-  { value: "us", label: "United States" },
-  { value: "de", label: "Germany" },
-];
-
-function ContactForm() {
-  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">
-      <Autocomplete
-        name="country"
-        title="Country"
-        options={countries}
-        required
-        emptyMessage="No countries found"
-      />
-      <Button theme="primary" type="submit">Submit</Button>
-    </Form>
-  );
-}
-```
-
-## Do
-
-- Provide a meaningful `emptyMessage` so users understand why no results appear.
-- Use `dynamicOption` when users should be able to add values not in the list.
-- Supply a custom `Render` component when each option needs to show more than its label (e.g., avatars, secondary text).
-- Prefer `Autocomplete` over `Select` for lists of more than ~15 items.
-
-## 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 `Autocomplete` for small lists where `Select` is simpler and faster.
-- Don't forget to handle the unselected case when `dynamicOption` is off and the user types but never picks an option.
-
-## Accessibility
-
-- Renders a `role="listbox"` dropdown managed by `@floating-ui/react`.
-- The visible input carries `aria-autocomplete="list"`.
-- Each option button has `aria-selected`, `aria-current`, and `aria-checked` set to reflect the active state.
-- Full keyboard navigation: Arrow Up/Down to move, Enter to select, Escape to close.
-- The caret button includes an `sr-only` label from the translation system.
-- Focus is returned to the trigger input when the dropdown closes.
-
-## Data Attributes
-
-- `data-value` — on the hidden `<input>`: the committed option value.
-- `data-shadow="true"` — on the visible text input to distinguish it from the real field.
-- `data-dynamic="true"` — on options injected by `dynamicOption`.
-- `data-initialized` — managed internally; used by `formReset` to track interaction state.
-- `data-floating="true"` — on the floating panel element.
-
-## Notes
-
-- The component renders two `<input>` elements: a visible shadow input for display/search and a hidden input with `name` that participates in form submission.
-- Option filtering uses a fuzzy-search (`fzf`) algorithm that matches partial text, abbreviations, and out-of-order characters against both `value` and `label`.
-- Large option lists are virtualized via `react-virtuoso` — rendering performance is maintained even with thousands of options.
-- The dropdown width always matches the width of the triggering fieldset.