@gntik-ai/blocks 0.0.0-stage → 0.6.0

package/src/tables/InlineEditRow/InlineEditRow.tsx

@@ -0,0 +1,215 @@
+import { Check, Pencil, X } from '@gntik-ai/icons';
+import {
+  cn,
+  IconButton,
+  Input,
+  Table,
+  TableBody,
+  TableCaption,
+  TableCell,
+  TableHead,
+  TableHeader,
+  TableRow,
+  useI18n,
+} from '@gntik-ai/ui';
+import { useEffect, useRef, useState, type KeyboardEvent } from 'react';
+import { EDITABLE_MEMBER_FIELDS, EDITABLE_MEMBERS, type EditableMember } from './fixtures';
+
+type Editable = string | number;
+
+export interface InlineEditField<T> {
+  key: Extract<keyof T, string>;
+  label: string;
+  type?: 'text' | 'number' | 'email';
+  align?: 'left' | 'right';
+  required?: boolean;
+  /** Read-mode cell classes. */
+  className?: string;
+}
+
+export interface InlineEditRowProps<T extends object> {
+  row: T;
+  fields: ReadonlyArray<InlineEditField<T>>;
+  /** Called with the edited row on Save (or Enter). */
+  onSave?: (next: T) => void;
+  onCancel?: () => void;
+  /** Row name for the Edit button label ("Edit Ana Lopez"). */
+  rowLabel?: string;
+  /** Start in edit mode. */
+  defaultEditing?: boolean;
+}
+
+const read = <T extends object>(row: T, key: string): Editable => {
+  const v = (row as Record<string, unknown>)[key];
+  return typeof v === 'number' ? v : v == null ? '' : String(v);
+};
+
+/**
+ * A table row that switches into edit mode: inputs replace the cells, with Save and Cancel.
+ * Enter saves, Escape cancels; focus moves to the first input and back to Edit afterwards.
+ */
+export function InlineEditRow<T extends object>({
+  row,
+  fields,
+  onSave,
+  onCancel,
+  rowLabel,
+  defaultEditing = false,
+}: InlineEditRowProps<T>) {
+  const { t } = useI18n();
+  const [editing, setEditing] = useState(defaultEditing);
+  const [draft, setDraft] = useState<Record<string, string>>({});
+  const editRef = useRef<HTMLButtonElement>(null);
+  const firstInputRef = useRef<HTMLInputElement>(null);
+  const restoreFocus = useRef(false);
+  const label = rowLabel ?? String(read(row, fields[0]?.key ?? ''));
+
+  useEffect(() => {
+    if (editing) firstInputRef.current?.focus();
+    else if (restoreFocus.current) {
+      restoreFocus.current = false;
+      editRef.current?.focus();
+    }
+  }, [editing]);
+
+  const start = () => {
+    setDraft(Object.fromEntries(fields.map((f) => [f.key, String(read(row, f.key))])));
+    setEditing(true);
+  };
+  const finish = () => {
+    restoreFocus.current = true;
+    setEditing(false);
+  };
+  const invalid = (f: InlineEditField<T>) => f.required === true && (draft[f.key] ?? '').trim() === '';
+  const save = () => {
+    if (fields.some(invalid)) return;
+    const next = { ...row } as Record<string, unknown>;
+    for (const f of fields) {
+      const value = draft[f.key] ?? '';
+      next[f.key] = f.type === 'number' ? Number(value) : value;
+    }
+    onSave?.(next as T);
+    finish();
+  };
+  const cancel = () => {
+    onCancel?.();
+    finish();
+  };
+  const onKeyDown = (event: KeyboardEvent<HTMLTableRowElement>) => {
+    if (!editing) return;
+    if (event.key === 'Escape') {
+      event.preventDefault();
+      cancel();
+    } else if (event.key === 'Enter' && event.target instanceof HTMLInputElement) {
+      event.preventDefault();
+      save();
+    }
+  };
+
+  return (
+    <TableRow selected={editing} onKeyDown={onKeyDown} data-editing={editing || undefined}>
+      {fields.map((f, i) => (
+        <TableCell key={f.key} align={f.align} className={cn(!editing && f.className, editing && 'py-1.5')}>
+          {editing ? (
+            <Input
+              ref={i === 0 ? firstInputRef : undefined}
+              aria-label={f.label}
+              type={f.type ?? 'text'}
+              size="sm"
+              required={f.required}
+              invalid={invalid(f)}
+              value={draft[f.key] ?? ''}
+              onValueChange={(v) => setDraft((d) => ({ ...d, [f.key]: String(v) }))}
+              inputClassName={f.align === 'right' ? 'text-end' : undefined}
+              className="min-w-24"
+            />
+          ) : (
+            read(row, f.key)
+          )}
+        </TableCell>
+      ))}
+      <TableCell align="right" className="w-24 py-1.5 whitespace-nowrap">
+        {editing ? (
+          <span className="inline-flex gap-1">
+            <IconButton
+              icon={Check}
+              label={t('common.save')}
+              size="sm"
+              variant="soft"
+              onClick={save}
+              disabled={fields.some(invalid)}
+            />
+            <IconButton icon={X} label={t('common.cancel')} size="sm" variant="ghost" onClick={cancel} />
+          </span>
+        ) : (
+          <IconButton
+            ref={editRef}
+            icon={Pencil}
+            label={t('table.editRow', { label })}
+            size="sm"
+            variant="ghost"
+            onClick={start}
+          />
+        )}
+      </TableCell>
+    </TableRow>
+  );
+}
+
+export interface InlineEditTableProps<T extends object> {
+  rows?: readonly T[];
+  fields?: ReadonlyArray<InlineEditField<T>>;
+  getRowId?: (row: T) => string;
+  caption?: string;
+  /** Called with the saved row; rows also update locally. */
+  onRowSave?: (row: T) => void;
+  className?: string;
+}
+
+/** Standalone demo of InlineEditRow: a small editable table that keeps its rows in state. */
+export function InlineEditTable<T extends object = EditableMember>({
+  rows: initialRows = EDITABLE_MEMBERS as unknown as readonly T[],
+  fields = EDITABLE_MEMBER_FIELDS as unknown as ReadonlyArray<InlineEditField<T>>,
+  getRowId = (row) => String((row as { id?: unknown }).id ?? ''),
+  caption = 'Members',
+  onRowSave,
+  className,
+}: InlineEditTableProps<T>) {
+  const { t } = useI18n();
+  const [rows, setRows] = useState<readonly T[]>(initialRows);
+  return (
+    <div className={cn('overflow-hidden rounded-xl border border-border bg-card shadow-sm', className)}>
+      <Table>
+        <TableCaption srOnly>{caption}</TableCaption>
+        <TableHeader>
+          <TableRow className="hover:bg-transparent">
+            {fields.map((f) => (
+              <TableHead key={f.key} align={f.align}>
+                {f.label}
+              </TableHead>
+            ))}
+            <TableHead align="right">
+              <span className="sr-only">{t('table.actions')}</span>
+            </TableHead>
+          </TableRow>
+        </TableHeader>
+        <TableBody>
+          {rows.map((row) => {
+            const id = getRowId(row);
+            return (
+              <InlineEditRow
+                key={id}
+                row={row}
+                fields={fields}
+                onSave={(next) => {
+                  setRows((prev) => prev.map((r) => (getRowId(r) === id ? next : r)));
+                  onRowSave?.(next);
+                }}
+              />
+            );
+          })}
+        </TableBody>
+      </Table>
+    </div>
+  );
+}

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

@@ -0,0 +1,10 @@
+import type { BlockMeta } from '../../meta';
+
+export const meta: BlockMeta = {
+  name: 'Inline edit row',
+  family: 'tables',
+  status: 'beta',
+  description:
+    'A table row that switches into edit mode with inputs, Save and Cancel; Enter saves, Escape cancels and focus returns to Edit. InlineEditTable is a ready-made editable table.',
+  uses: ['Table', 'Input', 'IconButton'],
+};

package/src/tables/InlineEditRow/fixtures.ts

@@ -0,0 +1,28 @@
+import type { InlineEditField } from './InlineEditRow';
+
+export interface EditableMember {
+  id: string;
+  name: string;
+  email: string;
+  role: string;
+  seats: number;
+}
+
+export const EDITABLE_MEMBER_FIELDS: InlineEditField<EditableMember>[] = [
+  { key: 'name', label: 'Name', required: true },
+  {
+    key: 'email',
+    label: 'Email',
+    type: 'email',
+    required: true,
+    className: 'font-mono text-[12px] text-muted-foreground',
+  },
+  { key: 'role', label: 'Role' },
+  { key: 'seats', label: 'Seats', type: 'number', align: 'right', className: 'font-mono text-[12.5px]' },
+];
+
+export const EDITABLE_MEMBERS: EditableMember[] = [
+  { id: 'm1', name: 'Ana Lopez', email: 'ana@example.com', role: 'Owner', seats: 3 },
+  { id: 'm2', name: 'Sam Carter', email: 'sam@example.com', role: 'Admin', seats: 2 },
+  { id: 'm3', name: 'Priya Nair', email: 'priya@example.com', role: 'Member', seats: 1 },
+];

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.test.tsx

@@ -0,0 +1,29 @@
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { expectNoAxeViolations } from '../../test/a11y';
+import { PaginationFooter } from './PaginationFooter';
+
+describe('PaginationFooter', () => {
+  it('renders the summary and pagination', async () => {
+    const { container } = render(<PaginationFooter />);
+    expect(screen.getByText('1–10')).toBeInTheDocument();
+    expect(screen.getByRole('navigation', { name: 'Rows pagination' })).toBeInTheDocument();
+    expect(screen.getByRole('button', { name: 'Page 10' })).toBeInTheDocument();
+    await expectNoAxeViolations(container);
+  });
+
+  it('pages and changes the page size', async () => {
+    const user = userEvent.setup();
+    const onPageChange = vi.fn();
+    const onPageSizeChange = vi.fn();
+    render(<PaginationFooter onPageChange={onPageChange} onPageSizeChange={onPageSizeChange} />);
+    await user.click(screen.getByRole('button', { name: 'Next page' }));
+    expect(onPageChange).toHaveBeenLastCalledWith(2);
+    expect(screen.getByText('11–20')).toBeInTheDocument();
+    await user.click(screen.getByRole('combobox', { name: 'Rows per page' }));
+    await user.click(await screen.findByRole('option', { name: '25' }));
+    expect(onPageSizeChange).toHaveBeenCalledWith(25);
+    expect(screen.getByText('1–25')).toBeInTheDocument();
+    expect(screen.getByRole('button', { name: 'Page 4' })).toBeInTheDocument();
+  });
+});

package/src/tables/PaginationFooter/PaginationFooter.tsx

@@ -0,0 +1,118 @@
+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). */
+  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,
+  labels,
+}: 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>
+          {labels?.rowsPerPage ?? t('table.rowsPerPage')}
+        </span>
+        <SimpleSelect
+          aria-label={labels?.rowsPerPageLabel ?? 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">
+          {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: 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

@@ -0,0 +1,33 @@
+import type { BlockMeta } from '../../meta';
+import type { PaginationFooterLabels } from './PaginationFooter';
+
+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.',
+  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'],
+};