@g4rcez/components 4.0.1 → 4.1.1

package/ai/docs/DatePicker.md

@@ -0,0 +1,152 @@
+---
+title: DatePicker
+description: Date input with locale-aware masked entry and a floating calendar dropdown for visual selection.
+package: "@g4rcez/components"
+export: "{ DatePicker }"
+import: "import { DatePicker } from '@g4rcez/components/date-picker'"
+category: form
+---
+
+# DatePicker
+
+Date input with locale-aware masked entry and a floating calendar dropdown for visual selection.
+
+## Import
+
+```tsx
+import { DatePicker } from "@g4rcez/components/date-picker";
+```
+
+## Props
+
+`DatePicker` inherits all `Input` and `Calendar` props. Notable additions:
+
+| Prop           | Type                                | Default       | Description                                                                   |
+| -------------- | ----------------------------------- | ------------- | ----------------------------------------------------------------------------- |
+| `date`         | `Date`                              | -             | Controlled selected date                                                      |
+| `type`         | `"date" \| "datetime"`              | `"date"`      | Whether to include time (hour + minute) selection                             |
+| `floating`     | `boolean`                           | `true`        | Show the calendar in a floating `Dropdown`; set to `false` to embed it inline |
+| `clickToClose` | `boolean`                           | `false`       | Close the calendar immediately after a date is picked                         |
+| `locale`       | `Locales`                           | system locale | Locale for mask generation and calendar display                               |
+| `markToday`    | `boolean`                           | `true`        | Highlight today in the calendar                                               |
+| `disabledDate` | `(date: Date) => boolean`           | -             | Callback that returns `true` for dates that should be unselectable            |
+| `onChange`     | `(date: Date \| undefined) => void` | -             | Called with the new `Date` when input is valid, or `undefined` when cleared   |
+| `title`        | `string`                            | -             | Field label                                                                   |
+| `error`        | `string`                            | -             | Error message shown below the field                                           |
+| `required`     | `boolean`                           | `true`        | Marks field as required (default is `true` for DatePicker)                    |
+| `name`         | `string`                            | -             | Form field name — also the `id` of the hidden `<input type="date">`           |
+
+## 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 border color                 |
+| `text-foreground`        | `--foreground`          | Input text color                     |
+| `text-primary`           | `--primary`             | Focus ring and border on focus/hover |
+| `text-danger`            | `--danger`              | Error state text and border          |
+| `placeholder-input-mask` | `--input-mask`          | Placeholder text color               |
+| `bg-floating-background` | `--floating-background` | Calendar dropdown background         |
+| `border-floating-border` | `--floating-border`     | Calendar dropdown border             |
+
+## Examples
+
+### Basic date picker
+
+```tsx
+import { DatePicker } from "@g4rcez/components/date-picker";
+
+<DatePicker name="birthdate" title="Date of birth" />;
+```
+
+### Date and time
+
+```tsx
+<DatePicker name="appointment" title="Appointment time" type="datetime" clickToClose />
+```
+
+### Disabling past dates
+
+```tsx
+import { isBefore, startOfDay } from "date-fns";
+
+<DatePicker name="event_date" title="Event date" disabledDate={(date) => isBefore(date, startOfDay(new Date()))} />;
+```
+
+### Controlled value
+
+```tsx
+const [date, setDate] = useState<Date | undefined>();
+
+<DatePicker name="due_date" title="Due date" date={date} onChange={setDate} />;
+```
+
+### Inline calendar (no dropdown)
+
+```tsx
+<DatePicker name="check_in" title="Check-in" floating={false} />
+```
+
+### Inside a form
+
+```tsx
+import { Form } from "@g4rcez/components/form";
+import { Button } from "@g4rcez/components/button";
+
+function BookingForm() {
+    const handleSubmit = (e: React.FormEvent<HTMLFormElement>) => {
+        const data = new FormData(e.currentTarget);
+        console.log(data.get("check_in"), data.get("check_out"));
+    };
+
+    return (
+        <Form onSubmit={handleSubmit} className="flex flex-col gap-base">
+            <DatePicker name="check_in" title="Check-in" />
+            <DatePicker name="check_out" title="Check-out" />
+            <Button theme="primary" type="submit">
+                Book
+            </Button>
+        </Form>
+    );
+}
+```
+
+## Do
+
+- Use `disabledDate` to prevent invalid date selection (e.g., past dates for future bookings).
+- Use `type="datetime"` when both date and time are required for the use case.
+- Provide a clear `title` label.
+- Rely on `locale` for locale-aware mask and calendar generation rather than hardcoding a format.
+
+## 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 `DatePicker` when only a year or only a month is needed — a `Select` is more appropriate.
+- Don't assume users will always use the calendar; the masked text input must also be keyboard-friendly.
+
+## Accessibility
+
+- The calendar icon button includes an `aria-describedby` referencing a visually-hidden `<span>` with a translatable label.
+- The underlying `Input` component handles `aria-disabled`, `aria-readonly`, and `aria-busy`.
+- The calendar (`Calendar` component) is fully keyboard-navigable.
+- The input is masked to prevent invalid character entry, reducing validation friction.
+- Follows the standard `fieldset > label` structure from `InputField`.
+
+## Data Attributes
+
+- `data-component="date-picker"` — on the visible `Input`.
+- `data-value` — ISO string representation of the selected date (set on the visible input).
+- `data-target` — mirrors the `name` prop; used to link the shadow input to the hidden field.
+- `data-origin` — on the hidden `<input type="date">`: its `name` value, used by `formReset`.
+
+## Notes
+
+- The component renders two inputs: a visible masked `Input` for user interaction and a hidden `<input type="date">` (with `name`) for native form submission.
+- The input mask is generated dynamically from `Intl.DateTimeFormat.formatToParts`, so it automatically reflects the locale's date order (e.g., MM/DD/YYYY vs DD/MM/YYYY).
+- Date parsing uses `date-fns`. The `placeholder` is derived from the same locale format string.
+- When `floating={true}` (default), the calendar is rendered in a `Dropdown` using `@floating-ui/react` positioned to the right of the input.

package/ai/docs/Dropdown.md

@@ -0,0 +1,195 @@
+---
+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 → ai}/docs/Empty.md

@@ -19,17 +19,17 @@ import { Empty } from "@g4rcez/components";
 
 ## Props
 
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `Icon` | `Icon` | `FileIcon` | Phosphor icon component to display |
-| `message` | `string` | Localized "No data available" | Descriptive empty state message |
+| Prop      | Type     | Default                       | Description                        |
+| --------- | -------- | ----------------------------- | ---------------------------------- |
+| `Icon`    | `Icon`   | `FileIcon`                    | Phosphor icon component to display |
+| `message` | `string` | Localized "No data available" | Descriptive empty state message    |
 
 ## Design Tokens
 
 Tokens this component reads. Customize by overriding these CSS variables in your theme.
 
-| Token | CSS Variable | Purpose |
-|-------|-------------|---------|
+| Token           | CSS Variable | Purpose                     |
+| --------------- | ------------ | --------------------------- |
 | `text-disabled` | `--disabled` | Icon and message text color |
 
 ## Examples
@@ -45,7 +45,7 @@ Tokens this component reads. Customize by overriding these CSS variables in your
 ```tsx
 import { MagnifyingGlassMinusIcon } from "@phosphor-icons/react";
 
-<Empty Icon={MagnifyingGlassMinusIcon} message="No results found" />
+<Empty Icon={MagnifyingGlassMinusIcon} message="No results found" />;
 ```
 
 ### In a Data Table
@@ -54,15 +54,15 @@ import { MagnifyingGlassMinusIcon } from "@phosphor-icons/react";
 import { DatabaseIcon } from "@phosphor-icons/react";
 
 function DataTable({ data }: { data: Item[] }) {
-  if (data.length === 0) {
-    return (
-      <div className="py-12">
-        <Empty Icon={DatabaseIcon} message="No records found" />
-      </div>
-    );
-  }
-
-  return <table>{/* table content */}</table>;
+    if (data.length === 0) {
+        return (
+            <div className="py-12">
+                <Empty Icon={DatabaseIcon} message="No records found" />
+            </div>
+        );
+    }
+
+    return <table>{/* table content */}</table>;
 }
 ```
 
@@ -72,21 +72,21 @@ function DataTable({ data }: { data: Item[] }) {
 import { TrayIcon } from "@phosphor-icons/react";
 
 function TaskList({ tasks }: { tasks: Task[] }) {
-  return (
-    <div className="space-y-4">
-      <h2>My Tasks</h2>
-
-      {tasks.length === 0 ? (
-        <Empty Icon={TrayIcon} message="No tasks yet" />
-      ) : (
-        <ul>
-          {tasks.map((task) => (
-            <TaskItem key={task.id} task={task} />
-          ))}
-        </ul>
-      )}
-    </div>
-  );
+    return (
+        <div className="space-y-4">
+            <h2>My Tasks</h2>
+
+            {tasks.length === 0 ? (
+                <Empty Icon={TrayIcon} message="No tasks yet" />
+            ) : (
+                <ul>
+                    {tasks.map((task) => (
+                        <TaskItem key={task.id} task={task} />
+                    ))}
+                </ul>
+            )}
+        </div>
+    );
 }
 ```
 
@@ -97,19 +97,16 @@ import { Button } from "@g4rcez/components/button";
 import { FolderPlusIcon } from "@phosphor-icons/react";
 
 function EmptyProjectsList() {
-  return (
-    <div className="text-center py-12">
-      <Empty
-        Icon={FolderPlusIcon}
-        message="You haven't created any projects yet"
-      />
-      <div className="mt-6">
-        <Button theme="primary" onClick={handleCreate}>
-          Create Your First Project
-        </Button>
-      </div>
-    </div>
-  );
+    return (
+        <div className="text-center py-12">
+            <Empty Icon={FolderPlusIcon} message="You haven't created any projects yet" />
+            <div className="mt-6">
+                <Button theme="primary" onClick={handleCreate}>
+                    Create Your First Project
+                </Button>
+            </div>
+        </div>
+    );
 }
 ```
 

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

@@ -21,12 +21,12 @@ import { Expand } from "@g4rcez/components/expand";
 
 `Expand` accepts all `Button` props plus the following:
 
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `trigger` | `Label` | — | Content displayed on the button before expansion |
-| `open` | `boolean` | `false` | Controlled open state |
-| `disabled` | `boolean` | `false` | When `true`, the button cannot be expanded |
-| `children` | `React.ReactNode` | — | Content shown inside the expanded floating container |
+| Prop       | Type              | Default | Description                                          |
+| ---------- | ----------------- | ------- | ---------------------------------------------------- |
+| `trigger`  | `Label`           | —       | Content displayed on the button before expansion     |
+| `open`     | `boolean`         | `false` | Controlled open state                                |
+| `disabled` | `boolean`         | `false` | When `true`, the button cannot be expanded           |
+| `children` | `React.ReactNode` | —       | Content shown inside the expanded floating container |
 
 Inherits all `Button` props: `theme`, `size`, `rounded`, `className`, etc.
 
@@ -34,10 +34,10 @@ Inherits all `Button` props: `theme`, `size`, `rounded`, `className`, etc.
 
 Tokens this component reads. Customize by overriding these CSS variables in your theme.
 
-| Token | CSS Variable | Purpose |
-|-------|-------------|---------|
+| Token           | CSS Variable   | Purpose                                                 |
+| --------------- | -------------- | ------------------------------------------------------- |
 | `bg-background` | `--background` | Default expanded panel background (applied by consumer) |
-| `border-border` | `--border` | Default expanded panel border (applied by consumer) |
+| `border-border` | `--border`     | Default expanded panel border (applied by consumer)     |
 
 The `Expand` component itself only renders the trigger button and an animated wrapper; visual tokens for the expanded content are your responsibility via `children` className.
 
@@ -49,28 +49,19 @@ The `Expand` component itself only renders the trigger button and an animated wr
 import { PlusIcon } from "@phosphor-icons/react";
 import { Expand } from "@g4rcez/components/expand";
 
-<Expand
-  trigger={<PlusIcon size={16} />}
-  theme="primary"
-  size="icon"
-  rounded="circle"
->
-  <div className="w-64 rounded-card border border-border bg-background p-4 shadow-shadow-floating">
-    <h3 className="font-bold mb-2 text-foreground">Create New</h3>
-    <ul className="space-y-2">
-      <li>
-        <button className="w-full rounded-button p-2 text-left text-foreground hover:bg-muted">
-          Project
-        </button>
-      </li>
-      <li>
-        <button className="w-full rounded-button p-2 text-left text-foreground hover:bg-muted">
-          Task
-        </button>
-      </li>
-    </ul>
-  </div>
-</Expand>
+<Expand trigger={<PlusIcon size={16} />} theme="primary" size="icon" rounded="circle">
+    <div className="w-64 rounded-card border border-border bg-background p-4 shadow-shadow-floating">
+        <h3 className="font-bold mb-2 text-foreground">Create New</h3>
+        <ul className="space-y-2">
+            <li>
+                <button className="w-full rounded-button p-2 text-left text-foreground hover:bg-muted">Project</button>
+            </li>
+            <li>
+                <button className="w-full rounded-button p-2 text-left text-foreground hover:bg-muted">Task</button>
+            </li>
+        </ul>
+    </div>
+</Expand>;
 ```
 
 ### Expand with Label
@@ -80,11 +71,13 @@ import { Expand } from "@g4rcez/components/expand";
 import { Button } from "@g4rcez/components/button";
 
 <Expand trigger="Open Menu">
-  <div className="rounded-card border border-border bg-background p-4 shadow-shadow-floating">
-    <p className="text-foreground">Expanded content goes here.</p>
-    <Button theme="primary" className="mt-2">Action</Button>
-  </div>
-</Expand>
+    <div className="rounded-card border border-border bg-background p-4 shadow-shadow-floating">
+        <p className="text-foreground">Expanded content goes here.</p>
+        <Button theme="primary" className="mt-2">
+            Action
+        </Button>
+    </div>
+</Expand>;
 ```
 
 ### Controlled Expand
@@ -94,24 +87,17 @@ import { useState } from "react";
 import { Expand } from "@g4rcez/components/expand";
 
 function ControlledExpand() {
-  const [open, setOpen] = useState(false);
-
-  return (
-    <Expand
-      trigger="Options"
-      open={open}
-      theme="ghost-neutral"
-    >
-      <div className="rounded-card border border-border bg-background p-4 shadow-shadow-floating">
-        <button
-          onClick={() => setOpen(false)}
-          className="text-sm text-foreground"
-        >
-          Close
-        </button>
-      </div>
-    </Expand>
-  );
+    const [open, setOpen] = useState(false);
+
+    return (
+        <Expand trigger="Options" open={open} theme="ghost-neutral">
+            <div className="rounded-card border border-border bg-background p-4 shadow-shadow-floating">
+                <button onClick={() => setOpen(false)} className="text-sm text-foreground">
+                    Close
+                </button>
+            </div>
+        </Expand>
+    );
 }
 ```