@flaredev/cli 0.2.0 → 0.4.0

package/templates/app/components/dashboard/inline-cell.tsx

@@ -0,0 +1,165 @@
+"use client";
+
+import { useEffect, useRef, useState, useTransition } from "react";
+import { useRouter } from "next/navigation";
+import { CheckIcon, ChevronDownIcon, PencilIcon, XIcon } from "lucide-react";
+import { toast } from "sonner";
+import { optionLabel, type StoredField } from "@flaredev/core";
+import { updateRecordAction } from "@/app/dashboard/actions";
+import { Button } from "@/components/ui/button";
+import { Input } from "@/components/ui/input";
+import { Select, SelectContent, SelectGroup, SelectItem, SelectTrigger, SelectValue } from "@/components/ui/select";
+import { Spinner } from "@/components/ui/spinner";
+import { Switch } from "@/components/ui/switch";
+import { cn } from "@/lib/utils";
+
+interface Props {
+  resourceName: string;
+  id: string;
+  fieldKey: string;
+  def: StoredField & { label: string };
+  value: unknown;
+  /** What the cell shows when it isn't being edited. */
+  children: React.ReactNode;
+}
+
+const NONE = "__none__";
+
+/**
+ * Edit one value without leaving the table.
+ *
+ * For the small changes — a status, a flag, a number — opening a form to change one
+ * field and closing it again is most of the work. Anything with a picker, an upload or
+ * a relation still goes through the form, where there's room to explain itself.
+ */
+export function InlineCell({ resourceName, id, fieldKey, def, value, children }: Props) {
+  const router = useRouter();
+  const [editing, setEditing] = useState(false);
+  const [draft, setDraft] = useState("");
+  const [pending, startTransition] = useTransition();
+  const input = useRef<HTMLInputElement>(null);
+
+  useEffect(() => {
+    if (editing) input.current?.focus();
+  }, [editing]);
+
+  const save = (next: unknown) => {
+    setEditing(false);
+    if (next === value || (next === null && value === null)) return;
+    startTransition(async () => {
+      const result = await updateRecordAction(resourceName, id, { [fieldKey]: next });
+      if (!result.ok) {
+        toast.error(result.issues?.[0]?.message ?? result.error);
+        return;
+      }
+      toast.success(`${def.label} saved.`);
+      router.refresh();
+    });
+  };
+
+  if (pending) {
+    return (
+      <span className="inline-flex items-center gap-2 text-muted-foreground">
+        <Spinner className="size-3.5" />
+        {children}
+      </span>
+    );
+  }
+
+  // A switch and a select are one click either way, so they're always live.
+  if (def.kind === "boolean") {
+    return (
+      <Switch
+        checked={value === true}
+        onCheckedChange={(checked) => save(checked)}
+        aria-label={`${def.label} for this record`}
+        className="data-[state=unchecked]:bg-muted-foreground/30"
+      />
+    );
+  }
+
+  if (def.kind === "enum") {
+    // The badge stays until it's clicked: a row of grey dropdowns loses the colour that
+    // makes a status column readable at a glance.
+    if (!editing) {
+      return (
+        <button
+          type="button"
+          onClick={() => setEditing(true)}
+          className="group/cell inline-flex items-center gap-1 rounded px-0.5 focus-visible:outline-2 focus-visible:outline-offset-1 focus-visible:outline-primary"
+          aria-label={`Change ${def.label.toLowerCase()}`}
+        >
+          {children}
+          <ChevronDownIcon className="size-3 shrink-0 text-muted-foreground opacity-0 transition-opacity group-hover/cell:opacity-100" aria-hidden="true" />
+        </button>
+      );
+    }
+    return (
+      <Select
+        defaultOpen
+        value={typeof value === "string" ? value : NONE}
+        onValueChange={(next) => save(next === NONE ? null : next)}
+        onOpenChange={(open) => {
+          if (!open) setEditing(false);
+        }}
+      >
+        <SelectTrigger size="sm" className="h-7 w-auto px-1.5" aria-label={def.label}>
+          <SelectValue placeholder="—" />
+        </SelectTrigger>
+        <SelectContent>
+          <SelectGroup>
+            {!def.required && <SelectItem value={NONE}>—</SelectItem>}
+            {def.options.map((option) => (
+              <SelectItem key={option} value={option}>
+                {optionLabel(def, option)}
+              </SelectItem>
+            ))}
+          </SelectGroup>
+        </SelectContent>
+      </Select>
+    );
+  }
+
+  if (editing) {
+    const numeric = def.kind === "int" || def.kind === "float";
+    return (
+      <span className="flex items-center gap-1">
+        <Input
+          ref={input}
+          value={draft}
+          onChange={(event) => setDraft(event.target.value)}
+          type={numeric ? "number" : "text"}
+          step={def.kind === "float" ? "any" : undefined}
+          className="h-7 w-full min-w-24 px-1.5"
+          aria-label={def.label}
+          onKeyDown={(event) => {
+            if (event.key === "Enter") save(numeric ? (draft === "" ? null : Number(draft)) : draft);
+            if (event.key === "Escape") setEditing(false);
+          }}
+          onBlur={() => save(numeric ? (draft === "" ? null : Number(draft)) : draft)}
+        />
+        <Button variant="ghost" size="icon" className="size-6" aria-label="Save" onMouseDown={(event) => event.preventDefault()}>
+          <CheckIcon />
+        </Button>
+        <Button variant="ghost" size="icon" className="size-6" aria-label="Cancel" onMouseDown={(event) => { event.preventDefault(); setEditing(false); }}>
+          <XIcon />
+        </Button>
+      </span>
+    );
+  }
+
+  return (
+    <button
+      type="button"
+      onClick={() => {
+        setDraft(value === null || value === undefined ? "" : String(value));
+        setEditing(true);
+      }}
+      className={cn("group/cell inline-flex max-w-full items-center gap-1.5 rounded px-1 py-0.5 text-left hover:bg-muted", "focus-visible:outline-2 focus-visible:outline-offset-1 focus-visible:outline-primary")}
+      aria-label={`Edit ${def.label.toLowerCase()}`}
+    >
+      <span className="truncate">{children}</span>
+      <PencilIcon className="size-3 shrink-0 text-muted-foreground opacity-0 transition-opacity group-hover/cell:opacity-100" aria-hidden="true" />
+    </button>
+  );
+}

package/templates/app/components/dashboard/local-time.tsx

@@ -0,0 +1,77 @@
+"use client";
+
+import { useEffect, useState } from "react";
+
+/**
+ * A timestamp in the reader's own timezone.
+ *
+ * Pages render on a Worker, where the clock is UTC, so a date formatted on the server is
+ * in the wrong timezone for everyone. The server's version is rendered first (so the
+ * markup isn't empty and search engines see something), then the browser replaces it
+ * with its own once it's running.
+ */
+export function LocalTime({
+  value,
+  dateStyle = "medium",
+  timeStyle = "short",
+  className,
+}: {
+  /** Milliseconds, an ISO string, or a Date. */
+  value: number | string | Date | null | undefined;
+  dateStyle?: Intl.DateTimeFormatOptions["dateStyle"];
+  timeStyle?: Intl.DateTimeFormatOptions["timeStyle"];
+  className?: string;
+}) {
+  const date = value === null || value === undefined ? null : value instanceof Date ? value : new Date(value);
+  const utc = date ? new Intl.DateTimeFormat("en-GB", { dateStyle, timeStyle, timeZone: "UTC" }).format(date) : "—";
+  const [text, setText] = useState(utc);
+
+  useEffect(() => {
+    if (!date) return;
+    setText(new Intl.DateTimeFormat(undefined, { dateStyle, timeStyle }).format(date));
+  }, [date?.getTime(), dateStyle, timeStyle]);
+
+  if (!date) return <span className={className}>—</span>;
+  return (
+    <time dateTime={date.toISOString()} title={date.toISOString()} className={className} suppressHydrationWarning>
+      {text}
+    </time>
+  );
+}
+
+/** "3 minutes ago", "yesterday", falling back to a date once it's a week old. */
+export function RelativeTime({ value, className }: { value: number | string | Date | null | undefined; className?: string }) {
+  const date = value === null || value === undefined ? null : value instanceof Date ? value : new Date(value);
+  const [text, setText] = useState<string | null>(null);
+
+  useEffect(() => {
+    if (!date) return;
+    const format = () => {
+      const seconds = Math.round((date.getTime() - Date.now()) / 1000);
+      const relative = new Intl.RelativeTimeFormat(undefined, { numeric: "auto" });
+      const units: [Intl.RelativeTimeFormatUnit, number][] = [
+        ["second", 60],
+        ["minute", 60],
+        ["hour", 24],
+        ["day", 7],
+      ];
+      let value = seconds;
+      for (const [unit, size] of units) {
+        if (Math.abs(value) < size) return relative.format(Math.round(value), unit);
+        value /= size;
+      }
+      return new Intl.DateTimeFormat(undefined, { dateStyle: "medium" }).format(date);
+    };
+    setText(format());
+    // Re-read every half minute, so "just now" doesn't stay "just now" all afternoon.
+    const timer = setInterval(() => setText(format()), 30_000);
+    return () => clearInterval(timer);
+  }, [date?.getTime()]);
+
+  if (!date) return <span className={className}>—</span>;
+  return (
+    <time dateTime={date.toISOString()} title={date.toISOString()} className={className} suppressHydrationWarning>
+      {text ?? new Intl.DateTimeFormat("en-GB", { dateStyle: "medium", timeZone: "UTC" }).format(date)}
+    </time>
+  );
+}

package/templates/app/components/dashboard/page-header.tsx

@@ -0,0 +1,57 @@
+import Link from "next/link";
+import { ChevronRightIcon } from "lucide-react";
+import { cn } from "@/lib/utils";
+
+export interface Crumb {
+  label: string;
+  href?: string;
+}
+
+/**
+ * The top of every dashboard page: where you are, what this page is, and what you can
+ * do here. Every page uses it, so they all line up.
+ */
+export function PageHeader({
+  title,
+  description,
+  crumbs = [],
+  actions,
+  className,
+}: {
+  title: React.ReactNode;
+  description?: React.ReactNode;
+  crumbs?: Crumb[];
+  /** Buttons for this page, right-aligned on a wide screen and below the title on a phone. */
+  actions?: React.ReactNode;
+  className?: string;
+}) {
+  return (
+    <div className={cn("flex flex-col gap-3", className)}>
+      {crumbs.length > 0 && (
+        <nav aria-label="Breadcrumb">
+          <ol className="flex flex-wrap items-center gap-1 text-sm text-muted-foreground">
+            {crumbs.map((crumb, index) => (
+              <li key={`${crumb.label}-${index}`} className="flex items-center gap-1">
+                {index > 0 && <ChevronRightIcon className="size-3.5 opacity-60" aria-hidden="true" />}
+                {crumb.href ? (
+                  <Link href={crumb.href} className="hover:text-foreground">
+                    {crumb.label}
+                  </Link>
+                ) : (
+                  <span aria-current="page">{crumb.label}</span>
+                )}
+              </li>
+            ))}
+          </ol>
+        </nav>
+      )}
+      <div className="flex flex-col gap-3 sm:flex-row sm:items-start sm:justify-between">
+        <div className="flex flex-col gap-1">
+          <h1 className="text-2xl font-semibold tracking-tight">{title}</h1>
+          {description && <p className="text-sm text-muted-foreground">{description}</p>}
+        </div>
+        {actions && <div className="flex flex-wrap items-center gap-2">{actions}</div>}
+      </div>
+    </div>
+  );
+}

package/templates/app/components/{admin → dashboard}/query.ts

@@ -19,7 +19,9 @@ export function hrefWith(path: string, current: URLSearchParams, changes: Record
     if (value === null || value === "") next.delete(key);
     else next.set(key, value);
   }
+  // A cursor belongs to the query that produced it, so changing anything else drops it.
   if (!("page" in changes)) next.delete("page");
+  if (!("cursor" in changes)) next.delete("cursor");
   const query = next.toString();
   return query ? `${path}?${query}` : path;
 }

package/templates/app/components/dashboard/record-actions.tsx

@@ -0,0 +1,113 @@
+"use client";
+
+import Link from "next/link";
+import { useRouter } from "next/navigation";
+import { useState, useTransition } from "react";
+import { PencilIcon, Trash2Icon } from "lucide-react";
+import { toast } from "sonner";
+import type { Resource } from "@flaredev/core";
+import { deleteRecordAction } from "@/app/dashboard/actions";
+import {
+  AlertDialog,
+  AlertDialogCancel,
+  AlertDialogContent,
+  AlertDialogDescription,
+  AlertDialogFooter,
+  AlertDialogHeader,
+  AlertDialogTitle,
+} from "@/components/ui/alert-dialog";
+import { Button } from "@/components/ui/button";
+import { Spinner } from "@/components/ui/spinner";
+import { ResourceFormDialog, type FormRelations } from "./resource-form-dialog";
+
+interface Props {
+  resource: Resource;
+  id: string;
+  record: Record<string, unknown>;
+  relations: FormRelations;
+  listHref: string;
+  editHref: string;
+  canUpdate: boolean;
+  canDelete: boolean;
+  /** Whether editing opens a dialog (site.dashboard.forms) or goes to the form page. */
+  modalForms: boolean;
+}
+
+/** Edit and delete, at the top of a record's own page. Deleting goes back to the list. */
+export function RecordActions({ resource, id, record, relations, listHref, editHref, canUpdate, canDelete, modalForms }: Props) {
+  const router = useRouter();
+  const [editing, setEditing] = useState(false);
+  const [confirming, setConfirming] = useState(false);
+  const [pending, startTransition] = useTransition();
+
+  const remove = () => {
+    startTransition(async () => {
+      const result = await deleteRecordAction(resource.name, id);
+      if (!result.ok) {
+        toast.error(result.error);
+        return;
+      }
+      toast.success(`${resource.label} deleted.`);
+      // The record this page is about is gone, so the list is the only place left to be.
+      router.push(listHref);
+      router.refresh();
+    });
+  };
+
+  return (
+    <>
+      {canUpdate &&
+        (modalForms ? (
+          <Button variant="outline" onClick={() => setEditing(true)}>
+            <PencilIcon data-icon="inline-start" />
+            Edit
+          </Button>
+        ) : (
+          <Button variant="outline" asChild>
+            <Link href={editHref}>
+              <PencilIcon data-icon="inline-start" />
+              Edit
+            </Link>
+          </Button>
+        ))}
+      {canDelete && (
+        <Button variant="outline" className="text-destructive hover:text-destructive" onClick={() => setConfirming(true)}>
+          <Trash2Icon data-icon="inline-start" />
+          Delete
+        </Button>
+      )}
+
+      {canUpdate && modalForms && (
+        <ResourceFormDialog
+          resource={resource}
+          relations={relations}
+          listHref={listHref}
+          mode="edit"
+          id={id}
+          record={record}
+          open={editing}
+          onOpenChange={(open) => {
+            setEditing(open);
+            if (!open) router.refresh();
+          }}
+        />
+      )}
+
+      <AlertDialog open={confirming} onOpenChange={setConfirming}>
+        <AlertDialogContent>
+          <AlertDialogHeader>
+            <AlertDialogTitle>Delete this {resource.label.toLowerCase()}?</AlertDialogTitle>
+            <AlertDialogDescription>This can&apos;t be undone. Anything that belongs to it may be deleted too.</AlertDialogDescription>
+          </AlertDialogHeader>
+          <AlertDialogFooter>
+            <AlertDialogCancel disabled={pending}>Keep it</AlertDialogCancel>
+            <Button variant="destructive" onClick={remove} disabled={pending}>
+              {pending && <Spinner data-icon="inline-start" />}
+              Delete
+            </Button>
+          </AlertDialogFooter>
+        </AlertDialogContent>
+      </AlertDialog>
+    </>
+  );
+}

package/templates/app/components/dashboard/record-detail.tsx

@@ -0,0 +1,200 @@
+import Link from "next/link";
+import { notFound } from "next/navigation";
+import { formatValue, optionLabel, relationGraph, statusTone, storedFields, type Resource } from "@flaredev/core";
+import { Badge } from "@/components/ui/badge";
+import { Button } from "@/components/ui/button";
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@/components/ui/card";
+import { recentAudit } from "@/lib/audit";
+import { adminPermissions, allResources, dashboardStore, requireAccess, resourcePath } from "@/lib/dashboard";
+import { site } from "@/lib/site";
+import { LocalTime } from "./local-time";
+import { PageHeader } from "./page-header";
+import { RecordActions } from "./record-actions";
+import type { RelationMeta } from "./fields/field-widget";
+
+/** How many of a record's children to show before pointing at the filtered list. */
+const RELATED_LIMIT = 5;
+
+/**
+ * One record: its fields, what belongs to it, and what's been done to it.
+ *
+ * A row in a table is a summary; this is the page you send someone when you want them
+ * to look at the thing itself.
+ */
+export async function RecordDetail({ resource, id }: { resource: Resource; id: string }) {
+  await requireAccess(resource, "read");
+  const store = dashboardStore(resource.name);
+  const result = await store.get(id);
+  if (!result.ok) notFound();
+  const record = result.data;
+  const permissions = await adminPermissions(resource.name);
+
+  const all = allResources();
+  const byName = new Map(all.map((item) => [item.name, item]));
+  const fields = storedFields(resource);
+
+  // Relation titles, so a belongsTo reads as a name rather than an id.
+  const relationTitles: Record<string, string> = {};
+  const relations: Record<string, RelationMeta & { initialTitle?: string }> = {};
+  for (const [key, def] of fields) {
+    if (def.kind !== "belongsTo") continue;
+    const target = byName.get(def.target);
+    if (!target) continue;
+    relations[key] = { name: target.name, label: target.label, pluralLabel: target.pluralLabel, slug: target.slug, titleField: target.titleField };
+    const value = record[key];
+    if (typeof value === "string") {
+      const titles = await dashboardStore(target.name).titles([value]);
+      const title = titles[value];
+      if (title) relationTitles[key] = title;
+    }
+  }
+
+  // Children: resources with a belongsTo pointing back here.
+  const graph = relationGraph(all);
+  const children = (graph.byResource[resource.name]?.hasMany ?? []).flatMap((relation) => {
+    const target = byName.get(relation.target);
+    return target ? [{ relation, target }] : [];
+  });
+  const related = await Promise.all(
+    children.map(async ({ relation, target }) => {
+      const params = new URLSearchParams({ perPage: String(RELATED_LIMIT), [`filter[${relation.foreignKey}]`]: id });
+      const list = await dashboardStore(target.name).list(params);
+      return { relation, target, rows: list.ok ? list.data.data : [], total: list.ok ? list.data.meta.total : 0, filterKey: relation.foreignKey };
+    }),
+  );
+
+  const history = await recentAudit(10, resource.name);
+  const forThisRecord = history.filter((entry) => entry.recordId === id);
+
+  const titleDef = resource.fields[resource.titleField];
+  const title = titleDef && titleDef.kind !== "hasMany" ? String(formatValue(titleDef, record[resource.titleField]) || id) : id;
+
+  return (
+    <>
+      <PageHeader
+        title={title}
+        description={<>Created <LocalTime value={record.createdAt as string | number | Date} /></>}
+        crumbs={[
+          { label: "Dashboard", href: "/dashboard" },
+          { label: resource.pluralLabel, href: resourcePath(resource) },
+          { label: title },
+        ]}
+        actions={
+          <RecordActions
+            resource={resource}
+            id={id}
+            record={record}
+            relations={relations}
+            listHref={resourcePath(resource)}
+            editHref={resourcePath(resource, id, "edit")}
+            canUpdate={permissions.update}
+            canDelete={permissions.delete}
+            modalForms={site.dashboard.forms === "modal"}
+          />
+        }
+      />
+
+      <div className="grid gap-6 lg:grid-cols-[minmax(0,1.6fr)_minmax(0,1fr)]">
+        <Card>
+          <CardHeader>
+            <CardTitle className="text-base">Details</CardTitle>
+          </CardHeader>
+          <CardContent className="grid gap-x-8 gap-y-4 sm:grid-cols-2">
+            {fields.map(([key, def]) => {
+              const value = record[key];
+              let content: React.ReactNode = formatValue(def, value);
+              if ((def.kind === "datetime") && value != null) {
+                content = <LocalTime value={value as string | number | Date} />;
+              } else if (def.kind === "enum" && value != null) {
+                const tone = statusTone(value);
+                content = <Badge variant={tone === "neutral" ? "secondary" : tone}>{content}</Badge>;
+              } else if (def.kind === "multiselect" && Array.isArray(value) && value.length > 0) {
+                content = (
+                  <span className="flex flex-wrap gap-1">
+                    {value.map((item) => (
+                      <Badge key={String(item)} variant="secondary">
+                        {optionLabel(def, String(item))}
+                      </Badge>
+                    ))}
+                  </span>
+                );
+              } else if (def.kind === "belongsTo" && typeof value === "string") {
+                const target = byName.get(def.target);
+                content = target ? (
+                  <Link href={resourcePath(target, value)} className="text-primary hover:underline">
+                    {relationTitles[key] ?? value}
+                  </Link>
+                ) : (
+                  value
+                );
+              }
+              return (
+                <div key={key} className={def.kind === "text" ? "flex flex-col gap-1 sm:col-span-2" : "flex flex-col gap-1"}>
+                  <dt className="text-xs text-muted-foreground">{def.label}</dt>
+                  <dd className="text-sm break-words">{content}</dd>
+                </div>
+              );
+            })}
+          </CardContent>
+        </Card>
+
+        <div className="flex flex-col gap-6">
+          <Card>
+            <CardHeader>
+              <CardTitle className="text-base">History</CardTitle>
+              <CardDescription>What's been done to this {resource.label.toLowerCase()}.</CardDescription>
+            </CardHeader>
+            <CardContent className="flex flex-col">
+              {forThisRecord.length === 0 ? (
+                <p className="text-sm text-muted-foreground">Nothing since the audit log started.</p>
+              ) : (
+                forThisRecord.map((entry) => (
+                  <div key={entry.id} className="flex flex-col gap-0.5 border-b py-2.5 text-sm last:border-b-0 last:pb-0">
+                    <span>
+                      <Badge variant={entry.action === "delete" ? "destructive" : "secondary"}>{entry.action}</Badge>
+                      <span className="ml-2 text-muted-foreground">{entry.userEmail ?? "someone"}</span>
+                    </span>
+                    <LocalTime value={entry.createdAt} className="text-xs text-muted-foreground tabular-nums" />
+                  </div>
+                ))
+              )}
+            </CardContent>
+          </Card>
+
+          {related.map(({ relation, target, rows, total, filterKey }) => (
+            <Card key={relation.key}>
+              <CardHeader>
+                <CardTitle className="text-base">{target.pluralLabel}</CardTitle>
+                <CardDescription>
+                  {total === 0 ? `No ${target.pluralLabel.toLowerCase()} yet.` : `${total.toLocaleString()} in total.`}
+                </CardDescription>
+              </CardHeader>
+              {rows.length > 0 && (
+                <CardContent className="flex flex-col">
+                  {rows.map((row) => {
+                    const childTitle = target.fields[target.titleField];
+                    const label = childTitle && childTitle.kind !== "hasMany" ? formatValue(childTitle, row[target.titleField]) : String(row.id);
+                    return (
+                      <Link
+                        key={String(row.id)}
+                        href={resourcePath(target, String(row.id))}
+                        className="truncate border-b py-2 text-sm last:border-b-0 last:pb-0 hover:text-primary"
+                      >
+                        {label || String(row.id)}
+                      </Link>
+                    );
+                  })}
+                  {total > rows.length && (
+                    <Button variant="link" className="h-auto justify-start p-0 pt-2" asChild>
+                      <Link href={`${resourcePath(target)}?filter[${filterKey}]=${id}`}>See all {total.toLocaleString()}</Link>
+                    </Button>
+                  )}
+                </CardContent>
+              )}
+            </Card>
+          ))}
+        </div>
+      </div>
+    </>
+  );
+}