@g4rcez/components 3.0.0 → 3.0.1

package/dist/ai/docs/DatePicker.md

@@ -0,0 +1,171 @@
+---
+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/dist/ai/docs/Dropdown.md

@@ -0,0 +1,223 @@
+---
+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, ChevronDownIcon } from "lucide-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
+          <ChevronDownIcon 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 { FilterIcon } from "lucide-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">
+          <FilterIcon 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/Empty.md

@@ -0,0 +1,163 @@
+---
+title: Empty
+description: Empty state placeholder displayed when a collection or data set contains no items.
+package: "@g4rcez/components"
+export: "{ Empty }"
+import: "import { Empty } from '@g4rcez/components'"
+category: display
+---
+
+# Empty
+
+Empty state placeholder displayed when a collection or data set contains no items.
+
+## Import
+
+```tsx
+import { Empty } from "@g4rcez/components";
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `Icon` | `React.FC<LucideProps>` | `FileIcon` | Lucide 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 |
+|-------|-------------|---------|
+| `text-disabled` | `--disabled` | Icon and message text color |
+
+## Examples
+
+### Default Empty State
+
+```tsx
+<Empty />
+```
+
+### Custom Message and Icon
+
+```tsx
+import { SearchXIcon } from "lucide-react";
+
+<Empty Icon={SearchXIcon} message="No results found" />
+```
+
+### In a Data Table
+
+```tsx
+import { DatabaseIcon } from "lucide-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>;
+}
+```
+
+### In a List
+
+```tsx
+import { InboxIcon } from "lucide-react";
+
+function TaskList({ tasks }: { tasks: Task[] }) {
+  return (
+    <div className="space-y-4">
+      <h2>My Tasks</h2>
+
+      {tasks.length === 0 ? (
+        <Empty Icon={InboxIcon} message="No tasks yet" />
+      ) : (
+        <ul>
+          {tasks.map((task) => (
+            <TaskItem key={task.id} task={task} />
+          ))}
+        </ul>
+      )}
+    </div>
+  );
+}
+```
+
+### With an Action
+
+```tsx
+import { Button } from "@g4rcez/components/button";
+import { FolderPlusIcon } from "lucide-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>
+  );
+}
+```
+
+### Contextual Icons
+
+```tsx
+import {
+  ShoppingCartIcon,
+  HeartIcon,
+  BellIcon,
+  MailIcon,
+} from "lucide-react";
+
+// Cart
+<Empty Icon={ShoppingCartIcon} message="Your cart is empty" />
+
+// Favorites
+<Empty Icon={HeartIcon} message="No favorites yet" />
+
+// Notifications
+<Empty Icon={BellIcon} message="No notifications" />
+
+// Messages
+<Empty Icon={MailIcon} message="No messages" />
+```
+
+## Do
+
+- Provide a clear, encouraging message that tells users what is missing.
+- Use an icon that is contextually relevant to the missing content type.
+- Pair `Empty` with an action button when the user can resolve the empty state.
+- Wrap `Empty` in a padded container for visual breathing room.
+
+## Don't
+
+- Don't pass raw Tailwind color classes (`text-gray-400`) for the icon — the component uses `text-disabled` from the design system.
+- Don't use arbitrary Tailwind values (`text-[#abc]`) — override CSS variables in your `@theme` block instead.
+- Don't use `Empty` for transient loading states — use `Skeleton` or `Spinner` instead.
+- Don't leave a blank space when data is missing; always provide visual feedback.
+- Don't use overly technical language in the empty state message.
+
+## Accessibility
+
+- The icon renders at `size={64}` using a Lucide component which includes accessible SVG markup.
+- The message uses a `<p>` element for semantic text.
+- Both icon and text use `text-disabled` ensuring sufficient contrast against the background.
+
+## Notes
+
+- The default message is sourced from the active locale translations via `useTranslations()`, so it localizes automatically when the app locale changes.
+- To override the default message permanently, pass an explicit `message` prop.

package/dist/ai/docs/Expand.md

@@ -0,0 +1,143 @@
+---
+title: Expand
+description: A button that expands in-place into a floating container using shared-element layout animations.
+package: "@g4rcez/components"
+export: "{ Expand }"
+import: "import { Expand } from '@g4rcez/components/expand'"
+category: floating
+---
+
+# Expand
+
+A button that expands in-place into a floating container using shared-element layout animations.
+
+## Import
+
+```tsx
+import { Expand } from "@g4rcez/components/expand";
+```
+
+## Props
+
+`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 |
+
+Inherits all `Button` props: `theme`, `size`, `rounded`, `className`, etc.
+
+## Design Tokens
+
+Tokens this component reads. Customize by overriding these CSS variables in your theme.
+
+| Token | CSS Variable | Purpose |
+|-------|-------------|---------|
+| `bg-background` | `--background` | Default expanded panel background (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.
+
+## Examples
+
+### Action FAB
+
+```tsx
+import { PlusIcon } from "lucide-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 with Label
+
+```tsx
+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>
+```
+
+### Controlled Expand
+
+```tsx
+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>
+  );
+}
+```
+
+## Do
+
+- Use `Expand` when you want the expanded panel to appear to "grow out of" the trigger button — the shared-element transition reinforces spatial context.
+- Apply design-token classes on the expanded content (`bg-background`, `border-border`, `shadow-shadow-floating`) for consistent theming.
+- Provide accessible `trigger` text or an icon with a `sr-only` label.
+
+## Don't
+
+- Don't use `Expand` when a standard `Dropdown` or `Modal` would feel more familiar to the user — the animation is distinctive and should be reserved for intentional moments.
+- Don't nest multiple `Expand` components inside each other; layout animations can conflict.
+- Don't pass raw Tailwind color classes (`bg-gray-50`, `border-gray-200`) inside the expanded content — use design-token classes.
+- Don't use arbitrary Tailwind values (`bg-[#abc]`, `shadow-[--my-shadow]`) — override CSS variables in your `@theme` block.
+
+## Accessibility
+
+- The trigger renders as a focusable `<button>` via the `Button` component.
+- `FloatingFocusManager` with `visuallyHiddenDismiss` and `closeOnFocusOut` manages focus correctly when the panel opens.
+- Pressing `Escape` closes the expanded panel (`useDismiss` with `escapeKey: true`).
+- Clicking outside also closes the panel (`outsidePress: true`).
+
+## Notes
+
+- Uses `motion/react` (`layoutId`) to animate a seamless transition between the collapsed button and the expanded container.
+- The expanded container is absolutely positioned at `-left-1/4 -top-3/4` by default. Override via `className` on the children wrapper if needed.
+- The `disabled` prop is forwarded to `useClick` — when `true`, the click interaction is enabled (the prop name is semantically inverted in the hook call, so pass `disabled={true}` to prevent expansion).
+- Rendered inside a `FloatingPortal` scoped to the component's own root `<div>` so it stays visually attached.