@gntik-ai/blocks 0.5.0 → 0.7.0

package/src/tables/LoadMoreFooter/examples/flag.tsx

@@ -0,0 +1,33 @@
+import { useState } from 'react';
+import { LoadMoreFooter } from '../LoadMoreFooter';
+import { LOAD_MORE_RECORDS } from '../fixtures';
+
+export default function FlagExample() {
+  const [state, setState] = useState({ rows: LOAD_MORE_RECORDS.slice(0, 2), hasMore: true, loading: false, error: '' });
+  const [lastAppend, setLastAppend] = useState<{ seq: number; count: number }>();
+  const load = async () => {
+    setState((previous) => ({ ...previous, loading: true }));
+    const batch = await Promise.resolve(LOAD_MORE_RECORDS.slice(2));
+    // Same-tick updates are batched: settle loading=false together with the result. Split settles are unsupported.
+    setState((previous) => ({ rows: [...previous.rows, ...batch], hasMore: false, loading: false, error: '' }));
+    setLastAppend({ seq: 1, count: batch.length });
+  };
+  return (
+    <div className="space-y-4">
+      <ul>
+        {state.rows.map((row) => (
+          <li key={row.id}>{row.name}</li>
+        ))}
+      </ul>
+      <LoadMoreFooter
+        hasMore={state.hasMore}
+        loading={state.loading}
+        error={state.error}
+        loadedCount={state.rows.length}
+        lastAppend={lastAppend}
+        onLoadMore={load}
+        exhaustedFocusTarget="root"
+      />
+    </div>
+  );
+}

package/src/tables/LoadMoreFooter/examples/useMockCursor.ts

@@ -0,0 +1,30 @@
+import { useState } from 'react';
+import { LOAD_MORE_RECORDS } from '../fixtures';
+
+/** Mock consumer: real consumers normalize cursors and preserve their filters here. */
+export function useMockCursor() {
+  const [state, setState] = useState({
+    rows: LOAD_MORE_RECORDS.slice(0, 2),
+    nextCursor: 'c1' as string | null,
+    loading: false,
+    error: '',
+    lastAppend: undefined as { seq: number; count: number } | undefined,
+  });
+  const load = async (cursor?: string) => {
+    setState((previous) => ({ ...previous, loading: true }));
+    try {
+      const batch = await Promise.resolve(cursor === 'c1' ? LOAD_MORE_RECORDS.slice(2) : []);
+      // Settle loading=false and the result together in one update. Split settles are unsupported.
+      setState((previous) => ({
+        rows: [...previous.rows, ...batch],
+        nextCursor: null,
+        loading: false,
+        error: '',
+        lastAppend: { seq: (previous.lastAppend?.seq ?? 0) + 1, count: batch.length },
+      }));
+    } catch {
+      setState((previous) => ({ ...previous, loading: false, error: 'Could not load more items.' }));
+    }
+  };
+  return { ...state, load };
+}

package/src/tables/LoadMoreFooter/fixtures.ts

@@ -0,0 +1,9 @@
+/** Meaningful defaults for the no-props catalogue preview. */
+export const LOAD_MORE_PREVIEW = { nextCursor: 'page-2', loadedCount: 20 } as const;
+
+export const LOAD_MORE_RECORDS = [
+  { id: 'r1', name: 'Record 1', status: 'Ready' },
+  { id: 'r2', name: 'Record 2', status: 'Ready' },
+  { id: 'r3', name: 'Record 3', status: 'Ready' },
+  { id: 'r4', name: 'Record 4', status: 'Ready' },
+];

package/src/tables/LoadMoreFooter/useLoadMoreFooter.ts

@@ -0,0 +1,56 @@
+import { useAnnounce } from '@gntik-ai/ui';
+import { useCallback, useEffect, useLayoutEffect, useRef } from 'react';
+
+/** Capture focus before React removes the control, then restore it after the replacement commits. */
+export function useLoadMoreFooter(
+  control: 'button' | 'retry' | 'none',
+  target: 'summary' | 'root',
+  loading: boolean,
+  error: string,
+) {
+  const rootRef = useRef<HTMLDivElement>(null);
+  const summaryRef = useRef<HTMLParagraphElement>(null);
+  const currentControl = useRef<HTMLElement | null>(null);
+  const moveFocus = useRef(false);
+  const inFlightCursorRef = useRef<string | undefined>(undefined);
+  useEffect(() => {
+    // A successful settle releases the cursor; later external failures use nextCursor.
+    if (!loading && !error) inFlightCursorRef.current = undefined;
+  }, [loading, error]);
+  const controlRef = useCallback((node: HTMLElement | null) => {
+    if (!node && currentControl.current?.contains(document.activeElement)) moveFocus.current = true;
+    currentControl.current = node;
+  }, []);
+
+  useLayoutEffect(() => {
+    if (!moveFocus.current) return;
+    moveFocus.current = false;
+    const nextControl = currentControl.current;
+    const next = nextControl?.matches('button') ? nextControl : nextControl?.querySelector('button');
+    (next ?? (target === 'root' ? rootRef.current : summaryRef.current))?.focus();
+  }, [control, target]);
+
+  return { rootRef, summaryRef, controlRef, inFlightCursorRef };
+}
+
+/** Track committed results; mounting and intermediate loading states remain silent. */
+export function useLoadMoreAnnouncements(
+  loading: boolean,
+  error: string,
+  lastAppend: { seq: number; count: number } | undefined,
+  loadedAnnouncement: (count: number) => string,
+) {
+  const announce = useAnnounce();
+  const previous = useRef({ loading, error });
+  const lastSeq = useRef(lastAppend?.seq);
+  useEffect(() => {
+    const before = previous.current;
+    previous.current = { loading, error };
+    if (!loading && error && (before.loading || before.error !== error)) announce(error, 'assertive');
+  }, [loading, error, announce]);
+  useEffect(() => {
+    if (!lastAppend || (lastSeq.current !== undefined && lastAppend.seq <= lastSeq.current)) return;
+    lastSeq.current = lastAppend.seq;
+    if (lastAppend.count > 0) announce(loadedAnnouncement(lastAppend.count), 'polite');
+  }, [lastAppend, loadedAnnouncement, announce]);
+}

package/src/tables/PaginationFooter/PaginationFooter.labels.test.tsx

@@ -0,0 +1,57 @@
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { I18nProvider } from '@gntik-ai/ui';
+import { PaginationFooter, type PaginationFooterLabels } from './PaginationFooter';
+
+it('replaces pagination chrome and renders formatter results verbatim through page and size changes', async () => {
+  const user = userEvent.setup();
+  const rangeSummary = vi.fn((from: number, to: number, total: number) => `${from}|${to}|${total} registros`);
+  const paginationNav = vi.fn((noun: string) => `Paginación: ${noun}`);
+  const page = vi.fn((n: number) => `Página ${n}`);
+  const labels: PaginationFooterLabels = {
+    rowsPerPage: 'Filas por página',
+    rowsPerPageLabel: 'Tamaño de página',
+    rangeSummary,
+    paginationNav,
+    previous: 'Anterior',
+    next: 'Siguiente',
+    page,
+  };
+  const { container } = render(<PaginationFooter labels={labels} noun="Items" />);
+  expect(screen.getByText('Filas por página')).toBeVisible();
+  expect(screen.getByRole('navigation', { name: 'Paginación: Items' })).toBeVisible();
+  expect(paginationNav).toHaveBeenCalledWith('Items');
+  expect(page).toHaveBeenCalledWith(10);
+  const summary = container.querySelector('[aria-live]');
+  expect(summary?.textContent).toBe('1|10|97 registros');
+  expect(rangeSummary).toHaveBeenLastCalledWith(1, 10, 97);
+  await user.click(screen.getByRole('button', { name: 'Siguiente' }));
+  expect(summary?.textContent).toBe('11|20|97 registros');
+  expect(rangeSummary).toHaveBeenLastCalledWith(11, 20, 97);
+  await user.click(screen.getByRole('button', { name: 'Anterior' }));
+  await user.click(screen.getByRole('button', { name: 'Página 3' }));
+  expect(summary?.textContent).toBe('21|30|97 registros');
+  await user.click(screen.getByRole('combobox', { name: 'Tamaño de página' }));
+  await user.click(await screen.findByRole('option', { name: '25' }));
+  expect(summary?.textContent).toBe('1|25|97 registros');
+  expect(rangeSummary).toHaveBeenLastCalledWith(1, 25, 97);
+});
+
+it('merges individual overrides over provider translations and preserves default summary markup', () => {
+  const { container, rerender } = render(
+    <I18nProvider locale="es">
+      <PaginationFooter />
+    </I18nProvider>,
+  );
+  const original = container.querySelector('[aria-live]')?.outerHTML;
+  const nextName = screen.getAllByRole('button').at(-1)?.getAttribute('aria-label');
+  rerender(
+    <I18nProvider locale="es">
+      <PaginationFooter labels={{ rowsPerPage: 'Custom' }} />
+    </I18nProvider>,
+  );
+  expect(screen.getByText('Custom')).toBeVisible();
+  expect(container.querySelector('[aria-live]')?.outerHTML).toBe(original);
+  expect(screen.getAllByRole('button').at(-1)?.getAttribute('aria-label')).toBe(nextName);
+  expect(screen.getByRole('combobox')).not.toHaveAccessibleName('Custom');
+});

package/src/tables/PaginationFooter/PaginationFooter.tsx

@@ -1,7 +1,19 @@
 import { cn, Pagination, SimpleSelect, useI18n } from '@gntik-ai/ui';
 import { useState } from 'react';
 
+export interface PaginationFooterLabels {
+  rowsPerPage: string;
+  rowsPerPageLabel: string;
+  rangeSummary: (from: number, to: number, total: number) => string;
+  paginationNav: (noun: string) => string;
+  previous: string;
+  next: string;
+  page: (page: number) => string;
+}
+
 export interface PaginationFooterProps {
+  /** Per-key overrides; omitted keys retain the existing provider translations and defaults. */
+  labels?: Partial<PaginationFooterLabels>;
   /** Total number of rows. */
   total?: number;
   /** Current page, 1-based (controlled). */
@@ -32,6 +44,7 @@ export function PaginationFooter({
   noun: nounProp,
   locale: localeProp,
   className,
+  labels,
 }: PaginationFooterProps) {
   const { t, locale: providerLocale } = useI18n();
   const locale = localeProp ?? providerLocale;
@@ -63,10 +76,10 @@ export function PaginationFooter({
     <div className={cn('flex flex-col gap-3 sm:flex-row sm:items-center sm:justify-between', className)}>
       <div className="flex items-center gap-2.5">
         <span className="text-[12.5px] text-muted-foreground" aria-hidden>
-          {t('table.rowsPerPage')}
+          {labels?.rowsPerPage ?? t('table.rowsPerPage')}
         </span>
         <SimpleSelect
-          aria-label={t('table.rowsPerPage')}
+          aria-label={labels?.rowsPerPageLabel ?? t('table.rowsPerPage')}
           size="sm"
           className="w-[76px] font-mono"
           value={String(pageSize)}
@@ -76,17 +89,28 @@ export function PaginationFooter({
       </div>
       <div className="flex flex-col gap-3 sm:flex-row sm:items-center">
         <p className="text-[12.5px] text-muted-foreground tabular-nums" aria-live="polite">
-          <span className="font-mono text-foreground">
-            {fmt(from)}–{fmt(to)}
-          </span>{' '}
-          {t('pagination.of')} <span className="font-mono text-foreground">{fmt(total)}</span>
+          {labels?.rangeSummary ? (
+            labels.rangeSummary(from, to, total)
+          ) : (
+            <>
+              <span className="font-mono text-foreground">
+                {fmt(from)}–{fmt(to)}
+              </span>{' '}
+              {t('pagination.of')} <span className="font-mono text-foreground">{fmt(total)}</span>
+            </>
+          )}
         </p>
         <Pagination
           page={page}
           pageCount={pageCount}
           onPageChange={goTo}
           size="sm"
-          labels={{ nav: t('table.pagination', { noun }) }}
+          labels={{
+            nav: labels?.paginationNav?.(noun) ?? t('table.pagination', { noun }),
+            previous: labels?.previous,
+            next: labels?.next,
+            page: labels?.page,
+          }}
         />
       </div>
     </div>

package/src/tables/PaginationFooter/block.meta.ts

@@ -1,4 +1,5 @@
 import type { BlockMeta } from '../../meta';
+import type { PaginationFooterLabels } from './PaginationFooter';
 
 export const meta: BlockMeta = {
   name: 'Pagination footer',
@@ -6,5 +7,27 @@ export const meta: BlockMeta = {
   status: 'beta',
   description:
     'Table footer with a rows-per-page Select, a "1–10 of 97" summary and numbered Pagination; controlled or uncontrolled.',
+  labels: [
+    { key: 'rowsPerPage', type: 'string', state: 'Always: visible page-size text' },
+    { key: 'rowsPerPageLabel', type: 'string', state: 'Always: page-size Select accessible name' },
+    {
+      key: 'rangeSummary',
+      type: '(from: number, to: number, total: number) => string',
+      state: 'Every page and page-size change: visible summary and polite live region',
+    },
+    {
+      key: 'paginationNav',
+      type: '(noun: string) => string',
+      state:
+        'Always: navigation accessible name; noun is caller content or defaults to the provider translation of rows',
+    },
+    { key: 'previous', type: 'string', state: 'Always: previous-page button name' },
+    { key: 'next', type: 'string', state: 'Always: next-page button name' },
+    {
+      key: 'page',
+      type: '(page: number) => string',
+      state: 'Always: numbered-page button name; number stays caller content',
+    },
+  ] satisfies Array<{ key: keyof PaginationFooterLabels; type: string; state: string }>,
   uses: ['SimpleSelect', 'Pagination'],
 };

package/src/tables/index.ts

@@ -35,7 +35,11 @@ export * from './FilterBar/FilterBar';
 export { meta as filterBarMeta } from './FilterBar/block.meta';
 export { DEPLOYMENT_DEFAULT_FILTERS, DEPLOYMENT_FILTER_FIELDS, DEPLOYMENT_SAVED_VIEWS } from './FilterBar/fixtures';
 export * from './PaginationFooter/PaginationFooter';
+export * from './CursorPagerFooter/CursorPagerFooter';
+export { meta as cursorPagerFooterMeta } from './CursorPagerFooter/block.meta';
 export { meta as paginationFooterMeta } from './PaginationFooter/block.meta';
+export * from './LoadMoreFooter/LoadMoreFooter';
+export { meta as loadMoreFooterMeta } from './LoadMoreFooter/block.meta';
 export * from './TruncatedCollectionFooter/TruncatedCollectionFooter';
 export { meta as truncatedCollectionFooterMeta } from './TruncatedCollectionFooter/block.meta';
 export * from './InlineEditRow/InlineEditRow';