@lyeve-labs/ui-kit 0.19.0 → 0.21.0

package/dist/components/Pagination.svelte

@@ -1,5 +1,6 @@
 <script lang="ts">
   import { safeHref } from '../internal/href.js';
+  import { formatCount } from '../internal/number.js';
 
   interface Base {
     page: number;
@@ -21,6 +22,31 @@
      * back.
      */
     hasNext?: boolean;
+    /**
+     * How many rows the page on screen actually holds.
+     *
+     * Only an uncounted list needs it, and only for the sentence: without a
+     * total the component knows where the page starts but not where it ends,
+     * because the last page is short and nothing here says how short. Given it,
+     * the summary states a range instead of naming the page.
+     *
+     * It is the row count of what was rendered, not a page size. A caller that
+     * asked for 50 and received 12 passes 12.
+     */
+    count?: number;
+    /**
+     * What the list holds, in the plural: 'files', 'jobs', 'webhooks'.
+     *
+     * The summary names it, because a console that stacks three lists under one
+     * page title prints '51 to 100' three times and says of what nowhere. Left
+     * out, the summary reads exactly as it did before this existed.
+     *
+     * Plural at every size, including a list of one. The noun labels the
+     * collection here rather than agreeing with a figure in the sentence, the
+     * same way the column header above it does, and a singular form would have
+     * to pick which of the three figures governs it.
+     */
+    noun?: string;
     class?: string;
   }
 
@@ -47,6 +73,8 @@
     total = undefined,
     perPage = 20,
     hasNext = false,
+    count = undefined,
+    noun = '',
     class: cls = '',
     onchange,
     href,
@@ -64,6 +92,15 @@
   let from = $derived(Math.min((safePage - 1) * perPage + 1, safeTotal));
   let to = $derived(Math.min(safePage * perPage, safeTotal));
 
+  /**
+   * The rows on screen, when the caller states them. Zero and a negative are
+   * both "nothing to describe": a page of no rows has no range, and the summary
+   * falls back to naming the page rather than printing an inverted one.
+   */
+  let safeCount = $derived(
+    typeof count === 'number' && isFinite(count) && count > 0 ? Math.floor(count) : undefined,
+  );
+
   let canPrev = $derived(safePage > 1);
   let canNext = $derived(counted ? safePage < totalPages : hasNext);
   let hasControls = $derived(counted ? totalPages > 1 : canPrev || canNext);
@@ -102,20 +139,40 @@
 
   let nums = $derived(counted ? pageNumbers(safePage, totalPages) : []);
 
+  /**
+   * The noun as it will be read.
+   *
+   * Trimmed, and empty means absent: a caller composing the word from data can
+   * hand over ' ' as easily as 'files', and a summary that opens with a stray
+   * space is worse than one that names nothing.
+   */
+  let label = $derived(noun.trim());
+
   /**
    * The count, when there is one to state.
    *
    * An uncounted list says which page it is on and nothing else. It cannot say
    * "1 to 20 of 400" without the total, and it cannot say "1 to 20" either: the
-   * last page is short and this component is never told how short.
+   * last page is short and this component is never told how short. It still
+   * groups the page number: `href` mode puts that number in the URL, so a link
+   * or a reader can land on page 5,000 without stepping there.
+   *
+   * Every figure is grouped, because a pager sits under a table that groups its
+   * own figures and the pager is where the largest number on the screen is.
    */
-  let summary = $derived(
-    counted
-      ? safeTotal === 0
-        ? 'No results'
-        : `${from} to ${to} of ${safeTotal}`
-      : `Page ${safePage}`,
-  );
+  let summary = $derived.by(() => {
+    if (!counted) {
+      if (safeCount !== undefined) {
+        const start = (safePage - 1) * perPage + 1;
+        const span = `${formatCount(start)} to ${formatCount(start + safeCount - 1)}`;
+        return label ? `${label} ${span}` : span;
+      }
+      return label ? `${label}, page ${formatCount(safePage)}` : `Page ${formatCount(safePage)}`;
+    }
+    if (safeTotal === 0) return label ? `No ${label}` : 'No results';
+    const range = `${formatCount(from)} to ${formatCount(to)} of ${formatCount(safeTotal)}`;
+    return label ? `${label} ${range}` : range;
+  });
 
   /** The target of a control, sanitized, or nothing when the step is unavailable. */
   function linkTo(target: number, enabled: boolean): string | undefined {

package/dist/components/Pagination.svelte.d.ts

@@ -18,6 +18,31 @@ interface Base {
      * back.
      */
     hasNext?: boolean;
+    /**
+     * How many rows the page on screen actually holds.
+     *
+     * Only an uncounted list needs it, and only for the sentence: without a
+     * total the component knows where the page starts but not where it ends,
+     * because the last page is short and nothing here says how short. Given it,
+     * the summary states a range instead of naming the page.
+     *
+     * It is the row count of what was rendered, not a page size. A caller that
+     * asked for 50 and received 12 passes 12.
+     */
+    count?: number;
+    /**
+     * What the list holds, in the plural: 'files', 'jobs', 'webhooks'.
+     *
+     * The summary names it, because a console that stacks three lists under one
+     * page title prints '51 to 100' three times and says of what nowhere. Left
+     * out, the summary reads exactly as it did before this existed.
+     *
+     * Plural at every size, including a list of one. The noun labels the
+     * collection here rather than agreeing with a figure in the sentence, the
+     * same way the column header above it does, and a singular form would have
+     * to pick which of the three figures governs it.
+     */
+    noun?: string;
     class?: string;
 }
 /**

package/dist/index.d.ts

@@ -89,4 +89,4 @@ export type { ConfirmOptions } from './components/dialog/dialog-manager.svelte.j
 export type { DialogOptions, DialogEntry, DialogSize } from './components/dialog/types.js';
 export { cn, type ClassValue } from './utils/cn.js';
 export { getTheme, getThemePreference, nextThemePreference, resolveTheme, setTheme, setThemePreference, systemTheme, themeBootScript, toggleTheme, watchSystemTheme, THEME_PREFERENCES, type Theme, type ThemePreference, } from './utils/theme.js';
-export declare const VERSION = "0.19.0";
+export declare const VERSION = "0.21.0";

package/dist/index.js

@@ -96,4 +96,4 @@ export { getTheme, getThemePreference, nextThemePreference, resolveTheme, setThe
 // ── Version ────────────────────────────────────────────────────────────────
 // Generated from package.json by `pnpm version:sync`. Bump package.json, never
 // this line; the build and the test suite fail when the two disagree.
-export const VERSION = '0.19.0';
+export const VERSION = '0.21.0';

package/dist/internal/number.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Digit grouping for a figure a reader is meant to take in at a glance.
+ *
+ * The locale is fixed rather than the runtime's. `toLocaleString()` with no
+ * argument formats by whatever locale the environment reports, and the server
+ * that renders a page and the browser that hydrates it do not have to report
+ * the same one: the same figure then arrives as `4,210` in the HTML and as
+ * `4.210` or `4210` after hydration, which is a mismatch the framework warns
+ * about and a number the reader watches change under them. A component library
+ * has no way to know which locale a host has configured either, so the
+ * separator has to be a decision the kit makes once.
+ *
+ * `en-US` because that is the language every string in the kit is written in,
+ * and an English sentence carrying a German separator is the worse of the two
+ * inconsistencies.
+ *
+ * Not exported from the package entry point - this is an implementation detail.
+ */
+/**
+ * A count, grouped in threes.
+ *
+ * A value that is not a finite number reads as zero rather than reaching the
+ * formatter, which spells infinity as a glyph no summary line should carry and
+ * NaN as a word no reader can act on.
+ */
+export declare function formatCount(n: number): string;

package/dist/internal/number.js

@@ -0,0 +1,35 @@
+/**
+ * Digit grouping for a figure a reader is meant to take in at a glance.
+ *
+ * The locale is fixed rather than the runtime's. `toLocaleString()` with no
+ * argument formats by whatever locale the environment reports, and the server
+ * that renders a page and the browser that hydrates it do not have to report
+ * the same one: the same figure then arrives as `4,210` in the HTML and as
+ * `4.210` or `4210` after hydration, which is a mismatch the framework warns
+ * about and a number the reader watches change under them. A component library
+ * has no way to know which locale a host has configured either, so the
+ * separator has to be a decision the kit makes once.
+ *
+ * `en-US` because that is the language every string in the kit is written in,
+ * and an English sentence carrying a German separator is the worse of the two
+ * inconsistencies.
+ *
+ * Not exported from the package entry point - this is an implementation detail.
+ */
+/**
+ * Built at module load, not per call.
+ *
+ * Constructing an `Intl` formatter is the expensive half of using one, and a
+ * pager re-renders on every keystroke that filters the list behind it.
+ */
+const GROUPED = new Intl.NumberFormat('en-US');
+/**
+ * A count, grouped in threes.
+ *
+ * A value that is not a finite number reads as zero rather than reaching the
+ * formatter, which spells infinity as a glyph no summary line should carry and
+ * NaN as a word no reader can act on.
+ */
+export function formatCount(n) {
+    return Number.isFinite(n) ? GROUPED.format(n) : '0';
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lyeve-labs/ui-kit",
-  "version": "0.19.0",
+  "version": "0.21.0",
   "description": "A clean, accessible, palette-aware Svelte 5 component library. The design system behind LyEve.",
   "license": "MIT",
   "author": "LyEve Labs <hello@lyeve.com>",