@mars-stack/core 0.4.0

package/cursor/skills/mars-build-data-table/SKILL.md

@@ -0,0 +1,284 @@
+# Skill: Build a Data Table
+
+Create a data table with sorting, pagination, and actions using MARS design system components.
+
+## When to Use
+
+Use this skill when the user asks to display tabular data, build a list view, create a data grid, or show records in a table.
+
+## Architecture
+
+MARS provides `Table` primitives (`Table`, `TableHead`, `TableBody`, `TableRow`, `TableHeaderCell`, `TableCell`) that use design tokens. Build feature-specific tables by composing these.
+
+## Template: Full Data Table
+
+```tsx
+'use client';
+
+import { useEffect, useState, useCallback } from 'react';
+import {
+  Table, TableHead, TableBody, TableRow, TableHeaderCell, TableCell,
+  Badge, Button, Spinner, Card, CardHeader, CardBody, EmptyState,
+} from '@mars-stack/ui';
+
+interface Item {
+  id: string;
+  name: string;
+  status: 'active' | 'inactive' | 'pending';
+  createdAt: string;
+}
+
+interface PaginatedResponse {
+  items: Item[];
+  pagination: { page: number; limit: number; total: number; totalPages: number };
+}
+
+type SortField = 'name' | 'status' | 'createdAt';
+type SortDirection = 'asc' | 'desc';
+
+const statusVariant: Record<Item['status'], 'success' | 'neutral' | 'warning'> = {
+  active: 'success',
+  inactive: 'neutral',
+  pending: 'warning',
+};
+
+export function ItemTable() {
+  const [data, setData] = useState<PaginatedResponse | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [page, setPage] = useState(1);
+  const [sortField, setSortField] = useState<SortField>('createdAt');
+  const [sortDir, setSortDir] = useState<SortDirection>('desc');
+
+  const fetchData = useCallback(async () => {
+    setLoading(true);
+    try {
+      const params = new URLSearchParams({
+        page: String(page),
+        limit: '20',
+        sort: sortField,
+        dir: sortDir,
+      });
+      const res = await fetch(`/api/protected/items?${params}`);
+      const json = await res.json();
+      setData(json);
+    } finally {
+      setLoading(false);
+    }
+  }, [page, sortField, sortDir]);
+
+  useEffect(() => { fetchData(); }, [fetchData]);
+
+  function handleSort(field: SortField) {
+    if (sortField === field) {
+      setSortDir((d) => (d === 'asc' ? 'desc' : 'asc'));
+    } else {
+      setSortField(field);
+      setSortDir('asc');
+    }
+    setPage(1);
+  }
+
+  function SortIndicator({ field }: { field: SortField }) {
+    if (sortField !== field) return <span className="text-text-muted ml-1">↕</span>;
+    return <span className="text-text-primary ml-1">{sortDir === 'asc' ? '↑' : '↓'}</span>;
+  }
+
+  if (loading && !data) {
+    return (
+      <div className="flex justify-center py-12">
+        <Spinner size="lg" />
+      </div>
+    );
+  }
+
+  if (!data || data.items.length === 0) {
+    return (
+      <EmptyState
+        title="No items yet"
+        description="Create your first item to get started."
+      />
+    );
+  }
+
+  const { items, pagination } = data;
+
+  return (
+    <Card>
+      <CardHeader className="flex items-center justify-between">
+        <h2 className="text-lg font-semibold text-text-primary">
+          Items ({pagination.total})
+        </h2>
+      </CardHeader>
+      <CardBody className="p-0">
+        <Table>
+          <TableHead>
+            <TableRow>
+              <TableHeaderCell>
+                <button onClick={() => handleSort('name')} className="flex items-center">
+                  Name <SortIndicator field="name" />
+                </button>
+              </TableHeaderCell>
+              <TableHeaderCell>
+                <button onClick={() => handleSort('status')} className="flex items-center">
+                  Status <SortIndicator field="status" />
+                </button>
+              </TableHeaderCell>
+              <TableHeaderCell>
+                <button onClick={() => handleSort('createdAt')} className="flex items-center">
+                  Created <SortIndicator field="createdAt" />
+                </button>
+              </TableHeaderCell>
+              <TableHeaderCell>
+                <span className="sr-only">Actions</span>
+              </TableHeaderCell>
+            </TableRow>
+          </TableHead>
+          <TableBody>
+            {items.map((item) => (
+              <TableRow key={item.id}>
+                <TableCell className="font-medium text-text-primary">{item.name}</TableCell>
+                <TableCell>
+                  <Badge variant={statusVariant[item.status]}>{item.status}</Badge>
+                </TableCell>
+                <TableCell className="text-text-secondary">
+                  {new Date(item.createdAt).toLocaleDateString()}
+                </TableCell>
+                <TableCell className="text-right">
+                  <Button variant="subtle" size="sm">Edit</Button>
+                </TableCell>
+              </TableRow>
+            ))}
+          </TableBody>
+        </Table>
+      </CardBody>
+
+      {pagination.totalPages > 1 && (
+        <div className="flex items-center justify-between border-t border-border-default px-4 py-3">
+          <p className="text-sm text-text-secondary">
+            Page {pagination.page} of {pagination.totalPages}
+          </p>
+          <div className="flex gap-2">
+            <Button
+              variant="subtle"
+              size="sm"
+              disabled={pagination.page <= 1}
+              onClick={() => setPage((p) => p - 1)}
+            >
+              Previous
+            </Button>
+            <Button
+              variant="subtle"
+              size="sm"
+              disabled={pagination.page >= pagination.totalPages}
+              onClick={() => setPage((p) => p + 1)}
+            >
+              Next
+            </Button>
+          </div>
+        </div>
+      )}
+    </Card>
+  );
+}
+```
+
+## API Endpoint for Sorted + Paginated Data
+
+```typescript
+export const GET = withAuthNoParams(async (request: AuthenticatedRequest) => {
+  try {
+    const url = new URL(request.url);
+    const page = Math.max(1, Number(url.searchParams.get('page') || '1'));
+    const limit = Math.min(100, Math.max(1, Number(url.searchParams.get('limit') || '20')));
+    const sort = url.searchParams.get('sort') || 'createdAt';
+    const dir = url.searchParams.get('dir') === 'asc' ? 'asc' : 'desc';
+
+    const allowedSortFields = ['name', 'status', 'createdAt'];
+    const orderBy = allowedSortFields.includes(sort)
+      ? { [sort]: dir }
+      : { createdAt: 'desc' as const };
+
+    const where = { userId: request.session.userId };
+    const [items, total] = await Promise.all([
+      prisma.item.findMany({ where, orderBy, skip: (page - 1) * limit, take: limit }),
+      prisma.item.count({ where }),
+    ]);
+
+    return NextResponse.json({
+      items,
+      pagination: { page, limit, total, totalPages: Math.ceil(total / limit) },
+    });
+  } catch (error) {
+    return handleApiError(error, { endpoint: '/api/protected/items' });
+  }
+});
+```
+
+## Patterns
+
+### Search/Filter Bar
+
+```tsx
+<CardHeader className="flex flex-col gap-3 sm:flex-row sm:items-center sm:justify-between">
+  <h2 className="text-lg font-semibold text-text-primary">Items</h2>
+  <div className="flex gap-2">
+    <Input
+      name="search"
+      placeholder="Search..."
+      value={search}
+      onChange={(e) => setSearch(e.target.value)}
+      className="w-48"
+    />
+    <Select
+      name="status"
+      value={statusFilter}
+      onChange={(e) => setStatusFilter(e.target.value)}
+      options={[
+        { value: '', label: 'All statuses' },
+        { value: 'active', label: 'Active' },
+        { value: 'inactive', label: 'Inactive' },
+      ]}
+    />
+  </div>
+</CardHeader>
+```
+
+### Row Actions (Delete with Confirmation)
+
+```tsx
+<TableCell className="text-right">
+  <div className="flex justify-end gap-1">
+    <Button variant="subtle" size="sm" onClick={() => handleEdit(item.id)}>
+      Edit
+    </Button>
+    <Button variant="danger" size="sm" onClick={() => handleDelete(item.id)}>
+      Delete
+    </Button>
+  </div>
+</TableCell>
+```
+
+### Loading Overlay
+
+```tsx
+<div className="relative">
+  {loading && (
+    <div className="absolute inset-0 flex items-center justify-center bg-surface-card/80 z-10">
+      <Spinner size="md" />
+    </div>
+  )}
+  <Table>...</Table>
+</div>
+```
+
+## Checklist
+
+- [ ] Table uses MARS `Table` primitives
+- [ ] Sortable column headers with visual indicators
+- [ ] Pagination with page controls
+- [ ] Empty state when no data
+- [ ] Loading spinner on initial load
+- [ ] Status badges use `Badge` with appropriate variants
+- [ ] All colours use semantic tokens
+- [ ] API endpoint supports `page`, `limit`, `sort`, `dir` params
+- [ ] Sort field allowlist prevents injection

package/cursor/skills/mars-build-form/SKILL.md

@@ -0,0 +1,229 @@
+# Skill: Build a Form
+
+Create a validated form using MARS design system components, Zod schemas, and proper error handling.
+
+## When to Use
+
+Use this skill when the user asks to build a form, input form, settings form, contact form, or any data entry UI.
+
+## Architecture
+
+MARS forms use:
+- **Primitives** (`Input`, `Select`, `Checkbox`, `Textarea`, `Button`) for fields
+- **Patterns** (`FormField`, `Card`) for layout
+- **Zod schemas** for validation (shared with API routes)
+- **`useZodForm` hook** for client-side form state (if available), or native React state
+
+## Template: Basic Form
+
+```tsx
+'use client';
+
+import { useState, type FormEvent } from 'react';
+import { Button, Input, Select, Textarea, Checkbox, Card, CardHeader, CardBody, CardFooter, H2 } from '@mars-stack/ui';
+import { z } from 'zod';
+
+const formSchema = z.object({
+  name: z.string().min(1, 'Name is required').max(100),
+  email: z.string().email('Invalid email address'),
+  category: z.string().min(1, 'Please select a category'),
+  message: z.string().min(10, 'Message must be at least 10 characters').max(1000),
+  agree: z.literal(true, { errorMap: () => ({ message: 'You must agree to continue' }) }),
+});
+
+type FormData = z.infer<typeof formSchema>;
+type FormErrors = Partial<Record<keyof FormData, string>>;
+
+export function ContactForm() {
+  const [errors, setErrors] = useState<FormErrors>({});
+  const [submitting, setSubmitting] = useState(false);
+  const [success, setSuccess] = useState(false);
+
+  async function handleSubmit(e: FormEvent<HTMLFormElement>) {
+    e.preventDefault();
+    setErrors({});
+
+    const formData = new FormData(e.currentTarget);
+    const raw = {
+      name: formData.get('name') as string,
+      email: formData.get('email') as string,
+      category: formData.get('category') as string,
+      message: formData.get('message') as string,
+      agree: formData.get('agree') === 'on' ? true : false,
+    };
+
+    const result = formSchema.safeParse(raw);
+    if (!result.success) {
+      const fieldErrors: FormErrors = {};
+      for (const issue of result.error.issues) {
+        const field = issue.path[0] as keyof FormData;
+        if (!fieldErrors[field]) fieldErrors[field] = issue.message;
+      }
+      setErrors(fieldErrors);
+      return;
+    }
+
+    setSubmitting(true);
+    try {
+      const response = await fetch('/api/protected/contact', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(result.data),
+      });
+
+      if (!response.ok) {
+        const data = await response.json();
+        setErrors({ name: data.error || 'Something went wrong' });
+        return;
+      }
+
+      setSuccess(true);
+    } finally {
+      setSubmitting(false);
+    }
+  }
+
+  if (success) {
+    return (
+      <Card>
+        <CardBody className="text-center py-8">
+          <p className="text-text-success font-medium">Message sent successfully!</p>
+        </CardBody>
+      </Card>
+    );
+  }
+
+  return (
+    <form onSubmit={handleSubmit} noValidate>
+      <Card>
+        <CardHeader>
+          <H2>Contact Us</H2>
+        </CardHeader>
+        <CardBody className="space-y-4">
+          <Input
+            name="name"
+            label="Full Name"
+            placeholder="Jane Smith"
+            error={errors.name}
+            required
+          />
+          <Input
+            name="email"
+            label="Email"
+            type="email"
+            placeholder="jane@example.com"
+            error={errors.email}
+            required
+          />
+          <Select
+            name="category"
+            label="Category"
+            placeholder="Select a category"
+            error={errors.category}
+            options={[
+              { value: 'general', label: 'General Inquiry' },
+              { value: 'support', label: 'Technical Support' },
+              { value: 'billing', label: 'Billing' },
+              { value: 'feedback', label: 'Feedback' },
+            ]}
+          />
+          <Textarea
+            name="message"
+            label="Message"
+            placeholder="Tell us how we can help..."
+            rows={5}
+            error={errors.message}
+            required
+          />
+          <Checkbox
+            name="agree"
+            label="I agree to the terms and conditions"
+            error={errors.agree}
+          />
+        </CardBody>
+        <CardFooter className="flex justify-end gap-3">
+          <Button type="button" variant="subtle">
+            Cancel
+          </Button>
+          <Button type="submit" disabled={submitting}>
+            {submitting ? 'Sending...' : 'Send Message'}
+          </Button>
+        </CardFooter>
+      </Card>
+    </form>
+  );
+}
+```
+
+## Validation Pattern
+
+**Share schemas between client and API:**
+
+```typescript
+// src/features/contact/validation/schemas.ts
+import { z } from 'zod';
+
+export const contactSchemas = {
+  create: z.object({
+    name: z.string().min(1).max(100),
+    email: z.string().email(),
+    category: z.string().min(1),
+    message: z.string().min(10).max(1000),
+  }),
+};
+```
+
+Import in both the form component and the API route handler.
+
+## Form Layouts
+
+### Two-Column Layout
+
+```tsx
+<CardBody className="grid grid-cols-1 gap-4 md:grid-cols-2">
+  <Input name="firstName" label="First Name" />
+  <Input name="lastName" label="Last Name" />
+  <Input name="email" label="Email" className="md:col-span-2" />
+</CardBody>
+```
+
+### Sections with Dividers
+
+```tsx
+<CardBody className="space-y-6">
+  <div className="space-y-4">
+    <h3 className="text-sm font-medium text-text-secondary uppercase tracking-wide">Personal</h3>
+    <Input name="name" label="Name" />
+    <Input name="email" label="Email" />
+  </div>
+  <Divider />
+  <div className="space-y-4">
+    <h3 className="text-sm font-medium text-text-secondary uppercase tracking-wide">Preferences</h3>
+    <Select name="timezone" label="Timezone" options={timezones} />
+  </div>
+</CardBody>
+```
+
+## With Server Actions
+
+For progressive enhancement, use Server Actions instead of `fetch`:
+
+```tsx
+<form action={submitContact}>
+  <Input name="name" label="Name" />
+  <Button type="submit">Send</Button>
+</form>
+```
+
+See the `add-server-action` skill for the full pattern.
+
+## Checklist
+
+- [ ] Zod schema defined and shared with API route
+- [ ] Client-side validation with `safeParse` before submission
+- [ ] Error messages displayed on individual fields
+- [ ] Loading state on submit button
+- [ ] Success state after submission
+- [ ] All form inputs use MARS primitives (`Input`, `Select`, `Textarea`, `Checkbox`)
+- [ ] Form wrapped in `Card` pattern for consistent layout
+- [ ] `noValidate` on `<form>` to use custom validation