create-stitchkit 0.1.0

package/template/packages/frontend/src/features/data-table/components/data-table.tsx

@@ -0,0 +1,303 @@
+'use client';
+
+import { IconChevronLeft, IconChevronRight, IconSearch } from '@tabler/icons-react';
+import {
+  type ColumnDef,
+  type ColumnFiltersState,
+  type ColumnVisibilityState,
+  type OnChangeFn,
+  type PaginationState,
+  type RowSelectionState,
+  type SortingState,
+  useTable,
+} from '@tanstack/react-table';
+import { type ReactNode, useId, useMemo, useState } from 'react';
+import {
+  Button,
+  Input,
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+  Skeleton,
+  Table,
+  TableBody,
+  TableCell,
+  TableHead,
+  TableHeader,
+  TableRow,
+} from '@/components/ui';
+import { dataTableFeatures } from '../table-features';
+
+interface DataTableProps<TData extends object> {
+  columns: ColumnDef<typeof dataTableFeatures, TData, unknown>[];
+  data: TData[];
+  searchKey?: string;
+  searchPlaceholder?: string;
+  actions?: ReactNode;
+  isLoading?: boolean;
+  isFetching?: boolean;
+  pageCount?: number;
+  totalCount?: number;
+  manualPagination?: boolean;
+  manualSorting?: boolean;
+  sorting?: SortingState;
+  pagination?: PaginationState;
+  search?: string;
+  onPaginationChange?: OnChangeFn<PaginationState>;
+  onSortingChange?: OnChangeFn<SortingState>;
+  onSearchChange?: (search: string) => void;
+}
+
+interface PaginationItem {
+  id: string;
+  page?: number;
+}
+
+function paginationItems(currentPage: number, totalPages: number): PaginationItem[] {
+  if (totalPages <= 7) {
+    return Array.from({ length: totalPages }, (_, page) => ({ id: `page-${page}`, page }));
+  }
+  const pages: PaginationItem[] = [{ id: 'page-0', page: 0 }];
+  if (currentPage > 2) pages.push({ id: 'ellipsis-left' });
+  for (
+    let index = Math.max(1, currentPage - 1);
+    index <= Math.min(totalPages - 2, currentPage + 1);
+    index++
+  ) {
+    pages.push({ id: `page-${index}`, page: index });
+  }
+  if (currentPage < totalPages - 3) pages.push({ id: 'ellipsis-right' });
+  pages.push({ id: `page-${totalPages - 1}`, page: totalPages - 1 });
+  return pages;
+}
+
+export function DataTable<TData extends object>({
+  columns,
+  data,
+  searchKey,
+  searchPlaceholder = 'Search…',
+  actions,
+  isLoading = false,
+  isFetching = false,
+  pageCount,
+  totalCount,
+  manualPagination = false,
+  manualSorting = false,
+  sorting: sortingProp,
+  pagination: paginationProp,
+  search: searchProp,
+  onPaginationChange,
+  onSortingChange,
+  onSearchChange,
+}: DataTableProps<TData>) {
+  const [columnFilters, setColumnFilters] = useState<ColumnFiltersState>([]);
+  const [columnVisibility, setColumnVisibility] = useState<ColumnVisibilityState>({});
+  const [rowSelection, setRowSelection] = useState<RowSelectionState>({});
+  const [internalSorting, setInternalSorting] = useState<SortingState>([]);
+  const [internalPagination, setInternalPagination] = useState<PaginationState>({
+    pageIndex: 0,
+    pageSize: 20,
+  });
+  const [internalSearch, setInternalSearch] = useState('');
+
+  const sorting = sortingProp ?? internalSorting;
+  const pagination = paginationProp ?? internalPagination;
+  const skeletonRootId = useId();
+  const skeletonRows = useMemo(
+    () =>
+      Array.from({ length: pagination.pageSize }, (_, position) => ({
+        id: `${skeletonRootId}-row-${position}`,
+        cells: columns.map(
+          (_, cellPosition) => `${skeletonRootId}-${position}-${cellPosition}`,
+        ),
+      })),
+    [columns, pagination.pageSize, skeletonRootId],
+  );
+  const searchValue = searchProp ?? internalSearch;
+  const isServerSide = manualPagination;
+  const table = useTable(
+    {
+      features: dataTableFeatures,
+      data,
+      columns,
+      pageCount,
+      manualPagination,
+      manualSorting,
+      manualFiltering: isServerSide,
+      enableSortingRemoval: false,
+      onSortingChange: onSortingChange ?? setInternalSorting,
+      onPaginationChange: onPaginationChange ?? setInternalPagination,
+      onColumnFiltersChange: setColumnFilters,
+      onColumnVisibilityChange: setColumnVisibility,
+      onRowSelectionChange: setRowSelection,
+      state: { sorting, columnFilters, columnVisibility, rowSelection, pagination },
+    },
+    (state) => state,
+  );
+
+  function handleSearchChange(value: string): void {
+    if (!isServerSide) {
+      setInternalSearch(value);
+      if (searchKey) table.getColumn(searchKey)?.setFilterValue(value);
+    }
+    onSearchChange?.(value);
+  }
+
+  const selectedCount = table.getFilteredSelectedRowModel().rows.length;
+  const displayedCount = isServerSide
+    ? (totalCount ?? data.length)
+    : table.getFilteredRowModel().rows.length;
+  const currentPage = table.state.pagination.pageIndex;
+  const totalPages = table.getPageCount();
+
+  return (
+    <div className='flex h-full flex-col'>
+      {(onSearchChange || searchKey || actions) && (
+        <div className='flex shrink-0 items-center justify-between gap-3 border-b border-border bg-background px-4 py-3'>
+          {onSearchChange || searchKey ? (
+            <div className='relative max-w-xs flex-1'>
+              <IconSearch className='absolute left-2.5 top-1/2 size-4 -translate-y-1/2 text-muted-foreground' />
+              <Input
+                className='h-8 pl-8 text-sm'
+                placeholder={searchPlaceholder}
+                value={searchValue}
+                onChange={(event) => handleSearchChange(event.target.value)}
+              />
+            </div>
+          ) : (
+            <div />
+          )}
+          {actions && <div className='flex items-center gap-2'>{actions}</div>}
+        </div>
+      )}
+
+      <div
+        className={`flex-1 overflow-auto transition-opacity ${isFetching ? 'opacity-50' : ''}`}
+      >
+        <Table>
+          <TableHeader className='sticky top-0 z-10 bg-background'>
+            {table.getHeaderGroups().map((headerGroup) => (
+              <TableRow
+                key={headerGroup.id}
+                className='border-b border-border hover:bg-transparent'
+              >
+                {headerGroup.headers.map((header) => (
+                  <TableHead
+                    key={header.id}
+                    className='h-10 whitespace-nowrap bg-background text-xs font-medium'
+                  >
+                    {header.isPlaceholder ? null : <table.FlexRender header={header} />}
+                  </TableHead>
+                ))}
+              </TableRow>
+            ))}
+          </TableHeader>
+          <TableBody>
+            {isLoading ? (
+              skeletonRows.map((row) => (
+                <TableRow key={row.id}>
+                  {row.cells.map((cellId) => (
+                    <TableCell key={cellId} className='h-12 py-2'>
+                      <Skeleton className='h-4 w-28' />
+                    </TableCell>
+                  ))}
+                </TableRow>
+              ))
+            ) : table.getRowModel().rows.length ? (
+              table.getRowModel().rows.map((row) => (
+                <TableRow key={row.id} data-state={row.getIsSelected() && 'selected'}>
+                  {row.getVisibleCells().map((cell) => (
+                    <TableCell key={cell.id} className='h-12 py-2'>
+                      <table.FlexRender cell={cell} />
+                    </TableCell>
+                  ))}
+                </TableRow>
+              ))
+            ) : (
+              <TableRow>
+                <TableCell
+                  colSpan={columns.length}
+                  className='h-24 text-center text-sm text-muted-foreground'
+                >
+                  No results
+                </TableCell>
+              </TableRow>
+            )}
+          </TableBody>
+        </Table>
+      </div>
+
+      <div className='flex h-11 shrink-0 items-center justify-between border-t border-border bg-background px-4'>
+        <div className='flex items-center gap-4'>
+          <span className='text-xs text-muted-foreground'>
+            {selectedCount > 0
+              ? `${selectedCount} of ${displayedCount} selected`
+              : `${displayedCount} projects`}
+          </span>
+          <Select
+            value={String(table.state.pagination.pageSize)}
+            onValueChange={(value) => table.setPageSize(Number(value))}
+          >
+            <SelectTrigger
+              aria-label='Rows per page'
+              variant='ghost'
+              className='h-7 w-fit rounded px-2 text-xs'
+            >
+              <SelectValue />
+            </SelectTrigger>
+            <SelectContent>
+              {[10, 20, 50, 100].map((size) => (
+                <SelectItem key={size} value={String(size)}>
+                  {size}
+                </SelectItem>
+              ))}
+            </SelectContent>
+          </Select>
+        </div>
+        <div className='flex items-center gap-0.5'>
+          <Button
+            aria-label='Previous page'
+            variant='ghost'
+            size='icon'
+            onClick={() => table.previousPage()}
+            disabled={!table.getCanPreviousPage()}
+          >
+            <IconChevronLeft size={14} />
+          </Button>
+          {paginationItems(currentPage, totalPages).map((item) => {
+            if (item.page === undefined) {
+              return (
+                <span key={item.id} className='px-1 text-xs text-muted-foreground'>
+                  …
+                </span>
+              );
+            }
+            const page = item.page;
+            return (
+              <Button
+                key={item.id}
+                aria-label={`Go to page ${page + 1}`}
+                variant={currentPage === page ? 'default' : 'ghost'}
+                size='icon'
+                onClick={() => table.setPageIndex(page)}
+              >
+                {page + 1}
+              </Button>
+            );
+          })}
+          <Button
+            aria-label='Next page'
+            variant='ghost'
+            size='icon'
+            onClick={() => table.nextPage()}
+            disabled={!table.getCanNextPage()}
+          >
+            <IconChevronRight size={14} />
+          </Button>
+        </div>
+      </div>
+    </div>
+  );
+}

package/template/packages/frontend/src/features/data-table/components/inline-stat.tsx

@@ -0,0 +1,113 @@
+'use client';
+
+import type { ComponentType } from 'react';
+import { cn } from '@/lib/utils';
+
+interface InlineStatProps {
+  label: string;
+  value: string;
+  icon: ComponentType<{ size?: number; className?: string }>;
+  isLoading?: boolean;
+  className?: string;
+}
+
+/**
+ * Compact inline stat card with icon and single value
+ */
+export function InlineStat({
+  label,
+  value,
+  icon: Icon,
+  isLoading,
+  className,
+}: InlineStatProps) {
+  return (
+    <div
+      className={cn(
+        'flex items-center gap-2 lg:gap-3 px-3 lg:px-4 py-2 lg:py-3 bg-muted/40 rounded-lg',
+        className,
+      )}
+    >
+      <div className='flex items-center justify-center w-7 h-7 lg:w-9 lg:h-9 bg-background rounded-md shrink-0'>
+        <Icon className='w-4 h-4 lg:w-[18px] lg:h-[18px] text-muted-foreground' />
+      </div>
+      <div className='flex flex-col min-w-0'>
+        <span className='text-[10px] lg:text-xs text-muted-foreground'>{label}</span>
+        {isLoading ? (
+          <div className='h-5 lg:h-7 w-16 bg-muted animate-pulse rounded' />
+        ) : (
+          <span className='text-base lg:text-lg font-semibold tracking-tight'>{value}</span>
+        )}
+      </div>
+    </div>
+  );
+}
+
+interface DualStatItem {
+  value: string;
+  suffix: string;
+  /** Цвет точки (на мобильных показывается вместо suffix) */
+  dotColor?: string;
+}
+
+interface DualInlineStatProps {
+  label: string;
+  items: DualStatItem[];
+  icon: ComponentType<{ size?: number; className?: string }>;
+  isLoading?: boolean;
+  className?: string;
+}
+
+/**
+ * Compact inline stat card with icon and two values side by side
+ */
+export function DualInlineStat({
+  label,
+  items,
+  icon: Icon,
+  isLoading,
+  className,
+}: DualInlineStatProps) {
+  return (
+    <div
+      className={cn(
+        'flex items-center gap-2 lg:gap-3 px-3 lg:px-4 py-2 lg:py-3 bg-muted/40 rounded-lg',
+        className,
+      )}
+    >
+      <div className='flex items-center justify-center w-7 h-7 lg:w-9 lg:h-9 bg-background rounded-md shrink-0'>
+        <Icon className='w-4 h-4 lg:w-[18px] lg:h-[18px] text-muted-foreground' />
+      </div>
+      <div className='flex flex-col min-w-0'>
+        <span className='text-[10px] lg:text-xs text-muted-foreground'>{label}</span>
+        {isLoading ? (
+          <div className='h-5 lg:h-7 w-24 bg-muted animate-pulse rounded' />
+        ) : (
+          <div className='flex items-baseline gap-2 lg:gap-3 whitespace-nowrap'>
+            {items.map((item, i) => (
+              <span key={item.suffix} className='flex items-center gap-1.5 lg:gap-1.5'>
+                <span className='text-base lg:text-lg font-semibold tracking-tight'>
+                  {item.value}
+                </span>
+                {/* На мобильных — точка, на десктопе — текст */}
+                {item.dotColor ? (
+                  <>
+                    <span className={cn('w-1.5 h-1.5 rounded-full lg:hidden', item.dotColor)} />
+                    <span className='hidden lg:inline text-[10px] lg:text-xs text-muted-foreground'>
+                      {item.suffix}
+                    </span>
+                  </>
+                ) : (
+                  <span className='text-[10px] lg:text-xs text-muted-foreground'>
+                    {item.suffix}
+                  </span>
+                )}
+                {i < items.length - 1 && <span className='w-px h-3 bg-border ml-1 lg:ml-1' />}
+              </span>
+            ))}
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}

package/template/packages/frontend/src/features/data-table/components/sortable-header.tsx

@@ -0,0 +1,33 @@
+'use client';
+
+import { IconChevronDown, IconChevronUp, IconSelector } from '@tabler/icons-react';
+import type { ReactNode } from 'react';
+
+interface SortableHeaderProps {
+  column: {
+    getIsSorted: () => false | 'asc' | 'desc';
+    toggleSorting: (desc: boolean) => void;
+  };
+  children: ReactNode;
+}
+
+export function SortableHeader({ column, children }: SortableHeaderProps) {
+  const sorted = column.getIsSorted();
+
+  const Icon =
+    sorted === 'asc' ? IconChevronUp : sorted === 'desc' ? IconChevronDown : IconSelector;
+
+  return (
+    <button
+      type='button'
+      className='flex items-center gap-1 hover:text-foreground transition-colors cursor-pointer whitespace-nowrap'
+      onClick={() => {
+        const currentSorted = column.getIsSorted();
+        column.toggleSorting(currentSorted === 'asc');
+      }}
+    >
+      {children}
+      <Icon size={14} className={sorted ? undefined : 'opacity-40'} />
+    </button>
+  );
+}

package/template/packages/frontend/src/features/data-table/components/table-error.tsx

@@ -0,0 +1,24 @@
+'use client';
+
+interface TableErrorProps {
+  error: unknown;
+  entity?: string;
+}
+
+/**
+ * Error state component for table pages
+ * Extracts error code from ApiError for display
+ */
+export function TableError({ error, entity = 'data' }: TableErrorProps) {
+  const message = error instanceof Error ? error.message : 'Unknown error';
+
+  return (
+    <div className='flex-1 flex items-center justify-center'>
+      <p className='text-sm text-destructive text-center'>
+        Could not load {entity}
+        <br />
+        <span className='text-xs font-medium'>{message}</span>
+      </p>
+    </div>
+  );
+}

package/template/packages/frontend/src/features/data-table/components/table-filters.tsx

@@ -0,0 +1,82 @@
+'use client';
+
+import { IconX } from '@tabler/icons-react';
+import {
+  Button,
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from '@/components/ui';
+
+export interface FilterOption {
+  value: string;
+  label: string;
+  color?: string;
+}
+
+export interface FilterConfig {
+  key: string;
+  placeholder: string;
+  allLabel: string;
+  options: FilterOption[];
+}
+
+interface TableFiltersProps {
+  filters: FilterConfig[];
+  values: Record<string, string | undefined>;
+  onChange: (key: string, value: string | undefined) => void;
+  onClear?: () => void;
+}
+
+export function TableFilters({ filters, values, onChange, onClear }: TableFiltersProps) {
+  const activeCount = Object.values(values).filter(Boolean).length;
+
+  return (
+    <div className='flex items-center gap-2'>
+      {filters.map((filter) => (
+        <Select
+          key={filter.key}
+          value={values[filter.key] ?? 'all'}
+          onValueChange={(v) => onChange(filter.key, v === 'all' ? undefined : v)}
+        >
+          <SelectTrigger
+            aria-label={`Filter by ${filter.placeholder}`}
+            variant='ghost'
+            className='w-fit h-8 text-xs px-2 gap-1 rounded-lg'
+          >
+            <SelectValue placeholder={filter.placeholder} />
+          </SelectTrigger>
+          <SelectContent>
+            <SelectItem value='all'>{filter.allLabel}</SelectItem>
+            {filter.options.map((opt) => (
+              <SelectItem key={opt.value} value={opt.value}>
+                {opt.color ? (
+                  <span className='flex items-center gap-2'>
+                    <span className={`h-2 w-2 rounded-full ${opt.color}`} />
+                    {opt.label}
+                  </span>
+                ) : (
+                  opt.label
+                )}
+              </SelectItem>
+            ))}
+          </SelectContent>
+        </Select>
+      ))}
+
+      {activeCount > 0 && onClear && (
+        <Button
+          variant='ghost'
+          size='sm'
+          onClick={onClear}
+          className='h-8 px-2 text-xs text-muted-foreground hover:text-foreground'
+        >
+          <IconX size={14} />
+          Clear
+        </Button>
+      )}
+    </div>
+  );
+}

package/template/packages/frontend/src/features/data-table/hooks/useTableState.ts

@@ -0,0 +1,111 @@
+'use client';
+
+import type { OnChangeFn, PaginationState, SortingState } from '@tanstack/react-table';
+import { useCallback, useMemo, useState } from 'react';
+
+export interface UseTableStateOptions {
+  defaultSort?: string;
+  defaultSortOrder?: 'asc' | 'desc';
+  defaultPageSize?: number;
+  defaultSearch?: string;
+}
+
+export interface TableQueryParams {
+  page: number;
+  limit: number;
+  sortBy: string;
+  sortOrder: 'asc' | 'desc';
+  search?: string;
+}
+
+export interface TableProps {
+  sorting: SortingState;
+  pagination: PaginationState;
+  search: string;
+  onSortingChange: OnChangeFn<SortingState>;
+  onPaginationChange: OnChangeFn<PaginationState>;
+  onSearchChange: (search: string) => void;
+  manualPagination: true;
+  manualSorting: true;
+}
+
+export interface UseTableStateReturn {
+  // State values
+  search: string;
+  pagination: PaginationState;
+  sorting: SortingState;
+
+  // Setters
+  setSearch: (value: string) => void;
+  setPagination: OnChangeFn<PaginationState>;
+  setSorting: OnChangeFn<SortingState>;
+
+  // Handler that resets to page 0 on search
+  handleSearchChange: (value: string) => void;
+
+  // Ready-to-use query params for API calls
+  queryParams: TableQueryParams;
+
+  // Props to spread directly to DataTable
+  tableProps: TableProps;
+}
+
+export function useTableState(options: UseTableStateOptions = {}): UseTableStateReturn {
+  const {
+    defaultSort = 'createdAt',
+    defaultSortOrder = 'desc',
+    defaultPageSize = 20,
+    defaultSearch = '',
+  } = options;
+
+  const [search, setSearch] = useState(defaultSearch);
+  const [pagination, setPagination] = useState<PaginationState>({
+    pageIndex: 0,
+    pageSize: defaultPageSize,
+  });
+  const [sorting, setSorting] = useState<SortingState>([
+    { id: defaultSort, desc: defaultSortOrder === 'desc' },
+  ]);
+
+  const handleSearchChange = useCallback((value: string) => {
+    setSearch(value);
+    setPagination((prev) => ({ ...prev, pageIndex: 0 }));
+  }, []);
+
+  const queryParams = useMemo<TableQueryParams>(
+    () => ({
+      page: pagination.pageIndex + 1,
+      limit: pagination.pageSize,
+      sortBy: sorting[0]?.id ?? defaultSort,
+      sortOrder: sorting[0]?.desc ? 'desc' : 'asc',
+      search: search || undefined,
+    }),
+    [pagination, sorting, search, defaultSort],
+  );
+
+  const tableProps = useMemo<TableProps>(
+    () => ({
+      sorting,
+      pagination,
+      search,
+      onSortingChange: setSorting,
+      onPaginationChange: setPagination,
+      onSearchChange: handleSearchChange,
+      manualPagination: true,
+      manualSorting: true,
+    }),
+    [sorting, pagination, search, handleSearchChange],
+  );
+
+  return {
+    search,
+    pagination,
+    sorting,
+    setSearch,
+    setPagination,
+    setSorting,
+    handleSearchChange,
+    queryParams,
+    tableProps,
+  };
+}

package/template/packages/frontend/src/features/data-table/index.ts

@@ -0,0 +1,26 @@
+// Components
+
+export {
+  type ActionItem,
+  createActionsColumn,
+  createDateColumn,
+  createSelectColumn,
+} from './components/column-helpers';
+export { DataTable } from './components/data-table';
+export { DualInlineStat, InlineStat } from './components/inline-stat';
+export { SortableHeader } from './components/sortable-header';
+export { TableError } from './components/table-error';
+export {
+  type FilterConfig,
+  type FilterOption,
+  TableFilters,
+} from './components/table-filters';
+
+// Hooks
+export {
+  type TableProps,
+  type TableQueryParams,
+  type UseTableStateOptions,
+  type UseTableStateReturn,
+  useTableState,
+} from './hooks/useTableState';