feat(ui): company list page with columns, filters, and sidebar entry

src/app/(dashboard)/[portSlug]/companies/page.tsx

@@ -0,0 +1,5 @@
+import { CompanyList } from '@/components/companies/company-list';
+
+export default function CompaniesPage() {
+  return <CompanyList />;
+}

src/components/companies/company-columns.tsx

@@ -0,0 +1,148 @@
+'use client';
+
+import Link from 'next/link';
+import { MoreHorizontal, Pencil, Archive, Eye } from 'lucide-react';
+import type { ColumnDef } from '@tanstack/react-table';
+
+import { Button } from '@/components/ui/button';
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuTrigger,
+} from '@/components/ui/dropdown-menu';
+
+// TODO: add member/yacht counts once the list endpoint returns them via a join.
+export interface CompanyRow {
+  id: string;
+  name: string;
+  legalName: string | null;
+  taxId: string | null;
+  registrationNumber: string | null;
+  incorporationCountry: string | null;
+  incorporationDate: string | null;
+  status: string;
+  billingEmail: string | null;
+  notes: string | null;
+  archivedAt: string | null;
+  createdAt: string;
+  updatedAt: string;
+}
+
+const STATUS_COLORS: Record<string, string> = {
+  active: 'bg-green-100 text-green-800 border-green-300',
+  dissolved: 'bg-red-100 text-red-800 border-red-300',
+};
+
+const STATUS_LABELS: Record<string, string> = {
+  active: 'Active',
+  dissolved: 'Dissolved',
+};
+
+interface GetCompanyColumnsOptions {
+  portSlug: string;
+  onEdit: (company: CompanyRow) => void;
+  onArchive: (company: CompanyRow) => void;
+}
+
+export function getCompanyColumns({
+  portSlug,
+  onEdit,
+  onArchive,
+}: GetCompanyColumnsOptions): ColumnDef<CompanyRow, unknown>[] {
+  return [
+    {
+      id: 'name',
+      accessorKey: 'name',
+      header: 'Name',
+      cell: ({ row }) => (
+        <Link
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          href={`/${portSlug}/companies/${row.original.id}` as any}
+          className="font-medium text-primary hover:underline"
+          onClick={(e) => e.stopPropagation()}
+        >
+          {row.original.name}
+        </Link>
+      ),
+    },
+    {
+      id: 'legalName',
+      accessorKey: 'legalName',
+      header: 'Legal Name',
+      enableSorting: false,
+      cell: ({ getValue }) => {
+        const value = getValue() as string | null;
+        if (!value) return <span className="text-muted-foreground">—</span>;
+        return <span className="text-sm">{value}</span>;
+      },
+    },
+    {
+      id: 'taxId',
+      accessorKey: 'taxId',
+      header: 'Tax ID',
+      enableSorting: false,
+      cell: ({ getValue }) => {
+        const value = getValue() as string | null;
+        if (!value) return <span className="text-muted-foreground">—</span>;
+        return <span className="text-sm">{value}</span>;
+      },
+    },
+    {
+      id: 'status',
+      accessorKey: 'status',
+      header: 'Status',
+      cell: ({ row }) => {
+        const status = row.original.status;
+        const label = STATUS_LABELS[status] ?? status;
+        const color = STATUS_COLORS[status] ?? 'bg-muted text-muted-foreground border-muted';
+        return (
+          <span
+            className={`inline-flex items-center rounded-full border px-2 py-0.5 text-xs font-medium ${color}`}
+          >
+            {label}
+          </span>
+        );
+      },
+    },
+    {
+      id: 'actions',
+      header: '',
+      enableSorting: false,
+      size: 48,
+      cell: ({ row }) => (
+        <DropdownMenu>
+          <DropdownMenuTrigger asChild>
+            <Button
+              variant="ghost"
+              size="icon"
+              className="h-7 w-7"
+              onClick={(e) => e.stopPropagation()}
+            >
+              <MoreHorizontal className="h-4 w-4" />
+            </Button>
+          </DropdownMenuTrigger>
+          <DropdownMenuContent align="end">
+            <DropdownMenuItem asChild>
+              <Link
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                href={`/${portSlug}/companies/${row.original.id}` as any}
+              >
+                <Eye className="mr-2 h-3.5 w-3.5" />
+                View
+              </Link>
+            </DropdownMenuItem>
+            <DropdownMenuItem onClick={() => onEdit(row.original)}>
+              <Pencil className="mr-2 h-3.5 w-3.5" />
+              Edit
+            </DropdownMenuItem>
+            <DropdownMenuItem className="text-destructive" onClick={() => onArchive(row.original)}>
+              <Archive className="mr-2 h-3.5 w-3.5" />
+              Archive
+            </DropdownMenuItem>
+          </DropdownMenuContent>
+        </DropdownMenu>
+      ),
+    },
+  ];
+}

src/components/companies/company-filters.tsx

@@ -0,0 +1,24 @@
+import type { FilterDefinition } from '@/components/shared/filter-bar';
+
+export const companyFilterDefinitions: FilterDefinition[] = [
+  {
+    key: 'search',
+    label: 'Search',
+    type: 'text',
+    placeholder: 'Search by name, legal name, tax ID...',
+  },
+  {
+    key: 'status',
+    label: 'Status',
+    type: 'select',
+    options: [
+      { label: 'Active', value: 'active' },
+      { label: 'Dissolved', value: 'dissolved' },
+    ],
+  },
+  {
+    key: 'includeArchived',
+    label: 'Include Archived',
+    type: 'boolean',
+  },
+];

src/components/companies/company-list.tsx

@@ -0,0 +1,167 @@
+'use client';
+
+import { useState } from 'react';
+import { useParams } from 'next/navigation';
+import { Plus } from 'lucide-react';
+import { useMutation, useQueryClient } from '@tanstack/react-query';
+
+import { Button } from '@/components/ui/button';
+import { DataTable } from '@/components/shared/data-table';
+import { FilterBar } from '@/components/shared/filter-bar';
+import { SavedViewsDropdown } from '@/components/shared/saved-views-dropdown';
+import { PageHeader } from '@/components/shared/page-header';
+import { EmptyState } from '@/components/shared/empty-state';
+import { TableSkeleton } from '@/components/shared/loading-skeleton';
+import { ArchiveConfirmDialog } from '@/components/shared/archive-confirm-dialog';
+import { PermissionGate } from '@/components/shared/permission-gate';
+import { CompanyForm } from '@/components/companies/company-form';
+import { companyFilterDefinitions } from '@/components/companies/company-filters';
+import { getCompanyColumns, type CompanyRow } from '@/components/companies/company-columns';
+import { usePaginatedQuery } from '@/hooks/use-paginated-query';
+import { useRealtimeInvalidation } from '@/hooks/use-realtime-invalidation';
+import { apiFetch } from '@/lib/api/client';
+
+export function CompanyList() {
+  const params = useParams<{ portSlug: string }>();
+  const portSlug = params?.portSlug ?? '';
+  const queryClient = useQueryClient();
+
+  const [createOpen, setCreateOpen] = useState(false);
+  const [editCompany, setEditCompany] = useState<CompanyRow | null>(null);
+  const [archiveCompany, setArchiveCompany] = useState<CompanyRow | null>(null);
+
+  const {
+    data,
+    pagination,
+    isLoading,
+    isFetching,
+    sort,
+    setSort,
+    setPage,
+    setPageSize,
+    filters,
+    setFilter,
+    clearFilters,
+  } = usePaginatedQuery<CompanyRow>({
+    queryKey: ['companies'],
+    endpoint: '/api/v1/companies',
+    filterDefinitions: companyFilterDefinitions,
+  });
+
+  useRealtimeInvalidation({
+    'company:created': [['companies']],
+    'company:updated': [['companies']],
+    'company:archived': [['companies']],
+  });
+
+  const archiveMutation = useMutation({
+    mutationFn: (id: string) => apiFetch(`/api/v1/companies/${id}`, { method: 'DELETE' }),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ['companies'] });
+      setArchiveCompany(null);
+    },
+  });
+
+  const columns = getCompanyColumns({
+    portSlug,
+    onEdit: (company) => setEditCompany(company),
+    onArchive: (company) => setArchiveCompany(company),
+  });
+
+  return (
+    <div className="space-y-4">
+      <PageHeader
+        title="Companies"
+        description="Manage company records"
+        actions={
+          <PermissionGate resource="companies" action="create">
+            <Button size="sm" onClick={() => setCreateOpen(true)}>
+              <Plus className="mr-1.5 h-4 w-4" />
+              New Company
+            </Button>
+          </PermissionGate>
+        }
+      />
+
+      <div className="flex items-center gap-2">
+        <FilterBar
+          filters={companyFilterDefinitions}
+          values={filters}
+          onChange={setFilter}
+          onClear={clearFilters}
+        />
+        <SavedViewsDropdown
+          entityType="companies"
+          currentFilters={filters}
+          currentSort={sort}
+          onApplyView={(savedFilters, _savedSort) => {
+            clearFilters();
+            Object.entries(savedFilters).forEach(([key, val]) => setFilter(key, val));
+          }}
+        />
+      </div>
+
+      {isLoading ? (
+        <TableSkeleton />
+      ) : !data.length ? (
+        <EmptyState
+          title="No companies yet"
+          description="Create your first company to get started."
+          action={{ label: 'New Company', onClick: () => setCreateOpen(true) }}
+        />
+      ) : (
+        <DataTable
+          columns={columns}
+          data={data}
+          pagination={pagination}
+          onPaginationChange={(p, ps) => {
+            setPage(p);
+            setPageSize(ps);
+          }}
+          sort={sort}
+          onSortChange={setSort}
+          isLoading={isFetching && !isLoading}
+          getRowId={(row) => row.id}
+          emptyState={
+            <EmptyState
+              title="No companies yet"
+              description="Create your first company to get started."
+              action={{ label: 'New Company', onClick: () => setCreateOpen(true) }}
+            />
+          }
+        />
+      )}
+
+      <CompanyForm open={createOpen} onOpenChange={setCreateOpen} />
+
+      {editCompany && (
+        <CompanyForm
+          open={!!editCompany}
+          onOpenChange={(open) => !open && setEditCompany(null)}
+          company={{
+            id: editCompany.id,
+            name: editCompany.name,
+            legalName: editCompany.legalName,
+            taxId: editCompany.taxId,
+            registrationNumber: editCompany.registrationNumber,
+            incorporationCountry: editCompany.incorporationCountry,
+            incorporationDate: editCompany.incorporationDate,
+            status: editCompany.status,
+            billingEmail: editCompany.billingEmail,
+            notes: editCompany.notes,
+          }}
+        />
+      )}
+
+      <ArchiveConfirmDialog
+        open={!!archiveCompany}
+        onOpenChange={(open) => !open && setArchiveCompany(null)}
+        entityName={archiveCompany?.name ?? ''}
+        entityType="Company"
+        isArchived={false}
+        onConfirm={() => archiveCompany && archiveMutation.mutate(archiveCompany.id)}
+        isLoading={archiveMutation.isPending}
+      />
+    </div>
+  );
+}

src/components/layout/sidebar.tsx

@@ -9,6 +9,7 @@ import {
   Bookmark,
   Anchor,
   Ship,
+  Building2,
   Receipt,
   FileText,
   FolderOpen,
@@ -62,6 +63,7 @@ function buildNavSections(portSlug: string | undefined): NavSection[] {
         { href: `${base}/dashboard`, label: 'Dashboard', icon: LayoutDashboard },
         { href: `${base}/clients`, label: 'Clients', icon: Users },
         { href: `${base}/yachts`, label: 'Yachts', icon: Ship },
+        { href: `${base}/companies`, label: 'Companies', icon: Building2 },
         { href: `${base}/interests`, label: 'Interests', icon: Bookmark },
         { href: `${base}/berths`, label: 'Berths', icon: Anchor },
       ],