@g4rcez/components 3.0.0 → 3.0.1

package/dist/ai/docs/Progress.md

@@ -0,0 +1,145 @@
+---
+title: Progress
+description: Accessible progress bar built on Base UI Progress with optional label overlay and smooth transitions.
+package: "@g4rcez/components"
+export: "{ Progress }"
+import: "import { Progress } from '@g4rcez/components'"
+category: display
+---
+
+# Progress
+
+Accessible progress bar built on Base UI Progress with optional label overlay and smooth transitions.
+
+## Import
+
+```tsx
+import { Progress } from "@g4rcez/components";
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `percent` | `number` | — | Current progress value (0–100) |
+| `max` | `number` | — | Maximum value (forwarded to Base UI `Progress.Root`) |
+| `label` | `Label` | — | Custom text overlay; overrides the default `{percent} %` |
+| `container` | `string` | — | Additional classes for the track element |
+| `className` | `string` | — | Additional classes for the indicator (fill) element |
+| `textClassName` | `string` | — | Additional classes for the label text overlay |
+
+## Design Tokens
+
+Tokens this component reads. Customize by overriding these CSS variables in your theme.
+
+| Token | CSS Variable | Purpose |
+|-------|-------------|---------|
+| `bg-background` | `--background` | Track (unfilled) background |
+| `bg-primary` | `--primary` | Indicator (fill) color |
+| `text-primary-foreground` | `--primary-foreground` | Default label text color |
+
+## Examples
+
+### Basic Progress Bar
+
+```tsx
+<Progress percent={75} />
+```
+
+### Animated Progress
+
+```tsx
+function AnimatedProgress() {
+  const [progress, setProgress] = useState(0);
+
+  useEffect(() => {
+    const timer = setInterval(() => {
+      setProgress((prev) => (prev >= 100 ? 0 : prev + 10));
+    }, 500);
+    return () => clearInterval(timer);
+  }, []);
+
+  return <Progress percent={progress} />;
+}
+```
+
+### Custom Label
+
+```tsx
+<Progress percent={60} label="Uploading file… 60%" />
+```
+
+### Indeterminate / Unknown Duration
+
+When `percent` is `undefined` the indicator is not rendered and the label is hidden, leaving only the track. Combine with a separate `Spinner` for unknown-duration operations.
+
+```tsx
+{isLoading ? <Spinner /> : <Progress percent={uploadPercent} />}
+```
+
+### Multi-Step Form Progress
+
+```tsx
+function MultiStepForm() {
+  const [currentStep, setCurrentStep] = useState(1);
+  const totalSteps = 4;
+  const progress = (currentStep / totalSteps) * 100;
+
+  return (
+    <div className="space-y-4">
+      <div className="flex justify-between items-center text-sm text-muted-foreground">
+        <span>Step {currentStep} of {totalSteps}</span>
+        <span>{Math.round(progress)}% complete</span>
+      </div>
+      <Progress percent={progress} />
+    </div>
+  );
+}
+```
+
+### Upload with Status Label
+
+```tsx
+function FileUploadProgress({ fileName, percent }: { fileName: string; percent: number }) {
+  const isDone = percent >= 100;
+
+  return (
+    <div className="space-y-1">
+      <div className="flex justify-between text-sm">
+        <span className="text-foreground">{fileName}</span>
+        <span className="text-muted-foreground">{percent}%</span>
+      </div>
+      <Progress
+        percent={percent}
+        label={isDone ? "Complete" : undefined}
+        container={isDone ? "bg-success/20" : undefined}
+        className={isDone ? "bg-success" : undefined}
+      />
+    </div>
+  );
+}
+```
+
+## Do
+
+- Use `Progress` when the duration of an operation is known or can be estimated.
+- Provide a `label` when a percentage alone is not descriptive enough.
+- Use `container` and `className` with design-token classes to change the track and fill colors (`bg-success`, `bg-warn`, etc.).
+
+## Don't
+
+- Don't pass raw Tailwind color classes (`bg-green-500`, `bg-blue-500`) in `container` or `className` — use design tokens (`bg-success`, `bg-primary`) instead.
+- Don't use arbitrary Tailwind values (`bg-[#abc]`) — override CSS variables in your `@theme` block.
+- Don't use `Progress` for operations with unknown durations — use `Spinner` instead.
+- Don't update `percent` more frequently than needed; excessive updates cause jitter.
+
+## Accessibility
+
+- Built on Base UI `Progress.Root` which renders the correct `role="progressbar"` with `aria-valuenow`, `aria-valuemin`, and `aria-valuemax` automatically.
+- The label overlay is a `<p>` element with `tabular-nums` for consistent digit rendering.
+
+## Notes
+
+- The indicator moves via a CSS `translateX` transform (`translateX(-${100 - percent}%)`) for GPU-accelerated animation.
+- The 500 ms `transition-transform ease-in-out` is applied via the `className` on the indicator element and can be overridden.
+- When `percent` is `undefined` or `null`, the label and fill are hidden; the track remains visible.

package/dist/ai/docs/Radiobox.md

@@ -0,0 +1,128 @@
+---
+title: Radiobox
+description: Styled radio button for selecting one option from a mutually exclusive set.
+package: "@g4rcez/components"
+export: "{ Radiobox }"
+import: "import { Radiobox } from '@g4rcez/components/radiobox'"
+category: form
+---
+
+# Radiobox
+
+Styled radio button for selecting one option from a mutually exclusive set.
+
+## Import
+
+```tsx
+import { Radiobox } from "@g4rcez/components/radiobox";
+```
+
+## Props
+
+Accepts all standard HTML `input[type="radio"]` attributes, plus:
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `React.ReactNode` | — | Label text or element displayed next to the radio button. |
+| `size` | `"medium" \| "large"` | `"medium"` | Visual size of the radio button. |
+| `className` | `string` | — | Additional CSS classes for the `<input>` element. |
+
+## Design Tokens
+
+Tokens this component reads. Customize by overriding these CSS variables in your theme.
+
+| Token | CSS Variable | Purpose |
+|-------|-------------|---------|
+| `border-card-border` | `--card-border` | Default border color of the radio circle |
+| `text-primary` | `--primary` | Checked fill color (via `accent-color`) |
+| `focus:ring-primary` | `--primary` | Focus ring color |
+| `disabled:opacity-70` | — | Reduced opacity for disabled state |
+
+## Examples
+
+### Basic group
+
+```tsx
+import { Radiobox } from "@g4rcez/components/radiobox";
+
+export default function PlanSelector() {
+  return (
+    <div className="flex flex-col gap-sm">
+      <Radiobox name="plan" value="basic" defaultChecked>
+        Basic Plan
+      </Radiobox>
+      <Radiobox name="plan" value="pro">
+        Pro Plan
+      </Radiobox>
+      <Radiobox name="plan" value="enterprise">
+        Enterprise Plan
+      </Radiobox>
+    </div>
+  );
+}
+```
+
+### Disabled state
+
+```tsx
+import { Radiobox } from "@g4rcez/components/radiobox";
+
+export default function DisabledOption() {
+  return (
+    <Radiobox disabled name="option" value="legacy">
+      Legacy (unavailable)
+    </Radiobox>
+  );
+}
+```
+
+### In a grid layout
+
+```tsx
+import { Radiobox } from "@g4rcez/components/radiobox";
+
+export default function GenderSelector() {
+  return (
+    <div className="grid grid-cols-2 gap-base">
+      <Radiobox name="gender" value="male">Male</Radiobox>
+      <Radiobox name="gender" value="female">Female</Radiobox>
+      <Radiobox name="gender" value="non-binary">Non-binary</Radiobox>
+      <Radiobox name="gender" value="prefer-not">Prefer not to say</Radiobox>
+    </div>
+  );
+}
+```
+
+## Do
+
+- Group related `Radiobox` components by giving them the same `name` attribute.
+- Provide a clear, concise label for each radio button via `children`.
+- Use `Radiobox` when there are 2–7 mutually exclusive options; for more, prefer `Select`.
+- Use design-token classes on wrapper elements (`bg-background`, `text-foreground`).
+
+## Don't
+
+- Don't use `Radiobox` for independent toggles — use `Checkbox` instead.
+- Don't use `Radiobox` for a simple yes/no choice — consider `Switch`.
+- Don't pass raw Tailwind color classes (`text-blue-500`, `border-gray-300`) — use design tokens instead.
+- Don't use arbitrary Tailwind values (`text-[--my-var]`) — override CSS variables in your `@theme` block instead.
+
+## Accessibility
+
+- A semantic `<label>` wraps the `<input>`, associating label text with the radio button without extra `htmlFor` wiring.
+- `aria-disabled` is set on the wrapper `<label>` when the input is disabled.
+- Standard keyboard interaction: Arrow keys navigate between radios in the same group; Space selects.
+- The `data-[disabled=true]:cursor-not-allowed` class gives a clear cursor signal for disabled items.
+
+## Data Attributes
+
+| Attribute | Element | Value | Description |
+|-----------|---------|-------|-------------|
+| `data-component` | `label` | `"radiobox"` | Identifies the component. |
+| `data-disabled` | `label` | `true \| undefined` | Set when the radio is disabled. |
+
+## Notes
+
+- Uses the `form-radio` utility class for consistent cross-browser appearance.
+- The `size` prop is accepted in the type definition but visual differentiation is handled via the `className` pass-through — you may add `h-5 w-5` or similar token-based size classes as needed.
+- Render multiple `Radiobox` components inside a `<fieldset>` with a `<legend>` for full semantic grouping.

package/dist/ai/docs/RenderOnView.md

@@ -0,0 +1,138 @@
+---
+title: RenderOnView
+description: A performance wrapper that defers rendering children until the container enters the viewport.
+package: "@g4rcez/components"
+export: "{ RenderOnView }"
+import: "import { RenderOnView } from '@g4rcez/components'"
+category: core
+---
+
+# RenderOnView
+
+A performance wrapper that defers rendering its children until the container element enters the viewport. Uses the `IntersectionObserver` API and renders children exactly once — they stay mounted after first appearing.
+
+## Import
+
+```tsx
+import { RenderOnView } from "@g4rcez/components";
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `onIntersection` | `() => void` | - | Callback fired once when the container first enters the viewport |
+| `children` | `React.ReactNode` | - | Content to render when the container is visible |
+| `as` | `React.ElementType` | `"div"` | HTML element to render the container as |
+| `...props` | `React.ComponentPropsWithoutRef<T>` | - | All props valid for the chosen element type |
+
+## Design Tokens
+
+None — `RenderOnView` is a layout/performance primitive that applies no styles of its own.
+
+## How It Works
+
+1. **Initial state**: The container element renders immediately but children are not mounted.
+2. **Intersection Observer**: A `useLayoutEffect` sets up an `IntersectionObserver` on the container.
+3. **First intersection**: When the container enters the viewport, `shouldRender` flips to `true` and children mount.
+4. **Stays mounted**: Children remain in the DOM after the first intersection — scrolling back out does not unmount them.
+5. **Callback**: `onIntersection` fires once at the moment of the first intersection.
+
+## Examples
+
+### Basic Lazy Rendering
+
+```tsx
+<div>
+  <div className="h-screen flex items-center justify-center text-foreground">
+    Scroll down to see lazy content
+  </div>
+
+  <RenderOnView>
+    <ExpensiveChart data={largeDataset} />
+  </RenderOnView>
+</div>
+```
+
+### With Intersection Callback
+
+```tsx
+const TrackableSection = ({ sectionName, children }: { sectionName: string; children: React.ReactNode }) => (
+  <RenderOnView
+    onIntersection={() => analytics.track("Section Viewed", { section: sectionName })}
+  >
+    {children}
+  </RenderOnView>
+);
+```
+
+### Multiple Deferred Sections
+
+```tsx
+<main>
+  <HeroSection />
+
+  <RenderOnView>
+    <FeaturesSection />
+  </RenderOnView>
+
+  <RenderOnView>
+    <TestimonialsSection />
+  </RenderOnView>
+
+  <RenderOnView>
+    <ContactForm />
+  </RenderOnView>
+</main>
+```
+
+### With Custom Element
+
+```tsx
+<RenderOnView as="section" aria-label="Analytics charts">
+  <RevenueChart />
+</RenderOnView>
+```
+
+### With React.lazy and Suspense
+
+```tsx
+import { lazy, Suspense } from "react";
+import { Spinner } from "@g4rcez/components";
+
+const HeavyComponent = lazy(() => import("./HeavyComponent"));
+
+<RenderOnView>
+  <Suspense fallback={<Spinner />}>
+    <HeavyComponent />
+  </Suspense>
+</RenderOnView>
+```
+
+## Do
+
+- Use `RenderOnView` for components with significant rendering cost (charts, maps, rich editors)
+- Combine with `React.lazy` and `Suspense` for maximum bundle and rendering savings
+- Use `as="section"` or another semantic element when the container has meaningful structure
+- Use design-token classes on wrapper divs inside children (`bg-background`, `border-border`)
+
+## Don't
+
+- Don't use `RenderOnView` for above-the-fold content — it adds an unnecessary observer
+- Don't rely on it for critical content that must be in the initial HTML (SEO, LCP elements)
+- Don't pass raw Tailwind color classes (`bg-white`, `text-gray-800`) to children or wrappers — use design tokens
+- Don't use arbitrary Tailwind values (`bg-[#abc]`) — override CSS variables in your `@theme` block
+
+## Accessibility
+
+- The container element is always rendered and present in the DOM
+- Children mount only when visible, so screen readers will encounter them when they scroll into view
+- Ensure any interactive content inside has proper focus management after mounting
+
+## Notes
+
+- Children render exactly once and are never unmounted, regardless of subsequent scroll position
+- `onIntersection` fires at most once per component lifetime
+- The `IntersectionObserver` is disconnected on component unmount
+- Uses `useLayoutEffect` for synchronous observer setup to avoid a flash of empty container
+- SSR-safe: the initial `shouldRender` state starts as `false` since `ref.current` is `null` on the server

package/dist/ai/docs/Resizable.md

@@ -0,0 +1,159 @@
+---
+title: Resizable
+description: A wrapper that animates its height smoothly when content dimensions change.
+package: "@g4rcez/components"
+export: "{ Resizable }"
+import: "import { Resizable } from '@g4rcez/components'"
+category: core
+---
+
+# Resizable
+
+A wrapper that automatically animates its height whenever the inner content size changes. Uses `ResizeObserver` to detect dimension changes and `motion/react` to drive smooth height transitions.
+
+## Import
+
+```tsx
+import { Resizable } from "@g4rcez/components";
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `React.ReactNode` | - | Content rendered inside the animated container |
+
+## Design Tokens
+
+None — `Resizable` is a layout animation primitive that applies no color or spacing tokens.
+
+## How It Works
+
+1. An inner `<div>` holds the children and is observed by a `ResizeObserver`.
+2. When the inner `div`'s height changes, the observed height value updates via a motion value.
+3. An outer `motion.div` animates from the previous height to the new height using `motion/react`.
+4. While the content has no measured height yet (`h === 0`), the container uses `height: "auto"`.
+
+## Examples
+
+### Collapsible Content
+
+```tsx
+import { useState } from "react";
+
+const CollapsiblePanel = () => {
+  const [isOpen, setIsOpen] = useState(false);
+
+  return (
+    <div className="border border-border rounded-card">
+      <button
+        type="button"
+        className="w-full px-4 py-3 text-left font-medium text-foreground"
+        onClick={() => setIsOpen((v) => !v)}
+      >
+        Toggle Details
+      </button>
+      <Resizable>
+        {isOpen ? (
+          <div className="px-4 pb-4 text-foreground">
+            <p>This content expands and collapses with a smooth height animation.</p>
+            <p>Additional paragraphs will also animate smoothly.</p>
+          </div>
+        ) : null}
+      </Resizable>
+    </div>
+  );
+};
+```
+
+### Dynamic List
+
+```tsx
+import { useState } from "react";
+import { Button } from "@g4rcez/components/button";
+
+const GrowingList = () => {
+  const [items, setItems] = useState(["Item 1"]);
+
+  return (
+    <div className="flex flex-col gap-base">
+      <Button
+        theme="primary"
+        onClick={() => setItems((prev) => [...prev, `Item ${prev.length + 1}`])}
+      >
+        Add Item
+      </Button>
+      <Resizable>
+        <ul className="flex flex-col gap-sm">
+          {items.map((item) => (
+            <li key={item} className="text-foreground">
+              {item}
+            </li>
+          ))}
+        </ul>
+      </Resizable>
+    </div>
+  );
+};
+```
+
+### Animated Tab Panels
+
+```tsx
+const TabbedContent = ({ activeTab }: { activeTab: string }) => (
+  <Resizable>
+    <div className="p-4 text-foreground">
+      {activeTab === "overview" && <OverviewPanel />}
+      {activeTab === "settings" && <SettingsPanel />}
+      {activeTab === "history"  && <HistoryPanel />}
+    </div>
+  </Resizable>
+);
+```
+
+### Async Content Loading
+
+```tsx
+const AsyncCard = ({ data }: { data: string[] | null }) => (
+  <div className="rounded-card border border-border bg-card-background shadow-shadow-card">
+    <Resizable>
+      {data === null ? (
+        <div className="p-4 text-muted-foreground">Loading…</div>
+      ) : (
+        <ul className="p-4 flex flex-col gap-sm">
+          {data.map((item) => (
+            <li key={item} className="text-foreground">{item}</li>
+          ))}
+        </ul>
+      )}
+    </Resizable>
+  </div>
+);
+```
+
+## Do
+
+- Use `Resizable` around any content that changes height to provide a polished animation
+- Wrap only the specific dynamic section — not large, stable portions of the page
+- Apply visual styles (`bg-*`, `border-*`, `rounded-*`) to elements inside `Resizable`, not to `Resizable` itself
+- Use design-token classes for all styling (`bg-background`, `border-border`, `rounded-card`)
+
+## Don't
+
+- Don't use `Resizable` on content that changes height at very high frequency (e.g., per-frame updates) — it may cause performance issues
+- Don't wrap large, stable sections of a page — keep the observed area small
+- Don't pass raw Tailwind color classes (`bg-white`, `border-gray-200`) inside `Resizable` wrappers — use design tokens
+- Don't use arbitrary Tailwind values (`bg-[#fff]`) — override CSS variables in your `@theme` block
+
+## Accessibility
+
+- `Resizable` is a layout animation wrapper and introduces no semantic elements or ARIA attributes
+- Ensure content inside maintains correct focus order and accessible roles
+- For accordion/collapsible patterns, add `aria-expanded` and `aria-controls` to the trigger button
+
+## Notes
+
+- Requires `motion/react` as a peer dependency
+- The outer `motion.div` drives the height animation; the inner `div` is the measured reference
+- SSR-safe: `isSsr()` prevents `ResizeObserver` from being created on the server
+- The component is a client component (`"use client"`)