@g4rcez/components 4.0.1 → 4.1.1

package/ai/docs/PageCalendar.md

@@ -0,0 +1,262 @@
+---
+title: PageCalendar
+description: Full-page calendar with month, week, and day views, event filtering, and custom event rendering.
+package: "@g4rcez/components"
+export: "{ PageCalendar }"
+import: "import { PageCalendar } from '@g4rcez/components'"
+category: calendar
+---
+
+# PageCalendar
+
+Full-page calendar with month, week, and day views, event filtering, and custom event rendering.
+
+## Import
+
+```tsx
+import { PageCalendar } from "@g4rcez/components";
+```
+
+## Props
+
+| Prop              | Type                                     | Default      | Description                                                                           |
+| ----------------- | ---------------------------------------- | ------------ | ------------------------------------------------------------------------------------- |
+| `events`          | `CalendarEvent<T>[]`                     | —            | Array of event objects to display across all views.                                   |
+| `filters`         | `CalendarFilter[]`                       | `[]`         | Filter tag definitions. Each filter can be toggled to hide/show matching events.      |
+| `defaultView`     | `"month" \| "week" \| "day"`             | `"month"`    | Initial view rendered when the component mounts.                                      |
+| `defaultDate`     | `Date`                                   | `new Date()` | Initial date the calendar focuses on.                                                 |
+| `onEventClick`    | `(event: CalendarEvent) => void`         | —            | Called when the user clicks an event pill.                                            |
+| `onSlotClick`     | `(date: Date) => void`                   | —            | Called when the user clicks an empty time slot (week and day views).                  |
+| `onAddEvent`      | `() => void`                             | —            | Called when the "Add event" button in the header is clicked. Omit to hide the button. |
+| `onChangeFilters` | `(filters: CalendarFilter[]) => void`    | —            | Called whenever a filter is toggled, receiving the updated filter array.              |
+| `renderEvent`     | `(event: CalendarEvent<T>) => ReactNode` | —            | Custom renderer for the selected event detail panel in day view.                      |
+| `filterArea`      | `ReactNode`                              | —            | Replaces the default filter tag row in the header with custom content.                |
+| `getFilterId`     | `() => void`                             | —            | Custom accessor to extract a `filterId` from an event. Defaults to `event.filterId`.  |
+
+## Type Definitions
+
+### CalendarEventBase
+
+```ts
+type CalendarEventBase = {
+    id: string;
+    date: Date;
+};
+```
+
+### CalendarEvent
+
+```ts
+type CalendarEvent<T extends CalendarEventBase = CalendarEventBase> = T & {
+    title: string;
+    filterId?: string;
+    className?: string;
+};
+```
+
+`className` is applied directly to the event pill element in all views.
+
+### CalendarFilter
+
+```ts
+type CalendarFilter = {
+    id: string;
+    label: string;
+    enabled: boolean;
+    theme: TagProps["theme"]; // "primary" | "success" | "warn" | "danger" | "info" | "neutral" | "secondary" | "muted"
+};
+```
+
+### ViewMode
+
+```ts
+type ViewMode = "month" | "week" | "day";
+```
+
+## Design Tokens
+
+Tokens this component reads. Customize by overriding these CSS variables in your theme.
+
+| Token                     | CSS Variable           | Purpose                                            |
+| ------------------------- | ---------------------- | -------------------------------------------------- |
+| `bg-primary`              | `--primary`            | Today indicator background, selected day highlight |
+| `text-primary-foreground` | `--primary-foreground` | Text on today / selected day indicator             |
+| `bg-card`                 | `--card`               | Non-today day indicator background in header       |
+| `text-foreground`         | `--foreground`         | Default text in day cells and header               |
+| `text-muted-foreground`   | `--muted-foreground`   | Week label, hour labels, secondary text            |
+| `border-border`           | `--border`             | Grid cell borders, day view hour-slot dividers     |
+| `border-card-border`      | `--card-border`        | Day and week view column borders                   |
+| `bg-muted`                | `--muted`              | Hover background on time slots                     |
+| `z-calendar`              | `--z-calendar`         | `z-index` for the column resizer handle (value: 2) |
+| `z-floating`              | `--z-floating`         | `z-index` for floating overlays (value: 22)        |
+
+## Views
+
+### Month view
+
+Displays a 6-row grid of all days in the selected month. Each day cell shows event pills. Clicking a day navigates to that day in the day view.
+
+### Week view
+
+Displays the 7 days of the current week with an hourly time grid. Events are placed at their time position. Clicking an empty slot calls `onSlotClick`.
+
+### Day view
+
+Displays a single day with an hourly grid alongside a mini calendar and a detail panel. The detail panel shows a default summary or your `renderEvent` output when an event is clicked.
+
+## Examples
+
+### Minimal calendar
+
+```tsx
+import { PageCalendar } from "@g4rcez/components";
+
+type MyEvent = { id: string; date: Date; title: string };
+
+const events: MyEvent[] = [{ id: "1", date: new Date(), title: "Team standup" }];
+
+export function MyCalendar() {
+    return <PageCalendar events={events} onEventClick={(event) => console.log(event)} />;
+}
+```
+
+### With filters
+
+```tsx
+import { PageCalendar } from "@g4rcez/components";
+import type { CalendarFilter } from "@g4rcez/components";
+
+const filters: CalendarFilter[] = [
+    { id: "work", label: "Work", enabled: true, theme: "primary" },
+    { id: "personal", label: "Personal", enabled: true, theme: "success" },
+];
+
+const events = [
+    { id: "1", date: new Date(), title: "Sprint planning", filterId: "work" },
+    { id: "2", date: new Date(), title: "Gym", filterId: "personal" },
+];
+
+export function FilteredCalendar() {
+    return <PageCalendar events={events} filters={filters} onChangeFilters={(updated) => console.log(updated)} />;
+}
+```
+
+### Custom event detail in day view
+
+```tsx
+import { PageCalendar } from "@g4rcez/components";
+import { MapPinIcon } from "@phosphor-icons/react";
+
+export function DetailCalendar() {
+    return (
+        <PageCalendar
+            events={events}
+            defaultView="day"
+            renderEvent={(event) => (
+                <div className="flex flex-col gap-1 p-2 bg-muted rounded-card">
+                    <span className="font-semibold text-foreground">{event.title}</span>
+                    <span className="flex items-center gap-1 text-sm text-muted-foreground">
+                        <MapPinIcon size={12} />
+                        {event.location}
+                    </span>
+                </div>
+            )}
+        />
+    );
+}
+```
+
+### Controlled add-event flow
+
+```tsx
+import { useState } from "react";
+import { PageCalendar } from "@g4rcez/components";
+
+export function EditableCalendar() {
+    const [showForm, setShowForm] = useState(false);
+    const [slotDate, setSlotDate] = useState<Date | null>(null);
+
+    return (
+        <>
+            <PageCalendar
+                events={events}
+                onAddEvent={() => setShowForm(true)}
+                onSlotClick={(date) => {
+                    setSlotDate(date);
+                    setShowForm(true);
+                }}
+            />
+            {showForm && <EventForm defaultDate={slotDate} onClose={() => setShowForm(false)} />}
+        </>
+    );
+}
+```
+
+### Custom filter area
+
+```tsx
+import { PageCalendar } from "@g4rcez/components";
+import { Button } from "@g4rcez/components/button";
+
+export function CustomFilterCalendar() {
+    return (
+        <PageCalendar
+            events={events}
+            filterArea={
+                <div className="flex items-center gap-2 rounded-card bg-muted px-3 py-1.5">
+                    <Button theme="ghost-muted" size="small">
+                        All
+                    </Button>
+                    <Button theme="primary" size="small">
+                        Mine
+                    </Button>
+                </div>
+            }
+        />
+    );
+}
+```
+
+## Do
+
+- Provide unique `id` values for every event and filter to ensure stable React keys and filter matching.
+- Use `theme` on filters to give users a quick visual legend for event categories.
+- Implement both `onAddEvent` and `onSlotClick` to give users two natural entry points for creating events.
+- Use design-token classes in `renderEvent` output (`bg-muted`, `text-foreground`, `border-border`).
+- Keep event `title` values short — they are truncated in month and week event pills.
+
+## Don't
+
+- Don't pass raw Tailwind color classes (`bg-blue-500`, `text-white`, `border-gray-300`) — use `theme` on filters/events or design tokens instead.
+- Don't use arbitrary Tailwind values (`bg-[#abc]`, `bg-[--my-var]`) — override CSS variables in your `@theme` block instead.
+- Don't pack more than a handful of events per day in month view — the grid will overflow; guide users toward week or day view for dense schedules.
+- Don't use extremely long event titles; they are truncated inside the event pill.
+- Don't supply both `filterArea` and `filters` expecting both to render — `filterArea` fully replaces the default filter tag row.
+
+## Accessibility
+
+- The root container has `role="application"` and `aria-label` from the i18n translation key `pageCalendarLabel`.
+- The header month/year title uses `aria-live="polite"` and `aria-atomic="true"` so screen readers announce date changes after navigation.
+- Navigation buttons (`Previous`, `Today`, `Next`) have `aria-label` attributes for screen reader descriptions.
+- View toggle buttons use `aria-pressed` to communicate the active view.
+- Filter tags are rendered as `<button>` elements with `aria-pressed` and an `aria-label` that includes the enabled/disabled state.
+- Day view hour slots have `role="button"`, `tabIndex={0}`, and `aria-label` for keyboard-accessible slot selection.
+- The day column header uses `aria-label` with the full formatted date string.
+
+## Data Attributes
+
+- `data-component="day-view-scroller"` — the scrolling container inside the day view. Useful for CSS height overrides:
+
+```css
+[data-component="day-view-scroller"] {
+    height: calc(100dvh - 200px);
+}
+```
+
+## Notes
+
+- Internally uses `date-fns` for all date arithmetic and locale-aware formatting. The locale is read from the `useLocale` hook; set it at the app root via the component provider.
+- All labels (button text, ARIA strings, week number format) are driven by the i18n translation system. Override via the `translations` prop on the root provider.
+- Event filtering is managed internally; `onChangeFilters` lets you mirror the filter state to an external store without controlling it.
+- The day view mini-calendar renders dots beneath days that have events, matching the `bg-primary` token for visual consistency.
+- The component grows to fill its container (`h-full flex-grow`). Place it inside a flex or grid container with an explicit height.

package/{dist/ai → ai}/docs/Polymorph.md

@@ -19,20 +19,20 @@ import { Polymorph } from "@g4rcez/components";
 
 ## Props
 
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `as` | `React.ElementType` | `"span"` | The HTML element or React component to render as |
-| `ref` | `React.Ref` | - | Forwarded ref to the rendered element |
-| `...props` | `React.ComponentPropsWithoutRef<T>` | - | All props valid for the chosen element type |
+| Prop       | Type                                | Default  | Description                                      |
+| ---------- | ----------------------------------- | -------- | ------------------------------------------------ |
+| `as`       | `React.ElementType`                 | `"span"` | The HTML element or React component to render as |
+| `ref`      | `React.Ref`                         | -        | Forwarded ref to the rendered element            |
+| `...props` | `React.ComponentPropsWithoutRef<T>` | -        | All props valid for the chosen element type      |
 
 ## Type Definitions
 
 ```tsx
 export type PolymorphicProps<Props, T extends React.ElementType> = Props & {
-  as?: T;
+    as?: T;
 } & Omit<React.ComponentPropsWithoutRef<T>, keyof Props | "as" | "ref"> & {
-  ref?: React.ComponentProps<T>["ref"];
-};
+        ref?: React.ComponentProps<T>["ref"];
+    };
 ```
 
 ## Design Tokens
@@ -61,17 +61,13 @@ None — Polymorph itself applies no styles. It is a structural primitive only.
 import { useRef } from "react";
 
 const MyComponent = () => {
-  const buttonRef = useRef<HTMLButtonElement>(null);
+    const buttonRef = useRef<HTMLButtonElement>(null);
 
-  return (
-    <Polymorph
-      as="button"
-      ref={buttonRef}
-      onClick={() => buttonRef.current?.focus()}
-    >
-      Focus Me
-    </Polymorph>
-  );
+    return (
+        <Polymorph as="button" ref={buttonRef} onClick={() => buttonRef.current?.focus()}>
+            Focus Me
+        </Polymorph>
+    );
 };
 ```
 
@@ -79,13 +75,9 @@ const MyComponent = () => {
 
 ```tsx
 const DynamicItem = ({ isLink, href }: { isLink: boolean; href?: string }) => (
-  <Polymorph
-    as={isLink ? "a" : "button"}
-    href={isLink ? href : undefined}
-    className="text-foreground"
-  >
-    {isLink ? "Visit Link" : "Click Button"}
-  </Polymorph>
+    <Polymorph as={isLink ? "a" : "button"} href={isLink ? href : undefined} className="text-foreground">
+        {isLink ? "Visit Link" : "Click Button"}
+    </Polymorph>
 );
 ```
 
@@ -94,22 +86,14 @@ const DynamicItem = ({ isLink, href }: { isLink: boolean; href?: string }) => (
 ```tsx
 import { Polymorph, PolymorphicProps } from "@g4rcez/components";
 
-type CardProps<T extends React.ElementType = "div"> = PolymorphicProps<
-  { variant?: "default" | "muted" },
-  T
->;
-
-const Card = <T extends React.ElementType = "div">({
-  as,
-  variant = "default",
-  className,
-  ...props
-}: CardProps<T>) => (
-  <Polymorph
-    as={as ?? "div"}
-    className={`rounded-card border border-border ${variant === "muted" ? "bg-muted" : "bg-card-background"} ${className ?? ""}`}
-    {...props}
-  />
+type CardProps<T extends React.ElementType = "div"> = PolymorphicProps<{ variant?: "default" | "muted" }, T>;
+
+const Card = <T extends React.ElementType = "div">({ as, variant = "default", className, ...props }: CardProps<T>) => (
+    <Polymorph
+        as={as ?? "div"}
+        className={`rounded-card border border-border ${variant === "muted" ? "bg-muted" : "bg-card-background"} ${className ?? ""}`}
+        {...props}
+    />
 );
 ```
 

package/{dist/ai → ai}/docs/Progress.md

@@ -19,24 +19,24 @@ 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 |
+| 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 |
+| 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
 
@@ -50,16 +50,16 @@ Tokens this component reads. Customize by overriding these CSS variables in your
 
 ```tsx
 function AnimatedProgress() {
-  const [progress, setProgress] = useState(0);
+    const [progress, setProgress] = useState(0);
 
-  useEffect(() => {
-    const timer = setInterval(() => {
-      setProgress((prev) => (prev >= 100 ? 0 : prev + 10));
-    }, 500);
-    return () => clearInterval(timer);
-  }, []);
+    useEffect(() => {
+        const timer = setInterval(() => {
+            setProgress((prev) => (prev >= 100 ? 0 : prev + 10));
+        }, 500);
+        return () => clearInterval(timer);
+    }, []);
 
-  return <Progress percent={progress} />;
+    return <Progress percent={progress} />;
 }
 ```
 
@@ -74,26 +74,30 @@ function AnimatedProgress() {
 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} />}
+{
+    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>
-  );
+    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>
+    );
 }
 ```
 
@@ -101,22 +105,22 @@ function MultiStepForm() {
 
 ```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>
-  );
+    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>
+    );
 }
 ```
 

package/{dist/ai → ai}/docs/Radiobox.md

@@ -21,22 +21,22 @@ import { Radiobox } from "@g4rcez/components/radiobox";
 
 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. |
+| 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 |
+| 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
 
@@ -46,19 +46,19 @@ Tokens this component reads. Customize by overriding these CSS variables in your
 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>
-  );
+    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>
+    );
 }
 ```
 
@@ -68,11 +68,11 @@ export default function PlanSelector() {
 import { Radiobox } from "@g4rcez/components/radiobox";
 
 export default function DisabledOption() {
-  return (
-    <Radiobox disabled name="option" value="legacy">
-      Legacy (unavailable)
-    </Radiobox>
-  );
+    return (
+        <Radiobox disabled name="option" value="legacy">
+            Legacy (unavailable)
+        </Radiobox>
+    );
 }
 ```
 
@@ -82,14 +82,22 @@ export default function DisabledOption() {
 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>
-  );
+    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>
+    );
 }
 ```
 
@@ -116,10 +124,10 @@ export default function GenderSelector() {
 
 ## Data Attributes
 
-| Attribute | Element | Value | Description |
-|-----------|---------|-------|-------------|
-| `data-component` | `label` | `"radiobox"` | Identifies the component. |
-| `data-disabled` | `label` | `true \| undefined` | Set when the radio is disabled. |
+| Attribute        | Element | Value               | Description                     |
+| ---------------- | ------- | ------------------- | ------------------------------- |
+| `data-component` | `label` | `"radiobox"`        | Identifies the component.       |
+| `data-disabled`  | `label` | `true \| undefined` | Set when the radio is disabled. |
 
 ## Notes