teamshare-bridge 0.2.5 → 0.4.0

package/templates/common/docs/api-contract.md.tpl

@@ -0,0 +1,72 @@
+# API Contract - {{projectName}}
+
+## Response envelope
+
+Every successful response returns:
+
+```json
+{
+  "success": true,
+  "data": { ... }
+}
+```
+
+Paginated responses include a `pagination` field:
+
+```json
+{
+  "success": true,
+  "data": [ ... ],
+  "pagination": {
+    "page": 1,
+    "limit": 20,
+    "total": 100,
+    "totalPages": 5
+  }
+}
+```
+
+## Error envelope
+
+```json
+{
+  "success": false,
+  "error": {
+    "code": "NOT_FOUND",
+    "message": "Resource not found",
+    "details": null
+  }
+}
+```
+
+Common error codes: `BAD_REQUEST`, `UNAUTHORIZED`, `FORBIDDEN`, `NOT_FOUND`, `CONFLICT`, `UNPROCESSABLE_ENTITY`, `TOO_MANY_REQUESTS`, `INTERNAL_ERROR`.
+
+## Authentication
+
+- Bearer token in `Authorization` header
+- JWT issued by `/api/auth/login`
+- Public routes marked with `@Public()` decorator
+
+## RBAC
+
+Route permissions declared via `@Permissions("resource:action")` decorator.
+Roles resolve against the addressed company scope.
+
+| Role | Description |
+|---|---|
+| owner | Full access |
+| admin | Manage members, settings |
+| member | Standard access |
+| viewer | Read-only |
+
+## Pagination
+
+Query params: `page` (default 1), `limit` (default 20, max 100).
+
+## Search
+
+`search` query param performs case-insensitive text matching.
+
+## Sorting
+
+`sort` and `order` query params (e.g. `?sort=createdAt&order=desc`).

package/templates/web/next.config.ts.tpl

@@ -0,0 +1,7 @@
+import type { NextConfig } from "next";
+
+const nextConfig: NextConfig = {
+  reactStrictMode: true,
+};
+
+export default nextConfig;

package/templates/web/package.json.tpl

@@ -0,0 +1,37 @@
+{
+  "name": "{{packageName}}",
+  "version": "0.1.0",
+  "private": true,
+  "description": "{{description}}",
+  "scripts": {
+    "dev": "next dev --turbopack",
+    "build": "next build",
+    "start": "next start",
+    "lint": "next lint"
+  },
+  "dependencies": {
+    "next": "^16.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "next-auth": "^4.24.0",
+    "next-themes": "^0.4.0",
+    "@tanstack/react-query": "^5.60.0",
+    "@tanstack/react-table": "^8.20.0",
+    "react-hook-form": "^7.53.0",
+    "@hookform/resolvers": "^3.9.0",
+    "zod": "^3.23.0",
+    "socket.io-client": "^4.8.0",
+    "iconsax-react": "^0.0.8",
+    "clsx": "^2.1.0",
+    "tailwind-merge": "^2.5.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "typescript": "^5.6.0",
+    "tailwindcss": "^4.0.0",
+    "@tailwindcss/postcss": "^4.0.0",
+    "postcss": "^8.4.0"
+  }
+}

package/templates/web/src/app/globals.css.tpl

@@ -0,0 +1,48 @@
+@import "tailwindcss";
+
+@theme inline {
+  --app-primary-50: #eff6ff;
+  --app-primary-100: #dbeafe;
+  --app-primary-200: #bfdbfe;
+  --app-primary-300: #93c5fd;
+  --app-primary-400: #60a5fa;
+  --app-primary-500: #3b82f6;
+  --app-primary-600: #2563eb;
+  --app-primary-700: #1d4ed8;
+  --app-primary-800: #1e40af;
+  --app-primary-900: #1e3a8a;
+
+  --app-bg-primary: #ffffff;
+  --app-bg-secondary: #f8fafc;
+  --app-bg-tertiary: #f1f5f9;
+  --app-bg-inverse: #0f172a;
+
+  --app-text-primary: #0f172a;
+  --app-text-secondary: #475569;
+  --app-text-tertiary: #94a3b8;
+  --app-text-inverse: #f8fafc;
+
+  --app-border-default: #e2e8f0;
+  --app-border-strong: #cbd5e1;
+
+  --app-radius: 0.5rem;
+
+  --color-background: var(--app-bg-primary);
+  --color-foreground: var(--app-text-primary);
+  --color-muted: var(--app-bg-secondary);
+  --color-muted-foreground: var(--app-text-secondary);
+  --color-border: var(--app-border-default);
+  --color-primary: var(--app-primary-600);
+  --color-primary-foreground: var(--app-text-inverse);
+}
+
+@custom-variant dark (&:is(.dark *));
+
+@layer base {
+  * {
+    @apply border-border;
+  }
+  body {
+    @apply bg-background text-foreground;
+  }
+}

package/templates/web/src/app/layout.tsx.tpl

@@ -0,0 +1,25 @@
+import type { Metadata } from "next";
+import { Inter } from "next/font/google";
+import { Providers } from "@/lib/providers";
+import "./globals.css";
+
+const inter = Inter({ subsets: ["latin"] });
+
+export const metadata: Metadata = {
+  title: "{{projectName}}",
+  description: "{{description}}",
+};
+
+export default function RootLayout({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  return (
+    <html lang="en" suppressHydrationWarning>
+      <body className={inter.className}>
+        <Providers>{children}</Providers>
+      </body>
+    </html>
+  );
+}

package/templates/web/src/components/shared/app-button.tsx.tpl

@@ -0,0 +1,59 @@
+import { Loader2 } from "lucide-react";
+import { type ButtonHTMLAttributes, forwardRef } from "react";
+import { cva, type VariantProps } from "class-variance-authority";
+import { cn } from "@/lib/utils";
+
+const buttonVariants = cva(
+  "inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-md text-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring disabled:pointer-events-none disabled:opacity-50",
+  {
+    variants: {
+      variant: {
+        default: "bg-primary text-primary-foreground hover:bg-primary/90",
+        destructive:
+          "bg-destructive text-destructive-foreground hover:bg-destructive/90",
+        outline:
+          "border border-input bg-background hover:bg-accent hover:text-accent-foreground",
+        secondary:
+          "bg-secondary text-secondary-foreground hover:bg-secondary/80",
+        ghost: "hover:bg-accent hover:text-accent-foreground",
+        link: "text-primary underline-offset-4 hover:underline",
+      },
+      size: {
+        default: "h-10 px-4 py-2",
+        sm: "h-9 rounded-md px-3",
+        lg: "h-11 rounded-md px-8",
+        icon: "h-10 w-10",
+      },
+    },
+    defaultVariants: {
+      variant: "default",
+      size: "default",
+    },
+  }
+);
+
+export interface AppButtonProps
+  extends ButtonHTMLAttributes<HTMLButtonElement>,
+    VariantProps<typeof buttonVariants> {
+  loading?: boolean;
+}
+
+const AppButton = forwardRef<HTMLButtonElement, AppButtonProps>(
+  ({ className, variant, size, loading, disabled, children, ...props }, ref) => {
+    return (
+      <button
+        ref={ref}
+        data-slot="app-button"
+        className={cn(buttonVariants({ variant, size, className }))}
+        disabled={disabled || loading}
+        {...props}
+      >
+        {loading && <Loader2 className="h-4 w-4 animate-spin" variant="Outline" color="currentColor" />}
+        {children}
+      </button>
+    );
+  }
+);
+AppButton.displayName = "AppButton";
+
+export { AppButton, buttonVariants };

package/templates/web/src/components/shared/app-empty-state.tsx.tpl

@@ -0,0 +1,39 @@
+import { type ReactNode } from "react";
+import { cn } from "@/lib/utils";
+
+export interface AppEmptyStateProps {
+  icon?: ReactNode;
+  title: string;
+  description?: string;
+  action?: ReactNode;
+  className?: string;
+}
+
+export function AppEmptyState({
+  icon,
+  title,
+  description,
+  action,
+  className,
+}: AppEmptyStateProps) {
+  return (
+    <div
+      data-slot="app-empty-state"
+      className={cn(
+        "flex flex-col items-center justify-center py-12 text-center",
+        className
+      )}
+    >
+      {icon && (
+        <div className="mb-4 text-tertiary [&_svg]:h-12 [&_svg]:w-12">
+          {icon}
+        </div>
+      )}
+      <h3 className="text-lg font-semibold text-primary">{title}</h3>
+      {description && (
+        <p className="mt-1 max-w-sm text-sm text-secondary">{description}</p>
+      )}
+      {action && <div className="mt-4">{action}</div>}
+    </div>
+  );
+}

package/templates/web/src/components/shared/app-list-toolbar.tsx.tpl

@@ -0,0 +1,63 @@
+"use client";
+
+import { Search } from "lucide-react";
+import { type ReactNode } from "react";
+import { cn } from "@/lib/utils";
+
+export interface AppListToolbarProps {
+  search?: string;
+  onSearchChange?: (value: string) => void;
+  searchPlaceholder?: string;
+  filters?: ReactNode;
+  actions?: ReactNode;
+  resultCount?: number;
+  className?: string;
+}
+
+export function AppListToolbar({
+  search,
+  onSearchChange,
+  searchPlaceholder = "Search...",
+  filters,
+  actions,
+  resultCount,
+  className,
+}: AppListToolbarProps) {
+  return (
+    <div
+      data-slot="app-list-toolbar"
+      className={cn(
+        "flex flex-col gap-3 sm:flex-row sm:items-center sm:justify-between",
+        className
+      )}
+    >
+      <div className="flex flex-1 items-center gap-3">
+        {onSearchChange && (
+          <div className="relative flex-1 max-w-sm">
+            <Search
+              className="absolute left-3 top-1/2 h-4 w-4 -translate-y-1/2 text-tertiary"
+              variant="Outline"
+              color="currentColor"
+            />
+            <input
+              type="text"
+              placeholder={searchPlaceholder}
+              value={search ?? ""}
+              onChange={(e) => onSearchChange(e.target.value)}
+              className="h-10 w-full rounded-md border border-input bg-background pl-9 pr-3 text-sm placeholder:text-tertiary focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+            />
+          </div>
+        )}
+        {filters}
+      </div>
+      <div className="flex items-center gap-3">
+        {resultCount !== undefined && (
+          <span className="text-sm text-secondary">
+            {resultCount} result{resultCount !== 1 ? "s" : ""}
+          </span>
+        )}
+        {actions}
+      </div>
+    </div>
+  );
+}

package/templates/web/src/components/shared/app-skeleton.tsx.tpl

@@ -0,0 +1,14 @@
+import { cn } from "@/lib/utils";
+
+export interface AppSkeletonProps {
+  className?: string;
+}
+
+export function AppSkeleton({ className }: AppSkeletonProps) {
+  return (
+    <div
+      data-slot="app-skeleton"
+      className={cn("animate-pulse rounded-md bg-muted", className)}
+    />
+  );
+}

package/templates/web/src/components/shared/app-table.tsx.tpl

@@ -0,0 +1,128 @@
+"use client";
+
+import {
+  type ColumnDef,
+  type PaginationState,
+  type SortingState,
+  flexRender,
+  getCoreRowModel,
+  getPaginationRowModel,
+  getSortedRowModel,
+  useReactTable,
+} from "@tanstack/react-table";
+import { type ReactNode } from "react";
+import { cn } from "@/lib/utils";
+import { AppSkeleton } from "./app-skeleton";
+import { AppEmptyState } from "./app-empty-state";
+
+export interface AppTableProps<TData> {
+  columns: ColumnDef<TData, unknown>[];
+  data: TData[];
+  loading?: boolean;
+  sorting?: SortingState;
+  onSortingChange?: (sorting: SortingState) => void;
+  pagination?: PaginationState;
+  onPaginationChange?: (pagination: PaginationState) => void;
+  pageCount?: number;
+  emptyIcon?: ReactNode;
+  emptyTitle?: string;
+  emptyDescription?: string;
+  className?: string;
+}
+
+export function AppTable<TData>({
+  columns,
+  data,
+  loading = false,
+  sorting,
+  onSortingChange,
+  pagination,
+  onPaginationChange,
+  pageCount,
+  emptyIcon,
+  emptyTitle = "No results",
+  emptyDescription,
+  className,
+}: AppTableProps<TData>) {
+  const table = useReactTable({
+    data,
+    columns,
+    pageCount,
+    state: {
+      sorting,
+      pagination,
+    },
+    onSortingChange,
+    onPaginationChange,
+    getCoreRowModel: getCoreRowModel(),
+    getSortedRowModel: getSortedRowModel(),
+    getPaginationRowModel: getPaginationRowModel(),
+    manualPagination: true,
+  });
+
+  if (loading) {
+    return (
+      <div data-slot="app-table" className={cn("rounded-md border", className)}>
+        <div className="space-y-2 p-4">
+          {Array.from({ length: 5 }).map((_, i) => (
+            <AppSkeleton key={i} className="h-12 w-full" />
+          ))}
+        </div>
+      </div>
+    );
+  }
+
+  if (data.length === 0) {
+    return (
+      <div data-slot="app-table" className={cn("rounded-md border", className)}>
+        <AppEmptyState
+          icon={emptyIcon}
+          title={emptyTitle}
+          description={emptyDescription}
+        />
+      </div>
+    );
+  }
+
+  return (
+    <div data-slot="app-table" className={cn("rounded-md border", className)}>
+      <div className="overflow-auto">
+        <table className="w-full caption-bottom text-sm">
+          <thead className="border-b bg-muted/50">
+            {table.getHeaderGroups().map((headerGroup) => (
+              <tr key={headerGroup.id}>
+                {headerGroup.headers.map((header) => (
+                  <th
+                    key={header.id}
+                    className="h-10 px-4 text-left font-medium text-secondary"
+                  >
+                    {header.isPlaceholder
+                      ? null
+                      : flexRender(
+                          header.column.columnDef.header,
+                          header.getContext()
+                        )}
+                  </th>
+                ))}
+              </tr>
+            ))}
+          </thead>
+          <tbody>
+            {table.getRowModel().rows.map((row) => (
+              <tr
+                key={row.id}
+                className="border-b transition-colors hover:bg-muted/50"
+              >
+                {row.getVisibleCells().map((cell) => (
+                  <td key={cell.id} className="p-4">
+                    {flexRender(cell.column.columnDef.cell, cell.getContext())}
+                  </td>
+                ))}
+              </tr>
+            ))}
+          </tbody>
+        </table>
+      </div>
+    </div>
+  );
+}

package/templates/web/src/components/shared/index.ts.tpl

@@ -0,0 +1,5 @@
+export { AppButton, buttonVariants, type AppButtonProps } from "./app-button";
+export { AppEmptyState, type AppEmptyStateProps } from "./app-empty-state";
+export { AppSkeleton, type AppSkeletonProps } from "./app-skeleton";
+export { AppTable, type AppTableProps } from "./app-table";
+export { AppListToolbar, type AppListToolbarProps } from "./app-list-toolbar";

package/templates/web/src/hooks/use-list-state.ts.tpl

@@ -0,0 +1,72 @@
+"use client";
+
+import { useRouter, useSearchParams } from "next/navigation";
+import { useCallback, useTransition } from "react";
+
+export interface ListState {
+  search: string;
+  page: number;
+  limit: number;
+  sort?: string;
+  order?: "asc" | "desc";
+  [key: string]: string | number | undefined;
+}
+
+export function useListState(defaults: Partial<ListState> = {}) {
+  const router = useRouter();
+  const searchParams = useSearchParams();
+  const [isPending, startTransition] = useTransition();
+
+  const state: ListState = {
+    search: searchParams.get("search") ?? defaults.search ?? "",
+    page: Number(searchParams.get("page")) || defaults.page || 1,
+    limit: Number(searchParams.get("limit")) || defaults.limit || 20,
+    sort: searchParams.get("sort") ?? defaults.sort,
+    order: (searchParams.get("order") as "asc" | "desc") ?? defaults.order,
+  };
+
+  const setSearchParams = useCallback(
+    (updates: Partial<ListState>) => {
+      const params = new URLSearchParams(searchParams.toString());
+      Object.entries(updates).forEach(([key, value]) => {
+        if (value === undefined || value === null || value === "") {
+          params.delete(key);
+        } else {
+          params.set(key, String(value));
+        }
+      });
+      if (updates.search !== undefined) {
+        params.set("page", "1");
+      }
+      startTransition(() => {
+        router.push(`?${params.toString()}`, { scroll: false });
+      });
+    },
+    [router, searchParams, startTransition]
+  );
+
+  const setSearch = useCallback(
+    (search: string) => setSearchParams({ search }),
+    [setSearchParams]
+  );
+
+  const setPage = useCallback(
+    (page: number) => setSearchParams({ page }),
+    [setSearchParams]
+  );
+
+  const setSort = useCallback(
+    (sort: string, order: "asc" | "desc" = "asc") =>
+      setSearchParams({ sort, order }),
+    [setSearchParams]
+  );
+
+  return {
+    state,
+    setSearch,
+    setPage,
+    setSort,
+    setParams: setSearchParams,
+    isPending,
+  };
+}

package/templates/web/src/hooks/use-url-tab.ts.tpl

@@ -0,0 +1,25 @@
+"use client";
+
+import { useSearchParams } from "next/navigation";
+import { useCallback } from "react";
+
+export function useUrlTab(defaultValue: string = "overview") {
+  const searchParams = useSearchParams();
+  const tab = searchParams.get("tab") ?? defaultValue;
+
+  const setTab = useCallback(
+    (value: string) => {
+      const url = new URL(window.location.href);
+      if (value === defaultValue) {
+        url.searchParams.delete("tab");
+      } else {
+        url.searchParams.set("tab", value);
+      }
+      window.history.replaceState({}, "", url.toString());
+      window.dispatchEvent(new Event("popstate"));
+    },
+    [defaultValue]
+  );
+
+  return { tab, setTab };
+}