@g4rcez/components 3.0.0-0 → 3.0.1

package/dist/ai/docs/Slot.md

@@ -0,0 +1,173 @@
+---
+title: Slot
+description: A composition primitive that merges its props into a single child element, enabling the asChild pattern.
+package: "@g4rcez/components"
+export: "{ Slot, Slottable, createSlot, createSlottable }"
+import: "import { Slot, Slottable } from '@g4rcez/components'"
+category: core
+---
+
+# Slot
+
+A composition primitive that merges its props into a single child element. This enables the `asChild` pattern — letting consumers supply their own element while still receiving component-level styles, event handlers, and ARIA attributes. The implementation follows the Radix UI `Slot` pattern.
+
+## Import
+
+```tsx
+import { Slot, Slottable } from "@g4rcez/components";
+```
+
+## Exports
+
+| Export | Description |
+|--------|-------------|
+| `Slot` | Merges props into the single child element |
+| `Slottable` | Marks which child is the slot target when the component has internal structure |
+| `createSlot(ownerName)` | Factory to create a named `Slot` (for building design-system components) |
+| `createSlottable(ownerName)` | Factory to create a named `Slottable` |
+
+## Props
+
+### Slot
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `React.ReactNode` | - | A single valid React element that will receive all of Slot's props |
+| `ref` | `React.ForwardedRef<HTMLElement>` | - | Forwarded to the child element |
+| `...props` | `React.HTMLAttributes<HTMLElement>` | - | Props merged into the child |
+
+### Slottable
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `React.ReactNode` | - | The element to render as the slot target |
+
+## Design Tokens
+
+None — `Slot` is a structural/composition primitive that applies no styles of its own. Any classes passed to `Slot` are merged into the child element's `className`.
+
+## How It Works
+
+1. `Slot` receives props and a single child element.
+2. It merges `className`, `style`, and event handlers from `Slot`'s own props with those of the child.
+3. For event handlers: both the `Slot`'s and the child's handlers are called (child first).
+4. For `className`: values are joined with a space.
+5. For `style`: `Slot`'s style is spread first, then the child's style overrides.
+6. The child's element type is rendered — `Slot` itself renders no DOM element.
+
+## Examples
+
+### The asChild Pattern
+
+```tsx
+interface ButtonProps {
+  asChild?: boolean;
+  children: React.ReactNode;
+  className?: string;
+}
+
+const StyledButton = ({ asChild, children, ...props }: ButtonProps) => {
+  const Component = asChild ? Slot : "button";
+  return (
+    <Component
+      className="inline-flex items-center rounded-button bg-button-primary-bg text-button-primary-text px-4 py-2 font-medium"
+      {...props}
+    >
+      {children}
+    </Component>
+  );
+};
+
+// Renders a <button>
+<StyledButton>Click me</StyledButton>
+
+// Renders an <a> with all button styles applied
+<StyledButton asChild>
+  <a href="/dashboard">Go to Dashboard</a>
+</StyledButton>
+```
+
+### Using Slottable for Internal Structure
+
+When your component wraps children with additional internal elements, use `Slottable` to mark which child is the slot target.
+
+```tsx
+import { CheckIcon } from "lucide-react";
+
+const IconButton = ({ asChild, children, ...props }: { asChild?: boolean; children: React.ReactNode }) => {
+  const Component = asChild ? Slot : "button";
+  return (
+    <Component
+      className="inline-flex items-center gap-1.5 rounded-button bg-button-success-bg text-button-success-text px-4 py-2"
+      {...props}
+    >
+      <Slottable>{children}</Slottable>
+      <CheckIcon size={14} aria-hidden="true" />
+    </Component>
+  );
+};
+
+// Renders <button> with icon
+<IconButton>Confirm</IconButton>
+
+// Renders <a> with icon — the <a> is the slot target
+<IconButton asChild>
+  <a href="/confirm">Confirm</a>
+</IconButton>
+```
+
+### Creating a Named Slot
+
+Use `createSlot` when building your own design-system components for better DevTools display names.
+
+```tsx
+import { createSlot, createSlottable } from "@g4rcez/components";
+
+const CardSlot = createSlot("Card");
+const CardSlottable = createSlottable("Card");
+```
+
+### Merging Event Handlers
+
+Both handlers are called when both the `Slot` and the child define the same event.
+
+```tsx
+<Slot onClick={() => console.log("slot handler")}>
+  <button onClick={() => console.log("child handler")}>
+    Click me
+  </button>
+</Slot>
+// Logs: "child handler", then "slot handler"
+```
+
+## Do
+
+- Use `Slot` when building reusable components that should support any element type via `asChild`
+- Use `Slottable` when your component wraps children with internal structure (icons, labels)
+- Pass accessibility attributes (`aria-*`, `role`) to `Slot` — they will be merged into the child
+- Use design-token classes in the `className` passed to `Slot` (`rounded-button`, `bg-button-primary-bg`)
+
+## Don't
+
+- Don't pass multiple direct children to `Slot` without using `Slottable` — `Slot` expects a single valid element
+- Don't use `Slot` when the element type is fixed and will never change
+- Don't pass raw Tailwind color classes (`bg-blue-500`, `text-white`) in `Slot` className — use design tokens
+- Don't use arbitrary Tailwind values (`bg-[#abc]`) — override CSS variables in your `@theme` block
+
+## Accessibility
+
+- `Slot` merges `aria-*` and `role` props into the child element transparently
+- The final rendered element's semantics depend entirely on the child element type
+- Event handlers from both `Slot` and the child are composed — neither is silently dropped
+
+## Data Attributes
+
+- `Slot` and `Slottable` use `displayName` for React DevTools identification but add no DOM attributes
+- Any `data-*` attributes passed to `Slot` are merged into the child element
+
+## Notes
+
+- Supports `React.lazy` children via `React.use` when available in the React version
+- Ref composition: if both `Slot` and the child have refs, they are composed via `composeRefs`
+- `Slottable` uses an internal symbol (`__radixId`) to identify itself — do not attempt to replicate this check
+- React Fragment children are supported: the composed ref is not applied to `Fragment` (React 19 compatibility)

package/dist/ai/docs/Spinner.md

@@ -0,0 +1,118 @@
+---
+title: Spinner
+description: Animated loading indicator for unknown-duration operations, available as an inline Spinner or a full-container Loading wrapper.
+package: "@g4rcez/components"
+export: "{ Spinner, Loading }"
+import: "import { Spinner, Loading } from '@g4rcez/components'"
+category: display
+---
+
+# Spinner
+
+Animated loading indicator for unknown-duration operations, available as an inline `Spinner` or a full-container `Loading` wrapper.
+
+## Import
+
+```tsx
+import { Spinner, Loading } from "@g4rcez/components";
+```
+
+## Props
+
+### Spinner
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `className` | `string` | — | Additional classes to customize size, color, or border |
+
+Default appearance: `size-12 border-4 border-background border-b-primary animate-spin rounded-full`.
+
+### Loading
+
+No props. Renders a centered `Spinner` inside a `flex h-full w-full items-center justify-center p-12` container.
+
+## Design Tokens
+
+Tokens this component reads. Customize by overriding these CSS variables in your theme.
+
+| Token | CSS Variable | Purpose |
+|-------|-------------|---------|
+| `border-background` | `--background` | Inactive spinner ring color |
+| `border-b-primary` | `--primary` | Active spinner arc color |
+
+## Examples
+
+### Default Spinner
+
+```tsx
+<Spinner />
+```
+
+### Full-Container Loading State
+
+```tsx
+{isLoading ? <Loading /> : <Content />}
+```
+
+### Custom Size
+
+```tsx
+<Spinner className="size-6 border-2" />
+```
+
+### Spinner Inside a Button
+
+```tsx
+<button type="submit" disabled={isSubmitting} className="flex items-center gap-2 px-4 py-2 bg-primary text-primary-foreground rounded-button">
+  {isSubmitting && <Spinner className="size-4 border-2 border-primary-foreground border-b-transparent" />}
+  {isSubmitting ? "Saving…" : "Save"}
+</button>
+```
+
+### Centered in a Card
+
+```tsx
+import { Card } from "@g4rcez/components/card";
+
+<Card title="Analytics">
+  <div className="h-64 flex items-center justify-center">
+    <Spinner />
+  </div>
+</Card>
+```
+
+### Lazy Component Fallback
+
+```tsx
+import { Suspense } from "react";
+import { Loading } from "@g4rcez/components";
+
+<Suspense fallback={<Loading />}>
+  <HeavyComponent />
+</Suspense>
+```
+
+## Do
+
+- Use `Loading` for full-page or large-section loading states where the parent already has a defined height.
+- Use `Spinner` inline (e.g. inside buttons) when an action is being processed.
+- Ensure the parent container of `Loading` has a defined height so the spinner centers correctly.
+- Provide a relevant `aria-label` or `aria-description` if the Portuguese default ("Carregando...") is not appropriate.
+
+## Don't
+
+- Don't pass raw Tailwind color classes (`border-blue-500`) for the spinner border — use design tokens (`border-primary`) instead.
+- Don't use arbitrary Tailwind values (`border-[#abc]`) — override CSS variables in your `@theme` block.
+- Don't leave a `Spinner` visible indefinitely; always handle error states or timeouts.
+- Don't render many spinners simultaneously on a single screen — it is visually disorienting.
+
+## Accessibility
+
+- `Spinner` includes `aria-busy="true"` and `aria-description="Carregando..."` so assistive technologies know content is loading.
+- For non-Portuguese applications, pass a `className` and wrap with a visually hidden `<span aria-live="polite">` if you need a localized announcement.
+
+## Notes
+
+- The spinning effect comes from Tailwind's `animate-spin` utility (`animation: spin 1s linear infinite`).
+- The arc effect is achieved via `border-background` for the full ring and `border-b-primary` for the colored arc — one border property per side.
+- `Loading` is a thin wrapper; prefer `Loading` over manually composing `flex items-center justify-center` wrappers every time.

package/dist/ai/docs/Stats.md

@@ -0,0 +1,137 @@
+---
+title: Stats
+description: Metric display card with a prominent icon, value, and optional footer for trend or contextual data.
+package: "@g4rcez/components"
+export: "{ Stats }"
+import: "import { Stats } from '@g4rcez/components/stats'"
+category: display
+---
+
+# Stats
+
+Metric display card with a prominent icon, value, and optional footer for trend or contextual data.
+
+## Import
+
+```tsx
+import { Stats } from "@g4rcez/components/stats";
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `title` | `Label` | — | Metric label displayed above the value |
+| `Icon` | `React.FC<{ className: string }>` | — | Icon component to display (Lucide recommended) |
+| `iconContainer` | `string` | — | Additional classes for the icon background container |
+| `footer` | `React.ReactElement` | — | Optional footer area for trend data or context |
+| `children` | `React.ReactNode` | — | The metric value (e.g. a number, formatted string) |
+
+## Design Tokens
+
+Tokens this component reads. Customize by overriding these CSS variables in your theme.
+
+| Token | CSS Variable | Purpose |
+|-------|-------------|---------|
+| `bg-card-background` | `--card-background` | Card surface |
+| `border-card-border` | `--card-border` | Card border and divider |
+| `rounded-card` | `--radius-card` | Corner radius |
+| `shadow-shadow-card` | `--shadow-card` | Card drop shadow |
+| `bg-primary` | `--primary` | Icon container background (default) |
+| `text-primary-foreground` | `--primary-foreground` | Icon color (default) |
+| `divide-card-border` | `--card-border` | Divider between header and footer |
+
+## Examples
+
+### Basic Metric
+
+```tsx
+import { UsersIcon } from "lucide-react";
+
+<Stats title="Active Users" Icon={UsersIcon}>
+  1,234
+</Stats>
+```
+
+### With Footer Trend
+
+```tsx
+import { TrendingUpIcon, DollarSignIcon } from "lucide-react";
+
+<Stats
+  title="Revenue"
+  Icon={DollarSignIcon}
+  iconContainer="bg-success"
+  footer={
+    <div className="flex items-center gap-1 text-success text-sm font-medium">
+      <TrendingUpIcon size={14} />
+      <span>+12% from last month</span>
+    </div>
+  }
+>
+  $45,200.00
+</Stats>
+```
+
+### Custom Icon Container Theme
+
+```tsx
+import { AlertCircleIcon } from "lucide-react";
+
+<Stats
+  title="Error Rate"
+  Icon={AlertCircleIcon}
+  iconContainer="bg-danger"
+>
+  0.3%
+</Stats>
+```
+
+### Dashboard Grid
+
+```tsx
+import { UsersIcon, ClockIcon, TargetIcon } from "lucide-react";
+
+<div className="grid grid-cols-1 md:grid-cols-3 gap-4">
+  <Stats title="Users" Icon={UsersIcon}>1.2k</Stats>
+  <Stats title="Sessions" Icon={ClockIcon}>450</Stats>
+  <Stats title="Conversion" Icon={TargetIcon}>3.2%</Stats>
+</div>
+```
+
+### With Skeleton Loading
+
+```tsx
+import { BarChartIcon } from "lucide-react";
+import { Skeleton } from "@g4rcez/components";
+
+<Stats title="Page Views" Icon={BarChartIcon}>
+  {isLoading ? <Skeleton className="h-9 w-24" /> : "48,301"}
+</Stats>
+```
+
+## Do
+
+- Use clear, descriptive icons that relate to the metric shown.
+- Keep the metric value prominent and concise — one or two tokens, not a sentence.
+- Use `iconContainer` with design-token color classes (`bg-success`, `bg-danger`) to differentiate metric types visually.
+- Use the `footer` prop to provide trend context (period-over-period comparison).
+
+## Don't
+
+- Don't pass raw Tailwind color classes (`bg-green-500`, `text-red-600`) to `iconContainer` or `footer` — use design tokens instead.
+- Don't use arbitrary Tailwind values (`bg-[#abc]`) — override CSS variables in your `@theme` block.
+- Don't place too many `Stats` cards without logical grouping — they lose impact when overused.
+- Don't put long sentences as `title` or `children`; they should be scannable at a glance.
+
+## Accessibility
+
+- The metric label uses an `<h3>` element for proper heading hierarchy within a dashboard context.
+- The icon renders via `props.Icon` with a `className` prop applied; Lucide icons include accessible SVG structure.
+- Consider adding `aria-label` to the icon container if the icon carries essential meaning not conveyed by the title.
+
+## Notes
+
+- The icon container is sized via `size-10` with `p-8` padding, producing a square aspect ratio. Use `iconContainer` to adjust (`bg-success`, `bg-danger`, etc.).
+- `children` renders in a `<p>` with `text-4xl font-semibold` — pass a pre-formatted string for custom number formatting.
+- The footer section only renders when `footer` is provided; otherwise the divider is omitted.

package/dist/ai/docs/Step.md

@@ -0,0 +1,159 @@
+---
+title: Step
+description: Animated multi-step progress indicator with status tracking for checkout flows, onboarding, and wizards.
+package: "@g4rcez/components"
+export: "{ Step }"
+import: "import { Steps, Step } from '@g4rcez/components'"
+category: display
+---
+
+# Step
+
+Animated multi-step progress indicator with status tracking for checkout flows, onboarding, and wizards.
+
+## Import
+
+```tsx
+import { Steps, Step } from "@g4rcez/components";
+```
+
+## Props
+
+### Steps (Container)
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `currentStep` | `number` | — | Index of the currently active step |
+| `steps` | `number` | — | Total number of steps |
+| `children` | `React.ReactNode` | — | `Step` components |
+
+### Step
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `step` | `number` | — | Index of this step |
+| `currentStep` | `number` | — | Index of the currently active step (usually from parent) |
+| `title` | `Label` | — | Step label |
+| `status` | `StepStatus` | — | Override automatic status (`"active" \| "inactive" \| "complete" \| "error"`) |
+| `titleClassName` | `string` | — | Additional classes for the title text |
+
+Standard `<button>` props are also forwarded (e.g. `onClick`, `disabled`).
+
+## Step Statuses
+
+| Status | Visual | Icon |
+|--------|--------|------|
+| `active` | Primary color ring | Step number |
+| `inactive` | Muted border | Step number |
+| `complete` | Success color fill | Animated check mark |
+| `error` | Danger color fill | Animated X mark |
+
+Status is derived automatically from `step` vs. `currentStep` unless overridden via `status`.
+
+## Design Tokens
+
+Tokens this component reads. Customize by overriding these CSS variables in your theme.
+
+| Token | CSS Variable | Purpose |
+|-------|-------------|---------|
+| `bg-primary` / `border-primary` | `--primary-DEFAULT` | Active step fill and border |
+| `text-primary-foreground` | `--primary-foreground` | Active step text |
+| `bg-success` / `border-success` | `--success-DEFAULT` | Complete step fill and border |
+| `text-success-foreground` | `--success-foreground` | Complete step check icon |
+| `bg-danger` / `border-danger` | `--danger-DEFAULT` / `--danger-hover` | Error step fill and border |
+| `text-danger-foreground` | `--danger-foreground` | Error step X icon |
+| `text-disabled` | `--disabled` | Inactive step text |
+| `bg-card-border` / `border-card-border` | `--card-border` | Connector line and inactive border |
+| `bg-background` | `--background` | Inactive step background |
+
+## Examples
+
+### Basic Steps
+
+```tsx
+<Steps currentStep={2} steps={3}>
+  <Step step={1} currentStep={2} title="Account" />
+  <Step step={2} currentStep={2} title="Profile" />
+  <Step step={3} currentStep={2} title="Review" />
+</Steps>
+```
+
+### Interactive Wizard
+
+```tsx
+function Wizard() {
+  const [currentStep, setCurrentStep] = useState(1);
+
+  return (
+    <div className="space-y-8">
+      <Steps currentStep={currentStep} steps={4}>
+        <Step step={1} currentStep={currentStep} title="Account" onClick={() => setCurrentStep(1)} />
+        <Step step={2} currentStep={currentStep} title="Profile" onClick={() => setCurrentStep(2)} />
+        <Step step={3} currentStep={currentStep} title="Payment" onClick={() => setCurrentStep(3)} />
+        <Step step={4} currentStep={currentStep} title="Review" onClick={() => setCurrentStep(4)} />
+      </Steps>
+
+      <div className="p-6 rounded-card border border-card-border bg-card-background">
+        {currentStep === 1 && <AccountForm />}
+        {currentStep === 2 && <ProfileForm />}
+        {currentStep === 3 && <PaymentForm />}
+        {currentStep === 4 && <ReviewSummary />}
+      </div>
+    </div>
+  );
+}
+```
+
+### With Error State
+
+```tsx
+<Steps currentStep={2} steps={3}>
+  <Step step={1} currentStep={2} title="Identity" />
+  <Step step={2} currentStep={2} title="Payment" status="error" />
+  <Step step={3} currentStep={2} title="Finish" />
+</Steps>
+```
+
+### Checkout Flow
+
+```tsx
+function CheckoutSteps({ step }: { step: number }) {
+  return (
+    <Steps currentStep={step} steps={3}>
+      <Step step={1} currentStep={step} title="Cart" />
+      <Step step={2} currentStep={step} title="Shipping" />
+      <Step step={3} currentStep={step} title="Confirmation" />
+    </Steps>
+  );
+}
+```
+
+## Do
+
+- Provide clear, concise `title` labels for each step.
+- Keep the total number of steps manageable (3–5 is ideal).
+- Use `status="error"` to clearly indicate where a user needs to return and fix a problem.
+- Use `onClick` on `Step` to enable backward navigation in wizards.
+
+## Don't
+
+- Don't pass raw Tailwind color classes for step styling — the component derives colors from CSS variables.
+- Don't use arbitrary Tailwind values (`bg-[#abc]`) — override CSS variables in your `@theme` block.
+- Don't hide critical information in steps the user hasn't yet seen.
+- Don't use `Step` for non-linear navigation without a clear sequential intent.
+
+## Accessibility
+
+- Each `Step` renders as a `<button>` element, making it focusable and keyboard-operable.
+- Icons use `aria-hidden` to prevent redundant screen reader announcements.
+- The `Steps` container provides a logical visual grouping for the process.
+
+## Data Attributes
+
+- `data-step` — the step index number, applied to each step's `<button>`.
+
+## Notes
+
+- Connector lines between steps are shown only on `xl` breakpoints (hidden on smaller screens where steps stack vertically).
+- Animations use Framer Motion (`motion/react`): the step circle animates between status colors, and the check/X icons draw in with `pathLength`.
+- The `Steps` component tracks `previousStep` internally to orchestrate staggered transition delays when jumping multiple steps at once.