@paygreen/pgui 3.0.14 → 3.1.0

package/README.md

@@ -11,7 +11,7 @@ Core UI components library for Paygreen applications built with React and Chakra
 npm install @paygreen/pgui
 
 # Install required peer dependencies
-npm install react react-dom @chakra-ui/react @emotion/react @emotion/styled framer-motion
+npm install react react-dom @chakra-ui/react @emotion/react @emotion/styled
 ```
 
 ### Component-Specific Dependencies
@@ -20,7 +20,7 @@ Install additional packages based on the components you want to use:
 
 | Component | Required Package | Command |
 |-----------|------------------|---------|
-| **DatePicker** | `react-datepicker` | `npm install react-datepicker` |
+| **DatePicker** | `@internationalized/date` | `npm install @internationalized/date` |
 | **Select** | `react-select` | `npm install react-select` |
 | **InputPhone** | `react-phone-number-input` | `npm install react-phone-number-input` |
 | **InputMask** | `use-mask-input` | `npm install use-mask-input` |
@@ -31,7 +31,7 @@ Install additional packages based on the components you want to use:
 
 ```bash
 # Install everything at once
-npm install @paygreen/pgui react react-dom @chakra-ui/react @emotion/react @emotion/styled framer-motion react-datepicker react-select react-phone-number-input use-mask-input @tanstack/react-table react-icons
+npm install @paygreen/pgui react react-dom @chakra-ui/react @emotion/react @emotion/styled @internationalized/date react-select react-phone-number-input use-mask-input @tanstack/react-table react-icons
 ```
 
 ## 🎨 CSS Setup
@@ -58,6 +58,87 @@ function App() {
 }
 ```
 
+## 🎞️ Animations
+
+pgui exposes a curated set of named `animationStyle` presets so consumer apps stop hardcoding durations, easings and keyframes. Apps pick a semantic name; pgui owns the underlying values.
+
+### Available animationStyles
+
+```tsx
+<Box animationStyle="slideInTop" />
+<Box animationStyle={{ _open: 'slideInTop', _closed: 'slideOutTop' }} />
+```
+
+| Name | Composition |
+| --- | --- |
+| `fadeIn` | `fade-in` + `fast` + `decelerate` |
+| `fadeOut` | `fade-out` + `fast` + `accelerate` |
+| `slideInTop` / `slideInBottom` / `slideInLeft` / `slideInRight` | `slide-from-X, fade-in` + `moderate` + `decelerate` |
+| `slideOutTop` / `slideOutBottom` / `slideOutLeft` / `slideOutRight` | `slide-to-X, fade-out` + `fast` + `accelerate` |
+
+Slide distances are Chakra's subtle 0.5rem variants. For panel-sized motion (drawers, full overlays), reach for Chakra's built-in `slide-fade-in/out` (placement-driven) directly.
+
+Enter and exit are intentionally asymmetric: `slideIn*` runs at `moderate` (200ms) with `decelerate` so content settles in; `slideOut*` runs at `fast` (150ms) with `accelerate` so dismissals feel snappy. Fade follows the same enter-slower / exit-faster pacing.
+
+Override `animationDuration` / `animationTimingFunction` at the call site if a specific case needs a different pacing:
+
+```tsx
+<Box animationStyle="slideInTop" animationDuration="slow" />
+```
+
+### Internal tokens
+
+pgui consumes Chakra v3's default duration scale (`fastest` 50ms → `slowest` 500ms) as-is + one off-scale `durations.spin` (800ms) for continuous Spinner / Loader rotation, and adds 3 design-semantic easings (`standard` / `accelerate` / `decelerate`, Material-inspired) alongside Chakra's CSS-keyword easings. These tokens drive the `animationStyle` presets above and pgui-internal component transitions — they are not exposed as a JS bridge for consumer apps.
+
+### Convention
+
+Any duration or easing in pgui or consumer apps should come from a pgui token rather than a hardcoded value (`200ms`, `cubic-bezier(...)`). Reviewed at PR time.
+
+### Enter + exit animations
+
+For elements that mount/unmount based on state (dropdowns, error messages, overlays), use Chakra v3's `<Presence>` with conditional `animationName`. This keeps the element mounted during the exit animation, then unmounts on `animationend`. No JS animation lib required.
+
+```tsx
+import { Presence } from '@chakra-ui/react';
+
+<Presence
+  present={open}
+  animationName={{
+    _open: 'slide-from-top, fade-in',
+    _closed: 'slide-to-top, fade-out',
+  }}
+  animationDuration="moderate"
+  animationTimingFunction="standard"
+>
+  {/* content */}
+</Presence>
+```
+
+The `slide-from-X` / `slide-to-X`, `fade-in` / `fade-out` and `scale-in` / `scale-out` keyframes ship with Chakra v3 — combine them comma-separated for compound entry/exit.
+
+### Tokens consumed by pgui components
+
+For reference when migrating an app: the components below already pull from the tokens above.
+
+| Component | Tokens consumed |
+| --- | --- |
+| `ActionsButton` | `durations.faster`, `easings.standard` |
+| `CardExpandable` (card root) | `durations.moderate` |
+| `CardExpandable` (header hover) | `durations.moderate` |
+| `CardExpandable` (chevron) | `durations.fast`, `easings.standard` |
+| `DataList` (rows) | `durations.moderate` |
+| `DataTable` (row wrapper) | `durations.moderate` |
+| `DatePicker` (calendar enter/exit) | `scale-fade-in` / `scale-fade-out` via the Chakra v3 `datePicker` slot recipe defaults |
+| `FieldWrapper` (error message enter/exit) | `<Presence>` + `slide-from-top, fade-in` / `slide-to-top, fade-out` + `durations.fast` |
+| `InputPhone` (country dropdown enter/exit) | `<Presence>` + `slide-from-top, fade-in` / `slide-to-top, fade-out` + `durations.moderate` |
+| `InputPhone` (option list item) | `durations.faster`, `easings.standard` |
+| `Loader` | `durations.spin` |
+| `Pagination` (page text hover) | `durations.moderate` |
+| `Sidebar` (slide open/close) | `durations.slow` (configurable), `easings.standard` |
+| `Sidebar` (nav item hover) | `durations.moderate`, `easings.standard` |
+
+See the `Foundations / Animations` story in Storybook for live previews.
+
 ## 🔧 Development & Testing
 
 ### Why YALC?
@@ -159,14 +240,6 @@ import '@paygreen/pgui/src/styles/index.css';
 
 If you get an error about missing packages, install the required dependency for the component you're using (see table above).
 
-### Source Map Warnings
-
-If you see warnings about react-datepicker source maps, add this to your `.env` file:
-
-```bash
-GENERATE_SOURCEMAP=false
-```
-
 ## 📋 Requirements
 
 - **React** ^18.0.0 || ^19.0.0

package/dist/components/date-picker/date-picker.d.ts

@@ -1,85 +1,91 @@
+import { ReactNode } from 'react';
+import { DatePickerLocale } from './utils';
+export { formatDateRange, formatDateValue, fromDateValue, localeToBcp47, parseDateInput, toCalendarDate, toCalendarDateTime, } from './utils';
+export type { DatePickerLocale } from './utils';
 /**
- * Props for the DatePicker component
+ * Preset values recognized natively by Ark UI's date-picker state
+ * machine (mirrors `@zag-js/date-utils`' `DateRangePreset`).
  */
-export interface DatePickerProps {
-    /** ID attribute for the input element */
-    id?: string;
-    /** Name attribute for form integration */
-    name?: string;
-    /** The selected date or date range */
-    value?: Date | [Date | null, Date | null] | null;
-    /** Label text displayed above the input */
-    label?: string;
-    /** Callback fired when the date selection changes */
-    onChange?: (date: Date | [Date | null, Date | null] | null) => void;
-    /** Whether to enable date range selection */
-    isRange?: boolean;
-    /** Whether to enable time selection */
-    isDateTime?: boolean;
-    /** Custom placeholder text for the input (overrides default format placeholder) */
+export type DatePickerPresetValue = 'thisWeek' | 'lastWeek' | 'thisMonth' | 'lastMonth' | 'thisQuarter' | 'lastQuarter' | 'thisYear' | 'lastYear' | 'last3Days' | 'last7Days' | 'last14Days' | 'last30Days' | 'last90Days';
+/** A quick-select preset rendered as a button beside the calendar. */
+export interface DatePickerPreset {
+    value: DatePickerPresetValue;
+    label: string;
+}
+interface CommonProps {
+    /**
+     * Standard field label rendered above the inputs via `<ArkDatePicker.Label>`
+     * (Chakra v3 convention). Use this for the canonical "label above field"
+     * pattern. Can coexist with `inputLabel`.
+     */
+    label?: ReactNode;
+    /**
+     * Floating label rendered on the top border of the input area, matching
+     * the pgui `<Input>` / `<InputMask>` visual pattern.
+     *
+     * Distinct from `label`: `label` sits *above* the field (Chakra default),
+     * `inputLabel` sits *on* the field's border (pgui floating style). Both
+     * may be used together if needed.
+     */
+    inputLabel?: ReactNode;
+    /** Placeholder text shown when no date is selected */
     placeholder?: string;
-    /** Locale string for date formatting and translations ('en', 'fr') */
-    locale?: 'en' | 'fr';
-    /** Minimum selectable date */
-    minDate?: Date;
-    /** Maximum selectable date */
-    maxDate?: Date;
-    /** Custom date format string */
-    dateFormat?: string;
-    /** Callback fired when the input loses focus */
+    /** Locale for month/weekday names and date formatting */
+    locale?: DatePickerLocale;
+    /** Earliest selectable date */
+    minDate?: Date | null;
+    /** Latest selectable date */
+    maxDate?: Date | null;
+    /** Fired when the input loses focus */
     onBlur?: () => void;
-    /** Whether the input is disabled */
+    /** Disable the whole picker */
     disabled?: boolean;
-    /** Whether to show a clear button when there's a value (default: true) */
+    /** Mark the inputs as required (HTML form validation) */
+    required?: boolean;
+    /** Show a clear button when a value is set (default: true) */
     clearable?: boolean;
-    /** Whether the input is in invalid state */
+    /** Form field name (in range mode, `${name}.start` / `${name}.end`) */
+    name?: string;
+    /** Marks the inputs as invalid (`aria-invalid` propagated) */
     invalid?: boolean;
+    /**
+     * Optional quick-select presets rendered as a sidebar inside the
+     * popper. When omitted, the calendar is shown without a sidebar.
+     */
+    presets?: DatePickerPreset[];
+}
+interface SingleProps extends CommonProps {
+    isRange?: false;
+    /**
+     * Add a time input below the day calendar (selection emits a `Date`
+     * with both date and time set). Only available in single mode.
+     */
+    withTime?: boolean;
+    value?: Date | null;
+    onChange?: (date: Date | null) => void;
 }
+interface RangeProps extends CommonProps {
+    isRange: true;
+    value?: [Date | null, Date | null] | null;
+    onChange?: (range: [Date | null, Date | null] | null) => void;
+}
+export type DatePickerProps = SingleProps | RangeProps;
 /**
- * A reusable date picker component with floating label and range selection support
- *
- * @example
- * ```tsx
- * // Default behavior - shows format as placeholder (mm/dd/yyyy)
- * <DatePicker
- *   label="Birthdate"
- *   value={date}
- *   onChange={setDate}
- * />
- *
- * // French locale - shows French format (jj/mm/aaaa)
- * <DatePicker
- *   label="Date de naissance"
- *   value={date}
- *   onChange={setDate}
- *   locale="fr"
- * />
- *
- * // With custom placeholder (overrides default format)
- * <DatePicker
- *   label="Birthdate"
- *   value={date}
- *   onChange={setDate}
- *   placeholderText="Choose your birthdate"
- * />
+ * `DatePicker` is the pgui facade over Chakra v3's compound
+ * `ArkDatePicker.*` namespace (Ark UI / @zag-js/date-picker). It exposes a
+ * single-component API that speaks JS `Date` (compat-friendly with legacy
+ * app code) and bundles:
  *
- * // To disable the clear button:
- * <DatePicker
- *   label="Birthdate"
- *   value={date}
- *   onChange={setDate}
- *   clearable={false}
- * />
+ * - locale-aware format/parse (`dd/MM/yyyy` FR, `MM/dd/yyyy` EN, tolerant
+ *   to `/`, `-`, `.`)
+ * - 3 views (day / month / year) with the default Chakra header
+ * - 1 read-only input in range mode displaying `"DD MMM YYYY - DD MMM YYYY"`;
+ *   submission via hidden inputs `${name}.start` / `${name}.end` (ISO)
+ * - calendar popper inside `<Portal>` (avoids clip by overflow / modals)
+ * - conditional Clear trigger + calendar Trigger via `ArkDatePicker.Context`
  *
- * // With name and id for form integration:
- * <DatePicker
- *   id="birthdate-input"
- *   name="birthdate"
- *   label="Birthdate"
- *   value={date}
- *   onChange={setDate}
- * />
- * ```
+ * For one-off custom layouts, import `DatePicker` directly from
+ * `@chakra-ui/react` and assemble the parts yourself.
  */
-declare const DatePicker: import('react').ForwardRefExoticComponent<DatePickerProps & import('react').RefAttributes<HTMLInputElement>>;
+declare const DatePicker: import('react').ForwardRefExoticComponent<DatePickerProps & import('react').RefAttributes<HTMLDivElement>>;
 export { DatePicker };

package/dist/components/date-picker/utils.d.ts

@@ -0,0 +1,48 @@
+import { CalendarDate, CalendarDateTime, DateValue } from '@internationalized/date';
+/**
+ * Locale strings accepted by `DatePicker`. Internally mapped to
+ * BCP-47 via `localeToBcp47`.
+ */
+export type DatePickerLocale = 'en' | 'fr';
+/**
+ * Convert a JS `Date` (or null/undefined) to an `@internationalized/date`
+ * `CalendarDate`. Returns `undefined` for nullish inputs so the value can
+ * be passed straight to `<DatePicker.Root min|max>` props.
+ */
+export declare const toCalendarDate: (date: Date | null | undefined) => CalendarDate | undefined;
+/**
+ * Like `toCalendarDate` but preserves the hour/minute of the input —
+ * used by `DatePicker` when `withTime` is enabled.
+ */
+export declare const toCalendarDateTime: (date: Date | null | undefined) => CalendarDateTime | undefined;
+/**
+ * Convert a `DateValue` back to a local-time-zone JS `Date`. Returns
+ * `null` for nullish inputs so consumers can rely on a single sentinel.
+ */
+export declare const fromDateValue: (value: DateValue | undefined) => Date | null;
+/**
+ * Map the simple `'en' | 'fr'` locale used by pgui to the BCP-47 tag
+ * required by `@internationalized/date` and the Chakra DatePicker.
+ */
+export declare const localeToBcp47: (locale: DatePickerLocale) => string;
+/**
+ * Format a `DateValue` for the editable single-mode input, locale-aware
+ * (`dd/MM/yyyy` for FR, `MM/dd/yyyy` for EN). When `withTime`, appends
+ * 2-digit `HH:mm`.
+ */
+export declare const formatDateValue: (date: DateValue, bcp47Locale: string, withTime: boolean) => string;
+/**
+ * Format a `DateValue[]` (range) into a single display string like
+ * `"18 Oct 2026 - 18 Nov 2026"` (or French `"18 oct. 2026 - 18 nov. 2026"`).
+ * For a partial range with only the start date, returns `"18 Oct 2026 - …"`
+ * so the user has a visual cue that the end date is still pending.
+ * Returns empty string when no date has been picked.
+ */
+export declare const formatDateRange: (values: DateValue[], bcp47Locale: string) => string;
+/**
+ * Parse a user-typed date string into a `CalendarDate`. Accepts `/`, `-`,
+ * or `.` as separators. The day/month ordering follows the locale:
+ * `dd/MM/yyyy` for FR, `MM/dd/yyyy` for EN. Returns `undefined` for any
+ * malformed or out-of-range input.
+ */
+export declare const parseDateInput: (raw: string, locale: DatePickerLocale) => CalendarDate | undefined;

package/dist/components/loader/loader.d.ts

@@ -15,7 +15,7 @@ export interface LoaderProps extends SpinnerProps {
  *
  * @example
  * ```tsx
- * <Loader  size="lg" loading={false} />
+ * <Loader size="lg" loading={false} />
  * ```
  */
 declare const Loader: {

package/dist/components/sidebar/sidebar.d.ts

@@ -14,7 +14,7 @@ export interface SidebarTheme {
     boxShadow?: string;
     /** Z-index value */
     zIndex?: number | string;
-    /** Transition duration for animations */
+    /** Transition duration for animations. Prefer a pgui token name (e.g. `'slow'`); a raw CSS duration is accepted for legacy callers. */
     transitionDuration?: string;
 }
 /**

package/dist/hooks/index.d.ts

@@ -1,3 +1,4 @@
 export { useDataTable } from './use-data-table';
 export { useDebouncedLoadOptions } from './use-debounced-load-options';
 export { useHasScrollbar } from './use-has-scrollbar';
+export { useOutsideClick } from './use-outside-click';

package/dist/hooks/use-outside-click.d.ts

@@ -0,0 +1,13 @@
+import { RefObject } from 'react';
+interface UseOutsideClickProps {
+    ref: RefObject<HTMLElement | null>;
+    handler: (event: Event) => void;
+    enabled?: boolean;
+}
+/**
+ * Hook that fires a handler when a pointer interaction occurs outside the
+ * referenced element. Handles both mouse and touch input, and ignores
+ * emulated mouse events that follow a touch sequence.
+ */
+export declare function useOutsideClick({ ref, handler, enabled, }: UseOutsideClickProps): void;
+export {};

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+export * from './styled-system';
 export * from './components';
 export { default as PGUISystemContext } from './theme';
 export * from './utils';