@g4rcez/components 4.0.1 → 4.1.1

package/dist/ai/docs/Tooltip.md

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

@@ -1,142 +0,0 @@
----
-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 "@phosphor-icons/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 `CaretRightIcon` from `@phosphor-icons/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

@@ -1,187 +0,0 @@
----
-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