najm-kit 2.2.9 → 2.4.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 2.3.0
+
+- `NTablePagination` renders numbered page buttons instead of `Page X of Y`. The window shows the first and last page, the current page, and one page either side, collapsing the rest into at most two gaps. The slot count is constant for any result longer than the window, so the bar does not change width as the reader pages through it, and a gap never stands in for a single page — that slot goes to the page instead.
+- Added `paginationVariant`, defaulting to `"numbered"`. Pass `"compact"` to keep the previous position text with first/previous/next/last controls. **This changes the default appearance of every paginated `NTable`.**
+- The numbered variant drops the first/last double chevrons, because page 1 and page N are now single-click targets of their own. Previous and next remain. The compact variant is unchanged.
+- Numbered pages fall back to compact on their own when the page count is not trustworthy — that is, under `manualPagination` with no `pageCount` supplied, where TanStack infers a count from the rows it happens to hold rather than from a result total. Numbering that would invite clicks on pages that may not exist is not rendered.
+- Below the `sm` breakpoint the numbers give way to the position text; seven page buttons plus the rows-per-page select do not fit a phone.
+- Added `paginationLabels` so the bar can be localized: `rowsPerPage`, `pagination`, `goToPage`, `currentPage`, `firstPage`, `previousPage`, `nextPage`, `lastPage`, `pageOf`, and `rowsSelected`. All optional, all falling back to the previous English strings.
+- Pagination chevrons now mirror under `dir="rtl"`. They previously pointed against the reading direction in right-to-left layouts.
+- The page controls are wrapped in a labelled `nav`, and the current page carries `aria-current="page"`.
+- Exported `buildPageItems` and `NTablePageItem` for consumers that need the same windowing outside the table.
+
 ## 2.2.1
 
 - Fixed a regression in 2.2.0: the dynamic page size reported under `manualPagination` could oscillate. Card row height is measured from rendered cards, so it grows as images decode; feeding that back into the page size refetched, re-rendered, re-measured, and refetched again. A list visibly settled from one page size to another with the loading skeleton flashing twice. The report is now allowed once per container geometry, which does not depend on the rows inside it, so it terminates. A resize still re-arms it, and the debounce still waits for the measurement to settle before reporting.

package/dist/index.d.ts

@@ -2771,6 +2771,42 @@ type StepSubmitResult = {
 };
 declare function useFormSubmission({ steps, schema, defaultValues, onSubmit, currentStep, isLastStep, handleNext, markStepCompleted, reset, }: UseFormSubmissionOptions): FormSubmissionState;
 
+/**
+ * How the page controls present position within the result.
+ *
+ * `numbered` renders a windowed list of page buttons. `compact` renders the
+ * `Page X of Y` text with first/previous/next/last controls.
+ *
+ * `numbered` needs a trustworthy page count. Under `manualPagination` that
+ * means the application must pass a `pageCount` derived from a real result
+ * total; without one, the bar falls back to `compact` on its own rather than
+ * inviting clicks on pages that may not exist.
+ */
+type NTablePaginationVariant = "numbered" | "compact";
+/**
+ * Accessible names and visible copy for the page controls.
+ *
+ * Every field is optional and falls back to English. Supply them to localize —
+ * the numbered variant is mostly digits, but its controls still need names.
+ */
+interface NTablePaginationLabels {
+    /** Labels the rows-per-page select. Defaults to `"Rows/page"`. */
+    rowsPerPage?: string;
+    /** Accessible name of the whole page control group. Defaults to `"Pagination"`. */
+    pagination?: string;
+    /** Accessible name for one page button, given a 1-based page. */
+    goToPage?: (page: number) => string;
+    /** Accessible name of the current page button, given a 1-based page. */
+    currentPage?: (page: number) => string;
+    firstPage?: string;
+    previousPage?: string;
+    nextPage?: string;
+    lastPage?: string;
+    /** The `compact` variant's position text, given 1-based values. */
+    pageOf?: (page: number, pageCount: number) => string;
+    /** The selection summary, given selected and total row counts. */
+    rowsSelected?: (selected: number, total: number) => string;
+}
 interface NTableLoadMorePagination {
     /** Render the supplied rows as one card list with an explicit continuation control. */
     mode: "load-more";
@@ -2933,6 +2969,8 @@ interface TableState {
     availableModes: readonly ViewMode[];
     setViewMode: (mode: ViewMode) => void;
     hasSyncedFromProps: boolean;
+    paginationVariant: NTablePaginationVariant;
+    paginationLabels: NTablePaginationLabels;
     manualPagination: boolean;
     pageCount: number | undefined;
     rowCount: number | undefined;
@@ -3071,6 +3109,8 @@ declare const createTableStore: (seed?: Partial<TableState>) => {
         availableModes: () => readonly ViewMode[];
         setViewMode: () => (mode: ViewMode) => void;
         hasSyncedFromProps: () => boolean;
+        paginationVariant: () => NTablePaginationVariant;
+        paginationLabels: () => NTablePaginationLabels;
         manualPagination: () => boolean;
         pageCount: () => number;
         rowCount: () => number;
@@ -3262,6 +3302,14 @@ interface NTableProps<T = any, M extends ViewMode = ViewMode> {
     }) => void;
     /** Pagination presentation used whenever NTable is actually rendering cards. */
     cardPagination?: NTableCardPagination;
+    /**
+     * How the page controls present position. Defaults to `"numbered"`, which
+     * falls back to `"compact"` on its own when the page count is not
+     * trustworthy. Pass `"compact"` for the `Page X of Y` text everywhere.
+     */
+    paginationVariant?: NTablePaginationVariant;
+    /** Accessible names and visible copy for the page controls. */
+    paginationLabels?: NTablePaginationLabels;
     rowSelection?: RowSelectionState;
     defaultRowSelection?: RowSelectionState;
     onRowSelectionChange?: (state: RowSelectionState) => void;
@@ -3519,6 +3567,8 @@ declare const TableStoreContext: React$1.Context<{
         availableModes: () => readonly ViewMode[];
         setViewMode: () => (mode: ViewMode) => void;
         hasSyncedFromProps: () => boolean;
+        paginationVariant: () => NTablePaginationVariant;
+        paginationLabels: () => NTablePaginationLabels;
         manualPagination: () => boolean;
         pageCount: () => number;
         rowCount: () => number;
@@ -3652,6 +3702,8 @@ declare function useStoreSync(props: any): {
         availableModes: () => readonly ViewMode[];
         setViewMode: () => (mode: ViewMode) => void;
         hasSyncedFromProps: () => boolean;
+        paginationVariant: () => NTablePaginationVariant;
+        paginationLabels: () => NTablePaginationLabels;
         manualPagination: () => boolean;
         pageCount: () => number;
         rowCount: () => number;

package/dist/index.mjs

@@ -12222,6 +12222,8 @@ var createTableStore = (seed) => {
       hasMeasuredLayout: false,
       skeletonRowCount: 6,
       maxHeight: null,
+      paginationVariant: "numbered",
+      paginationLabels: {},
       bodyWidth: 0,
       bodyHeight: 0,
       tableHeaderHeight: 48,
@@ -13728,6 +13730,51 @@ function NTableCards({ effectiveMode }) {
     ) : null
   ] });
 }
+
+// src/components/table/paginationPages.ts
+function buildPageItems(pageIndex, pageCount, siblingCount = 1) {
+  const pages = Math.max(0, Math.floor(pageCount));
+  if (pages <= 0) return [];
+  const current = Math.min(Math.max(0, Math.floor(pageIndex)), pages - 1);
+  const siblings = Math.max(0, Math.floor(siblingCount));
+  const lastIndex = pages - 1;
+  const windowSize = siblings * 2 + 5;
+  if (pages <= windowSize) {
+    return range(0, lastIndex);
+  }
+  const left = Math.max(current - siblings, 0);
+  const right = Math.min(current + siblings, lastIndex);
+  const showStartGap = left - 1 >= 2;
+  const showEndGap = lastIndex - 1 - right >= 2;
+  const runLength = siblings * 2 + 3;
+  if (!showStartGap && showEndGap) {
+    return [
+      ...range(0, runLength - 1),
+      { type: "gap", key: "end" },
+      page(lastIndex)
+    ];
+  }
+  if (showStartGap && !showEndGap) {
+    return [
+      page(0),
+      { type: "gap", key: "start" },
+      ...range(lastIndex - runLength + 1, lastIndex)
+    ];
+  }
+  return [
+    page(0),
+    { type: "gap", key: "start" },
+    ...range(left, right),
+    { type: "gap", key: "end" },
+    page(lastIndex)
+  ];
+}
+function page(pageIndex) {
+  return { type: "page", pageIndex };
+}
+function range(from, to) {
+  return Array.from({ length: to - from + 1 }, (_, index) => page(from + index));
+}
 function CardLoadMorePagination({
   config,
   rowCount,
@@ -13821,6 +13868,44 @@ function CardLoadMorePagination({
     }
   );
 }
+var navButtonClass = "h-8 w-8 p-0 text-foreground disabled:text-muted-foreground disabled:opacity-70";
+var chevronClass = "h-4 w-4 rtl:-scale-x-100";
+function PageNumbers({
+  pageIndex,
+  pageCount,
+  bordered,
+  labels,
+  onSelect
+}) {
+  return /* @__PURE__ */ jsx(Fragment, { children: buildPageItems(pageIndex, pageCount).map((item) => {
+    if (item.type === "gap") {
+      return /* @__PURE__ */ jsx(
+        "span",
+        {
+          "aria-hidden": "true",
+          className: "flex h-8 w-8 items-center justify-center text-sm text-muted-foreground",
+          children: "\u2026"
+        },
+        `gap-${item.key}`
+      );
+    }
+    const page2 = item.pageIndex + 1;
+    const isCurrent = item.pageIndex === pageIndex;
+    return /* @__PURE__ */ jsx(
+      Button,
+      {
+        bordered,
+        variant: isCurrent ? "default" : "outline",
+        className: cn(navButtonClass, "tabular-nums"),
+        "aria-label": isCurrent ? labels.currentPage?.(page2) ?? `Page ${page2}, current page` : labels.goToPage?.(page2) ?? `Go to page ${page2}`,
+        "aria-current": isCurrent ? "page" : void 0,
+        onClick: () => onSelect(item.pageIndex),
+        children: page2
+      },
+      item.pageIndex
+    );
+  }) });
+}
 function NTablePagination() {
   const table = useTableStore.use.table();
   const showPagination = useTableStore.use.showPagination();
@@ -13837,6 +13922,8 @@ function NTablePagination() {
   const setPagination = useTableStore.use.setPagination();
   const isPaginationControlled = useTableStore.use.isPaginationControlled();
   const bordered = useTableStore.use.bordered();
+  const paginationVariant = useTableStore.use.paginationVariant();
+  const labels = useTableStore.use.paginationLabels();
   if (!showPagination || effectiveViewMode === "json" || effectiveViewMode === "files") return null;
   if (cardPagination.mode === "all") return null;
   if (effectiveViewMode === "cards" && cardPagination.mode === "infinite") return null;
@@ -13879,10 +13966,15 @@ function NTablePagination() {
     const newSize = Number(value);
     setPagination({ pageIndex: 0, pageSize: newSize });
   };
+  const hasTrustworthyPageCount = manualPagination ? pageCount !== void 0 && pageCount > 0 : effectivePageCount > 0;
+  const showNumbers = paginationVariant === "numbered" && hasTrustworthyPageCount;
+  const canPrevious = (table?.getCanPreviousPage?.() ?? pageIndex > 0) && pageIndex > 0;
+  const canNext = (table?.getCanNextPage?.() ?? true) && pageIndex < effectivePageCount - 1;
+  const selectedTotal = manualPagination && rowCount !== void 0 ? rowCount : filteredRows.length;
   return /* @__PURE__ */ jsxs("div", { className: cn("flex w-full min-w-0 flex-wrap items-center justify-between gap-x-4 gap-y-2 py-1 text-foreground", classNames?.pagination), children: [
     /* @__PURE__ */ jsxs("div", { className: "flex min-w-0 flex-1 flex-wrap items-center gap-4 lg:gap-6", children: [
       (!isPaginationControlled || manualPagination) && /* @__PURE__ */ jsxs("div", { className: "flex items-center gap-2 text-foreground", children: [
-        /* @__PURE__ */ jsx("p", { className: "text-sm font-medium text-foreground", children: "Rows/page" }),
+        /* @__PURE__ */ jsx("p", { className: "text-sm font-medium text-foreground", children: labels.rowsPerPage ?? "Rows/page" }),
         /* @__PURE__ */ jsxs(Select, { value: `${pageSize}`, onValueChange: handlePageSizeChange, children: [
           /* @__PURE__ */ jsx(
             SelectTrigger,
@@ -13895,25 +13987,32 @@ function NTablePagination() {
           /* @__PURE__ */ jsx(SelectContent, { side: "top", children: currentPageSizeOptions.map((size) => /* @__PURE__ */ jsx(SelectItem, { value: `${size}`, children: size }, size)) })
         ] })
       ] }),
-      /* @__PURE__ */ jsxs("div", { className: "text-sm font-medium text-foreground", children: [
-        "Page ",
-        pageIndex + 1,
-        " of ",
-        effectivePageCount
-      ] }),
-      /* @__PURE__ */ jsxs("div", { className: "flex items-center gap-2", children: [
-        /* @__PURE__ */ jsx(Button, { bordered, variant: "outline", className: "hidden h-8 w-8 p-0 text-foreground disabled:text-muted-foreground disabled:opacity-70 lg:flex", "aria-label": "First page", onClick: () => navigate("first"), disabled: !table?.getCanPreviousPage?.() || pageIndex === 0, children: /* @__PURE__ */ jsx(ChevronsLeft, { className: "h-4 w-4" }) }),
-        /* @__PURE__ */ jsx(Button, { bordered, variant: "outline", className: "h-8 w-8 p-0 text-foreground disabled:text-muted-foreground disabled:opacity-70", "aria-label": "Previous", onClick: () => navigate("prev"), disabled: !table?.getCanPreviousPage?.() || pageIndex === 0, children: /* @__PURE__ */ jsx(ChevronLeft, { className: "h-4 w-4" }) }),
-        /* @__PURE__ */ jsx(Button, { bordered, variant: "outline", className: "h-8 w-8 p-0 text-foreground disabled:text-muted-foreground disabled:opacity-70", "aria-label": "Next", onClick: () => navigate("next"), disabled: !table?.getCanNextPage?.() || pageIndex >= effectivePageCount - 1, children: /* @__PURE__ */ jsx(ChevronRight, { className: "h-4 w-4" }) }),
-        /* @__PURE__ */ jsx(Button, { bordered, variant: "outline", className: "hidden h-8 w-8 p-0 text-foreground disabled:text-muted-foreground disabled:opacity-70 lg:flex", "aria-label": "Last page", onClick: () => navigate("last"), disabled: !table?.getCanNextPage?.() || pageIndex >= effectivePageCount - 1, children: /* @__PURE__ */ jsx(ChevronsRight, { className: "h-4 w-4" }) })
-      ] })
+      /* @__PURE__ */ jsx("div", { className: cn("text-sm font-medium text-foreground", showNumbers && "sm:hidden"), children: labels.pageOf?.(pageIndex + 1, effectivePageCount) ?? `Page ${pageIndex + 1} of ${effectivePageCount}` }),
+      /* @__PURE__ */ jsxs(
+        "nav",
+        {
+          "aria-label": labels.pagination ?? "Pagination",
+          className: "flex items-center gap-2",
+          children: [
+            !showNumbers && /* @__PURE__ */ jsx(Button, { bordered, variant: "outline", className: cn(navButtonClass, "hidden lg:flex"), "aria-label": labels.firstPage ?? "First page", onClick: () => navigate("first"), disabled: !canPrevious, children: /* @__PURE__ */ jsx(ChevronsLeft, { className: chevronClass }) }),
+            /* @__PURE__ */ jsx(Button, { bordered, variant: "outline", className: navButtonClass, "aria-label": labels.previousPage ?? "Previous", onClick: () => navigate("prev"), disabled: !canPrevious, children: /* @__PURE__ */ jsx(ChevronLeft, { className: chevronClass }) }),
+            showNumbers && /* @__PURE__ */ jsx("div", { className: "hidden items-center gap-2 sm:flex", children: /* @__PURE__ */ jsx(
+              PageNumbers,
+              {
+                pageIndex,
+                pageCount: effectivePageCount,
+                bordered,
+                labels,
+                onSelect: (next) => setPagination({ ...currentPagination, pageIndex: next })
+              }
+            ) }),
+            /* @__PURE__ */ jsx(Button, { bordered, variant: "outline", className: navButtonClass, "aria-label": labels.nextPage ?? "Next", onClick: () => navigate("next"), disabled: !canNext, children: /* @__PURE__ */ jsx(ChevronRight, { className: chevronClass }) }),
+            !showNumbers && /* @__PURE__ */ jsx(Button, { bordered, variant: "outline", className: cn(navButtonClass, "hidden lg:flex"), "aria-label": labels.lastPage ?? "Last page", onClick: () => navigate("last"), disabled: !canNext, children: /* @__PURE__ */ jsx(ChevronsRight, { className: chevronClass }) })
+          ]
+        }
+      )
     ] }),
-    /* @__PURE__ */ jsxs("div", { className: "min-w-0 flex-none whitespace-nowrap text-sm text-muted-foreground max-sm:hidden", children: [
-      selectedRows.length,
-      " of ",
-      manualPagination && rowCount !== void 0 ? rowCount : filteredRows.length,
-      " row(s) selected."
-    ] })
+    /* @__PURE__ */ jsx("div", { className: "min-w-0 flex-none whitespace-nowrap text-sm text-muted-foreground max-sm:hidden", children: labels.rowsSelected?.(selectedRows.length, selectedTotal) ?? `${selectedRows.length} of ${selectedTotal} row(s) selected.` })
   ] });
 }
 function PendingFilter({ placeholder, icon, bordered }) {
@@ -14501,6 +14600,8 @@ function NTable(props) {
     defaultPagination: props.defaultPagination,
     onPaginationChange: props.onPaginationChange ?? null,
     cardPagination: props.cardPagination ?? { mode: "paged" },
+    paginationVariant: props.paginationVariant ?? "numbered",
+    paginationLabels: props.paginationLabels ?? {},
     // Row selection
     rowSelection: props.rowSelection,
     defaultRowSelection: props.defaultRowSelection,

package/package.json

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