create-stitchkit 0.1.0

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

@@ -0,0 +1,26 @@
+import {
+  columnFilteringFeature,
+  columnVisibilityFeature,
+  createFilteredRowModel,
+  createPaginatedRowModel,
+  createSortedRowModel,
+  filterFn_includesString,
+  rowPaginationFeature,
+  rowSelectionFeature,
+  rowSortingFeature,
+  sortFn_alphanumeric,
+  tableFeatures,
+} from '@tanstack/react-table';
+
+export const dataTableFeatures = tableFeatures({
+  columnFilteringFeature,
+  filteredRowModel: createFilteredRowModel(),
+  filterFns: { includesString: filterFn_includesString },
+  rowSortingFeature,
+  sortedRowModel: createSortedRowModel(),
+  sortFns: { alphanumeric: sortFn_alphanumeric },
+  rowPaginationFeature,
+  paginatedRowModel: createPaginatedRowModel(),
+  rowSelectionFeature,
+  columnVisibilityFeature,
+});

package/template/packages/frontend/src/hooks/index.ts

@@ -0,0 +1,3 @@
+export { useInfiniteScroll } from './useInfiniteScroll';
+export { useIsTouchDevice } from './useIsTouchDevice';
+export { useMediaQuery } from './useMediaQuery';

package/template/packages/frontend/src/hooks/useInfiniteScroll.ts

@@ -0,0 +1,67 @@
+import { useCallback, useEffect, useRef } from 'react';
+
+interface UseInfiniteScrollOptions {
+  /** Функция загрузки следующей страницы */
+  fetchNextPage: () => void;
+  /** Есть ли ещё страницы */
+  hasNextPage: boolean;
+  /** Идёт ли загрузка */
+  isFetchingNextPage: boolean;
+  /** Отступ от края для срабатывания (default: 100px) */
+  rootMargin?: string;
+  /** Порог срабатывания (default: 0) */
+  threshold?: number;
+}
+
+/**
+ * Хук для infinite scroll с IntersectionObserver
+ *
+ * @example
+ * const { loadMoreRef } = useInfiniteScroll({
+ *   fetchNextPage,
+ *   hasNextPage,
+ *   isFetchingNextPage,
+ * });
+ *
+ * return (
+ *   <div>
+ *     {items.map(...)}
+ *     <div ref={loadMoreRef} />
+ *   </div>
+ * );
+ */
+export function useInfiniteScroll({
+  fetchNextPage,
+  hasNextPage,
+  isFetchingNextPage,
+  rootMargin = '100px',
+  threshold = 0,
+}: UseInfiniteScrollOptions) {
+  const loadMoreRef = useRef<HTMLDivElement>(null);
+
+  const handleObserver = useCallback(
+    (entries: IntersectionObserverEntry[]) => {
+      const [entry] = entries;
+      if (entry?.isIntersecting && hasNextPage && !isFetchingNextPage) {
+        fetchNextPage();
+      }
+    },
+    [hasNextPage, isFetchingNextPage, fetchNextPage],
+  );
+
+  useEffect(() => {
+    const element = loadMoreRef.current;
+    if (!element) return;
+
+    const observer = new IntersectionObserver(handleObserver, {
+      root: null,
+      rootMargin,
+      threshold,
+    });
+
+    observer.observe(element);
+    return () => observer.disconnect();
+  }, [handleObserver, rootMargin, threshold]);
+
+  return { loadMoreRef };
+}

package/template/packages/frontend/src/hooks/useIsTouchDevice.ts

@@ -0,0 +1,25 @@
+'use client';
+
+import { useEffect, useState } from 'react';
+
+/**
+ * Определяет touch устройство
+ *
+ * Проверяет:
+ * - ontouchstart в window
+ * - navigator.maxTouchPoints
+ * - media query (pointer: coarse)
+ */
+export function useIsTouchDevice() {
+  const [isTouch, setIsTouch] = useState(false);
+
+  useEffect(() => {
+    setIsTouch(
+      'ontouchstart' in window ||
+        navigator.maxTouchPoints > 0 ||
+        window.matchMedia('(pointer: coarse)').matches,
+    );
+  }, []);
+
+  return isTouch;
+}

package/template/packages/frontend/src/hooks/useMediaQuery.ts

@@ -0,0 +1,30 @@
+'use client';
+
+import { useEffect, useState } from 'react';
+
+/**
+ * Хук для отслеживания media query
+ *
+ * @param query - CSS media query строка (например '(min-width: 768px)')
+ * @returns true если query совпадает, false если нет или SSR
+ */
+export function useMediaQuery(query: string): boolean {
+  const [matches, setMatches] = useState(false);
+  const [mounted, setMounted] = useState(false);
+
+  useEffect(() => {
+    setMounted(true);
+    const mediaQuery = window.matchMedia(query);
+    setMatches(mediaQuery.matches);
+
+    const handler = (event: MediaQueryListEvent) => {
+      setMatches(event.matches);
+    };
+
+    mediaQuery.addEventListener('change', handler);
+    return () => mediaQuery.removeEventListener('change', handler);
+  }, [query]);
+
+  // Return false during SSR to avoid hydration mismatch
+  return mounted ? matches : false;
+}

package/template/packages/frontend/src/i18n/locales.ts

@@ -0,0 +1,6 @@
+import { z } from 'zod';
+
+export const LocaleSchema = z.enum(['en', 'ru']);
+export type AppLocale = z.infer<typeof LocaleSchema>;
+export const locales = LocaleSchema.options;
+export const defaultLocale: AppLocale = 'en';

package/template/packages/frontend/src/i18n/navigation.ts

@@ -0,0 +1,4 @@
+import { createNavigation } from 'next-intl/navigation';
+import { routing } from './routing';
+
+export const { Link, redirect, usePathname, useRouter } = createNavigation(routing);

package/template/packages/frontend/src/i18n/request.ts

@@ -0,0 +1,9 @@
+import { getRequestConfig } from 'next-intl/server';
+import { defaultLocale, LocaleSchema } from './locales';
+
+export default getRequestConfig(async ({ requestLocale }) => {
+  const requested = await requestLocale;
+  const parsedLocale = LocaleSchema.safeParse(requested);
+  const locale = parsedLocale.success ? parsedLocale.data : defaultLocale;
+  return { locale, messages: (await import(`../../messages/${locale}.json`)).default };
+});

package/template/packages/frontend/src/i18n/routing.ts

@@ -0,0 +1,8 @@
+import { defineRouting } from 'next-intl/routing';
+import { defaultLocale, locales } from './locales';
+
+export const routing = defineRouting({
+  locales,
+  defaultLocale,
+  localePrefix: 'always',
+});

package/template/packages/frontend/src/lib/api/client.ts

@@ -0,0 +1,20 @@
+import { repositoryContract } from '@app/shared';
+import { createClient, createHttpClient, createUrlBuilder } from 'stitchkit';
+import { env } from '@/env';
+
+function apiOrigin(): string {
+  return typeof window === 'undefined' ? env.INTERNAL_API_URL : env.NEXT_PUBLIC_API_URL;
+}
+
+export function createRepositoryApi(baseUrl: string) {
+  const http = createHttpClient({ baseUrl: `${baseUrl}/api`, credentials: 'omit' });
+  return createClient(repositoryContract, http);
+}
+
+const http = createHttpClient({ baseUrl: `${apiOrigin()}/api`, credentials: 'omit' });
+export const repositoryApi = createRepositoryApi(apiOrigin());
+export const repositoryUrls = createUrlBuilder(repositoryContract, http);
+
+export function createServerRepositoryApi() {
+  return createRepositoryApi(env.INTERNAL_API_URL);
+}

package/template/packages/frontend/src/lib/api/queries.ts

@@ -0,0 +1,11 @@
+import { createMutation, createQuery } from 'react-query-kit';
+import { repositoryApi } from './client';
+
+export const useRepository = createQuery({
+  queryKey: ['repository'],
+  fetcher: () => repositoryApi.read(),
+});
+
+export const useRefreshRepository = createMutation({
+  mutationFn: () => repositoryApi.refresh(),
+});

package/template/packages/frontend/src/lib/query-client.ts

@@ -0,0 +1,20 @@
+import { isServer, QueryClient } from '@tanstack/react-query';
+import { cache } from 'react';
+
+function createQueryClient(): QueryClient {
+  return new QueryClient({
+    defaultOptions: {
+      queries: { staleTime: 30_000, retry: 1 },
+      dehydrate: { shouldDehydrateQuery: (query) => query.state.status === 'pending' },
+    },
+  });
+}
+
+const getServerQueryClient = cache(createQueryClient);
+let browserQueryClient: QueryClient | undefined;
+
+export function getQueryClient(): QueryClient {
+  if (isServer) return getServerQueryClient();
+  if (!browserQueryClient) browserQueryClient = createQueryClient();
+  return browserQueryClient;
+}

package/template/packages/frontend/src/lib/realtime/repository.ts

@@ -0,0 +1,21 @@
+import type { ClientToServerEvents, ServerToClientEvents } from '@app/shared';
+import { createSocketIOClient } from 'stitchkit';
+import { createCacheBridge } from 'stitchkit/react';
+import { env } from '@/env';
+import { useRepository } from '@/lib/api/queries';
+import { getQueryClient } from '@/lib/query-client';
+
+export const repositorySocket = createSocketIOClient<
+  ServerToClientEvents,
+  ClientToServerEvents
+>({ url: env.NEXT_PUBLIC_API_URL });
+
+export const repositoryBridge = createCacheBridge({
+  socket: repositorySocket,
+  queryClient: getQueryClient,
+  handlers: {
+    'repository:refreshed': (snapshot, { queryClient }) => {
+      queryClient.setQueryData(useRepository.getKey(), snapshot);
+    },
+  },
+});

package/template/packages/frontend/src/lib/seo/metadata.ts

@@ -0,0 +1,50 @@
+import type { Metadata } from 'next';
+import { env } from '@/env';
+import type { AppLocale } from '@/i18n/locales';
+import { locales } from '@/i18n/locales';
+import type { SeoPageId } from './pages';
+import { getSeoPage, localizedPagePath, SITE_NAME } from './pages';
+
+export const siteOrigin = new URL(env.NEXT_PUBLIC_WEB_URL).origin;
+
+export function absoluteSiteUrl(path: string): string {
+  return new URL(path, siteOrigin).toString();
+}
+
+export function createPageMetadata(pageId: SeoPageId, locale: AppLocale): Metadata {
+  const page = getSeoPage(pageId, locale);
+  const title = pageId === 'home' ? SITE_NAME : `${page.title} · ${SITE_NAME}`;
+  const canonicalPath = localizedPagePath(pageId, locale);
+  const image = absoluteSiteUrl(`/api/og/${locale}/${pageId}`);
+  const languageAlternates = Object.fromEntries(
+    locales.map((availableLocale) => [
+      availableLocale,
+      absoluteSiteUrl(localizedPagePath(pageId, availableLocale)),
+    ]),
+  );
+
+  return {
+    title,
+    description: page.description,
+    alternates: {
+      canonical: absoluteSiteUrl(canonicalPath),
+      languages: languageAlternates,
+    },
+    openGraph: {
+      type: 'website',
+      siteName: SITE_NAME,
+      title,
+      description: page.description,
+      url: absoluteSiteUrl(canonicalPath),
+      locale: locale === 'ru' ? 'ru_RU' : 'en_US',
+      alternateLocale: locale === 'ru' ? ['en_US'] : ['ru_RU'],
+      images: [{ url: image, width: 1200, height: 630, alt: `${title} — ${page.eyebrow}` }],
+    },
+    twitter: {
+      card: 'summary_large_image',
+      title,
+      description: page.description,
+      images: [{ url: image, alt: `${title} — ${page.eyebrow}` }],
+    },
+  };
+}

package/template/packages/frontend/src/lib/seo/pages.test.ts

@@ -0,0 +1,25 @@
+import { describe, expect, test } from 'bun:test';
+import { LocaleSchema } from '@/i18n/locales';
+import { getSeoPage, localizedPagePath, publicPageIds } from './pages';
+
+describe('SEO page registry', () => {
+  test('defines complete localized copy for every public page', () => {
+    for (const locale of LocaleSchema.options) {
+      const titles = new Set<string>();
+      const descriptions = new Set<string>();
+
+      for (const pageId of publicPageIds) {
+        const page = getSeoPage(pageId, locale);
+        expect(page.title.length).toBeGreaterThan(10);
+        expect(page.description.length).toBeGreaterThan(60);
+        expect(page.eyebrow.length).toBeGreaterThan(0);
+        expect(localizedPagePath(pageId, locale)).toStartWith(`/${locale}`);
+        titles.add(page.title);
+        descriptions.add(page.description);
+      }
+
+      expect(titles.size).toBe(publicPageIds.length);
+      expect(descriptions.size).toBe(publicPageIds.length);
+    }
+  });
+});

package/template/packages/frontend/src/lib/seo/pages.ts

@@ -0,0 +1,107 @@
+import { z } from 'zod';
+import type { AppLocale } from '@/i18n/locales';
+
+export const SITE_NAME = 'Stitchkit Starter';
+export const StoryIdSchema = z.enum(['components', 'themes', 'blocks']);
+export type StoryId = z.infer<typeof StoryIdSchema>;
+
+export const SeoPageIdSchema = z.enum(['home', ...StoryIdSchema.options]);
+export type SeoPageId = z.infer<typeof SeoPageIdSchema>;
+
+interface SeoCopy {
+  title: string;
+  description: string;
+  eyebrow: string;
+}
+
+interface SeoPageDefinition {
+  path: string;
+  copy: Record<AppLocale, SeoCopy>;
+}
+
+const seoPages: Record<SeoPageId, SeoPageDefinition> = {
+  home: {
+    path: '',
+    copy: {
+      en: {
+        title: 'Production-ready full-stack starter',
+        description:
+          'Build typed production applications with Stitchkit, Next.js, Bun, PostgreSQL, realtime cache updates and contract-driven tools.',
+        eyebrow: 'One contract. Every surface.',
+      },
+      ru: {
+        title: 'Production-ready full-stack стартер',
+        description:
+          'Создавайте типизированные production-приложения на Stitchkit, Next.js, Bun и PostgreSQL с realtime-кешем и contract-driven tools.',
+        eyebrow: 'Один контракт. Все поверхности.',
+      },
+    },
+  },
+  components: {
+    path: '/ui/components',
+    copy: {
+      en: {
+        title: 'UI components',
+        description:
+          'Explore accessible actions, forms, feedback, overlays, data displays and motion components included in the Stitchkit starter.',
+        eyebrow: 'UI system',
+      },
+      ru: {
+        title: 'UI-компоненты',
+        description:
+          'Изучите доступные действия, формы, обратную связь, оверлеи, представление данных и анимации в Stitchkit Starter.',
+        eyebrow: 'UI-система',
+      },
+    },
+  },
+  themes: {
+    path: '/ui/themes',
+    copy: {
+      en: {
+        title: 'Theme system',
+        description:
+          'Global, system, server-readable, forced and scoped themes with configurable View Transition effects.',
+        eyebrow: 'UI system',
+      },
+      ru: {
+        title: 'Система тем',
+        description:
+          'Глобальные, системные, server-readable, forced и scoped темы с настраиваемыми View Transition эффектами.',
+        eyebrow: 'UI-система',
+      },
+    },
+  },
+  blocks: {
+    path: '/ui/blocks',
+    copy: {
+      en: {
+        title: 'Reusable UI blocks',
+        description:
+          'Production-shaped landing, application shell, account and checkout blocks composed from the starter components.',
+        eyebrow: 'UI system',
+      },
+      ru: {
+        title: 'Готовые UI-блоки',
+        description:
+          'Production-shaped лендинг, каркас приложения, аккаунт и checkout-блоки, собранные из компонентов стартера.',
+        eyebrow: 'UI-система',
+      },
+    },
+  },
+};
+
+export const publicPageIds = SeoPageIdSchema.options;
+export const storyIds = StoryIdSchema.options;
+
+export function isStoryId(value: string): value is StoryId {
+  return StoryIdSchema.safeParse(value).success;
+}
+
+export function getSeoPage(pageId: SeoPageId, locale: AppLocale) {
+  const page = seoPages[pageId];
+  return { ...page, ...page.copy[locale] };
+}
+
+export function localizedPagePath(pageId: SeoPageId, locale: AppLocale): string {
+  return `/${locale}${seoPages[pageId].path}`;
+}

package/template/packages/frontend/src/lib/utils/cn.ts

@@ -0,0 +1,6 @@
+import { type ClassValue, clsx } from 'clsx';
+import { twMerge } from 'tailwind-merge';
+
+export function cn(...inputs: ClassValue[]): string {
+  return twMerge(clsx(inputs));
+}

package/template/packages/frontend/src/lib/utils/format.ts

@@ -0,0 +1,25 @@
+import { formatDistanceToNow } from 'date-fns';
+import { enUS, ru } from 'date-fns/locale';
+
+export type Currency = 'EUR' | 'RUB' | 'USD';
+
+const currencySymbols: Record<Currency, string> = { EUR: '€', RUB: '₽', USD: '$' };
+
+export function formatPrice(amount: number, currency: Currency): string {
+  return `${currencySymbols[currency]}${Math.round(amount).toLocaleString()}`;
+}
+
+export function formatDateTime(value: Date | string): { date: string; time: string } {
+  const date = typeof value === 'string' ? new Date(value) : value;
+  return {
+    date: new Intl.DateTimeFormat('en', { dateStyle: 'medium' }).format(date),
+    time: new Intl.DateTimeFormat('en', { timeStyle: 'short' }).format(date),
+  };
+}
+
+export function formatRelativeTime(date: string, locale: string): string {
+  return formatDistanceToNow(new Date(date), {
+    addSuffix: true,
+    locale: locale === 'ru' ? ru : enUS,
+  });
+}

package/template/packages/frontend/src/lib/utils/index.ts

@@ -0,0 +1,2 @@
+export { cn } from './cn';
+export * from './format';

package/template/packages/frontend/src/providers/index.tsx

@@ -0,0 +1,18 @@
+'use client';
+
+import { TooltipProvider } from '@radix-ui/react-tooltip';
+import type { ReactNode } from 'react';
+import { Toaster } from '@/components/ui/toaster';
+import { ReactQueryProvider } from './react-query';
+import { RealtimeProvider } from './realtime';
+
+export function Providers({ children }: { children: ReactNode }) {
+  return (
+    <ReactQueryProvider>
+      <RealtimeProvider>
+        <TooltipProvider delayDuration={250}>{children}</TooltipProvider>
+      </RealtimeProvider>
+      <Toaster />
+    </ReactQueryProvider>
+  );
+}

package/template/packages/frontend/src/providers/react-query.tsx

@@ -0,0 +1,9 @@
+'use client';
+
+import { QueryClientProvider } from '@tanstack/react-query';
+import type { ReactNode } from 'react';
+import { getQueryClient } from '@/lib/query-client';
+
+export function ReactQueryProvider({ children }: { children: ReactNode }) {
+  return <QueryClientProvider client={getQueryClient()}>{children}</QueryClientProvider>;
+}

package/template/packages/frontend/src/providers/realtime.tsx

@@ -0,0 +1,16 @@
+'use client';
+
+import { type ReactNode, useEffect } from 'react';
+import { repositoryBridge, repositorySocket } from '@/lib/realtime/repository';
+
+export function RealtimeProvider({ children }: { children: ReactNode }) {
+  useEffect(() => {
+    repositorySocket.connect();
+    repositoryBridge.connect();
+    return () => {
+      repositoryBridge.disconnect();
+      repositorySocket.disconnect();
+    };
+  }, []);
+  return children;
+}

package/template/packages/frontend/src/proxy.ts

@@ -0,0 +1,6 @@
+import createMiddleware from 'next-intl/middleware';
+import { routing } from './i18n/routing';
+
+export default createMiddleware(routing);
+
+export const config = { matcher: ['/', '/(en|ru)/:path*'] };

package/template/packages/frontend/src/theme/config.ts

@@ -0,0 +1,20 @@
+import type { ThemeProviderProps } from '@wrksz/themes/next';
+
+export type AppTheme = 'light' | 'dark';
+
+export const appThemes: readonly [AppTheme, AppTheme] = ['light', 'dark'];
+export const themeStorageKey = 'stitchkit-starter-theme';
+
+export const themeProviderConfig = {
+  themes: appThemes,
+  attribute: 'class',
+  defaultTheme: 'system',
+  enableSystem: true,
+  enableColorScheme: true,
+  storage: 'hybrid',
+  storageKey: themeStorageKey,
+  themeColor: {
+    light: '#ffffff',
+    dark: '#242428',
+  },
+} satisfies Omit<ThemeProviderProps<AppTheme>, 'children'>;

package/template/packages/frontend/src/theme/transition.ts

@@ -0,0 +1,54 @@
+export type ThemeTransitionStyle = 'crossfade' | 'radial';
+
+export interface ThemeTransitionConfig {
+  style: ThemeTransitionStyle;
+  durationMs: number;
+  easing: string;
+}
+
+export interface ThemeTransitionOrigin {
+  x: number;
+  y: number;
+}
+
+export const defaultThemeTransition = {
+  style: 'crossfade',
+  durationMs: 250,
+  easing: 'ease-out',
+} satisfies ThemeTransitionConfig;
+
+export function runThemeTransition(
+  updateTheme: () => void,
+  config: ThemeTransitionConfig = defaultThemeTransition,
+  origin?: ThemeTransitionOrigin,
+) {
+  const reducedMotion = window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+  if (typeof document.startViewTransition !== 'function' || reducedMotion) {
+    updateTheme();
+    return;
+  }
+
+  const root = document.documentElement;
+  const transitionOrigin = origin ?? {
+    x: window.innerWidth / 2,
+    y: window.innerHeight / 2,
+  };
+  root.classList.add('theme-transitioning');
+  root.dataset.themeTransition = config.style;
+  root.style.setProperty('--theme-transition-duration', `${config.durationMs}ms`);
+  root.style.setProperty('--theme-transition-easing', config.easing);
+  root.style.setProperty('--theme-transition-x', `${transitionOrigin.x}px`);
+  root.style.setProperty('--theme-transition-y', `${transitionOrigin.y}px`);
+
+  const cleanup = () => {
+    root.classList.remove('theme-transitioning');
+    delete root.dataset.themeTransition;
+    root.style.removeProperty('--theme-transition-duration');
+    root.style.removeProperty('--theme-transition-easing');
+    root.style.removeProperty('--theme-transition-x');
+    root.style.removeProperty('--theme-transition-y');
+  };
+
+  const transition = document.startViewTransition(updateTheme);
+  transition.finished.then(cleanup, cleanup);
+}

package/template/packages/frontend/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "lib": ["DOM", "DOM.Iterable", "ESNext"],
+    "jsx": "react-jsx",
+    "incremental": true,
+    "types": ["bun"],
+    "plugins": [{ "name": "next" }],
+    "paths": { "@/*": ["./src/*"] }
+  },
+  "include": ["next-env.d.ts", "src/**/*.ts", "src/**/*.tsx", ".next/types/**/*.ts"],
+  "exclude": ["node_modules"]
+}

package/template/packages/shared/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@app/shared",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "check": "bun x tsc --noEmit",
+    "test": "bun test --pass-with-no-tests"
+  },
+  "dependencies": {
+    "@app/db": "workspace:*",
+    "stitchkit": "catalog:",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.14",
+    "typescript": "^7.0.2"
+  }
+}