@pylonsync/create-pylon 0.3.344 → 0.3.345

package/templates/helpdesk/app/workspace.tsx

@@ -0,0 +1,210 @@
+"use client";
+
+import React, { useEffect, useMemo, useRef, useState } from "react";
+import { callFn, db, useRouter } from "@pylonsync/react";
+import { useAuth } from "@pylonsync/client";
+import { Sidebar } from "@/components/sidebar";
+import { CommandPalette } from "@/components/command-palette";
+import type { SearchItem } from "@/lib/search";
+import { counts, isOpen } from "@/lib/tickets";
+
+export interface CustomerRow {
+  id: string;
+  name: string;
+  email: string;
+  company?: string | null;
+  createdAt?: string | null;
+}
+export interface TicketRow {
+  id: string;
+  subject: string;
+  status: string;
+  priority: string;
+  customerId?: string | null;
+  assigneeId?: string | null;
+  firstRespondedAt?: string | null;
+  createdAt?: string | null;
+  updatedAt?: string | null;
+}
+export interface MessageRow {
+  id: string;
+  ticketId: string;
+  body: string;
+  fromCustomer?: boolean | null;
+  internal?: boolean | null;
+  authorId?: string | null;
+  createdAt?: string | null;
+}
+export interface UserRow {
+  id: string;
+  email: string;
+  displayName?: string | null;
+}
+
+export interface WorkspaceData {
+  customers: CustomerRow[];
+  tickets: TicketRow[];
+  messages: MessageRow[];
+  agents: UserRow[];
+  customerName: (id: string | null | undefined) => string | null;
+  agentName: (id: string | null | undefined) => string | null;
+  loading: boolean;
+}
+
+/**
+ * The app shell, and the ONLY place that touches `db`.
+ *
+ * Every view below receives plain data through the render prop and reports
+ * changes through callbacks, which is what lets the components in `components/`
+ * render from fixtures in a test with nothing mocked.
+ *
+ * Each `db.useQuery` is live: a ticket another agent assigns, or a reply they
+ * send, arrives here and re-renders the queue. Your own writes take the same
+ * path, so there's one behaviour to reason about rather than two.
+ */
+export function Workspace({
+  email,
+  pathname,
+  children,
+}: {
+  email: string;
+  pathname: string;
+  children: (data: WorkspaceData) => React.ReactNode;
+}) {
+  const router = useRouter();
+  const { signOut } = useAuth();
+  const { data: tickets, loading } = db.useQuery<TicketRow>("Ticket");
+  const { data: customers } = db.useQuery<CustomerRow>("Customer");
+  const { data: messages } = db.useQuery<MessageRow>("Message");
+  const { data: users } = db.useQuery<UserRow>("User");
+
+  const [paletteOpen, setPaletteOpen] = useState(false);
+  const seeded = useRef(false);
+
+  const ticketList = tickets ?? [];
+  const customerList = customers ?? [];
+  const agentList = users ?? [];
+
+  // A brand-new helpdesk gets a realistic queue once, so the inbox never opens
+  // empty. `seedWorkspace` no-ops when anything exists; the ref stops a
+  // re-render from firing a second call mid-flight.
+  useEffect(() => {
+    if (loading || seeded.current) return;
+    if (ticketList.length > 0) {
+      seeded.current = true;
+      return;
+    }
+    seeded.current = true;
+    callFn("seedWorkspace", {}).catch(() => {
+      // A failed seed leaves an empty inbox, which is usable — the queue has an
+      // empty state that offers to open the first ticket.
+      seeded.current = false;
+    });
+  }, [loading, ticketList.length]);
+
+  useEffect(() => {
+    function onKey(event: KeyboardEvent) {
+      const target = event.target as HTMLElement | null;
+      const typing =
+        !!target &&
+        (target.tagName === "INPUT" ||
+          target.tagName === "TEXTAREA" ||
+          target.isContentEditable);
+      if ((event.metaKey || event.ctrlKey) && event.key.toLowerCase() === "k") {
+        event.preventDefault();
+        setPaletteOpen((open) => !open);
+      } else if (event.key === "/" && !typing) {
+        event.preventDefault();
+        setPaletteOpen(true);
+      }
+    }
+    window.addEventListener("keydown", onKey);
+    return () => window.removeEventListener("keydown", onKey);
+  }, []);
+
+  const lookups = useMemo(() => {
+    const customerById = new Map(customerList.map((c) => [c.id, c] as const));
+    const userById = new Map(agentList.map((u) => [u.id, u] as const));
+    return { customerById, userById };
+  }, [customerList, agentList]);
+
+  const searchIndex = useMemo<SearchItem[]>(
+    () => [
+      ...ticketList.map((ticket) => ({
+        id: `ticket:${ticket.id}`,
+        type: "deal" as const,
+        title: ticket.subject,
+        subtitle: lookups.customerById.get(ticket.customerId ?? "")?.name,
+        href: `/tickets/${ticket.id}`,
+      })),
+      ...customerList.map((customer) => ({
+        id: `customer:${customer.id}`,
+        type: "contact" as const,
+        title: customer.name,
+        subtitle: customer.company ?? undefined,
+        href: "/customers",
+        keywords: customer.email,
+      })),
+    ],
+    [ticketList, customerList, lookups],
+  );
+
+  const queue = counts(ticketList);
+
+  const data: WorkspaceData = {
+    customers: customerList,
+    tickets: ticketList,
+    messages: messages ?? [],
+    agents: agentList,
+    customerName: (id) => lookups.customerById.get(id ?? "")?.name ?? null,
+    agentName: (id) => {
+      const user = lookups.userById.get(id ?? "");
+      return user?.displayName || user?.email || null;
+    },
+    loading,
+  };
+
+  return (
+    <div className="flex h-screen overflow-hidden">
+      <Sidebar
+        workspace="Helpdesk"
+        email={email}
+        pathname={pathname}
+        counts={{
+          "/": ticketList.filter(isOpen).length,
+          "/customers": customerList.length,
+        }}
+        onOpenCommand={() => setPaletteOpen(true)}
+        onSignOut={async () => {
+          await signOut();
+          window.location.assign("/login");
+        }}
+      />
+      <main className="flex min-w-0 flex-1 flex-col">{children(data)}</main>
+
+      <CommandPalette
+        open={paletteOpen}
+        items={searchIndex}
+        actions={[
+          {
+            id: "new-ticket",
+            label: "New ticket",
+            run: () => router.push("/?new=ticket"),
+          },
+          {
+            id: "unassigned",
+            label: `Unassigned (${queue.unassigned})`,
+            run: () => router.push("/?filter=unassigned"),
+          },
+          {
+            id: "go-customers",
+            label: "Go to Customers",
+            run: () => router.push("/customers"),
+          },
+        ]}
+        onClose={() => setPaletteOpen(false)}
+        onSelect={(item) => router.push(item.href)}
+      />
+    </div>
+  );
+}

package/templates/helpdesk/app.ts

@@ -0,0 +1,142 @@
+import {
+  entity,
+  field,
+  policy,
+  auth,
+  buildManifest,
+  discoverAppRoutes,
+  font,
+} from "@pylonsync/sdk";
+
+// ---------------------------------------------------------------------------
+// helpdesk — a support inbox for a small team: customers write in, agents triage
+// by priority and SLA, and every reply lands on a shared thread.
+//
+// The realtime hook: the queue subscribes to Ticket, so a new ticket appears at
+// the top of everyone's inbox as it arrives, and an assignment shows up before
+// two agents start the same reply.
+//
+//   • Customer — the person who wrote in. Holds email, so never public.
+//   • Ticket   — subject, status, priority, assignee. The queue.
+//   • Message  — one entry on a thread; `internal` marks an agent-only note.
+//   • User     — an agent (email/password).
+//
+// TRUST MODEL: an internal tool for ONE support team. Every entity is readable
+// and writable by any SIGNED-IN user and by nobody else. There is no customer
+// portal here — adding one means a separate, narrower policy scoped to the
+// customer's own tickets, NOT loosening these.
+// ---------------------------------------------------------------------------
+
+const TEAM = "auth.userId != null";
+
+const Customer = entity(
+  "Customer",
+  {
+    name: field.string(),
+    email: field.string(),
+    company: field.string().optional(),
+    createdAt: field.datetime().defaultNow(),
+  },
+  { indexes: [{ name: "by_email", fields: ["email"], unique: false }] },
+);
+
+const Ticket = entity(
+  "Ticket",
+  {
+    subject: field.string(),
+    // "open" | "pending" | "solved" | "closed" — see STATUSES in lib/tickets.ts.
+    status: field.string().default("open"),
+    // "urgent" | "high" | "normal" | "low" — sets the first-response window.
+    priority: field.string().default("normal"),
+    customerId: field.id("Customer").optional(),
+    assigneeId: field.id("User").optional(),
+    // When an agent first replied. Null means the customer is still waiting,
+    // which is what the SLA state is computed from.
+    firstRespondedAt: field.datetime().optional(),
+    createdAt: field.datetime().defaultNow(),
+    updatedAt: field.datetime().defaultNow(),
+  },
+  {
+    indexes: [
+      { name: "by_status", fields: ["status"], unique: false },
+      { name: "by_assignee", fields: ["assigneeId"], unique: false },
+    ],
+  },
+);
+
+const Message = entity(
+  "Message",
+  {
+    ticketId: field.id("Ticket"),
+    body: field.string(),
+    // True when the customer wrote it rather than an agent.
+    fromCustomer: field.boolean().default(false),
+    // An internal note stays with the team if you later add a customer portal.
+    internal: field.boolean().default(false),
+    authorId: field.id("User").readonly().optional(),
+    createdAt: field.datetime().defaultNow(),
+  },
+  { indexes: [{ name: "by_ticket", fields: ["ticketId"], unique: false }] },
+);
+
+const User = entity(
+  "User",
+  {
+    email: field.string(),
+    displayName: field.string().optional(),
+    passwordHash: field.string().serverOnly().optional(),
+    avatarColor: field.string().optional(),
+    emailVerified: field.datetime().optional(),
+    createdAt: field.datetime().defaultNow(),
+  },
+  { indexes: [{ name: "by_email", fields: ["email"], unique: true }] },
+);
+
+const teamPolicy = (name: string, entityName: string) =>
+  policy({
+    name,
+    entity: entityName,
+    allowRead: TEAM,
+    allowInsert: TEAM,
+    allowUpdate: TEAM,
+    allowDelete: TEAM,
+  });
+
+const userPolicy = policy({
+  name: "user_team_read",
+  entity: "User",
+  allowRead: TEAM,
+  allowInsert: "false",
+  allowUpdate: "false",
+  allowDelete: "false",
+});
+
+const manifest = buildManifest({
+  name: "__APP_NAME__",
+  version: "0.1.0",
+  entities: [Customer, Ticket, Message, User],
+  queries: [],
+  actions: [],
+  policies: [
+    teamPolicy("customer_team", "Customer"),
+    teamPolicy("ticket_team", "Ticket"),
+    teamPolicy("message_team", "Message"),
+    userPolicy,
+  ],
+  auth: auth(),
+  fonts: [
+    font({
+      family: "Inter",
+      variable: "--font-sans",
+      weights: ["400", "500", "600", "700"],
+      subsets: ["latin"],
+      display: "swap",
+      preload: true,
+    }),
+  ],
+  routes: await discoverAppRoutes(),
+});
+
+console.log(JSON.stringify(manifest, null, 2));
+
+export default manifest;

package/templates/helpdesk/bunfig

@@ -0,0 +1,4 @@
+[test]
+# Register a DOM (happy-dom) before any test runs so React component tests can
+# render under `pylon test` / `bun test`. Harmless for pure-logic tests.
+preload = ["./tests/setup.ts"]

package/templates/helpdesk/components/avatar.tsx

@@ -0,0 +1,40 @@
+import React from "react";
+import { cn } from "@/lib/utils";
+import { accentIndex, initials } from "@/lib/format";
+
+// Deterministic accent per record — the same company keeps its colour across
+// sessions and machines without storing one. Hues are muted so a dense list
+// doesn't turn into confetti.
+const ACCENTS = [
+  "bg-indigo-500/15 text-indigo-500 dark:text-indigo-300",
+  "bg-emerald-500/15 text-emerald-600 dark:text-emerald-300",
+  "bg-amber-500/15 text-amber-600 dark:text-amber-300",
+  "bg-rose-500/15 text-rose-500 dark:text-rose-300",
+  "bg-sky-500/15 text-sky-600 dark:text-sky-300",
+  "bg-violet-500/15 text-violet-500 dark:text-violet-300",
+];
+
+export function Avatar({
+  name,
+  size = "md",
+  className,
+}: {
+  name: string | null | undefined;
+  size?: "sm" | "md";
+  className?: string;
+}) {
+  const label = initials(name);
+  return (
+    <span
+      aria-hidden="true"
+      className={cn(
+        "inline-flex shrink-0 select-none items-center justify-center rounded-full font-medium",
+        size === "sm" ? "size-5 text-[9px]" : "size-6 text-[10px]",
+        ACCENTS[accentIndex(name ?? "?", ACCENTS.length)],
+        className,
+      )}
+    >
+      {label}
+    </span>
+  );
+}

package/templates/helpdesk/components/command-palette.tsx

@@ -0,0 +1,162 @@
+import React, { useEffect, useMemo, useRef, useState } from "react";
+import { Building2, Plus, Search, User } from "lucide-react";
+import { cn } from "@/lib/utils";
+import { Kbd } from "@/components/kbd";
+import { moveSelection, searchItems, type SearchItem } from "@/lib/search";
+
+const TYPE_ICON: Record<SearchItem["type"], React.ReactNode> = {
+  deal: <Search />,
+  company: <Building2 />,
+  contact: <User />,
+};
+
+export interface CommandAction {
+  id: string;
+  label: string;
+  run: () => void;
+}
+
+/**
+ * ⌘K. Searches the synced replica in memory, so results land as you type with
+ * no request per keystroke — see lib/search.ts for the ranking.
+ *
+ * Presentational: items and actions come in as props, selection is delegated
+ * through onSelect. Keyboard handling lives here because it belongs to the
+ * widget, not to the page that opened it.
+ */
+export function CommandPalette({
+  open,
+  items,
+  actions = [],
+  onClose,
+  onSelect,
+}: {
+  open: boolean;
+  items: SearchItem[];
+  actions?: CommandAction[];
+  onClose: () => void;
+  onSelect: (item: SearchItem) => void;
+}) {
+  const [query, setQuery] = useState("");
+  const [index, setIndex] = useState(0);
+  const inputRef = useRef<HTMLInputElement | null>(null);
+
+  const results = useMemo(() => searchItems(items, query), [items, query]);
+  const shownActions = query.trim() ? [] : actions;
+  const rows = useMemo(
+    () => [
+      ...shownActions.map((a) => ({ kind: "action" as const, action: a })),
+      ...results.map((item) => ({ kind: "item" as const, item })),
+    ],
+    [shownActions, results],
+  );
+
+  useEffect(() => {
+    if (!open) return;
+    setQuery("");
+    setIndex(0);
+    // Focus after paint so the dialog is mounted and the caret lands.
+    const id = requestAnimationFrame(() => inputRef.current?.focus());
+    return () => cancelAnimationFrame(id);
+  }, [open]);
+
+  useEffect(() => {
+    setIndex(0);
+  }, [query]);
+
+  if (!open) return null;
+
+  function commit(at: number) {
+    const row = rows[at];
+    if (!row) return;
+    if (row.kind === "action") row.action.run();
+    else onSelect(row.item);
+    onClose();
+  }
+
+  return (
+    <div
+      className="fixed inset-0 z-50 flex items-start justify-center bg-black/50 pt-[12vh]"
+      // Clicking the backdrop dismisses; clicks inside the panel must not.
+      onMouseDown={(event) => {
+        if (event.target === event.currentTarget) onClose();
+      }}
+    >
+      <div
+        role="dialog"
+        aria-modal="true"
+        aria-label="Search"
+        className="w-full max-w-lg overflow-hidden rounded-xl border border-border bg-popover shadow-2xl"
+        onKeyDown={(event) => {
+          if (event.key === "Escape") {
+            event.preventDefault();
+            onClose();
+          } else if (event.key === "ArrowDown") {
+            event.preventDefault();
+            setIndex((i) => moveSelection(i, 1, rows.length));
+          } else if (event.key === "ArrowUp") {
+            event.preventDefault();
+            setIndex((i) => moveSelection(i, -1, rows.length));
+          } else if (event.key === "Enter") {
+            event.preventDefault();
+            commit(index);
+          }
+        }}
+      >
+        <div className="flex items-center gap-2 border-b border-border px-3">
+          <Search className="size-4 shrink-0 text-muted-foreground" />
+          <input
+            ref={inputRef}
+            value={query}
+            onChange={(event) => setQuery(event.target.value)}
+            placeholder="Search deals, companies, contacts…"
+            aria-label="Search deals, companies and contacts"
+            className="h-11 flex-1 bg-transparent text-[13px] outline-none placeholder:text-muted-foreground"
+          />
+          <Kbd>esc</Kbd>
+        </div>
+
+        <div className="max-h-80 overflow-y-auto p-1.5">
+          {rows.length === 0 ? (
+            <p className="px-3 py-6 text-center text-[12px] text-muted-foreground">
+              No matches for “{query}”
+            </p>
+          ) : (
+            rows.map((row, at) => (
+              <button
+                key={row.kind === "action" ? row.action.id : row.item.id}
+                type="button"
+                // Pointer hover moves selection so mouse and keyboard agree.
+                onMouseMove={() => setIndex(at)}
+                onClick={() => commit(at)}
+                aria-selected={at === index}
+                className={cn(
+                  "flex w-full items-center gap-2.5 rounded-md px-2.5 py-2 text-left text-[13px] transition-colors",
+                  "[&_svg]:size-3.5 [&_svg]:shrink-0 [&_svg]:text-muted-foreground",
+                  at === index ? "bg-surface-2" : "hover:bg-surface-2/60",
+                )}
+              >
+                {row.kind === "action" ? (
+                  <>
+                    <Plus />
+                    <span className="flex-1 truncate">{row.action.label}</span>
+                  </>
+                ) : (
+                  <>
+                    {TYPE_ICON[row.item.type]}
+                    <span className="flex-1 truncate">{row.item.title}</span>
+                    {row.item.subtitle ? (
+                      <span className="truncate text-[12px] text-muted-foreground">
+                        {row.item.subtitle}
+                      </span>
+                    ) : null}
+                  </>
+                )}
+              </button>
+            ))
+          )}
+        </div>
+      </div>
+    </div>
+  );
+}

package/templates/helpdesk/components/data-table.tsx

@@ -0,0 +1,90 @@
+import React from "react";
+import { cn } from "@/lib/utils";
+
+export interface ColumnDef<Row> {
+  key: string;
+  header: string;
+  /** Cell content. Return a string and it's rendered as-is. */
+  cell: (row: Row) => React.ReactNode;
+  /** Right-align and tabular-figure a numeric column. */
+  numeric?: boolean;
+  className?: string;
+}
+
+/**
+ * A dense list view. Rows are 36px so a screenful is a screenful of data, and
+ * the header sticks while the body scrolls.
+ *
+ * Generic and presentational — every view here uses the same one, which is why
+ * companies and contacts look like the same product.
+ */
+export function DataTable<Row extends { id: string }>({
+  rows,
+  columns,
+  onRowClick,
+  empty,
+}: {
+  rows: Row[];
+  columns: ColumnDef<Row>[];
+  onRowClick?: (row: Row) => void;
+  empty?: React.ReactNode;
+}) {
+  if (rows.length === 0 && empty) return <>{empty}</>;
+
+  return (
+    <div className="min-h-0 flex-1 overflow-auto">
+      <table className="w-full border-collapse text-[13px]">
+        <thead className="sticky top-0 z-10 bg-background">
+          <tr className="hairline">
+            {columns.map((column) => (
+              <th
+                key={column.key}
+                scope="col"
+                className={cn(
+                  "h-8 px-4 text-left text-[11px] font-medium text-muted-foreground",
+                  column.numeric && "text-right",
+                  column.className,
+                )}
+              >
+                {column.header}
+              </th>
+            ))}
+          </tr>
+        </thead>
+        <tbody>
+          {rows.map((row) => (
+            <tr
+              key={row.id}
+              onClick={onRowClick ? () => onRowClick(row) : undefined}
+              tabIndex={onRowClick ? 0 : undefined}
+              onKeyDown={
+                onRowClick
+                  ? (event) => {
+                      if (event.key === "Enter") onRowClick(row);
+                    }
+                  : undefined
+              }
+              className={cn(
+                "border-b border-border/60 transition-colors",
+                onRowClick && "cursor-pointer hover:bg-surface-1",
+              )}
+            >
+              {columns.map((column) => (
+                <td
+                  key={column.key}
+                  className={cn(
+                    "h-9 max-w-0 truncate px-4",
+                    column.numeric && "tabular text-right",
+                    column.className,
+                  )}
+                >
+                  {column.cell(row)}
+                </td>
+              ))}
+            </tr>
+          ))}
+        </tbody>
+      </table>
+    </div>
+  );
+}

package/templates/helpdesk/components/empty-state.tsx

@@ -0,0 +1,43 @@
+import React from "react";
+import { cn } from "@/lib/utils";
+
+/**
+ * An empty state that says what this screen is for and offers the one action
+ * that fills it. "No records found" tells a new user nothing and gives them
+ * nowhere to go.
+ */
+export function EmptyState({
+  icon,
+  title,
+  description,
+  action,
+  className,
+}: {
+  icon?: React.ReactNode;
+  title: string;
+  description?: string;
+  action?: React.ReactNode;
+  className?: string;
+}) {
+  return (
+    <div
+      className={cn(
+        "flex flex-col items-center justify-center px-6 py-16 text-center",
+        className,
+      )}
+    >
+      {icon ? (
+        <div className="mb-3 flex size-9 items-center justify-center rounded-lg bg-surface-2 text-muted-foreground [&_svg]:size-4">
+          {icon}
+        </div>
+      ) : null}
+      <p className="text-[13px] font-medium">{title}</p>
+      {description ? (
+        <p className="mt-1 max-w-sm text-[12px] leading-5 text-muted-foreground">
+          {description}
+        </p>
+      ) : null}
+      {action ? <div className="mt-4">{action}</div> : null}
+    </div>
+  );
+}