@g4rcez/components 3.0.0 → 3.0.1

package/dist/ai/docs/Notifications.md

@@ -0,0 +1,231 @@
+---
+title: Notifications
+description: Toast notification system with themes, stacking, swipe-to-dismiss, and programmatic control.
+package: "@g4rcez/components"
+export: "{ Notifications }"
+import: "import { Notifications, useNotification } from '@g4rcez/components/notifications'"
+category: display
+---
+
+# Notifications
+
+Toast notification system with themes, stacking, swipe-to-dismiss, and programmatic control.
+
+## Import
+
+```tsx
+import { Notifications, useNotification } from "@g4rcez/components/notifications";
+```
+
+## Setup
+
+Wrap your app (or the subtree that needs toasts) with `Notifications`:
+
+```tsx
+import { Notifications } from "@g4rcez/components/notifications";
+
+function App() {
+  return (
+    <Notifications max={5} timeout={5000}>
+      <YourApp />
+    </Notifications>
+  );
+}
+```
+
+## Props
+
+### Notifications (Provider)
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `max` | `number` | `5` | Maximum notifications displayed at once |
+| `timeout` | `number` | `5000` | Default auto-dismiss duration in milliseconds |
+| `children` | `React.ReactNode` | — | Subtree that can use `useNotification` |
+
+### useNotification — notify function
+
+```tsx
+const notify = useNotification();
+const subscription = notify(message, options);
+```
+
+**Parameters**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `message` | `Label` | Notification body text (string or React node) |
+| `options` | `NotificationOptions` | Optional configuration (see below) |
+
+**NotificationOptions**
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `id` | `string` | — | Stable ID; if provided and a toast with this ID exists, it will be updated instead of duplicated |
+| `title` | `Label` | — | Optional notification title |
+| `theme` | `NotificationTheme` | `"default"` | Visual theme variant |
+| `timeout` | `number` | Provider default | Override auto-dismiss duration in ms |
+| `closable` | `boolean` | `true` | Show close button |
+| `loading` | `boolean` | `false` | Replaces icon with spinning `Loader2Icon` |
+
+**Return value — NotificationSubscriber**
+
+| Method | Description |
+|--------|-------------|
+| `close()` | Dismiss this specific notification |
+| `clear()` | Dismiss all visible notifications |
+
+## Themes
+
+| Value | Appearance |
+|-------|-----------|
+| `"default"` | Card background with foreground text |
+| `"info"` | `bg-alert-info-bg` / `text-alert-info-text` / `border-alert-info-border` |
+| `"success"` | `bg-alert-success-bg` / `text-alert-success-text` / `border-alert-success-border` |
+| `"warn"` | `bg-alert-warn-bg` / `text-alert-warn-text` / `border-alert-warn-border` |
+| `"danger"` | `bg-alert-danger-bg` / `text-alert-danger-text` / `border-alert-danger-border` |
+| `"secondary"` | `bg-alert-secondary-bg` / `text-alert-secondary-text` / `border-alert-secondary-border` |
+| `"muted"` | `bg-alert-muted-bg` / `text-alert-muted-text` / `border-alert-muted-border` |
+
+## Design Tokens
+
+Tokens this component reads. Customize by overriding these CSS variables in your theme.
+
+| Token | CSS Variable | Purpose |
+|-------|-------------|---------|
+| `bg-card-background` | `--card-background` | Default notification background |
+| `border-card-border` | `--card-border` | Default notification border |
+| `text-foreground` | `--foreground` | Default notification text |
+| `bg-alert-{theme}-bg` | `--alert-{theme}-bg` | Themed background |
+| `text-alert-{theme}-text` | `--alert-{theme}-text` | Themed text |
+| `border-alert-{theme}-border` | `--alert-{theme}-border` | Themed border |
+
+## Examples
+
+### Basic Notifications
+
+```tsx
+function NotificationExamples() {
+  const notify = useNotification();
+
+  return (
+    <div className="space-y-2">
+      <button onClick={() => notify("Default notification")}>Default</button>
+      <button onClick={() => notify("Info message", { theme: "info" })}>Info</button>
+      <button onClick={() => notify("Success!", { theme: "success" })}>Success</button>
+      <button onClick={() => notify("Warning", { theme: "warn" })}>Warning</button>
+      <button onClick={() => notify("Error occurred", { theme: "danger" })}>Error</button>
+    </div>
+  );
+}
+```
+
+### With Title
+
+```tsx
+function SaveButton() {
+  const notify = useNotification();
+
+  const handleSave = () => {
+    notify("Your changes have been saved to the server.", {
+      title: "Changes Saved",
+      theme: "success",
+      timeout: 3000,
+    });
+  };
+
+  return <button onClick={handleSave}>Save</button>;
+}
+```
+
+### Persistent Notification with Manual Close
+
+```tsx
+function ProcessButton() {
+  const notify = useNotification();
+
+  const startProcess = () => {
+    const subscription = notify("Processing your request…", {
+      title: "In Progress",
+      theme: "info",
+      timeout: Infinity,
+      closable: false,
+      loading: true,
+    });
+
+    doWork().then(() => {
+      subscription.close();
+      notify("Process completed successfully!", { theme: "success" });
+    });
+  };
+
+  return <button onClick={startProcess}>Start</button>;
+}
+```
+
+### Form Submission Feedback
+
+```tsx
+function ContactForm() {
+  const notify = useNotification();
+
+  const handleSubmit = async (e: React.FormEvent) => {
+    e.preventDefault();
+    try {
+      await submitForm();
+      notify("Message sent successfully.", { title: "Done", theme: "success" });
+    } catch {
+      notify("Failed to send. Please try again.", {
+        title: "Error",
+        theme: "danger",
+        timeout: 7000,
+      });
+    }
+  };
+
+  return <form onSubmit={handleSubmit}>{/* fields */}</form>;
+}
+```
+
+### Updating an Existing Toast
+
+```tsx
+const SYNC_ID = "data-sync";
+const notify = useNotification();
+
+// Show initial state
+notify("Syncing data…", { id: SYNC_ID, theme: "info", timeout: Infinity });
+
+// Update in-place when done
+notify("Sync complete.", { id: SYNC_ID, theme: "success", timeout: 3000 });
+```
+
+## Do
+
+- Use the correct `theme` to convey message severity (`success`, `danger`, `warn`).
+- Keep messages short — toasts are glanced at, not read.
+- Use `title` for important notifications that need extra prominence.
+- Set a longer `timeout` (or `Infinity`) for critical errors that need user attention.
+- Use `loading: true` for in-progress operations to signal activity.
+
+## Don't
+
+- Don't pass raw Tailwind color classes (`bg-blue-500`, `text-white`) — use `theme` instead.
+- Don't use arbitrary Tailwind values (`bg-[#abc]`) — override CSS variables in your `@theme` block.
+- Don't use notifications for information that must be acknowledged before proceeding — use a `Modal` instead.
+- Don't show more than 3–5 notifications at a time; configure `max` accordingly.
+- Don't use notifications for persistent status indicators — use `Alert` or a status bar.
+
+## Accessibility
+
+- Built on Base UI Toast which manages ARIA live regions for screen reader announcements.
+- Close buttons are keyboard accessible with visible focus states.
+- Swipe-to-dismiss works on touch devices via the Base UI primitive.
+- The viewport is positioned with `role` semantics handled by the underlying primitive.
+
+## Notes
+
+- Up to 3 notifications are visible by default; hovering the stack reveals all (up to `max`).
+- Animations use Framer Motion (`motion/react`) with spring physics for enter/exit.
+- The viewport is centered horizontally at the top of the viewport (`top-6`, `z-[100]`).
+- When `max` is exceeded, a pill showing `+N more` appears below the visible toasts.

package/dist/ai/docs/PageCalendar.md

@@ -0,0 +1,271 @@
+---
+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 "lucide-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/docs/Polymorph.md

@@ -0,0 +1,159 @@
+---
+title: Polymorph
+description: A polymorphic component that renders as any HTML element while maintaining full TypeScript type safety.
+package: "@g4rcez/components"
+export: "{ Polymorph }"
+import: "import { Polymorph } from '@g4rcez/components'"
+category: core
+---
+
+# Polymorph
+
+A polymorphic component that renders as any HTML element while maintaining full TypeScript type safety. It is the foundational primitive used internally by `Button`, `Tag`, `Heading`, `RenderOnView`, and other components in the library.
+
+## Import
+
+```tsx
+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 |
+
+## Type Definitions
+
+```tsx
+export type PolymorphicProps<Props, T extends React.ElementType> = Props & {
+  as?: T;
+} & Omit<React.ComponentPropsWithoutRef<T>, keyof Props | "as" | "ref"> & {
+  ref?: React.ComponentProps<T>["ref"];
+};
+```
+
+## Design Tokens
+
+None — Polymorph itself applies no styles. It is a structural primitive only.
+
+## Examples
+
+### Basic Elements
+
+```tsx
+<Polymorph>Default span</Polymorph>
+
+<Polymorph as="button" onClick={() => void 0}>
+  Button
+</Polymorph>
+
+<Polymorph as="a" href="https://example.com" target="_blank">
+  External Link
+</Polymorph>
+```
+
+### With Refs
+
+```tsx
+import { useRef } from "react";
+
+const MyComponent = () => {
+  const buttonRef = useRef<HTMLButtonElement>(null);
+
+  return (
+    <Polymorph
+      as="button"
+      ref={buttonRef}
+      onClick={() => buttonRef.current?.focus()}
+    >
+      Focus Me
+    </Polymorph>
+  );
+};
+```
+
+### Conditional Element Type
+
+```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>
+);
+```
+
+### Building Higher-Order Components
+
+```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}
+  />
+);
+```
+
+### TypeScript Safety
+
+```tsx
+// Valid — button accepts type and disabled
+<Polymorph as="button" type="submit" disabled />
+
+// Valid — anchor accepts href and target
+<Polymorph as="a" href="/link" target="_blank" />
+
+// TypeScript error — href is not valid on button
+// <Polymorph as="button" href="/link" />
+```
+
+## Do
+
+- Use `Polymorph` as the base when building library components that need element flexibility
+- Always provide a meaningful default for `as` in derived components
+- Forward refs from your wrapper to `Polymorph` so consumers can access the DOM node
+- Use design-token classes for any styling you apply (`text-foreground`, `bg-primary`, etc.)
+
+## Don't
+
+- Don't use `Polymorph` when the element type is fixed and will never change — use the native element directly
+- Don't pass raw Tailwind color classes (`text-gray-800`, `bg-blue-500`) when building styled wrappers
+- Don't use arbitrary Tailwind values (`text-[#333]`) — override CSS variables in your `@theme` block
+- Don't pass props that are invalid for the target element (TypeScript will flag these at compile time)
+
+## Accessibility
+
+- `Polymorph` adds no ARIA attributes of its own — the rendered element's semantics are determined by the `as` prop
+- When `as="button"` is omitted and you need interactive behavior, prefer `as="button"` over `as="div"` with an `onClick`
+- Refs are forwarded correctly, enabling programmatic focus management
+
+## Data Attributes
+
+- No data attributes are set by `Polymorph` itself
+- Components built on top of `Polymorph` (e.g., `Button`, `Tag`) add their own `data-component` attribute
+
+## Notes
+
+- The default element is `<span>` when no `as` prop is provided
+- The `as` prop is stripped before forwarding to the DOM element to prevent unknown attribute warnings
+- Refs are forwarded via `React.forwardRef`
+- `PolymorphicProps` is exported and can be used to type custom components built on `Polymorph`