@gntik-ai/blocks 0.0.0-stage → 0.5.0

package/src/tables/PaginationFooter/PaginationFooter.tsx

@@ -0,0 +1,94 @@
+import { cn, Pagination, SimpleSelect, useI18n } from '@gntik-ai/ui';
+import { useState } from 'react';
+
+export interface PaginationFooterProps {
+  /** Total number of rows. */
+  total?: number;
+  /** Current page, 1-based (controlled). */
+  page?: number;
+  defaultPage?: number;
+  onPageChange?: (page: number) => void;
+  /** Rows per page (controlled). */
+  pageSize?: number;
+  defaultPageSize?: number;
+  onPageSizeChange?: (pageSize: number) => void;
+  pageSizeOptions?: readonly number[];
+  /** What the rows are, for the accessible names ("Deployments"). */
+  noun?: string;
+  locale?: string;
+  className?: string;
+}
+
+/** Table footer: rows-per-page Select, a "1–10 of 97" summary and numbered Pagination. Stacks on small screens. */
+export function PaginationFooter({
+  total = 97,
+  page: pageProp,
+  defaultPage = 1,
+  onPageChange,
+  pageSize: sizeProp,
+  defaultPageSize = 10,
+  onPageSizeChange,
+  pageSizeOptions = [10, 25, 50, 100],
+  noun: nounProp,
+  locale: localeProp,
+  className,
+}: PaginationFooterProps) {
+  const { t, locale: providerLocale } = useI18n();
+  const locale = localeProp ?? providerLocale;
+  const noun = nounProp ?? t('table.rows');
+  const [innerPage, setInnerPage] = useState(defaultPage);
+  const [innerSize, setInnerSize] = useState(defaultPageSize);
+  const pageSize = sizeProp ?? innerSize;
+  const pageCount = Math.max(1, Math.ceil(total / Math.max(1, pageSize)));
+  const page = Math.min(Math.max(1, pageProp ?? innerPage), pageCount);
+  const from = total === 0 ? 0 : (page - 1) * pageSize + 1;
+  const to = Math.min(page * pageSize, total);
+  const fmt = (n: number) => n.toLocaleString(locale);
+
+  const goTo = (next: number) => {
+    setInnerPage(next);
+    onPageChange?.(next);
+  };
+  const resize = (value: string | null) => {
+    const next = Number(value);
+    if (!next || next === pageSize) return;
+    setInnerSize(next);
+    onPageSizeChange?.(next);
+    // Keep the first visible row on screen.
+    const nextPage = Math.floor((from - 1) / next) + 1;
+    if (nextPage !== page) goTo(Math.max(1, nextPage));
+  };
+
+  return (
+    <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')}
+        </span>
+        <SimpleSelect
+          aria-label={t('table.rowsPerPage')}
+          size="sm"
+          className="w-[76px] font-mono"
+          value={String(pageSize)}
+          onValueChange={resize}
+          items={pageSizeOptions.map((n) => ({ value: String(n), label: String(n) }))}
+        />
+      </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>
+        </p>
+        <Pagination
+          page={page}
+          pageCount={pageCount}
+          onPageChange={goTo}
+          size="sm"
+          labels={{ nav: t('table.pagination', { noun }) }}
+        />
+      </div>
+    </div>
+  );
+}

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

@@ -0,0 +1,10 @@
+import type { BlockMeta } from '../../meta';
+
+export const meta: BlockMeta = {
+  name: 'Pagination footer',
+  family: 'tables',
+  status: 'beta',
+  description:
+    'Table footer with a rows-per-page Select, a "1–10 of 97" summary and numbered Pagination; controlled or uncontrolled.',
+  uses: ['SimpleSelect', 'Pagination'],
+};

package/src/tables/SubordinateList/SubordinateList.test.tsx

@@ -0,0 +1,351 @@
+import { render, screen, within } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { I18nProvider } from '@gntik-ai/ui';
+import { expectNoAxeViolations } from '../../test/a11y';
+import type { DataTableColumn } from '../DataTable/data-table-utils';
+import { SubordinateList, type SubordinateListProps } from './SubordinateList';
+import ResourceFormExample from './examples/ResourceForm';
+
+interface Row {
+  id: string;
+  name: string;
+}
+const columns: DataTableColumn<Row>[] = [{ id: 'name', header: 'Name', accessor: (row) => row.name, sortable: true }];
+const rows: Row[] = Array.from({ length: 12 }, (_, i) => ({
+  id: String(i),
+  name: `Record ${i + 1}`,
+}));
+const props: SubordinateListProps<Row> = {
+  title: 'History',
+  headingLevel: 'h2',
+  count: 37,
+  columns,
+  rows,
+  getRowId: (row) => row.id,
+  pagination: null,
+  loading: false,
+  error: null,
+  onRetry: () => {},
+  emptyState: <p>No history yet</p>,
+};
+
+// The public prop contract: every omitted input must be a type error.
+function requiredProps(input: SubordinateListProps<Row>) {
+  const { title, headingLevel, count, columns, rows, getRowId, pagination, loading, error, onRetry, emptyState } =
+    input;
+  // @ts-expect-error title is required
+  <SubordinateList
+    headingLevel={headingLevel}
+    count={count}
+    columns={columns}
+    rows={rows}
+    getRowId={getRowId}
+    pagination={pagination}
+    loading={loading}
+    error={error}
+    onRetry={onRetry}
+    emptyState={emptyState}
+  />;
+  // @ts-expect-error headingLevel is required
+  <SubordinateList
+    title={title}
+    count={count}
+    columns={columns}
+    rows={rows}
+    getRowId={getRowId}
+    pagination={pagination}
+    loading={loading}
+    error={error}
+    onRetry={onRetry}
+    emptyState={emptyState}
+  />;
+  // @ts-expect-error count is required
+  <SubordinateList
+    title={title}
+    headingLevel={headingLevel}
+    columns={columns}
+    rows={rows}
+    getRowId={getRowId}
+    pagination={pagination}
+    loading={loading}
+    error={error}
+    onRetry={onRetry}
+    emptyState={emptyState}
+  />;
+  // @ts-expect-error columns are required
+  <SubordinateList
+    title={title}
+    headingLevel={headingLevel}
+    count={count}
+    rows={rows}
+    getRowId={getRowId}
+    pagination={pagination}
+    loading={loading}
+    error={error}
+    onRetry={onRetry}
+    emptyState={emptyState}
+  />;
+  // @ts-expect-error rows are required
+  <SubordinateList
+    title={title}
+    headingLevel={headingLevel}
+    count={count}
+    columns={columns}
+    getRowId={getRowId}
+    pagination={pagination}
+    loading={loading}
+    error={error}
+    onRetry={onRetry}
+    emptyState={emptyState}
+  />;
+  // @ts-expect-error getRowId is required
+  <SubordinateList
+    title={title}
+    headingLevel={headingLevel}
+    count={count}
+    columns={columns}
+    rows={rows}
+    pagination={pagination}
+    loading={loading}
+    error={error}
+    onRetry={onRetry}
+    emptyState={emptyState}
+  />;
+  // @ts-expect-error pagination is required
+  <SubordinateList
+    title={title}
+    headingLevel={headingLevel}
+    count={count}
+    columns={columns}
+    rows={rows}
+    getRowId={getRowId}
+    loading={loading}
+    error={error}
+    onRetry={onRetry}
+    emptyState={emptyState}
+  />;
+  // @ts-expect-error loading is required
+  <SubordinateList
+    title={title}
+    headingLevel={headingLevel}
+    count={count}
+    columns={columns}
+    rows={rows}
+    getRowId={getRowId}
+    pagination={pagination}
+    error={error}
+    onRetry={onRetry}
+    emptyState={emptyState}
+  />;
+  // @ts-expect-error error is required
+  <SubordinateList
+    title={title}
+    headingLevel={headingLevel}
+    count={count}
+    columns={columns}
+    rows={rows}
+    getRowId={getRowId}
+    pagination={pagination}
+    loading={loading}
+    onRetry={onRetry}
+    emptyState={emptyState}
+  />;
+  // @ts-expect-error onRetry is required
+  <SubordinateList
+    title={title}
+    headingLevel={headingLevel}
+    count={count}
+    columns={columns}
+    rows={rows}
+    getRowId={getRowId}
+    pagination={pagination}
+    loading={loading}
+    error={error}
+    emptyState={emptyState}
+  />;
+  // @ts-expect-error emptyState is required
+  <SubordinateList
+    title={title}
+    headingLevel={headingLevel}
+    count={count}
+    columns={columns}
+    rows={rows}
+    getRowId={getRowId}
+    pagination={pagination}
+    loading={loading}
+    error={error}
+    onRetry={onRetry}
+  />;
+}
+void requiredProps;
+
+describe('SubordinateList', () => {
+  it('embeds a paginated history and an unpaginated consumer section in a resource-form host', async () => {
+    render(<ResourceFormExample />);
+    expect(screen.getByRole('form', { name: 'Resource settings' })).toBeVisible();
+    const history = screen.getByRole('region', { name: 'History' });
+    const consumers = screen.getByRole('region', { name: 'Consumers' });
+    expect(within(history).getByRole('navigation', { name: 'History pagination' })).toBeVisible();
+    expect(within(consumers).queryByRole('navigation')).not.toBeInTheDocument();
+    await expectNoAxeViolations(document.body);
+  });
+
+  for (const theme of ['dark', 'light', 'high_contrast']) {
+    it.each(['default', 'loading', 'empty', 'error'] as const)(
+      `has no axe violations in ${theme} / %s`,
+      async (state) => {
+        document.documentElement.className = theme;
+        const { container } = render(
+          <SubordinateList
+            {...props}
+            loading={state === 'loading'}
+            rows={state === 'empty' ? [] : rows}
+            error={
+              state === 'error'
+                ? {
+                    title: 'History unavailable',
+                    message: 'Please retry.',
+                    code: null,
+                  }
+                : null
+            }
+            pagination={{
+              limit: 10,
+              offset: 0,
+              total: state === 'empty' ? 0 : 37,
+              onPageChange: () => {},
+            }}
+          />,
+        );
+        await expectNoAxeViolations(container);
+      },
+    );
+  }
+
+  it.each(['en', 'es'])('shows only the supplied error and retries the failing section once in %s', async (locale) => {
+    const user = userEvent.setup();
+    const onRetry = vi.fn();
+    render(
+      <I18nProvider locale={locale}>
+        <SubordinateList
+          {...props}
+          error={{
+            title: 'History unavailable',
+            message: 'Please retry this section.',
+            code: null,
+          }}
+          onRetry={onRetry}
+        />
+        <SubordinateList {...props} title="Consumers" headingLevel="h3" />
+      </I18nProvider>,
+    );
+    const failed = screen.getByRole('region', { name: 'History' });
+    expect(
+      within(failed).getByRole('heading', {
+        name: 'History unavailable',
+        level: 3,
+      }),
+    ).toBeVisible();
+    expect(failed).toHaveTextContent('Please retry this section.');
+    expect(failed).not.toHaveTextContent(/503|req_|Contact support|deployments|Add policy/i);
+    expect(within(failed).queryByRole('table')).not.toBeInTheDocument();
+    expect(within(failed).queryByRole('navigation')).not.toBeInTheDocument();
+    const retryLabel = locale === 'es' ? 'Reintentar' : 'Try again';
+    await user.click(within(failed).getByRole('button', { name: retryLabel }));
+    expect(onRetry).toHaveBeenCalledTimes(1);
+    const healthy = screen.getByRole('region', { name: 'Consumers' });
+    expect(within(healthy).getByRole('table', { name: 'Consumers' })).toBeVisible();
+    expect(within(healthy).queryByRole('button', { name: retryLabel })).not.toBeInTheDocument();
+  });
+
+  it('shows an explicit error code and keeps the header while a section has failed', () => {
+    render(
+      <SubordinateList
+        {...props}
+        error={{
+          title: 'History unavailable',
+          message: 'Try later.',
+          code: 'E_LOAD',
+        }}
+      />,
+    );
+    expect(screen.getByText('E_LOAD')).toBeVisible();
+    expect(screen.getByRole('heading', { name: 'History', level: 2 })).toBeVisible();
+  });
+
+  it('replaces the table and pagination with a busy TableSkeleton while loading', () => {
+    render(
+      <SubordinateList
+        {...props}
+        loading={true}
+        pagination={{ limit: 10, offset: 0, total: 37, onPageChange: () => {} }}
+      />,
+    );
+    expect(screen.getByRole('region', { name: 'History' })).toHaveAttribute('aria-busy', 'true');
+    expect(screen.getByRole('status')).toHaveTextContent('Loading table');
+    expect(screen.queryByRole('table')).not.toBeInTheDocument();
+    expect(screen.queryByRole('navigation')).not.toBeInTheDocument();
+  });
+
+  it('renders the host empty state instead of a table when rows are empty', () => {
+    render(<SubordinateList {...props} rows={[]} count={0} />);
+    expect(screen.getByText('No history yet')).toBeVisible();
+    expect(screen.queryByRole('table')).not.toBeInTheDocument();
+    expect(screen.getByRole('region', { name: 'History' })).toHaveAttribute('aria-busy', 'false');
+  });
+
+  it('renders every supplied row with server pagination and translates page 2 to offset 10', async () => {
+    const user = userEvent.setup();
+    const onPageChange = vi.fn();
+    const { rerender } = render(
+      <SubordinateList {...props} pagination={{ limit: 10, offset: 0, total: 37, onPageChange }} />,
+    );
+    expect(screen.getAllByRole('row')).toHaveLength(13);
+    expect(screen.getByRole('region', { name: 'History' })).toHaveTextContent('1–10 of 37');
+    expect(screen.getByRole('navigation', { name: 'History pagination' })).toBeVisible();
+    await user.click(screen.getByRole('button', { name: 'Page 2' }));
+    expect(onPageChange).toHaveBeenCalledExactlyOnceWith(10);
+    // Controlled: only a new host offset changes the page summary.
+    expect(screen.getByText('1–10')).toBeVisible();
+    rerender(<SubordinateList {...props} pagination={{ limit: 10, offset: 10, total: 37, onPageChange }} />);
+    expect(screen.getByText('11–20')).toBeVisible();
+    await user.click(screen.getByRole('combobox', { name: 'Rows per page' }));
+    expect(await screen.findAllByRole('option')).toHaveLength(1);
+    expect(screen.getByRole('option', { name: '10' })).toBeVisible();
+  });
+
+  it('renders a large unpaginated collection without list controls, sorting, virtualization or sticky elements', () => {
+    const largeRows = Array.from({ length: 120 }, (_, i) => ({
+      id: String(i),
+      name: `Entry ${i}`,
+    }));
+    const { container } = render(<SubordinateList {...props} rows={largeRows} count={120} />);
+    expect(screen.getAllByRole('row')).toHaveLength(121);
+    expect(screen.queryByRole('navigation')).not.toBeInTheDocument();
+    expect(screen.queryByRole('checkbox')).not.toBeInTheDocument();
+    expect(screen.queryByRole('button')).not.toBeInTheDocument();
+    expect(screen.queryByRole('toolbar')).not.toBeInTheDocument();
+    expect(screen.queryByRole('searchbox')).not.toBeInTheDocument();
+    expect(screen.getByRole('table', { name: 'History' })).not.toHaveAttribute('data-virtualized');
+    for (const element of container.querySelectorAll<HTMLElement>('*')) {
+      expect(element.classList.contains('sticky')).toBe(false);
+      expect(getComputedStyle(element).position).not.toBe('sticky');
+    }
+  });
+
+  it.each(['h2', 'h3'] as const)(
+    'labels the section with its %s heading and shows count 0 without fixture actions or description',
+    (headingLevel) => {
+      render(<SubordinateList {...props} headingLevel={headingLevel} count={0} />);
+      const region = screen.getByRole('region', { name: 'History' });
+      const heading = within(region).getByRole('heading', {
+        name: 'History',
+        level: headingLevel === 'h2' ? 2 : 3,
+      });
+      expect(region).toHaveAttribute('aria-labelledby', heading.id);
+      expect(within(region).getByText('0')).toBeVisible();
+      expect(within(region).queryByRole('button')).not.toBeInTheDocument();
+      expect(region).not.toHaveTextContent(/Add policy|Guardrails|deployments/i);
+    },
+  );
+});

package/src/tables/SubordinateList/SubordinateList.tsx

@@ -0,0 +1,140 @@
+import { useId, type ReactNode } from 'react';
+import { SectionHeader } from '../../page-chrome/SectionHeader/SectionHeader';
+import { TableSkeleton } from '../../feedback/Skeletons/Skeletons';
+import { ErrorPanel } from '../../feedback/ErrorPanel/ErrorPanel';
+import { ServerCrash } from '@gntik-ai/icons';
+import { DataTable } from '../DataTable/DataTable';
+import type { DataTableColumn } from '../DataTable/data-table-utils';
+import { PaginationFooter } from '../PaginationFooter/PaginationFooter';
+import { useI18n } from '@gntik-ai/ui';
+
+export interface SubordinateListPagination {
+  /** Positive server page size. */
+  limit: number;
+  /** Zero-based server offset. */
+  offset: number;
+  total: number;
+  onPageChange: (offset: number) => void;
+}
+
+export interface SubordinateListError {
+  title: string;
+  message: string;
+  /** null hides the error code chip. */
+  code: string | number | null;
+}
+
+export interface SubordinateListProps<T> {
+  title: string;
+  headingLevel: 'h2' | 'h3';
+  /** Server total, or the length of an unpaginated collection (including zero). */
+  count: number;
+  columns: ReadonlyArray<DataTableColumn<T>>;
+  rows: readonly T[];
+  getRowId: (row: T) => string;
+  pagination: SubordinateListPagination | null;
+  loading: boolean;
+  error: SubordinateListError | null;
+  onRetry: () => void | Promise<void>;
+  /** Host-supplied EmptyStates composition. */
+  emptyState: ReactNode;
+}
+
+/** Read-only list section with explicit host data and no demo defaults. */
+export function SubordinateList<T>({
+  title,
+  headingLevel,
+  count,
+  columns,
+  rows,
+  getRowId,
+  pagination,
+  loading,
+  error,
+  onRetry,
+  emptyState,
+}: SubordinateListProps<T>) {
+  const headingId = useId();
+  const { locale, t } = useI18n();
+  return (
+    <section aria-labelledby={headingId} aria-busy={loading} className="space-y-4">
+      <SectionHeader
+        title={title}
+        as={headingLevel}
+        count={count}
+        description={null}
+        actions={[]}
+        bordered={true}
+        headingId={headingId}
+        className=""
+      />
+      {error !== null ? (
+        <ErrorPanel
+          icon={ServerCrash}
+          title={error.title}
+          message={error.message}
+          code={error.code}
+          requestId=""
+          details=""
+          onRetry={onRetry}
+          retrying={undefined}
+          retryLabel={t('error.retry')}
+          secondaryAction={null}
+          titleAs="h3"
+          className=""
+        />
+      ) : loading ? (
+        <TableSkeleton rows={pagination?.limit ?? 5} columns={columns.length} label={t('loading.table')} className="" />
+      ) : rows.length === 0 ? (
+        emptyState
+      ) : (
+        <DataTable
+          rows={rows}
+          columns={columns.map((column) => ({
+            ...column,
+            sortable: false,
+            editable: false,
+          }))}
+          getRowId={getRowId}
+          caption={title}
+          showCaption={false}
+          paginated={false}
+          selectable={false}
+          selectedIds={[]}
+          selectionSummary={false}
+          sort={null}
+          defaultSort={null}
+          manualSorting={true}
+          showColumnMenu={false}
+          showDensityToggle={false}
+          showViewSwitcher={false}
+          resizable={false}
+          pinnedColumns={{}}
+          showPinMenu={false}
+          virtualize={false}
+          hiddenColumns={[]}
+          toolbar={null}
+          loading={false}
+          loadingRows={0}
+          emptyState={emptyState}
+          className=""
+        />
+      )}
+      {error === null && !loading && pagination !== null && (
+        <PaginationFooter
+          total={pagination.total}
+          page={Math.floor(pagination.offset / pagination.limit) + 1}
+          defaultPage={1}
+          onPageChange={(page) => pagination.onPageChange((page - 1) * pagination.limit)}
+          pageSize={pagination.limit}
+          defaultPageSize={pagination.limit}
+          onPageSizeChange={() => {}}
+          pageSizeOptions={[pagination.limit]}
+          noun={title}
+          locale={locale}
+          className=""
+        />
+      )}
+    </section>
+  );
+}

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

@@ -0,0 +1,10 @@
+import type { BlockMeta } from '../../meta';
+
+export const meta: BlockMeta = {
+  name: 'Subordinate list',
+  family: 'tables',
+  status: 'beta',
+  description:
+    'Read-only list section inside a resource-form host, composing section-header, data-table, pagination-footer, empty-states, skeletons and error-panel. All props are required: title (string), headingLevel (h2 or h3), count (number, including 0), columns (typed DataTableColumn<T>[]), rows (readonly T[]), getRowId, pagination ({limit, offset, total, onPageChange(offset)} or null), loading (boolean), error ({title, message, code: string | number | null} or null), onRetry and emptyState (host-supplied ReactNode). Every supplied row renders; server pagination converts the zero-based offset to a 1-based footer page and fixes pageSizeOptions to [limit]. No filtering, sorting, selection, create action, toolbar, virtualization, pinning or sticky region. Error takes precedence over loading, then empty and data; retry uses the current i18n locale. Error headings use h3 for either section heading level. Composition example: packages/blocks/src/tables/SubordinateList/examples/ResourceForm.tsx uses the resource-form form sections and sticky save bar with a server-paginated History section and an unpaginated Consumers section.',
+  uses: ['section-header', 'data-table', 'pagination-footer', 'empty-states', 'skeletons', 'error-panel'],
+};