@g4rcez/components 4.0.1 → 4.1.1

package/dist/ai/docs/PageCalendar.md

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

@@ -1,284 +0,0 @@
----
-title: Select
-description: Styled native select component with validation, loading state, and form integration.
-package: "@g4rcez/components"
-export: "{ Select }"
-import: "import { Select } from '@g4rcez/components/select'"
-category: form
----
-
-# Select
-
-Styled native select component with validation, loading state, and form integration.
-
-## Import
-
-```tsx
-import { Select } from "@g4rcez/components/select";
-```
-
-## Props
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `options` | `OptionProps[]` | — | Array of option objects. |
-| `selectContainer` | `string` | `""` | Additional CSS classes for the select container. |
-| `required` | `boolean` | `true` | Whether the field is required. |
-| `error` | `string` | — | Error message to display. |
-| `loading` | `boolean` | `false` | Shows a loading indicator and disables the field. |
-| `disabled` | `boolean` | `false` | Disables the select. |
-| `placeholder` | `string` | — | Placeholder shown as a disabled hidden option. |
-| `value` | `string` | — | Controlled selected value. |
-| `onChange` | `(e: ChangeEvent<HTMLSelectElement>) => void` | — | Change handler. |
-| `...inputFieldProps` | `InputFieldProps` | — | All `InputField` props (title, left, right, feedback, etc.). |
-
-### OptionProps
-
-| Prop | Type | Description |
-|------|------|-------------|
-| `value` | `string` | Option value (required). |
-| `label` | `string` | Display text (falls back to `value` if omitted). |
-| `disabled` | `boolean` | Disables this individual option. |
-| `data-dynamic` | `string` | Marks a dynamically generated option. |
-| `data-*` | `string` | Any custom data attributes forwarded to the `<option>`. |
-
-## Design Tokens
-
-Tokens this component reads. Customize by overriding these CSS variables in your theme.
-
-| Token | CSS Variable | Purpose |
-|-------|-------------|---------|
-| `text-foreground` | `--foreground` | Selected option text color |
-| `text-input-placeholder` | `--input-placeholder` | Color when no option is selected |
-| `placeholder-input-placeholder` | `--input-placeholder` | Placeholder styling |
-| `bg-input-mask-error` (via `group-error`) | `--input-mask-error` | Placeholder tint in error state |
-| `text-danger` (via `group-error`) | `--danger` | Text color in error state |
-| `hover:text-primary` | `--primary` | Caret icon hover color |
-| `h-input-height` | `--input-height` | Control height (2.5 rem) |
-| `px-input-x` | `--input-x` | Horizontal padding |
-| `py-input-y` | `--input-y` | Vertical padding |
-
-## Examples
-
-### Basic usage
-
-```tsx
-import { useState } from "react";
-import { Select } from "@g4rcez/components/select";
-
-export default function FruitPicker() {
-  const [value, setValue] = useState("");
-
-  return (
-    <Select
-      title="Fruit"
-      options={[
-        { value: "apple", label: "Apple" },
-        { value: "banana", label: "Banana" },
-        { value: "orange", label: "Orange" },
-      ]}
-      placeholder="Select a fruit"
-      value={value}
-      onChange={(e) => setValue(e.target.value)}
-    />
-  );
-}
-```
-
-### With validation error
-
-```tsx
-import { useState } from "react";
-import { Select } from "@g4rcez/components/select";
-
-export default function CountrySelect() {
-  const [country, setCountry] = useState("");
-  const [error, setError] = useState("");
-
-  return (
-    <Select
-      title="Country"
-      options={[
-        { value: "us", label: "United States" },
-        { value: "ca", label: "Canada" },
-        { value: "uk", label: "United Kingdom" },
-      ]}
-      placeholder="Select country"
-      value={country}
-      error={error}
-      required
-      onChange={(e) => {
-        setCountry(e.target.value);
-        setError(e.target.value ? "" : "Please select a country");
-      }}
-    />
-  );
-}
-```
-
-### With disabled options
-
-```tsx
-import { Select } from "@g4rcez/components/select";
-
-export default function StatusSelect() {
-  return (
-    <Select
-      title="Status"
-      options={[
-        { value: "active", label: "Active" },
-        { value: "pending", label: "Pending" },
-        { value: "legacy", label: "Legacy (deprecated)", disabled: true },
-        { value: "inactive", label: "Inactive" },
-      ]}
-      placeholder="Select status"
-    />
-  );
-}
-```
-
-### Async options with loading state
-
-```tsx
-import { useEffect, useState } from "react";
-import { Select } from "@g4rcez/components/select";
-
-export default function AsyncSelect() {
-  const [options, setOptions] = useState<{ value: string; label: string }[]>([]);
-  const [loading, setLoading] = useState(false);
-  const [value, setValue] = useState("");
-
-  useEffect(() => {
-    setLoading(true);
-    fetchOptions().then((data) => {
-      setOptions(data);
-      setLoading(false);
-    });
-  }, []);
-
-  return (
-    <Select
-      title="Region"
-      options={options}
-      placeholder={loading ? "Loading..." : "Select a region"}
-      value={value}
-      loading={loading}
-      disabled={loading}
-      onChange={(e) => setValue(e.target.value)}
-    />
-  );
-}
-```
-
-### Form integration with `useForm`
-
-```tsx
-import { Select } from "@g4rcez/components/select";
-import { useForm } from "@g4rcez/components/form";
-
-export default function UserForm() {
-  const form = useForm(schema, "userForm");
-
-  return (
-    <form {...form.props}>
-      <Select
-        {...form.select("role")}
-        options={[
-          { value: "admin", label: "Administrator" },
-          { value: "editor", label: "Editor" },
-          { value: "viewer", label: "Viewer" },
-        ]}
-        placeholder="Select role"
-      />
-    </form>
-  );
-}
-```
-
-### Cascading selects
-
-```tsx
-import { useState } from "react";
-import { Select } from "@g4rcez/components/select";
-
-const subcategories: Record<string, { value: string; label: string }[]> = {
-  electronics: [
-    { value: "phones", label: "Phones" },
-    { value: "laptops", label: "Laptops" },
-  ],
-  clothing: [
-    { value: "shirts", label: "Shirts" },
-    { value: "pants", label: "Pants" },
-  ],
-};
-
-export default function CascadingSelect() {
-  const [category, setCategory] = useState("");
-  const [subcategory, setSubcategory] = useState("");
-
-  return (
-    <div className="flex flex-col gap-base">
-      <Select
-        title="Category"
-        options={[
-          { value: "electronics", label: "Electronics" },
-          { value: "clothing", label: "Clothing" },
-        ]}
-        placeholder="Select category"
-        value={category}
-        onChange={(e) => {
-          setCategory(e.target.value);
-          setSubcategory("");
-        }}
-      />
-
-      {category && (
-        <Select
-          title="Subcategory"
-          options={subcategories[category] ?? []}
-          placeholder="Select subcategory"
-          value={subcategory}
-          onChange={(e) => setSubcategory(e.target.value)}
-        />
-      )}
-    </div>
-  );
-}
-```
-
-## Do
-
-- Use descriptive `label` values for each option.
-- Order options logically (alphabetically or by usage frequency).
-- Provide a `placeholder` so users know what to select.
-- Use `loading` and `disabled` together while fetching options asynchronously.
-- Use design-token classes for wrapper elements (`bg-background`, `text-foreground`, `border-border`).
-
-## Don't
-
-- Don't use `Select` for only 2–3 options — prefer `Radiobox` or `Switch` for better visibility.
-- Don't use `Select` for large searchable lists — use `Autocomplete` instead.
-- Don't use long option labels that may truncate on small viewports.
-- 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]`, `bg-[--my-var]`) — override CSS variables in your `@theme` block instead.
-
-## Accessibility
-
-- Uses a native `<select>` element for full keyboard support and screen-reader compatibility.
-- The `placeholder` renders as a `disabled hidden` option so it is never submitted.
-- A `CaretDownIcon` caret is rendered inside a `<label>` pointing to the select id, giving it a larger click target.
-- `data-selected` is set to `"false"` until the user selects an option, which toggles the placeholder color class.
-
-## Data Attributes
-
-| Attribute | Element | Value | Description |
-|-----------|---------|-------|-------------|
-| `data-component` | `InputField` root | `"select"` | Identifies the component. |
-| `data-selected` | `<select>` | `"true" \| "false"` | Whether a non-placeholder option is selected. |
-
-## Notes
-
-- Built on `InputField` for layout, label, error, and loading handling.
-- Supports all standard HTML `<select>` attributes via prop spread.
-- `required` defaults to `true` — pass `required={false}` when the field is optional.
-- Custom data attributes on `OptionProps` (e.g., `data-price`) are forwarded to each `<option>` and accessible via `e.target.selectedOptions[0].dataset`.