@vertesia/ui 1.2.0 → 1.4.0-dev.20260615.042549Z

package/src/core/components/Divider.tsx

@@ -1,11 +1,8 @@
-import clsx from "clsx";
-
+import clsx from 'clsx';
 
 interface DividerProps {
     className?: string;
 }
 export function Divider({ className }: DividerProps) {
-    return (
-        <hr className={clsx("w-full h-0.5 border-t-0 bg-border", className)} />
-    )
+    return <hr className={clsx('w-full h-0.5 border-t-0 bg-border', className)} />;
 }

package/src/core/components/EmptyCollection.tsx

@@ -1,6 +1,5 @@
-import { Plus } from "lucide-react";
-import { Button } from "@vertesia/ui/core";
-
+import { Plus } from 'lucide-react';
+import { Button } from './shadcn/button';
 
 interface EmptyInteractionsProps {
     buttonLabel: string;
@@ -31,11 +30,11 @@ export function EmptyCollection({ buttonLabel, title, children, onClick }: Empty
                 <p className="mt-1 text-sm text-muted">{children}</p>
                 <div className="mt-6">
                     <Button onClick={onClick}>
-                        <Plus className="-ml-0.5 mr-1.5 size-5" aria-hidden="true" />
+                        <Plus className="-ms-0.5 me-1.5 size-5" aria-hidden="true" />
                         {buttonLabel}
                     </Button>
                 </div>
             </div>
         </div>
-    )
-}
+    );
+}

package/src/core/components/FileUpload.tsx

@@ -1,4 +1,34 @@
-import { DragEventHandler, MutableRefObject, ReactNode, useRef } from "react";
+import { type DragEventHandler, type ReactNode, type RefObject, useRef } from 'react';
+
+type DragCounterElement = HTMLElement & {
+    __dragOver_cnt__?: number;
+};
+
+interface FileSystemEntry {
+    name: string;
+    isFile: boolean;
+    isDirectory: boolean;
+}
+
+interface FileSystemFileEntry extends FileSystemEntry {
+    isFile: true;
+    file(callback: (file: File) => void): void;
+}
+
+interface FileSystemDirectoryEntry extends FileSystemEntry {
+    isDirectory: true;
+    createReader(): {
+        readEntries(callback: (entries: FileSystemEntry[]) => void): void;
+    };
+}
+
+function isFileEntry(entry: FileSystemEntry): entry is FileSystemFileEntry {
+    return entry.isFile;
+}
+
+function isDirectoryEntry(entry: FileSystemEntry): entry is FileSystemDirectoryEntry {
+    return entry.isDirectory;
+}
 
 /**
  * TODO: TS complains that:
@@ -27,9 +57,9 @@ export function FileUploadInput({ children, onUpload }: FileUploadInputProps) {
         }
     };
     return (
-        <label style={{ cursor: "pointer" }}>
+        <label style={{ cursor: 'pointer' }}>
             {children}
-            <input ref={inputRef} type="file" style={{ display: "none" }} onChange={_onUpload} />
+            <input ref={inputRef} type="file" style={{ display: 'none' }} onChange={_onUpload} />
         </label>
     );
 }
@@ -78,40 +108,43 @@ export function DropZone({ onUpload }: DropZoneProps) {
     );
 }
 
-function _onDragEnter(el: any) {
-    let cnt = el.__dragOver_cnt__ || 0;
+function _onDragEnter(el: DragCounterElement | null) {
+    if (!el) return false;
+    const cnt = el.__dragOver_cnt__ || 0;
     el.__dragOver_cnt__ = cnt + 1;
     return !cnt; // true if first drag o ver false if dragover already recorded
 }
 
-function _onDragLeave(el: any) {
-    let cnt = el.__dragOver_cnt__;
+function _onDragLeave(el: DragCounterElement | null) {
+    if (!el) return false;
+    const cnt = el.__dragOver_cnt__;
     if (!cnt) return false;
     el.__dragOver_cnt__ = cnt - 1;
     return cnt === 1; // true if leave false if not
 }
 
-function _onDrop(el: any) {
+function _onDrop(el: DragCounterElement | null) {
+    if (!el) return;
     delete el.__dragOver_cnt__;
 }
 
 export interface IDropZoneOpts {
     onUpload: (files: File[]) => unknown;
     dragOverClass?: string;
-    dropEffect?: "none" | "copy" | "link" | "move";
+    dropEffect?: 'none' | 'copy' | 'link' | 'move';
 }
 export interface IDropZoneProps<T> {
     onDrop: DragEventHandler<T>;
     onDragOver: DragEventHandler<T>;
     onDragEnter: DragEventHandler<T>;
     onDragLeave: DragEventHandler<T>;
-    ref: MutableRefObject<T | null>;
+    ref: RefObject<T | null>;
 }
 
 export function useDropZone<T extends HTMLElement = HTMLDivElement>({
     onUpload,
-    dragOverClass = "is-drag-over-on",
-    dropEffect = "copy",
+    dragOverClass = 'is-drag-over-on',
+    dropEffect = 'copy',
 }: IDropZoneOpts): IDropZoneProps<T> {
     const ref = useRef<T>(null);
 
@@ -124,24 +157,24 @@ export function useDropZone<T extends HTMLElement = HTMLDivElement>({
         if (items) {
             const promises: Promise<File[]>[] = [];
 
-            const traverseFileTree = (item: any, path: string = ""): Promise<File[]> => {
+            const traverseFileTree = (item: FileSystemEntry, path: string = ''): Promise<File[]> => {
                 return new Promise((resolve) => {
-                    if (item.isFile) {
+                    if (isFileEntry(item)) {
                         item.file((file: File) => {
-                            Object.defineProperty(file, "webkitRelativePath", { value: path + file.name });
+                            Object.defineProperty(file, 'webkitRelativePath', { value: path + file.name });
                             resolve([file]);
                         });
-                    } else if (item.isDirectory) {
+                    } else if (isDirectoryEntry(item)) {
                         const dirReader = item.createReader();
                         const entries: Promise<File[]>[] = [];
 
                         const readEntries = () => {
-                            dirReader.readEntries((results: any[]) => {
+                            dirReader.readEntries((results) => {
                                 if (!results.length) {
-                                    Promise.all(entries).then((filesArrays) => resolve(filesArrays.flat()));
+                                    void Promise.all(entries).then((filesArrays) => resolve(filesArrays.flat()));
                                 } else {
                                     for (const entry of results) {
-                                        entries.push(traverseFileTree(entry, path + item.name + "/"));
+                                        entries.push(traverseFileTree(entry, `${path + item.name}/`));
                                     }
                                     readEntries();
                                 }
@@ -154,13 +187,13 @@ export function useDropZone<T extends HTMLElement = HTMLDivElement>({
             };
 
             for (let i = 0; i < items.length; i++) {
-                const entry = items[i].webkitGetAsEntry();
+                const entry = items[i].webkitGetAsEntry() as FileSystemEntry | null;
                 if (entry) {
                     promises.push(traverseFileTree(entry));
                 }
             }
 
-            Promise.all(promises).then((filesArrays) => {
+            void Promise.all(promises).then((filesArrays) => {
                 const allFiles = filesArrays.flat();
                 if (allFiles.length) {
                     onUpload(allFiles);

package/src/core/components/FormItem.tsx

@@ -1,39 +1,148 @@
+import { Env } from '@vertesia/ui/env';
 import clsx from 'clsx';
-import { ReactNode } from 'react';
-
-import { VTooltip } from './shadcn/tooltip';
 import { Info } from 'lucide-react';
+import { Children, cloneElement, Fragment, isValidElement, type ReactNode, useId, useRef } from 'react';
+import { VTooltip } from './shadcn/tooltip';
 
 interface FormItemProps {
-    label: any;
+    label: ReactNode;
     children: ReactNode;
+    /** Explicit id for the control. When omitted and FormItem can wire a single
+     *  element child, an id is auto-generated via useId(). */
     childrenId?: string;
     className?: string;
+    /** Tooltip text rendered on an Info icon next to the label.
+     *  NOTE: this is *not* an a11y substitute for helpText — it is hover-only.
+     *  For persistent helper text linked to the control via aria-describedby,
+     *  use the `helpText` prop instead. */
     description?: ReactNode;
+    /** Persistent helper text rendered below the control and linked via
+     *  aria-describedby. Use this (not `description`) to give screen-reader
+     *  users guidance on how to fill the field. */
+    helpText?: ReactNode;
+    /** Persistent error message rendered below the control. When set, the
+     *  control gets aria-invalid="true" and the error id is appended to
+     *  aria-describedby. */
+    error?: ReactNode;
     required?: boolean;
-    direction?: "row" | "column" | "row-reverse";
+    direction?: 'row' | 'column' | 'row-reverse';
     disabled?: boolean;
     /** When true, the label row stretches to full width. Useful when placing actions (e.g. buttons) inside the label. */
     fullWidthLabel?: boolean;
 }
-export function FormItem({ description, required, label, className, direction = "column", children, disabled = false, fullWidthLabel = false, childrenId }: FormItemProps) {
+
+function joinIds(...ids: Array<string | undefined | false | null>): string | undefined {
+    const filtered = ids.filter((id): id is string => typeof id === 'string' && id.length > 0);
+    return filtered.length > 0 ? filtered.join(' ') : undefined;
+}
+
+function canShowDevWarning(): boolean {
+    try {
+        return Env.isDev;
+    } catch {
+        return false;
+    }
+}
+
+export function FormItem({
+    description,
+    helpText,
+    error,
+    required,
+    label,
+    className,
+    direction = 'column',
+    children,
+    disabled = false,
+    fullWidthLabel = false,
+    childrenId,
+}: FormItemProps) {
+    const generatedId = useId();
+    const helpTextId = useId();
+    const errorId = useId();
+    const inputId = childrenId ?? generatedId;
+    const hasWarnedRef = useRef(false);
+
+    // A single valid element child is the auto-wire target. Children.toArray flattens
+    // nested arrays and fragments-of-elements, but a *single* element whose `type` is
+    // Fragment is still counted as one element by React — cloning it would add props
+    // to the Fragment (which ignores them), not to the input inside. Exclude that case.
+    const validChildren = Children.toArray(children).filter(isValidElement);
+    const singleChild = validChildren.length === 1 ? validChildren[0] : undefined;
+    const isSingleFragment = singleChild?.type === Fragment;
+    const canWireChild = !!singleChild && !isSingleFragment;
+    let wired = false;
+
+    let renderedChildren: ReactNode = children;
+    if (canWireChild && singleChild) {
+        const child = singleChild as React.ReactElement<Record<string, unknown>>;
+        const childProps = child.props ?? {};
+        const mergedDescribedBy = joinIds(
+            childProps['aria-describedby'] as string | undefined,
+            helpText ? helpTextId : undefined,
+            error ? errorId : undefined,
+        );
+        const ariaInvalid = childProps['aria-invalid'] ?? (error ? true : undefined);
+        renderedChildren = cloneElement(child, {
+            id: (childProps.id as string | undefined) ?? inputId,
+            'aria-describedby': mergedDescribedBy,
+            'aria-invalid': ariaInvalid,
+        });
+        wired = true;
+    } else if (canShowDevWarning() && !hasWarnedRef.current && (helpText || error || childrenId === undefined)) {
+        hasWarnedRef.current = true;
+        // eslint-disable-next-line no-console
+        console.warn(
+            '[@vertesia/ui] FormItem received zero, multiple, or a fragment as element children. ARIA wiring skipped. ' +
+                'Pass `childrenId` and set `id` / `aria-describedby` / `aria-invalid` on your input manually, ' +
+                'or wrap the input in a single non-fragment element.',
+        );
+    }
+
+    // Only set htmlFor when the label actually points at a real control:
+    // either we wired the child (so it received `inputId`) or the consumer
+    // provided `childrenId` and wired their input themselves.
+    const labelHtmlFor = wired || childrenId ? inputId : undefined;
+
     return (
-        <div className={clsx("flex w-full space-y-1", className, direction === "row" ? "flex-row justify-between items-center gap-2" : direction === "row-reverse" ? "flex-row-reverse justify-between items-center gap-2" : "flex-col")}>
+        <div
+            className={clsx(
+                'flex w-full space-y-1',
+                className,
+                direction === 'row'
+                    ? 'flex-row justify-between items-center gap-2'
+                    : direction === 'row-reverse'
+                      ? 'flex-row-reverse justify-between items-center gap-2'
+                      : 'flex-col',
+            )}
+        >
             <div className={clsx('flex items-center gap-1 mb-0', fullWidthLabel && 'w-full')}>
-                <label htmlFor={childrenId} className={`text-sm font-medium mb-1 ${disabled ? "text-muted" : ""} ${fullWidthLabel && "flex-1"}`}>
-                    {label}{required ? <span className='text-destructive -mt-4 ml-1'>*</span> : ""}
+                <label
+                    htmlFor={labelHtmlFor}
+                    className={`text-sm font-medium mb-1 ${disabled ? 'text-muted' : ''} ${fullWidthLabel && 'flex-1'}`}
+                >
+                    {label}
+                    {required ? <span className="text-destructive -mt-4 ms-1">*</span> : ''}
                 </label>
-                {
-                    description &&
-                    <div className='mx-2 flex w-4 items-center'>
-                        <VTooltip
-                            description={description}>
+                {description && (
+                    <div className="mx-2 flex w-4 items-center">
+                        <VTooltip description={description}>
                             <Info className="size-3 text-muted" />
                         </VTooltip>
                     </div>
-                }
+                )}
             </div>
-            {children}
+            {renderedChildren}
+            {helpText && (
+                <p id={helpTextId} className="text-xs text-muted">
+                    {helpText}
+                </p>
+            )}
+            {error && (
+                <p id={errorId} className="text-xs text-destructive">
+                    {error}
+                </p>
+            )}
         </div>
     );
 }

package/src/core/components/InputList.tsx

@@ -1,9 +1,10 @@
 import clsx from 'clsx';
-import React, { useState } from 'react';
+import type React from 'react';
+import { useState } from 'react';
 
 import { Badge } from './shadcn/badge';
 import { Input } from './shadcn/input';
-import { VTooltip } from '@vertesia/ui/core';
+import { VTooltip } from './shadcn/tooltip';
 
 interface InputListProps {
     value?: string[];
@@ -13,44 +14,57 @@ interface InputListProps {
     delimiters?: string; // space and , by default
     placeholder?: string;
     autoFocus?: boolean;
+    disabled?: boolean;
 }
-export function InputList({ value = [], onChange, className, delimiters = ", ", placeholder, autoFocus }: InputListProps) {
+export function InputList({
+    value = [],
+    onChange,
+    className,
+    delimiters = ', ',
+    placeholder,
+    autoFocus,
+    disabled = false,
+}: InputListProps) {
     const [text, setText] = useState<string>('');
 
-    const onBlur = (ev: any) => {
-        const v = ev.target.value;
-        if (v && v.trim()) {
-            onChange([...value, v.trim()])
-            setText('')
+    const onBlur = (ev: React.FocusEvent<HTMLInputElement>) => {
+        if (disabled) return;
+        const v = ev.currentTarget.value;
+        if (v?.trim()) {
+            onChange([...value, v.trim()]);
+            setText('');
         }
-    }
-    const onKeyDown = (ev: any) => {
-        const v = ev.target.value;
+    };
+    const onKeyDown = (ev: React.KeyboardEvent<HTMLInputElement>) => {
+        if (disabled) return;
+        const v = ev.currentTarget.value;
         const isEmpty = !v.trim();
         const key = ev.key;
         if (key === 'Enter' || delimiters.indexOf(key) > -1) {
             ev.preventDefault();
             if (value && !isEmpty) {
-                onChange([...value, v.trim()])
-                setText('')
+                onChange([...value, v.trim()]);
+                setText('');
             }
         } else if (key === 'Backspace' && isEmpty) {
             if (value && value.length > 0) {
                 value.pop();
-                onChange([...value])
+                onChange([...value]);
             }
         }
-    }
+    };
 
     const onPaste = (ev: React.ClipboardEvent<HTMLInputElement>) => {
+        if (disabled) return;
         const pastedText = ev.clipboardData.getData('text');
         if (pastedText) {
             ev.preventDefault();
 
             // Create a regex pattern from delimiters
-            const delimiterPattern = delimiters.split('').map((char: string) =>
-                char === ' ' ? '\\s' : char.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
-            ).join('|');
+            const delimiterPattern = delimiters
+                .split('')
+                .map((char: string) => (char === ' ' ? '\\s' : char.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')))
+                .join('|');
             const regex = new RegExp(`[${delimiterPattern}]+`);
 
             // Split the pasted text by delimiters and filter out empty values
@@ -65,9 +79,10 @@ export function InputList({ value = [], onChange, className, delimiters = ", ",
 
             setText('');
         }
-    }
+    };
 
-    const _onClick = (index: any): void => {
+    const _onClick = (index: number): void => {
+        if (disabled) return;
         if (value && value.length > 0) {
             value.splice(index, 1);
             onChange([...value]);
@@ -75,30 +90,41 @@ export function InputList({ value = [], onChange, className, delimiters = ", ",
     };
 
     return (
-        <div className={clsx(className,
-            'w-full flex flex-wrap items-center gap-1 p-2 py-1.5',
-            'rounded-md text-sm rounded-md border border-input bg-background ring-offset-background file:border-0 file:bg-transparent file:text-sm file:font-medium file:text-foreground placeholder:text-muted focus-visible:outline-none focus-visible:ring-1 ring-inset focus-visible:ring-ring disabled:cursor-not-allowed disabled:opacity-50')}>
-            {
-                value && value.length > 0 &&
-                (value.map((v, index) =>
+        <div
+            className={clsx(
+                className,
+                'w-full flex flex-wrap items-center gap-1 p-2 py-1.5',
+                'rounded-md text-sm rounded-md border border-input bg-background ring-offset-background file:border-0 file:bg-transparent file:text-sm file:font-medium file:text-foreground placeholder:text-muted focus-visible:outline-none focus-visible:ring-1 ring-inset focus-visible:ring-ring disabled:cursor-not-allowed disabled:opacity-50',
+                disabled && 'opacity-50 cursor-not-allowed',
+            )}
+        >
+            {value &&
+                value.length > 0 &&
+                value.map((v, index) => (
+                    // biome-ignore lint/suspicious/noArrayIndexKey: list order is stable for this render
                     <VTooltip description={'click to remove'} key={index}>
                         <Badge
-                            variant={"secondary"}
+                            variant={'secondary'}
+                            // biome-ignore lint/suspicious/noArrayIndexKey: list order is stable for this render
                             key={index}
                             onClick={() => _onClick(index)}
-                            className='cursor-pointer flex-shrink-0 hover:bg-destructive hover:text-destructive transition-colors'
+                            className={clsx(
+                                'flex-shrink-0 transition-colors',
+                                disabled
+                                    ? 'cursor-not-allowed'
+                                    : 'cursor-pointer hover:bg-destructive hover:text-destructive',
+                            )}
                             title={v}
                         >
-                            <span className='break-all'>{v}</span>
+                            <span className="break-all">{v}</span>
                         </Badge>
                     </VTooltip>
-                ))
-            }
+                ))}
             <Input
                 clearable={false}
-                className='placeholder:text-muted px-1 flex-1 min-w-[120px]'
-                variant='unstyled'
-                type='text'
+                className="placeholder:text-muted px-1 flex-1 min-w-[120px]"
+                variant="unstyled"
+                type="text"
                 value={text}
                 onBlur={onBlur}
                 onKeyDown={onKeyDown}
@@ -106,7 +132,8 @@ export function InputList({ value = [], onChange, className, delimiters = ", ",
                 onChange={setText}
                 placeholder={!value || value.length === 0 ? placeholder : ''}
                 autoFocus={autoFocus}
+                disabled={disabled}
             />
         </div>
-    )
-}
+    );
+}

package/src/core/components/Link.tsx

@@ -1,16 +1,19 @@
-import React from "react";
-import clsx from "clsx";
+import clsx from 'clsx';
+import type React from 'react';
 
 interface LinkProps extends React.HTMLProps<HTMLAnchorElement> {
-    underline?: 'always' | 'hover' | 'none'
+    underline?: 'always' | 'hover' | 'none';
 }
 export function Link({ underline = 'always', className, children, ...others }: LinkProps) {
-
     let underlineClass: string | undefined;
     if (underline === 'always') {
         underlineClass = 'underline';
     } else if (underline === 'hover') {
         underlineClass = 'hover:underline';
     }
-    return <a className={clsx("text-indigo-800 dark:text-indigo-300", className, underlineClass)} {...others}>{children}</a>
+    return (
+        <a className={clsx('text-indigo-800 dark:text-indigo-300', className, underlineClass)} {...others}>
+            {children}
+        </a>
+    );
 }

package/src/core/components/MenuList.tsx

@@ -1,41 +1,46 @@
-import clsx from "clsx";
-import { AnchorHTMLAttributes, forwardRef } from "react";
+import clsx from 'clsx';
+import { type AnchorHTMLAttributes, forwardRef } from 'react';
 
 interface MenuListProps {
-    children: React.ReactNode | React.ReactNode[]
-    className?: string
+    children: React.ReactNode | React.ReactNode[];
+    className?: string;
 }
 export function MenuList({ className, children }: MenuListProps) {
-    return (
-        <ul className={`${className} space-y-1 flex flex-col items-start`}>
-            {children}
-        </ul>
-    )
+    return <ul className={`${className} space-y-1 flex flex-col items-start`}>{children}</ul>;
 }
 
-
 interface MenuListItemProps extends AnchorHTMLAttributes<HTMLAnchorElement> {
-    current?: boolean
+    current?: boolean;
 }
 
 const MenuListItem = forwardRef<HTMLAnchorElement, MenuListItemProps>(function _MenuListItem(props, ref) {
     const { current, children, className, href = '#', onClick, ...others } = props;
     return (
-        <li className={clsx(className, current ? 'bg-muted' : '',
-            'w-full p-2 pl-3 text-sm leading-6 font-semibold hover:bg-muted')}>
-            <a ref={ref} href={href} onClick={(e) => {
-                if (onClick) {
-                    e.preventDefault();
-                    onClick(e);
-                } else if (href === '#') {
-                    e.preventDefault();
-                }
-            }}
-                className='w-full flex items-center gap-x-3'
+        <li
+            className={clsx(
+                className,
+                current ? 'bg-muted' : '',
+                'w-full p-2 ps-3 text-sm leading-6 font-semibold hover:bg-muted',
+            )}
+        >
+            <a
+                ref={ref}
+                href={href}
+                onClick={(e) => {
+                    if (onClick) {
+                        e.preventDefault();
+                        onClick(e);
+                    } else if (href === '#') {
+                        e.preventDefault();
+                    }
+                }}
+                className="w-full flex items-center gap-x-3"
                 {...others}
-            >{children}</a>
+            >
+                {children}
+            </a>
         </li>
-    )
+    );
 });
 
 MenuList.Item = MenuListItem;