@gntik-ai/blocks 0.6.0 → 0.8.0

package/src/tables/LoadMoreFooter/LoadMoreFooter.announcements.test.tsx

@@ -0,0 +1,106 @@
+import { act, render } from '@testing-library/react';
+import { LiveAnnouncer } from '@gntik-ai/ui';
+import { StrictMode } from 'react';
+import { LoadMoreFooter, type LoadMoreFooterProps } from './LoadMoreFooter';
+
+function announcements(initial: LoadMoreFooterProps, outer = false) {
+  const wrap = (props: LoadMoreFooterProps) => (
+    <StrictMode>
+      {outer ? (
+        <LiveAnnouncer>
+          <LoadMoreFooter {...props} />
+        </LiveAnnouncer>
+      ) : (
+        <LoadMoreFooter {...props} />
+      )}
+    </StrictMode>
+  );
+  const { container, rerender } = render(wrap(initial));
+  const region = container.querySelector('[aria-live="assertive"]');
+  expect(region).not.toBeNull();
+  expect(region).toHaveTextContent('');
+  const messages: string[] = [];
+  const observer = new MutationObserver(() => messages.push(region?.textContent?.trim() ?? ''));
+  observer.observe(region!, { childList: true, characterData: true, subtree: true });
+  return {
+    container,
+    messages,
+    async update(props: LoadMoreFooterProps) {
+      rerender(wrap(props));
+      await act(async () => {});
+    },
+    disconnect: () => observer.disconnect(),
+  };
+}
+
+describe('LoadMoreFooter announcements', () => {
+  it.each([true, false])('announces new appended sequences only, with outer provider=%s', async (outer) => {
+    const h = announcements({ hasMore: true, lastAppend: { seq: 1, count: 20 } }, outer);
+    expect(h.container.querySelectorAll('[aria-live="polite"]')).toHaveLength(1);
+    const polite = h.container.querySelector('[aria-live="polite"]');
+    expect(polite?.textContent).toBe('');
+    await h.update({ hasMore: true, lastAppend: { seq: 2, count: 3 } });
+    expect(polite?.textContent).toBe('3 items added.');
+    await h.update({ hasMore: true, lastAppend: { seq: 2, count: 3 } });
+    expect(polite?.textContent).toBe('3 items added.');
+    await h.update({ hasMore: true, lastAppend: { seq: 3, count: 0 } });
+    await h.update({ hasMore: true, lastAppend: { seq: 3, count: 9 } });
+    expect(polite?.textContent).toBe('3 items added.');
+    await h.update({ hasMore: false, lastAppend: { seq: 4, count: 1 } });
+    expect(polite?.textContent).toBe('1 item added.');
+    h.disconnect();
+  });
+
+  it('announces a first append when lastAppend was initially absent', async () => {
+    const h = announcements({ hasMore: true });
+    await h.update({ hasMore: true, lastAppend: { seq: 1, count: 2 } });
+    expect(h.container.querySelector('[aria-live="polite"]')?.textContent).toBe('2 items added.');
+    h.disconnect();
+  });
+
+  it.each(['cursor', 'flag'])('announces an exhausted error exactly once in %s mode', async (mode) => {
+    const props = { nextCursor: mode === 'cursor' ? 'c1' : undefined, hasMore: true };
+    const h = announcements(props);
+    await h.update({ ...props, loading: true });
+    await h.update({ ...props, loading: false, hasMore: false, error: 'E1' });
+    await h.update({ ...props, loading: false, hasMore: false, error: 'E1' });
+    expect(h.messages).toEqual(['E1']);
+    h.disconnect();
+  });
+
+  it('announces settled failures, including the same error again, but not retained errors on success', async () => {
+    const h = announcements({ hasMore: true });
+    await h.update({ hasMore: true, loading: true });
+    await h.update({ hasMore: true, loading: false, error: 'E1' });
+    expect(h.messages).toEqual(['E1']);
+    await h.update({ hasMore: true, loading: true, error: 'E1' });
+    await h.update({ hasMore: true, loading: false, error: '' });
+    expect(h.messages).toEqual(['E1']);
+    await h.update({ hasMore: true, loading: true, error: 'E1' });
+    await h.update({ hasMore: true, loading: false, error: 'E1' });
+    expect(h.messages).toEqual(['E1', 'E1']);
+    h.disconnect();
+  });
+
+  it('ignores mount errors and changes while loading, then announces the final error on settle', async () => {
+    const h = announcements({ nextCursor: 'c1', error: 'E1', loading: true });
+    await h.update({ nextCursor: 'c1', error: 'E2', loading: true });
+    expect(h.messages).toEqual([]);
+    await h.update({ nextCursor: 'c1', error: 'E2', loading: false });
+    await h.update({ nextCursor: 'c1', error: 'E2', loading: false });
+    expect(h.messages).toEqual(['E2']);
+    h.disconnect();
+  });
+
+  it('announces new non-empty idle errors, but not mount or identical values', async () => {
+    const h = announcements({ hasMore: true, error: 'mount' });
+    await h.update({ hasMore: true, error: 'mount' });
+    await h.update({ hasMore: true });
+    expect(h.messages).toEqual([]);
+    await h.update({ hasMore: true, error: 'E1' });
+    await h.update({ hasMore: true, error: 'E1' });
+    await h.update({ hasMore: true, error: 'E2' });
+    expect(h.messages).toEqual(['E1', 'E2']);
+    h.disconnect();
+  });
+});

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

@@ -0,0 +1,36 @@
+import { render, screen, within } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import CursorExample from './examples/cursor';
+import FlagExample from './examples/flag';
+import CardsExample from './examples/cards';
+import ExhaustedExample from './examples/exhausted';
+
+describe('LoadMoreFooter consumer examples', () => {
+  it('keeps a settled error visible without retry in the exhausted example', () => {
+    render(<ExhaustedExample />);
+    expect(screen.getByRole('heading', { name: 'Request failed' })).toBeVisible();
+    expect(screen.queryByRole('button')).toBeNull();
+    expect(screen.getByText(/40 items loaded/)).toBeVisible();
+  });
+
+  it.each([
+    ['table', CursorExample],
+    ['cards', CardsExample],
+  ] as const)('appends the next cursor batch in the %s example', async (_name, Example) => {
+    render(<Example />);
+    expect(screen.getByText('Record 1')).toBeVisible();
+    await userEvent.setup().click(screen.getByRole('button', { name: 'Load more' }));
+    expect(await screen.findByText('Record 3')).toBeVisible();
+    expect(screen.getByText('Record 1')).toBeVisible();
+    const footer = screen.getByRole('group', { name: 'Load more items' });
+    expect(within(footer).queryByRole('button')).toBeNull();
+    expect(screen.getByText(/4 items loaded/)).toHaveFocus();
+  });
+
+  it('appends a flag-mode batch and uses the root exhaustion target', async () => {
+    render(<FlagExample />);
+    await userEvent.setup().click(screen.getByRole('button', { name: 'Load more' }));
+    expect(await screen.findByText(/4 items loaded/)).toBeVisible();
+    expect(screen.getByRole('group')).toHaveFocus();
+  });
+});

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

@@ -0,0 +1,71 @@
+import { render, screen } from '@testing-library/react';
+import { I18nProvider } from '@gntik-ai/ui';
+import { LoadMoreFooter, type LoadMoreFooterProps } from './LoadMoreFooter';
+import { expectNoAxeViolations } from '../../test/a11y';
+
+describe('LoadMoreFooter copy and accessibility', () => {
+  it('inherits Spanish defaults, including retry, summary and append announcements', () => {
+    const wrap = (props: LoadMoreFooterProps) => (
+      <I18nProvider locale="es">
+        <LoadMoreFooter {...props} />
+      </I18nProvider>
+    );
+    const { container, rerender } = render(wrap({ hasMore: true, loadedCount: 3 }));
+    expect(screen.getByRole('group', { name: 'Cargar más elementos' })).toBeVisible();
+    expect(screen.getByRole('button', { name: 'Cargar más' })).toBeVisible();
+    expect(screen.getByText(/3 elementos cargados/)).toBeVisible();
+    expect(screen.getByText('Hay más elementos disponibles.')).toBeVisible();
+    rerender(wrap({ hasMore: true, loading: true }));
+    expect(screen.getByRole('button', { name: 'Cargando…' })).toBeVisible();
+    rerender(wrap({ hasMore: true, error: 'E1' }));
+    expect(screen.getByRole('button', { name: 'Reintentar' })).toBeVisible();
+    rerender(wrap({ hasMore: true, lastAppend: { seq: 1, count: 2 } }));
+    expect(container.querySelector('[aria-live="polite"]')).toHaveTextContent('2 elementos añadidos.');
+  });
+
+  it('uses every supplied label exactly and preserves empty overrides', () => {
+    const labels = {
+      loadMore: 'Fetch again',
+      loading: 'Fetching records',
+      retry: 'Repeat request',
+      group: 'Records footer',
+      moreAvailable: 'Another batch exists',
+      summary: (n: number) => `Seen ${n}`,
+      loadedAnnouncement: (n: number) => `Appended ${n}`,
+    };
+    const wrap = (props: LoadMoreFooterProps) => (
+      <I18nProvider locale="es">
+        <LoadMoreFooter hasMore labels={labels} {...props} />
+      </I18nProvider>
+    );
+    const { container, rerender } = render(wrap({ loadedCount: 7 }));
+    expect(screen.getByRole('group', { name: 'Records footer' })).toBeVisible();
+    expect(screen.getByRole('button', { name: 'Fetch again' })).toBeVisible();
+    expect(screen.getByText(/Seen 7/)).toBeVisible();
+    expect(screen.getByText('Another batch exists')).toBeVisible();
+    rerender(wrap({ loading: true }));
+    expect(screen.getByRole('button', { name: 'Fetching records' })).toBeVisible();
+    rerender(wrap({ error: 'E1' }));
+    expect(screen.getByRole('button', { name: 'Repeat request' })).toBeVisible();
+    rerender(wrap({ lastAppend: { seq: 1, count: 4 } }));
+    expect(container.querySelector('[aria-live="polite"]')?.textContent).toBe('Appended 4');
+    rerender(wrap({ labels: { ...labels, moreAvailable: '', summary: () => '' } }));
+    expect(screen.queryByText('Another batch exists')).toBeNull();
+    expect(screen.queryByText(/elementos cargados/)).toBeNull();
+  });
+
+  for (const theme of ['dark', 'light', 'high_contrast']) {
+    it.each([
+      { nextCursor: 'c1' },
+      { nextCursor: 'c1', loading: true },
+      { nextCursor: 'c1', error: 'Request failed' },
+      { hasMore: true, error: 'Request failed' },
+      { nextCursor: null, error: 'Request failed' },
+      { hasMore: false },
+    ])(`has no axe violations in ${theme} with %j`, async (props) => {
+      document.documentElement.className = theme;
+      const { container } = render(<LoadMoreFooter {...props} />);
+      await expectNoAxeViolations(container);
+    });
+  }
+});

package/src/tables/LoadMoreFooter/LoadMoreFooter.test.tsx

@@ -0,0 +1,184 @@
+import userEvent from '@testing-library/user-event';
+import { render, screen, within } from '@testing-library/react';
+import { LoadMoreFooter } from './LoadMoreFooter';
+
+describe('LoadMoreFooter availability', () => {
+  it.each([
+    ['c1', undefined, true],
+    ['c1', true, true],
+    ['c1', false, false],
+    ['', true, false],
+    ['', undefined, false],
+    [null, true, false],
+    [undefined, true, true],
+    [undefined, false, false],
+    [undefined, undefined, false],
+  ] as const)('nextCursor=%s hasMore=%s available=%s', (nextCursor, hasMore, available) => {
+    render(<LoadMoreFooter nextCursor={nextCursor} hasMore={hasMore} loadedCount={37} />);
+    expect(screen.queryAllByRole('button')).toHaveLength(available ? 1 : 0);
+    const root = screen.getByRole('group', { name: 'Load more items' });
+    expect(root).toHaveAttribute('tabindex', '-1');
+    expect(screen.getByText(/37 items loaded/)).toHaveAttribute('tabindex', '-1');
+    expect(root).not.toHaveTextContent(/total|page|of \d/i);
+    expect(screen.queryByText('More items available.')).toBe(
+      available ? screen.getByText('More items available.') : null,
+    );
+  });
+
+  it('renders meaningful English defaults without props', () => {
+    render(<LoadMoreFooter />);
+    expect(screen.getByRole('button', { name: 'Load more' })).toBeVisible();
+    expect(screen.getByText(/20 items loaded/)).toBeVisible();
+  });
+});
+
+describe('LoadMoreFooter loading', () => {
+  it.each(['cursor', 'flag'])('loads exactly once and retains focus while loading in %s mode', async (mode) => {
+    const user = userEvent.setup();
+    const onLoadMore = vi.fn();
+    const props = { nextCursor: mode === 'cursor' ? 'c1' : undefined, hasMore: true, onLoadMore };
+    const { rerender } = render(<LoadMoreFooter {...props} />);
+    const button = screen.getByRole('button', { name: 'Load more' });
+    await user.click(button);
+    expect(onLoadMore.mock.calls).toEqual(mode === 'cursor' ? [['c1']] : [[]]);
+    rerender(<LoadMoreFooter {...props} loading />);
+    expect(button).toHaveFocus();
+    expect(button).toHaveAttribute('aria-disabled', 'true');
+    expect(button).not.toHaveAttribute('disabled');
+    expect(button).toHaveAccessibleName('Loading…');
+    expect(button.querySelector('svg')).not.toBeNull();
+    expect(screen.getByRole('group')).toHaveAttribute('aria-busy', 'true');
+    await user.click(button);
+    await user.keyboard('{Enter} ');
+    expect(onLoadMore).toHaveBeenCalledTimes(1);
+    expect(button).toHaveFocus();
+  });
+});
+
+describe('LoadMoreFooter failures and focus', () => {
+  it.each([true, false])(
+    'retries the recorded cursor and returns focus after success (onRetry=%s)',
+    async (explicitRetry) => {
+      const user = userEvent.setup();
+      const onLoadMore = vi.fn();
+      const onRetry = vi.fn();
+      const props = { nextCursor: 'c1', onLoadMore, onRetry: explicitRetry ? onRetry : undefined };
+      const { rerender } = render(<LoadMoreFooter {...props} />);
+      await user.click(screen.getByRole('button'));
+      rerender(<LoadMoreFooter {...props} loading />);
+      rerender(<LoadMoreFooter {...props} nextCursor="c2" error="Request failed" />);
+      const retry = screen.getByRole('button', { name: 'Try again' });
+      expect(retry).toHaveFocus();
+      expect(screen.getByRole('heading', { name: 'Request failed' })).toBeVisible();
+      expect(screen.queryByText(/503|req_|Contact support|Details|Your data/)).toBeNull();
+      await user.click(retry);
+      expect((explicitRetry ? onRetry : onLoadMore).mock.calls).toEqual(explicitRetry ? [['c1']] : [['c1'], ['c1']]);
+      rerender(<LoadMoreFooter {...props} error="Request failed" loading />);
+      expect(retry).toHaveFocus();
+      expect(retry).toHaveAttribute('aria-disabled', 'true');
+      await user.click(retry);
+      await user.keyboard('{Enter} ');
+      expect(explicitRetry ? onRetry : onLoadMore).toHaveBeenCalledTimes(explicitRetry ? 1 : 2);
+      rerender(<LoadMoreFooter {...props} nextCursor="c2" error="" loading={false} />);
+      expect(screen.getByRole('button', { name: 'Load more' })).toHaveFocus();
+    },
+  );
+
+  it.each([true, false])(
+    'retains the same flag button with a visible error and no cursor argument (onRetry=%s)',
+    async (explicitRetry) => {
+      const user = userEvent.setup();
+      const onLoadMore = vi.fn();
+      const onRetry = vi.fn();
+      const props = { hasMore: true, onLoadMore, onRetry: explicitRetry ? onRetry : undefined };
+      const { rerender } = render(<LoadMoreFooter {...props} />);
+      const button = screen.getByRole('button');
+      await user.click(button);
+      rerender(<LoadMoreFooter {...props} loading />);
+      rerender(<LoadMoreFooter {...props} error="Request failed" />);
+      expect(screen.getByRole('button', { name: 'Try again' })).toBe(button);
+      expect(button).toHaveFocus();
+      expect(button).toHaveAccessibleDescription('Request failed');
+      expect(within(screen.getByRole('group')).getByText('Request failed')).toBeVisible();
+      expect(screen.queryByRole('heading')).toBeNull();
+      await user.click(button);
+      expect((explicitRetry ? onRetry : onLoadMore).mock.calls).toEqual(explicitRetry ? [[]] : [[], []]);
+    },
+  );
+
+  it('uses the current cursor when no attempt was recorded', async () => {
+    const onRetry = vi.fn();
+    render(<LoadMoreFooter nextCursor="c2" error="Request failed" onRetry={onRetry} />);
+    await userEvent.setup().click(screen.getByRole('button', { name: 'Try again' }));
+    expect(onRetry.mock.calls).toEqual([['c2']]);
+  });
+
+  it.each([true, false])(
+    'uses the current cursor for an external failure after a successful load (onRetry=%s)',
+    async (explicitRetry) => {
+      const user = userEvent.setup();
+      const onLoadMore = vi.fn();
+      const onRetry = vi.fn();
+      const props = { onLoadMore, onRetry: explicitRetry ? onRetry : undefined };
+      const { rerender } = render(<LoadMoreFooter {...props} nextCursor="c1" />);
+      await user.click(screen.getByRole('button', { name: 'Load more' }));
+      rerender(<LoadMoreFooter {...props} nextCursor="c1" loading />);
+      rerender(<LoadMoreFooter {...props} nextCursor="c2" loading={false} error="" />);
+      rerender(<LoadMoreFooter {...props} nextCursor="c2" error="External request failed" />);
+      await user.click(screen.getByRole('button', { name: 'Try again' }));
+      expect((explicitRetry ? onRetry : onLoadMore).mock.calls).toEqual(explicitRetry ? [['c2']] : [['c1'], ['c2']]);
+    },
+  );
+
+  it.each(['cursor', 'flag'])('exhaustion overrides an error and removes every control in %s mode', async (mode) => {
+    const props = { nextCursor: mode === 'cursor' ? 'c1' : undefined, hasMore: true, loadedCount: 37 };
+    const { rerender } = render(<LoadMoreFooter {...props} />);
+    await userEvent.setup().click(screen.getByRole('button'));
+    rerender(<LoadMoreFooter {...props} loading />);
+    rerender(<LoadMoreFooter {...props} hasMore={false} error="Request failed" />);
+    expect(screen.queryAllByRole('button')).toHaveLength(0);
+    expect(screen.getByText(/37 items loaded/)).toHaveFocus();
+    expect(within(screen.getByRole('group')).getByText('Request failed')).toBeVisible();
+  });
+
+  it.each(['summary', 'root'] as const)('focuses %s after an exhausted successful retry', async (target) => {
+    const props = { nextCursor: 'c1', error: 'Request failed', exhaustedFocusTarget: target };
+    const { rerender } = render(<LoadMoreFooter {...props} />);
+    await userEvent.setup().click(screen.getByRole('button'));
+    rerender(<LoadMoreFooter {...props} loading />);
+    rerender(<LoadMoreFooter {...props} hasMore={false} error="" />);
+    expect(target === 'root' ? screen.getByRole('group') : screen.getByText(/items loaded/)).toHaveFocus();
+  });
+
+  it.each(['cursor', 'flag'])(
+    'moves a focused retry to the root on an exhausted failed attempt in %s mode',
+    async (mode) => {
+      const props = {
+        nextCursor: mode === 'cursor' ? 'c1' : undefined,
+        hasMore: true,
+        error: 'E1',
+        exhaustedFocusTarget: 'root' as const,
+      };
+      const { rerender } = render(<LoadMoreFooter {...props} />);
+      await userEvent.setup().click(screen.getByRole('button'));
+      rerender(<LoadMoreFooter {...props} loading />);
+      rerender(<LoadMoreFooter {...props} hasMore={false} />);
+      expect(screen.queryAllByRole('button')).toHaveLength(0);
+      expect(screen.getByRole('group')).toHaveFocus();
+    },
+  );
+
+  it('never takes focus from elsewhere on any control transition', () => {
+    const outside = document.createElement('button');
+    document.body.append(outside);
+    outside.focus();
+    const { rerender } = render(<LoadMoreFooter nextCursor="c1" />);
+    rerender(<LoadMoreFooter nextCursor="c1" error="Request failed" />);
+    expect(outside).toHaveFocus();
+    rerender(<LoadMoreFooter nextCursor="c2" />);
+    expect(outside).toHaveFocus();
+    rerender(<LoadMoreFooter nextCursor={null} />);
+    expect(outside).toHaveFocus();
+    outside.remove();
+  });
+});

package/src/tables/LoadMoreFooter/LoadMoreFooter.tsx

@@ -0,0 +1,151 @@
+import { Button, LiveAnnouncer, cn, useHasLiveAnnouncer, useI18n } from '@gntik-ai/ui';
+import { useId } from 'react';
+import { ErrorPanel } from '../../feedback/ErrorPanel/ErrorPanel';
+import { useLoadMoreFooter, useLoadMoreAnnouncements } from './useLoadMoreFooter';
+import { LOAD_MORE_PREVIEW } from './fixtures';
+
+export interface LoadMoreFooterLabels {
+  loadMore: string;
+  loading: string;
+  retry: string;
+  group: string;
+  moreAvailable: string;
+  summary: (count: number) => string;
+  loadedAnnouncement: (count: number) => string;
+}
+
+/**
+ * Each attempt must settle in one update: loading=false together with its result
+ * (error, or an empty error on success). Split settles are unsupported.
+ */
+export interface LoadMoreFooterProps {
+  /** Undefined selects flag mode; null or an empty string exhausts cursor mode. */
+  nextCursor?: string | null;
+  hasMore?: boolean;
+  loading?: boolean;
+  error?: string;
+  onLoadMore?: (cursor?: string) => void;
+  onRetry?: (cursor?: string) => void;
+  loadedCount?: number;
+  /** Increasing sequence for successful appends only; leave unchanged on replacement or failure. */
+  lastAppend?: { seq: number; count: number };
+  exhaustedFocusTarget?: 'summary' | 'root';
+  labels?: Partial<LoadMoreFooterLabels>;
+  className?: string;
+}
+
+/**
+ * Load more for appended lists without a total or page count. The consumer owns rows and requests.
+ * With no props, renders a static catalogue preview using fixture data. Supplying any prop selects
+ * the consumer contract: undefined nextCursor means flag mode and requires hasMore=true.
+ * loadedCount defaults to the preview fixture; consumers should pass their actual loaded count.
+ */
+export function LoadMoreFooter(props: LoadMoreFooterProps = {}) {
+  const hasAnnouncer = useHasLiveAnnouncer();
+  return hasAnnouncer ? (
+    <LoadMoreFooterContent {...props} />
+  ) : (
+    <LiveAnnouncer>
+      <LoadMoreFooterContent {...props} />
+    </LiveAnnouncer>
+  );
+}
+
+function LoadMoreFooterContent(props: LoadMoreFooterProps) {
+  const { t } = useI18n();
+  const {
+    nextCursor,
+    hasMore,
+    loading = false,
+    error = '',
+    exhaustedFocusTarget = 'summary',
+    loadedCount = LOAD_MORE_PREVIEW.loadedCount,
+    labels,
+    className,
+  } = props;
+  // Only the no-input preview uses a fixture cursor. Explicit undefined remains flag mode.
+  const cursor = Object.keys(props).length === 0 ? LOAD_MORE_PREVIEW.nextCursor : nextCursor;
+  const available =
+    cursor === undefined ? hasMore === true : typeof cursor === 'string' && cursor.length > 0 && hasMore !== false;
+  const failed = error.length > 0;
+  const cursorMode = cursor !== undefined;
+  const panel = cursorMode && failed;
+  const control = !available ? 'none' : panel ? 'retry' : 'button';
+  const { rootRef, summaryRef, controlRef, inFlightCursorRef } = useLoadMoreFooter(
+    control,
+    exhaustedFocusTarget,
+    loading,
+    error,
+  );
+  const errorId = useId();
+  useLoadMoreAnnouncements(
+    loading,
+    error,
+    props.lastAppend,
+    labels?.loadedAnnouncement ?? ((count) => t('table.loadedAnnouncement', { count })),
+  );
+  const load = () => {
+    if (loading || !available) return;
+    inFlightCursorRef.current = cursor ?? undefined;
+    if (cursor === undefined) props.onLoadMore?.();
+    else props.onLoadMore?.(cursor ?? undefined);
+  };
+  const retry = () => {
+    if (loading || !available) return;
+    const handler = props.onRetry ?? props.onLoadMore;
+    if (cursorMode) handler?.(inFlightCursorRef.current ?? cursor ?? undefined);
+    else handler?.();
+  };
+  return (
+    <div
+      ref={rootRef}
+      role="group"
+      aria-label={labels?.group ?? t('table.loadMoreGroup')}
+      tabIndex={-1}
+      aria-busy={loading}
+      className={cn('flex flex-col gap-3 sm:flex-row sm:items-center sm:justify-between', className)}
+    >
+      <p ref={summaryRef} tabIndex={-1} className="text-sm text-muted-foreground tabular-nums">
+        {labels?.summary?.(loadedCount) ?? t('table.loadedSummary', { count: loadedCount })}{' '}
+        {available && <span>{labels?.moreAvailable ?? t('table.moreAvailable')}</span>}
+      </p>
+      {panel ? (
+        <div key={available ? 'retry' : 'exhausted'} ref={available ? controlRef : undefined}>
+          <ErrorPanel
+            title={error}
+            message={null}
+            code={null}
+            requestId=""
+            details=""
+            secondaryAction={null}
+            onRetry={available ? retry : undefined}
+            retrying={loading}
+            retryLabel={labels?.retry ?? t('error.retry')}
+          />
+        </div>
+      ) : (
+        <>
+          {failed && (
+            <p id={errorId} className="text-sm text-destructive-text">
+              {error}
+            </p>
+          )}
+          {available && (
+            <Button
+              ref={controlRef}
+              loading={loading}
+              onClick={failed ? retry : load}
+              aria-describedby={failed ? errorId : undefined}
+            >
+              {loading
+                ? (labels?.loading ?? t('table.loadingMore'))
+                : failed
+                  ? (labels?.retry ?? t('error.retry'))
+                  : (labels?.loadMore ?? t('table.loadMore'))}
+            </Button>
+          )}
+        </>
+      )}
+    </div>
+  );
+}

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

@@ -0,0 +1,28 @@
+import type { BlockMeta } from '../../meta';
+import type { LoadMoreFooterLabels } from './LoadMoreFooter';
+
+export const meta: BlockMeta = {
+  name: 'Load more footer',
+  family: 'tables',
+  status: 'beta',
+  description:
+    'A load more button and loaded-count summary for appended lists without a total or page count. Cursor mode uses nextCursor and optional hasMore; flag mode omits nextCursor and uses hasMore. Compose with DataTable paginated={false} or Collapsible and JsonViewer cards. The consumer owns rows, filters and cursor normalization. Each attempt must settle loading=false together with its result in one update; split settles are unsupported. Keep cursor, hasMore, counts and lastAppend unchanged on failure. Cursor failures replace the button with ErrorPanel; flag failures keep the same button. Exhaustion removes every control even on failure. Focus moves only when the focused control is removed, to its replacement or exhaustedFocusTarget (summary by default, root optionally). lastAppend uses increasing seq values for successful appends, never initial loads, replacements or failures. New appended counts are announced politely; settled errors assertively. Self-wraps in LiveAnnouncer when needed. Every label has translated defaults and per-key overrides.',
+  labels: [
+    { key: 'loadMore', type: 'string', state: 'Available and idle: button name' },
+    { key: 'loading', type: 'string', state: 'Loading: button name; ErrorPanel uses its own translated busy text' },
+    { key: 'retry', type: 'string', state: 'Failed and available: retry button name' },
+    { key: 'group', type: 'string', state: 'Always: root group accessible name' },
+    { key: 'moreAvailable', type: 'string', state: 'Available: visible summary note' },
+    {
+      key: 'summary',
+      type: '(count: number) => string',
+      state: 'Always: loaded-count summary and default exhaustion focus target',
+    },
+    {
+      key: 'loadedAnnouncement',
+      type: '(count: number) => string',
+      state: 'New lastAppend.seq with positive count: polite announcement',
+    },
+  ] satisfies Array<{ key: keyof LoadMoreFooterLabels; type: string; state: string }>,
+  uses: ['Button', 'ErrorPanel', 'LiveAnnouncer'],
+};

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

@@ -0,0 +1,22 @@
+import { Collapsible, CollapsiblePanel, CollapsibleTrigger, JsonViewer } from '@gntik-ai/ui';
+import { LoadMoreFooter } from '../LoadMoreFooter';
+import { useMockCursor } from './useMockCursor';
+
+/** A mocked cursor consumer can append cards just as it appends table rows. */
+export default function CardsExample() {
+  const { rows, load, ...state } = useMockCursor();
+  return (
+    <div className="space-y-4">
+      {rows.map((row) => (
+        <Collapsible key={row.id} variant="row">
+          <CollapsibleTrigger>{row.name}</CollapsibleTrigger>
+          <CollapsiblePanel>
+            <JsonViewer label={`${row.name} data`} data={row} />
+          </CollapsiblePanel>
+        </Collapsible>
+      ))}
+      {/* Settle loading=false and its result in one update; split settles are unsupported. */}
+      <LoadMoreFooter {...state} loadedCount={rows.length} onLoadMore={load} onRetry={load} />
+    </div>
+  );
+}

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

@@ -0,0 +1,25 @@
+import { DataTable } from '../../DataTable/DataTable';
+import { LoadMoreFooter } from '../LoadMoreFooter';
+import { useMockCursor } from './useMockCursor';
+
+/** The consumer appends rows; DataTable must use paginated={false}. */
+export default function CursorExample() {
+  const { rows, load, ...state } = useMockCursor();
+  return (
+    <div className="space-y-4">
+      <DataTable
+        rows={rows}
+        columns={[{ id: 'name', header: 'Name', accessor: (row) => row.name }]}
+        caption="Records"
+        paginated={false}
+        selectable={false}
+        showColumnMenu={false}
+        showDensityToggle={false}
+        showViewSwitcher={false}
+        resizable={false}
+      />
+      {/* Each attempt settles loading=false together with its result in one update; split settles are unsupported. */}
+      <LoadMoreFooter {...state} loadedCount={rows.length} onLoadMore={load} onRetry={load} />
+    </div>
+  );
+}

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

@@ -0,0 +1,6 @@
+import { LoadMoreFooter } from '../LoadMoreFooter';
+
+/** Exhausted lists have no controls, including when a settled error remains visible. */
+export default function ExhaustedExample() {
+  return <LoadMoreFooter nextCursor={null} loadedCount={40} error="Request failed" />;
+}

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

@@ -0,0 +1,13 @@
+import { useState } from 'react';
+import { LoadMoreFooter } from '../LoadMoreFooter';
+
+export default function FailedExample() {
+  const [state, setState] = useState({ loading: false, error: 'Could not load more items.' });
+  const retry = async () => {
+    setState((previous) => ({ ...previous, loading: true }));
+    await Promise.resolve();
+    // Settle loading=false with its result in one update. Split settles are unsupported.
+    setState({ loading: false, error: '' });
+  };
+  return <LoadMoreFooter nextCursor="c1" loadedCount={20} {...state} onLoadMore={retry} onRetry={retry} />;
+}