najm-kit 2.2.2 → 2.2.4

package/dist/index.d.ts

@@ -2875,6 +2875,8 @@ interface TableState {
     isRefreshing: boolean;
     dynamicHeight: boolean;
     CardComponent: ComponentType<any> | null;
+    /** Placeholder shaped like `CardComponent`; see `renderCardSkeleton`. */
+    CardSkeletonComponent: ComponentType<any> | null;
     className: string;
     classNames: NTableClassNames;
     bordered?: boolean;
@@ -3014,6 +3016,7 @@ declare const createTableStore: (seed?: Partial<TableState>) => {
         isRefreshing: () => boolean;
         dynamicHeight: () => boolean;
         CardComponent: () => ComponentType<any>;
+        CardSkeletonComponent: () => ComponentType<any>;
         className: () => string;
         classNames: () => NTableClassNames;
         bordered?: () => boolean;
@@ -3199,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;
@@ -3435,6 +3464,7 @@ declare const TableStoreContext: React$1.Context<{
         isRefreshing: () => boolean;
         dynamicHeight: () => boolean;
         CardComponent: () => React$1.ComponentType<any>;
+        CardSkeletonComponent: () => React$1.ComponentType<any>;
         className: () => string;
         classNames: () => NTableClassNames;
         bordered?: () => boolean;
@@ -3567,6 +3597,7 @@ declare function useStoreSync(props: any): {
         isRefreshing: () => boolean;
         dynamicHeight: () => boolean;
         CardComponent: () => React__default.ComponentType<any>;
+        CardSkeletonComponent: () => React__default.ComponentType<any>;
         className: () => string;
         classNames: () => NTableClassNames;
         bordered?: () => boolean;

package/dist/index.mjs

@@ -12183,6 +12183,7 @@ var createTableStore = (seed) => {
       getRowId: null,
       renderToolbar: null,
       CardComponent: null,
+      CardSkeletonComponent: null,
       className: "",
       classNames: {},
       bordered: void 0,
@@ -12492,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) {
@@ -12726,11 +12729,12 @@ function useTable(effectiveViewModeOverride) {
     if (dynamicPageSizeTarget === storePagination.pageSize) return;
     const reported = reportedGeometryRef.current;
     if (reported?.key === geometryKey && reported.count >= MAX_PAGE_SIZE_REPORTS_PER_GEOMETRY) return;
+    const delay = reported ? DYNAMIC_PAGE_SIZE_DEBOUNCE_MS : 0;
     const timer = setTimeout(() => {
       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);
+    }, delay);
     return () => clearTimeout(timer);
   }, [
     manualPagination,
@@ -13207,6 +13211,7 @@ function NDataCardShell({ row, onClick, onContextMenu, actions, children, classN
   );
 }
 var DEFAULT_ROWS2 = 6;
+var UNMEASURED_DYNAMIC_ROWS = 32;
 var DEFAULT_CARD_COUNT = 48;
 function NTableCardSkeleton({ surface }) {
   return /* @__PURE__ */ jsx(
@@ -13353,7 +13358,7 @@ function NTableLoadingSkeleton({ rows }) {
   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 rowCount = rows ?? (dynamicHeight ? bodyHeight > 0 ? skeletonRowCount : UNMEASURED_DYNAMIC_ROWS : 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, {}),
@@ -13423,6 +13428,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,
@@ -13451,7 +13457,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))
             }
           )
         ]
@@ -13561,6 +13567,7 @@ 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();
   useTableStore.use.isLoading();
   const error = useTableStore.use.error();
@@ -13702,7 +13709,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",
@@ -14316,7 +14323,10 @@ function TableLayout(props) {
         "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() }) : effectiveMode === "table" ? /* @__PURE__ */ jsx(NTableLoadingSkeleton, {}) : effectiveMode === "cards" ? /* @__PURE__ */ jsx(NTableCardsLoadingSkeleton, {}) : /* @__PURE__ */ jsx(NTableLoadingSkeleton, {})),
+          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 }) }),
@@ -14420,6 +14430,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),
@@ -14501,6 +14512,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.2",
+  "version": "2.2.4",
   "license": "MIT",
   "type": "module",
   "description": "Reusable React UI component package for Najm framework",