create-nevela 0.5.1 → 0.5.3

package/template/laravel/src/Trash/Trash.php

@@ -0,0 +1,151 @@
+<?php
+
+namespace Nevela\Laravel\Trash;
+
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\QueryException;
+use Illuminate\Support\Carbon;
+use Illuminate\Support\Facades\Gate;
+use Nevela\Laravel\Nevela;
+use Nevela\Laravel\Support\Descriptor;
+
+/**
+ * What a delete leaves behind, and what becomes of it.
+ *
+ * A deleted record is kept, hidden from every list, count and export, for a number of
+ * days (config: nevela.trash.days, 30 unless changed). In that time it can be restored
+ * from the dashboard's Trash page. After it, the record is removed for good: by
+ * `nevela:trash`, which the scheduler runs each night, and whenever the trash is opened.
+ */
+final class Trash
+{
+    /** How many days a deleted record can be brought back, or null when it is kept until someone removes it. */
+    public static function days(): ?int
+    {
+        $days = config('nevela.trash.days', 30);
+
+        return is_numeric($days) && (int) $days > 0 ? (int) $days : null;
+    }
+
+    /**
+     * The resources that have a trash, with the model each one's records are.
+     *
+     * A resource is left out when its model doesn't keep deleted records: the app hasn't
+     * migrated yet, or its model was changed not to.
+     *
+     * @return list<array{descriptor: Descriptor, model: class-string<Model>}>
+     */
+    public static function resources(): array
+    {
+        $found = [];
+        foreach (Nevela::all() as $descriptor) {
+            $model = "App\\Models\\{$descriptor->name}";
+            if (class_exists($model) && method_exists($model, 'trashes') && $model::trashes()) {
+                $found[] = ['descriptor' => $descriptor, 'model' => $model];
+            }
+        }
+        usort($found, fn ($a, $b) => strcmp($a['descriptor']->pluralLabel, $b['descriptor']->pluralLabel));
+
+        return $found;
+    }
+
+    /** @return array{descriptor: Descriptor, model: class-string<Model>}|null */
+    public static function resource(string $slug): ?array
+    {
+        foreach (self::resources() as $resource) {
+            if ($resource['descriptor']->slug === $slug) {
+                return $resource;
+            }
+        }
+
+        return null;
+    }
+
+    /**
+     * Whether the signed-in person may do something to a deleted record.
+     *
+     * Laravel's names for these are `restore` and `forceDelete`, and a generated policy
+     * has both. A policy written before the trash existed has neither, so it is asked
+     * what it would say to `delete`: whoever could delete a record can deal with it here.
+     */
+    public static function may(string $ability, Model $record): bool
+    {
+        $policy = Gate::getPolicyFor($record);
+
+        return Gate::allows($policy !== null && method_exists($policy, $ability) ? $ability : 'delete', $record);
+    }
+
+    /**
+     * Whether they may see a resource's trash at all: whoever may delete, restore or remove
+     * for good. Asked of a record that is nobody's in particular. A policy that keeps
+     * restoring for administrators still lets the people who delete see what they deleted.
+     */
+    public static function maySee(string $model): bool
+    {
+        $blank = new $model;
+
+        return self::may('delete', $blank) || self::may('restore', $blank) || self::may('forceDelete', $blank);
+    }
+
+    /** When a record deleted at `$deletedAt` is removed for good, or null when it is kept until someone does. */
+    public static function expires(?Carbon $deletedAt): ?Carbon
+    {
+        $days = self::days();
+
+        return $days === null || $deletedAt === null ? null : $deletedAt->copy()->addDays($days);
+    }
+
+    /**
+     * Remove a deleted record for good. False when the database won't let it go because
+     * other records, themselves in the trash, still belong to it.
+     */
+    public static function purge(Model $record): bool
+    {
+        try {
+            $record->forceDelete();
+
+            return true;
+        } catch (QueryException $e) {
+            // 23000 (and Postgres's 23503): a foreign key still points at this row.
+            if (str_starts_with((string) $e->getCode(), '23')) {
+                return false;
+            }
+            throw $e;
+        }
+    }
+
+    /**
+     * Remove everything whose time in the trash has run out.
+     *
+     * @param  class-string<Model>|null  $only  One resource's model, or all of them
+     * @return array<string, int> How many were removed, by resource name
+     */
+    public static function purgeExpired(?string $only = null): array
+    {
+        $days = self::days();
+        if ($days === null) {
+            return [];
+        }
+        $cutoff = now()->subDays($days);
+        $removed = [];
+        foreach (self::resources() as $resource) {
+            $model = $resource['model'];
+            if ($only !== null && $only !== $model) {
+                continue;
+            }
+            $count = 0;
+            // One at a time, so a record something still belongs to is left and the rest go.
+            $model::onlyTrashed()->where((new $model)->getQualifiedDeletedAtColumn(), '<', $cutoff)->orderBy((new $model)->getKeyName())
+                ->chunkById(200, function ($records) use (&$count) {
+                    foreach ($records as $record) {
+                        $count += self::purge($record) ? 1 : 0;
+                    }
+                });
+            if ($count > 0) {
+                $removed[$resource['descriptor']->name] = $count;
+            }
+        }
+
+        return $removed;
+    }
+}

package/template/laravel/src/Trash/TrashedScope.php

@@ -0,0 +1,21 @@
+<?php
+
+namespace Nevela\Laravel\Trash;
+
+use Illuminate\Database\Eloquent\Builder;
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\SoftDeletingScope;
+
+/**
+ * Laravel's soft-delete scope, which hides deleted rows from every query, applied only
+ * to a table that has the column to hide them by. See Concerns\Trashable.
+ */
+final class TrashedScope extends SoftDeletingScope
+{
+    public function apply(Builder $builder, Model $model): void
+    {
+        if ($model::trashes()) {
+            parent::apply($builder, $model);
+        }
+    }
+}

package/template/web/app/dashboard/actions.ts

@@ -4,7 +4,9 @@ import { revalidatePath } from "next/cache";
 import { storedFields, type PolicyAction } from "@flaredev/core";
 import type { FieldIssue } from "@/lib/resource/store";
 import { toCsv } from "@/lib/csv";
+import { revalidateResource } from "@/lib/cache";
 import { fileUrl } from "@/lib/files";
+import { laravel } from "@/lib/laravel";
 import { allResources, resourcePath, dashboardSession, dashboardStore, mayDo } from "@/lib/dashboard";
 
 export type ActionResult<T = unknown> =
@@ -103,6 +105,83 @@ export async function createRecordAction(resourceName: string, input: unknown):
   return result;
 }
 
+export type InsightsUnit = "day" | "week" | "month";
+
+export interface InsightsData {
+  /** Everything the list matches, whenever it was created. */
+  total: number;
+  unit: InsightsUnit;
+  /** How many were created in each period, oldest first. A day or a week is "2026-10-05" (a week by its Monday), a month "2026-10". */
+  series: { bucket: string; count: number }[];
+  /** How the records split across each field that is a choice. */
+  breakdown: { field: string; kind: "enum" | "boolean"; slices: { value: string; count: number }[] }[];
+}
+
+/**
+ * The counts behind the insights panel: `GET /{slug}/_insights`.
+ *
+ * `query` is the list's own search and filters, so the charts are of the rows the table
+ * is showing. Asked for only when the panel is opened.
+ */
+export async function resourceInsightsAction(resourceName: string, query: string, unit: InsightsUnit): Promise<ActionResult<InsightsData>> {
+  const denied = await allowed(resourceName, "read");
+  if (denied) return denied;
+
+  const { resource } = dashboardStore(resourceName);
+  const params = new URLSearchParams();
+  for (const [key, value] of new URLSearchParams(query)) if (key === "q" || key.startsWith("filter[")) params.append(key, value);
+  params.set("unit", unit);
+  const response = await laravel(`${resource.slug}/_insights?${params}`);
+  if (!response.ok) {
+    const body = (response.body ?? {}) as { error?: string };
+    // An app whose Laravel side is from before this existed has no such address.
+    const missing = response.status === 404 || response.status === 405;
+    return { ok: false, status: response.status, error: missing ? "This app's API has no insights yet. Run: nevela upgrade" : (body.error ?? "Request failed.") };
+  }
+  return { ok: true, data: response.body as InsightsData };
+}
+
+/** What was wrong with one row of several, numbered from 1 among the rows that were sent. */
+export interface RowProblem {
+  row: number;
+  issues: FieldIssue[];
+}
+
+export type CreateManyResult = { ok: true; data: { created: number } } | { ok: false; status: number; error: string; rows?: RowProblem[] };
+
+/**
+ * Several records at once, for the "Add several" grid: `POST /{slug}/_bulk`.
+ *
+ * Laravel checks every row with the rules it uses for one, and saves them in a single
+ * transaction. So the answer is all of them, or none and the rows that were wrong.
+ */
+export async function createManyAction(resourceName: string, rows: Record<string, unknown>[]): Promise<CreateManyResult> {
+  const denied = await allowed(resourceName, "create");
+  if (denied) return denied;
+  if (rows.length === 0) return { ok: false, status: 400, error: "Nothing to create: every row is empty." };
+
+  const { resource } = dashboardStore(resourceName);
+  const response = await laravel(`${resource.slug}/_bulk`, { method: "POST", body: { items: rows } });
+  const body = (response.body ?? {}) as { error?: string; rows?: RowProblem[]; created?: number; data?: { id?: unknown }[] };
+  if (!response.ok) {
+    return {
+      ok: false,
+      status: response.status,
+      // An app whose Laravel side is from before this existed answers 404 or 405.
+      error: response.status === 404 || response.status === 405 ? "This app's API can't create several at once yet. Run: nevela upgrade" : (body.error ?? "Request failed."),
+      ...(body.rows ? { rows: body.rows } : {}),
+    };
+  }
+
+  try {
+    revalidateResource({ resource: resource.name, action: "create", id: String(body.data?.[0]?.id ?? "") });
+  } catch (error) {
+    console.error(`[nevela] ${resource.name} bulk create cache invalidation failed:`, error);
+  }
+  revalidatePath(resourcePath(resource));
+  return { ok: true, data: { created: body.created ?? rows.length } };
+}
+
 export async function updateRecordAction(resourceName: string, id: string, input: unknown): Promise<ActionResult<Record<string, unknown>>> {
   const denied = await allowed(resourceName, "update");
   if (denied) return denied;

package/template/web/app/dashboard/layout.tsx

@@ -4,7 +4,7 @@ import { Toaster } from "@/components/ui/sonner";
 import { DashboardHeader, type Theme } from "@/components/dashboard/dashboard-header";
 import { DashboardSidebar } from "@/components/dashboard/dashboard-sidebar";
 import { dashboardLinks } from "@/lib/dashboard-nav";
-import { dashboardSession, visibleResources } from "@/lib/dashboard";
+import { allResources, dashboardSession, mayDo, visibleResources } from "@/lib/dashboard";
 import { fileUrl } from "@/lib/files";
 import { requireSession } from "@/lib/session";
 import { site } from "@/lib/site";
@@ -34,10 +34,12 @@ export default async function DashboardLayout({ children }: { children: React.Re
   // The screens for managing people, for those whose roles allow it.
   const { isAdmin, may } = await dashboardSession();
   const access = { users: may("users.view"), roles: may("roles.view") };
+  // The trash is for those who may delete: whoever can put a record there can deal with it there.
+  const trash = (await Promise.all(allResources().map((resource) => mayDo(resource, "delete")))).some(Boolean);
 
   return (
     <SidebarProvider defaultOpen={!collapsed}>
-      <DashboardSidebar appName={site.name} resources={resources} links={dashboardLinks} isAdmin={isAdmin} access={access} user={account} />
+      <DashboardSidebar appName={site.name} resources={resources} links={dashboardLinks} isAdmin={isAdmin} access={access} trash={trash} user={account} />
       <SidebarInset>
         <DashboardHeader user={account} initialTheme={theme} notices={[]} />
         <main className="flex flex-1 flex-col gap-6 p-4 md:p-6 lg:p-8">{children}</main>

package/template/web/app/dashboard/trash/actions.ts

@@ -0,0 +1,78 @@
+"use server";
+
+import { revalidatePath } from "next/cache";
+import { revalidateResource } from "@/lib/cache";
+import { allResources, resourcePath } from "@/lib/dashboard";
+import { laravel } from "@/lib/laravel";
+import { getSession } from "@/lib/session";
+
+/**
+ * What can be done with a deleted record: bring it back, or remove it for good. Laravel
+ * decides who may, by the resource's own policy, and its answer is passed back as it is.
+ */
+
+export type TrashResult<T = null> = { ok: true; data: T } | { ok: false; error: string };
+
+/** Both places a change shows: the trash it left or stayed in, and the list it came from. */
+function revalidate(slug: string) {
+  const resource = allResources().find((item) => item.slug === slug);
+  if (resource) {
+    try {
+      revalidateResource({ resource: resource.name, action: "create", id: "" });
+    } catch (error) {
+      console.error(`[nevela] ${resource.name} trash cache invalidation failed:`, error);
+    }
+    revalidatePath(resourcePath(resource));
+  }
+  revalidatePath("/dashboard/trash");
+}
+
+async function send<T>(slug: string, path: string, method: "POST" | "DELETE"): Promise<TrashResult<T>> {
+  if (!(await getSession())) return { ok: false, error: "Sign in to continue." };
+  const response = await laravel(path, { method });
+  if (!response.ok) {
+    const body = (response.body ?? {}) as { error?: string };
+    return { ok: false, error: body.error ?? `Something went wrong (${response.status}).` };
+  }
+  revalidate(slug);
+  return { ok: true, data: response.body as T };
+}
+
+/** Back into its list, as it was. */
+export async function restoreRecordAction(slug: string, id: string): Promise<TrashResult<{ id: string }>> {
+  return send(slug, `_nevela/trash/${encodeURIComponent(slug)}/${encodeURIComponent(id)}/restore`, "POST");
+}
+
+/**
+ * Several back at once: what "Undo" does after deleting a selection. Ids that were never
+ * deleted (the ones the delete itself refused) aren't in the trash, and are passed over.
+ */
+export async function restoreManyAction(slug: string, ids: string[]): Promise<TrashResult<{ restored: number; refused: number; reason?: string }>> {
+  if (!(await getSession())) return { ok: false, error: "Sign in to continue." };
+  if (ids.length > 500) return { ok: false, error: "That's more than 500 records. Restore them from the trash instead." };
+  let restored = 0;
+  let refused = 0;
+  let reason: string | undefined;
+  for (const id of ids) {
+    const response = await laravel(`_nevela/trash/${encodeURIComponent(slug)}/${encodeURIComponent(id)}/restore`, { method: "POST" });
+    if (response.ok) restored++;
+    else if (response.status !== 404) {
+      refused++;
+      reason ??= ((response.body ?? {}) as { error?: string }).error ?? `Something went wrong (${response.status}).`;
+    }
+  }
+  if (restored > 0) revalidate(slug);
+  if (restored === 0) return { ok: false, error: reason ?? "Nothing to restore: these aren't in the trash any more." };
+  // Some came back and some were refused: both are said, so "Restored" is never the whole answer when it isn't.
+  return { ok: true, data: { restored, refused, reason } };
+}
+
+/** Gone for good. */
+export async function purgeRecordAction(slug: string, id: string): Promise<TrashResult> {
+  return send(slug, `_nevela/trash/${encodeURIComponent(slug)}/${encodeURIComponent(id)}`, "DELETE");
+}
+
+/** Everything of one resource that is in the trash, for good. */
+export async function emptyTrashAction(slug: string): Promise<TrashResult<{ removed: number; kept: number }>> {
+  return send(slug, `_nevela/trash/${encodeURIComponent(slug)}?confirm=${encodeURIComponent(slug)}`, "DELETE");
+}

package/template/web/app/dashboard/trash/page.tsx

@@ -0,0 +1,167 @@
+import Link from "next/link";
+import { LocalTime } from "@/components/dashboard/local-time";
+import { PageHeader } from "@/components/dashboard/page-header";
+import { resourceIcon } from "@/components/dashboard/resource-icon";
+import { EmptyTrashButton, TimeLeft, TrashRowActions } from "@/components/dashboard/trash-actions";
+import { Badge } from "@/components/ui/badge";
+import { Button } from "@/components/ui/button";
+import { Empty, EmptyDescription, EmptyHeader, EmptyTitle } from "@/components/ui/empty";
+import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "@/components/ui/table";
+import { requireDashboard } from "@/lib/dashboard";
+import { trashBuckets, trashedRecords } from "@/lib/trash";
+import { keptFor } from "@/lib/trash-info";
+import { cn } from "@/lib/utils";
+
+export const metadata = { title: "Trash" };
+
+type Params = { in?: string; page?: string };
+
+/**
+ * Deleted records, by resource: restore one, or remove it for good.
+ *
+ * Whose trash a person sees is Laravel's to say, by each resource's own policy. Someone
+ * who may delete products and nothing else sees deleted products and nothing else.
+ */
+export default async function TrashPage({ searchParams }: { searchParams: Promise<Params> }) {
+  await requireDashboard("/dashboard/trash");
+  const params = await searchParams;
+  const trash = await trashBuckets();
+  const buckets = trash?.resources ?? [];
+  // The one asked for, or the first with something in it.
+  const current = buckets.find((bucket) => bucket.slug === params.in) ?? buckets.find((bucket) => bucket.count > 0) ?? buckets[0];
+  let list = current ? await trashedRecords(current.slug, params.page) : null;
+  // The last record of the last page was just restored or removed: show the page before it.
+  if (current && list && list.data.length === 0 && list.meta.total > 0) list = await trashedRecords(current.slug, String(list.meta.totalPages));
+  const records = list?.data ?? [];
+  const meta = list?.meta ?? { page: 1, perPage: 25, total: 0, totalPages: 1 };
+  const href = (slug: string, page?: number) => `/dashboard/trash?${new URLSearchParams({ in: slug, ...(page && page > 1 ? { page: String(page) } : {}) })}`;
+
+  return (
+    <>
+      <PageHeader
+        title="Trash"
+        description={
+          trash
+            ? `Deleted records are kept here ${keptFor(trash)}${trash.days === null ? "." : ", then removed for good."} Until then, they can be restored.`
+            : "Deleted records, to restore or to remove for good."
+        }
+        crumbs={[{ label: "Dashboard", href: "/dashboard" }, { label: "Trash" }]}
+        actions={current && meta.total > 0 && <EmptyTrashButton slug={current.slug} count={meta.total} noun={current.label.toLowerCase()} plural={current.pluralLabel.toLowerCase()} />}
+      />
+
+      {!trash ? (
+        <Empty className="rounded-xl border border-dashed">
+          <EmptyHeader>
+            <EmptyTitle>This app has no trash yet</EmptyTitle>
+            <EmptyDescription>
+              Its Laravel side is from before Nevela had one. Run <code>nevela upgrade</code>, then <code>nevela migrate</code>.
+            </EmptyDescription>
+          </EmptyHeader>
+        </Empty>
+      ) : buckets.length === 0 ? (
+        <Empty className="rounded-xl border border-dashed">
+          <EmptyHeader>
+            <EmptyTitle>Nothing here for you</EmptyTitle>
+            <EmptyDescription>
+              The trash holds what you may delete, once its table keeps deleted records. After an upgrade, <code>nevela migrate</code> is what gives each table
+              its trash.
+            </EmptyDescription>
+          </EmptyHeader>
+        </Empty>
+      ) : (
+        <>
+          <nav aria-label="Deleted records, by resource" className="flex flex-wrap gap-2">
+            {buckets.map((bucket) => {
+              const Icon = resourceIcon(bucket.icon ?? undefined);
+              const active = bucket.slug === current?.slug;
+              return (
+                <Button key={bucket.slug} variant={active ? "secondary" : "ghost"} size="sm" asChild>
+                  <Link href={href(bucket.slug)} aria-current={active ? "page" : undefined} className={cn(!active && "text-muted-foreground")}>
+                    <Icon data-icon="inline-start" />
+                    {bucket.pluralLabel}
+                    <Badge variant={bucket.count > 0 ? "default" : "outline"} className="tabular-nums">
+                      {bucket.count.toLocaleString()}
+                    </Badge>
+                  </Link>
+                </Button>
+              );
+            })}
+          </nav>
+
+          {current && records.length === 0 ? (
+            <Empty className="rounded-xl border border-dashed">
+              <EmptyHeader>
+                <EmptyTitle>No deleted {current.pluralLabel.toLowerCase()}</EmptyTitle>
+                <EmptyDescription>When one is deleted, it waits here until it is restored or its time runs out.</EmptyDescription>
+              </EmptyHeader>
+            </Empty>
+          ) : (
+            current && (
+              <div className="overflow-x-auto rounded-xl border">
+                <Table>
+                  <TableHeader>
+                    <TableRow>
+                      <TableHead>{current.label}</TableHead>
+                      <TableHead>Deleted</TableHead>
+                      <TableHead>Removed for good</TableHead>
+                      <TableHead className="w-56">
+                        <span className="sr-only">Actions</span>
+                      </TableHead>
+                    </TableRow>
+                  </TableHeader>
+                  <TableBody>
+                    {records.map((record) => (
+                      <TableRow key={record.id}>
+                        <TableCell className="max-w-80 truncate font-medium">{record.label}</TableCell>
+                        <TableCell className="text-sm text-muted-foreground tabular-nums">
+                          <LocalTime value={record.deletedAt} />
+                        </TableCell>
+                        <TableCell className="text-sm text-muted-foreground tabular-nums">
+                          <TimeLeft until={record.expiresAt} />
+                        </TableCell>
+                        <TableCell>
+                          <TrashRowActions slug={current.slug} id={record.id} label={record.label} noun={current.label.toLowerCase()} />
+                        </TableCell>
+                      </TableRow>
+                    ))}
+                  </TableBody>
+                </Table>
+              </div>
+            )
+          )}
+
+          {current && meta.total > 0 && (
+            <div className="flex items-center justify-between gap-3 text-sm text-muted-foreground">
+              <p className="tabular-nums">
+                {(meta.page - 1) * meta.perPage + 1}–{Math.min(meta.page * meta.perPage, meta.total)} of {meta.total.toLocaleString()} deleted{" "}
+                {meta.total === 1 ? current.label.toLowerCase() : current.pluralLabel.toLowerCase()}
+              </p>
+              {meta.totalPages > 1 && (
+                <div className="flex items-center gap-2">
+                  {meta.page > 1 ? (
+                    <Button variant="outline" size="sm" asChild>
+                      <Link href={href(current.slug, meta.page - 1)}>Previous</Link>
+                    </Button>
+                  ) : (
+                    <Button variant="outline" size="sm" disabled>
+                      Previous
+                    </Button>
+                  )}
+                  {meta.page < meta.totalPages ? (
+                    <Button variant="outline" size="sm" asChild>
+                      <Link href={href(current.slug, meta.page + 1)}>Next</Link>
+                    </Button>
+                  ) : (
+                    <Button variant="outline" size="sm" disabled>
+                      Next
+                    </Button>
+                  )}
+                </div>
+              )}
+            </div>
+          )}
+        </>
+      )}
+    </>
+  );
+}