najm-kit 2.2.1 → 2.2.3

package/dist/index.d.ts

@@ -2871,8 +2871,12 @@ interface TableState {
     hasData: boolean;
     hasControls: boolean;
     hasNoData: boolean;
+    /** Loading while rows are already on screen: a refresh, not a first load. */
+    isRefreshing: boolean;
     dynamicHeight: boolean;
     CardComponent: ComponentType<any> | null;
+    /** Placeholder shaped like `CardComponent`; see `renderCardSkeleton`. */
+    CardSkeletonComponent: ComponentType<any> | null;
     className: string;
     classNames: NTableClassNames;
     bordered?: boolean;
@@ -2909,6 +2913,8 @@ interface TableState {
     calculatedPageSize: number;
     /** Whole card rows that fit the measured body, multiplied by the column count. */
     calculatedCardPageSize: number;
+    /** True once a real layout measurement has replaced the seeded defaults. */
+    hasMeasuredLayout: boolean;
     skeletonRowCount: number;
     maxHeight: number | null;
     bodyWidth: number;
@@ -2970,7 +2976,16 @@ interface TableState {
     hasSyncedExpandedFromProps: boolean;
 }
 type TableStore = ReturnType<typeof createTableStore>;
-declare const createTableStore: () => {
+/**
+ * `seed` becomes part of the store's *initial* state rather than a `set()` call
+ * made after creation. Zustand serves `getInitialState()` as the snapshot for
+ * server rendering and for the hydration render, so anything applied after
+ * creation is invisible on the first paint: `isLoading` would read false while
+ * the caller passed true (rendering the empty state instead of the skeleton),
+ * and `manualPagination` would read false long enough for layout effects to
+ * push a default page size back to a consumer that owns pagination.
+ */
+declare const createTableStore: (seed?: Partial<TableState>) => {
     (): TableState;
     <U>(selector: (state: TableState) => U): U;
 } & StoreApi<TableState> & {
@@ -2998,8 +3013,10 @@ declare const createTableStore: () => {
         hasData: () => boolean;
         hasControls: () => boolean;
         hasNoData: () => boolean;
+        isRefreshing: () => boolean;
         dynamicHeight: () => boolean;
         CardComponent: () => ComponentType<any>;
+        CardSkeletonComponent: () => ComponentType<any>;
         className: () => string;
         classNames: () => NTableClassNames;
         bordered?: () => boolean;
@@ -3035,6 +3052,7 @@ declare const createTableStore: () => {
         pageSizeOptions: () => number[];
         calculatedPageSize: () => number;
         calculatedCardPageSize: () => number;
+        hasMeasuredLayout: () => boolean;
         skeletonRowCount: () => number;
         maxHeight: () => number;
         bodyWidth: () => number;
@@ -3184,6 +3202,32 @@ interface NTableProps<T = any, M extends ViewMode = ViewMode> {
         'data-row'?: string;
         'data-row-id'?: string;
     }>;
+    /**
+     * A placeholder shaped like `renderCard`.
+     *
+     * The card page size is measured from whatever is on screen, and during a
+     * first load that is the skeleton. The built-in placeholder is an avatar row,
+     * so a consumer whose cards are a different height — a media card, say — gets
+     * a page size measured against a card it does not use, and the grid re-lays
+     * out once real cards arrive. Supplying a placeholder with the real card's
+     * geometry makes the first measurement the correct one.
+     */
+    renderCardSkeleton?: ComponentType<Record<string, never>>;
+    /**
+     * Emit both skeleton shapes and let a media query choose between them.
+     *
+     * A view mode derived from the viewport is unknowable on the server, so the
+     * server renders the card shape and the client corrects it after hydration —
+     * on a desktop table page that is a visible card skeleton followed by a table
+     * skeleton. No client-side detection can fix it, because the first paint is
+     * whatever the server sent. Rendering both and hiding one in CSS puts the
+     * right shape in that first paint. The skeleton is `aria-hidden` decoration,
+     * so the duplicate costs nothing to assistive technology.
+     *
+     * The breakpoint is `lg` (1024px), matching the point at which a table
+     * becomes usable.
+     */
+    responsiveSkeleton?: boolean;
     renderToolbar?: (state: NTableState) => React__default.ReactNode;
     renderEmpty?: () => React__default.ReactNode;
     renderError?: (error: any) => React__default.ReactNode;
@@ -3417,8 +3461,10 @@ declare const TableStoreContext: React$1.Context<{
         hasData: () => boolean;
         hasControls: () => boolean;
         hasNoData: () => boolean;
+        isRefreshing: () => boolean;
         dynamicHeight: () => boolean;
         CardComponent: () => React$1.ComponentType<any>;
+        CardSkeletonComponent: () => React$1.ComponentType<any>;
         className: () => string;
         classNames: () => NTableClassNames;
         bordered?: () => boolean;
@@ -3454,6 +3500,7 @@ declare const TableStoreContext: React$1.Context<{
         pageSizeOptions: () => number[];
         calculatedPageSize: () => number;
         calculatedCardPageSize: () => number;
+        hasMeasuredLayout: () => boolean;
         skeletonRowCount: () => number;
         maxHeight: () => number;
         bodyWidth: () => number;
@@ -3547,8 +3594,10 @@ declare function useStoreSync(props: any): {
         hasData: () => boolean;
         hasControls: () => boolean;
         hasNoData: () => boolean;
+        isRefreshing: () => boolean;
         dynamicHeight: () => boolean;
         CardComponent: () => React__default.ComponentType<any>;
+        CardSkeletonComponent: () => React__default.ComponentType<any>;
         className: () => string;
         classNames: () => NTableClassNames;
         bordered?: () => boolean;
@@ -3584,6 +3633,7 @@ declare function useStoreSync(props: any): {
         pageSizeOptions: () => number[];
         calculatedPageSize: () => number;
         calculatedCardPageSize: () => number;
+        hasMeasuredLayout: () => boolean;
         skeletonRowCount: () => number;
         maxHeight: () => number;
         bodyWidth: () => number;

package/dist/index.mjs

@@ -12125,8 +12125,9 @@ var computeFlags = (state) => {
     state.menuButton && state.openRowMenu || state.onView || state.onEdit || state.onDelete
   );
   const hasControls = Boolean(state.showColumnVisibility || state.showAddButton || state.showViewToggle);
-  const showContent = !state.isLoading && !state.error && !hasNoData && !isFilteredEmpty;
-  return { hasData, hasNoData, isTableView, isCardView, isJsonView, isFilesView, isCustomMode, hasActions, hasControls, showContent, showPagination: state.showPagination && showContent };
+  const isRefreshing = Boolean(state.isLoading) && hasData;
+  const showContent = !state.error && !hasNoData && !isFilteredEmpty && (!state.isLoading || hasData);
+  return { hasData, hasNoData, isTableView, isCardView, isJsonView, isFilesView, isCustomMode, hasActions, hasControls, isRefreshing, showContent, showPagination: state.showPagination && showContent };
 };
 var createSelectors = (_store) => {
   const store = _store;
@@ -12136,177 +12137,193 @@ var createSelectors = (_store) => {
   }
   return store;
 };
-var createTableStore = () => {
-  const store = create((set, get) => ({
-    table: null,
-    data: [],
-    columns: [],
-    filters: [],
-    isLoading: false,
-    error: null,
-    viewMode: "table",
-    showSorting: true,
-    showPagination: true,
-    showColumnVisibility: false,
-    showAddButton: true,
-    showViewToggle: true,
-    toolbarLabels: true,
-    dynamicHeight: true,
-    showContent: false,
-    isTableView: true,
-    isCardView: false,
-    isJsonView: false,
-    isFilesView: false,
-    isCustomMode: false,
-    hasActions: false,
-    hasData: false,
-    hasControls: true,
-    hasNoData: true,
-    onView: null,
-    onEdit: null,
-    onDelete: null,
-    onAddClick: null,
-    onRowClick: null,
-    onRowContextMenu: null,
-    onBackgroundContextMenu: null,
-    openRowMenu: null,
-    getRowClassName: null,
-    menuButton: false,
-    onCellClick: null,
-    onBulkDelete: null,
-    onRetry: null,
-    onCellEdit: null,
-    onStateChange: null,
-    getRowId: null,
-    renderToolbar: null,
-    CardComponent: null,
-    className: "",
-    classNames: {},
-    bordered: void 0,
-    headerClassName: "bg-card",
-    headerColor: void 0,
-    headerTextColor: void 0,
-    borderColor: void 0,
-    showCheckbox: true,
-    selectedRowId: null,
-    headerSlot: null,
-    noResultsText: "No results.",
-    filterPlaceholder: "",
-    loadingText: "Loading...",
-    noDataText: "No data available",
-    addButtonText: "",
-    pageSizeOptions: [10, 20, 30, 40, 50],
-    calculatedPageSize: 10,
-    calculatedCardPageSize: 0,
-    skeletonRowCount: 6,
-    maxHeight: null,
-    bodyWidth: 0,
-    bodyHeight: 0,
-    tableHeaderHeight: 48,
-    cardColumnCount: 1,
-    cardRowHeight: 0,
-    cardGap: 12,
-    // JSON mode
-    jsonValue: void 0,
-    jsonColors: null,
-    renderJson: null,
-    // Custom mode
-    renderCustomMode: null,
-    // Controlled mode
-    isModeControlled: false,
-    onModeChange: null,
-    // availableModes
-    availableModes: ["table", "cards", "json"],
-    // User-intent setter
-    setViewMode: (mode) => {
-      const { isModeControlled, onModeChange } = get();
-      onModeChange?.(mode);
-      if (!isModeControlled) {
-        const updates = { viewMode: mode };
+var createTableStore = (seed) => {
+  const store = create((set, get) => {
+    const defaults = {
+      table: null,
+      data: [],
+      columns: [],
+      filters: [],
+      isLoading: false,
+      error: null,
+      viewMode: "table",
+      showSorting: true,
+      showPagination: true,
+      showColumnVisibility: false,
+      showAddButton: true,
+      showViewToggle: true,
+      toolbarLabels: true,
+      dynamicHeight: true,
+      showContent: false,
+      isTableView: true,
+      isCardView: false,
+      isJsonView: false,
+      isFilesView: false,
+      isCustomMode: false,
+      hasActions: false,
+      hasData: false,
+      hasControls: true,
+      hasNoData: true,
+      isRefreshing: false,
+      onView: null,
+      onEdit: null,
+      onDelete: null,
+      onAddClick: null,
+      onRowClick: null,
+      onRowContextMenu: null,
+      onBackgroundContextMenu: null,
+      openRowMenu: null,
+      getRowClassName: null,
+      menuButton: false,
+      onCellClick: null,
+      onBulkDelete: null,
+      onRetry: null,
+      onCellEdit: null,
+      onStateChange: null,
+      getRowId: null,
+      renderToolbar: null,
+      CardComponent: null,
+      CardSkeletonComponent: null,
+      className: "",
+      classNames: {},
+      bordered: void 0,
+      headerClassName: "bg-card",
+      headerColor: void 0,
+      headerTextColor: void 0,
+      borderColor: void 0,
+      showCheckbox: true,
+      selectedRowId: null,
+      headerSlot: null,
+      noResultsText: "No results.",
+      filterPlaceholder: "",
+      loadingText: "Loading...",
+      noDataText: "No data available",
+      addButtonText: "",
+      pageSizeOptions: [10, 20, 30, 40, 50],
+      calculatedPageSize: 10,
+      calculatedCardPageSize: 0,
+      hasMeasuredLayout: false,
+      skeletonRowCount: 6,
+      maxHeight: null,
+      bodyWidth: 0,
+      bodyHeight: 0,
+      tableHeaderHeight: 48,
+      cardColumnCount: 1,
+      cardRowHeight: 0,
+      cardGap: 12,
+      // JSON mode
+      jsonValue: void 0,
+      jsonColors: null,
+      renderJson: null,
+      // Custom mode
+      renderCustomMode: null,
+      // Controlled mode
+      isModeControlled: false,
+      onModeChange: null,
+      // availableModes
+      availableModes: ["table", "cards", "json"],
+      // User-intent setter
+      setViewMode: (mode) => {
+        const { isModeControlled, onModeChange } = get();
+        onModeChange?.(mode);
+        if (!isModeControlled) {
+          const updates = { viewMode: mode };
+          const currentState = get();
+          const mergedState = { ...currentState, ...updates };
+          const flags = computeFlags(mergedState);
+          set({ ...updates, ...flags });
+        }
+      },
+      // Track if we've ever synced viewMode from props
+      hasSyncedFromProps: false,
+      // Server-side pagination
+      manualPagination: false,
+      pageCount: void 0,
+      rowCount: void 0,
+      pagination: { pageIndex: 0, pageSize: 10 },
+      isPaginationControlled: false,
+      onPaginationChange: null,
+      // User-intent setter for pagination
+      setPagination: (pagination) => {
+        const { isPaginationControlled, onPaginationChange } = get();
+        onPaginationChange?.(pagination);
+        if (!isPaginationControlled) {
+          set({ pagination });
+        }
+      },
+      // Track if we've ever synced pagination from props
+      hasSyncedPaginationFromProps: false,
+      // Row selection
+      rowSelection: {},
+      isRowSelectionControlled: false,
+      onRowSelectionChange: null,
+      setRowSelection: (state) => {
+        const { isRowSelectionControlled, onRowSelectionChange } = get();
+        onRowSelectionChange?.(state);
+        if (!isRowSelectionControlled) {
+          set({ rowSelection: state });
+        }
+      },
+      hasSyncedRowSelectionFromProps: false,
+      // Sorting
+      sorting: [],
+      isSortingControlled: false,
+      onSortingChange: null,
+      setSorting: (state) => {
+        const { isSortingControlled, onSortingChange } = get();
+        onSortingChange?.(state);
+        if (!isSortingControlled) {
+          set({ sorting: state });
+        }
+      },
+      hasSyncedSortingFromProps: false,
+      // Responsive cards
+      responsiveCards: true,
+      isMobile: false,
+      effectiveViewMode: "table",
+      cardPagination: { mode: "paged" },
+      // Empty states
+      isEmpty: void 0,
+      isFilteredEmpty: false,
+      renderFilteredEmpty: null,
+      // Row expansion
+      expanded: {},
+      isExpandedControlled: false,
+      onExpandedChange: null,
+      getRowCanExpand: null,
+      renderSubRow: null,
+      setExpanded: (next) => {
+        const { isExpandedControlled, onExpandedChange } = get();
+        onExpandedChange?.(next);
+        if (!isExpandedControlled) {
+          set({ expanded: next });
+        }
+      },
+      hasSyncedExpandedFromProps: false,
+      syncWithProps: (updates) => {
         const currentState = get();
-        const mergedState = { ...currentState, ...updates };
+        const hasSyncedFromProps = currentState.hasSyncedFromProps || "viewMode" in updates;
+        const hasSyncedPaginationFromProps = currentState.hasSyncedPaginationFromProps || "pagination" in updates;
+        const hasSyncedRowSelectionFromProps = currentState.hasSyncedRowSelectionFromProps || "rowSelection" in updates;
+        const hasSyncedExpandedFromProps = currentState.hasSyncedExpandedFromProps || "expanded" in updates;
+        const hasSyncedSortingFromProps = currentState.hasSyncedSortingFromProps || "sorting" in updates;
+        const mergedState = { ...currentState, ...updates};
         const flags = computeFlags(mergedState);
-        set({ ...updates, ...flags });
-      }
-    },
-    // Track if we've ever synced viewMode from props
-    hasSyncedFromProps: false,
-    // Server-side pagination
-    manualPagination: false,
-    pageCount: void 0,
-    rowCount: void 0,
-    pagination: { pageIndex: 0, pageSize: 10 },
-    isPaginationControlled: false,
-    onPaginationChange: null,
-    // User-intent setter for pagination
-    setPagination: (pagination) => {
-      const { isPaginationControlled, onPaginationChange } = get();
-      onPaginationChange?.(pagination);
-      if (!isPaginationControlled) {
-        set({ pagination });
-      }
-    },
-    // Track if we've ever synced pagination from props
-    hasSyncedPaginationFromProps: false,
-    // Row selection
-    rowSelection: {},
-    isRowSelectionControlled: false,
-    onRowSelectionChange: null,
-    setRowSelection: (state) => {
-      const { isRowSelectionControlled, onRowSelectionChange } = get();
-      onRowSelectionChange?.(state);
-      if (!isRowSelectionControlled) {
-        set({ rowSelection: state });
-      }
-    },
-    hasSyncedRowSelectionFromProps: false,
-    // Sorting
-    sorting: [],
-    isSortingControlled: false,
-    onSortingChange: null,
-    setSorting: (state) => {
-      const { isSortingControlled, onSortingChange } = get();
-      onSortingChange?.(state);
-      if (!isSortingControlled) {
-        set({ sorting: state });
+        set({ ...updates, ...flags, hasSyncedFromProps, hasSyncedPaginationFromProps, hasSyncedRowSelectionFromProps, hasSyncedExpandedFromProps, hasSyncedSortingFromProps });
       }
-    },
-    hasSyncedSortingFromProps: false,
-    // Responsive cards
-    responsiveCards: true,
-    isMobile: false,
-    effectiveViewMode: "table",
-    cardPagination: { mode: "paged" },
-    // Empty states
-    isEmpty: void 0,
-    isFilteredEmpty: false,
-    renderFilteredEmpty: null,
-    // Row expansion
-    expanded: {},
-    isExpandedControlled: false,
-    onExpandedChange: null,
-    getRowCanExpand: null,
-    renderSubRow: null,
-    setExpanded: (next) => {
-      const { isExpandedControlled, onExpandedChange } = get();
-      onExpandedChange?.(next);
-      if (!isExpandedControlled) {
-        set({ expanded: next });
-      }
-    },
-    hasSyncedExpandedFromProps: false,
-    syncWithProps: (updates) => {
-      const currentState = get();
-      const hasSyncedFromProps = currentState.hasSyncedFromProps || "viewMode" in updates;
-      const hasSyncedPaginationFromProps = currentState.hasSyncedPaginationFromProps || "pagination" in updates;
-      const hasSyncedRowSelectionFromProps = currentState.hasSyncedRowSelectionFromProps || "rowSelection" in updates;
-      const hasSyncedExpandedFromProps = currentState.hasSyncedExpandedFromProps || "expanded" in updates;
-      const hasSyncedSortingFromProps = currentState.hasSyncedSortingFromProps || "sorting" in updates;
-      const mergedState = { ...currentState, ...updates};
-      const flags = computeFlags(mergedState);
-      set({ ...updates, ...flags, hasSyncedFromProps, hasSyncedPaginationFromProps, hasSyncedRowSelectionFromProps, hasSyncedExpandedFromProps, hasSyncedSortingFromProps });
-    }
-  }));
+    };
+    if (!seed) return defaults;
+    const merged = {
+      ...defaults,
+      ...seed,
+      hasSyncedFromProps: "viewMode" in seed,
+      hasSyncedPaginationFromProps: "pagination" in seed,
+      hasSyncedRowSelectionFromProps: "rowSelection" in seed,
+      hasSyncedExpandedFromProps: "expanded" in seed,
+      hasSyncedSortingFromProps: "sorting" in seed
+    };
+    return { ...merged, ...computeFlags(merged) };
+  });
   return createSelectors(store);
 };
 
@@ -12355,7 +12372,9 @@ var DEFAULT_TABLE_HEADER_HEIGHT = 48;
 var DEFAULT_CARD_HEIGHT = 176;
 var DEFAULT_CARD_GAP = 12;
 var ROOT_SECTION_GAP_COUNT = 2;
-var DYNAMIC_PAGE_SIZE_DEBOUNCE_MS = 200;
+var DYNAMIC_PAGE_SIZE_DEBOUNCE_MS = 800;
+var MAX_PAGE_SIZE_REPORTS_PER_GEOMETRY = 2;
+var GEOMETRY_BUCKET_PX = 32;
 function useStoreSync(props) {
   const storeRef = useRef(null);
   const isControlled = props.mode !== void 0;
@@ -12364,7 +12383,6 @@ function useStoreSync(props) {
   const isExpandedControlled = props.expanded !== void 0;
   const isSortingControlled = props.sorting !== void 0;
   if (!storeRef.current) {
-    storeRef.current = createTableStore();
     const syncSnapshot = { ...props, isModeControlled: isControlled, isPaginationControlled, isRowSelectionControlled, isExpandedControlled, isSortingControlled };
     delete syncSnapshot.pagination;
     delete syncSnapshot.defaultPagination;
@@ -12382,7 +12400,7 @@ function useStoreSync(props) {
     delete syncSnapshot.defaultSorting;
     if (props.sorting !== void 0) syncSnapshot.sorting = props.sorting;
     else if (props.defaultSorting !== void 0) syncSnapshot.sorting = props.defaultSorting;
-    storeRef.current.getState().syncWithProps(syncSnapshot);
+    storeRef.current = createTableStore(syncSnapshot);
   }
   useLayoutEffect(() => {
     const syncData = { ...props };
@@ -12475,9 +12493,11 @@ function useDynamicPageSize(containerRef, effectiveViewMode) {
       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]"
-      );
+      const cardsGridEl = Array.from(
+        container2.querySelectorAll(
+          "[data-ntable-loading-cards-grid], [data-ntable-cards-grid]"
+        )
+      ).find((el) => el.clientHeight > 0 || el.clientWidth > 0) ?? null;
       let bodyHeight = bodyEl?.clientHeight ?? 0;
       const bodyWidth = bodyEl?.clientWidth ?? container2.clientWidth ?? 0;
       if (!bodyHeight) {
@@ -12515,6 +12535,9 @@ function useDynamicPageSize(containerRef, effectiveViewMode) {
         // mutating the table directly, so the consumer still owns fetching.
         calculatedPageSize: newPageSize,
         calculatedCardPageSize: cardPageSize,
+        // Distinguishes a real measurement from the seeded defaults, so a page
+        // size is never reported before the container has been measured.
+        hasMeasuredLayout: bodyHeight > 0,
         ...!manualPagination ? { maxHeight: calculatedMaxHeight } : {},
         skeletonRowCount: newPageSize,
         bodyWidth,
@@ -12567,6 +12590,7 @@ function useTable(effectiveViewModeOverride) {
   const calculatedCardPageSize = useTableStore.use.calculatedCardPageSize();
   const measuredBodyHeight = useTableStore.use.bodyHeight();
   const measuredBodyWidth = useTableStore.use.bodyWidth();
+  const hasMeasuredLayout = useTableStore.use.hasMeasuredLayout();
   const syncWithProps = useTableStore.use.syncWithProps();
   const onStateChange = useTableStore.use.onStateChange();
   const getRowId = useTableStore.use.getRowId();
@@ -12574,6 +12598,7 @@ function useTable(effectiveViewModeOverride) {
   const pageCount = useTableStore.use.pageCount();
   const rowCount = useTableStore.use.rowCount();
   const storePagination = useTableStore.use.pagination();
+  const isPaginationControlled = useTableStore.use.isPaginationControlled();
   const setPagination = useTableStore.use.setPagination();
   const storeRowSelection = useTableStore.use.rowSelection();
   const setRowSelection = useTableStore.use.setRowSelection();
@@ -12687,24 +12712,26 @@ function useTable(effectiveViewModeOverride) {
     syncWithProps({ table });
   }, [table]);
   useLayoutEffect(() => {
-    if (manualPagination) return;
+    if (manualPagination || isPaginationControlled) return;
     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]);
+  }, [calculatedPageSize, dynamicHeight, renderedMode, viewMode, cardPagination.mode, table, data.length, manualPagination, isPaginationControlled]);
   const dynamicPageSizeTarget = renderedMode === "cards" ? calculatedCardPageSize : calculatedPageSize;
-  const geometryKey = `${renderedMode}:${measuredBodyWidth}x${measuredBodyHeight}`;
+  const geometryKey = `${Math.round(measuredBodyWidth / GEOMETRY_BUCKET_PX)}x${Math.round(measuredBodyHeight / GEOMETRY_BUCKET_PX)}`;
   const reportedGeometryRef = useRef(null);
   useEffect(() => {
     if (!manualPagination || !dynamicHeight) return;
     if (cardPagination.mode !== "paged") return;
-    if (measuredBodyHeight <= 0) return;
+    if (!hasMeasuredLayout || measuredBodyHeight <= 0) return;
     if (!dynamicPageSizeTarget || dynamicPageSizeTarget < 1) return;
     if (dynamicPageSizeTarget === storePagination.pageSize) return;
-    if (reportedGeometryRef.current === geometryKey) return;
+    const reported = reportedGeometryRef.current;
+    if (reported?.key === geometryKey && reported.count >= MAX_PAGE_SIZE_REPORTS_PER_GEOMETRY) return;
     const timer = setTimeout(() => {
-      reportedGeometryRef.current = geometryKey;
+      const current = reportedGeometryRef.current;
+      reportedGeometryRef.current = current?.key === geometryKey ? { key: geometryKey, count: current.count + 1 } : { key: geometryKey, count: 1 };
       setPagination({ pageIndex: storePagination.pageIndex, pageSize: dynamicPageSizeTarget });
     }, DYNAMIC_PAGE_SIZE_DEBOUNCE_MS);
     return () => clearTimeout(timer);
@@ -12712,6 +12739,7 @@ function useTable(effectiveViewModeOverride) {
     manualPagination,
     dynamicHeight,
     cardPagination.mode,
+    hasMeasuredLayout,
     measuredBodyHeight,
     geometryKey,
     dynamicPageSizeTarget,
@@ -12908,7 +12936,7 @@ function NTableContent({ effectiveMode }) {
   const onBackgroundContextMenu = useTableStore.use.onBackgroundContextMenu();
   const getRowClassName = useTableStore.use.getRowClassName();
   const onCellEdit = useTableStore.use.onCellEdit();
-  const isLoading = useTableStore.use.isLoading();
+  useTableStore.use.isLoading();
   const error = useTableStore.use.error();
   const hasNoData = useTableStore.use.hasNoData();
   const showContent = useTableStore.use.showContent();
@@ -12928,7 +12956,7 @@ function NTableContent({ effectiveMode }) {
       onBackgroundContextMenu(e);
     }
   }, [onBackgroundContextMenu]);
-  if (isLoading || error || hasNoData || !showContent || !table) return null;
+  if (error || hasNoData || !showContent || !table) return null;
   const isTableView = effectiveMode ? effectiveMode === "table" : storeIsTableView;
   if (!isTableView) return null;
   const getSortIcon = (column) => {
@@ -13182,7 +13210,7 @@ function NDataCardShell({ row, onClick, onContextMenu, actions, children, classN
   );
 }
 var DEFAULT_ROWS2 = 6;
-var DEFAULT_CARD_COUNT = 16;
+var DEFAULT_CARD_COUNT = 48;
 function NTableCardSkeleton({ surface }) {
   return /* @__PURE__ */ jsx(
     "div",
@@ -13398,6 +13426,7 @@ function NTableCardsLoadingSkeleton({ rows }) {
   const cardRowHeight = useTableStore.use.cardRowHeight();
   const cardGap = useTableStore.use.cardGap();
   const loadingText = useTableStore.use.loadingText();
+  const CardSkeletonComponent = useTableStore.use.CardSkeletonComponent();
   const cardCount = rows ?? (dynamicHeight && bodyHeight > 0 ? calculateCardSkeletonCount({
     bodyHeight,
     columnCount: cardColumnCount,
@@ -13426,7 +13455,7 @@ function NTableCardsLoadingSkeleton({ rows }) {
               "data-ntable-loading-card-count": cardCount,
               "aria-hidden": "true",
               className: cn(containerClass),
-              children: Array.from({ length: cardCount }).map((_, index) => /* @__PURE__ */ jsx(NTableCardSkeleton, { surface }, index))
+              children: Array.from({ length: cardCount }).map((_, index) => CardSkeletonComponent ? /* @__PURE__ */ jsx("div", { "data-ntable-loading-card": true, children: /* @__PURE__ */ jsx(CardSkeletonComponent, {}) }, index) : /* @__PURE__ */ jsx(NTableCardSkeleton, { surface }, index))
             }
           )
         ]
@@ -13485,13 +13514,13 @@ function useCardContinuation({
   });
   React__default.useEffect(() => {
     const previous = previousRowCountRef.current;
-    if (rowCount > previous) {
-      const appended = rowCount - previous;
-      setAnnouncement(
-        configRef.current?.itemsLoadedLabel?.(appended) ?? `${appended} more ${appended === 1 ? "item" : "items"} loaded.`
-      );
-    }
     previousRowCountRef.current = rowCount;
+    if (!configRef.current) return;
+    if (rowCount <= previous) return;
+    const appended = rowCount - previous;
+    setAnnouncement(
+      configRef.current.itemsLoadedLabel?.(appended) ?? `${appended} more ${appended === 1 ? "item" : "items"} loaded.`
+    );
   }, [rowCount]);
   React__default.useEffect(() => {
     if (!pending) doneLoading();
@@ -13536,8 +13565,9 @@ function NTableCards({ effectiveMode }) {
   const showCheckbox = useTableStore.use.showCheckbox();
   const selectedRowId = useTableStore.use.selectedRowId();
   const CardComponent = useTableStore.use.CardComponent();
+  const CardSkeletonComponent = useTableStore.use.CardSkeletonComponent();
   const storeIsCardView = useTableStore.use.isCardView();
-  const isLoading = useTableStore.use.isLoading();
+  useTableStore.use.isLoading();
   const error = useTableStore.use.error();
   const hasNoData = useTableStore.use.hasNoData();
   const showContent = useTableStore.use.showContent();
@@ -13583,7 +13613,7 @@ function NTableCards({ effectiveMode }) {
       onBackgroundContextMenu(e);
     }
   }, [table, onRowContextMenu, onBackgroundContextMenu]);
-  if (isLoading || error || hasNoData || !showContent || !table) return null;
+  if (error || hasNoData || !showContent || !table) return null;
   const isCardView = effectiveMode ? effectiveMode === "cards" : storeIsCardView;
   if (!isCardView) return null;
   const rows = table.getRowModel().rows;
@@ -13677,7 +13707,7 @@ function NTableCards({ effectiveMode }) {
           row.id
         );
       }),
-      continuation.pending ? Array.from({ length: Math.max(1, cardColumnCount || 1) }).map((_, index) => /* @__PURE__ */ jsx(NTableCardSkeleton, { surface }, `ntable-continuation-skeleton-${index}`)) : null
+      continuation.pending ? Array.from({ length: Math.max(1, cardColumnCount || 1) }).map((_, index) => CardSkeletonComponent ? /* @__PURE__ */ jsx(CardSkeletonComponent, {}, `ntable-continuation-skeleton-${index}`) : /* @__PURE__ */ jsx(NTableCardSkeleton, { surface }, `ntable-continuation-skeleton-${index}`)) : null
     ] }),
     continuation.error ? /* @__PURE__ */ jsxs(
       "div",
@@ -13702,7 +13732,16 @@ function NTableCards({ effectiveMode }) {
       }
     ) : null,
     continuation.active ? /* @__PURE__ */ jsx("div", { ref: continuation.sentinelRef, "data-ntable-cards-sentinel": true, "aria-hidden": "true" }) : null,
-    /* @__PURE__ */ jsx("span", { className: "sr-only", role: "status", "aria-live": "polite", "aria-atomic": "true", children: continuation.announcement })
+    continuationConfig ? /* @__PURE__ */ jsx(
+      "span",
+      {
+        role: "status",
+        "aria-live": "polite",
+        "aria-atomic": "true",
+        className: "sr-only absolute -m-px h-px w-px overflow-hidden border-0 p-0 whitespace-nowrap [clip:rect(0,0,0,0)]",
+        children: continuation.announcement
+      }
+    ) : null
   ] });
 }
 function CardLoadMorePagination({
@@ -14140,6 +14179,7 @@ function TableToolbarSlot() {
 function NTableHeader() {
   const hasControls = useTableStore.use.hasControls();
   const isLoading = useTableStore.use.isLoading();
+  const isRefreshing = useTableStore.use.isRefreshing();
   const error = useTableStore.use.error();
   const hasNoData = useTableStore.use.hasNoData();
   const isFilteredEmpty = useTableStore.use.isFilteredEmpty();
@@ -14150,7 +14190,7 @@ function NTableHeader() {
   const isCustomMode = useTableStore.use.isCustomMode();
   const showViewToggle = useTableStore.use.showViewToggle();
   const showColumnVisibility = useTableStore.use.showColumnVisibility();
-  const hideDataChrome = isLoading || error || hasNoData && !isFilteredEmpty;
+  const hideDataChrome = isLoading && !isRefreshing || error || hasNoData && !isFilteredEmpty;
   if (isCustomMode) {
     if (!showViewToggle && !showColumnVisibility && !headerSlot && !hasControls) return null;
     if (hideDataChrome) return null;
@@ -14232,6 +14272,7 @@ function TableLayout(props) {
   const className = useTableStore.use.className();
   useTableStore.use.dynamicHeight();
   const isLoading = useTableStore.use.isLoading();
+  const isRefreshing = useTableStore.use.isRefreshing();
   const error = useTableStore.use.error();
   const hasNoData = useTableStore.use.hasNoData();
   const noDataText = useTableStore.use.noDataText();
@@ -14272,15 +14313,27 @@ function TableLayout(props) {
   const customRenderer = isCustomMode ? renderCustomMode?.[viewMode] : void 0;
   return /* @__PURE__ */ jsxs("div", { ref: containerRef, "data-ntable-root": true, className: cn("flex h-full min-h-0 flex-1 w-full flex-col gap-2 overflow-hidden", classNames?.root, className), children: [
     /* @__PURE__ */ jsx(NTableHeader, {}),
-    /* @__PURE__ */ jsx("div", { "data-ntable-body": true, className: "flex min-h-0 flex-1 flex-col gap-2 overflow-hidden", children: isCustomMode ? customRenderer ? customRenderer() : null : /* @__PURE__ */ jsxs(Fragment, { children: [
-      isLoading && (props.renderLoading ? /* @__PURE__ */ jsx(TableStateSlot, { children: props.renderLoading() }) : effectiveMode === "table" ? /* @__PURE__ */ jsx(NTableLoadingSkeleton, {}) : effectiveMode === "cards" ? /* @__PURE__ */ jsx(NTableCardsLoadingSkeleton, {}) : /* @__PURE__ */ jsx(NTableLoadingSkeleton, {})),
-      error && !isLoading && /* @__PURE__ */ jsx(TableStateSlot, { children: props.renderError ? props.renderError(error) : /* @__PURE__ */ jsx(NErrorState, { message: typeof error === "string" ? error : "An error occurred" }) }),
-      showFilteredEmpty && /* @__PURE__ */ jsx(TableStateSlot, { children: props.renderFilteredEmpty ? props.renderFilteredEmpty() : renderFilteredEmpty ? renderFilteredEmpty() : props.renderEmpty ? props.renderEmpty() : /* @__PURE__ */ jsx(DefaultTableFilteredEmptyState, {}) }),
-      showEmpty && /* @__PURE__ */ jsx(TableStateSlot, { children: props.renderEmpty ? props.renderEmpty() : /* @__PURE__ */ jsx(DefaultTableEmptyState, { title: noDataText }) }),
-      /* @__PURE__ */ jsx(NTableContent, { effectiveMode }),
-      /* @__PURE__ */ jsx(NTableCards, { effectiveMode }),
-      /* @__PURE__ */ jsx(NTableJson, {})
-    ] }) }),
+    /* @__PURE__ */ jsx(
+      "div",
+      {
+        "data-ntable-body": true,
+        "data-ntable-refreshing": isRefreshing ? "true" : void 0,
+        "aria-busy": isRefreshing ? "true" : void 0,
+        className: "flex min-h-0 flex-1 flex-col gap-2 overflow-hidden",
+        children: isCustomMode ? customRenderer ? customRenderer() : null : /* @__PURE__ */ jsxs(Fragment, { children: [
+          isLoading && !isRefreshing && (props.renderLoading ? /* @__PURE__ */ jsx(TableStateSlot, { children: props.renderLoading() }) : props.responsiveSkeleton ? /* @__PURE__ */ jsxs(Fragment, { children: [
+            /* @__PURE__ */ jsx("div", { "data-ntable-skeleton-variant": "table", className: "hidden min-h-0 flex-1 flex-col lg:flex", children: /* @__PURE__ */ jsx(NTableLoadingSkeleton, {}) }),
+            /* @__PURE__ */ jsx("div", { "data-ntable-skeleton-variant": "cards", className: "flex min-h-0 flex-1 flex-col lg:hidden", children: /* @__PURE__ */ jsx(NTableCardsLoadingSkeleton, {}) })
+          ] }) : effectiveMode === "table" ? /* @__PURE__ */ jsx(NTableLoadingSkeleton, {}) : effectiveMode === "cards" ? /* @__PURE__ */ jsx(NTableCardsLoadingSkeleton, {}) : /* @__PURE__ */ jsx(NTableLoadingSkeleton, {})),
+          error && !isLoading && /* @__PURE__ */ jsx(TableStateSlot, { children: props.renderError ? props.renderError(error) : /* @__PURE__ */ jsx(NErrorState, { message: typeof error === "string" ? error : "An error occurred" }) }),
+          showFilteredEmpty && /* @__PURE__ */ jsx(TableStateSlot, { children: props.renderFilteredEmpty ? props.renderFilteredEmpty() : renderFilteredEmpty ? renderFilteredEmpty() : props.renderEmpty ? props.renderEmpty() : /* @__PURE__ */ jsx(DefaultTableFilteredEmptyState, {}) }),
+          showEmpty && /* @__PURE__ */ jsx(TableStateSlot, { children: props.renderEmpty ? props.renderEmpty() : /* @__PURE__ */ jsx(DefaultTableEmptyState, { title: noDataText }) }),
+          /* @__PURE__ */ jsx(NTableContent, { effectiveMode }),
+          /* @__PURE__ */ jsx(NTableCards, { effectiveMode }),
+          /* @__PURE__ */ jsx(NTableJson, {})
+        ] })
+      }
+    ),
     /* @__PURE__ */ jsx("div", { "data-ntable-pagination": true, className: "min-w-0 shrink-0 bg-background text-foreground", children: /* @__PURE__ */ jsx(NTablePagination, {}) })
   ] });
 }
@@ -14375,6 +14428,7 @@ function NTable(props) {
     mode,
     onModeChange: props.onModeChange,
     CardComponent: props.renderCard ?? null,
+    CardSkeletonComponent: props.renderCardSkeleton ?? null,
     className: props.className ?? "",
     classNames: props.classNames ?? {},
     bordered: props.bordered ?? (recipeBordered ? true : void 0),
@@ -14456,6 +14510,7 @@ function NTable(props) {
         renderFilteredEmpty: props.renderFilteredEmpty,
         renderError: props.renderError,
         renderLoading: props.renderLoading,
+        responsiveSkeleton: props.responsiveSkeleton,
         contextMenuClose: ctx.close,
         contextMenuOpen: ctx.isOpen
       }

package/package.json

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