create-nevela 0.7.1 → 0.8.0

package/template/web/components/dashboard/resource-action.tsx

@@ -0,0 +1,281 @@
+"use client";
+
+import { useRouter } from "next/navigation";
+import { useState, useTransition } from "react";
+import {
+  ArchiveIcon,
+  BanIcon,
+  BellIcon,
+  CheckIcon,
+  CopyIcon,
+  DownloadIcon,
+  FlagIcon,
+  LockIcon,
+  MailIcon,
+  MegaphoneIcon,
+  PauseIcon,
+  PlayIcon,
+  RefreshCwIcon,
+  SendIcon,
+  StarIcon,
+  UnlockIcon,
+  UploadIcon,
+  XIcon,
+  ZapIcon,
+  type LucideIcon,
+} from "lucide-react";
+import { toast } from "sonner";
+import { field as build, type StoredField } from "@flaredev/core";
+import { runResourceAction } from "@/app/dashboard/actions";
+import {
+  AlertDialog,
+  AlertDialogCancel,
+  AlertDialogContent,
+  AlertDialogDescription,
+  AlertDialogFooter,
+  AlertDialogHeader,
+  AlertDialogTitle,
+} from "@/components/ui/alert-dialog";
+import { Button } from "@/components/ui/button";
+import { Field, FieldError, FieldLabel } from "@/components/ui/field";
+import { Sheet, SheetContent, SheetDescription, SheetFooter, SheetHeader, SheetTitle } from "@/components/ui/sheet";
+import { Spinner } from "@/components/ui/spinner";
+import type { ActionField, ResourceAction } from "@/lib/extras";
+import { FieldWidget } from "./fields/field-widget";
+
+const ICONS: Record<string, LucideIcon> = {
+  archive: ArchiveIcon,
+  ban: BanIcon,
+  bell: BellIcon,
+  check: CheckIcon,
+  copy: CopyIcon,
+  download: DownloadIcon,
+  flag: FlagIcon,
+  lock: LockIcon,
+  mail: MailIcon,
+  megaphone: MegaphoneIcon,
+  pause: PauseIcon,
+  play: PlayIcon,
+  refresh: RefreshCwIcon,
+  send: SendIcon,
+  star: StarIcon,
+  unlock: UnlockIcon,
+  upload: UploadIcon,
+  x: XIcon,
+};
+
+/** The icon an action names, or a general one for "do something". */
+export function actionIcon(name: string | undefined): LucideIcon {
+  return (name && ICONS[name]) || ZapIcon;
+}
+
+/** What an action is run on: one record, the rows selected, or nothing in particular (the list as a whole). */
+export interface ActionTarget {
+  id?: string;
+  ids?: string[];
+}
+
+const words = (key: string) => {
+  const spaced = key.replace(/([a-z0-9])([A-Z])/g, "$1 $2").toLowerCase();
+  return spaced.charAt(0).toUpperCase() + spaced.slice(1);
+};
+
+/** A field an action asks for, as the form's widgets know fields. */
+function widgetField(key: string, def: ActionField): StoredField & { label: string } {
+  const options = { required: def.required !== false, ...(def.maxLength ? { maxLength: def.maxLength } : {}) };
+  const made =
+    def.kind === "enum"
+      ? build.enum((def.options?.length ? def.options : [""]) as [string, ...string[]], { required: options.required })
+      : def.kind === "string" && def.format === "email"
+        ? build.email(options)
+        : def.kind === "string" && def.format === "url"
+          ? build.url(options)
+          : def.kind === "string" && def.format === "tel"
+            ? build.tel(options)
+            : def.kind === "string"
+              ? build.string(options)
+              : def.kind === "text"
+                ? build.text(options)
+                : def.kind === "int"
+                  ? build.int({ required: options.required })
+                  : def.kind === "float"
+                    ? build.float({ required: options.required })
+                    : def.kind === "boolean"
+                      ? build.boolean({ required: options.required })
+                      : def.kind === "date"
+                        ? build.date({ required: options.required })
+                        : build.datetime({ required: options.required });
+  return { ...made, label: def.label ?? words(key) } as StoredField & { label: string };
+}
+
+/** What the widgets hold while typing, as the API wants it: a number as a number, nothing as nothing. */
+function asInput(fields: Record<string, ActionField>, values: Record<string, string | boolean>): Record<string, unknown> {
+  const input: Record<string, unknown> = {};
+  for (const [key, def] of Object.entries(fields)) {
+    const value = values[key];
+    if (def.kind === "boolean") input[key] = value === true;
+    else if (value === undefined || value === "") continue;
+    else if (def.kind === "int" || def.kind === "float") input[key] = Number(value);
+    else input[key] = value;
+  }
+  return input;
+}
+
+/**
+ * Running a resource's own actions from wherever their buttons are: a record's page, a
+ * row's menu, beside New, the selection bar.
+ *
+ * `start` does what the action calls for first. One with something to fill in opens a
+ * sheet; one with a question asks it, in the dialog Delete uses; one with neither runs.
+ * Then the message its class returned is the toast, and the page is asked for again.
+ * `dialogs` is the sheet and the dialog, to be rendered once by whoever holds the buttons.
+ */
+export function useResourceActions(resourceName: string, nouns: { one: string; many: string }, onDone?: () => void) {
+  const router = useRouter();
+  const [current, setCurrent] = useState<{ action: ResourceAction; target: ActionTarget } | null>(null);
+  const [values, setValues] = useState<Record<string, string | boolean>>({});
+  const [issues, setIssues] = useState<Record<string, string>>({});
+  const [pending, startTransition] = useTransition();
+
+  function run(action: ResourceAction, target: ActionTarget, input: Record<string, unknown>) {
+    startTransition(async () => {
+      const result = await runResourceAction(resourceName, action.key, target, input);
+      if (result.ok) {
+        toast.success(result.data.message);
+        setCurrent(null);
+        onDone?.();
+        router.refresh();
+        return;
+      }
+      const byField: Record<string, string> = {};
+      for (const issue of result.issues ?? []) byField[issue.path] ??= issue.message;
+      // A problem with something that was filled in is shown where it was filled in.
+      if (action.fields && Object.keys(byField).some((key) => key in action.fields!)) {
+        setIssues(byField);
+        return;
+      }
+      toast.error(result.error);
+      setCurrent(null);
+      // It may have stopped applying while the page was open: show the page as it is now.
+      if (result.status === 409 || result.status === 404) router.refresh();
+    });
+  }
+
+  function start(action: ResourceAction, target: ActionTarget = {}) {
+    setIssues({});
+    setValues(Object.fromEntries(Object.entries(action.fields ?? {}).map(([key, def]) => [key, def.kind === "boolean" ? false : ""])));
+    if (!action.fields && !action.confirm) run(action, target, {});
+    else setCurrent({ action, target });
+  }
+
+  const action = current?.action;
+  const count = current?.target.ids?.length;
+  // "the 1 article you selected", "the 3 articles you selected"
+  const selected = count ? ` This is for the ${count} ${count === 1 ? nouns.one : nouns.many} you selected.` : "";
+  const asking = Boolean(action && !action.fields);
+  const filling = Boolean(action?.fields);
+
+  const dialogs = (
+    <>
+      <AlertDialog open={asking} onOpenChange={(open) => !open && !pending && setCurrent(null)}>
+        <AlertDialogContent>
+          <AlertDialogHeader>
+            <AlertDialogTitle>{action?.label}</AlertDialogTitle>
+            <AlertDialogDescription>
+              {action?.confirm}
+              {selected}
+            </AlertDialogDescription>
+          </AlertDialogHeader>
+          <AlertDialogFooter>
+            <AlertDialogCancel disabled={pending}>Cancel</AlertDialogCancel>
+            <Button onClick={() => current && run(current.action, current.target, {})} disabled={pending}>
+              {pending && <Spinner data-icon="inline-start" />}
+              {action?.label}
+            </Button>
+          </AlertDialogFooter>
+        </AlertDialogContent>
+      </AlertDialog>
+
+      <Sheet open={filling} onOpenChange={(open) => !open && !pending && setCurrent(null)}>
+        <SheetContent className="flex w-full flex-col gap-0 sm:max-w-md">
+          <SheetHeader>
+            <SheetTitle>{action?.label}</SheetTitle>
+            <SheetDescription>
+              {action?.confirm ?? `Fill this in, then ${action?.label.toLowerCase()}.`}
+              {selected}
+            </SheetDescription>
+          </SheetHeader>
+          <form
+            className="flex min-h-0 flex-1 flex-col"
+            onSubmit={(event) => {
+              event.preventDefault();
+              if (current?.action.fields) run(current.action, current.target, asInput(current.action.fields, values));
+            }}
+          >
+            <div className="flex flex-1 flex-col gap-4 overflow-y-auto px-4 pb-4">
+              {Object.entries(action?.fields ?? {}).map(([key, def]) => {
+                const widget = widgetField(key, def);
+                const id = `action-${action?.key}-${key}`;
+                return (
+                  <Field key={key} data-invalid={issues[key] ? true : undefined} orientation={def.kind === "boolean" ? "horizontal" : "vertical"}>
+                    <FieldLabel htmlFor={id}>
+                      {widget.label}
+                      {def.required !== false && def.kind !== "boolean" && <span className="text-destructive"> *</span>}
+                    </FieldLabel>
+                    <FieldWidget
+                      id={id}
+                      name={key}
+                      resourceName={resourceName}
+                      fieldKey={key}
+                      field={widget}
+                      value={values[key] ?? ""}
+                      onChange={(value) => setValues((before) => ({ ...before, [key]: value }))}
+                      invalid={Boolean(issues[key])}
+                      disabled={pending}
+                    />
+                    {issues[key] && <FieldError>{issues[key]}</FieldError>}
+                  </Field>
+                );
+              })}
+            </div>
+            <SheetFooter className="flex-row justify-end border-t">
+              <Button type="button" variant="outline" onClick={() => setCurrent(null)} disabled={pending}>
+                Cancel
+              </Button>
+              <Button type="submit" disabled={pending}>
+                {pending && <Spinner data-icon="inline-start" />}
+                {action?.label}
+              </Button>
+            </SheetFooter>
+          </form>
+        </SheetContent>
+      </Sheet>
+    </>
+  );
+
+  return { start, pending, dialogs };
+}
+
+/**
+ * Buttons for a resource's actions: on a record's page (with the record's id), or beside
+ * New for actions on the list as a whole (with none).
+ */
+export function ActionButtons({ resourceName, actions, id }: { resourceName: string; actions: ResourceAction[]; id?: string }) {
+  // Buttons here are for one record or for the list as a whole: never for a selection, so no noun is needed.
+  const { start, pending, dialogs } = useResourceActions(resourceName, { one: "record", many: "records" });
+  if (actions.length === 0) return null;
+  return (
+    <>
+      {actions.map((action) => {
+        const Icon = actionIcon(action.icon);
+        return (
+          <Button key={action.key} variant="outline" disabled={pending} onClick={() => start(action, id ? { id } : {})}>
+            <Icon data-icon="inline-start" />
+            {action.label}
+          </Button>
+        );
+      })}
+      {dialogs}
+    </>
+  );
+}

package/template/web/components/dashboard/resource-table.tsx

@@ -3,6 +3,8 @@ import { FileCell } from "@/components/dashboard/fields/file-cell";
 import { ArrowDownIcon, ArrowUpIcon, ChevronLeftIcon, ChevronRightIcon, ChevronsUpDownIcon, PlusIcon } from "lucide-react";
 import { clientResource, formatValue, optionLabel, statusTone, storedFields, type Resource, type StoredField } from "@flaredev/core";
 import { isSortable } from "@/lib/resource/query";
+import { privateFileUrl } from "@/lib/files";
+import { isRich, richToText } from "@/lib/rich";
 import { Alert, AlertDescription } from "@/components/ui/alert";
 import { Badge } from "@/components/ui/badge";
 import { Button } from "@/components/ui/button";
@@ -16,7 +18,8 @@ import {
   PaginationPrevious,
 } from "@/components/ui/pagination";
 import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "@/components/ui/table";
-import { resourcePath, adminPermissions, allResources, dashboardStore, requireAccess } from "@/lib/dashboard";
+import { resourcePath, adminPermissions, allowedActions, allResources, dashboardStore, requireAccess } from "@/lib/dashboard";
+import { actionApplies } from "@/lib/extras";
 import { site } from "@/lib/site";
 import { trashFor } from "@/lib/trash";
 import { cn } from "@/lib/utils";
@@ -26,6 +29,7 @@ import { isInlineEditable } from "./editable";
 import { InlineCell } from "./inline-cell";
 import type { RelationMeta } from "./fields/field-widget";
 import { BulkCreateButton } from "./bulk-create-grid";
+import { ActionButtons } from "./resource-action";
 import { ResourceInsights } from "./resource-insights";
 import { ImportDialog } from "./import-dialog";
 import { LocalTime } from "./local-time";
@@ -96,6 +100,9 @@ export async function ResourceTable({ resource, searchParams }: { resource: Reso
   }
 
   const overlayForms = site.dashboard.forms === "sheet";
+  // The resource's own actions this person may run: on the list as a whole, and on a record.
+  const actions = await allowedActions(resource.name);
+  const onRecords = actions.filter((action) => action.on === "record");
   const rowIds = rows.map((row) => String(row.id));
   const exportColumns = [{ key: "id", label: "Id" }, ...fields.filter(([, def]) => def.kind !== "file").map(([key, def]) => ({ key, label: def.label }))];
 
@@ -115,6 +122,7 @@ export async function ResourceTable({ resource, searchParams }: { resource: Reso
         <div className="flex flex-wrap items-center gap-2">
           <ColumnMenu columns={allColumns.map(({ key, label }) => ({ key, label }))} visible={columns.map((column) => column.key)} />
           <ExportButton resourceName={resource.name} pluralLabel={resource.pluralLabel} />
+          <ActionButtons resourceName={resource.name} actions={actions.filter((action) => action.on === "collection")} />
           {permissions.create && <ImportDialog resource={forClient} />}
           {permissions.create && <BulkCreateButton resource={forClient} relations={relations} />}
           {permissions.create &&
@@ -213,10 +221,13 @@ export async function ResourceTable({ resource, searchParams }: { resource: Reso
                       } else if (column.def.kind === "enum" && value != null) {
                         const tone = statusTone(value);
                         content = <Badge variant={tone === "neutral" ? "secondary" : tone}>{content}</Badge>;
+                      } else if (isRich(column.def) && typeof value === "string") {
+                        // The start of it, as words: markup is noise in a table.
+                        content = richToText(value, 120);
                       } else if (column.def.kind === "file" && typeof value === "string" && value) {
                         // A thumbnail for an image, a filename for anything else — the raw
                         // object key is noise in a table.
-                        content = <FileCell resourceName={resource.name} fieldKey={column.key} value={value} />;
+                        content = <FileCell resourceName={resource.name} fieldKey={column.key} value={value} download={privateFileUrl(resource.slug, String(row.id), column.key)} />;
                       } else if (column.def.kind === "multiselect" && Array.isArray(value) && value.length) {
                         const def = column.def;
                         content = (
@@ -304,6 +315,7 @@ export async function ResourceTable({ resource, searchParams }: { resource: Reso
                         canUpdate={permissions.update}
                         canDelete={permissions.delete}
                         trash={trash}
+                        actions={onRecords.filter((action) => actionApplies(action, row))}
                       />
                     </TableCell>
                   </TableRow>
@@ -398,6 +410,7 @@ export async function ResourceTable({ resource, searchParams }: { resource: Reso
         label={resource.label}
         pluralLabel={resource.pluralLabel}
         canDelete={permissions.delete}
+        actions={onRecords.filter((action) => action.many)}
         rows={rows}
         columns={exportColumns}
         slug={resource.slug}

package/template/web/components/dashboard/row-actions.tsx

@@ -27,7 +27,9 @@ import {
   DropdownMenuTrigger,
 } from "@/components/ui/dropdown-menu";
 import { Spinner } from "@/components/ui/spinner";
+import type { ResourceAction } from "@/lib/extras";
 import { keptFor, type TrashInfo } from "@/lib/trash-info";
+import { actionIcon, useResourceActions } from "./resource-action";
 import { ResourceFormSheet, type FormRelations } from "./resource-form-sheet";
 import { toastMovedToTrash } from "./trash-actions";
 
@@ -46,6 +48,7 @@ export function RowActions({
   canUpdate = true,
   canDelete = true,
   trash,
+  actions = [],
 }: {
   resource: ClientResource;
   id: string;
@@ -60,8 +63,11 @@ export function RowActions({
   canDelete?: boolean;
   /** This resource's trash, when a deleted record goes there instead of going for good. */
   trash?: TrashInfo;
+  /** The resource's own actions that this person may run and that apply to this row. */
+  actions?: ResourceAction[];
 }) {
   const router = useRouter();
+  const own = useResourceActions(resource.name, { one: resource.label.toLowerCase(), many: resource.pluralLabel.toLowerCase() });
   const [confirming, setConfirming] = useState(false);
   const [editing, setEditing] = useState(false);
   const [pending, startTransition] = useTransition();
@@ -99,6 +105,22 @@ export function RowActions({
             </DropdownMenuItem>
           </DropdownMenuGroup>
           <DropdownMenuSeparator />
+          {actions.length > 0 && (
+            <>
+              <DropdownMenuGroup>
+                {actions.map((action) => {
+                  const Icon = actionIcon(action.icon);
+                  return (
+                    <DropdownMenuItem key={action.key} disabled={own.pending} onSelect={() => own.start(action, { id })}>
+                      <Icon />
+                      {action.label}
+                    </DropdownMenuItem>
+                  );
+                })}
+              </DropdownMenuGroup>
+              {(canUpdate || canDelete) && <DropdownMenuSeparator />}
+            </>
+          )}
           {canUpdate && (
             <DropdownMenuGroup>
               {record ? (
@@ -128,6 +150,8 @@ export function RowActions({
         </DropdownMenuContent>
       </DropdownMenu>
 
+      {own.dialogs}
+
       {record && canUpdate && (
         <ResourceFormSheet
           resource={resource}

package/template/web/components/dashboard/table-selection.tsx

@@ -20,7 +20,9 @@ import { Button } from "@/components/ui/button";
 import { Checkbox } from "@/components/ui/checkbox";
 import { Spinner } from "@/components/ui/spinner";
 import { toCsv } from "@/lib/csv";
+import { actionApplies, type ResourceAction } from "@/lib/extras";
 import { keptFor, type TrashInfo } from "@/lib/trash-info";
+import { actionIcon, useResourceActions } from "./resource-action";
 import { toastMovedToTrash } from "./trash-actions";
 
 interface SelectionValue {
@@ -100,15 +102,18 @@ interface BarProps {
   /** The resource's address, and its trash when deleted records go there instead of going for good. */
   slug: string;
   trash?: TrashInfo;
+  /** The resource's own actions that can be run on several records at once, and that this person may run. */
+  actions?: ResourceAction[];
 }
 
 /**
  * What you can do with the rows you've ticked. Appears only when something is selected,
  * pinned to the bottom so it's reachable in a long table.
  */
-export function SelectionBar({ resourceName, label, pluralLabel, canDelete, rows, columns, slug, trash }: BarProps) {
+export function SelectionBar({ resourceName, label, pluralLabel, canDelete, rows, columns, slug, trash, actions = [] }: BarProps) {
   const { selected, clear } = useSelection();
   const router = useRouter();
+  const own = useResourceActions(resourceName, { one: label.toLowerCase(), many: pluralLabel.toLowerCase() }, clear);
   const [confirming, setConfirming] = useState(false);
   const [pending, startTransition] = useTransition();
   const count = selected.size;
@@ -157,6 +162,17 @@ export function SelectionBar({ resourceName, label, pluralLabel, canDelete, rows
           <DownloadIcon data-icon="inline-start" />
           Export
         </Button>
+        {actions.map((action) => {
+          const Icon = actionIcon(action.icon);
+          // Offered when it applies to at least one of the rows ticked. Laravel passes over the rest.
+          const applicable = rows.filter((row) => selected.has(String(row.id)) && actionApplies(action, row)).map((row) => String(row.id));
+          return (
+            <Button key={action.key} variant="ghost" size="sm" disabled={own.pending || applicable.length === 0} onClick={() => own.start(action, { ids: applicable })}>
+              <Icon data-icon="inline-start" />
+              {action.label}
+            </Button>
+          );
+        })}
         {canDelete && (
           <Button variant="ghost" size="sm" className="text-destructive hover:text-destructive" onClick={() => setConfirming(true)}>
             <Trash2Icon data-icon="inline-start" />
@@ -168,6 +184,8 @@ export function SelectionBar({ resourceName, label, pluralLabel, canDelete, rows
         </Button>
       </div>
 
+      {own.dialogs}
+
       <AlertDialog open={confirming} onOpenChange={setConfirming}>
         <AlertDialogContent>
           <AlertDialogHeader>

package/template/web/lib/access.ts

@@ -51,8 +51,10 @@ export interface PermissionFeature {
   /** The first half of a permission: "products". */
   key: string;
   name: string;
-  /** The second halves that mean something for it: create, view, edit, delete. */
+  /** The second halves that mean something for it: create, view, edit, delete, then the resource's own actions. */
   actions: string[];
+  /** What a resource's own actions are called, by second half: { accept: "Accept" }. */
+  labels?: Record<string, string>;
 }
 
 export interface PermissionModule {

package/template/web/lib/dashboard.ts

@@ -1,3 +1,4 @@
+import { actionsOf, type ResourceAction } from "@/lib/extras";
 import { cache } from "react";
 import { notFound, redirect } from "next/navigation";
 import { can, type Policy, type PolicyAction, type Resource } from "@flaredev/core";
@@ -96,6 +97,15 @@ export async function adminPermissions(resourceName: string): Promise<Record<Exc
   return { read: read!, create: create!, update: update!, delete: remove! };
 }
 
+/**
+ * The resource's own actions that the current person may run, for drawing their buttons.
+ * Each is a permission by name. Laravel checks it again when the button is pressed.
+ */
+export async function allowedActions(resourceName: string): Promise<ResourceAction[]> {
+  const { session, may } = await dashboardSession();
+  return session ? actionsOf(resourceName).filter((action) => may(action.permission)) : [];
+}
+
 const stores = new Map<string, ResourceStore>();
 
 /** CRUD store for a resource by name (404 for unknown names). */

package/template/web/lib/extras.ts

@@ -0,0 +1,66 @@
+// What a resource has beyond its fields, which Flare's descriptor has no place for.
+//
+// Written by `php nevela generate` into resources/index.ts as `extras`, by resource
+// name, from the descriptors in the Laravel app. Read through here, on the server: a
+// client component is handed what it needs of it as props.
+
+import * as registry from "@/resources";
+
+/** A field an action asks for, as the descriptor has it. */
+export interface ActionField {
+  kind: "string" | "text" | "int" | "float" | "boolean" | "date" | "datetime" | "enum";
+  format?: string;
+  options?: string[];
+  required?: boolean;
+  label?: string;
+  maxLength?: number;
+}
+
+/**
+ * Something that can be done to a record, or to the list, beyond creating, editing and
+ * deleting: the descriptor's "actions" section. What it does is a class in the Laravel
+ * app; this is what the dashboard needs to offer it.
+ */
+export interface ResourceAction {
+  /** Its name in the descriptor and in the address: "accept". */
+  key: string;
+  /** The permission that allows it: "internship_applications.accept". */
+  permission: string;
+  label: string;
+  /** A lucide icon name. */
+  icon?: string;
+  /** Where its button is: on one record, or on the list as a whole. */
+  on: "record" | "collection";
+  /** A question asked before it runs. */
+  confirm?: string;
+  /** Field values a record must have for the action to apply to it. */
+  when?: Record<string, string | number | boolean | null>;
+  /** What it asks for, in a sheet. */
+  fields?: Record<string, ActionField>;
+  /** A record action that can also be run on the rows selected in the table. */
+  many?: boolean;
+}
+
+interface ResourceExtras {
+  actions?: Record<string, Omit<ResourceAction, "key">>;
+}
+
+/** An app generated before there were any has no `extras` in its registry, and none to have. */
+const extras = ((registry as { extras?: unknown }).extras ?? {}) as Record<string, ResourceExtras>;
+
+/** A resource's actions, in the order the descriptor gives them. */
+export function actionsOf(resourceName: string): ResourceAction[] {
+  return Object.entries(extras[resourceName]?.actions ?? {}).map(([key, action]) => ({ ...action, key }));
+}
+
+/** Whether an action applies to a record as it is now. Laravel asks the same before running it. */
+export function actionApplies(action: ResourceAction, record: Record<string, unknown>): boolean {
+  return Object.entries(action.when ?? {}).every(([field, wanted]) => {
+    const value = record[field] ?? null;
+    if (wanted === null) return value === null;
+    if (value === null) return false;
+    // A yes/no value may arrive as 1 or 0.
+    if (typeof wanted === "boolean") return (value === true || value === 1 || value === "1") === wanted;
+    return String(value) === String(wanted);
+  });
+}

package/template/web/lib/files.ts

@@ -17,5 +17,19 @@ export function fileUrl(key: string, rendition?: string): string {
   return `/api/_nevela/files/${path.split("/").map(encodeURIComponent).join("/")}`;
 }
 
+/**
+ * Whether a key is a private file's. Such a file has no address of its own: asked for by
+ * key, Laravel answers that there is no such file. It is fetched through its record.
+ */
+export const isPrivateKey = (key: string) => key.startsWith("private/");
+
+/**
+ * Where a private file is fetched from: the record it belongs to and the field it is in.
+ * Laravel hands it over only to someone signed in who may view that record.
+ */
+export function privateFileUrl(resourceSlug: string, id: string, fieldKey: string): string {
+  return `/api/_nevela/private/${encodeURIComponent(resourceSlug)}/${encodeURIComponent(id)}/${encodeURIComponent(fieldKey)}`;
+}
+
 /** "products/image/2026/10/<uuid>-kettle.webp" → "kettle.webp" */
 export const fileName = (key: string) => key.slice(key.lastIndexOf("/") + 1).replace(/^[0-9a-f-]{36}-/, "");

package/template/web/lib/laravel.ts

@@ -34,6 +34,17 @@ export async function callerHeaders(): Promise<Record<string, string>> {
   if (agent) sent["X-Nevela-User-Agent"] = agent.slice(0, 500);
   const address = (incoming.get("x-forwarded-for") ?? "").split(",")[0]?.trim() || incoming.get("x-real-ip");
   if (address) sent["X-Nevela-Ip"] = address.replace(/^::ffff:/, "");
+  // That one is for showing: the first entry of X-Forwarded-For is whatever the request
+  // came with, and anyone can send one. The address a visitor is *counted* by (the public
+  // routes' throttle) has to be one they couldn't have made up. Each proxy adds the
+  // address it was called from to the end of the list, so with one proxy in front of this
+  // app the last entry is the visitor as that proxy saw them. NEVELA_TRUSTED_PROXIES says
+  // how many proxies are in front: 1 unless set, and 0 when this app is reached directly,
+  // in which case nobody's word is taken and visitors are counted together.
+  const proxies = Number.parseInt(process.env.NEVELA_TRUSTED_PROXIES ?? "1", 10);
+  const chain = (incoming.get("x-forwarded-for") ?? "").split(",").map((part) => part.trim()).filter(Boolean);
+  const counted = Number.isInteger(proxies) && proxies > 0 ? chain[chain.length - proxies] : undefined;
+  sent["X-Nevela-Client"] = counted ? counted.replace(/^::ffff:/, "") : "unknown";
   // Proves to Laravel that this is the dashboard speaking for a browser, and not someone
   // calling the API with made-up headers. The same value is in the Laravel app's .env.
   if (process.env.NEVELA_PROXY_SECRET) sent["X-Nevela-Proxy-Secret"] = process.env.NEVELA_PROXY_SECRET;
@@ -80,3 +91,52 @@ export async function laravel(path: string, { method = "GET", body, token }: Lar
   }
   return { status: response.status, ok: response.ok, body: parsed };
 }
+
+export interface PublicRequest {
+  /** How long an answer may be reused, in seconds. Default 300. `false` keeps it until one of its tags is revalidated. */
+  revalidate?: number | false;
+  /** What makes it stale. `resourceTag("Post")` from lib/cache: the dashboard revalidates it when a post is created, changed, deleted or restored. */
+  tags?: string[];
+}
+
+/**
+ * Read what a resource's "public" section opens, for a page anyone can visit.
+ *
+ * ```ts
+ * const { body } = await laravelPublic("posts?sort=-publishedAt", { tags: [resourceTag("Post")] });
+ * ```
+ *
+ * Unlike `laravel()` it carries nothing of the person asking: no token and none of their
+ * headers. The answer is the same for everyone, so it is cached and shared between
+ * visitors, and a published post appears as soon as the dashboard saves it, because
+ * saving revalidates the resource's tag.
+ *
+ * `path` is under `{api}/public/`. To send a form (a public create), post to
+ * `/api/public/<slug>` from the browser: see app/api/[...path]/route.ts.
+ */
+export async function laravelPublic(path: string, { revalidate = 300, tags = [] }: PublicRequest = {}): Promise<LaravelResponse> {
+  let response: Response;
+  try {
+    response = await fetch(`${API_URL}/public/${path.replace(/^\/+/, "")}`, {
+      headers: {
+        Accept: "application/json",
+        // The site reading its own data, to show to many: Laravel doesn't count it against
+        // a visitor's allowance, which it otherwise would against this server's address.
+        ...(process.env.NEVELA_PROXY_SECRET ? { "X-Nevela-Proxy-Secret": process.env.NEVELA_PROXY_SECRET } : {}),
+      },
+      next: { revalidate, tags },
+    });
+  } catch {
+    return { status: 502, ok: false, body: { error: "Can't reach the API." } };
+  }
+  const text = response.status === 204 ? "" : await response.text();
+  let parsed: unknown = null;
+  if (text) {
+    try {
+      parsed = JSON.parse(text);
+    } catch {
+      parsed = { error: `Laravel answered ${response.status} with something that isn't JSON.` };
+    }
+  }
+  return { status: response.status, ok: response.ok, body: parsed };
+}