najm-kit 2.1.47 → 2.1.48

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## 2.1.48 - 2026-08-04
+
+- Keep responsive card row actions visible on phone, tablet, and touch input,
+  while retaining hover and keyboard-focus reveal on fine-pointer desktops.
+- Size table and card loading skeletons from the measured body and active grid,
+  and keep loading borders, radius, color, and shadow aligned with loaded
+  surfaces.
+- Add the exported `NTableCardPagination` and `NTableLoadMorePagination`
+  contracts for paged, complete supplied-data, and explicit server-backed Load
+  more card presentation, including guarded append/retry behavior and accessible
+  loading, result, error, and terminal feedback.

package/README.md

@@ -211,8 +211,74 @@ Notes:
 - The columns the TanStack table receives are already filtered, so the
   settings menu will not list `visible: false` columns.
 
-If you need to inspect or build your own effective column list, the same
-pure helper is exported as `filterResponsiveColumns`. The literal class
-map is also exported as `hiddenBelowClasses`, and
-`resolveHiddenBelowClass(breakpoint)` returns the class for a single
-breakpoint or `undefined` when no breakpoint is set.
+If you need to inspect or build your own effective column list, the same
+pure helper is exported as `filterResponsiveColumns`. The literal class
+map is also exported as `hiddenBelowClasses`, and
+`resolveHiddenBelowClass(breakpoint)` returns the class for a single
+breakpoint or `undefined` when no breakpoint is set.
+
+## NTable responsive cards, loading, and pagination
+
+Responsive row actions are visible by default on phone, tablet, and coarse or
+non-hover pointers. Fine-pointer desktop layouts may reveal them on hover, but
+keyboard focus always reveals the action. Applications still decide which menu
+items exist through `menu`, `onView`, `onEdit`, and `onDelete`; visibility does
+not grant an action or replace server authorization.
+
+When `dynamicHeight` is enabled, table and card loading skeletons measure the
+available body. Table rows use the same header/row geometry as dynamic page
+sizing, while cards measure the active grid columns, card height, and gap. The
+loading surface also follows the loaded `bordered`, design recipe, radius,
+border color, shadow, and `classNames.content`/`classNames.cards` contract.
+
+Use `cardPagination` to choose pagination presentation whenever the effective
+rendered mode is cards:
+
+- `{ mode: "paged" }` (the default) preserves existing pagination.
+- `{ mode: "all" }` renders every row already supplied and hides the footer.
+- `{ mode: "load-more", ... }` renders every supplied row and provides a
+  guarded, keyboard-operable Load more/Retry control with polite loading,
+  appended-result, and end-of-list announcements.
+
+`showPagination={false}` remains an absolute presentation override and hides
+both numbered controls and Load more. In table mode, existing controlled and
+manual server pagination remains unchanged.
+
+```tsx
+import { NTable, type NTableCardPagination } from "najm-kit";
+
+const cardPagination: NTableCardPagination = {
+  mode: "load-more",
+  hasNextPage: query.hasNextPage,
+  loadingMore: query.isFetchingNextPage,
+  loadMoreError: query.isFetchNextPageError
+    ? "The next page could not be loaded."
+    : undefined,
+  onLoadMore: () => query.fetchNextPage(),
+  loadMoreLabel: "Load more",
+  loadingMoreLabel: "Loading more...",
+  retryLabel: "Retry",
+  endLabel: "No more results.",
+};
+
+<NTable
+  data={query.data?.pages.flatMap((page) => page.rows) ?? []}
+  columns={columns}
+  getRowId={(row) => row.id}
+  renderCard={ResultCard}
+  cardPagination={cardPagination}
+/>
+```
+
+The application owns the query, cursor/offset, accumulated pages, cache
+invalidation, search/filter/sort semantics, authorization, and privacy
+projection. Najm Kit never imports React Query, calls an endpoint, invents a
+page size, or treats supplied rows as proof that every database row is loaded.
+Client sorting and filtering cover the rows currently supplied unless the
+application implements matching server-side behavior.
+
+For a responsive screen that uses current-page data in desktop table mode and
+accumulated pages in card mode, keep those two query shapes in the application
+and pass the appropriate `data`. Crossing the `<640px` responsive-card
+breakpoint does not overwrite the user's chosen view, pagination position,
+sorting, filters, expansion, or row selection.

package/dist/index.d.ts

@@ -2671,6 +2671,39 @@ type StepSubmitResult = {
 };
 declare function useFormSubmission({ steps, schema, defaultValues, onSubmit, currentStep, isLastStep, handleNext, markStepCompleted, reset, }: UseFormSubmissionOptions): FormSubmissionState;
 
+interface NTableLoadMorePagination {
+    /** Render the supplied rows as one card list with an explicit continuation control. */
+    mode: "load-more";
+    /** Whether the owning application has another server page available. */
+    hasNextPage: boolean;
+    /** True while the owning application is appending the next page. */
+    loadingMore?: boolean;
+    /** A controlled append error. Existing rows remain rendered and the control becomes Retry. */
+    loadMoreError?: ReactNode;
+    /** Fetch exactly one additional page. Najm Kit never constructs or owns the request. */
+    onLoadMore: () => unknown | Promise<unknown>;
+    loadMoreLabel?: string;
+    loadingMoreLabel?: string;
+    retryLabel?: string;
+    endLabel?: string;
+    loadMoreErrorLabel?: string;
+    /** Localize the polite announcement made after appended rows arrive. */
+    itemsLoadedLabel?: (count: number) => string;
+}
+/**
+ * Presentation policy used while NTable is actually rendering cards.
+ *
+ * `paged` preserves the existing page controls. `all` renders every supplied
+ * row without a footer. `load-more` also renders every supplied row and adds a
+ * guarded, accessible continuation control. Applications remain responsible
+ * for fetching, accumulating, filtering, sorting, authorization, and privacy.
+ */
+type NTableCardPagination = {
+    mode?: "paged";
+} | {
+    mode: "all";
+} | NTableLoadMorePagination;
+
 interface NTableClassNames {
     root?: string;
     header?: string;
@@ -2742,7 +2775,14 @@ interface TableState {
     addButtonText: string;
     pageSizeOptions: number[];
     calculatedPageSize: number;
+    skeletonRowCount: number;
     maxHeight: number | null;
+    bodyWidth: number;
+    bodyHeight: number;
+    tableHeaderHeight: number;
+    cardColumnCount: number;
+    cardRowHeight: number;
+    cardGap: number;
     syncWithProps: (updates: Partial<TableState>) => void;
     jsonValue: unknown;
     jsonColors: any;
@@ -2782,6 +2822,8 @@ interface TableState {
     hasSyncedSortingFromProps: boolean;
     responsiveCards: boolean;
     isMobile: boolean;
+    effectiveViewMode: ViewMode;
+    cardPagination: NTableCardPagination;
     isEmpty: boolean | undefined;
     isFilteredEmpty: boolean;
     renderFilteredEmpty: (() => React.ReactNode) | null;
@@ -2858,7 +2900,14 @@ declare const createTableStore: () => {
         addButtonText: () => string;
         pageSizeOptions: () => number[];
         calculatedPageSize: () => number;
+        skeletonRowCount: () => number;
         maxHeight: () => number;
+        bodyWidth: () => number;
+        bodyHeight: () => number;
+        tableHeaderHeight: () => number;
+        cardColumnCount: () => number;
+        cardRowHeight: () => number;
+        cardGap: () => number;
         syncWithProps: () => (updates: Partial<TableState>) => void;
         jsonValue: () => unknown;
         jsonColors: () => any;
@@ -2898,6 +2947,8 @@ declare const createTableStore: () => {
         hasSyncedSortingFromProps: () => boolean;
         responsiveCards: () => boolean;
         isMobile: () => boolean;
+        effectiveViewMode: () => ViewMode;
+        cardPagination: () => NTableCardPagination;
         isEmpty: () => boolean;
         isFilteredEmpty: () => boolean;
         renderFilteredEmpty: () => () => React.ReactNode;
@@ -3030,6 +3081,8 @@ interface NTableProps<T = any, M extends ViewMode = ViewMode> {
         pageIndex: number;
         pageSize: number;
     }) => void;
+    /** Pagination presentation used whenever NTable is actually rendering cards. */
+    cardPagination?: NTableCardPagination;
     rowSelection?: RowSelectionState;
     defaultRowSelection?: RowSelectionState;
     onRowSelectionChange?: (state: RowSelectionState) => void;
@@ -3125,8 +3178,9 @@ interface NDataCardShellProps {
     openRowMenu?: ((e: React__default.MouseEvent, row: any) => void) | null;
     menuButton?: boolean;
     bordered?: boolean;
+    borderColor?: string;
 }
-declare function NDataCardShell({ row, onClick, onContextMenu, actions, children, className, showCheckbox, selectedRowId, openRowMenu, menuButton, bordered }: NDataCardShellProps): react_jsx_runtime.JSX.Element;
+declare function NDataCardShell({ row, onClick, onContextMenu, actions, children, className, showCheckbox, selectedRowId, openRowMenu, menuButton, bordered, borderColor }: NDataCardShellProps): react_jsx_runtime.JSX.Element;
 
 interface NTableCardRootProps extends Omit<React__default.HTMLAttributes<HTMLDivElement>, "onClick" | "onContextMenu"> {
     card: {
@@ -3264,7 +3318,14 @@ declare const TableStoreContext: React$1.Context<{
         addButtonText: () => string;
         pageSizeOptions: () => number[];
         calculatedPageSize: () => number;
+        skeletonRowCount: () => number;
         maxHeight: () => number;
+        bodyWidth: () => number;
+        bodyHeight: () => number;
+        tableHeaderHeight: () => number;
+        cardColumnCount: () => number;
+        cardRowHeight: () => number;
+        cardGap: () => number;
         syncWithProps: () => (updates: Partial<TableState>) => void;
         jsonValue: () => unknown;
         jsonColors: () => any;
@@ -3304,6 +3365,8 @@ declare const TableStoreContext: React$1.Context<{
         hasSyncedSortingFromProps: () => boolean;
         responsiveCards: () => boolean;
         isMobile: () => boolean;
+        effectiveViewMode: () => ViewMode;
+        cardPagination: () => NTableCardPagination;
         isEmpty: () => boolean;
         isFilteredEmpty: () => boolean;
         renderFilteredEmpty: () => () => React.ReactNode;
@@ -3384,7 +3447,14 @@ declare function useStoreSync(props: any): {
         addButtonText: () => string;
         pageSizeOptions: () => number[];
         calculatedPageSize: () => number;
+        skeletonRowCount: () => number;
         maxHeight: () => number;
+        bodyWidth: () => number;
+        bodyHeight: () => number;
+        tableHeaderHeight: () => number;
+        cardColumnCount: () => number;
+        cardRowHeight: () => number;
+        cardGap: () => number;
         syncWithProps: () => (updates: Partial<TableState>) => void;
         jsonValue: () => unknown;
         jsonColors: () => any;
@@ -3424,6 +3494,8 @@ declare function useStoreSync(props: any): {
         hasSyncedSortingFromProps: () => boolean;
         responsiveCards: () => boolean;
         isMobile: () => boolean;
+        effectiveViewMode: () => ViewMode;
+        cardPagination: () => NTableCardPagination;
         isEmpty: () => boolean;
         isFilteredEmpty: () => boolean;
         renderFilteredEmpty: () => () => React__default.ReactNode;
@@ -3436,8 +3508,8 @@ declare function useStoreSync(props: any): {
         hasSyncedExpandedFromProps: () => boolean;
     };
 };
-declare function useDynamicPageSize(containerRef: React__default.RefObject<HTMLDivElement | null>): void;
-declare function useTable(): {
+declare function useDynamicPageSize(containerRef: React__default.RefObject<HTMLDivElement | null>, effectiveViewMode?: TableState["viewMode"]): void;
+declare function useTable(effectiveViewModeOverride?: TableState["viewMode"]): {
     table: _tanstack_table_core.Table<unknown>;
     finalColumns: _tanstack_table_core.ColumnDef<unknown, unknown>[];
     sorting: SortingState;
@@ -3833,4 +3905,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, NTableCardRoot, type NTableCardRootProps, NTableCards, type NTableClassNames, type NTableColumnBreakpoint, type NTableColumnDef, type NTableColumnMeta, NTableContent, NTableHeader, 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 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

@@ -7274,7 +7274,7 @@ function NSkeleton({ className, ...props }) {
   return /* @__PURE__ */ jsx(
     "div",
     {
-      className: cn("animate-pulse rounded-md bg-accent", className),
+      className: cn("animate-pulse rounded-md bg-accent motion-reduce:animate-none", className),
       "aria-hidden": "true",
       ...props
     }
@@ -11629,7 +11629,14 @@ var createTableStore = () => {
     addButtonText: "",
     pageSizeOptions: [10, 20, 30, 40, 50],
     calculatedPageSize: 10,
+    skeletonRowCount: 6,
     maxHeight: null,
+    bodyWidth: 0,
+    bodyHeight: 0,
+    tableHeaderHeight: 48,
+    cardColumnCount: 1,
+    cardRowHeight: 0,
+    cardGap: 12,
     // JSON mode
     jsonValue: void 0,
     jsonColors: null,
@@ -11699,6 +11706,8 @@ var createTableStore = () => {
     // Responsive cards
     responsiveCards: true,
     isMobile: false,
+    effectiveViewMode: "table",
+    cardPagination: { mode: "paged" },
     // Empty states
     isEmpty: void 0,
     isFilteredEmpty: false,
@@ -11774,6 +11783,8 @@ function filterResponsiveColumns(columns) {
 // src/components/table/hooks.ts
 var ROW_HEIGHT = 56;
 var DEFAULT_TABLE_HEADER_HEIGHT = 48;
+var DEFAULT_CARD_HEIGHT = 176;
+var DEFAULT_CARD_GAP = 12;
 var ROOT_SECTION_GAP_COUNT = 2;
 function useStoreSync(props) {
   const storeRef = useRef(null);
@@ -11854,23 +11865,43 @@ function calculateDynamicPageSize(input) {
   if (availableRowsHeight <= 0) return 1;
   return Math.max(1, Math.floor(availableRowsHeight / rowHeight));
 }
-function useDynamicPageSize(containerRef) {
+function calculateCardSkeletonCount(input) {
+  const columns = Math.max(1, Math.floor(input.columnCount));
+  const cardHeight = Math.max(1, input.cardHeight ?? DEFAULT_CARD_HEIGHT);
+  const gap = Math.max(0, input.gap ?? DEFAULT_CARD_GAP);
+  if (input.bodyHeight <= 0) return columns;
+  const rows = Math.max(1, Math.ceil((input.bodyHeight + gap) / (cardHeight + gap)));
+  return rows * columns;
+}
+function fallbackCardColumns(width) {
+  if (width >= 1280) return 4;
+  if (width >= 1024) return 3;
+  if (width >= 640) return 2;
+  return 1;
+}
+function useDynamicPageSize(containerRef, effectiveViewMode) {
   const dynamicHeight = useTableStore.use.dynamicHeight();
-  const viewMode = useTableStore.use.viewMode();
+  const viewMode = useTableStore.use.effectiveViewMode();
   const manualPagination = useTableStore.use.manualPagination();
   const isLoading = useTableStore.use.isLoading();
   const error = useTableStore.use.error();
   const hasNoData = useTableStore.use.hasNoData();
   const isFilteredEmpty = useTableStore.use.isFilteredEmpty();
   const syncWithProps = useTableStore.use.syncWithProps();
+  const lastMeasurementRef = useRef("");
   useLayoutEffect(() => {
-    if (!dynamicHeight || !containerRef.current || viewMode !== "table" || manualPagination) return;
+    if (!dynamicHeight || !containerRef.current) return;
     const calculatePageSize = () => {
       const container2 = containerRef.current;
       if (!container2) return;
       const bodyEl = container2.querySelector("[data-ntable-body]");
       const tableHeaderEl = container2.querySelector("[data-ntable-table-header]");
+      const loadingHeaderEl = container2.querySelector("[data-ntable-loading-header]");
+      const cardsGridEl = container2.querySelector(
+        "[data-ntable-loading-cards-grid], [data-ntable-cards-grid]"
+      );
       let bodyHeight = bodyEl?.clientHeight ?? 0;
+      const bodyWidth = bodyEl?.clientWidth ?? container2.clientWidth ?? 0;
       if (!bodyHeight) {
         const rootHeight = container2.clientHeight;
         const headerHeight = container2.querySelector("[data-ntable-header]")?.offsetHeight ?? 0;
@@ -11879,10 +11910,36 @@ function useDynamicPageSize(containerRef) {
         const gap = Number.parseFloat(rootStyles.rowGap || rootStyles.gap || "0") || 0;
         bodyHeight = rootHeight - headerHeight - paginationHeight - gap * ROOT_SECTION_GAP_COUNT;
       }
+      if (loadingHeaderEl && bodyEl) {
+        const bodyStyles = window.getComputedStyle(bodyEl);
+        const bodyGap = Number.parseFloat(bodyStyles.rowGap || bodyStyles.gap || "0") || 0;
+        bodyHeight = Math.max(0, bodyHeight - loadingHeaderEl.offsetHeight - bodyGap);
+      }
       const tableHeaderHeight = tableHeaderEl?.offsetHeight ?? DEFAULT_TABLE_HEADER_HEIGHT;
       const newPageSize = calculateDynamicPageSize({ bodyHeight, tableHeaderHeight });
       const calculatedMaxHeight = tableHeaderHeight + newPageSize * ROW_HEIGHT;
-      syncWithProps({ calculatedPageSize: newPageSize, maxHeight: calculatedMaxHeight });
+      const gridStyles = cardsGridEl ? window.getComputedStyle(cardsGridEl) : null;
+      const gridTemplateColumns = gridStyles?.gridTemplateColumns;
+      const gridColumns = gridTemplateColumns && gridTemplateColumns !== "none" ? gridTemplateColumns.split(" ").filter(Boolean).length : 0;
+      const cardColumnCount = gridColumns || fallbackCardColumns(bodyWidth);
+      const cardGap = Number.parseFloat(gridStyles?.rowGap || gridStyles?.gap || "") || DEFAULT_CARD_GAP;
+      const firstCard = cardsGridEl?.querySelector("[data-ntable-loading-card], [data-row]");
+      const cardRowHeight = firstCard?.offsetHeight || firstCard?.getBoundingClientRect().height || DEFAULT_CARD_HEIGHT;
+      const updates = {
+        ...!manualPagination ? { calculatedPageSize: newPageSize, maxHeight: calculatedMaxHeight } : {},
+        skeletonRowCount: newPageSize,
+        bodyWidth,
+        bodyHeight,
+        tableHeaderHeight,
+        cardColumnCount,
+        cardRowHeight,
+        cardGap
+      };
+      const fingerprint = JSON.stringify(updates);
+      if (fingerprint !== lastMeasurementRef.current) {
+        lastMeasurementRef.current = fingerprint;
+        syncWithProps(updates);
+      }
     };
     calculatePageSize();
     const resizeObserver = new ResizeObserver(calculatePageSize);
@@ -11891,11 +11948,14 @@ function useDynamicPageSize(containerRef) {
     container.querySelectorAll(
       "[data-ntable-header], [data-ntable-body], [data-ntable-pagination], [data-ntable-table-header]"
     ).forEach((el) => resizeObserver.observe(el));
+    container.querySelectorAll(
+      "[data-ntable-loading-header], [data-ntable-loading-cards-grid], [data-ntable-loading-card], [data-ntable-cards-grid]"
+    ).forEach((el) => resizeObserver.observe(el));
     if (container.parentElement) resizeObserver.observe(container.parentElement);
     return () => resizeObserver.disconnect();
-  }, [dynamicHeight, viewMode, containerRef, syncWithProps, manualPagination, isLoading, error, hasNoData, isFilteredEmpty]);
+  }, [dynamicHeight, effectiveViewMode, viewMode, containerRef, syncWithProps, manualPagination, isLoading, error, hasNoData, isFilteredEmpty]);
 }
-function useTable() {
+function useTable(effectiveViewModeOverride) {
   const [sorting, setSorting] = useState([]);
   const [columnFilters, setColumnFilters] = useState([]);
   const [columnVisibility, setColumnVisibility] = useState({});
@@ -11912,6 +11972,8 @@ function useTable() {
   const CardComponent = useTableStore.use.CardComponent();
   const dynamicHeight = useTableStore.use.dynamicHeight();
   const viewMode = useTableStore.use.viewMode();
+  const effectiveViewMode = useTableStore.use.effectiveViewMode();
+  const cardPagination = useTableStore.use.cardPagination();
   const calculatedPageSize = useTableStore.use.calculatedPageSize();
   const syncWithProps = useTableStore.use.syncWithProps();
   const onStateChange = useTableStore.use.onStateChange();
@@ -12002,6 +12064,8 @@ function useTable() {
     notifyStateChange({ sorting, columnFilters, columnVisibility, rowSelection: storeRowSelection, globalFilter });
   }, [storePagination, storeRowSelection, setPagination, sorting, columnFilters, columnVisibility, globalFilter, notifyStateChange]);
   const hasExpansion = Boolean(renderSubRow || userGetRowCanExpand);
+  const renderedMode = effectiveViewModeOverride ?? effectiveViewMode ?? viewMode;
+  const renderAllSuppliedRows = renderedMode === "cards" && cardPagination.mode !== "paged";
   const tableConfig = {
     data,
     columns: finalColumns,
@@ -12018,7 +12082,7 @@ function useTable() {
     getPaginationRowModel: getPaginationRowModel(),
     getSortedRowModel: getSortedRowModel(),
     getExpandedRowModel: getExpandedRowModel(),
-    manualPagination,
+    manualPagination: manualPagination || renderAllSuppliedRows,
     pageCount,
     rowCount
   };
@@ -12032,9 +12096,11 @@ function useTable() {
   }, [table]);
   useLayoutEffect(() => {
     if (manualPagination) return;
-    if (dynamicHeight && viewMode === "table") table.setPageSize(calculatedPageSize);
-    if (viewMode === "cards") table.setPageSize(data.length || 9999);
-  }, [calculatedPageSize, dynamicHeight, viewMode, table, data.length, manualPagination]);
+    if (dynamicHeight && renderedMode === "table") table.setPageSize(calculatedPageSize);
+    if (viewMode === "cards" && cardPagination.mode === "paged") {
+      table.setPageSize(data.length || 9999);
+    }
+  }, [calculatedPageSize, dynamicHeight, renderedMode, viewMode, cardPagination.mode, table, data.length, manualPagination]);
   return { table, finalColumns, sorting, setSorting, columnFilters, setColumnFilters, columnVisibility, setColumnVisibility, globalFilter, setGlobalFilter };
 }
 function useTableKeyboard(options = {}) {
@@ -12128,6 +12194,26 @@ function resolveTableColor(value, fallback) {
   }
   return color;
 }
+
+// src/components/table/tableSurface.ts
+function useTableSurfaceAppearance(bordered, borderColor) {
+  const recipe = useNajmComponentStyle("table");
+  const recipeRadius = resolveRadiusValue(recipe?.radius);
+  const resolvedBorderColor = resolveTableColor(borderColor, DEFAULT_TABLE_BORDER_COLOR);
+  const style = recipeRadius || bordered !== false && (recipe?.borderWidth || borderColor) ? {
+    ...recipeRadius ? { borderRadius: recipeRadius } : {},
+    ...bordered !== false && recipe?.borderWidth ? { borderWidth: recipe.borderWidth } : {},
+    ...bordered !== false && borderColor ? { borderColor: resolvedBorderColor } : {}
+  } : void 0;
+  return {
+    bordered,
+    style,
+    className: cn(
+      "bg-card",
+      bordered === true ? surfaceBorderClasses(true) : "border-0 shadow-sm"
+    )
+  };
+}
 var ROW_CONTEXT_HANDLED = "__ntableRowContextHandled";
 function EditableCell({ cell, onCellEdit }) {
   const columnDef = cell.column.columnDef;
@@ -12182,12 +12268,6 @@ function EditableCell({ cell, onCellEdit }) {
   ] });
 }
 function NTableContent({ effectiveMode }) {
-  const recipe = useNajmComponentStyle("table");
-  const recipeRadius = resolveRadiusValue(recipe?.radius);
-  const recipeStyle = recipeRadius || recipe?.borderWidth ? {
-    ...recipeRadius ? { borderRadius: recipeRadius } : {},
-    ...recipe?.borderWidth ? { borderWidth: recipe.borderWidth } : {}
-  } : void 0;
   const table = useTableStore.use.table();
   const storeIsTableView = useTableStore.use.isTableView();
   const columns = useTableStore.use.columns();
@@ -12204,10 +12284,6 @@ function NTableContent({ effectiveMode }) {
     backgroundColor: resolvedHeaderColor,
     color: resolvedHeaderTextColor
   };
-  const contentStyle = recipeStyle || tableBorderColor ? {
-    ...recipeStyle ?? {},
-    ...tableBorderColor ? { borderColor: resolvedBorderColor } : {}
-  } : void 0;
   const rowBorderStyle = tableBorderColor ? { borderColor: resolvedBorderColor } : void 0;
   const onRowClick = useTableStore.use.onRowClick();
   const onRowContextMenu = useTableStore.use.onRowContextMenu();
@@ -12220,6 +12296,7 @@ function NTableContent({ effectiveMode }) {
   const showContent = useTableStore.use.showContent();
   const classNames = useTableStore.use.classNames();
   const bordered = useTableStore.use.bordered();
+  const surface = useTableSurfaceAppearance(bordered, tableBorderColor);
   const showCheckbox = useTableStore.use.showCheckbox();
   const selectedRowId = useTableStore.use.selectedRowId();
   const renderSubRow = useTableStore.use.renderSubRow();
@@ -12248,11 +12325,11 @@ function NTableContent({ effectiveMode }) {
       axis: "both",
       "data-bordered": bordered === false ? "false" : bordered ? "true" : void 0,
       className: cn(
-        "min-h-0 flex-1 overflow-hidden rounded-md bg-card",
-        bordered === true ? surfaceBorderClasses(true) : "shadow-sm",
+        "min-h-0 flex-1 overflow-hidden rounded-md",
+        surface.className,
         classNames?.content
       ),
-      style: contentStyle,
+      style: surface.style,
       onContextMenu: handleBackgroundContextMenu,
       children: /* @__PURE__ */ jsxs(Table, { children: [
         /* @__PURE__ */ jsx(TableHeader, { "data-ntable-table-header": true, className: cn("bg-card sticky top-0 z-10", headerClassName, bordered === true && "[&_tr]:border-border", classNames?.tableHeader), children: table.getHeaderGroups().map((hg) => /* @__PURE__ */ jsxs(TableRow, { style: rowBorderStyle, className: cn("hover:bg-transparent", bordered === true && "border-border"), children: [
@@ -12361,13 +12438,8 @@ function NTableContent({ effectiveMode }) {
     }
   );
 }
-function NDataCardShell({ row, onClick, onContextMenu, actions, children, className, showCheckbox = true, selectedRowId, openRowMenu, menuButton, bordered }) {
-  const recipe = useNajmComponentStyle("table");
-  const recipeRadius = resolveRadiusValue(recipe?.radius);
-  const recipeStyle = recipeRadius || recipe?.borderWidth ? {
-    ...recipeRadius ? { borderRadius: recipeRadius } : {},
-    ...recipe?.borderWidth ? { borderWidth: recipe.borderWidth } : {}
-  } : void 0;
+function NDataCardShell({ row, onClick, onContextMenu, actions, children, className, showCheckbox = true, selectedRowId, openRowMenu, menuButton, bordered, borderColor }) {
+  const surface = useTableSurfaceAppearance(bordered, borderColor);
   const canExpand = row.getCanExpand();
   const isExpanded = canExpand && row.getIsExpanded();
   const isSelected = row.getIsSelected();
@@ -12382,10 +12454,10 @@ function NDataCardShell({ row, onClick, onContextMenu, actions, children, classN
       "data-bordered": bordered === false ? "false" : bordered ? "true" : void 0,
       onClick,
       onContextMenu,
-      style: recipeStyle,
+      style: surface.style,
       className: cn(
         "relative group w-full rounded-lg bg-card text-card-foreground overflow-hidden",
-        surfaceBorderClasses(bordered),
+        surface.className,
         isActive && (bordered ? "border-primary" : "ring-2 ring-primary ring-offset-1 ring-offset-background"),
         onClick && "cursor-pointer",
         className
@@ -12402,7 +12474,7 @@ function NDataCardShell({ row, onClick, onContextMenu, actions, children, classN
             className: "h-4 w-4"
           }
         ) }),
-        useMenuButton ? /* @__PURE__ */ jsx("div", { className: "absolute top-2 right-2 h-auto z-10 opacity-0 transition-opacity duration-200 group-hover:opacity-100 focus-within:opacity-100", children: /* @__PURE__ */ jsx(
+        useMenuButton ? /* @__PURE__ */ jsx("div", { "data-ntable-card-action": true, className: "ntable-card-action absolute end-2 top-2 z-10 h-auto transition-opacity duration-200", children: /* @__PURE__ */ jsx(
           "button",
           {
             type: "button",
@@ -12411,10 +12483,10 @@ function NDataCardShell({ row, onClick, onContextMenu, actions, children, classN
               e.stopPropagation();
               openRowMenu(e, row.original);
             },
-            className: "flex h-7 w-7 p-0 rounded-md cursor-pointer justify-center items-center text-muted-foreground transition-colors hover:bg-muted/50 hover:text-foreground",
+            className: "flex h-7 w-7 cursor-pointer items-center justify-center rounded-md p-0 text-muted-foreground transition-colors hover:bg-muted/50 hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2",
             children: /* @__PURE__ */ jsx(MoreVertical, { className: "h-4 w-4" })
           }
-        ) }) : actions && (actions.onView || actions.onEdit || actions.onDelete) ? /* @__PURE__ */ jsx("div", { className: "absolute top-2 right-2 h-auto z-10 opacity-0 transition-opacity duration-200 group-hover:opacity-100 focus-within:opacity-100", children: /* @__PURE__ */ jsxs(DropdownMenu, { children: [
+        ) }) : actions && (actions.onView || actions.onEdit || actions.onDelete) ? /* @__PURE__ */ jsx("div", { "data-ntable-card-action": true, className: "ntable-card-action absolute end-2 top-2 z-10 h-auto transition-opacity duration-200", children: /* @__PURE__ */ jsxs(DropdownMenu, { children: [
           /* @__PURE__ */ jsx(DropdownMenuTrigger, { asChild: true, children: /* @__PURE__ */ jsx(
             "div",
             {
@@ -12519,6 +12591,7 @@ function NTableCards({ effectiveMode }) {
   const showContent = useTableStore.use.showContent();
   const classNames = useTableStore.use.classNames();
   const bordered = useTableStore.use.bordered();
+  const borderColor = useTableStore.use.borderColor();
   const renderSubRow = useTableStore.use.renderSubRow();
   const userGetRowCanExpand = useTableStore.use.getRowCanExpand();
   const handleContainerContextMenu = useCallback((e) => {
@@ -12556,7 +12629,7 @@ function NTableCards({ effectiveMode }) {
   const defaultContainerClass = "grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4 gap-3";
   const containerClass = classNames?.cards ?? defaultContainerClass;
   const actions = !menuButton && (onView || onEdit || onDelete) ? { onView, onEdit, onDelete } : void 0;
-  return /* @__PURE__ */ jsx(NajmScroll, { axis: "y", className: "min-h-0 flex-1 overflow-hidden", children: /* @__PURE__ */ jsx("div", { className: cn(containerClass), onContextMenu: handleContainerContextMenu, children: rows.map((row) => {
+  return /* @__PURE__ */ jsx(NajmScroll, { axis: "y", className: "min-h-0 flex-1 overflow-hidden", children: /* @__PURE__ */ jsx("div", { "data-ntable-cards-grid": true, className: cn(containerClass), onContextMenu: handleContainerContextMenu, children: rows.map((row) => {
     const noShell = Boolean(row.original?.__smsNoShell);
     const hasExpansion = Boolean(renderSubRow || userGetRowCanExpand);
     const canExpand = hasExpansion && row.getCanExpand();
@@ -12586,7 +12659,8 @@ function NTableCards({ effectiveMode }) {
                   e.stopPropagation();
                   openRowMenu(e, row.original);
                 },
-                className: "absolute top-2 right-2 z-10 flex h-7 w-7 cursor-pointer items-center justify-center rounded-md p-0 text-muted-foreground opacity-0 transition-all duration-200 hover:bg-muted/50 hover:text-foreground group-hover:opacity-100 focus:opacity-100 focus-visible:opacity-100",
+                "data-ntable-card-action": true,
+                className: "ntable-card-action absolute end-2 top-2 z-10 flex h-7 w-7 cursor-pointer items-center justify-center rounded-md p-0 text-muted-foreground transition-all duration-200 hover:bg-muted/50 hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2",
                 children: /* @__PURE__ */ jsx(MoreVertical, { className: "h-4 w-4" })
               }
             ),
@@ -12622,6 +12696,7 @@ function NTableCards({ effectiveMode }) {
         openRowMenu,
         menuButton,
         bordered,
+        borderColor,
         className: rowClassName || void 0,
         children: /* @__PURE__ */ jsx(
           CardComponent,
@@ -12639,13 +12714,108 @@ function NTableCards({ effectiveMode }) {
     );
   }) }) });
 }
+function CardLoadMorePagination({
+  config,
+  rowCount,
+  bordered,
+  className
+}) {
+  const [internalPending, setInternalPending] = React__default.useState(false);
+  const [internalError, setInternalError] = React__default.useState(null);
+  const [announcement, setAnnouncement] = React__default.useState("");
+  const buttonRef = React__default.useRef(null);
+  const pendingRef = React__default.useRef(false);
+  const restoreFocusRef = React__default.useRef(false);
+  const previousRowCountRef = React__default.useRef(rowCount);
+  const errorId = React__default.useId();
+  const pending = Boolean(config.loadingMore || internalPending);
+  const error = config.loadMoreError ?? internalError;
+  React__default.useEffect(() => {
+    const previous = previousRowCountRef.current;
+    if (rowCount > previous) {
+      const appended = rowCount - previous;
+      setAnnouncement(
+        config.itemsLoadedLabel?.(appended) ?? `${appended} more ${appended === 1 ? "item" : "items"} loaded.`
+      );
+    }
+    previousRowCountRef.current = rowCount;
+  }, [config.itemsLoadedLabel, rowCount]);
+  React__default.useEffect(() => {
+    if (pending || !restoreFocusRef.current) return;
+    restoreFocusRef.current = false;
+    const frame = requestAnimationFrame(() => buttonRef.current?.focus());
+    return () => cancelAnimationFrame(frame);
+  }, [pending]);
+  const loadMore = async () => {
+    if (pendingRef.current || pending || !config.hasNextPage && !error) return;
+    pendingRef.current = true;
+    restoreFocusRef.current = document.activeElement === buttonRef.current;
+    setInternalPending(true);
+    setInternalError(null);
+    const loadingAnnouncement = config.loadingMoreLabel ?? "Loading more items...";
+    setAnnouncement(loadingAnnouncement);
+    try {
+      await config.onLoadMore();
+    } catch {
+      setInternalError(config.loadMoreErrorLabel ?? "Couldn't load more items.");
+      setAnnouncement("");
+    } finally {
+      pendingRef.current = false;
+      setInternalPending(false);
+      setAnnouncement((current) => current === loadingAnnouncement ? "" : current);
+    }
+  };
+  if (!config.hasNextPage && !pending && !error) {
+    return /* @__PURE__ */ jsx(
+      "div",
+      {
+        "data-ntable-load-more-end": true,
+        role: "status",
+        "aria-live": "polite",
+        className: cn("py-2 text-center text-sm text-muted-foreground", className),
+        children: config.endLabel ?? "No more items."
+      }
+    );
+  }
+  return /* @__PURE__ */ jsxs(
+    "div",
+    {
+      "data-ntable-load-more": true,
+      className: cn("flex min-w-0 flex-col items-center gap-2 py-2", className),
+      children: [
+        error ? /* @__PURE__ */ jsx("div", { id: errorId, role: "alert", className: "text-center text-sm text-destructive", children: error === true ? config.loadMoreErrorLabel ?? "Couldn't load more items." : error }) : null,
+        /* @__PURE__ */ jsxs(
+          Button,
+          {
+            ref: buttonRef,
+            type: "button",
+            bordered,
+            variant: "outline",
+            autoLoading: false,
+            disabled: pending,
+            "aria-describedby": error ? errorId : void 0,
+            "aria-busy": pending ? "true" : void 0,
+            onClick: loadMore,
+            children: [
+              pending ? /* @__PURE__ */ jsx(Loader2, { "aria-hidden": "true", className: "h-4 w-4 animate-spin motion-reduce:animate-none" }) : null,
+              pending ? config.loadingMoreLabel ?? "Loading more..." : error ? config.retryLabel ?? "Retry" : config.loadMoreLabel ?? "Load more"
+            ]
+          }
+        ),
+        /* @__PURE__ */ jsx("span", { className: "sr-only", role: "status", "aria-live": "polite", "aria-atomic": "true", children: announcement })
+      ]
+    }
+  );
+}
 function NTablePagination() {
   const table = useTableStore.use.table();
   const showPagination = useTableStore.use.showPagination();
   const showContent = useTableStore.use.showContent();
   const pageSizeOptions = useTableStore.use.pageSizeOptions();
   const classNames = useTableStore.use.classNames();
-  const viewMode = useTableStore.use.viewMode();
+  const effectiveViewMode = useTableStore.use.effectiveViewMode();
+  const cardPagination = useTableStore.use.cardPagination();
+  const data = useTableStore.use.data();
   const pagination = useTableStore.use.pagination();
   const manualPagination = useTableStore.use.manualPagination();
   const pageCount = useTableStore.use.pageCount();
@@ -12653,7 +12823,19 @@ function NTablePagination() {
   const setPagination = useTableStore.use.setPagination();
   const isPaginationControlled = useTableStore.use.isPaginationControlled();
   const bordered = useTableStore.use.bordered();
-  if (!table || !showContent || !showPagination || viewMode === "json" || viewMode === "files") return null;
+  if (!table || !showContent || !showPagination || effectiveViewMode === "json" || effectiveViewMode === "files") return null;
+  if (effectiveViewMode === "cards" && cardPagination.mode === "all") return null;
+  if (effectiveViewMode === "cards" && cardPagination.mode === "load-more") {
+    return /* @__PURE__ */ jsx(
+      CardLoadMorePagination,
+      {
+        config: cardPagination,
+        rowCount: data.length,
+        bordered,
+        className: classNames?.pagination
+      }
+    );
+  }
   const filteredRows = table.getFilteredRowModel().rows;
   const selectedRows = table.getFilteredSelectedRowModel().rows;
   const { pageIndex, pageSize } = table.getState().pagination;
@@ -13091,7 +13273,7 @@ function NTableHeaderSkeleton() {
     }
   );
 }
-function NTableLoadingSkeleton({ rows = DEFAULT_ROWS2 }) {
+function NTableLoadingSkeleton({ rows }) {
   const rawColumns = useTableStore.use.columns();
   const responsiveColumns = React__default.useMemo(() => filterResponsiveColumns(rawColumns), [rawColumns]);
   const columns = responsiveColumns;
@@ -13099,24 +13281,34 @@ function NTableLoadingSkeleton({ rows = DEFAULT_ROWS2 }) {
   const headerClassName = useTableStore.use.headerClassName();
   const classNames = useTableStore.use.classNames();
   const dynamicHeight = useTableStore.use.dynamicHeight();
+  const bordered = useTableStore.use.bordered();
+  const borderColor = useTableStore.use.borderColor();
+  const surface = useTableSurfaceAppearance(bordered, borderColor);
+  const bodyHeight = useTableStore.use.bodyHeight();
+  const skeletonRowCount = useTableStore.use.skeletonRowCount();
   const renderSubRow = useTableStore.use.renderSubRow();
   const userGetRowCanExpand = useTableStore.use.getRowCanExpand();
   const hasExpansion = Boolean(renderSubRow || userGetRowCanExpand);
   const loadingText = useTableStore.use.loadingText();
+  const rowCount = rows ?? (dynamicHeight && bodyHeight > 0 ? skeletonRowCount : DEFAULT_ROWS2);
   const renderHeaderLabel = (header) => typeof header === "string" ? header : null;
   return /* @__PURE__ */ jsxs("div", { className: "flex min-h-0 flex-1 flex-col gap-2", children: [
     /* @__PURE__ */ jsx(NTableHeaderSkeleton, {}),
     /* @__PURE__ */ jsxs(
-      Card,
+      "div",
       {
         "data-testid": "ntable-loading-skeleton",
+        "data-ntable-loading-row-count": rowCount,
+        "data-bordered": surface.bordered === false ? "false" : surface.bordered ? "true" : void 0,
         "aria-busy": "true",
         "aria-label": loadingText,
-        className: cn("rounded-md p-0 border", dynamicHeight ? "overflow-hidden" : "najm-overlay-scroll", classNames?.content),
+        role: "status",
+        style: surface.style,
+        className: cn("min-h-0 flex-1 rounded-md p-0", surface.className, dynamicHeight ? "overflow-hidden" : "najm-overlay-scroll", classNames?.content),
         children: [
           /* @__PURE__ */ jsx("span", { className: "sr-only", children: loadingText }),
-          /* @__PURE__ */ jsx("div", { className: dynamicHeight ? "najm-overlay-scroll" : void 0, children: /* @__PURE__ */ jsxs(Table, { children: [
-            /* @__PURE__ */ jsx(TableHeader, { className: cn(headerClassName, dynamicHeight && "sticky top-0 z-10", classNames?.tableHeader), children: /* @__PURE__ */ jsxs(TableRow, { className: "hover:bg-muted/30", children: [
+          /* @__PURE__ */ jsx("div", { "aria-hidden": "true", className: dynamicHeight ? "najm-overlay-scroll h-full" : void 0, children: /* @__PURE__ */ jsxs(Table, { children: [
+            /* @__PURE__ */ jsx(TableHeader, { "data-ntable-table-header": true, className: cn(headerClassName, "sticky top-0 z-10", classNames?.tableHeader), children: /* @__PURE__ */ jsxs(TableRow, { className: "hover:bg-muted/30", children: [
               showCheckbox && /* @__PURE__ */ jsx(TableHead, { "aria-label": "Select column", className: "w-10 text-foreground h-12" }),
               hasExpansion && /* @__PURE__ */ jsx(TableHead, { "aria-label": "Expand column", className: "w-10 text-foreground h-12" }),
               columns.map((col, i) => /* @__PURE__ */ jsx(
@@ -13129,7 +13321,7 @@ function NTableLoadingSkeleton({ rows = DEFAULT_ROWS2 }) {
                 col?.id ?? col?.accessorKey ?? i
               ))
             ] }) }),
-            /* @__PURE__ */ jsx(TableBody, { children: Array.from({ length: rows }).map((_, r) => /* @__PURE__ */ jsxs(TableRow, { children: [
+            /* @__PURE__ */ jsx(TableBody, { children: Array.from({ length: rowCount }).map((_, r) => /* @__PURE__ */ jsxs(TableRow, { children: [
               showCheckbox && /* @__PURE__ */ jsx(TableCell, { className: "h-14 w-10", children: /* @__PURE__ */ jsx(NSkeleton, { className: "h-4 w-4" }) }),
               hasExpansion && /* @__PURE__ */ jsx(TableCell, { className: "h-14 w-10", children: /* @__PURE__ */ jsx(NSkeleton, { className: "h-4 w-4" }) }),
               columns.map((col, c) => /* @__PURE__ */ jsx(
@@ -13160,74 +13352,105 @@ function NTableCardsLoadingSkeleton({ rows }) {
   );
   const classNames = useTableStore.use.classNames();
   const bordered = useTableStore.use.bordered();
-  const calculatedPageSize = useTableStore.use.calculatedPageSize();
-  const pagination = useTableStore.use.pagination();
-  const cardCount = rows ?? Math.max(1, calculatedPageSize || pagination?.pageSize || DEFAULT_CARD_COUNT);
+  const borderColor = useTableStore.use.borderColor();
+  const surface = useTableSurfaceAppearance(bordered, borderColor);
+  const dynamicHeight = useTableStore.use.dynamicHeight();
+  const bodyHeight = useTableStore.use.bodyHeight();
+  const cardColumnCount = useTableStore.use.cardColumnCount();
+  const cardRowHeight = useTableStore.use.cardRowHeight();
+  const cardGap = useTableStore.use.cardGap();
+  const loadingText = useTableStore.use.loadingText();
+  const cardCount = rows ?? (dynamicHeight && bodyHeight > 0 ? calculateCardSkeletonCount({
+    bodyHeight,
+    columnCount: cardColumnCount,
+    cardHeight: cardRowHeight,
+    gap: cardGap
+  }) : DEFAULT_CARD_COUNT);
+  const defaultContainerClass = "grid grid-cols-1 gap-3 sm:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4";
+  const containerClass = classNames?.cards ?? defaultContainerClass;
   return /* @__PURE__ */ jsxs("div", { className: "flex min-h-0 flex-1 flex-col gap-2", children: [
     hasHeaderSkeleton && /* @__PURE__ */ jsx(NTableHeaderSkeleton, {}),
-    /* @__PURE__ */ jsx(NajmScroll, { axis: "y", className: "min-h-0 flex-1 overflow-hidden", children: /* @__PURE__ */ jsx(
-      "div",
+    /* @__PURE__ */ jsxs(
+      NajmScroll,
       {
-        "data-testid": "ntable-cards-loading-skeleton",
+        axis: "y",
         "aria-busy": "true",
-        className: cn("grid grid-cols-1 gap-3 sm:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4", classNames?.cards),
-        children: Array.from({ length: cardCount }).map((_, index) => /* @__PURE__ */ jsx(
-          Card,
-          {
-            className: cn("rounded-lg bg-card p-3 shadow-none sm:p-4", surfaceBorderClasses(bordered)),
-            children: /* @__PURE__ */ jsxs(
-              "div",
-              {
-                "data-ntable-loading-card-layout": "responsive-avatar",
-                className: "grid grid-cols-[80px_minmax(0,1fr)] gap-3 sm:grid-cols-[72px_minmax(0,1fr)]",
-                children: [
-                  /* @__PURE__ */ jsx("div", { className: "col-start-1 row-start-1 flex items-start justify-center sm:justify-start", children: /* @__PURE__ */ jsx(
-                    NSkeleton,
-                    {
-                      "data-ntable-loading-card-avatar": true,
-                      className: "size-20 shrink-0 rounded-full sm:size-16"
-                    }
-                  ) }),
-                  /* @__PURE__ */ jsxs("div", { className: "col-start-2 row-start-1 flex min-w-0 items-start justify-between gap-3", children: [
-                    /* @__PURE__ */ jsxs("div", { className: "min-w-0 flex-1 space-y-2", children: [
-                      /* @__PURE__ */ jsx(NSkeleton, { className: "h-5 w-36 max-w-full" }),
-                      /* @__PURE__ */ jsx(NSkeleton, { className: "hidden h-3 w-16 sm:block" })
-                    ] }),
-                    /* @__PURE__ */ jsx(
-                      NSkeleton,
-                      {
-                        "data-ntable-loading-card-status": true,
-                        className: "hidden h-6 w-14 shrink-0 rounded-full sm:block"
-                      }
-                    )
-                  ] }),
-                  /* @__PURE__ */ jsx(
+        "aria-label": loadingText,
+        role: "status",
+        className: "min-h-0 flex-1 overflow-hidden",
+        children: [
+          /* @__PURE__ */ jsx("span", { className: "sr-only", children: loadingText }),
+          /* @__PURE__ */ jsx(
+            "div",
+            {
+              "data-testid": "ntable-cards-loading-skeleton",
+              "data-ntable-loading-cards-grid": true,
+              "data-ntable-loading-card-count": cardCount,
+              "aria-hidden": "true",
+              className: cn(containerClass),
+              children: Array.from({ length: cardCount }).map((_, index) => /* @__PURE__ */ jsx(
+                "div",
+                {
+                  "data-ntable-loading-card": true,
+                  "data-bordered": surface.bordered === false ? "false" : surface.bordered ? "true" : void 0,
+                  style: surface.style,
+                  className: cn("rounded-lg p-3 sm:p-4", surface.className),
+                  children: /* @__PURE__ */ jsxs(
                     "div",
                     {
-                      "data-ntable-loading-card-details": true,
-                      className: "col-start-2 row-start-2 space-y-1 sm:col-span-full sm:col-start-1 sm:space-y-2 sm:rounded-lg sm:bg-muted/50 sm:p-3",
-                      children: Array.from({ length: 3 }).map((_2, detailIndex) => /* @__PURE__ */ jsxs("div", { className: "flex items-center gap-1.5 sm:gap-2", children: [
-                        /* @__PURE__ */ jsx(NSkeleton, { className: "size-3.5 shrink-0 rounded-sm sm:size-4" }),
-                        /* @__PURE__ */ jsx(
+                      "data-ntable-loading-card-layout": "responsive-avatar",
+                      className: "grid grid-cols-[80px_minmax(0,1fr)] gap-3 sm:grid-cols-[72px_minmax(0,1fr)]",
+                      children: [
+                        /* @__PURE__ */ jsx("div", { className: "col-start-1 row-start-1 flex items-start justify-center sm:justify-start", children: /* @__PURE__ */ jsx(
                           NSkeleton,
                           {
-                            className: cn(
-                              "h-3 max-w-full sm:h-4",
-                              detailIndex === 0 ? "w-full" : detailIndex === 1 ? "w-4/5" : "w-3/4"
-                            )
+                            "data-ntable-loading-card-avatar": true,
+                            className: "size-20 shrink-0 rounded-full sm:size-16"
+                          }
+                        ) }),
+                        /* @__PURE__ */ jsxs("div", { className: "col-start-2 row-start-1 flex min-w-0 items-start justify-between gap-3", children: [
+                          /* @__PURE__ */ jsxs("div", { className: "min-w-0 flex-1 space-y-2", children: [
+                            /* @__PURE__ */ jsx(NSkeleton, { className: "h-5 w-36 max-w-full" }),
+                            /* @__PURE__ */ jsx(NSkeleton, { className: "hidden h-3 w-16 sm:block" })
+                          ] }),
+                          /* @__PURE__ */ jsx(
+                            NSkeleton,
+                            {
+                              "data-ntable-loading-card-status": true,
+                              className: "hidden h-6 w-14 shrink-0 rounded-full sm:block"
+                            }
+                          )
+                        ] }),
+                        /* @__PURE__ */ jsx(
+                          "div",
+                          {
+                            "data-ntable-loading-card-details": true,
+                            className: "col-start-2 row-start-2 space-y-1 sm:col-span-full sm:col-start-1 sm:space-y-2 sm:rounded-lg sm:bg-muted/50 sm:p-3",
+                            children: Array.from({ length: 3 }).map((_2, detailIndex) => /* @__PURE__ */ jsxs("div", { className: "flex items-center gap-1.5 sm:gap-2", children: [
+                              /* @__PURE__ */ jsx(NSkeleton, { className: "size-3.5 shrink-0 rounded-sm sm:size-4" }),
+                              /* @__PURE__ */ jsx(
+                                NSkeleton,
+                                {
+                                  className: cn(
+                                    "h-3 max-w-full sm:h-4",
+                                    detailIndex === 0 ? "w-full" : detailIndex === 1 ? "w-4/5" : "w-3/4"
+                                  )
+                                }
+                              )
+                            ] }, detailIndex))
                           }
                         )
-                      ] }, detailIndex))
+                      ]
                     }
                   )
-                ]
-              }
-            )
-          },
-          index
-        ))
+                },
+                index
+              ))
+            }
+          )
+        ]
       }
-    ) })
+    )
   ] });
 }
 function TableStateSlot({ children }) {
@@ -13278,7 +13501,7 @@ function TableLayout(props) {
   const responsiveCards = useTableStore.use.responsiveCards();
   const isCustomMode = useTableStore.use.isCustomMode();
   const renderCustomMode = useTableStore.use.renderCustomMode();
-  const [isMobile, setIsMobile] = useState(false);
+  const [isMobile, setIsMobile] = useState(() => typeof window !== "undefined" && typeof window.matchMedia === "function" ? window.matchMedia("(max-width: 639px)").matches : false);
   useEffect(() => {
     if (typeof window === "undefined" || typeof window.matchMedia !== "function") return;
     const mql = window.matchMedia("(max-width: 639px)");
@@ -13287,18 +13510,22 @@ function TableLayout(props) {
     mql.addEventListener("change", handler2);
     return () => mql.removeEventListener("change", handler2);
   }, []);
-  useDynamicPageSize(containerRef);
-  useTable();
-  useTableKeyboard({
-    scopeRef: containerRef,
-    contextMenuClose: props.contextMenuClose,
-    contextMenuOpen: props.contextMenuOpen
-  });
   const effectiveMode = (() => {
     if (viewMode === "json") return "json";
     if (isMobile && responsiveCards && CardComponent) return "cards";
     return viewMode;
   })();
+  const syncWithProps = useTableStore.use.syncWithProps();
+  useLayoutEffect(() => {
+    syncWithProps({ isMobile, effectiveViewMode: effectiveMode });
+  }, [effectiveMode, isMobile, syncWithProps]);
+  useDynamicPageSize(containerRef, effectiveMode);
+  useTable(effectiveMode);
+  useTableKeyboard({
+    scopeRef: containerRef,
+    contextMenuClose: props.contextMenuClose,
+    contextMenuOpen: props.contextMenuOpen
+  });
   const showFilteredEmpty = isFilteredEmpty && !isLoading && !error;
   const showEmpty = hasNoData && !isLoading && !error && !showFilteredEmpty;
   const customRenderer = isCustomMode ? renderCustomMode?.[viewMode] : void 0;
@@ -13458,6 +13685,7 @@ function NTable(props) {
     pagination: props.pagination,
     defaultPagination: props.defaultPagination,
     onPaginationChange: props.onPaginationChange ?? null,
+    cardPagination: props.cardPagination ?? { mode: "paged" },
     // Row selection
     rowSelection: props.rowSelection,
     defaultRowSelection: props.defaultRowSelection,

package/dist/theme.css

@@ -307,9 +307,28 @@ input:autofill {
   overflow-x: auto;
   scrollbar-width: none;
 }
-.najm-overlay-scroll-x::-webkit-scrollbar {
-  display: none;
-}
+.najm-overlay-scroll-x::-webkit-scrollbar {
+  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;
+  }
+}
 
 /* OverlayScrollbars theme used by the <NajmScroll> component — a thin,
    translucent slate bar that floats over content with no reserved space.

package/package.json

@@ -1,13 +1,15 @@
 {
   "name": "najm-kit",
-  "version": "2.1.47",
+  "version": "2.1.48",
   "license": "MIT",
   "type": "module",
   "description": "Reusable React UI component package for Najm framework",
   "main": "./dist/index.mjs",
   "types": "./dist/index.d.ts",
   "files": [
-    "dist"
+    "dist",
+    "README.md",
+    "CHANGELOG.md"
   ],
   "exports": {
     ".": {