najm-kit 2.11.2 → 2.11.4

package/CHANGELOG.md

@@ -1,19 +1,33 @@
-# Changelog
-
-## 2.11.2 - 2026-08-11
-
-- Fixed `PasswordInput` forwarding native input attributes such as generated
-  form IDs and ARIA metadata to the actual `<input>`, restoring programmatic
-  label association for assistive technology and browser automation.
-
-## 2.11.1 - 2026-08-11
-
-- Fixed `NajmThemeProvider` precedence so an explicit runtime `mode` overrides
-  a preset stored in the design config. An explicit `preset` prop still wins,
-  allowing deliberately fixed-preset subtrees without producing mixed light
-  and dark application surfaces.
-
-## 2.11.0 - 2026-08-10
+# Changelog
+
+## 2.11.4 - 2026-08-12
+
+- Fixed server-paginated card grids briefly rendering at a placeholder-derived
+  page size before correcting to the real card height. Card mode now waits for
+  real rows and publishes the measured fit before their first paint; fixed-row
+  table sizing remains immediate during loading.
+
+## 2.11.3 - 2026-08-12
+
+- Fixed `NTable` replacing or clipping an explicit Rows/page choice when
+  `dynamicHeight` was enabled. Automatic fit sizing still owns the initial page
+  size; after the reader chooses a value, the table preserves it and scrolls
+  its bounded body when the requested rows exceed the measured fit.
+
+## 2.11.2 - 2026-08-11
+
+- Fixed `PasswordInput` forwarding native input attributes such as generated
+  form IDs and ARIA metadata to the actual `<input>`, restoring programmatic
+  label association for assistive technology and browser automation.
+
+## 2.11.1 - 2026-08-11
+
+- Fixed `NajmThemeProvider` precedence so an explicit runtime `mode` overrides
+  a preset stored in the design config. An explicit `preset` prop still wins,
+  allowing deliberately fixed-preset subtrees without producing mixed light
+  and dark application surfaces.
+
+## 2.11.0 - 2026-08-10
 
 - Gave every keyboard-focusable primitive a visible focus ring, from one shared
   source: `focusRingClasses` and `focusRingWithinClasses`, exported from the

package/README.md

@@ -730,6 +730,9 @@ 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.
+The measured fit owns the initial page size. Once a reader explicitly chooses
+Rows/page, `NTable` preserves that choice and scrolls the bounded table body
+when the requested rows exceed the available height.
 
 Use `cardPagination` to choose pagination presentation whenever the effective
 rendered mode is cards:

package/dist/index.d.ts

@@ -2969,10 +2969,13 @@ interface TableState {
         pageIndex: number;
         pageSize: number;
     }) => void) | null;
+    /** True after the reader explicitly chooses a Rows/page value. */
+    isPageSizeUserSelected: boolean;
     setPagination: (pagination: {
         pageIndex: number;
         pageSize: number;
     }) => void;
+    setPageSizeFromUser: (pageSize: number) => void;
     hasSyncedPaginationFromProps: boolean;
     rowSelection: Record<string, boolean>;
     isRowSelectionControlled: boolean;
@@ -3110,10 +3113,12 @@ declare const createTableStore: (seed?: Partial<TableState>) => {
             pageIndex: number;
             pageSize: number;
         }) => void;
+        isPageSizeUserSelected: () => boolean;
         setPagination: () => (pagination: {
             pageIndex: number;
             pageSize: number;
         }) => void;
+        setPageSizeFromUser: () => (pageSize: number) => void;
         hasSyncedPaginationFromProps: () => boolean;
         rowSelection: () => Record<string, boolean>;
         isRowSelectionControlled: () => boolean;
@@ -3606,10 +3611,12 @@ declare const TableStoreContext: React$1.Context<{
             pageIndex: number;
             pageSize: number;
         }) => void;
+        isPageSizeUserSelected: () => boolean;
         setPagination: () => (pagination: {
             pageIndex: number;
             pageSize: number;
         }) => void;
+        setPageSizeFromUser: () => (pageSize: number) => void;
         hasSyncedPaginationFromProps: () => boolean;
         rowSelection: () => Record<string, boolean>;
         isRowSelectionControlled: () => boolean;
@@ -3742,10 +3749,12 @@ declare function useStoreSync(props: any): {
             pageIndex: number;
             pageSize: number;
         }) => void;
+        isPageSizeUserSelected: () => boolean;
         setPagination: () => (pagination: {
             pageIndex: number;
             pageSize: number;
         }) => void;
+        setPageSizeFromUser: () => (pageSize: number) => void;
         hasSyncedPaginationFromProps: () => boolean;
         rowSelection: () => Record<string, boolean>;
         isRowSelectionControlled: () => boolean;

package/dist/index.mjs

@@ -11645,7 +11645,8 @@ var createTableStore = (seed) => {
       pagination: { pageIndex: 0, pageSize: 10 },
       isPaginationControlled: false,
       onPaginationChange: null,
-      // User-intent setter for pagination
+      isPageSizeUserSelected: false,
+      // Pagination navigation and automatic sizing.
       setPagination: (pagination) => {
         const { isPaginationControlled, onPaginationChange } = get();
         onPaginationChange?.(pagination);
@@ -11653,6 +11654,18 @@ var createTableStore = (seed) => {
           set({ pagination });
         }
       },
+      // Rows/page is an explicit request to render that many rows. Keep the
+      // bounded NTable body as the scroll viewport instead of letting the
+      // dynamic fit measurement replace the reader's choice.
+      setPageSizeFromUser: (pageSize) => {
+        const { isPaginationControlled, onPaginationChange } = get();
+        const next = { pageIndex: 0, pageSize };
+        set({
+          isPageSizeUserSelected: true,
+          ...!isPaginationControlled ? { pagination: next } : {}
+        });
+        onPaginationChange?.(next);
+      },
       // Track if we've ever synced pagination from props
       hasSyncedPaginationFromProps: false,
       // Row selection
@@ -11871,6 +11884,12 @@ function calculateCardPageSize(input) {
   const rows = Math.max(1, Math.floor((input.bodyHeight + gap) / (cardHeight + gap)));
   return rows * columns;
 }
+function shouldDeferCardPageSizeUntilRows(renderedMode, hasDataRows) {
+  return renderedMode === "cards" && !hasDataRows;
+}
+function shouldCommitDynamicPageSizeImmediately(reportedMode, renderedMode) {
+  return reportedMode === null || reportedMode !== renderedMode;
+}
 function fallbackCardColumns(width) {
   if (width >= 1280) return 4;
   if (width >= 1024) return 3;
@@ -11884,6 +11903,7 @@ function useDynamicPageSize(containerRef, effectiveViewMode) {
   const isLoading = useTableStore.use.isLoading();
   const error = useTableStore.use.error();
   const hasNoData = useTableStore.use.hasNoData();
+  const hasDataRows = useTableStore.use.hasData();
   const isFilteredEmpty = useTableStore.use.isFilteredEmpty();
   const syncWithProps = useTableStore.use.syncWithProps();
   const lastMeasurementRef = useRef("");
@@ -11920,7 +11940,8 @@ function useDynamicPageSize(containerRef, effectiveViewMode) {
       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 cardPageSize = calculateCardPageSize({
+      const measuredMode = effectiveViewMode ?? viewMode;
+      const cardPageSize = shouldDeferCardPageSizeUntilRows(measuredMode, hasDataRows) ? 0 : calculateCardPageSize({
         bodyHeight,
         columnCount: cardColumnCount,
         cardHeight: cardRowHeight,
@@ -11962,7 +11983,7 @@ function useDynamicPageSize(containerRef, effectiveViewMode) {
     ).forEach((el) => resizeObserver.observe(el));
     if (container.parentElement) resizeObserver.observe(container.parentElement);
     return () => resizeObserver.disconnect();
-  }, [dynamicHeight, effectiveViewMode, viewMode, containerRef, syncWithProps, manualPagination, isLoading, error, hasNoData, isFilteredEmpty]);
+  }, [dynamicHeight, effectiveViewMode, viewMode, containerRef, syncWithProps, manualPagination, isLoading, error, hasNoData, hasDataRows, isFilteredEmpty]);
 }
 function useTable(effectiveViewModeOverride) {
   const [sorting, setSorting] = useState([]);
@@ -11997,6 +12018,7 @@ function useTable(effectiveViewModeOverride) {
   const rowCount = useTableStore.use.rowCount();
   const storePagination = useTableStore.use.pagination();
   const isPaginationControlled = useTableStore.use.isPaginationControlled();
+  const isPageSizeUserSelected = useTableStore.use.isPageSizeUserSelected();
   const setPagination = useTableStore.use.setPagination();
   const storeRowSelection = useTableStore.use.rowSelection();
   const setRowSelection = useTableStore.use.setRowSelection();
@@ -12115,34 +12137,31 @@ function useTable(effectiveViewModeOverride) {
     syncWithProps({ table });
   }, [table]);
   useLayoutEffect(() => {
-    if (manualPagination || isPaginationControlled) return;
+    if (manualPagination || isPaginationControlled || isPageSizeUserSelected) 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, isPaginationControlled]);
+  }, [calculatedPageSize, dynamicHeight, renderedMode, viewMode, cardPagination.mode, table, data.length, manualPagination, isPaginationControlled, isPageSizeUserSelected]);
   const dynamicPageSizeTarget = renderedMode === "cards" ? calculatedCardPageSize : calculatedPageSize;
   const geometryKey = `${Math.round(measuredBodyWidth / GEOMETRY_BUCKET_PX)}x${Math.round(measuredBodyHeight / GEOMETRY_BUCKET_PX)}`;
   const reportedGeometryRef = useRef(null);
   useLayoutEffect(() => {
-    if (!manualPagination || !dynamicHeight) return;
+    if (!manualPagination || !dynamicHeight || isPageSizeUserSelected) return;
     if (cardPagination.mode !== "paged") return;
     if (!hasMeasuredLayout || measuredBodyHeight <= 0) return;
     if (!dynamicPageSizeTarget || dynamicPageSizeTarget < 1) return;
     if (dynamicPageSizeTarget === storePagination.pageSize) return;
+    if (shouldDeferCardPageSizeUntilRows(renderedMode, hasDataRows)) return;
     const reported = reportedGeometryRef.current;
-    if (reported?.key === geometryKey && reported.target === dynamicPageSizeTarget) return;
-    if (reported?.key === geometryKey && reported.count >= MAX_PAGE_SIZE_REPORTS_PER_GEOMETRY) return;
+    if (reported?.key === geometryKey && reported.mode === renderedMode && reported.target === dynamicPageSizeTarget) return;
+    if (reported?.key === geometryKey && reported.mode === renderedMode && reported.count >= MAX_PAGE_SIZE_REPORTS_PER_GEOMETRY) return;
     const commit = () => {
       const current = reportedGeometryRef.current;
-      reportedGeometryRef.current = current?.key === geometryKey ? { key: geometryKey, count: current.count + 1, target: dynamicPageSizeTarget } : { key: geometryKey, count: 1, target: dynamicPageSizeTarget };
+      reportedGeometryRef.current = current?.key === geometryKey && current.mode === renderedMode ? { key: geometryKey, count: current.count + 1, target: dynamicPageSizeTarget, mode: renderedMode } : { key: geometryKey, count: 1, target: dynamicPageSizeTarget, mode: renderedMode };
       setPagination({ pageIndex: storePagination.pageIndex, pageSize: dynamicPageSizeTarget });
     };
-    if (!hasDataRows) {
-      commit();
-      return;
-    }
-    if (!reported) {
+    if (shouldCommitDynamicPageSizeImmediately(reported?.mode ?? null, renderedMode)) {
       commit();
       return;
     }
@@ -12151,6 +12170,7 @@ function useTable(effectiveViewModeOverride) {
   }, [
     manualPagination,
     dynamicHeight,
+    isPageSizeUserSelected,
     cardPagination.mode,
     hasMeasuredLayout,
     measuredBodyHeight,
@@ -12158,6 +12178,7 @@ function useTable(effectiveViewModeOverride) {
     dynamicPageSizeTarget,
     storePagination.pageIndex,
     storePagination.pageSize,
+    renderedMode,
     hasDataRows,
     setPagination
   ]);
@@ -12357,6 +12378,8 @@ function NTableContent({ effectiveMode }) {
   const contentCardPagination = useTableStore.use.cardPagination();
   const contentCalculatedPageSize = useTableStore.use.calculatedPageSize();
   const contentHasMeasuredLayout = useTableStore.use.hasMeasuredLayout();
+  const isPageSizeUserSelected = useTableStore.use.isPageSizeUserSelected();
+  const contentPagination = useTableStore.use.pagination();
   const hasNoData = useTableStore.use.hasNoData();
   const showContent = useTableStore.use.showContent();
   const classNames = useTableStore.use.classNames();
@@ -12379,8 +12402,9 @@ function NTableContent({ effectiveMode }) {
   const isTableView = effectiveMode ? effectiveMode === "table" : storeIsTableView;
   if (!isTableView) return null;
   const allRows = table.getRowModel().rows ?? [];
-  const clampRowsToMeasuredPage = contentDynamicHeight && contentManualPagination && contentCardPagination.mode === "paged" && contentHasMeasuredLayout && contentCalculatedPageSize > 0;
+  const clampRowsToMeasuredPage = contentDynamicHeight && contentManualPagination && !isPageSizeUserSelected && contentCardPagination.mode === "paged" && contentHasMeasuredLayout && contentCalculatedPageSize > 0;
   const visibleRows = clampRowsToMeasuredPage ? allRows.slice(0, contentCalculatedPageSize) : allRows;
+  const userPageNeedsScroll = isPageSizeUserSelected && contentPagination.pageSize > contentCalculatedPageSize;
   const getSortIcon = (column) => {
     const dir = column.getIsSorted();
     if (dir === "asc") return /* @__PURE__ */ jsx(ArrowUp, { className: "h-4 w-4" });
@@ -12402,7 +12426,7 @@ function NTableContent({ effectiveMode }) {
         // leftover belongs to the page, not to the table. Without
         // `dynamicHeight` the row count is the caller's, so the container has
         // to keep filling its height to stay a scroll viewport.
-        contentDynamicHeight ? "max-h-full shrink" : "flex-1",
+        contentDynamicHeight && !userPageNeedsScroll ? "max-h-full shrink" : "flex-1",
         surface.className,
         classNames?.content
       ),
@@ -13333,6 +13357,7 @@ function NTablePagination() {
   const rowCount = useTableStore.use.rowCount();
   const suppliedHasNextPage = useTableStore.use.hasNextPage();
   const setPagination = useTableStore.use.setPagination();
+  const setPageSizeFromUser = useTableStore.use.setPageSizeFromUser();
   const isPaginationControlled = useTableStore.use.isPaginationControlled();
   const bordered = useTableStore.use.bordered();
   const paginationVariant = useTableStore.use.paginationVariant();
@@ -13380,7 +13405,7 @@ function NTablePagination() {
   };
   const handlePageSizeChange = (value) => {
     const newSize = Number(value);
-    setPagination({ pageIndex: 0, pageSize: newSize });
+    setPageSizeFromUser(newSize);
   };
   const hasTrustworthyPageCount = manualPagination ? pageCount !== void 0 && pageCount > 0 || unbounded : effectivePageCount > 0;
   const showNumbers = paginationVariant === "numbered" && hasTrustworthyPageCount;

package/dist/theme.css

@@ -307,10 +307,10 @@ 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 {
@@ -367,7 +367,7 @@ input:autofill {
   .nimage-input-compact-overlay:focus-visible {
     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,6 +1,6 @@
 {
   "name": "najm-kit",
-  "version": "2.11.2",
+  "version": "2.11.4",
   "license": "MIT",
   "type": "module",
   "description": "Reusable React UI component package for Najm framework",