@g4rcez/components 4.0.1 → 4.1.1

package/ai/docs/Tooltip.md

@@ -0,0 +1,231 @@
+---
+title: Tooltip
+description: Polymorphic tooltip with hover, focus, and click triggers; supports cursor-following and rich content.
+package: "@g4rcez/components"
+export: "{ Tooltip }"
+import: "import { Tooltip } from '@g4rcez/components/tooltip'"
+category: floating
+---
+
+# Tooltip
+
+Polymorphic tooltip with hover, focus, and click triggers; supports cursor-following and rich content.
+
+## Import
+
+```tsx
+import { Tooltip } from "@g4rcez/components/tooltip";
+```
+
+## Props
+
+| Prop           | Type                      | Default  | Description                                                   |
+| -------------- | ------------------------- | -------- | ------------------------------------------------------------- |
+| `title`        | `Label`                   | —        | Tooltip trigger element — the element the user interacts with |
+| `children`     | `React.ReactNode`         | —        | Tooltip popup content                                         |
+| `open`         | `boolean`                 | —        | Controlled open state                                         |
+| `enabled`      | `boolean`                 | `true`   | Enable or disable the tooltip entirely                        |
+| `hover`        | `boolean`                 | `true`   | Show tooltip on hover                                         |
+| `focus`        | `boolean`                 | `true`   | Show tooltip on focus                                         |
+| `popover`      | `boolean`                 | `true`   | Show tooltip on click                                         |
+| `placement`    | `Placement`               | auto     | Preferred placement; falls back via `autoPlacement`           |
+| `followCursor` | `boolean`                 | `false`  | Tooltip follows the mouse cursor position                     |
+| `onChange`     | `(open: boolean) => void` | —        | Open state change handler                                     |
+| `as`           | `React.ElementType`       | `"span"` | HTML element to render the trigger wrapper as                 |
+
+> Note: `title` is the **trigger** and `children` is the **popup content**. This is the inverse of the HTML `title` attribute convention — the prop name matches how the component API evolved.
+
+## Design Tokens
+
+Tokens this component reads. Customize by overriding these CSS variables in your theme.
+
+| Token                     | CSS Variable           | Purpose                               |
+| ------------------------- | ---------------------- | ------------------------------------- |
+| `bg-tooltip-background`   | `--tooltip-background` | Tooltip popup background              |
+| `text-tooltip-foreground` | `--tooltip-foreground` | Tooltip popup text color              |
+| `border-tooltip-border`   | `--tooltip-border`     | Tooltip popup border and arrow stroke |
+| `fill-tooltip-background` | `--tooltip-background` | Arrow fill color                      |
+| `z-tooltip`               | `--z-tooltip`          | Z-index of the tooltip popup          |
+| `shadow-shadow-floating`  | `--shadow-floating`    | Tooltip drop shadow                   |
+
+## Placement Options
+
+Supports all Floating UI placements: `"top"`, `"top-start"`, `"top-end"`, `"bottom"`, `"bottom-start"`, `"bottom-end"`, `"left"`, `"left-start"`, `"left-end"`, `"right"`, `"right-start"`, `"right-end"`. When `placement` is omitted, `autoPlacement` picks the best available side.
+
+## Examples
+
+### Basic Hover Tooltip
+
+```tsx
+import { Tooltip } from "@g4rcez/components/tooltip";
+
+<Tooltip title={<button className="px-4 py-2 bg-primary text-primary-foreground rounded-button">Hover me</button>}>
+    This is a helpful tooltip
+</Tooltip>;
+```
+
+### Icon Button with Label
+
+```tsx
+import { FloppyDiskIcon } from "@phosphor-icons/react";
+import { Tooltip } from "@g4rcez/components/tooltip";
+import { Button } from "@g4rcez/components/button";
+
+<Tooltip
+    title={
+        <Button size="icon" theme="ghost-neutral">
+            <FloppyDiskIcon size={16} />
+        </Button>
+    }
+>
+    Save (Ctrl+S)
+</Tooltip>;
+```
+
+### Interaction Modes
+
+```tsx
+import { Tooltip } from "@g4rcez/components/tooltip";
+
+{
+    /* Hover only */
+}
+<Tooltip title={<button className="px-4 py-2 rounded-button border border-border text-foreground">Hover Only</button>} focus={false} popover={false}>
+    Shown on hover
+</Tooltip>;
+
+{
+    /* Focus only — keyboard accessible */
+}
+<Tooltip
+    title={<input placeholder="Focus me with tab" className="px-3 py-2 rounded-button border border-border bg-background text-foreground" />}
+    hover={false}
+    popover={false}
+>
+    Shown on focus
+</Tooltip>;
+
+{
+    /* Click only — acts like a popover */
+}
+<Tooltip title={<button className="px-4 py-2 bg-primary text-primary-foreground rounded-button">Click me</button>} hover={false} focus={false}>
+    Shown on click
+</Tooltip>;
+```
+
+### Cursor-Following Tooltip
+
+```tsx
+import { Tooltip } from "@g4rcez/components/tooltip";
+
+<Tooltip
+    followCursor
+    placement="top-start"
+    title={
+        <div className="w-full h-32 rounded-card border border-border bg-muted flex items-center justify-center">
+            <span className="text-muted-foreground">Move your mouse over this area</span>
+        </div>
+    }
+>
+    Follows your cursor
+</Tooltip>;
+```
+
+### Controlled Tooltip
+
+```tsx
+import { useState } from "react";
+import { Tooltip } from "@g4rcez/components/tooltip";
+
+function ControlledTooltip() {
+    const [isOpen, setIsOpen] = useState(false);
+
+    return (
+        <>
+            <Tooltip
+                title={<button className="px-4 py-2 rounded-button border border-border text-foreground">Target</button>}
+                open={isOpen}
+                onChange={setIsOpen}
+                hover={false}
+                focus={false}
+                popover={false}
+            >
+                Externally controlled
+            </Tooltip>
+
+            <div className="mt-4 flex gap-2">
+                <button onClick={() => setIsOpen(true)} className="px-3 py-1 bg-primary text-primary-foreground rounded-button text-sm">
+                    Show
+                </button>
+                <button onClick={() => setIsOpen(false)} className="px-3 py-1 bg-muted text-foreground rounded-button text-sm">
+                    Hide
+                </button>
+            </div>
+        </>
+    );
+}
+```
+
+### Polymorphic — Render as Different Elements
+
+```tsx
+import { Tooltip } from "@g4rcez/components/tooltip";
+
+{
+    /* Render as <div> */
+}
+<Tooltip as="div" title={<span className="p-3 bg-muted rounded-button inline-block text-foreground">Div with tooltip</span>}>
+    Tooltip on a div
+</Tooltip>;
+
+{
+    /* Wrap a paragraph */
+}
+<Tooltip as="p" title={<span className="text-primary cursor-pointer">Hover this paragraph</span>}>
+    Paragraph tooltip
+</Tooltip>;
+```
+
+### Form Field Help Tooltip
+
+```tsx
+import { InfoIcon } from "@phosphor-icons/react";
+import { Tooltip } from "@g4rcez/components/tooltip";
+
+<label className="block text-sm font-medium text-foreground mb-1">
+    Username
+    <Tooltip title={<InfoIcon className="inline ml-1 text-muted-foreground cursor-help" size={14} />}>
+        3–20 characters; letters, numbers, and underscores only
+    </Tooltip>
+</label>;
+```
+
+## Do
+
+- Always keep `focus={true}` (default) so keyboard users can access tooltips via Tab navigation.
+- Keep tooltip content short — one or two sentences at most.
+- Use `followCursor` for large interactive areas (charts, canvases) to keep the tip near the pointer.
+- Use design-token classes for any custom elements inside the tooltip popup (`text-tooltip-foreground`, `bg-muted`, etc.).
+
+## Don't
+
+- Don't put essential information only in a tooltip — users on touch devices may never see it.
+- Don't use tooltips for long text or complex layouts — use `Modal` or `Dropdown` instead.
+- Don't pass raw Tailwind color classes (`bg-gray-900`, `text-white`) inside tooltip content — use design-token classes.
+- Don't use arbitrary Tailwind values (`bg-[#abc]`, `z-[9999]`) — override CSS variables in your `@theme` block.
+- Don't use tooltips on elements that are already self-explanatory.
+
+## Accessibility
+
+- By default all three triggers are active (`hover`, `focus`, `popover`); disable `focus` only when the trigger itself provides equivalent keyboard affordance.
+- The tooltip popup receives `role="tooltip"` via Floating UI's `useRole`.
+- `useDismiss` closes the tooltip when focus moves away or `Escape` is pressed.
+- Safe-polygon hover handling keeps the tooltip open while the pointer moves toward interactive content (`popover={true}` enables this).
+- The `as` prop lets you place the reference on a semantically correct element without extra wrapper divs.
+
+## Notes
+
+- The `open` prop syncs to internal state via `useEffect`; when provided, external changes override internal toggle state.
+- `autoPlacement` middleware runs alongside `flip` — placement is fully automatic when `placement` is omitted.
+- Hover delay is controlled by the shared `FLOATING_DELAY` constant; there is no per-instance delay prop.
+- The component is polymorphic via the `Polymorph` core component for the popup and `as` for the trigger wrapper.

package/ai/docs/Typography.md

@@ -0,0 +1,187 @@
+---
+title: Typography
+description: A set of text and page-structure components for consistent typographic styling.
+package: "@g4rcez/components"
+export: "{ Paragraph, Description, Info, PageTitle, PageHeader }"
+import: "import { Paragraph, Description, Info, PageTitle, PageHeader } from '@g4rcez/components'"
+category: core
+---
+
+# Typography
+
+A set of text and page-structure components for consistent typographic styling across the application. Exports `Paragraph`, `Description`, `Info`, `PageTitle`, and `PageHeader`.
+
+## Import
+
+```tsx
+import { Paragraph, Description, Info, PageTitle, PageHeader } from "@g4rcez/components";
+```
+
+## Props
+
+### Paragraph
+
+Renders a `<p>` element with `text-base leading-snug`.
+
+| Prop        | Type                        | Default | Description                   |
+| ----------- | --------------------------- | ------- | ----------------------------- |
+| `children`  | `React.ReactNode`           | -       | Paragraph content             |
+| `className` | `string`                    | -       | Additional CSS classes        |
+| `...props`  | `React.ComponentProps<"p">` | -       | All standard `<p>` attributes |
+
+### Description
+
+Renders a `<p>` element with `text-sm text-secondary mb-kilo`.
+
+| Prop        | Type                        | Default | Description                   |
+| ----------- | --------------------------- | ------- | ----------------------------- |
+| `children`  | `React.ReactNode`           | -       | Description content           |
+| `className` | `string`                    | -       | Additional CSS classes        |
+| `...props`  | `React.ComponentProps<"p">` | -       | All standard `<p>` attributes |
+
+### Info
+
+Renders a labeled key-value pair in a flex container.
+
+| Prop              | Type              | Default | Description                                                |
+| ----------------- | ----------------- | ------- | ---------------------------------------------------------- |
+| `label`           | `Label`           | -       | The label text (required)                                  |
+| `children`        | `React.ReactNode` | -       | The value content                                          |
+| `row`             | `boolean`         | `false` | Renders label and value side-by-side instead of stacked    |
+| `disabled`        | `Label`           | -       | When set, applies `text-disabled` to the value             |
+| `className`       | `string`          | -       | Additional classes for the container                       |
+| `info`            | `Label`           | -       | Reserved field (available in type, not currently rendered) |
+| `infoDescription` | `string`          | -       | Reserved field (available in type, not currently rendered) |
+
+### PageTitle
+
+Renders an `<h2>` title with a paragraph subtitle.
+
+| Prop       | Type              | Default | Description                               |
+| ---------- | ----------------- | ------- | ----------------------------------------- |
+| `title`    | `string`          | -       | Main title text (required)                |
+| `children` | `React.ReactNode` | -       | Subtitle or description beneath the title |
+
+### PageHeader
+
+Renders a `<header>` element with title/description on the left and action slots on the right.
+
+| Prop          | Type              | Default | Description                                    |
+| ------------- | ----------------- | ------- | ---------------------------------------------- |
+| `title`       | `string`          | -       | Page title (required)                          |
+| `description` | `Label`           | -       | Short description beneath the title (required) |
+| `children`    | `React.ReactNode` | -       | Action buttons or other right-aligned content  |
+
+## Design Tokens
+
+Tokens these components read. Customize by overriding these CSS variables in your theme.
+
+| Token            | CSS Variable     | Purpose                                  |
+| ---------------- | ---------------- | ---------------------------------------- |
+| `text-secondary` | `--secondary`    | Description and subtitle text color      |
+| `text-disabled`  | `--disabled`     | Disabled value text in `Info`            |
+| `mb-kilo`        | `--spacing-kilo` | Bottom margin on `Description`           |
+| `gap-mega`       | `--spacing-mega` | Gap in `PageHeader` between sections     |
+| `gap-kilo`       | `--spacing-kilo` | Gap between action items in `PageHeader` |
+
+## Examples
+
+### Page Header with Actions
+
+```tsx
+import { Button } from "@g4rcez/components/button";
+
+<PageHeader title="Orders" description="List of all orders from your shop">
+    <Button size="small">Export CSV</Button>
+    <Button theme="primary" size="small">
+        Create Order
+    </Button>
+</PageHeader>;
+```
+
+### Standalone Page Title
+
+```tsx
+<PageTitle title="Dashboard">Overview of your application metrics</PageTitle>
+```
+
+### Paragraph and Description
+
+```tsx
+<Paragraph>
+  This is a standard paragraph with base font size and snug line height.
+</Paragraph>
+
+<Description>
+  Secondary description text, typically used beneath form fields or titles.
+</Description>
+```
+
+### Info — Stacked (default)
+
+```tsx
+<Info label="Full Name">John Doe</Info>
+<Info label="Email">john@example.com</Info>
+<Info label="Role">Administrator</Info>
+```
+
+### Info — Row Layout
+
+```tsx
+<Info label="Status" row>Active</Info>
+<Info label="Plan" row>Pro</Info>
+```
+
+### Info — Disabled Value
+
+```tsx
+<Info label="API Key" disabled="true">
+    sk-••••••••••••••••
+</Info>
+```
+
+### Profile Card
+
+```tsx
+<div className="flex flex-col gap-base rounded-card border border-border bg-card-background p-4">
+    <PageTitle title="John Doe">Software Engineer</PageTitle>
+    <div className="flex flex-col gap-sm">
+        <Info label="Email" row>
+            john@example.com
+        </Info>
+        <Info label="Team" row>
+            Platform
+        </Info>
+        <Info label="Joined" row>
+            March 2024
+        </Info>
+    </div>
+</div>
+```
+
+## Do
+
+- Use `PageHeader` at the top of every page for consistent title + action layout
+- Use `Paragraph` instead of raw `<p>` to inherit consistent base styling
+- Use `Description` for secondary/supporting text — it signals lower visual hierarchy
+- Use design-token classes for any additional styling (`text-foreground`, `bg-background`)
+
+## Don't
+
+- Don't use `PageTitle` more than once per page — it represents the page's main topic
+- Don't pass raw Tailwind color classes (`text-gray-500`, `text-black`) — use `text-secondary` or `text-foreground`
+- Don't use arbitrary Tailwind values (`text-[#555]`) — override CSS variables in your `@theme` block
+- Don't use `Info` for long-form content — it is designed for short labeled values
+
+## Accessibility
+
+- `PageTitle` renders an `<h2>` — ensure there is an `<h1>` elsewhere on the page
+- `PageHeader` wraps content in a semantic `<header>` element
+- `Info` labels are `<span>` elements; if the label identifies a form field, prefer a `<label>` with `htmlFor` instead
+- `Description` text should be concise and supplementary — do not place critical content only in `Description`
+
+## Notes
+
+- All components accept standard HTML props for their root element and merge `className` correctly
+- `PageHeader` uses `gap-mega` and `gap-kilo` spacing tokens — override these in `@theme` to adjust layout rhythm
+- `Info` with `disabled` prop applies `text-disabled` to the value span only, not the label

package/ai/docs/Wizard.md

@@ -0,0 +1,208 @@
+---
+title: Wizard
+description: Guided tour overlay that highlights page elements step-by-step with animated SVG masking and floating tooltips.
+package: "@g4rcez/components"
+export: "{ Wizard }"
+import: "import { Wizard } from '@g4rcez/components'"
+category: floating
+---
+
+# Wizard
+
+Guided tour overlay that highlights page elements step-by-step with animated SVG masking and floating tooltips.
+
+## Import
+
+```tsx
+import { Wizard } from "@g4rcez/components";
+```
+
+## Props
+
+### Wizard
+
+| Prop       | Type                                                                   | Default | Description                                        |
+| ---------- | ---------------------------------------------------------------------- | ------- | -------------------------------------------------- |
+| `active`   | `boolean`                                                              | `false` | Controls whether the wizard is visible             |
+| `steps`    | `WizardStep[]`                                                         | —       | Ordered array of step configurations               |
+| `onClose`  | `() => void`                                                           | —       | Callback when the user skips or dismisses the tour |
+| `onFinish` | `() => void`                                                           | —       | Callback when the last step is completed           |
+| `onChange` | `(index: number) => void`                                              | —       | Callback fired when the step index changes         |
+| `labels`   | `{ next?: string; skip?: string; finish?: string; previous?: string }` | —       | Override button labels                             |
+
+### WizardStep
+
+| Prop          | Type                                                    | Default    | Description                                             |
+| ------------- | ------------------------------------------------------- | ---------- | ------------------------------------------------------- |
+| `element`     | `string \| Element \| React.RefObject<Element \| null>` | —          | Target element: CSS selector, DOM element, or React ref |
+| `title`       | `React.ReactNode`                                       | —          | Step title displayed in the tooltip                     |
+| `description` | `React.ReactNode`                                       | —          | Step body content                                       |
+| `side`        | `Placement`                                             | `"bottom"` | Tooltip placement relative to the target element        |
+| `onEnter`     | `() => void`                                            | —          | Called when this step becomes active                    |
+| `onNext`      | `() => void`                                            | —          | Called before advancing to the next step                |
+| `onPrevious`  | `() => void`                                            | —          | Called before going back to the previous step           |
+
+## Design Tokens
+
+Tokens this component reads. Customize by overriding these CSS variables in your theme.
+
+| Token                    | CSS Variable            | Purpose                                     |
+| ------------------------ | ----------------------- | ------------------------------------------- |
+| `text-floating-overlay`  | `--floating-overlay`    | SVG mask fill color (`/70` opacity applied) |
+| `bg-floating-background` | `--floating-background` | Step tooltip surface background             |
+| `border-floating-border` | `--floating-border`     | Step tooltip border and footer divider      |
+| `z-wizard`               | `--z-wizard`            | Z-index for the overlay layer               |
+| `z-floating`             | `--z-floating`          | Z-index for the step tooltip                |
+| `text-muted-foreground`  | `--muted-foreground`    | Step counter and skip button text           |
+| `text-foreground`        | `--foreground`          | Skip button hover text                      |
+
+## Examples
+
+### Basic Two-Step Tour
+
+```tsx
+import { useState } from "react";
+import { Wizard } from "@g4rcez/components";
+import { Button } from "@g4rcez/components/button";
+
+function OnboardingTour() {
+    const [active, setActive] = useState(false);
+
+    const steps = [
+        {
+            element: "#create-button",
+            title: "Create something new",
+            description: "Use this button to create a new project.",
+            side: "bottom" as const,
+        },
+        {
+            element: "#notifications-bell",
+            title: "Stay up to date",
+            description: "Check here for the latest updates.",
+            side: "left" as const,
+        },
+    ];
+
+    return (
+        <>
+            <Button onClick={() => setActive(true)}>Start Tour</Button>
+
+            <Wizard
+                active={active}
+                steps={steps}
+                onClose={() => setActive(false)}
+                onFinish={() => {
+                    setActive(false);
+                    console.log("Tour complete");
+                }}
+            />
+        </>
+    );
+}
+```
+
+### Using Refs as Targets
+
+```tsx
+import { useRef, useState } from "react";
+import { Wizard } from "@g4rcez/components";
+import { Button } from "@g4rcez/components/button";
+
+function RefTour() {
+    const [active, setActive] = useState(false);
+    const buttonRef = useRef<HTMLButtonElement>(null);
+
+    const steps = [
+        {
+            element: buttonRef,
+            title: "Action Button",
+            description: "Click here to perform the primary action.",
+            side: "right" as const,
+        },
+    ];
+
+    return (
+        <>
+            <Button ref={buttonRef} theme="primary">
+                Primary Action
+            </Button>
+
+            <Wizard active={active} steps={steps} onClose={() => setActive(false)} labels={{ finish: "Got it!", skip: "No thanks" }} />
+        </>
+    );
+}
+```
+
+### Step Lifecycle Callbacks
+
+```tsx
+const steps = [
+    {
+        element: "#dashboard-chart",
+        title: "Your Analytics",
+        description: "This chart shows activity for the last 30 days.",
+        onEnter: () => console.log("User reached analytics step"),
+        onNext: () => console.log("User advancing past analytics"),
+    },
+    {
+        element: "#export-button",
+        title: "Export Data",
+        description: "Download your data at any time.",
+        side: "left" as const,
+    },
+];
+```
+
+### Custom Labels
+
+```tsx
+<Wizard
+    active={active}
+    steps={steps}
+    onClose={() => setActive(false)}
+    onFinish={() => setActive(false)}
+    labels={{
+        next: "Continue",
+        previous: "Back",
+        skip: "Skip tour",
+        finish: "Done",
+    }}
+/>
+```
+
+## Do
+
+- Keep tours to 3–7 steps; fewer steps are completed more often.
+- Ensure target elements are visible in the viewport when each step activates — the wizard scrolls to them automatically.
+- Always provide `onClose` so users can exit at any time without completing the tour.
+- Use `onEnter` to trigger any side effects that make the target element visible (e.g., open a panel) before the step highlights it.
+
+## Don't
+
+- Don't use the wizard for critical information that isn't accessible elsewhere — some users will skip it.
+- Don't pass more than ~10 steps; tours that feel long are abandoned.
+- Don't block users from navigating if they skip the wizard.
+- Don't pass raw Tailwind color classes in `title` or `description` content — use design-token classes.
+- Don't use arbitrary Tailwind values (`z-[9999]`) — the wizard already uses `z-wizard`; override the CSS variable if needed.
+
+## Accessibility
+
+- The wizard renders in a `FloatingPortal` above all other content.
+- The SVG mask highlights the target element using `pointer-events-auto` so users can interact with it during the tour.
+- Navigation buttons use the `Button` component and are keyboard accessible.
+- Step progress is shown as `{current} / {total}` in the tooltip corner.
+- The `FloatingArrow` provides a visual pointer connecting the tooltip to the target element.
+
+## Data Attributes
+
+| Attribute                 | Applied to            | Description                        |
+| ------------------------- | --------------------- | ---------------------------------- |
+| `data-component="wizard"` | Main wizard container | Identifies the wizard overlay root |
+
+## Notes
+
+- The SVG mask uses a `<motion.rect>` that animates to the target element's bounding rect with a spring transition. The tooltip appears only after the animation completes (`onAnimationComplete`).
+- The overlay is `pointer-events-none` except for the mask rect, which is `pointer-events-auto` — this allows clicking the highlighted element while the tour is active.
+- When `element` resolves to `null` (selector not found or ref is empty), the tooltip centers on the screen and a console warning is emitted.
+- `useResizeObserver` and scroll/resize event listeners keep the highlight rect in sync as the layout changes.
+- The `labels` prop values fall back to the global translations provided by `useTranslations`.