@dragunio/fe-libs 0.1.8 → 0.1.9

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import * as react from 'react';
-import { ButtonHTMLAttributes, ReactNode, HTMLAttributes, MouseEvent, KeyboardEvent, TableHTMLAttributes, InputHTMLAttributes, TextareaHTMLAttributes, KeyboardEventHandler, ChangeEvent, ReactElement } from 'react';
-export { ChevronDownIcon, ChevronUpIcon, CloseIcon, IconProps, MoreHorizontalIcon, MoreVerticalIcon, PlusIcon, SearchIcon, arrow_left, check_square_fill, chevron_down, chevron_left, chevron_right, chevron_up, copy, key, lock, lock_unlocked, log_out, minus_square, plus, plus_square, search, trash, x_close } from './icons.js';
+import { ButtonHTMLAttributes, ReactNode, HTMLAttributes, MouseEvent, KeyboardEvent, TableHTMLAttributes, InputHTMLAttributes, RefObject, TextareaHTMLAttributes, KeyboardEventHandler, ChangeEvent, ReactElement } from 'react';
+export { ChevronDownIcon, ChevronUpIcon, CloseIcon, EyeIcon, EyeOffIcon, IconProps, MailboxIcon, MoreHorizontalIcon, MoreVerticalIcon, PhoneIcon, PlusIcon, SearchIcon, arrow_left, check_square_fill, chevron_down, chevron_left, chevron_right, chevron_up, copy, key, lock, lock_unlocked, log_out, minus_square, plus, plus_square, search, trash, x_close } from './icons.js';
 
 type ButtonHierarchy = 'primary' | 'secondary-gray' | 'secondary-color' | 'tertiary-gray' | 'tertiary-color';
 type ButtonSize = '24' | '32' | '40';
@@ -183,22 +183,39 @@ declare const Toggle: react.ForwardRefExoticComponent<Omit<InputHTMLAttributes<H
     labelPosition?: "top" | "right";
 } & react.RefAttributes<HTMLInputElement>>;
 
+type DrawerSide = 'left' | 'right' | 'top' | 'bottom';
+/** Named width presets for left and right drawers. */
+declare const DrawerWidths: {
+    readonly small: 360;
+    readonly medium: 400;
+    readonly large: 480;
+};
+type DrawerWidthPreset = (typeof DrawerWidths)[keyof typeof DrawerWidths];
+type DrawerWidth = DrawerWidthPreset | number | string;
 type DrawerProps = Omit<HTMLAttributes<HTMLElement>, 'title'> & {
     open: boolean;
     onClose: () => void;
     title?: ReactNode;
+    description?: ReactNode;
     /** Optional content pinned below the scrollable body. */
     footer?: ReactNode;
-    side?: 'left' | 'right' | 'top' | 'bottom';
-    /** Width of a left/right drawer. Defaults to 400px. */
-    width?: number | string;
+    side?: DrawerSide;
+    /** Width of a left/right drawer. Use DrawerWidths presets or any CSS width. Defaults to DrawerWidths.medium (400px). */
+    width?: DrawerWidth;
     /** Makes the panel fill the entire viewport while retaining the chosen entrance direction. */
     fullScreen?: boolean;
     children?: ReactNode;
     closeOnBackdropClick?: boolean;
+    /** Allows Escape to request closing the drawer. Defaults to true. */
+    closeOnEscape?: boolean;
+    closeLabel?: string;
+    /** Element that receives focus when the drawer opens. The dialog itself is focused by default. */
+    initialFocusRef?: RefObject<HTMLElement | null>;
+    /** Restores focus to the opener after closing. Defaults to true. */
+    restoreFocus?: boolean;
 };
 /** 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;
+declare function Drawer({ open, onClose, title, description, footer, side, width, fullScreen, children, closeOnBackdropClick, closeOnEscape, closeLabel, initialFocusRef, restoreFocus, className, style, 'aria-label': ariaLabel, 'aria-describedby': ariaDescribedBy, ...props }: DrawerProps): react.ReactPortal | null;
 
 type FieldError = boolean | ReactNode;
 type DescriptionDisplay = 'inline' | 'tooltip';
@@ -251,6 +268,63 @@ type TextInputProps = Omit<InputHTMLAttributes<HTMLInputElement>, 'size' | 'valu
     Suffix?: ReactNode;
 };
 
+/**
+ * Return a message (or `false`) to mark a value invalid. Return `undefined`,
+ * `null`, or `true` when the value is valid.
+ */
+type InputValidator = (value: string) => string | boolean | null | undefined;
+type ValidationTiming = 'blur' | 'change';
+/** Shared public props for inputs with built-in format validation. */
+type ValidatedTextInputProps = Omit<TextInputProps, 'type' | 'prefix' | 'suffix' | 'Prefix' | 'Suffix'> & {
+    /**
+     * Extra validation run after the built-in format check. Return an error
+     * message (or `false`) when invalid.
+     */
+    validate?: InputValidator;
+    /** When validation runs. It runs on blur by default. */
+    validateOn?: ValidationTiming;
+};
+
+declare function validateEmail(value: string, required?: boolean): string | undefined;
+declare function validatePassword(value: string, required?: boolean): string | undefined;
+declare function validatePhoneNumber(value: string, required?: boolean): string | undefined;
+declare function normalizePhoneNumber(value: string): string;
+
+/** An email field with a mailbox prefix and built-in format validation. */
+declare const EmailInput: react.ForwardRefExoticComponent<Omit<TextInputProps, "prefix" | "type" | "suffix" | "Prefix" | "Suffix"> & {
+    validate?: InputValidator;
+    validateOn?: ValidationTiming;
+} & react.RefAttributes<HTMLInputElement>>;
+
+type EmailInputProps = ValidatedTextInputProps;
+
+/** A password field with reveal/hide control and built-in strength validation. */
+declare const PasswordInput: react.ForwardRefExoticComponent<Omit<TextInputProps, "prefix" | "type" | "suffix" | "Prefix" | "Suffix"> & {
+    validate?: InputValidator;
+    validateOn?: ValidationTiming;
+} & {
+    showPasswordLabel?: string;
+    hidePasswordLabel?: string;
+} & react.RefAttributes<HTMLInputElement>>;
+
+type PasswordInputProps = ValidatedTextInputProps & {
+    /** Accessible label for the control that reveals the password. */
+    showPasswordLabel?: string;
+    /** Accessible label for the control that hides the password. */
+    hidePasswordLabel?: string;
+};
+
+/**
+ * A phone field that accepts digits, spaces, parentheses, and plus signs,
+ * with built-in digit-count validation.
+ */
+declare const PhoneNumberInput: react.ForwardRefExoticComponent<Omit<TextInputProps, "prefix" | "type" | "suffix" | "Prefix" | "Suffix"> & {
+    validate?: InputValidator;
+    validateOn?: ValidationTiming;
+} & react.RefAttributes<HTMLInputElement>>;
+
+type PhoneNumberInputProps = ValidatedTextInputProps;
+
 /** A multi-line text field with helper/error text and a Button-powered clear action. */
 declare const TextArea: react.ForwardRefExoticComponent<Omit<react.TextareaHTMLAttributes<HTMLTextAreaElement>, "value" | "defaultValue"> & FieldBaseProps & {
     clearable?: boolean;
@@ -571,11 +645,17 @@ type ModalProps = Omit<HTMLAttributes<HTMLDivElement>, 'title'> & {
     actions?: ModalAction[];
     size?: ModalSize;
     closeOnBackdropClick?: boolean;
+    /** Allows Escape to request closing the modal. Defaults to true. */
+    closeOnEscape?: boolean;
     closeButton?: boolean;
     closeLabel?: string;
+    /** Element that receives focus when the modal opens. The dialog itself is focused by default. */
+    initialFocusRef?: RefObject<HTMLElement | null>;
+    /** Restores focus to the opener after closing. Defaults to true. */
+    restoreFocus?: boolean;
 };
 /** 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;
+declare function Modal({ open, onClose, title, description, children, footer, actions, size, closeOnBackdropClick, closeOnEscape, closeButton, closeLabel, initialFocusRef, restoreFocus, className, 'aria-label': ariaLabel, 'aria-describedby': ariaDescribedBy, ...props }: ModalProps): react.ReactPortal | null;
 
 type ProgressBarSize = 'small' | 'medium' | 'large';
 type ProgressBarProps = HTMLAttributes<HTMLDivElement> & {
@@ -718,4 +798,143 @@ declare function Avatar({ src, content, alt, size, shape, fallbackIndex, classNa
  */
 declare function AvatarGroup({ children, maxCount, className, style, role, ...props }: AvatarGroupProps): react.JSX.Element;
 
-export { Avatar, AvatarGroup, type AvatarGroupProps, type AvatarProps, type AvatarShape, type AvatarSize, Button, ButtonBar, type ButtonBarAction, type ButtonBarItem, type ButtonBarProps, type ButtonColor, type ButtonHierarchy, type ButtonProps, type ButtonSize, type ButtonVariant, Checkbox, type CheckboxProps, Chip, type ChipProps, type ChipStatus, type ChipVariant, type ColumnResizeHandler, type ControlLabelPosition, type Currency, CurrencyInput, type CurrencyInputProps, type DateRange, DateTimePicker, type DateTimePickerProps, type DateTimePickerRangeProps, type DateTimePickerSingleProps, type DescriptionDisplay, Drawer, type DrawerProps, ExpandableSection, type ExpandableSectionProps, type FieldError, 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, ProgressBar, type ProgressBarProps, type ProgressBarSize, RadioButton, type RadioButtonProps, RadioGroup, type RadioGroupOption, type RadioGroupProps, type RadioValue, 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, type TabChangeEvent, type TabItem, Table, TableBody, TableCaption, TableCell, type TableData, TableHead, TableHeader, type TablePaginationPosition, type TableProps, TableRow, Tabs, type TabsProps, type TabsScrollButtons, type TabsVariant, TextArea, type TextAreaProps, TextInput, type TextInputProps, Toggle, type ToggleProps, Tooltip, type TooltipProps, formatNumber, getIconSize, message };
+type FileUploadRejectionCode = 'accept' | 'max-files' | 'max-size' | 'duplicate';
+type FileUploadRejection = {
+    file: File;
+    code: FileUploadRejectionCode;
+    message: string;
+};
+/**
+ * Predefined file groups that FileUpload maps to native accept patterns and
+ * validates locally. Use `all` to leave the file picker unrestricted.
+ */
+declare const FILE_UPLOAD_ACCEPTS: {
+    readonly all: readonly [];
+    readonly image: readonly ["image/*", ".avif", ".bmp", ".gif", ".heic", ".heif", ".ico", ".jpeg", ".jpg", ".png", ".svg", ".tif", ".tiff", ".webp"];
+    readonly pdf: readonly [".pdf"];
+    readonly word: readonly [".doc", ".docm", ".docx", ".dot", ".dotx", ".odt", ".rtf"];
+    readonly spreadsheet: readonly [".csv", ".ods", ".xls", ".xlsb", ".xlsm", ".xlsx"];
+    readonly presentation: readonly [".odp", ".pot", ".potx", ".pps", ".ppsx", ".ppt", ".pptx"];
+    readonly document: readonly [".pdf", ".doc", ".docm", ".docx", ".dot", ".dotx", ".odt", ".rtf", ".csv", ".xls", ".xlsb", ".xlsx", ".xlsm", ".ods", ".pot", ".potx", ".pps", ".ppsx", ".ppt", ".pptx", ".odp"];
+    readonly text: readonly [".log", ".md", ".rtf", ".text", ".txt"];
+    readonly csv: readonly [".csv"];
+    readonly json: readonly [".json"];
+    readonly xml: readonly [".xml"];
+    readonly code: readonly [".c", ".cpp", ".cs", ".css", ".go", ".html", ".java", ".js", ".jsx", ".php", ".py", ".rb", ".rs", ".scss", ".sh", ".sql", ".swift", ".ts", ".tsx", ".vue", ".yml", ".yaml"];
+    readonly archive: readonly [".7z", ".bz2", ".gz", ".rar", ".tar", ".tgz", ".xz", ".zip"];
+    readonly audio: readonly ["audio/*", ".aac", ".aiff", ".flac", ".m4a", ".mp3", ".ogg", ".opus", ".wav", ".wma"];
+    readonly video: readonly ["video/*", ".avi", ".mkv", ".mov", ".mp4", ".mpeg", ".mpg", ".webm", ".wmv"];
+    readonly font: readonly [".ttf", ".otf", ".woff", ".woff2"];
+    readonly email: readonly [".eml", ".msg"];
+};
+/** A predefined FileUpload group name. */
+type FileUploadFileType = keyof typeof FILE_UPLOAD_ACCEPTS;
+/** One or more predefined FileUpload file groups. */
+type FileUploadAccept = FileUploadFileType | readonly FileUploadFileType[];
+type FileUploadProps = Omit<HTMLAttributes<HTMLDivElement>, 'children' | 'onChange'> & {
+    /** Controlled files currently shown by the component. */
+    value?: readonly File[];
+    /** Initial files for uncontrolled use. */
+    defaultValue?: readonly File[];
+    /** Called synchronously whenever the accepted file list changes. */
+    onChange?: (files: File[]) => void;
+    /** Called with only the files accepted during one selection or drop. */
+    onAccept?: (files: File[]) => void;
+    /** Called with validation failures; no upload or API request is made. */
+    onReject?: (rejections: FileUploadRejection[]) => void;
+    /** Called before a file is removed from the list. */
+    onRemove?: (file: File, index: number) => void;
+    /** Predefined file group(s) used to select and validate files. */
+    accept?: FileUploadAccept;
+    /** Maximum bytes allowed for one file. Defaults to no limit. */
+    maxSize?: number;
+    /** Maximum files in the list. Defaults to no limit. */
+    maxFiles?: number;
+    multiple?: boolean;
+    disabled?: boolean;
+    /** Rejects files with the same name, size, and last-modified timestamp. */
+    preventDuplicate?: boolean;
+    label?: ReactNode;
+    description?: ReactNode;
+    dropLabel?: ReactNode;
+    browseLabel?: ReactNode;
+    removeLabel?: (file: File) => string;
+    /** Shows local image previews and file metadata below the drop zone. */
+    showFileList?: boolean;
+    inputProps?: Omit<InputHTMLAttributes<HTMLInputElement>, 'accept' | 'disabled' | 'multiple' | 'onChange' | 'type' | 'value'>;
+};
+declare function formatFileSize(bytes: number): string;
+/**
+ * A local file picker and drop zone. It validates and emits browser File
+ * objects only; callers own all persistence, uploads, progress, and API work.
+ */
+declare const FileUpload: react.ForwardRefExoticComponent<Omit<HTMLAttributes<HTMLDivElement>, "children" | "onChange"> & {
+    /** Controlled files currently shown by the component. */
+    value?: readonly File[];
+    /** Initial files for uncontrolled use. */
+    defaultValue?: readonly File[];
+    /** Called synchronously whenever the accepted file list changes. */
+    onChange?: (files: File[]) => void;
+    /** Called with only the files accepted during one selection or drop. */
+    onAccept?: (files: File[]) => void;
+    /** Called with validation failures; no upload or API request is made. */
+    onReject?: (rejections: FileUploadRejection[]) => void;
+    /** Called before a file is removed from the list. */
+    onRemove?: (file: File, index: number) => void;
+    /** Predefined file group(s) used to select and validate files. */
+    accept?: FileUploadAccept;
+    /** Maximum bytes allowed for one file. Defaults to no limit. */
+    maxSize?: number;
+    /** Maximum files in the list. Defaults to no limit. */
+    maxFiles?: number;
+    multiple?: boolean;
+    disabled?: boolean;
+    /** Rejects files with the same name, size, and last-modified timestamp. */
+    preventDuplicate?: boolean;
+    label?: ReactNode;
+    description?: ReactNode;
+    dropLabel?: ReactNode;
+    browseLabel?: ReactNode;
+    removeLabel?: (file: File) => string;
+    /** Shows local image previews and file metadata below the drop zone. */
+    showFileList?: boolean;
+    inputProps?: Omit<InputHTMLAttributes<HTMLInputElement>, "accept" | "disabled" | "multiple" | "onChange" | "type" | "value">;
+} & react.RefAttributes<HTMLInputElement>>;
+
+type FilePreviewKind = 'audio' | 'image' | 'pdf' | 'unsupported' | 'video';
+type FilePreviewCloseReason = 'backdrop' | 'close' | 'escape';
+type FilePreviewActionHandler = (file: File, index: number) => void;
+type FilePreviewProps = Omit<HTMLAttributes<HTMLDivElement>, 'children' | 'onChange' | 'onClose'> & {
+    open: boolean;
+    files: readonly File[];
+    /** Controlled zero-based index of the file currently shown. */
+    activeIndex?: number;
+    /** Initial zero-based file index for uncontrolled use. */
+    defaultActiveIndex?: number;
+    /** Called after a previous/next control or Arrow key changes the active file. */
+    onActiveIndexChange?: (index: number, file: File) => void;
+    /** Called when the preview requests closing, including the reason. */
+    onClose: (reason: FilePreviewCloseReason) => void;
+    /** Called immediately before `onClose('escape')`. */
+    onEscape?: () => void;
+    /** Called when the Delete action is pressed. The owner removes files. */
+    onDelete?: FilePreviewActionHandler;
+    /** Called when the Download action is pressed, before the local browser download starts. */
+    onDownload?: FilePreviewActionHandler;
+    closeOnBackdropClick?: boolean;
+    closeOnEscape?: boolean;
+    closeLabel?: string;
+    downloadLabel?: ReactNode;
+    deleteLabel?: ReactNode;
+    /** Hides the local browser Download action. Defaults to false. */
+    hideDownload?: boolean;
+};
+/** Identifies browser-native previews supported by FilePreview. */
+declare function getFilePreviewKind(file: File): FilePreviewKind;
+/**
+ * A local File viewer with click and keyboard navigation. It makes no network
+ * request: deletion and download notifications always carry the active File.
+ */
+declare function FilePreview({ open, files, activeIndex, defaultActiveIndex, onActiveIndexChange, onClose, onEscape, onDelete, onDownload, closeOnBackdropClick, closeOnEscape, closeLabel, downloadLabel, deleteLabel, hideDownload, className, 'aria-label': ariaLabel, ...props }: FilePreviewProps): react.ReactPortal | null;
+
+export { Avatar, AvatarGroup, type AvatarGroupProps, type AvatarProps, type AvatarShape, type AvatarSize, Button, ButtonBar, type ButtonBarAction, type ButtonBarItem, type ButtonBarProps, type ButtonColor, type ButtonHierarchy, type ButtonProps, type ButtonSize, type ButtonVariant, Checkbox, type CheckboxProps, Chip, type ChipProps, type ChipStatus, type ChipVariant, type ColumnResizeHandler, type ControlLabelPosition, type Currency, CurrencyInput, type CurrencyInputProps, type DateRange, DateTimePicker, type DateTimePickerProps, type DateTimePickerRangeProps, type DateTimePickerSingleProps, type DescriptionDisplay, Drawer, type DrawerProps, type DrawerSide, type DrawerWidth, type DrawerWidthPreset, DrawerWidths, EmailInput, type EmailInputProps, ExpandableSection, type ExpandableSectionProps, FILE_UPLOAD_ACCEPTS, type FieldError, FilePreview, type FilePreviewActionHandler, type FilePreviewCloseReason, type FilePreviewKind, type FilePreviewProps, FileUpload, type FileUploadAccept, type FileUploadFileType, type FileUploadProps, type FileUploadRejection, type FileUploadRejectionCode, type InputValidator, 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, PasswordInput, type PasswordInputProps, PhoneNumberInput, type PhoneNumberInputProps, ProgressBar, type ProgressBarProps, type ProgressBarSize, RadioButton, type RadioButtonProps, RadioGroup, type RadioGroupOption, type RadioGroupProps, type RadioValue, 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, type TabChangeEvent, type TabItem, Table, TableBody, TableCaption, TableCell, type TableData, TableHead, TableHeader, type TablePaginationPosition, type TableProps, TableRow, Tabs, type TabsProps, type TabsScrollButtons, type TabsVariant, TextArea, type TextAreaProps, TextInput, type TextInputProps, Toggle, type ToggleProps, Tooltip, type TooltipProps, type ValidatedTextInputProps, type ValidationTiming, formatFileSize, formatNumber, getFilePreviewKind, getIconSize, message, normalizePhoneNumber, validateEmail, validatePassword, validatePhoneNumber };