@paygreen/pgui 2.14.9 → 3.0.0-beta

package/README.md

@@ -1,109 +1,175 @@
-# PGUI 🌿
+# @paygreen/pgui
 
-## Information
-PGUI is the current Paygreen's Design System. The purpose of the package is to provide Components for [Paygreen](https://paygreen.io) applications that works with [Chakra UI](https://chakra-ui.com)
-___
+Core UI components library for Paygreen applications built with React and Chakra UI.
 
-## Getting Started
-To setup PGUI in a local environment, please install the package in your target project.
+## 📦 Installation
 
-```bash
-npm i @paygreen/pgui
-```
+### Base Installation
 
-```javascript
-import { ChakraProvider } from '@chakra-ui/react';
-import { theme } from '@paygreen/pgui',
+```bash
+# Install the core library
+npm install @paygreen/pgui
 
-<ChakraProvider theme={theme}>
-  {Your App}
-</ChakraProvider>
+# Install required peer dependencies
+npm install react react-dom @chakra-ui/react @emotion/react @emotion/styled framer-motion
 ```
-___
 
-## Develop a new component
+### Component-Specific Dependencies
 
-If you need to develop or update a component you will need to create a new folder with your component's name inside ```src/components```. Inside this folder you'll need to create 2 files, ```index.tsx``` and ```docs.stories.tsx``` if needed.
+Install additional packages based on the components you want to use:
 
-Don't hesite to refer yourself to ```FormGroup``` component which is a good simple component created with Chakra.
+| Component | Required Package | Command |
+|-----------|------------------|---------|
+| **DatePicker** | `react-datepicker` | `npm install react-datepicker` |
+| **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` |
+| **DataTable** | `@tanstack/react-table` | `npm install @tanstack/react-table` |
+| **All Icons** | `react-icons` | `npm install react-icons` |
 
-When your component is finished, you will need to export it globally on the
-```src/components/index.ts``` and ```src/index.ts``` file.
+### Complete Installation (All Components)
 
-To make your modifications accessible, build the package with rollup.
 ```bash
-npm run build
+# 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
 ```
-___
 
-## Storybook
+## 🎨 CSS Setup
 
-When you add a component and you write documentation, you can see it in storybook.
-To run storybook please use the command
-```bash
-npm run storybook
+```javascript
+// In your main App.js or index.js
+import '@paygreen/pgui/src/styles/index.css';
 ```
 
-It should open you storybook on your localhost:6006 port.
-___
+## 🚀 Basic Usage
 
-## Link PGUI development into your current React project
+```javascript
+import React from 'react';
+import { ChakraProvider } from '@chakra-ui/react';
+import { DatePicker, Select, Input, systemTheme } from '@paygreen/pgui';
+import '@paygreen/pgui/src/styles/index.css';
+
+function App() {
+  return (
+    <ChakraProvider value={systemTheme}>
+      {/* Your components */}
+    </ChakraProvider>
+  );
+}
+```
+
+## 🔧 Development & Testing
+
+### Why YALC?
 
-You will need to link Chakra UI and React packages from your target project to PGUI and then link PGUI to your target project as the schema explains here.
+**YALC** (Yet Another Local Cache) is the best tool for testing libraries locally because it:
 
-![Screenshot](pgui-schema.png)
+- ✅ **No symlinks** - Avoids React duplicate issues from `npm link`
+- ✅ **Real package simulation** - Works exactly like published packages
+- ✅ **Fast updates** - Push changes instantly to consuming projects
+- ✅ **No conflicts** - Prevents peer dependency resolution issues
+- ✅ **Production-like** - Tests the actual built package, not source
 
-To do that please follow these steps
+### Setting up YALC
+
+#### 1. Install YALC globally
 
-1. in ```/target_app/node_modules/@chakra-ui/react```, this will create 1st symlink to @chakra-ui/react
 ```bash
-npm link
+npm install -g yalc
 ```
 
-2. in ```/target_app/node_modules/react```, this will create 2nd symlink react
+#### 2. In this library (pgui/)
+
 ```bash
-npm link
+# Build and publish to local store
+npm run build
+yalc publish
+
+# For development - rebuild and push changes
+npm run build
+yalc push  # Updates all projects using this package
 ```
 
-3. in ```/pgui```, this will create 3rd symlink to pgui library
+#### 3. In your test project
+
 ```bash
-npm link
+# Install from local YALC store
+yalc add @paygreen/pgui
+npm install
+
+# When done testing, clean up
+yalc remove @paygreen/pgui
+npm install @paygreen/pgui  # Back to npm registry
 ```
 
-4. in ```/pgui```, this will link your local packages @chakra-ui/react and react
+### Development Workflow
+
 ```bash
-npm run link-local-lib
+# 1. Make changes to components in pgui/
+# 2. Build and push
+npm run build && yalc push
+
+# 3. Your test project automatically gets the updates
+# 4. Test your changes
+
+# 5. When ready, publish to npm
+npm publish
 ```
 
-5. in ```/pgui```, this will build your project
+### Useful YALC Commands
+
 ```bash
-npm run build
+# See which packages are published locally
+yalc installations show
+
+# Remove package from YALC store
+yalc remove @paygreen/pgui --all
+
+# Clean all YALC installations
+yalc remove --all
 ```
 
-6. in ```/target_app```, this will link pgui to your local app directory
+## 🏗️ Building
+
 ```bash
-npm link @paygreen/pgui
+# Build the library
+npm run build
+
+# Output files:
+# - dist/index.mjs (ES modules)
+# - dist/index.js (CommonJS)
+# - dist/index.d.ts (TypeScript definitions)
+# - dist/pgui.css (Compiled styles)
 ```
 
-7. it should works well, you just now have to link your theme with the one on PGUI on your ChakraProvider in your target project, and then use the components you need! 🥳
+## 🐛 Troubleshooting
 
-> See all links
-```
-npm ls --link --global
+### CSS Not Loading
+
+Make sure you import the CSS file:
+
+```javascript
+import '@paygreen/pgui/src/styles/index.css';
 ```
 
-Instead of use npm link, to real-time testing your component, run ```npx relative-deps``` in the APP project ad restart it.
+### Missing Dependencies
 
-Then your modifications will be available on your target project.
+If you get an error about missing packages, install the required dependency for the component you're using (see table above).
 
-___
+### Source Map Warnings
 
-## Troubleshooting
+If you see warnings about react-datepicker source maps, add this to your `.env` file:
 
-### React Invalid Hook Call Warning
-If you have an error based on [React Invalid Hook Call Warning](https://reactjs.org/warnings/invalid-hook-call-warning.html), this is because you're trying to use the local project without npm link (on chakra-ui/react or react). Please use the command to normally solve it
 ```bash
-npm run link-local-lib
+GENERATE_SOURCEMAP=false
 ```
 
-If it doesn't work, please refer to Getting Started guide to check the npm link process.
+## 📋 Requirements
+
+- **React** ^18.0.0 || ^19.0.0
+- **Node.js** >= 16
+- **TypeScript** >= 4.5 (if using TypeScript)
+
+## 📄 License
+
+Private - Paygreen Internal Use Only

package/dist/components/actions-button/actions-button.d.ts

@@ -0,0 +1,20 @@
+import { IconButtonProps } from '@chakra-ui/react';
+/**
+ * Props for the ActionsButton component
+ */
+export interface ActionsButtonProps extends Omit<IconButtonProps, 'aria-label' | 'icon'> {
+    /** Accessible label for the action button (used for aria-label) */
+    label: string;
+    /** Optional custom icon to display instead of the default three dots */
+    icon?: React.ReactElement;
+}
+/**
+ * ActionsButton component - A semantic action button for triggering contextual menus
+ *
+ * @example
+ * ```tsx
+ * <ActionsButton label="Open actions menu" />
+ * ```
+ */
+declare const ActionsButton: import('react').ForwardRefExoticComponent<ActionsButtonProps & import('react').RefAttributes<HTMLButtonElement>>;
+export { ActionsButton };

package/dist/components/data-list/datalist.d.ts

@@ -0,0 +1,88 @@
+import { default as React } from 'react';
+import { AccordionItemProps, AccordionRootProps, FlexProps } from '@chakra-ui/react';
+/**
+ * Record mapping column names to their configuration properties
+ */
+interface DataListColumns extends Record<string, DataListCellProps> {
+}
+/**
+ * Props for individual data list cells that represent table columns
+ */
+interface DataListCellProps extends FlexProps {
+    /** Unique identifier for the column, used to link header and body cells */
+    colName?: string;
+    /** Column width configuration - can be relative number, CSS unit, or responsive object */
+    colWidth?: string | number | Record<string, string | number>;
+    /** Column visibility configuration - can be boolean or responsive object */
+    isVisible?: boolean | boolean[] | Record<string, boolean>;
+}
+/**
+ * Props for accordion items within the DataList
+ */
+interface DataListAccordionProps extends AccordionItemProps {
+    /** Unique string identifier for the accordion item */
+    value: string;
+}
+/**
+ * Props for DataList row components
+ */
+interface DataListRowProps extends FlexProps {
+    /** Row visibility configuration - can be boolean or responsive object */
+    isVisible?: boolean | boolean[] | Record<string, boolean>;
+    /** Whether the row is disabled (grayed out and non-interactive) */
+    isDisabled?: boolean;
+}
+/**
+ * Props for DataList header component
+ */
+interface DataListHeaderProps extends DataListRowProps {
+}
+/**
+ * Props for DataList footer component
+ */
+interface DataListFooterProps extends DataListRowProps {
+}
+/**
+ * Main props for the DataList component
+ */
+interface DataListProps extends AccordionRootProps {
+    /** Whether to enable hover effects on rows */
+    isHover?: boolean;
+}
+/**
+ * DataList component - A flexible data list with accordion functionality
+ *
+ * @example
+ * ```tsx
+ * <DataList>
+ *   <DataList.Header>
+ *     <DataList.Cell colName="name">Name</DataList.Cell>
+ *     <DataList.Cell colName="email">Email</DataList.Cell>
+ *   </DataList.Header>
+ *   <DataList.Row>
+ *     <DataList.Cell colName="name">John Doe</DataList.Cell>
+ *     <DataList.Cell colName="email">john@example.com</DataList.Cell>
+ *   </DataList.Row>
+ * </DataList>
+ * ```
+ */
+declare const DataList: {
+    ({ multiple, collapsible, isHover, ...rest }: DataListProps): import("react/jsx-runtime").JSX.Element;
+    Cell: React.NamedExoticComponent<DataListCellProps>;
+    Row({ isVisible, isDisabled, ...rest }: DataListRowProps): import("react/jsx-runtime").JSX.Element;
+    Header({ ...rest }: DataListHeaderProps): import("react/jsx-runtime").JSX.Element;
+    Footer({ ...rest }: DataListFooterProps): import("react/jsx-runtime").JSX.Element;
+    Accordion({ value, ...rest }: DataListAccordionProps): import("react/jsx-runtime").JSX.Element;
+    AccordionButton({ ...rest }: {
+        [x: string]: any;
+    }): import("react/jsx-runtime").JSX.Element;
+    AccordionIcon({ ...rest }: {
+        [x: string]: any;
+    }): import("react/jsx-runtime").JSX.Element;
+    AccordionPanel({ ...rest }: {
+        [x: string]: any;
+    }): import("react/jsx-runtime").JSX.Element;
+    displayName: string;
+};
+export { DataList };
+export type { DataListAccordionProps, DataListCellProps, DataListColumns, DataListFooterProps, DataListHeaderProps, DataListProps, DataListRowProps, };

package/dist/components/data-table/data-table.d.ts

@@ -0,0 +1,67 @@
+import { default as React } from 'react';
+import { ColumnDef, ColumnFiltersState, SortingState } from '@tanstack/react-table';
+import { PaginationProps } from '../pagination/pagination';
+/**
+ * Configuration for DataTable pagination
+ */
+export interface DataTablePagination extends PaginationProps {
+    /** Whether to enable client-side pagination (all data loaded at once) */
+    enableClientSide?: boolean;
+}
+/**
+ * Props for the DataTable component
+ */
+export interface DataTableProps<TData> {
+    /** Array of data objects to display in the table */
+    data: TData[];
+    /** Column definitions for the table structure and rendering */
+    columns: ColumnDef<TData, any>[];
+    /** Pagination configuration (optional) */
+    pagination?: DataTablePagination;
+    /** Visual variant of the table */
+    variant?: 'simple' | 'striped';
+    /** Enable column filtering functionality */
+    enableFiltering?: boolean;
+    /** Enable column sorting functionality */
+    enableSorting?: boolean;
+    /** Content to display when no data is available */
+    emptyState?: React.ReactNode;
+    /** Enable responsive behavior (mobile cards view) */
+    responsive?: boolean;
+    /** Mobile view mode when responsive is enabled */
+    mobileView?: 'cards' | 'scroll';
+    /** Force mobile view regardless of screen size */
+    isMobile?: boolean;
+    /** Show loading state */
+    isLoading?: boolean;
+    /** Callback fired when column filters change */
+    onFilterChange?: (filters: ColumnFiltersState) => void;
+    /** Callback fired when sorting changes */
+    onSortingChange?: (sorting: SortingState) => void;
+    /** Callback fired when a row is clicked */
+    onRowClick?: (row: TData) => void;
+}
+/**
+ * DataTable component - A flexible, responsive data table with sorting, filtering, and pagination
+ *
+ * @example
+ * ```tsx
+ * <DataTable
+ *   data={users}
+ *   columns={columns}
+ *   enableSorting
+ *   enableFiltering
+ *   pagination={{
+ *     page: 1,
+ *     pageSize: 10,
+ *     totalItems: 100,
+ *     setPage: setCurrentPage
+ *   }}
+ * />
+ * ```
+ */
+declare function DataTable<TData>({ data, columns, pagination, variant, enableFiltering, enableSorting, emptyState, responsive, mobileView, isMobile, isLoading, onFilterChange, onSortingChange, onRowClick, }: DataTableProps<TData>): import("react/jsx-runtime").JSX.Element;
+declare namespace DataTable {
+    var displayName: string;
+}
+export { DataTable };

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

@@ -0,0 +1,44 @@
+import { Locale } from 'date-fns';
+/**
+ * Props for the DatePicker component
+ */
+export interface DatePickerProps {
+    /** 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;
+    /** Placeholder text for the input */
+    placeholderText?: string;
+    /** Locale for date formatting and translations */
+    locale?: Locale;
+    /** Minimum selectable date */
+    minDate?: Date;
+    /** Maximum selectable date */
+    maxDate?: Date;
+    /** Custom date format string */
+    dateFormat?: string;
+    /** Callback fired when the input loses focus */
+    onBlur?: () => void;
+    /** Whether the input is disabled */
+    isDisabled?: boolean;
+}
+/**
+ * A reusable date picker component with floating label and range selection support
+ *
+ * @example
+ * ```tsx
+ * <DatePicker
+ *   label="Birthdate"
+ *   value={date}
+ *   onChange={setDate}
+ * />
+ * ```
+ */
+declare const DatePicker: import('react').ForwardRefExoticComponent<DatePickerProps & import('react').RefAttributes<HTMLInputElement>>;
+export { DatePicker };

package/dist/components/field-wrapper/field-wrapper.d.ts

@@ -0,0 +1,50 @@
+import { ReactNode } from 'react';
+interface FieldContextType {
+    /** Whether the field is invalid */
+    isInvalid?: boolean;
+    /** Whether the field is required */
+    isRequired?: boolean;
+    /** Whether the field is disabled */
+    isDisabled?: boolean;
+}
+export interface FieldWrapperProps {
+    /** The field label */
+    label?: string;
+    /** The error message to display */
+    errorMessage?: string;
+    /** Whether the field is invalid */
+    isInvalid?: boolean;
+    /** Whether the field is required */
+    isRequired?: boolean;
+    /** Whether the field is disabled */
+    isDisabled?: boolean;
+    /** Helper text to display below the field */
+    helperText?: string;
+    /** The field content (input, select, etc.) */
+    children: ReactNode;
+    /** Additional props for the field root */
+    fieldRootProps?: Record<string, any>;
+    /** Additional props for the field container */
+    containerProps?: Record<string, any>;
+}
+/**
+ * FieldWrapper component - A wrapper for form fields with label, error message, and context
+ *
+ * @example
+ * ```tsx
+ * <FieldWrapper
+ *   label="Email"
+ *   errorMessage="Please enter a valid email"
+ *   isInvalid={hasError}
+ *   isRequired
+ * >
+ *   <Input type="email" />
+ * </FieldWrapper>
+ * ```
+ */
+declare const FieldWrapper: import('react').ForwardRefExoticComponent<FieldWrapperProps & import('react').RefAttributes<HTMLDivElement>>;
+/**
+ * Hook to access the field context
+ */
+declare const useField: () => FieldContextType;
+export { FieldWrapper, useField };

package/dist/components/index.d.ts

@@ -0,0 +1,15 @@
+export * from './actions-button/actions-button';
+export * from './data-list/datalist';
+export * from './data-table/data-table';
+export * from './date-picker/date-picker';
+export * from './field-wrapper/field-wrapper';
+export * from './input-mask/input-mask';
+export * from './input-phone/input-phone';
+export * from './input/input';
+export * from './loader/loader';
+export * from './logos/logoPaygreenByLemonway';
+export * from './modal/modal';
+export * from './pagination/pagination';
+export * from './select/select';
+export * from './sidebar/sidebar';
+export * from './ui/color-mode';

package/dist/components/input/input.d.ts

@@ -0,0 +1,24 @@
+import { InputProps as ChakraInputProps } from '@chakra-ui/react';
+/**
+ * Props for the Input component
+ */
+export interface InputProps extends ChakraInputProps {
+    /** Label text displayed above the input */
+    label?: string;
+    /** Whether the input is disabled */
+    isDisabled?: boolean;
+}
+/**
+ * A reusable input component that extends Chakra UI's Input with floating label and field validation
+ *
+ * @example
+ * ```tsx
+ * <Input
+ *   label="Email"
+ *   placeholder="Enter your email"
+ *   isRequired
+ * />
+ * ```
+ */
+declare const Input: import('react').ForwardRefExoticComponent<InputProps & import('react').RefAttributes<HTMLInputElement>>;
+export { Input };

package/dist/components/input-mask/input-mask.d.ts

@@ -0,0 +1,27 @@
+import { InputProps } from '../input/input';
+/**
+ * Props for the InputMask component
+ */
+export interface InputMaskProps extends Omit<InputProps, 'onChange'> {
+    /** The mask pattern to apply to the input */
+    mask: string | string[];
+    /** Additional options for the mask behavior */
+    maskOptions?: any;
+    /** Callback fired when the input value changes */
+    onChange?: (e: React.ChangeEvent<HTMLInputElement>) => void;
+}
+/**
+ * A reusable input component that extends the base Input with mask functionality
+ *
+ * @example
+ * ```tsx
+ * <InputMask
+ *   label="Phone"
+ *   mask="(999) 999-9999"
+ *   placeholder="(555) 555-5555"
+ *   isRequired
+ * />
+ * ```
+ */
+declare const InputMask: import('react').ForwardRefExoticComponent<InputMaskProps & import('react').RefAttributes<HTMLInputElement>>;
+export { InputMask };

package/dist/components/input-phone/input-phone.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Props for the InputPhone component
+ */
+export interface InputPhoneProps {
+    /** The locale to use for translations ('fr' or 'en') */
+    locale?: 'fr' | 'en';
+    /** The phone number value in E.164 format */
+    value?: string;
+    /** The label to display above the input */
+    label?: string;
+    /** Placeholder text for the input */
+    placeholder?: string;
+    /** Whether the input is disabled */
+    isDisabled?: boolean;
+    /** Additional props to pass to the input element */
+    inputProps?: Record<string, unknown>;
+    /** Callback fired when the phone number changes */
+    onChange?: (value: string) => void;
+    /** Whether the input is required */
+    isRequired?: boolean;
+    /** Whether the input is invalid */
+    isInvalid?: boolean;
+    /** Error message to display when invalid */
+    errorMessage?: string;
+    /** Custom labels for the country search component */
+    searchLabels?: {
+        /** Placeholder text for the search input */
+        search?: string;
+        /** Text shown when no results are found */
+        noResults?: string;
+        /** Text shown while loading */
+        loading?: string;
+    };
+}
+/**
+ * Validates if a phone number is valid
+ */
+declare const isValidPhone: (val: string) => boolean;
+/**
+ * Formats a phone number to international format
+ */
+declare const formatPhoneIntl: (val: string) => string;
+/**
+ * A reusable phone input component with international formatting and country selection
+ *
+ * Note: This component does NOT use forwardRef intentionally, as react-phone-number-input
+ * manages its own ref system for proper focus management and country selection.
+ *
+ * @example
+ * ```tsx
+ * <InputPhone
+ *   value="+33612345678"
+ *   onChange={setPhoneNumber}
+ *   isRequired
+ * />
+ * ```
+ */
+declare const InputPhone: {
+    ({ locale, label, value, placeholder, isDisabled, inputProps, onChange, isRequired, isInvalid, errorMessage, searchLabels, ...props }: InputPhoneProps): import("react/jsx-runtime").JSX.Element;
+    displayName: string;
+};
+export { formatPhoneIntl, InputPhone, isValidPhone };