@g4rcez/components 3.0.0 → 3.0.1

package/dist/ai/docs/TransferList.md

@@ -0,0 +1,142 @@
+---
+title: TransferList
+description: Two-panel component for moving items between a source list and a target list.
+package: "@g4rcez/components"
+export: "{ TransferList }"
+import: "import { TransferList } from '@g4rcez/components/transfer-list'"
+category: form
+---
+
+# TransferList
+
+Two-panel component for moving items between a source list and a target list.
+
+## Import
+
+```tsx
+import { TransferList } from "@g4rcez/components/transfer-list";
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `source` | `T[]` | — | Items in the left (available) list. |
+| `target` | `T[]` | — | Items in the right (selected) list. |
+| `Item` | `React.FC<{ data: T }>` | — | Component used to render each list row. |
+| `reference` | `keyof T` | — | Unique key used to identify and compare items (e.g., `"id"`). |
+| `setSource` | `Dispatch<SetStateAction<T[]>>` | — | State setter for the source list. |
+| `setTarget` | `Dispatch<SetStateAction<T[]>>` | — | State setter for the target list. |
+
+## Design Tokens
+
+Tokens this component reads. Customize by overriding these CSS variables in your theme.
+
+| Token | CSS Variable | Purpose |
+|-------|-------------|---------|
+| `border-card-border` | `--card-border` | Border around each list panel |
+| `bg-background` | `--background` | Panel background (inherited) |
+| `text-foreground` | `--foreground` | Item text color (inherited) |
+| `border-border` | `--border` | Section divider inside the panel header |
+
+## Examples
+
+### Basic transfer list
+
+```tsx
+import { useState } from "react";
+import { TransferList } from "@g4rcez/components/transfer-list";
+
+type Role = { id: string; name: string };
+
+const allRoles: Role[] = [
+  { id: "admin", name: "Administrator" },
+  { id: "editor", name: "Editor" },
+  { id: "viewer", name: "Viewer" },
+  { id: "auditor", name: "Auditor" },
+];
+
+const RoleItem: React.FC<{ data: Role }> = ({ data }) => (
+  <span className="text-sm text-foreground">{data.name}</span>
+);
+
+export default function RoleAssignment() {
+  const [available, setAvailable] = useState(allRoles);
+  const [assigned, setAssigned] = useState<Role[]>([]);
+
+  return (
+    <TransferList
+      source={available}
+      target={assigned}
+      setSource={setAvailable}
+      setTarget={setAssigned}
+      reference="id"
+      Item={RoleItem}
+    />
+  );
+}
+```
+
+### With custom item rendering
+
+```tsx
+import { ShieldIcon } from "lucide-react";
+import { TransferList } from "@g4rcez/components/transfer-list";
+
+type Permission = { id: string; label: string; scope: string };
+
+const PermissionItem: React.FC<{ data: Permission }> = ({ data }) => (
+  <span className="flex items-center gap-base">
+    <ShieldIcon size={14} className="text-primary" />
+    <span className="text-sm text-foreground">{data.label}</span>
+    <span className="ml-auto text-xs text-muted-foreground">{data.scope}</span>
+  </span>
+);
+
+export default function PermissionManager() {
+  const [source, setSource] = useState(allPermissions);
+  const [target, setTarget] = useState<Permission[]>([]);
+
+  return (
+    <TransferList
+      source={source}
+      target={target}
+      setSource={setSource}
+      setTarget={setTarget}
+      reference="id"
+      Item={PermissionItem}
+    />
+  );
+}
+```
+
+## Do
+
+- Provide a unique, stable `reference` key for each item (typically the primary key from your data model).
+- Use `TransferList` when users need to pick a significant number of items from a large pool.
+- Keep the `Item` component focused on displaying — handle mutations via `setSource` / `setTarget`.
+- Use design-token classes inside `Item` for text and icon colors (`text-foreground`, `text-primary`, `text-muted-foreground`).
+
+## Don't
+
+- Don't use `TransferList` for very small lists (3–5 items) where `MultiSelect` or a `Checkbox` group would be faster.
+- Don't perform expensive side effects inside the `Item` component — keep it purely presentational.
+- 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]`) — override CSS variables in your `@theme` block instead.
+
+## Accessibility
+
+- Each item is rendered with a `Checkbox` for selection, giving it full keyboard and screen-reader support.
+- Lists are virtualized using `react-virtuoso` for performance with large datasets.
+- Transfer buttons use `ChevronRightIcon` from `lucide-react` and should have descriptive `aria-label` attributes when used.
+
+## Data Attributes
+
+The `TransferList` component does not set component-specific `data-*` attributes directly. Individual list items inherit `data-component` and accessibility attributes from the embedded `Checkbox` components.
+
+## Notes
+
+- Uses `react-virtuoso` with a `useWindowScroll` strategy — the list height adapts to the parent container via `useParentHeight`.
+- The source panel includes a built-in `Input` search field for quick filtering.
+- The component is a generic `<T extends POJO>` — TypeScript will infer `T` from `source` and `target` props.
+- Only the source-to-target transfer button (`ChevronRightIcon`) is currently wired in the implementation; bidirectional transfer requires wiring additional buttons if needed.

package/dist/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/dist/ai/docs/Wizard.md

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