@pylonsync/create-pylon 0.3.344 → 0.3.346

package/templates/projects/lib/work.ts

@@ -0,0 +1,233 @@
+// Projects, tasks, and time.
+//
+// TIME IS A LEDGER, like stock in the inventory template: a task's logged hours
+// are the sum of its time entries, never a running total on the task. Two people
+// logging against the same task at once is normal, and a mutable total loses one
+// of them. It also means every hour on an invoice traces to who logged it and
+// when — which is the question a client asks.
+//
+// Minutes are integers. Hours as floats produce 7.999999 on a timesheet, and
+// nobody wants to explain that.
+//
+// Pure: no React, no `db`.
+
+export interface Status {
+  id: string;
+  label: string;
+  /** Done and cancelled leave the active board. */
+  terminal?: boolean;
+}
+
+export const TASK_STATUSES: Status[] = [
+  { id: "todo", label: "To do" },
+  { id: "doing", label: "In progress" },
+  { id: "review", label: "Review" },
+  { id: "done", label: "Done", terminal: true },
+];
+
+export const PROJECT_STATUSES: Status[] = [
+  { id: "active", label: "Active" },
+  { id: "paused", label: "Paused" },
+  { id: "complete", label: "Complete", terminal: true },
+];
+
+export interface Project {
+  id: string;
+  name: string;
+  clientId?: string | null;
+  status: string;
+  /** Agreed budget in whole minutes, 0 for none. */
+  budgetMinutes?: number | null;
+  hourlyRateCents?: number | null;
+  dueDate?: string | null;
+  createdAt?: string | null;
+}
+
+export interface Task {
+  id: string;
+  projectId: string;
+  title: string;
+  status: string;
+  assigneeId?: string | null;
+  /** What we thought it would take, in minutes. */
+  estimateMinutes?: number | null;
+  position?: number | null;
+  createdAt?: string | null;
+}
+
+export interface TimeEntry {
+  id: string;
+  taskId: string;
+  projectId: string;
+  minutes: number;
+  note?: string | null;
+  userId?: string | null;
+  spentOn?: string | null;
+}
+
+export function taskStatusById(id: string): Status | undefined {
+  return TASK_STATUSES.find((s) => s.id === id);
+}
+
+export function isValidTaskStatus(id: string): boolean {
+  return TASK_STATUSES.some((s) => s.id === id);
+}
+
+export function isValidProjectStatus(id: string): boolean {
+  return PROJECT_STATUSES.some((s) => s.id === id);
+}
+
+export function isOpen(task: { status: string }): boolean {
+  return !taskStatusById(task.status)?.terminal;
+}
+
+export interface Column {
+  status: Status;
+  tasks: Task[];
+}
+
+/** Group a project's tasks into board columns, in their manual order. */
+export function groupByStatus(tasks: Task[]): Column[] {
+  return TASK_STATUSES.map((status) => ({
+    status,
+    tasks: tasks
+      .filter((task) => task.status === status.id)
+      .sort(
+        (a, b) =>
+          (Number(a.position) || 0) - (Number(b.position) || 0) ||
+          (a.createdAt ?? "").localeCompare(b.createdAt ?? ""),
+      ),
+  }));
+}
+
+/** Minutes logged against one task. */
+export function minutesForTask(taskId: string, entries: TimeEntry[]): number {
+  let total = 0;
+  for (const entry of entries) {
+    if (entry.taskId !== taskId) continue;
+    const minutes = Number(entry.minutes);
+    if (Number.isFinite(minutes)) total += Math.trunc(minutes);
+  }
+  return total;
+}
+
+/**
+ * Minutes per task in one pass — a board calling minutesForTask per card would
+ * be O(tasks × entries).
+ */
+export function minutesByTask(entries: TimeEntry[]): Map<string, number> {
+  const totals = new Map<string, number>();
+  for (const entry of entries) {
+    const minutes = Number(entry.minutes);
+    if (!Number.isFinite(minutes)) continue;
+    totals.set(entry.taskId, (totals.get(entry.taskId) ?? 0) + Math.trunc(minutes));
+  }
+  return totals;
+}
+
+export function minutesForProject(projectId: string, entries: TimeEntry[]): number {
+  let total = 0;
+  for (const entry of entries) {
+    if (entry.projectId !== projectId) continue;
+    const minutes = Number(entry.minutes);
+    if (Number.isFinite(minutes)) total += Math.trunc(minutes);
+  }
+  return total;
+}
+
+export interface Progress {
+  total: number;
+  done: number;
+  /** 0–1, or null when there's nothing to measure. */
+  ratio: number | null;
+}
+
+/**
+ * Progress by task COUNT, not by logged time.
+ *
+ * Time spent measures effort, not completion — a project can be 90% through its
+ * budget and 20% done, and conflating them is how a status report lies.
+ * `budgetState` reports the other half separately.
+ */
+export function progress(tasks: Task[]): Progress {
+  const total = tasks.length;
+  const done = tasks.filter((task) => !isOpen(task)).length;
+  return { total, done, ratio: total === 0 ? null : done / total };
+}
+
+export type BudgetState = "none" | "ok" | "near" | "over";
+
+/** Where a project sits against its agreed budget. */
+export function budgetState(
+  budgetMinutes: number | null | undefined,
+  loggedMinutes: number,
+): BudgetState {
+  const budget = Number(budgetMinutes);
+  if (!Number.isFinite(budget) || budget <= 0) return "none";
+  if (loggedMinutes > budget) return "over";
+  // 85% is where you can still do something about it.
+  if (loggedMinutes >= budget * 0.85) return "near";
+  return "ok";
+}
+
+/** What the logged time is worth at the project's rate. */
+export function billableCents(
+  minutes: number,
+  hourlyRateCents: number | null | undefined,
+): number {
+  const rate = Number(hourlyRateCents) || 0;
+  return Math.round((minutes * rate) / 60);
+}
+
+/** "7h 30m" / "45m" / "0m" — the format a timesheet is read in. */
+export function duration(minutes: number | null | undefined): string {
+  const value = Math.trunc(Number(minutes) || 0);
+  const sign = value < 0 ? "-" : "";
+  const abs = Math.abs(value);
+  const hours = Math.floor(abs / 60);
+  const rest = abs % 60;
+  if (hours === 0) return `${sign}${rest}m`;
+  if (rest === 0) return `${sign}${hours}h`;
+  return `${sign}${hours}h ${rest}m`;
+}
+
+export function money(cents: number | null | undefined): string {
+  const value = Number(cents) || 0;
+  const sign = value < 0 ? "-" : "";
+  const abs = Math.abs(value);
+  const dollars = Math.floor(abs / 100).toLocaleString("en-US");
+  const rest = String(abs % 100).padStart(2, "0");
+  return `${sign}$${dollars}.${rest}`;
+}
+
+/**
+ * Parse typed time into minutes. Accepts "90", "1.5h", "1h30", "1h 30m", "45m".
+ *
+ * People write time however they think of it, and rejecting "1h30" because it
+ * isn't "90" is the kind of friction that stops time being logged at all —
+ * which costs far more than a lenient parser.
+ */
+export function parseDuration(input: string): number | null {
+  const text = input.trim().toLowerCase().replace(/\s+/g, "");
+  if (!text) return null;
+
+  // "1h30" / "1h30m" / "2h" / "45m"
+  const hm = text.match(/^(\d+(?:\.\d+)?)h(?:(\d+)m?)?$/);
+  if (hm) {
+    const hours = Number(hm[1]);
+    const mins = hm[2] ? Number(hm[2]) : 0;
+    if (!Number.isFinite(hours) || !Number.isFinite(mins) || mins >= 60) return null;
+    return Math.round(hours * 60 + mins);
+  }
+
+  const m = text.match(/^(\d+)m$/);
+  if (m) return Number(m[1]);
+
+  // A bare number is minutes — the unit a timesheet field is usually in.
+  if (/^\d+(\.\d+)?$/.test(text)) {
+    const value = Number(text);
+    return Number.isFinite(value) ? Math.round(value) : null;
+  }
+
+  return null;
+}

package/templates/projects/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "__APP_NAME_KEBAB__",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "pylon dev",
+    "deploy": "pylon deploy",
+    "check": "tsc --noEmit",
+    "test": "pylon test"
+  },
+  "dependencies": {
+    "@pylonsync/react": "^__PYLON_VERSION__",
+    "@pylonsync/sdk": "^__PYLON_VERSION__",
+    "@pylonsync/functions": "^__PYLON_VERSION__",
+    "@pylonsync/client": "^__PYLON_VERSION__",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "tailwindcss": "^4.3.0",
+    "@tailwindcss/cli": "^4.3.0",
+    "tw-animate-css": "^1.2.0",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "tailwind-merge": "^2.5.0",
+    "lucide-react": "^0.460.0",
+    "@radix-ui/react-dialog": "^1.1.4",
+    "@radix-ui/react-slot": "^1.1.0"
+  },
+  "devDependencies": {
+    "@happy-dom/global-registrator": "^20.10.0",
+    "@pylonsync/cli": "^__PYLON_VERSION__",
+    "@testing-library/dom": "^10.4.0",
+    "@testing-library/react": "^16.3.0",
+    "@types/node": "^22.0.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "typescript": "^5.6.0"
+  }
+}

package/templates/projects/tests/components.test.tsx

@@ -0,0 +1,200 @@
+import { afterEach, describe, expect, test } from "bun:test";
+// This project uses the classic JSX transform, so .tsx tests import React.
+import React from "react";
+import { cleanup, fireEvent, render, screen, within } from "@testing-library/react";
+import { TaskBoard } from "../components/task-board";
+import { TimeDialog } from "../components/time-dialog";
+import { BudgetBar } from "../components/budget-bar";
+import type { Task } from "../lib/work";
+
+afterEach(cleanup);
+
+// Tier 2: components. No mocking needed — they take data as props and report
+// changes through callbacks, because the container owns `db`.
+
+const tasks: Task[] = [
+  { id: "t1", projectId: "p1", title: "Dispatcher board UI", status: "doing" },
+  { id: "t2", projectId: "p1", title: "Weekly report", status: "todo" },
+];
+
+const noName = () => null;
+const noMinutes = () => 0;
+
+describe("TaskBoard", () => {
+  test("renders every column", () => {
+    render(
+      <TaskBoard
+        tasks={tasks}
+        assigneeName={noName}
+        minutesFor={noMinutes}
+        onMove={() => {}}
+        onOpen={() => {}}
+      />,
+    );
+    for (const label of ["To do", "In progress", "Review", "Done"]) {
+      expect(screen.getByLabelText(label)).toBeDefined();
+    }
+  });
+
+  test("dropping on another column reports the move", () => {
+    const moves: Array<[string, string]> = [];
+    render(
+      <TaskBoard
+        tasks={tasks}
+        assigneeName={noName}
+        minutesFor={noMinutes}
+        onMove={(id, status) => moves.push([id, status])}
+        onOpen={() => {}}
+      />,
+    );
+    const data = new Map<string, string>();
+    const dataTransfer = {
+      setData: (k: string, v: string) => data.set(k, v),
+      getData: (k: string) => data.get(k) ?? "",
+      effectAllowed: "",
+      dropEffect: "",
+    };
+    fireEvent.dragStart(screen.getByText("Weekly report"), { dataTransfer });
+    fireEvent.drop(screen.getByLabelText("Done"), { dataTransfer });
+    expect(moves).toEqual([["t2", "done"]]);
+  });
+
+  test("dropping back on the same column writes nothing", () => {
+    const moves: unknown[] = [];
+    render(
+      <TaskBoard
+        tasks={tasks}
+        assigneeName={noName}
+        minutesFor={noMinutes}
+        onMove={() => moves.push(1)}
+        onOpen={() => {}}
+      />,
+    );
+    const data = new Map<string, string>();
+    const dataTransfer = {
+      setData: (k: string, v: string) => data.set(k, v),
+      getData: (k: string) => data.get(k) ?? "",
+      effectAllowed: "",
+      dropEffect: "",
+    };
+    fireEvent.dragStart(screen.getByText("Weekly report"), { dataTransfer });
+    fireEvent.drop(screen.getByLabelText("To do"), { dataTransfer });
+    expect(moves).toEqual([]);
+  });
+
+  test("shows a column's logged total", () => {
+    render(
+      <TaskBoard
+        tasks={tasks}
+        assigneeName={noName}
+        minutesFor={(id) => (id === "t1" ? 600 : 0)}
+        onMove={() => {}}
+        onOpen={() => {}}
+      />,
+    );
+    expect(within(screen.getByLabelText("In progress")).getAllByText("10h").length)
+      .toBeGreaterThan(0);
+  });
+
+  test("flags a card that has blown its estimate", () => {
+    // Showing "3h / 8h" on every card is noise; an overrun is worth seeing.
+    render(
+      <TaskBoard
+        tasks={[{ ...tasks[0], estimateMinutes: 120 }]}
+        assigneeName={noName}
+        minutesFor={() => 300}
+        onMove={() => {}}
+        onOpen={() => {}}
+      />,
+    );
+    expect(screen.getByText("5h / 2h")).toBeDefined();
+  });
+
+  test("opening a card reports the task id", () => {
+    const opened: string[] = [];
+    render(
+      <TaskBoard
+        tasks={tasks}
+        assigneeName={noName}
+        minutesFor={noMinutes}
+        onMove={() => {}}
+        onOpen={(id) => opened.push(id)}
+      />,
+    );
+    fireEvent.click(screen.getByText("Dispatcher board UI"));
+    expect(opened).toEqual(["t1"]);
+  });
+});
+
+describe("TimeDialog", () => {
+  test("accepts the formats people actually type", () => {
+    const logged: number[] = [];
+    render(
+      <TimeDialog
+        open
+        taskTitle="Dispatcher board UI"
+        onOpenChange={() => {}}
+        onLog={(minutes) => logged.push(minutes)}
+      />,
+    );
+    fireEvent.change(screen.getByLabelText("Time"), { target: { value: "1h30" } });
+    fireEvent.click(screen.getByRole("button", { name: /log time/i }));
+    expect(logged).toEqual([90]);
+  });
+
+  test("previews what it parsed, so a typo is visible before submitting", () => {
+    render(
+      <TimeDialog open taskTitle="X" onOpenChange={() => {}} onLog={() => {}} />,
+    );
+    fireEvent.change(screen.getByLabelText("Time"), { target: { value: "90" } });
+    expect(screen.getByText("1h 30m")).toBeDefined();
+  });
+
+  test("refuses an unparseable value", () => {
+    const logged: number[] = [];
+    render(
+      <TimeDialog open taskTitle="X" onOpenChange={() => {}} onLog={(m) => logged.push(m)} />,
+    );
+    fireEvent.change(screen.getByLabelText("Time"), { target: { value: "soon" } });
+    fireEvent.click(screen.getByRole("button", { name: /log time/i }));
+    expect(logged).toEqual([]);
+    expect(screen.getByText(/try 90/i)).toBeDefined();
+  });
+
+  test("refuses more than a day", () => {
+    // A typo on a timesheet becomes a typo on an invoice.
+    const logged: number[] = [];
+    render(
+      <TimeDialog open taskTitle="X" onOpenChange={() => {}} onLog={(m) => logged.push(m)} />,
+    );
+    fireEvent.change(screen.getByLabelText("Time"), { target: { value: "30h" } });
+    fireEvent.click(screen.getByRole("button", { name: /log time/i }));
+    expect(logged).toEqual([]);
+  });
+
+  test("renders nothing when closed", () => {
+    const { container } = render(
+      <TimeDialog open={false} taskTitle="X" onOpenChange={() => {}} onLog={() => {}} />,
+    );
+    expect(container.firstChild).toBeNull();
+  });
+});
+
+describe("BudgetBar", () => {
+  test("calls out an overrun with the amount", () => {
+    render(<BudgetBar budgetMinutes={2400} loggedMinutes={2760} />);
+    expect(screen.getByText(/over budget by 6h/i)).toBeDefined();
+  });
+
+  test("shows billable value when there's a rate", () => {
+    render(
+      <BudgetBar budgetMinutes={2400} loggedMinutes={600} hourlyRateCents={16_500} />,
+    );
+    expect(screen.getByText(/\$1,650\.00 billable/)).toBeDefined();
+  });
+
+  test("says so when there's no budget rather than drawing an empty bar", () => {
+    render(<BudgetBar budgetMinutes={0} loggedMinutes={600} />);
+    expect(screen.getByText("No budget set")).toBeDefined();
+  });
+});

package/templates/projects/tests/search.test.ts

@@ -0,0 +1,83 @@
+import { describe, expect, test } from "bun:test";
+import { moveSelection, searchItems, type SearchItem } from "../lib/search";
+
+const items: SearchItem[] = [
+  { id: "1", type: "company", title: "Acme Inc", subtitle: "acme.com", href: "/c" },
+  {
+    id: "2",
+    type: "company",
+    title: "Acme Corporation Holdings",
+    subtitle: "acmeholdings.com",
+    href: "/c",
+  },
+  {
+    id: "3",
+    type: "contact",
+    title: "Dana Whitfield",
+    subtitle: "Northwind Logistics",
+    href: "/p",
+    keywords: "dana@northwind.co VP Operations",
+  },
+  { id: "4", type: "deal", title: "Fleet dispatch rollout", href: "/d" },
+];
+
+const titles = (q: string) => searchItems(items, q).map((i) => i.title);
+
+describe("searchItems", () => {
+  test("an empty query lists everything", () => {
+    expect(searchItems(items, "").length).toBe(items.length);
+    expect(searchItems(items, "   ").length).toBe(items.length);
+  });
+
+  test("prefix beats substring", () => {
+    expect(titles("acme")[0]).toBe("Acme Inc");
+  });
+
+  test("the shorter title wins a tie", () => {
+    // Both start with "Acme"; the more specific record should come first.
+    expect(titles("acme")).toEqual(["Acme Inc", "Acme Corporation Holdings"]);
+  });
+
+  test("matches a word inside the title", () => {
+    expect(titles("dispatch")).toContain("Fleet dispatch rollout");
+  });
+
+  test("matches the subtitle and hidden keywords", () => {
+    expect(titles("northwind")).toContain("Dana Whitfield");
+    expect(titles("dana@northwind.co")).toContain("Dana Whitfield");
+    expect(titles("VP")).toContain("Dana Whitfield");
+  });
+
+  test("is case-insensitive", () => {
+    expect(titles("ACME").length).toBe(2);
+  });
+
+  test("no match is empty, not everything", () => {
+    expect(titles("zzzz")).toEqual([]);
+  });
+
+  test("respects the limit", () => {
+    expect(searchItems(items, "", 2)).toHaveLength(2);
+  });
+
+  test("a word-boundary hit beats a mid-word one", () => {
+    const rows: SearchItem[] = [
+      { id: "a", type: "deal", title: "Broadcasting", href: "/" },
+      { id: "b", type: "deal", title: "New cast list", href: "/" },
+    ];
+    expect(searchItems(rows, "cast").map((r) => r.title)[0]).toBe("New cast list");
+  });
+});
+
+describe("moveSelection", () => {
+  test("wraps at both ends", () => {
+    expect(moveSelection(0, -1, 3)).toBe(2);
+    expect(moveSelection(2, 1, 3)).toBe(0);
+    expect(moveSelection(0, 1, 3)).toBe(1);
+  });
+
+  test("an empty list stays at zero rather than going negative", () => {
+    expect(moveSelection(0, 1, 0)).toBe(0);
+    expect(moveSelection(0, -1, 0)).toBe(0);
+  });
+});

package/templates/projects/tests/setup.ts

@@ -0,0 +1,5 @@
+import { GlobalRegistrator } from "@happy-dom/global-registrator";
+
+// Make document/window available so @testing-library/react can render. Loaded
+// via bunfig.toml's [test] preload, before any test file runs.
+GlobalRegistrator.register();