najm-kit 2.1.48 → 2.1.49

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## 2.1.49 - 2026-08-04
+
+### ImageInput and AvatarInput
+
+- Add `previewAlt`, `fallbackImage`, `fallbackAlt`, `unavailableContent`,
+  `imageClassName`, `onPreviewError`, `replaceAriaLabel`, and `clearAriaLabel`
+  to `ImageInputProps`. `AvatarInput` forwards every new prop unchanged.
+- Preview sources resolve in this priority order: `value`, `fallbackImage`,
+  `defaultImage`. Candidate URLs are deduplicated so a failing primary URL is
+  never retried through multiple stages. When every candidate fails, the
+  broken `<img>` is unmounted and `unavailableContent` (or a neutral default)
+  is rendered in its place.
+- `imageVersion` is appended safely to relative, absolute, queried, and
+  fragmented URLs. `data:`, `blob:`, `javascript:`, and `file:` URLs are
+  left unchanged.
+- Expose `data-image-input-state="empty" | "preview" | "fallback" | "unavailable"`
+  on the preview container for styling, testing, and consumer diagnostics.
+- File selection is race-safe: stale `FileReader` completions cannot replace
+  a newer value. Object URLs created by the component are tracked so
+  consumer-owned blob URLs are never revoked.
+- Replace and clear controls are real `<button>` elements, are reachable
+  with the keyboard, and stay visible on touch and coarse-pointer devices.
+  Only on `(hover: hover) and (pointer: fine)` desktops do the controls fall
+  back to a hover/focus reveal. `focus-visible` always restores visibility.
+- Use logical positioning (`end-*`) so the clear button works correctly in
+  RTL layouts.
+- Re-export `ImageInputPreviewSource` and `ImageInputPreviewError` from
+  `najm-kit/components/inputs` and the package root.
+
 ## 2.1.48 - 2026-08-04
 
 - Keep responsive card row actions visible on phone, tablet, and touch input,

package/README.md

@@ -141,12 +141,80 @@ import { Form, FormInput, useNForm } from 'najm-kit';
 | Category | Components |
 |----------|-----------|
 | Actions | NButton, IconButton, toggleVariants |
-| Forms | Input, Textarea, Label, Select, Checkbox, RadioGroup, Switch, DateInput, FileInput |
+| Forms | Input, Textarea, Label, Select, Checkbox, RadioGroup, Switch, DateInput, FileInput, ImageInput, AvatarInput |
 | Feedback | Alert, Badge, Progress, Spinner, Toast |
 | Layout | Card, Sheet, Dialog, Popover, DropdownMenu, Tabs |
 | Data | Table (NTable), StatCard, DetailList |
 | Overlays | Command palette, Tooltip, Toast |
 
+## ImageInput and AvatarInput
+
+`ImageInput` and `AvatarInput` ship with a resilient preview contract so
+consumers do not need to wrap them with application-specific preview
+components.
+
+Source precedence:
+
+- When `value` is a non-empty string URL, candidates are tried in order:
+  1. `value` is the primary preview source.
+  2. If the primary source fails, `fallbackImage` is tried when supplied.
+  3. `defaultImage` is the last-resort fallback.
+- When `value` is `null` or empty, only `defaultImage` is tracked. The
+  `fallbackImage` is intentionally not used in the empty state — a null
+  `value` is the consumer's empty-state signal, and only the configured
+  default participates in the failed-default → unavailable transition.
+  If `defaultImage` itself fails, `onPreviewError({ source: "default" })`
+  fires and the unavailable state is rendered.
+
+Candidate URLs are deduplicated so the same failing URL is never retried
+through multiple stages. When every candidate fails, the broken `<img>` is
+unmounted and `unavailableContent` (or a neutral default) is rendered in its
+place. A `data-image-input-state="empty" | "preview" | "fallback" | "unavailable"`
+marker is exposed for styling, testing, and consumer diagnostics.
+
+Candidate URLs are deduplicated so the same failing URL is never retried
+through multiple stages. When every candidate fails, the broken `<img>` is
+unmounted and `unavailableContent` (or a neutral default) is rendered in its
+place. A `data-image-input-state="empty" | "preview" | "fallback" | "unavailable"`
+marker is exposed for styling, testing, and consumer diagnostics.
+
+```tsx
+import { ImageInput } from "najm-kit";
+
+<ImageInput
+  value="https://cdn.example.com/avatar.png"
+  onChange={setAvatar}
+  previewAlt="Workspace logo"
+  fallbackImage="/assets/logo-default.png"
+  fallbackAlt="Default workspace logo"
+  unavailableContent={<span>Logo unavailable</span>}
+  imageClassName="object-contain"
+  imageVersion={cacheBustVersion}
+  replaceAriaLabel="Replace workspace logo"
+  clearAriaLabel="Remove workspace logo"
+  onPreviewError={(err) => log(err)}
+/>
+```
+
+Key behaviors:
+
+- The replace and clear controls are real `<button>` elements, are reachable
+  with the keyboard (`Enter` and `Space` activate them once), and stay
+  visible on touch and coarse-pointer devices. Only on `(hover: hover) and
+  (pointer: fine)` desktops do the controls fall back to a hover/focus
+  reveal. `focus-visible` always restores visibility.
+- Positioning uses logical properties (`end-*`) so the clear button works
+  correctly in RTL layouts.
+- `imageVersion` is appended safely to relative, absolute, queried, and
+  fragmented URLs. `data:`, `blob:`, `javascript:`, and `file:` URLs are
+  left unchanged.
+- File selection is race-safe: stale `FileReader` completions cannot replace
+  a newer value, and object URLs created by the component are tracked so
+  consumer-owned blob URLs are never revoked.
+
+`AvatarInput` forwards every preview and accessibility prop unchanged while
+preserving its circular, size, fill, and camera-icon defaults.
+
 ## Hooks
 
 ```tsx

package/dist/index.d.ts

@@ -2178,6 +2178,11 @@ interface TimeInputProps extends BaseProps {
 interface TimeZoneInputProps extends Omit<ComboboxInputProps, "items"> {
     items?: SelectItemType[];
 }
+type ImageInputPreviewSource = "value" | "fallback" | "default";
+interface ImageInputPreviewError {
+    source: ImageInputPreviewSource;
+    src: string;
+}
 interface ImageInputProps extends BaseProps {
     value: File | string | null;
     onChange: (file: File | null) => void;
@@ -2192,6 +2197,8 @@ interface ImageInputProps extends BaseProps {
     previewStyle?: CSSProperties;
     /** Class applied to the empty and replace-overlay content inside the preview. */
     contentClassName?: string;
+    /** Class applied to the preview <img> element to control object-fit / sizing. */
+    imageClassName?: string;
     showPreview?: boolean;
     previewPosition?: "top" | "bottom" | "left" | "right";
     allowClear?: boolean;
@@ -2208,6 +2215,26 @@ interface ImageInputProps extends BaseProps {
     trigger?: "icon" | "button" | "both";
     buttonLabel?: string;
     disabled?: boolean;
+    /** Accessible name for the primary preview image. Falls back to `replaceTitle`. */
+    previewAlt?: string;
+    /** Accessible name for the fallback/default preview image. Falls back to `previewAlt`. */
+    fallbackAlt?: string;
+    /**
+     * URL tried when the primary `value` fails to load.
+     * The same URL is never attempted twice, so a failing primary cannot loop.
+     */
+    fallbackImage?: string | null;
+    /**
+     * Rendered inside the preview area when every candidate URL has failed.
+     * When omitted, a small neutral unavailable state is rendered instead.
+     */
+    unavailableContent?: React.ReactNode;
+    /** Fires once for every URL that failed to load, with its source. */
+    onPreviewError?: (error: ImageInputPreviewError) => void;
+    /** Accessible name for the replace (re-upload) control. */
+    replaceAriaLabel?: string;
+    /** Accessible name for the clear control. */
+    clearAriaLabel?: string;
 }
 interface OtpInputProps extends BaseProps {
     value: string;
@@ -2334,7 +2361,7 @@ interface NUploaderProps {
 }
 declare function NUploader({ title, subtitle, accept, multiple, disabled, items, listTitle, className, dropzoneClassName, onFilesSelected, onCancel, onRemove, }: NUploaderProps): react_jsx_runtime.JSX.Element;
 
-declare function ImageInput({ value, onChange, containerClassName, previewClassName, previewStyle, contentClassName, showPreview, previewPosition, allowClear, accept, defaultImage, imageSize, imageVersion, disabled, uploadIcon, title, subtitle, titleClassName, subtitleClassName, replaceTitle, replaceSubtitle, trigger, buttonLabel, }: ImageInputProps): react_jsx_runtime.JSX.Element;
+declare function ImageInput({ value, onChange, containerClassName, previewClassName, previewStyle, contentClassName, imageClassName, showPreview, previewPosition, allowClear, accept, defaultImage, fallbackImage, previewAlt, fallbackAlt, unavailableContent, onPreviewError, replaceAriaLabel, clearAriaLabel, imageSize, imageVersion, disabled, uploadIcon, title, subtitle, titleClassName, subtitleClassName, replaceTitle, replaceSubtitle, trigger, buttonLabel, }: ImageInputProps): react_jsx_runtime.JSX.Element;
 
 /** A circular image picker preset for profile photos and user avatars. */
 declare function AvatarInput({ imageSize, size, fill, radius, containerClassName, previewClassName, previewStyle, contentClassName, uploadIcon, title, subtitleClassName, trigger, ...props }: AvatarInputProps): react_jsx_runtime.JSX.Element;
@@ -3905,4 +3932,4 @@ interface NGridItemProps extends Omit<React$1.AllHTMLAttributes<HTMLDivElement>,
 declare function NGrid({ as: Comp, children, cols, smCols, mdCols, lgCols, xlCols, gap, className, style, ...props }: NGridProps): react_jsx_runtime.JSX.Element;
 declare function NGridItem({ children, span, smSpan, mdSpan, lgSpan, xlSpan, className, ...props }: NGridItemProps): react_jsx_runtime.JSX.Element;
 
-export { Alert, type AlertLook, type AlertOrientation, type AlertProps, type AlertSize, type AlertTone, type AlertVariant, NCard as AsyncCard, Avatar, AvatarFallback, AvatarFormInput, type AvatarFormInputProps, AvatarGroup, type AvatarGroupProps, AvatarImage, AvatarInput, type AvatarInputProps, type AvatarInputRadius, type AvatarProps$1 as AvatarProps, type AvatarShape$1 as AvatarShape, type AvatarSize, AvatarStatus, type AvatarStatusType, Badge, type BadgeColor, type BadgeIcon, type BadgeLook, type BadgeProps, type BadgeShape, type BadgeSize, type BadgeVariant, BaseInput, type BuildDefaultFileColumnsOptions, Button, type ButtonConfig, type ButtonIcon, type ButtonLoaderPosition, type ButtonProps, type ButtonRounded, type ButtonSize, type ButtonVariant, Calendar, Card, CardAction, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, Checkbox, CheckboxGroupInput, type CheckboxGroupInputProps, CheckboxInput, type CheckboxInputProps, Collapsible, CollapsibleContent, CollapsibleTrigger, ColorArrayInput, type ColorArrayInputProps, type ColorFormat, ColorPickerInput, type ColorPickerInputProps, Combobox, ComboboxInput, type ComboboxInputProps, type ComboboxOption, type ComboboxProps, Command, CommandDialog, CommandEmpty, CommandGroup, CommandInput, CommandItem, CommandList, CommandSeparator, CommandShortcut, type ContextMenuItem, DEFAULT_THEME_FILE_NAME, DateInput, type DateInputProps, type DeleteDialogOptions, Dialog, type DialogActionMode, type DialogApi, DialogClose, type DialogConfig, DialogContent, type DialogContentProps, DialogDescription, DialogFooter, DialogHeader, type DialogHeight, DialogOverlay, type DialogPadding, DialogPortal, type DialogRenderContext, type DialogRenderer, type DialogSize, type DialogStore, DialogTitle, DialogTrigger, type DialogVariant, type DialogWidth, DropdownMenu, DropdownMenuCheckboxItem, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuLabel, DropdownMenuPortal, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, DropdownMenuTrigger, DynamicArray, type DynamicArrayProps, EmojiInput, type EmojiInputProps, type FileBrowserMode, FileImportButton, FileInput, type FileInputProps, type FileNode, Form, FormControl, FormDescription, FormField, FormInput, type FormInputBackground, type FormInputProps, FormItem, FormLabel, FormMessage, type FormProps, type FormSlotClassNames, type FormVariant, IconButton, type IconButtonProps, type IconButtonSize, type IconButtonVariant, ImageInput, type ImageInputProps, Indicator, type IndicatorHorizontal, type IndicatorOverlay, type IndicatorPosition, type IndicatorProps, type IndicatorResponsivePosition, type IndicatorSize, type IndicatorVertical, Input, type InputIcon, Label, LangInput, type LangInputProps, type LinkComponentType, MultiSelectInput, type MultiSelectInputProps, NAJM_COMPONENT_NAMES, NAlert, type NAppCommandItem, NAppShell, type NAppShellAction, type NAppShellClassNames, type NAppShellProps, type NAppShellUser, NCard as NAsyncCard, type CardClassNames as NAsyncCardClassNames, type CardProps as NAsyncCardProps, NAvatar, type NAvatarClassNames, type NAvatarProps, type AvatarShape as NAvatarShape, NBadge, type NBadgeLook, type NBadgeProps, type NBulkAction, type NBulkActionButton, type NBulkActionSelect, NBulkActionsBar, type NBulkActionsBarProps, NButton, type NButtonProps, NCard, NCardAction, type CardClassNames as NCardClassNames, type NCardDensity, NCardFooter, NCardInfo, type NCardInfoProps, NCardMedia, type NCardMediaAspect, type NCardMediaPlacement, type NCardMediaProps, type NCardMediaSize, type NCardMediaVariant, type CardProps as NCardProps, NCardSection, type NCardSectionProps, type NCardSectionSurface, NCommandPalette, type NCommandPaletteProps, NConfirmDialog, type NConfirmDialogProps, NContextMenu, type NContextMenuItem, type NContextMenuProps, NDataCardShell, type NDataCardShellActions, type NDataCardShellProps, NDeleteDialog, NDeleteDialogContent, type NDeleteDialogContentProps, type NDeleteDialogProps, NDetailCard, type NDetailCardClassNames, type NDetailCardProps, NDetailItem, type NDetailItemProps, NDetailList, type NDetailListItem, type NDetailListProps, NDialog, type NDialogActionProps, NDialogDescription, type NDialogDescriptionProps, type NDialogDirectProps, NDialogHeader, type NDialogHeaderProps, NDialogPrimaryButton, type NDialogProps, NDialogSecondaryButton, NDonutCard, type NDonutCardClassNames, type NDonutCardItem, type NDonutCardLayout, type NDonutCardLegendMarker, type NDonutCardProps, type NDonutCardVariant, type NEditorTab, NEditorTabs, type NEditorTabsProps, NEmptyState, type NEmptyStateProps, NErrorBoundary, NErrorState, type NErrorStateProps, NFileBrowser, type NFileBrowserCardProps, type NFileBrowserProps, type NFileBrowserRenderThumbProps, NFileTypeIcon, type NFileTypeIconProps, NFilterBar, NFolderIcon, type NFolderIconProps, NForm, NFormSectionHeader, type NFormSectionHeaderProps, NGrid, type NGridCols, NGridItem, type NGridItemProps, type NGridProps, type NGridSpan, NIcon, type NIconProps, type NIconSource, NIndicator, NInspectorSheet, NLoadingState, type NLoadingStateProps, NMultiDialog, type NMultiDialogProps, NNavbar, NPageHeader, NPageHeaderActions, type NPageHeaderBreakpoint, NPageHeaderCompactActions, NPageHeaderFilters, type NPageHeaderProps, NPageHeaderTop, NPageLayout, type NPageLayoutProps, NPortalScopeProvider, NProgress, type NProgressProps, NRowActions, NSection, NSectionHeader, type NSectionHeaderActionsProps, type NSectionHeaderContentProps, type NSectionHeaderProps, type NSectionHeaderSubtitleProps, type NSectionHeaderTitleProps, NSectionInfo, type NSectionInfoProps, type NSectionProps, NSectionWithInfo, type NSectionWithInfoItem, type NSectionWithInfoProps, NSheet, type NSheetClassNames, type NSheetProps, NSidebar, NSidebarContent, type NSidebarContentProps, NSidebarFooter, type NSidebarFooterProps, NSidebarHeader, type NSidebarHeaderProps, NSidebarItem, NSidebarLogo, type NSidebarLogoProps, NSidebarMobile, type NSidebarMobileProps, NSidebarSection, type NSidebarSectionProps, NSkeleton, NSkeletonCalendar, NSkeletonChart, NSkeletonDonut, NSkeletonEventList, NSkeletonWidget, NSkeletonWidgets, NSlider, type NSliderProps, NSmartPasteDialog, type NSmartPasteDialogProps, NSpinner, type NSpinnerProps, NStatCard, type NStatCardClassNames, type NStatCardProps, NStatCardSkeleton, type NStatCardVariant, Swap as NSwap, type NSwapProps, NTable, type NTableCardPagination, NTableCardRoot, type NTableCardRootProps, NTableCards, type NTableClassNames, type NTableColumnBreakpoint, type NTableColumnDef, type NTableColumnMeta, NTableContent, NTableHeader, type NTableLoadMorePagination, NTableLoadingSkeleton, type NTableMenu, type NTableMenuProp, NTablePagination, type NTableProps, NTableRowSkeleton, NTableSkeleton, type NTableState, NTabs, type NTabsClassNames, type NTabsColor, type NTabsItem, type NTabsProps, type NTabsStyles, NThemeCustomizer, type NThemeCustomizerFontOption, type NThemeCustomizerLabels, type NThemeCustomizerProps, type NThemeCustomizerTab, NUploader, type NUploaderItem, type NUploaderItemStatus, type NUploaderProps, NViewBody, NViewToggle, type NajmAccent, type NajmAppearance, type NajmBorderSide, type NajmComponentName, type NajmComponentRadius, type NajmComponentStyleConfig, type NajmComponentThemeConfig, type NajmDensity, type NajmDesignConfig, NajmDesignProvider, type NajmDesignProviderProps, type NajmLayoutConfig, type NajmMode, type NajmPreset, type NajmResponsiveBreakpoint, type NajmResponsiveValue, NajmScroll, type NajmScrollProps, type NajmSlotStyle, type NajmThemeConfig, NajmThemeProvider, type NajmThemeProviderProps, type NajmThemeTokens, type NajmTypographyConfig, type NajmVariantStyle, NativeSelect, type NativeSelectOption, type NativeSelectProps, type NavItem, type NavItemGroup, NumberInput, type NumberInputProps, OtpInput, type OtpInputProps, PasswordInput, type PasswordInputProps, PhoneInput, type PhoneInputProps, Popover, PopoverAnchor, PopoverContent, PopoverTrigger, PrefixProvider, Progress, type ProgressColor, type ProgressLabelPosition, type ProgressProps, type ProgressSize, type PushDialogOptions, RADIUS_VALUE_MAP, RadioGroup, RadioGroupInput, type RadioGroupInputProps, RadioGroupItem, type RenderSlot, RepeatingFields, type RepeatingFieldsProps, ScrollArea, type ScrollAreaProps, SearchField, SearchField as SearchInput, SegmentedControl, type SegmentedControlOption, type SegmentedControlProps, Select, SelectContent, SelectGroup, SelectInput, type SelectInputProps, SelectItem, type SelectItemType$1 as SelectItemDataType, type SelectItemType, SelectLabel, SelectScrollDownButton, SelectScrollUpButton, SelectSeparator, SelectTrigger, SelectValue, Separator, Sheet, SheetClose, SheetContent, SheetDescription, SheetFooter, SheetHeader, SheetOverlay, SheetPortal, SheetTitle, SheetTrigger, type SidebarItemProps, type SidebarProps, type SidebarWidth, type SidebarWidths, SimpleTooltip, type SimpleTooltipProps, NSkeleton as Skeleton, Slider, SliderInput, type SliderInputProps, type SliderOrientation, type SliderProps, type SliderSize, type SliderVariant, type SmartPastePreview, type SpinnerVariant, StarRatingInput, type StarRatingInputProps, StatusPill, type StatusPillProps, type StatusPillTone, type StepConfig, StepIndicator, type StepMeta, StepsHeader, StepsProgress, type StorageMenuAction, type StorageSortOption, type StorageTarget, Swap, type SwapEffect, SwapIndeterminate, SwapOff, SwapOn, type SwapProps, type SwapSize, type SwapState, Switch, type SwitchColor, SwitchInput, type SwitchInputProps, type SwitchSize, TAB_COLORS, Table, TableBody, TableCaption, TableCell, TableFooter, TableHead, TableHeader, type TableHeaderColor, TableRow, type TableState, type TableStore, TableStoreContext, Tabs, TabsContent, TabsList, type TabsListProps, type TabsOrientation, type TabsProps, TabsTrigger, type TabsTriggerProps, type TabsVariant, TextAreaInput, type TextAreaInputProps, TextInput, type TextInputProps, Textarea, TimeInput, type TimeInputProps, TimeZoneInput, type TimeZoneInputProps, Toaster, Toggle, Tooltip, TooltipContent, TooltipProvider, TooltipTrigger, type UseContextMenuResult, type UseNFormOptions, type UseStorageContextMenuOptions, type UseStorageContextMenuResult, type UserMenuAction, VariantProvider, type WizardClassNames, WizardForm, type WizardFormProps, alertVariants, avatarVariants, badgeColorVariants, badgeVariants, buildDefaultFileColumns, buttonVariants, cn, composePreset, createDialogStore, createTableStore, defineNajmDesignConfig, defineNajmThemeConfig, detectFormat, dialogVariants, filterResponsiveColumns, formatColor, formatFileBytes, formatFileRelative, getIconColorProps, getNextEditorTabValue, hiddenBelowClasses, indicatorVariants, inputBorderClasses, normalizeThemeFileName, parseColor, parseNajmDesignConfig, parseNajmThemeConfig, parseThemeFile, resolveHiddenBelowClass, resolvePreset, resolveRadiusValue, resolveSlot, resolveVariantAlias, sidebarBorderClasses, sliderVariants, stringifyNajmDesignConfig, stringifyNajmThemeConfig, stringifyThemeFile, surfaceBorderClasses, swapVariants, toPickerHex, toggleVariants, tooltipContentVariants, truncateByCharacters, useClickOutside, useContextMenu, useDebouncedValue, useDelayedLoading, useDialog, useDialogStore, useDynamicPageSize, useFormField, useFormSubmission, useInfiniteScroll, useKeyboard, useLocalStorageState, useNForm, useNPortalScope, useNajmAppearance, useNajmComponentStyle, useNajmDesign, useNajmThemeMode, usePrefix, useSelection, useStepNavigation, useStorageContextMenu, useStoreSync, useTable, useTableKeyboard, useTableStore, useVariant, useVariantPreset };
+export { Alert, type AlertLook, type AlertOrientation, type AlertProps, type AlertSize, type AlertTone, type AlertVariant, NCard as AsyncCard, Avatar, AvatarFallback, AvatarFormInput, type AvatarFormInputProps, AvatarGroup, type AvatarGroupProps, AvatarImage, AvatarInput, type AvatarInputProps, type AvatarInputRadius, type AvatarProps$1 as AvatarProps, type AvatarShape$1 as AvatarShape, type AvatarSize, AvatarStatus, type AvatarStatusType, Badge, type BadgeColor, type BadgeIcon, type BadgeLook, type BadgeProps, type BadgeShape, type BadgeSize, type BadgeVariant, BaseInput, type BuildDefaultFileColumnsOptions, Button, type ButtonConfig, type ButtonIcon, type ButtonLoaderPosition, type ButtonProps, type ButtonRounded, type ButtonSize, type ButtonVariant, Calendar, Card, CardAction, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, Checkbox, CheckboxGroupInput, type CheckboxGroupInputProps, CheckboxInput, type CheckboxInputProps, Collapsible, CollapsibleContent, CollapsibleTrigger, ColorArrayInput, type ColorArrayInputProps, type ColorFormat, ColorPickerInput, type ColorPickerInputProps, Combobox, ComboboxInput, type ComboboxInputProps, type ComboboxOption, type ComboboxProps, Command, CommandDialog, CommandEmpty, CommandGroup, CommandInput, CommandItem, CommandList, CommandSeparator, CommandShortcut, type ContextMenuItem, DEFAULT_THEME_FILE_NAME, DateInput, type DateInputProps, type DeleteDialogOptions, Dialog, type DialogActionMode, type DialogApi, DialogClose, type DialogConfig, DialogContent, type DialogContentProps, DialogDescription, DialogFooter, DialogHeader, type DialogHeight, DialogOverlay, type DialogPadding, DialogPortal, type DialogRenderContext, type DialogRenderer, type DialogSize, type DialogStore, DialogTitle, DialogTrigger, type DialogVariant, type DialogWidth, DropdownMenu, DropdownMenuCheckboxItem, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuLabel, DropdownMenuPortal, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, DropdownMenuTrigger, DynamicArray, type DynamicArrayProps, EmojiInput, type EmojiInputProps, type FileBrowserMode, FileImportButton, FileInput, type FileInputProps, type FileNode, Form, FormControl, FormDescription, FormField, FormInput, type FormInputBackground, type FormInputProps, FormItem, FormLabel, FormMessage, type FormProps, type FormSlotClassNames, type FormVariant, IconButton, type IconButtonProps, type IconButtonSize, type IconButtonVariant, ImageInput, type ImageInputPreviewError, type ImageInputPreviewSource, type ImageInputProps, Indicator, type IndicatorHorizontal, type IndicatorOverlay, type IndicatorPosition, type IndicatorProps, type IndicatorResponsivePosition, type IndicatorSize, type IndicatorVertical, Input, type InputIcon, Label, LangInput, type LangInputProps, type LinkComponentType, MultiSelectInput, type MultiSelectInputProps, NAJM_COMPONENT_NAMES, NAlert, type NAppCommandItem, NAppShell, type NAppShellAction, type NAppShellClassNames, type NAppShellProps, type NAppShellUser, NCard as NAsyncCard, type CardClassNames as NAsyncCardClassNames, type CardProps as NAsyncCardProps, NAvatar, type NAvatarClassNames, type NAvatarProps, type AvatarShape as NAvatarShape, NBadge, type NBadgeLook, type NBadgeProps, type NBulkAction, type NBulkActionButton, type NBulkActionSelect, NBulkActionsBar, type NBulkActionsBarProps, NButton, type NButtonProps, NCard, NCardAction, type CardClassNames as NCardClassNames, type NCardDensity, NCardFooter, NCardInfo, type NCardInfoProps, NCardMedia, type NCardMediaAspect, type NCardMediaPlacement, type NCardMediaProps, type NCardMediaSize, type NCardMediaVariant, type CardProps as NCardProps, NCardSection, type NCardSectionProps, type NCardSectionSurface, NCommandPalette, type NCommandPaletteProps, NConfirmDialog, type NConfirmDialogProps, NContextMenu, type NContextMenuItem, type NContextMenuProps, NDataCardShell, type NDataCardShellActions, type NDataCardShellProps, NDeleteDialog, NDeleteDialogContent, type NDeleteDialogContentProps, type NDeleteDialogProps, NDetailCard, type NDetailCardClassNames, type NDetailCardProps, NDetailItem, type NDetailItemProps, NDetailList, type NDetailListItem, type NDetailListProps, NDialog, type NDialogActionProps, NDialogDescription, type NDialogDescriptionProps, type NDialogDirectProps, NDialogHeader, type NDialogHeaderProps, NDialogPrimaryButton, type NDialogProps, NDialogSecondaryButton, NDonutCard, type NDonutCardClassNames, type NDonutCardItem, type NDonutCardLayout, type NDonutCardLegendMarker, type NDonutCardProps, type NDonutCardVariant, type NEditorTab, NEditorTabs, type NEditorTabsProps, NEmptyState, type NEmptyStateProps, NErrorBoundary, NErrorState, type NErrorStateProps, NFileBrowser, type NFileBrowserCardProps, type NFileBrowserProps, type NFileBrowserRenderThumbProps, NFileTypeIcon, type NFileTypeIconProps, NFilterBar, NFolderIcon, type NFolderIconProps, NForm, NFormSectionHeader, type NFormSectionHeaderProps, NGrid, type NGridCols, NGridItem, type NGridItemProps, type NGridProps, type NGridSpan, NIcon, type NIconProps, type NIconSource, NIndicator, NInspectorSheet, NLoadingState, type NLoadingStateProps, NMultiDialog, type NMultiDialogProps, NNavbar, NPageHeader, NPageHeaderActions, type NPageHeaderBreakpoint, NPageHeaderCompactActions, NPageHeaderFilters, type NPageHeaderProps, NPageHeaderTop, NPageLayout, type NPageLayoutProps, NPortalScopeProvider, NProgress, type NProgressProps, NRowActions, NSection, NSectionHeader, type NSectionHeaderActionsProps, type NSectionHeaderContentProps, type NSectionHeaderProps, type NSectionHeaderSubtitleProps, type NSectionHeaderTitleProps, NSectionInfo, type NSectionInfoProps, type NSectionProps, NSectionWithInfo, type NSectionWithInfoItem, type NSectionWithInfoProps, NSheet, type NSheetClassNames, type NSheetProps, NSidebar, NSidebarContent, type NSidebarContentProps, NSidebarFooter, type NSidebarFooterProps, NSidebarHeader, type NSidebarHeaderProps, NSidebarItem, NSidebarLogo, type NSidebarLogoProps, NSidebarMobile, type NSidebarMobileProps, NSidebarSection, type NSidebarSectionProps, NSkeleton, NSkeletonCalendar, NSkeletonChart, NSkeletonDonut, NSkeletonEventList, NSkeletonWidget, NSkeletonWidgets, NSlider, type NSliderProps, NSmartPasteDialog, type NSmartPasteDialogProps, NSpinner, type NSpinnerProps, NStatCard, type NStatCardClassNames, type NStatCardProps, NStatCardSkeleton, type NStatCardVariant, Swap as NSwap, type NSwapProps, NTable, type NTableCardPagination, NTableCardRoot, type NTableCardRootProps, NTableCards, type NTableClassNames, type NTableColumnBreakpoint, type NTableColumnDef, type NTableColumnMeta, NTableContent, NTableHeader, type NTableLoadMorePagination, NTableLoadingSkeleton, type NTableMenu, type NTableMenuProp, NTablePagination, type NTableProps, NTableRowSkeleton, NTableSkeleton, type NTableState, NTabs, type NTabsClassNames, type NTabsColor, type NTabsItem, type NTabsProps, type NTabsStyles, NThemeCustomizer, type NThemeCustomizerFontOption, type NThemeCustomizerLabels, type NThemeCustomizerProps, type NThemeCustomizerTab, NUploader, type NUploaderItem, type NUploaderItemStatus, type NUploaderProps, NViewBody, NViewToggle, type NajmAccent, type NajmAppearance, type NajmBorderSide, type NajmComponentName, type NajmComponentRadius, type NajmComponentStyleConfig, type NajmComponentThemeConfig, type NajmDensity, type NajmDesignConfig, NajmDesignProvider, type NajmDesignProviderProps, type NajmLayoutConfig, type NajmMode, type NajmPreset, type NajmResponsiveBreakpoint, type NajmResponsiveValue, NajmScroll, type NajmScrollProps, type NajmSlotStyle, type NajmThemeConfig, NajmThemeProvider, type NajmThemeProviderProps, type NajmThemeTokens, type NajmTypographyConfig, type NajmVariantStyle, NativeSelect, type NativeSelectOption, type NativeSelectProps, type NavItem, type NavItemGroup, NumberInput, type NumberInputProps, OtpInput, type OtpInputProps, PasswordInput, type PasswordInputProps, PhoneInput, type PhoneInputProps, Popover, PopoverAnchor, PopoverContent, PopoverTrigger, PrefixProvider, Progress, type ProgressColor, type ProgressLabelPosition, type ProgressProps, type ProgressSize, type PushDialogOptions, RADIUS_VALUE_MAP, RadioGroup, RadioGroupInput, type RadioGroupInputProps, RadioGroupItem, type RenderSlot, RepeatingFields, type RepeatingFieldsProps, ScrollArea, type ScrollAreaProps, SearchField, SearchField as SearchInput, SegmentedControl, type SegmentedControlOption, type SegmentedControlProps, Select, SelectContent, SelectGroup, SelectInput, type SelectInputProps, SelectItem, type SelectItemType$1 as SelectItemDataType, type SelectItemType, SelectLabel, SelectScrollDownButton, SelectScrollUpButton, SelectSeparator, SelectTrigger, SelectValue, Separator, Sheet, SheetClose, SheetContent, SheetDescription, SheetFooter, SheetHeader, SheetOverlay, SheetPortal, SheetTitle, SheetTrigger, type SidebarItemProps, type SidebarProps, type SidebarWidth, type SidebarWidths, SimpleTooltip, type SimpleTooltipProps, NSkeleton as Skeleton, Slider, SliderInput, type SliderInputProps, type SliderOrientation, type SliderProps, type SliderSize, type SliderVariant, type SmartPastePreview, type SpinnerVariant, StarRatingInput, type StarRatingInputProps, StatusPill, type StatusPillProps, type StatusPillTone, type StepConfig, StepIndicator, type StepMeta, StepsHeader, StepsProgress, type StorageMenuAction, type StorageSortOption, type StorageTarget, Swap, type SwapEffect, SwapIndeterminate, SwapOff, SwapOn, type SwapProps, type SwapSize, type SwapState, Switch, type SwitchColor, SwitchInput, type SwitchInputProps, type SwitchSize, TAB_COLORS, Table, TableBody, TableCaption, TableCell, TableFooter, TableHead, TableHeader, type TableHeaderColor, TableRow, type TableState, type TableStore, TableStoreContext, Tabs, TabsContent, TabsList, type TabsListProps, type TabsOrientation, type TabsProps, TabsTrigger, type TabsTriggerProps, type TabsVariant, TextAreaInput, type TextAreaInputProps, TextInput, type TextInputProps, Textarea, TimeInput, type TimeInputProps, TimeZoneInput, type TimeZoneInputProps, Toaster, Toggle, Tooltip, TooltipContent, TooltipProvider, TooltipTrigger, type UseContextMenuResult, type UseNFormOptions, type UseStorageContextMenuOptions, type UseStorageContextMenuResult, type UserMenuAction, VariantProvider, type WizardClassNames, WizardForm, type WizardFormProps, alertVariants, avatarVariants, badgeColorVariants, badgeVariants, buildDefaultFileColumns, buttonVariants, cn, composePreset, createDialogStore, createTableStore, defineNajmDesignConfig, defineNajmThemeConfig, detectFormat, dialogVariants, filterResponsiveColumns, formatColor, formatFileBytes, formatFileRelative, getIconColorProps, getNextEditorTabValue, hiddenBelowClasses, indicatorVariants, inputBorderClasses, normalizeThemeFileName, parseColor, parseNajmDesignConfig, parseNajmThemeConfig, parseThemeFile, resolveHiddenBelowClass, resolvePreset, resolveRadiusValue, resolveSlot, resolveVariantAlias, sidebarBorderClasses, sliderVariants, stringifyNajmDesignConfig, stringifyNajmThemeConfig, stringifyThemeFile, surfaceBorderClasses, swapVariants, toPickerHex, toggleVariants, tooltipContentVariants, truncateByCharacters, useClickOutside, useContextMenu, useDebouncedValue, useDelayedLoading, useDialog, useDialogStore, useDynamicPageSize, useFormField, useFormSubmission, useInfiniteScroll, useKeyboard, useLocalStorageState, useNForm, useNPortalScope, useNajmAppearance, useNajmComponentStyle, useNajmDesign, useNajmThemeMode, usePrefix, useSelection, useStepNavigation, useStorageContextMenu, useStoreSync, useTable, useTableKeyboard, useTableStore, useVariant, useVariantPreset };

package/dist/index.mjs

@@ -9850,12 +9850,74 @@ function UploaderRow({ item, onCancel, onRemove }) {
     }
   );
 }
+
+// src/components/inputs/imagePreview.ts
+var NON_APPENDABLE_PREFIXES = ["data:", "blob:", "javascript:", "file:"];
+function isNonAppendable(src) {
+  const lower = src.toLowerCase();
+  return NON_APPENDABLE_PREFIXES.some((prefix) => lower.startsWith(prefix));
+}
+function isMeaningful(src) {
+  return typeof src === "string" && src.length > 0;
+}
+function appendImageVersion(src, version) {
+  if (!isMeaningful(src)) return src;
+  if (version == null || version === "") return src;
+  if (isNonAppendable(src)) return src;
+  const fragmentIndex = src.indexOf("#");
+  const beforeFragment = fragmentIndex === -1 ? src : src.slice(0, fragmentIndex);
+  const fragment = fragmentIndex === -1 ? "" : src.slice(fragmentIndex);
+  const queryIndex = beforeFragment.indexOf("?");
+  const base = queryIndex === -1 ? beforeFragment : beforeFragment.slice(0, queryIndex);
+  const existingQuery = queryIndex === -1 ? "" : beforeFragment.slice(queryIndex);
+  const separator = existingQuery ? "&" : "?";
+  const versionString = `${separator}v=${encodeURIComponent(String(version))}`;
+  if (!existingQuery && !fragment) {
+    return `${base}${versionString}`;
+  }
+  if (!existingQuery) {
+    return `${base}${versionString}${fragment}`;
+  }
+  if (!fragment) {
+    return `${base}${existingQuery}${versionString}`;
+  }
+  return `${base}${existingQuery}${versionString}${fragment}`;
+}
+function appendVersionToCandidate(src, version) {
+  if (version == null || version === "") return src;
+  if (isNonAppendable(src)) return src;
+  return appendImageVersion(src, version);
+}
+function buildPreviewCandidates(options) {
+  const seen = /* @__PURE__ */ new Set();
+  const result = [];
+  const push = (src, source) => {
+    if (!isMeaningful(src)) return;
+    if (seen.has(src)) return;
+    seen.add(src);
+    result.push({ src, source });
+  };
+  push(options.value ?? null, "value");
+  push(options.fallback ?? null, "fallback");
+  push(options.defaultImage ?? null, "default");
+  const version = options.imageVersion;
+  if (version == null || version === "") return result;
+  return result.map((candidate) => ({
+    src: appendVersionToCandidate(candidate.src, version),
+    source: candidate.source
+  }));
+}
+function candidatesKey(candidates) {
+  return candidates.map((candidate) => `${candidate.source}:${candidate.src}`).join("|");
+}
 var IMAGE_SIZE_MAP = {
   sm: "w-16 h-16",
   md: "w-24 h-24",
   lg: "w-32 h-32",
   xl: "w-40 h-40"
 };
+var CONTROL_VISIBILITY = "nimage-input-control";
+var COMPACT_OVERLAY_VISIBILITY = "nimage-input-compact-overlay";
 function ImageInput({
   value,
   onChange,
@@ -9863,11 +9925,19 @@ function ImageInput({
   previewClassName,
   previewStyle,
   contentClassName,
+  imageClassName,
   showPreview = true,
   previewPosition = "top",
   allowClear = true,
   accept = "image/*",
   defaultImage,
+  fallbackImage,
+  previewAlt,
+  fallbackAlt,
+  unavailableContent,
+  onPreviewError,
+  replaceAriaLabel,
+  clearAriaLabel,
   imageSize = "md",
   imageVersion,
   disabled = false,
@@ -9882,117 +9952,242 @@ function ImageInput({
   buttonLabel = "Upload"
 }) {
   const fileInputRef = useRef(null);
-  const [preview, setPreview] = useState(null);
+  const [localFilePreview, setLocalFilePreview] = useState(null);
+  const [failedSources, setFailedSources] = useState(() => /* @__PURE__ */ new Set());
+  const readerTokenRef = useRef(0);
+  const previewCandidates = useMemo(() => {
+    if (value instanceof File) return [];
+    if (typeof value === "string" && value) {
+      return buildPreviewCandidates({
+        value,
+        fallback: fallbackImage ?? null,
+        defaultImage: defaultImage ?? null,
+        imageVersion
+      });
+    }
+    return buildPreviewCandidates({
+      value: null,
+      fallback: null,
+      defaultImage: defaultImage ?? null,
+      imageVersion
+    });
+  }, [value, fallbackImage, defaultImage, imageVersion]);
+  const candidateKeyValue = useMemo(
+    () => candidatesKey(previewCandidates),
+    [previewCandidates]
+  );
+  const [trackedKey, setTrackedKey] = useState(candidateKeyValue);
+  if (trackedKey !== candidateKeyValue) {
+    setTrackedKey(candidateKeyValue);
+    setFailedSources(/* @__PURE__ */ new Set());
+  }
   useEffect(() => {
-    if (value instanceof File) {
-      const reader = new FileReader();
-      reader.onloadend = () => setPreview(reader.result);
-      reader.readAsDataURL(value);
-    } else if (typeof value === "string" && value) {
-      const url = imageVersion != null ? `${value}?v=${imageVersion}` : value;
-      setPreview(url);
-    } else {
-      setPreview(null);
+    if (!(value instanceof File)) {
+      setLocalFilePreview(null);
+      return void 0;
+    }
+    const token = ++readerTokenRef.current;
+    const reader = new FileReader();
+    reader.onloadend = () => {
+      if (token !== readerTokenRef.current) return;
+      if (typeof reader.result === "string") {
+        setLocalFilePreview(reader.result);
+      }
+    };
+    reader.onerror = () => {
+      if (token !== readerTokenRef.current) return;
+      setLocalFilePreview(null);
+    };
+    reader.readAsDataURL(value);
+    return () => {
+      if (token === readerTokenRef.current) {
+        readerTokenRef.current = token - 1;
+      }
+    };
+  }, [value]);
+  const activeCandidate = useMemo(() => {
+    if (value instanceof File) return null;
+    for (const candidate of previewCandidates) {
+      if (!failedSources.has(candidate.src)) return candidate;
     }
-  }, [value, imageVersion]);
+    return null;
+  }, [previewCandidates, failedSources, value]);
+  const handleCandidateError = (candidate) => {
+    setFailedSources((prev) => {
+      if (prev.has(candidate.src)) return prev;
+      const next = new Set(prev);
+      next.add(candidate.src);
+      return next;
+    });
+    onPreviewError?.({ source: candidate.source, src: candidate.src });
+  };
   const handleClick = () => {
-    if (!disabled) fileInputRef.current?.click();
+    if (disabled) return;
+    fileInputRef.current?.click();
   };
   const handleChange = (e) => {
     const file = e.target.files?.[0] || null;
     if (file) onChange(file);
+    e.target.value = "";
   };
   const handleClear = (e) => {
     e.stopPropagation();
+    if (disabled) return;
     onChange(null);
-    setPreview(null);
+    setLocalFilePreview(null);
     if (fileInputRef.current) fileInputRef.current.value = "";
   };
+  const handleImgError = () => {
+    if (value instanceof File) return;
+    if (activeCandidate) handleCandidateError(activeCandidate);
+  };
   const effectiveSize = previewClassName || IMAGE_SIZE_MAP[imageSize];
   const isDropzone = !!previewClassName;
   const effectiveReplaceSubtitle = replaceSubtitle ?? subtitle;
+  const primaryAlt = previewAlt ?? replaceTitle ?? "Preview";
+  const secondaryAlt = fallbackAlt ?? previewAlt ?? replaceTitle ?? "Preview";
+  const replaceAccessibleName = replaceAriaLabel ?? replaceTitle;
+  const clearAccessibleName = clearAriaLabel ?? "Remove image";
+  let dataState = "empty";
+  let previewSrc = null;
+  let previewAltText = primaryAlt;
+  if (value instanceof File) {
+    dataState = localFilePreview ? "preview" : "empty";
+    previewSrc = localFilePreview;
+    previewAltText = primaryAlt;
+  } else if (activeCandidate) {
+    dataState = activeCandidate.source === "value" ? "preview" : "fallback";
+    previewSrc = activeCandidate.src;
+    previewAltText = activeCandidate.source === "value" ? primaryAlt : secondaryAlt;
+  } else if (previewCandidates.length > 0) {
+    dataState = "unavailable";
+  }
+  const renderUnavailableContent = () => unavailableContent ?? /* @__PURE__ */ jsxs(Fragment, { children: [
+    /* @__PURE__ */ jsx(Image, { className: "h-10 w-10 text-muted-foreground/50", "aria-hidden": true }),
+    /* @__PURE__ */ jsx("span", { className: "text-xs text-muted-foreground", children: "Image unavailable" })
+  ] });
+  const renderClearButton = (compact) => {
+    if (!allowClear) return null;
+    return /* @__PURE__ */ jsx(
+      "button",
+      {
+        type: "button",
+        onClick: handleClear,
+        disabled,
+        "aria-label": clearAccessibleName,
+        className: cn(
+          "absolute top-2 end-2 z-10 flex items-center justify-center rounded-full bg-destructive text-destructive-foreground shadow-sm hover:bg-destructive/90 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background",
+          compact ? "p-1.5" : "h-6 w-6",
+          CONTROL_VISIBILITY
+        ),
+        children: /* @__PURE__ */ jsx(X, { className: compact ? "h-4 w-4" : "h-3.5 w-3.5" })
+      }
+    );
+  };
   const renderPreview = () => /* @__PURE__ */ jsx(
     "div",
     {
       style: previewStyle,
+      "data-image-input-state": dataState,
       className: cn(
-        "flex relative group rounded-lg overflow-hidden border-2 border-dashed border-muted-foreground/60 hover:border-primary transition-colors",
+        "group/image flex relative rounded-lg overflow-hidden border-2 border-dashed border-muted-foreground/60 hover:border-primary transition-colors",
         effectiveSize
       ),
-      children: preview ? isDropzone ? /* @__PURE__ */ jsxs(Fragment, { children: [
-        /* @__PURE__ */ jsx("img", { src: preview, alt: "Preview", className: "absolute inset-0 w-full h-full object-cover" }),
-        /* @__PURE__ */ jsxs("div", { className: cn("relative w-full h-full flex flex-col items-center justify-center gap-1.5 bg-black/40 text-white px-6 py-8 text-center", contentClassName), children: [
-          /* @__PURE__ */ jsx("span", { className: cn("text-sm font-medium", titleClassName), children: replaceTitle }),
-          effectiveReplaceSubtitle ? /* @__PURE__ */ jsx("span", { className: cn("text-xs opacity-80", subtitleClassName), children: effectiveReplaceSubtitle }) : null,
-          allowClear && /* @__PURE__ */ jsx(
-            "button",
-            {
-              type: "button",
-              onClick: handleClear,
-              disabled,
-              className: "absolute top-2 right-2 flex h-6 w-6 items-center justify-center rounded-full bg-destructive text-destructive-foreground shadow-sm hover:bg-destructive/90",
-              "aria-label": "Remove image",
-              children: /* @__PURE__ */ jsx(X, { className: "h-3.5 w-3.5" })
-            }
-          )
-        ] })
-      ] }) : /* @__PURE__ */ jsxs(Fragment, { children: [
-        /* @__PURE__ */ jsx("img", { src: preview, alt: "Preview", className: "w-full h-full object-cover" }),
+      children: previewSrc ? isDropzone ? /* @__PURE__ */ jsxs(Fragment, { children: [
         /* @__PURE__ */ jsx(
-          "div",
+          "img",
           {
-            onClick: handleClick,
-            className: "absolute inset-0 bg-black/50 opacity-0 group-hover:opacity-100 transition-opacity flex items-center justify-center cursor-pointer",
-            children: /* @__PURE__ */ jsx(Upload, { className: "h-8 w-8 text-white" })
+            src: previewSrc,
+            alt: previewAltText,
+            onError: handleImgError,
+            className: cn(
+              "absolute inset-0 w-full h-full object-cover",
+              imageClassName
+            )
           }
         ),
-        allowClear && /* @__PURE__ */ jsx(
+        /* @__PURE__ */ jsxs(
           "button",
           {
             type: "button",
-            onClick: handleClear,
+            onClick: handleClick,
             disabled,
-            className: "absolute top-2 right-2 p-1.5 bg-destructive text-white rounded-full opacity-0 group-hover:opacity-100 transition-opacity shadow-md hover:bg-destructive/90 z-10",
-            children: /* @__PURE__ */ jsx(X, { className: "h-4 w-4" })
+            "aria-label": replaceAccessibleName,
+            className: cn(
+              "relative w-full h-full flex flex-col items-center justify-center gap-1.5 bg-black/40 text-white px-6 py-8 text-center cursor-pointer focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background",
+              contentClassName
+            ),
+            children: [
+              /* @__PURE__ */ jsx("span", { className: cn("text-sm font-medium", titleClassName), children: replaceTitle }),
+              effectiveReplaceSubtitle ? /* @__PURE__ */ jsx("span", { className: cn("text-xs opacity-80", subtitleClassName), children: effectiveReplaceSubtitle }) : null
+            ]
           }
-        )
-      ] }) : defaultImage ? /* @__PURE__ */ jsxs(Fragment, { children: [
-        /* @__PURE__ */ jsx("img", { src: defaultImage, alt: "Default", className: "w-full h-full object-cover" }),
+        ),
+        renderClearButton(false)
+      ] }) : /* @__PURE__ */ jsxs(Fragment, { children: [
         /* @__PURE__ */ jsx(
-          "div",
+          "img",
           {
+            src: previewSrc,
+            alt: previewAltText,
+            onError: handleImgError,
+            className: cn("w-full h-full", imageClassName ?? "object-cover")
+          }
+        ),
+        /* @__PURE__ */ jsx(
+          "button",
+          {
+            type: "button",
             onClick: handleClick,
-            className: "absolute inset-0 bg-black/50 opacity-0 group-hover:opacity-100 transition-opacity flex items-center justify-center cursor-pointer",
-            children: /* @__PURE__ */ jsx(Upload, { className: "h-8 w-8 text-white" })
+            disabled,
+            "aria-label": replaceAccessibleName,
+            className: cn(
+              "absolute inset-0 bg-black/50 flex items-center justify-center cursor-pointer focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background",
+              COMPACT_OVERLAY_VISIBILITY
+            ),
+            children: /* @__PURE__ */ jsx(Upload, { className: "h-8 w-8 text-white", "aria-hidden": true })
           }
-        )
-      ] }) : isDropzone ? /* @__PURE__ */ jsxs(
+        ),
+        renderClearButton(true)
+      ] }) : dataState === "unavailable" ? /* @__PURE__ */ jsx(
         "div",
         {
+          "data-image-input-unavailable": true,
+          className: cn(
+            "w-full h-full flex flex-col items-center justify-center gap-2 bg-muted/30 text-muted-foreground px-6 py-8 text-center",
+            contentClassName
+          ),
+          children: renderUnavailableContent()
+        }
+      ) : isDropzone ? /* @__PURE__ */ jsxs(
+        "button",
+        {
+          type: "button",
           onClick: handleClick,
-          className: cn("w-full h-full flex flex-col items-center justify-center gap-2 cursor-pointer bg-muted/30 hover:bg-muted/50 transition-colors px-6 py-8 text-center", contentClassName),
+          disabled,
+          "aria-label": replaceAriaLabel ?? title,
+          className: cn(
+            "w-full h-full flex flex-col items-center justify-center gap-2 cursor-pointer bg-muted/30 hover:bg-muted/50 transition-colors px-6 py-8 text-center focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background",
+            contentClassName
+          ),
           children: [
             (trigger === "icon" || trigger === "both") && /* @__PURE__ */ jsx("div", { className: "text-primary", children: uploadIcon ?? /* @__PURE__ */ jsx(Plus, { className: "h-8 w-8" }) }),
-            (trigger === "button" || trigger === "both") && /* @__PURE__ */ jsx(
-              "span",
-              {
-                role: "button",
-                className: "inline-flex items-center justify-center rounded-md border border-input bg-background px-3 py-1.5 text-xs font-medium text-foreground shadow-sm hover:bg-accent hover:text-accent-foreground",
-                children: buttonLabel
-              }
-            ),
+            (trigger === "button" || trigger === "both") && /* @__PURE__ */ jsx("span", { className: "inline-flex items-center justify-center rounded-md border border-input bg-background px-3 py-1.5 text-xs font-medium text-foreground shadow-sm hover:bg-accent hover:text-accent-foreground", children: buttonLabel }),
             /* @__PURE__ */ jsx("span", { className: cn("text-sm font-medium text-foreground", titleClassName), children: title }),
             subtitle ? /* @__PURE__ */ jsx("span", { className: cn("text-xs text-muted-foreground", subtitleClassName), children: subtitle }) : null
           ]
         }
       ) : /* @__PURE__ */ jsxs(
-        "div",
+        "button",
         {
+          type: "button",
           onClick: handleClick,
-          className: "w-full h-full flex flex-col items-center justify-center cursor-pointer bg-muted/30 hover:bg-muted/50 transition-colors",
+          disabled,
+          "aria-label": replaceAriaLabel ?? title,
+          className: "w-full h-full flex flex-col items-center justify-center cursor-pointer bg-muted/30 hover:bg-muted/50 transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background",
           children: [
-            /* @__PURE__ */ jsx(Image, { className: "h-12 w-12 text-muted-foreground/50 mb-2" }),
-            /* @__PURE__ */ jsx("span", { className: "text-xs text-muted-foreground text-center px-2", children: "Click to upload" })
+            /* @__PURE__ */ jsx(Image, { className: "h-12 w-12 text-muted-foreground/50 mb-2", "aria-hidden": true }),
+            /* @__PURE__ */ jsx("span", { className: "text-xs text-muted-foreground text-center px-2", children: title })
           ]
         }
       )
@@ -10006,20 +10201,42 @@ function ImageInput({
       onChange: handleChange,
       className: "hidden",
       accept,
-      disabled
+      disabled,
+      "aria-hidden": true,
+      tabIndex: -1
     }
   );
   if (!showPreview) return renderFileInput();
   if (previewPosition === "left" || previewPosition === "right") {
-    return /* @__PURE__ */ jsxs("div", { className: cn("flex items-center gap-4", previewPosition === "right" && "flex-row-reverse", containerClassName), children: [
-      renderPreview(),
-      /* @__PURE__ */ jsx("div", { className: "flex-1", children: renderFileInput() })
-    ] });
+    return /* @__PURE__ */ jsxs(
+      "div",
+      {
+        className: cn(
+          "flex items-center gap-4",
+          previewPosition === "right" && "flex-row-reverse",
+          containerClassName
+        ),
+        children: [
+          renderPreview(),
+          /* @__PURE__ */ jsx("div", { className: "flex-1", children: renderFileInput() })
+        ]
+      }
+    );
   }
-  return /* @__PURE__ */ jsxs("div", { className: cn("flex flex-col gap-3", previewPosition === "bottom" && "flex-col-reverse", containerClassName), children: [
-    renderPreview(),
-    renderFileInput()
-  ] });
+  return /* @__PURE__ */ jsxs(
+    "div",
+    {
+      className: cn(
+        "flex flex-col gap-3",
+        previewPosition === "bottom" && "flex-col-reverse",
+        containerClassName
+      ),
+      children: [
+        renderPreview(),
+        renderFileInput()
+      ]
+    }
+  );
 }
 var AVATAR_SIZE_MAP = {
   sm: "size-16",

package/dist/theme.css

@@ -311,23 +311,62 @@ input:autofill {
   display: none;
 }
 
-/* Responsive table actions stay discoverable on touch and tablet layouts.
-   Fine-pointer desktops may keep the quieter hover/focus reveal treatment. */
-.ntable-card-action {
-  opacity: 1;
-}
-
-@media (min-width: 64rem) and (hover: hover) and (pointer: fine) {
-  .ntable-card-action {
-    opacity: 0;
-  }
-
-  .group:hover > .ntable-card-action,
-  .group:focus-within > .ntable-card-action,
-  .ntable-card-action:focus,
-  .ntable-card-action:focus-within {
-    opacity: 1;
-  }
+/* Responsive table actions stay discoverable on touch and tablet layouts.
+   Fine-pointer desktops may keep the quieter hover/focus reveal treatment. */
+.ntable-card-action {
+  opacity: 1;
+}
+
+@media (min-width: 64rem) and (hover: hover) and (pointer: fine) {
+  .ntable-card-action {
+    opacity: 0;
+  }
+
+  .group:hover > .ntable-card-action,
+  .group:focus-within > .ntable-card-action,
+  .ntable-card-action:focus,
+  .ntable-card-action:focus-within {
+    opacity: 1;
+  }
+}
+
+/* ImageInput controls (clear button and replace overlay) stay visible on touch
+   and coarse-pointer devices. Only on fine-pointer desktops do they fall back to
+   a hover/focus reveal. Keyboard focus always restores visibility. The rule
+   below ships in dist/theme.css via scripts/build-css.mjs so the JSX only needs
+   to reference the static class names. */
+.nimage-input-control {
+  opacity: 1;
+}
+
+@media (hover: hover) and (pointer: fine) {
+  .nimage-input-control {
+    opacity: 0;
+  }
+
+  .group\/image:hover .nimage-input-control,
+  .group\/image:focus-within .nimage-input-control,
+  .nimage-input-control:focus,
+  .nimage-input-control:focus-visible {
+    opacity: 1;
+  }
+}
+
+.nimage-input-compact-overlay {
+  opacity: 1;
+}
+
+@media (hover: hover) and (pointer: fine) {
+  .nimage-input-compact-overlay {
+    opacity: 0;
+  }
+
+  .group\/image:hover .nimage-input-compact-overlay,
+  .group\/image:focus-within .nimage-input-compact-overlay,
+  .nimage-input-compact-overlay:focus,
+  .nimage-input-compact-overlay:focus-visible {
+    opacity: 1;
+  }
 }
 
 /* OverlayScrollbars theme used by the <NajmScroll> component — a thin,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "najm-kit",
-  "version": "2.1.48",
+  "version": "2.1.49",
   "license": "MIT",
   "type": "module",
   "description": "Reusable React UI component package for Najm framework",