@dragunio/fe-libs 0.1.2 → 0.1.3

package/README.md

@@ -14,7 +14,12 @@ packages/            # Internal component source folders
 ├── drawer/
 ├── form-controls/
 ├── tooltip/
-└── expandable-section/
+├── expandable-section/
+├── loading/
+├── skeleton/
+├── modal/
+├── progress/
+└── chip/
 apps/playground/     # Local component storybook
 ```
 
@@ -34,21 +39,30 @@ The playground resolves package names directly to `packages/*/src`, so component
 pnpm dev
 ```
 
-Open the URL printed by Vite, usually `http://127.0.0.1:5173`.
+Open the URL printed by Vite, usually `http://127.0.0.1:3000`.
 
 Available review routes:
 
-- `http://127.0.0.1:5173/#/` — overview
-- `http://127.0.0.1:5173/#/icons` — SVG Icons
-- `http://127.0.0.1:5173/#/button` — Button
-- `http://127.0.0.1:5173/#/table` — Table
-- `http://127.0.0.1:5173/#/drawer` — Drawer
-- `http://127.0.0.1:5173/#/selection` — Selection
-- `http://127.0.0.1:5173/#/datetime` — DateTimePicker
-- `http://127.0.0.1:5173/#/currency` — CurrencyInput
-- `http://127.0.0.1:5173/#/number` — NumberInput
-- `http://127.0.0.1:5173/#/tooltip` — Tooltip
-- `http://127.0.0.1:5173/#/expandable` — ExpandableSection
+- `http://127.0.0.1:3000/#/` — overview
+- `http://127.0.0.1:3000/#/icons` — SVG Icons
+- `http://127.0.0.1:3000/#/button` — Button
+- `http://127.0.0.1:3000/#/table` — Table
+- `http://127.0.0.1:3000/#/drawer` — Drawer
+- `http://127.0.0.1:3000/#/selection` — Selection
+- `http://127.0.0.1:3000/#/datetime` — DateTimePicker
+- `http://127.0.0.1:3000/#/currency` — CurrencyInput
+- `http://127.0.0.1:3000/#/number` — NumberInput
+- `http://127.0.0.1:3000/#/tooltip` — Tooltip
+- `http://127.0.0.1:3000/#/expandable` — ExpandableSection
+- `http://127.0.0.1:3000/#/loading` — Loading
+- `http://127.0.0.1:3000/#/skeleton` — Skeleton
+- `http://127.0.0.1:3000/#/modal` — Modal
+- `http://127.0.0.1:3000/#/progress` — ProgressBar
+- `http://127.0.0.1:3000/#/chip` — Chip
+- `http://127.0.0.1:3000/#/text-input` — TextInput & TextArea
+- `http://127.0.0.1:3000/#/pagination` — Pagination
+- `http://127.0.0.1:3000/#/message` — Message
+- `http://127.0.0.1:3000/#/snackbar` — Snackbar
 
 To test the playground against generated package output instead of source aliases:
 
@@ -108,6 +122,8 @@ const [columnSizes, setColumnSizes] = useState<number[]>();
 
 Use `minColumnWidth` to change the minimum resize limit. The header resize handles support pointer dragging and left/right arrow keys.
 
+Set `pageSize` to paginate a data-driven table (it enables pagination automatically), or use `pagination` with the default page size of 10. `page`, `defaultPage`, and `onPageChange` support controlled or uncontrolled state; `paginationPosition` accepts `top-right`, `bottom-right`, and `bottom-center`.
+
 The library exposes ESM, CommonJS, TypeScript declarations, and keeps React as a peer dependency.
 
 ### New form and overlay primitives
@@ -115,6 +131,27 @@ The library exposes ESM, CommonJS, TypeScript declarations, and keeps React as a
 - `Drawer` is a portal-based modal panel with `left`, `right`, `top`, and `bottom` slide-in animations. Use `fullScreen` for a full-viewport panel and `footer` for fixed actions below the scrollable body.
 - `Selection` is a rounded custom dropdown inspired by DropdownCustom, with single/multiple modes, optional search, clear action, tags, form-field values, and keyboard navigation.
 - `DateTimePicker` supports `mode="single"` and `mode="range"`; its default format is `dd/MM/yyyy HH:mm`.
-- `NumberInput` and `CurrencyInput` format values immediately while typing (`1000` → `1,000`) and keep up to two fractional digits by default. Use `allowDecimal`, `decimals`, `min`, and `max` to control decimal input and numeric limits. `CurrencyInput` adds a `VND` suffix by default, or a currency dropdown through `currencies`.
+- `NumberInput` and `CurrencyInput` format values immediately while typing (`1000` → `1,000`) and keep up to two fractional digits by default. Use `allowDecimal`, `decimals`, `min`, and `max` to control decimal input and numeric limits. Both support `error` and `errorMessage` with the same red border/message treatment as `TextInput`. `CurrencyInput` adds a `VND` suffix by default, or a currency dropdown through `currencies`.
 - `Tooltip` shows accessible content on hover and focus.
 - `ExpandableSection` provides controlled and uncontrolled expand/collapse behavior.
+- `TextInput` and `TextArea` support `error`/`errorMessage`, `helperText`, `clearable`, `onClear`, and `onValueChange`. Passing a string to `error` shows it below the field and applies the error border.
+- `Modal` is a centered portal dialog in `small`, `medium`, `large`, `xlarge`, and `full` sizes. Its close control and `actions` are library `Button` instances.
+- `Loading` provides `small`, `medium`, and `large` circular indicators (or a custom pixel `size`); use `Skeleton.Circle` and `Skeleton.Square` with `size`, or `Skeleton.Box` and `Skeleton.Line` with `width` and `height`.
+- `ProgressBar` is determinate when `value` is supplied and renders an indeterminate back-and-forth animation when it is omitted.
+- `Chip` supports the standard `default`, `success`, `error`, `info`, and `warning` palettes, plus `color` for any CSS color and `subtle`, `solid`, or `outline` variants.
+- `Pagination` supports controlled (`page`) and uncontrolled (`defaultPage`) navigation, compact ellipses, and accessible previous/next controls.
+- Mount `Message` once near the app root and trigger top-right alert notifications with `Message.success`, `Message.info`, `Message.warning`, or `Message.error`. `Snackbar` is a controlled temporary notification with actions, auto-hide, and configurable placement.
+
+```tsx
+<TextInput
+  label="Email"
+  value={email}
+  onValueChange={setEmail}
+  errorMessage={emailError}
+  clearable
+/>
+
+<ProgressBar label="Upload" value={72} />
+<ProgressBar label="Synchronising" />
+<Chip status="success" dot>Complete</Chip>
+```

package/dist/index.d.mts

@@ -1,5 +1,5 @@
 import * as react from 'react';
-import { ButtonHTMLAttributes, ReactNode, SVGProps, TableHTMLAttributes, HTMLAttributes, InputHTMLAttributes, KeyboardEventHandler, ReactElement } from 'react';
+import { ButtonHTMLAttributes, ReactNode, SVGProps, TableHTMLAttributes, HTMLAttributes, InputHTMLAttributes, KeyboardEventHandler, TextareaHTMLAttributes, ReactElement } from 'react';
 
 type ButtonHierarchy = 'primary' | 'secondary-gray' | 'secondary-color' | 'tertiary-gray' | 'tertiary-color';
 type ButtonSize = '24' | '32' | '40';
@@ -53,6 +53,7 @@ declare function SearchIcon(props: IconProps): react.JSX.Element;
 
 type TableData = readonly (readonly ReactNode[])[];
 type ColumnResizeHandler = (columnSizes: number[], columnIndex: number) => void;
+type TablePaginationPosition = 'top-right' | 'bottom-right' | 'bottom-center' | 'middle-bottom';
 type TableProps = TableHTMLAttributes<HTMLTableElement> & {
     /** Enables alternating background colors for body rows. */
     striped?: boolean;
@@ -68,12 +69,24 @@ type TableProps = TableHTMLAttributes<HTMLTableElement> & {
     onColumnResize?: ColumnResizeHandler;
     /** Smallest width, in pixels, that a user can resize a column to. */
     minColumnWidth?: number;
+    /** Shows the built-in Pagination for data-driven tables. Enabled by pageSize as well. */
+    pagination?: boolean;
+    /** Number of data rows shown on each page. Defaults to 10 when pagination is enabled. */
+    pageSize?: number;
+    /** Controlled one-based page number. */
+    page?: number;
+    /** Initial page number for uncontrolled pagination. */
+    defaultPage?: number;
+    /** Called with the newly selected one-based page number. */
+    onPageChange?: (page: number) => void;
+    /** Location of the built-in Pagination. Defaults to bottom-right. */
+    paginationPosition?: TablePaginationPosition;
 };
 /**
  * A semantic table. Use its child primitives for custom markup, or pass headers
  * and data for an automatically sized, striped and resizable table.
  */
-declare function Table({ headers, data, striped, children, ...props }: TableProps): react.JSX.Element;
+declare function Table({ headers, data, striped, children, pagination, pageSize, page, defaultPage, onPageChange, paginationPosition, ...props }: TableProps): react.JSX.Element;
 declare function TableHead(props: HTMLAttributes<HTMLTableSectionElement>): react.JSX.Element;
 declare function TableBody(props: HTMLAttributes<HTMLTableSectionElement>): react.JSX.Element;
 declare function TableRow({ children, ...props }: HTMLAttributes<HTMLTableRowElement>): react.JSX.Element;
@@ -111,6 +124,36 @@ type DrawerProps = Omit<HTMLAttributes<HTMLElement>, 'title'> & {
 /** A modal panel with fixed header/footer regions and a scrollable body. */
 declare function Drawer({ open, onClose, title, footer, side, width, fullScreen, children, closeOnBackdropClick, className, style, ...props }: DrawerProps): react.ReactPortal | null;
 
+type FieldError = boolean | ReactNode;
+type TextFieldBaseProps = {
+    label?: ReactNode;
+    helperText?: ReactNode;
+    /** A string/node is displayed beneath the control; `true` uses a default message. */
+    error?: FieldError;
+    errorMessage?: ReactNode;
+    clearable?: boolean;
+    onClear?: () => void;
+    onValueChange?: (value: string) => void;
+    clearLabel?: string;
+};
+type TextInputProps = Omit<InputHTMLAttributes<HTMLInputElement>, 'size' | 'value' | 'defaultValue'> & TextFieldBaseProps & {
+    value?: string;
+    defaultValue?: string;
+};
+type TextAreaProps = Omit<TextareaHTMLAttributes<HTMLTextAreaElement>, 'value' | 'defaultValue'> & TextFieldBaseProps & {
+    value?: string;
+    defaultValue?: string;
+};
+/** A text field with helper/error text and a Button-powered clear action. */
+declare const TextInput: react.ForwardRefExoticComponent<Omit<InputHTMLAttributes<HTMLInputElement>, "size" | "value" | "defaultValue"> & TextFieldBaseProps & {
+    value?: string;
+    defaultValue?: string;
+} & react.RefAttributes<HTMLInputElement>>;
+/** A multi-line text field with helper/error text and a Button-powered clear action. */
+declare const TextArea: react.ForwardRefExoticComponent<Omit<TextareaHTMLAttributes<HTMLTextAreaElement>, "value" | "defaultValue"> & TextFieldBaseProps & {
+    value?: string;
+    defaultValue?: string;
+} & react.RefAttributes<HTMLTextAreaElement>>;
 type SelectionOption = {
     label: ReactNode;
     value: string | number;
@@ -170,7 +213,9 @@ type NumberInputProps = Omit<InputHTMLAttributes<HTMLInputElement>, 'type' | 'va
     thousandSeparator?: string;
     label?: ReactNode;
     helperText?: ReactNode;
-    error?: boolean;
+    /** A string/node is displayed beneath the control; `true` uses a default message. */
+    error?: FieldError;
+    errorMessage?: ReactNode;
 };
 declare function formatNumber(value: number, decimals?: number, thousandSeparator?: string, decimalSeparator?: string): string;
 /** A text input that displays numbers as 1,000.05 by default. */
@@ -189,7 +234,9 @@ declare const NumberInput: react.ForwardRefExoticComponent<Omit<InputHTMLAttribu
     thousandSeparator?: string;
     label?: ReactNode;
     helperText?: ReactNode;
-    error?: boolean;
+    /** A string/node is displayed beneath the control; `true` uses a default message. */
+    error?: FieldError;
+    errorMessage?: ReactNode;
 } & react.RefAttributes<HTMLInputElement>>;
 type Currency = {
     code: string;
@@ -249,4 +296,186 @@ type ExpandableSectionProps = Omit<HTMLAttributes<HTMLDivElement>, 'title'> & {
 /** An outlined section that can be expanded or collapsed. */
 declare function ExpandableSection({ title, children, expanded, defaultExpanded, onExpandedChange, disabled, className, ...props }: ExpandableSectionProps): react.JSX.Element;
 
-export { Button, type ButtonColor, type ButtonHierarchy, type ButtonProps, type ButtonSize, type ButtonVariant, ChevronDownIcon, CloseIcon, type ColumnResizeHandler, type Currency, CurrencyInput, type CurrencyInputProps, type DateRange, DateTimePicker, type DateTimePickerProps, type DateTimePickerRangeProps, type DateTimePickerSingleProps, Drawer, type DrawerProps, ExpandableSection, type ExpandableSectionProps, type IconProps, NumberInput, type NumberInputProps, PlusIcon, SearchIcon, Selection, type SelectionOption, type SelectionProps, type SelectionValue, Table, TableBody, TableCaption, TableCell, type TableData, TableHead, TableHeader, type TableProps, TableRow, Toggle, type ToggleProps, Tooltip, type TooltipProps, formatNumber, getIconSize };
+type LoadingSize = 'small' | 'medium' | 'large' | number;
+type LoadingProps = HTMLAttributes<HTMLSpanElement> & {
+    /** Diameter of the spinner. Accepts presets or a pixel value. */
+    size?: LoadingSize;
+    /** Spinner color. Accepts every valid CSS color. */
+    color?: string;
+    /** Optional visible status text. */
+    label?: ReactNode;
+};
+/** An accessible circular loading indicator with three preset sizes. */
+declare function Loading({ size, color, label, className, style, ...props }: LoadingProps): react.JSX.Element;
+
+type SkeletonVariant = 'box' | 'circle' | 'line';
+type SkeletonProps = HTMLAttributes<HTMLDivElement> & {
+    /** Visual shape. `box` is the default. */
+    variant?: SkeletonVariant;
+    /** Alias for variant, useful when describing the visual shape. */
+    shape?: SkeletonVariant;
+    width?: number | string;
+    height?: number | string;
+    /** Render multiple stacked placeholders. */
+    count?: number;
+    /** Turns off the shimmer animation. */
+    animated?: boolean;
+};
+type SkeletonSizeProps = Omit<SkeletonProps, 'variant' | 'shape' | 'width' | 'height' | 'count'> & {
+    /** Diameter/edge length. A number is converted to pixels. */
+    size?: number | string;
+};
+type SkeletonBoxProps = Omit<SkeletonProps, 'variant' | 'shape' | 'count'>;
+/** A shimmer placeholder for rectangular boxes, avatars, and text lines. */
+declare function SkeletonBase({ variant, shape, width, height, count, animated, className, style, ...props }: SkeletonProps): react.JSX.Element;
+/** A circular placeholder, useful for avatars and icon buttons. */
+declare function SkeletonCircle({ size, ...props }: SkeletonSizeProps): react.JSX.Element;
+/** A square placeholder, useful for thumbnails and image previews. */
+declare function SkeletonSquare({ size, ...props }: SkeletonSizeProps): react.JSX.Element;
+/** A rectangular placeholder with explicit width and height. */
+declare function SkeletonBox({ width, height, ...props }: SkeletonBoxProps): react.JSX.Element;
+/** A text-line placeholder with explicit width and height. */
+declare function SkeletonLine({ width, height, ...props }: SkeletonBoxProps): react.JSX.Element;
+type SkeletonComponent = typeof SkeletonBase & {
+    Circle: typeof SkeletonCircle;
+    Square: typeof SkeletonSquare;
+    Box: typeof SkeletonBox;
+    Line: typeof SkeletonLine;
+};
+/**
+ * A shimmer placeholder. Use the focused helpers for new code:
+ * `Skeleton.Circle`, `Skeleton.Square`, `Skeleton.Box`, and `Skeleton.Line`.
+ */
+declare const Skeleton: SkeletonComponent;
+
+type ModalSize = 'small' | 'medium' | 'large' | 'xlarge' | 'full';
+type ModalAction = Omit<ButtonProps, 'children' | 'content'> & {
+    label: ReactNode;
+};
+type ModalProps = Omit<HTMLAttributes<HTMLDivElement>, 'title'> & {
+    open: boolean;
+    onClose: () => void;
+    title?: ReactNode;
+    description?: ReactNode;
+    children?: ReactNode;
+    /** Custom footer content, rendered before actions. */
+    footer?: ReactNode;
+    /** Actions rendered with the library Button component. */
+    actions?: ModalAction[];
+    size?: ModalSize;
+    closeOnBackdropClick?: boolean;
+    closeButton?: boolean;
+    closeLabel?: string;
+};
+/** A centered, portal-based dialog with Button-powered close and footer actions. */
+declare function Modal({ open, onClose, title, description, children, footer, actions, size, closeOnBackdropClick, closeButton, closeLabel, className, ...props }: ModalProps): react.ReactPortal | null;
+
+type ProgressBarSize = 'small' | 'medium' | 'large';
+type ProgressBarProps = HTMLAttributes<HTMLDivElement> & {
+    /** Current value. Omit it for the indeterminate, bouncing state. */
+    value?: number | null;
+    max?: number;
+    label?: ReactNode;
+    showValue?: boolean;
+    size?: ProgressBarSize;
+    color?: string;
+};
+/** A determinate percentage bar or an indeterminate bar that moves back and forth. */
+declare function ProgressBar({ value, max, label, showValue, size, color, className, style, 'aria-label': ariaLabel, ...props }: ProgressBarProps): react.JSX.Element;
+
+type ChipStatus = 'default' | 'info' | 'success' | 'warning' | 'error' | 'neutral' | 'pending' | 'processing';
+type ChipVariant = 'subtle' | 'solid' | 'outline';
+type ChipProps = HTMLAttributes<HTMLSpanElement> & {
+    children: ReactNode;
+    /** Status color palette: default, success, error, info, warning, plus neutral/pending/processing. */
+    status?: ChipStatus;
+    /** Any CSS color. Overrides the status palette. */
+    color?: string;
+    variant?: ChipVariant;
+    dot?: boolean;
+    onRemove?: () => void;
+    removeLabel?: string;
+};
+/** A compact status label with status palettes and custom CSS colors. */
+declare function Chip({ children, status, color, variant, dot, onRemove, removeLabel, className, style, ...props }: ChipProps): react.JSX.Element;
+
+type PaginationProps = Omit<HTMLAttributes<HTMLElement>, 'onChange'> & {
+    /** Current page (one-based). Provide this with onPageChange for controlled use. */
+    page?: number;
+    /** Starting page for uncontrolled use. */
+    defaultPage?: number;
+    /** Total number of pages. */
+    totalPages: number;
+    /** Called whenever the selected page changes. */
+    onPageChange?: (page: number) => void;
+    /** Number of page buttons shown around the current page. */
+    siblingCount?: number;
+    /** Number of page buttons retained at each edge. */
+    boundaryCount?: number;
+    disabled?: boolean;
+    previousLabel?: string;
+    nextLabel?: string;
+};
+/** A compact, accessible page navigator with controlled and uncontrolled APIs. */
+declare function Pagination({ page, defaultPage, totalPages, onPageChange, siblingCount, boundaryCount, disabled, previousLabel, nextLabel, className, ...props }: PaginationProps): react.JSX.Element;
+
+type MessageSeverity = 'success' | 'info' | 'warning' | 'error';
+type MessageOptions = {
+    content: ReactNode;
+    severity?: MessageSeverity;
+    title?: ReactNode;
+    /** Set to null to leave the message visible until manually dismissed. */
+    duration?: number | null;
+    action?: ReactNode;
+    onClose?: () => void;
+};
+declare function dismiss(id: number): void;
+declare function show({ duration, severity, ...options }: MessageOptions): number;
+declare const message: {
+    show: typeof show;
+    success: (content: ReactNode, options?: Omit<MessageOptions, "content" | "severity">) => number;
+    info: (content: ReactNode, options?: Omit<MessageOptions, "content" | "severity">) => number;
+    warning: (content: ReactNode, options?: Omit<MessageOptions, "content" | "severity">) => number;
+    error: (content: ReactNode, options?: Omit<MessageOptions, "content" | "severity">) => number;
+    dismiss: typeof dismiss;
+    clear: () => void;
+};
+type MessageProps = HTMLAttributes<HTMLDivElement> & {
+    /** Maximum notifications shown at the same time. */
+    maxCount?: number;
+    closeLabel?: string;
+};
+/**
+ * Notification viewport for the global `message` trigger.
+ * Mount once near the application root, then call `message.success(...)`.
+ */
+declare function Message({ maxCount, closeLabel, className, ...props }: MessageProps): react.JSX.Element;
+/** Imperative trigger aliases, available as `Message.success(...)` as well. */
+declare namespace Message {
+    const show: ({ duration, severity, ...options }: MessageOptions) => number;
+    const success: (content: ReactNode, options?: Omit<MessageOptions, "content" | "severity">) => number;
+    const info: (content: ReactNode, options?: Omit<MessageOptions, "content" | "severity">) => number;
+    const warning: (content: ReactNode, options?: Omit<MessageOptions, "content" | "severity">) => number;
+    const error: (content: ReactNode, options?: Omit<MessageOptions, "content" | "severity">) => number;
+    const dismiss: (id: number) => void;
+    const clear: () => void;
+}
+
+type SnackbarAnchorOrigin = {
+    vertical?: 'top' | 'bottom';
+    horizontal?: 'left' | 'center' | 'right';
+};
+type SnackbarProps = Omit<HTMLAttributes<HTMLDivElement>, 'onClose'> & {
+    open: boolean;
+    message: ReactNode;
+    /** Set to null to keep the snackbar open until dismissed. */
+    autoHideDuration?: number | null;
+    onClose?: (reason: 'timeout' | 'closeButton' | 'escapeKeyDown') => void;
+    action?: ReactNode;
+    anchorOrigin?: SnackbarAnchorOrigin;
+    closeLabel?: string;
+};
+/** A controlled, temporary notification surface. */
+declare function Snackbar({ open, message, autoHideDuration, onClose, action, anchorOrigin, closeLabel, className, ...props }: SnackbarProps): react.JSX.Element | null;
+
+export { Button, type ButtonColor, type ButtonHierarchy, type ButtonProps, type ButtonSize, type ButtonVariant, ChevronDownIcon, Chip, type ChipProps, type ChipStatus, type ChipVariant, CloseIcon, type ColumnResizeHandler, type Currency, CurrencyInput, type CurrencyInputProps, type DateRange, DateTimePicker, type DateTimePickerProps, type DateTimePickerRangeProps, type DateTimePickerSingleProps, Drawer, type DrawerProps, ExpandableSection, type ExpandableSectionProps, type FieldError, type IconProps, Loading, type LoadingProps, type LoadingSize, Message, type MessageOptions, type MessageProps, type MessageSeverity, Modal, type ModalAction, type ModalProps, type ModalSize, NumberInput, type NumberInputProps, Pagination, type PaginationProps, PlusIcon, ProgressBar, type ProgressBarProps, type ProgressBarSize, SearchIcon, Selection, type SelectionOption, type SelectionProps, type SelectionValue, Skeleton, SkeletonBox, type SkeletonBoxProps, SkeletonCircle, SkeletonLine, type SkeletonProps, type SkeletonSizeProps, SkeletonSquare, type SkeletonVariant, Snackbar, type SnackbarAnchorOrigin, type SnackbarProps, Table, TableBody, TableCaption, TableCell, type TableData, TableHead, TableHeader, type TablePaginationPosition, type TableProps, TableRow, TextArea, type TextAreaProps, TextInput, type TextInputProps, Toggle, type ToggleProps, Tooltip, type TooltipProps, formatNumber, getIconSize, message };