@djangocfg/ui-core 2.1.560 → 2.1.562

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/ui-core",
-  "version": "2.1.560",
+  "version": "2.1.562",
   "description": "Pure React UI component library without Next.js dependencies - for Electron, Vite, CRA apps",
   "keywords": [
     "ui-components",
@@ -126,11 +126,11 @@
   ],
   "scripts": {
     "lint": "eslint .",
-    "check": "tsc --noEmit",
+    "check": "tsc --noEmit && node scripts/check-preset-contrast.mjs",
     "check:contrast": "node scripts/check-preset-contrast.mjs"
   },
   "peerDependencies": {
-    "@djangocfg/i18n": "^2.1.560",
+    "@djangocfg/i18n": "^2.1.562",
     "consola": "^3.4.2",
     "lucide-react": "^0.545.0",
     "moment": "^2.30.1",
@@ -206,9 +206,9 @@
     "vaul": "1.1.2"
   },
   "devDependencies": {
-    "@djangocfg/eslint-config": "^2.1.560",
-    "@djangocfg/i18n": "^2.1.560",
-    "@djangocfg/typescript-config": "^2.1.560",
+    "@djangocfg/eslint-config": "^2.1.562",
+    "@djangocfg/i18n": "^2.1.562",
+    "@djangocfg/typescript-config": "^2.1.562",
     "@storybook/react-vite": "^10.5.0",
     "@types/node": "^24.13.3",
     "@types/react": "19.2.15",

package/src/components/navigation/pagination/pagination-static.tsx

@@ -10,7 +10,9 @@
 import { ChevronLeft, ChevronRight } from 'lucide-react';
 import React from 'react';
 
-import { cn } from '../../../lib';
+import { useAppT, useI18n } from '@djangocfg/i18n';
+
+import { cn, formatNumber } from '../../../lib';
 import { Button } from '../../forms/button';
 import { useIsMobile } from '../../../hooks';
 
@@ -46,6 +48,8 @@ export const StaticPagination: React.FC<StaticPaginationProps> = ({
   maxVisiblePages = 7,
 }) => {
   const isMobile = useIsMobile();
+  const t = useAppT();
+  const { locale } = useI18n();
 
   if (!data || !('count' in data) || !('page' in data) || !('pages' in data)) {
     return null;
@@ -129,11 +133,17 @@ export const StaticPagination: React.FC<StaticPaginationProps> = ({
     <div className={cn("space-y-4", className)}>
       {showInfo && (
         <div className="text-sm text-muted-foreground text-center">
-          {isMobile ? (
-            `Page ${currentPage} of ${totalPages}`
-          ) : (
-            `Showing ${startItem.toLocaleString()} to ${endItem.toLocaleString()} of ${totalItems.toLocaleString()} results`
-          )}
+          {/* Through `ui.pagination.*`, which ships translated in every
+              locale this package supports. The figures are grouped with
+              `toLocaleString(locale)` rather than the host's default, so a
+              German reader sees `1.234` and a French one `1 234`. */}
+          {isMobile
+            ? `${t('ui.pagination.page', { page: currentPage })} ${t('ui.pagination.of', { total: totalPages })}`
+            : t('ui.pagination.showing', {
+                from: formatNumber(startItem, locale),
+                to: formatNumber(endItem, locale),
+                total: formatNumber(totalItems, locale),
+              })}
         </div>
       )}
 
@@ -149,10 +159,9 @@ export const StaticPagination: React.FC<StaticPaginationProps> = ({
                 "gap-1 pl-2.5",
                 !hasPreviousPage && "pointer-events-none opacity-50"
               )}
-              aria-label="Go to previous page"
+              aria-label={t('ui.pagination.previous')}
             >
               <ChevronLeft className="h-4 w-4" />
-              <span>Previous</span>
             </Button>
           </PaginationItem>
 
@@ -170,7 +179,12 @@ export const StaticPagination: React.FC<StaticPaginationProps> = ({
                     page === currentPage && "pointer-events-none"
                   )}
                 >
-                  {page}
+                  {/* GROUPED, not compacted. `34 781` reads; `34781` is
+                      scanned digit by digit. But never `34,8 тыс.` — this is
+                      a destination the reader clicks, and a rounded address
+                      is not an address. Compaction belongs on counts, never
+                      on page numbers. */}
+                  {formatNumber(page, locale)}
                 </Button>
               )}
             </PaginationItem>
@@ -186,9 +200,8 @@ export const StaticPagination: React.FC<StaticPaginationProps> = ({
                 "gap-1 pr-2.5",
                 !hasNextPage && "pointer-events-none opacity-50"
               )}
-              aria-label="Go to next page"
+              aria-label={t('ui.pagination.next')}
             >
-              <span>Next</span>
               <ChevronRight className="h-4 w-4" />
             </Button>
           </PaginationItem>

package/src/components/navigation/pagination/pagination.tsx

@@ -1,6 +1,10 @@
+"use client";
+
 import { ChevronLeft, ChevronRight, MoreHorizontal } from 'lucide-react';
 import * as React from 'react';
 
+import { useAppT } from '@djangocfg/i18n';
+
 import { cn } from '../../../lib';
 import { type ButtonProps, buttonVariants } from '../../forms/button';
 import { Link } from '../link';
@@ -90,36 +94,50 @@ const PaginationLink = ({
 }
 PaginationLink.displayName = "PaginationLink"
 
+/* `ui.pagination.*` has shipped translated in all seventeen locales since
+   this package gained an i18n layer; only these components never read it, so
+   every app using them paginated in English. `useAppT` falls back to the
+   English defaults when no provider is mounted, which is what makes this safe
+   in a 404 or any tree rendered outside the app shell. */
 const PaginationPrevious = ({
   className,
   ...props
-}: React.ComponentProps<typeof PaginationLink>) => (
-  <PaginationLink
-    aria-label="Go to previous page"
-    size="default"
-    className={cn("gap-1 pl-2.5", className)}
-    {...props}
-  >
-    <ChevronLeft className="h-4 w-4" />
-    <span>Previous</span>
-  </PaginationLink>
-)
+}: React.ComponentProps<typeof PaginationLink>) => {
+  const t = useAppT();
+  return (
+    <PaginationLink
+      aria-label={t('ui.pagination.previous')}
+      size="default"
+      className={cn("gap-1", className)}
+      {...props}
+    >
+      {/* ICON ONLY — a chevron pointing back is the settled convention for
+          "previous page"; a word beside it adds nothing a reader needs while
+          adding a string every locale must carry and every layout must fit.
+          The `aria-label` above keeps the name, because a button without one
+          is announced as "button". */}
+      <ChevronLeft className="h-4 w-4" />
+    </PaginationLink>
+  )
+}
 PaginationPrevious.displayName = "PaginationPrevious"
 
 const PaginationNext = ({
   className,
   ...props
-}: React.ComponentProps<typeof PaginationLink>) => (
-  <PaginationLink
-    aria-label="Go to next page"
-    size="default"
-    className={cn("gap-1 pr-2.5", className)}
-    {...props}
-  >
-    <span>Next</span>
-    <ChevronRight className="h-4 w-4" />
-  </PaginationLink>
-)
+}: React.ComponentProps<typeof PaginationLink>) => {
+  const t = useAppT();
+  return (
+    <PaginationLink
+      aria-label={t('ui.pagination.next')}
+      size="default"
+      className={cn("gap-1", className)}
+      {...props}
+    >
+      <ChevronRight className="h-4 w-4" />
+    </PaginationLink>
+  )
+}
 PaginationNext.displayName = "PaginationNext"
 
 const PaginationEllipsis = ({

package/src/components/navigation/pagination/ssr-pagination.tsx

@@ -2,7 +2,9 @@
 
 import React from 'react';
 
-import { cn } from '../../../lib';
+import { useAppT, useI18n } from '@djangocfg/i18n';
+
+import { cn, formatNumber } from '../../../lib';
 import { useIsMobile } from '../../../hooks';
 import { useLocation, useQueryParams } from '../../../hooks/router';
 
@@ -59,6 +61,8 @@ export const SSRPagination: React.FC<SSRPaginationProps> = ({
   const queryParams = useQueryParams();
   const { pathname } = useLocation();
   const isMobile = useIsMobile();
+  const t = useAppT();
+  const { locale } = useI18n();
 
   const getCurrentPageFromUrl = (): number => {
     const pageParam = queryParams.get('page');
@@ -81,6 +85,20 @@ export const SSRPagination: React.FC<SSRPaginationProps> = ({
     return queryString ? `${basePath}?${queryString}` : basePath;
   };
 
+  /* NO "first" / "last" BUTTONS, deliberately.
+   *
+   * `ui.pagination.first` and `.last` exist in the dictionary and nothing
+   * renders them. That is the right outcome, not an omission to finish:
+   *
+   * - The row ALREADY ENDS IN BOTH. `1` is always pushed first and
+   *   `totalPages` always last, so a jump to either end is one click on a
+   *   number the reader can already see. A dedicated button would be a third
+   *   route to a place two already reach.
+   * - "Last" is a destination nobody wants. On a catalogue sorted by date or
+   *   price, page 34,781 is the worst match for the query — the control is
+   *   cheap to build and answers a question no one asks.
+   *
+   * Two chevrons and the numbers. Anything more is furniture. */
   const getVisiblePages = (): (number | 'ellipsis')[] => {
     const mobileMaxVisible = 3;
     const effectiveMaxVisible = isMobile ? mobileMaxVisible : maxVisiblePages;
@@ -129,11 +147,17 @@ export const SSRPagination: React.FC<SSRPaginationProps> = ({
     <div className={cn("space-y-4", className)}>
       {showInfo && (
         <div className="text-sm text-muted-foreground text-center">
-          {isMobile ? (
-            `Page ${actualCurrentPage} of ${totalPages}`
-          ) : (
-            `Showing ${startItem.toLocaleString()} to ${endItem.toLocaleString()} of ${totalItems.toLocaleString()} results`
-          )}
+          {/* Through `ui.pagination.*`, which ships translated in every
+              locale this package supports. The figures are grouped with
+              `toLocaleString(locale)` rather than the host's default, so a
+              German reader sees `1.234` and a French one `1 234`. */}
+          {isMobile
+            ? `${t('ui.pagination.page', { page: actualCurrentPage })} ${t('ui.pagination.of', { total: totalPages })}`
+            : t('ui.pagination.showing', {
+                from: formatNumber(startItem, locale),
+                to: formatNumber(endItem, locale),
+                total: formatNumber(totalItems, locale),
+              })}
         </div>
       )}
 
@@ -157,7 +181,12 @@ export const SSRPagination: React.FC<SSRPaginationProps> = ({
                   isActive={page === actualCurrentPage}
                   scroll
                 >
-                  {page}
+                  {/* GROUPED, not compacted. `34 781` reads; `34781` is
+                      scanned digit by digit. But never `34,8 тыс.` — this is
+                      a destination the reader clicks, and a rounded address
+                      is not an address. Compaction belongs on counts, never
+                      on page numbers. */}
+                  {formatNumber(page, locale)}
                 </PaginationLink>
               )}
             </PaginationItem>

package/src/hooks/index.ts

@@ -66,6 +66,8 @@ export {
   parseAsJson,
   // useRouter (composite facade)
   useRouter,
+  // useScrollToTop (covers the routes Next's own scroll handler skips)
+  useScrollToTop,
 } from './router';
 export type {
   RouterAdapter,
@@ -93,4 +95,5 @@ export type {
   QueryParser,
   QueryParserBuilder,
   UseRouterReturn,
+  UseScrollToTopOptions,
 } from './router';

package/src/hooks/router/index.ts

@@ -22,12 +22,17 @@ export type {
 export {
   useLocation,
   useLocationProperty,
+  patchHistoryOnce,
   NAVIGATE_EVENT,
   PUSH_STATE_EVENT,
   REPLACE_STATE_EVENT,
 } from './useLocation';
 export type { LocationSnapshot } from './useLocation';
 
+// useScrollToTop (fills the gaps in Next's own scroll restoration)
+export { useScrollToTop } from './useScrollToTop';
+export type { UseScrollToTopOptions } from './useScrollToTop';
+
 // useNavigate
 export { useNavigate } from './useNavigate';
 export type { NavigateOptions, UseNavigateReturn } from './useNavigate';

package/src/hooks/router/useLocation.ts

@@ -54,7 +54,16 @@ const SSR_SNAPSHOT: LocationSnapshot = Object.freeze({
 // (us or them) has installed a patch, the marker stays until full reload.
 const PATCH_KEY = Symbol.for('djc.router.historyPatched');
 
-function patchHistoryOnce(): void {
+/**
+ * Installs the `pushState`/`replaceState` patch that makes SPA navigations
+ * observable, exactly once per document.
+ *
+ * Exported because `useLocation` is no longer the only subscriber: a hook may
+ * listen for `NAVIGATE_EVENT` without reading the location through
+ * `useSyncExternalStore` (see `useScrollToTop`), and without this call it
+ * would subscribe to an event nothing dispatches — silently doing nothing.
+ */
+export function patchHistoryOnce(): void {
   if (typeof window === 'undefined') return;
   const w = window as Window & { [PATCH_KEY]?: true };
   if (w[PATCH_KEY]) return;

package/src/hooks/router/useScrollToTop.ts

@@ -0,0 +1,120 @@
+'use client';
+
+/**
+ * useScrollToTop — land at the top of the page after a forward navigation.
+ *
+ * WHY THIS EXISTS AT ALL — Next.js App Router already scrolls, sometimes
+ *
+ * `layout-router.tsx` walks the navigated segment looking for an element to
+ * scroll to, and **gives up silently** in two cases that are ordinary in our
+ * apps:
+ *
+ *   1. It takes the segment's first DOM node and skips it when the node is
+ *      `position: sticky|fixed` OR when `getBoundingClientRect()` is all
+ *      zeroes — then moves to `nextElementSibling`, and `return`s outright
+ *      when there is none. A page whose root is `display: contents` (a width
+ *      wrapper), or whose first child renders `null`, `<script type=
+ *      "application/ld+json">`, or any other zero-box node, therefore gets no
+ *      scroll at all.
+ *   2. Having found a node, it exits early when that node's top edge is
+ *      ALREADY within the viewport. Land mid-page on a long route whose next
+ *      route starts with a tall block, and the check passes while the visitor
+ *      is looking at the middle of the new page.
+ *
+ * Both are position-dependent, which is why the bug reads as intermittent:
+ * clicking from the top of a page (what an automated run usually does) hits
+ * neither branch, so the symptom only shows up when a person scrolls first.
+ *
+ * WHAT IT DELIBERATELY DOES NOT DO
+ *
+ * - **Back/forward are left alone.** The browser restores the previous scroll
+ *   position on a `popstate`, and overriding that is a worse bug than the one
+ *   being fixed. Only `pushState`/`replaceState` navigations scroll.
+ * - **`#hash` links are left alone.** A URL naming an anchor has already said
+ *   where it wants to land.
+ * - **Query-only changes are left alone.** Filters, pagination and tab state
+ *   write the query string; yanking the visitor to the top as they tick a
+ *   checkbox is the complaint this hook would otherwise cause. Only a
+ *   `pathname` change scrolls.
+ *
+ * It is idempotent with Next's own handler: when Next succeeds we are already
+ * at the top and the write is a no-op.
+ *
+ * @example
+ *   // Once, at the app root — `BaseApp` already does this for Next.js hosts.
+ *   useScrollToTop();
+ */
+
+import { useEffect, useRef } from 'react';
+
+import { NAVIGATE_EVENT, patchHistoryOnce } from './useLocation';
+
+export interface UseScrollToTopOptions {
+  /** Turn the behaviour off without unmounting the host. Default: true. */
+  enabled?: boolean;
+  /**
+   * Scroll animation. Default `'auto'` (instant), matching a hard navigation.
+   * `'smooth'` animates a full page height on every route change, which reads
+   * as lag rather than polish.
+   */
+  behavior?: ScrollBehavior;
+}
+
+/**
+ * Scrolls the window to the top after each forward navigation to a new path.
+ * Mount ONCE per app — a second mount just writes `scrollTo(0, 0)` twice.
+ */
+export function useScrollToTop({
+  enabled = true,
+  behavior = 'auto',
+}: UseScrollToTopOptions = {}): void {
+  /**
+   * The path we last saw. Seeded on mount rather than from `''`, so the first
+   * paint does not count as a navigation — that would fight the browser's own
+   * restoration on a reload.
+   */
+  const lastPathRef = useRef<string | null>(null);
+
+  useEffect(() => {
+    if (!enabled || typeof window === 'undefined') return;
+
+    // `pushState`/`replaceState` do not emit an event on their own. Without
+    // this the listener below is subscribed to something nothing dispatches.
+    patchHistoryOnce();
+    lastPathRef.current = window.location.pathname;
+
+    /*
+     * NAVIGATE_EVENT only, and that is what keeps back/forward working: the
+     * patch in `useLocation` dispatches it from `pushState`/`replaceState`
+     * exclusively, so a `popstate` never reaches this handler and the
+     * browser's restored position is never overwritten. Subscribing to
+     * `popstate` here — or to `hashchange` — would undo exactly that.
+     */
+    const onNavigate = () => {
+      const { pathname, hash } = window.location;
+      const changedPath = pathname !== lastPathRef.current;
+      lastPathRef.current = pathname;
+
+      // Query-only or state-only writes: the visitor stays where they are.
+      if (!changedPath) return;
+      // The URL names an anchor; it has already said where to land.
+      if (hash) return;
+
+      /*
+       * Deferred by one frame, and this is load-bearing. Our navigate event
+       * fires from a microtask right after `pushState`, while the destination
+       * is still the OLD document — React has not committed the new segment
+       * yet. Scrolling then is correct but immediately undone: Next's own
+       * handler runs on the commit that follows and may scroll back down to
+       * an element it found mid-page. Running after paint means we write
+       * last, over a document whose real height is known.
+       */
+      requestAnimationFrame(() => {
+        window.scrollTo({ top: 0, left: 0, behavior });
+      });
+    };
+
+    window.addEventListener(NAVIGATE_EVENT, onNavigate);
+    return () => window.removeEventListener(NAVIGATE_EVENT, onNavigate);
+  }, [enabled, behavior]);
+}

package/src/lib/format-number.ts

@@ -0,0 +1,51 @@
+/**
+ * Numbers, written the way the reader's language writes them.
+ *
+ * Two functions, because a figure does two different jobs and they want
+ * opposite things:
+ *
+ * - `formatNumber` — the figure IS the information. A price, a mileage, a
+ *   result count the reader may quote or compare. Grouped, never rounded.
+ * - `formatCompact` — the figure is a SIZE, glanced at in chrome: a badge, a
+ *   tab, a nav counter. Four digits is where a number stops being read and
+ *   starts being measured, and the exact value belongs on the page it leads
+ *   to, not on the label pointing at it.
+ *
+ * WHY `Intl` AND NOT `${Math.round(n / 1000)}k`
+ *
+ * Measured, not assumed — `834_763` through `notation: 'compact'`:
+ *
+ *     en  834.8K        ru  834,8 тыс.
+ *     ko  83.5만         de  834.763
+ *
+ * Korean groups by TEN THOUSAND, not by thousands, so a hardcoded `k` is not
+ * merely untranslated there — it states the wrong magnitude. Russian wants a
+ * word and a comma decimal. Hand-rolling this means hand-rolling CLDR.
+ *
+ * AND WHY THE CALLER STILL CANNOT ASSUME IT IS SHORT
+ *
+ * Note `de` in that table: Node returns the FULL number, because compact data
+ * is locale-dependent and a runtime may simply not carry it. `formatCompact`
+ * is a request, not a guarantee — never size a container on the assumption
+ * that it returns four characters.
+ */
+
+/** Grouped by the reader's locale. `834763` → `834,763` / `834 763`. */
+export function formatNumber(value: number, locale?: string): string {
+  return new Intl.NumberFormat(locale).format(value);
+}
+
+/**
+ * Shortened for chrome, in the reader's own notation.
+ *
+ * Below `threshold` the exact figure is returned grouped — a badge reading
+ * `1.2K` where it could say `1,180` has traded precision for nothing.
+ */
+export function formatCompact(value: number, locale?: string, threshold = 10_000): string {
+  if (Math.abs(value) < threshold) return formatNumber(value, locale);
+
+  return new Intl.NumberFormat(locale, {
+    notation: 'compact',
+    maximumFractionDigits: 1,
+  }).format(value);
+}

package/src/lib/index.ts

@@ -1,4 +1,5 @@
 export * from "./utils";
+export * from "./format-number";
 export * from "./logger";
 export * from "./dialog-service";
 export * from "./env";

package/src/styles/css/presets/macos.css

@@ -102,7 +102,14 @@
   --accent: hsl(211 25% 19%);
   --accent-foreground: hsl(211 100% 72%);
   --destructive: hsl(3 100% 62%);
+  /* Both ink tokens must flip with the fill. The dark --destructive is far
+     brighter than the light one, so the white label this preset sets above
+     drops to 3.38:1 on it; dark ink is 5.31:1. --destructive-foreground was
+     flipped here from the start and --on-destructive was not, which left
+     `text-on-destructive` inheriting white from the light block — unreadable,
+     and invisible to check-preset-contrast.mjs, which does not pair them. */
   --destructive-foreground: hsl(0 0% 9%);
+  --on-destructive: hsl(0 0% 9%);
     /* A hairline divides, it does not glow. Ten points over --background is a
      definite edge at one device pixel without becoming the loudest thing on
      the page — which it was once the fills stopped separating surfaces.