create-nevela 0.4.3 → 0.5.0

package/template/web/components/access/users-toolbar.tsx

@@ -0,0 +1,82 @@
+"use client";
+
+import { usePathname, useRouter, useSearchParams } from "next/navigation";
+import { useEffect, useRef, useState } from "react";
+import { SearchIcon } from "lucide-react";
+import { Input } from "@/components/ui/input";
+import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from "@/components/ui/select";
+
+const ANY = "any";
+
+/**
+ * Search and filters for the list of users. Each one is a query parameter, so a filtered
+ * list has an address of its own and survives a reload.
+ */
+export function UsersToolbar({ roles }: { roles: { id: string; name: string }[] }) {
+  const router = useRouter();
+  const pathname = usePathname();
+  const params = useSearchParams();
+  const [search, setSearch] = useState(params.get("q") ?? "");
+  const typed = useRef(false);
+
+  function go(changes: Record<string, string | null>) {
+    const next = new URLSearchParams(params);
+    for (const [key, value] of Object.entries(changes)) {
+      if (value) next.set(key, value);
+      else next.delete(key);
+    }
+    // Any change of filter starts again from the first page.
+    next.delete("page");
+    router.replace(next.size > 0 ? `${pathname}?${next}` : pathname);
+  }
+
+  // Search as they type, a moment after they stop.
+  useEffect(() => {
+    if (!typed.current) return;
+    const timer = setTimeout(() => go({ q: search.trim() || null }), 300);
+    return () => clearTimeout(timer);
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- only the text starts a search
+  }, [search]);
+
+  return (
+    <div className="flex flex-col gap-2 sm:flex-row sm:items-center">
+      <div className="relative sm:max-w-xs sm:flex-1">
+        <SearchIcon className="pointer-events-none absolute top-1/2 left-2.5 size-4 -translate-y-1/2 text-muted-foreground" />
+        <Input
+          type="search"
+          aria-label="Search users"
+          placeholder="Search by name or email"
+          className="pl-8"
+          value={search}
+          onChange={(event) => {
+            typed.current = true;
+            setSearch(event.target.value);
+          }}
+        />
+      </div>
+      <Select value={params.get("role") ?? ANY} onValueChange={(value) => go({ role: value === ANY ? null : value })}>
+        <SelectTrigger className="sm:w-44" aria-label="Role">
+          <SelectValue />
+        </SelectTrigger>
+        <SelectContent>
+          <SelectItem value={ANY}>Every role</SelectItem>
+          {roles.map((role) => (
+            <SelectItem key={role.id} value={role.id}>
+              {role.name}
+            </SelectItem>
+          ))}
+        </SelectContent>
+      </Select>
+      <Select value={params.get("status") ?? ANY} onValueChange={(value) => go({ status: value === ANY ? null : value })}>
+        <SelectTrigger className="sm:w-40" aria-label="Status">
+          <SelectValue />
+        </SelectTrigger>
+        <SelectContent>
+          <SelectItem value={ANY}>Any status</SelectItem>
+          <SelectItem value="active">Active</SelectItem>
+          <SelectItem value="inactive">Switched off</SelectItem>
+        </SelectContent>
+      </Select>
+    </div>
+  );
+}

package/template/web/components/dashboard/dashboard-sidebar.tsx

@@ -2,7 +2,7 @@
 
 import Link from "next/link";
 import { usePathname, useSearchParams } from "next/navigation";
-import { ActivityIcon, LayoutDashboardIcon, UserCircleIcon } from "lucide-react";
+import { ActivityIcon, LayoutDashboardIcon, ShieldCheckIcon, UserCircleIcon, UsersIcon } from "lucide-react";
 import { ChevronsUpDownIcon } from "lucide-react";
 import { DropdownMenu, DropdownMenuContent, DropdownMenuTrigger } from "@/components/ui/dropdown-menu";
 import {
@@ -63,6 +63,7 @@ export function DashboardSidebar({
   resources,
   links = [],
   isAdmin = false,
+  access = { users: false, roles: false },
   user,
 }: {
   appName: string;
@@ -71,12 +72,19 @@ export function DashboardSidebar({
   links?: Array<{ label: string; href: string; icon: string }>;
   /** Whether to show the sections that manage the app itself. */
   isAdmin?: boolean;
+  /** Which of the screens for managing people this person may open. */
+  access?: { users: boolean; roles: boolean };
   user: DashboardUser;
 }) {
   const pathname = usePathname();
   // A saved view is the query it was saved with, so the one you're on is the one that matches.
   const search = useSearchParams().toString();
-  const manage = [...ACCOUNT_LINKS, ...(isAdmin ? ADMIN_LINKS : [])];
+  const manage = [
+    ...ACCOUNT_LINKS,
+    ...(access.users ? [{ href: "/dashboard/access/users", label: "Users", icon: UsersIcon }] : []),
+    ...(access.roles ? [{ href: "/dashboard/access/roles", label: "Roles", icon: ShieldCheckIcon }] : []),
+    ...(isAdmin ? ADMIN_LINKS : []),
+  ];
 
   return (
     <Sidebar collapsible="icon">

package/template/web/lib/access.ts

@@ -0,0 +1,107 @@
+import { laravel } from "./laravel";
+
+/**
+ * Users, roles and permissions, as Laravel serves them (`/_nevela/users`, `/_nevela/roles`,
+ * `/_nevela/permissions`). Laravel decides who may see and change them; these are the
+ * shapes, and the calls the Users and Roles screens read with.
+ */
+
+export interface ManagedUser {
+  id: string;
+  name: string | null;
+  email: string;
+  /** False when the account is switched off: it can't sign in. */
+  active: boolean;
+  emailVerified: boolean;
+  twoFactorEnabled: boolean;
+  /** The small rendition of their picture, ready for an <img>, or null. */
+  image: string | null;
+  roles: { id: string; name: string }[];
+  /** Holds a role that allows everything. */
+  isAdmin: boolean;
+  /** This is the person looking. */
+  isSelf: boolean;
+  /** Whether the person looking may change this account: it may do no more than they may. */
+  withinYours: boolean;
+  /** How many devices they are signed in on. */
+  devices: number;
+  lastActiveAt: string | null;
+  createdAt: string | null;
+}
+
+export interface ManagedRole {
+  id: string;
+  name: string;
+  description: string | null;
+  /** As written: permissions, and patterns such as "products.*" or "@resources.view". */
+  grants: string[];
+  /** What the grants come to today. */
+  permissions: string[];
+  /** Built in: it can be edited, and not renamed or deleted. */
+  isSystem: boolean;
+  /** Allows everything. */
+  isAdmin: boolean;
+  /** How many people hold it. */
+  users: number;
+  /** Whether the person looking may hand it out or change it: it allows nothing they don't hold. */
+  withinYours: boolean;
+}
+
+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. */
+  actions: string[];
+}
+
+export interface PermissionModule {
+  key: string;
+  name: string;
+  groups: { key: string; name: string; features: PermissionFeature[] }[];
+}
+
+export interface PermissionCatalog {
+  modules: PermissionModule[];
+  /** How many permissions there are in all. */
+  total: number;
+}
+
+export interface UserList {
+  data: ManagedUser[];
+  meta: { page: number; perPage: number; total: number; totalPages: number };
+}
+
+/** What a call answered with when it didn't work, in words for the person. */
+export function accessError(response: { status: number; body: unknown }): string {
+  const body = (response.body ?? {}) as { error?: string; issues?: { message: string }[] };
+  if (body.issues?.length) return body.issues.map((issue) => issue.message).join(" ");
+  return body.error ?? `Something went wrong (${response.status}).`;
+}
+
+export async function listUsers(params: { q?: string; role?: string; status?: string; page?: string }): Promise<UserList | null> {
+  const query = new URLSearchParams();
+  for (const [key, value] of Object.entries(params)) if (value) query.set(key, value);
+  const response = await laravel(`_nevela/users?${query}`);
+  return response.ok ? (response.body as UserList) : null;
+}
+
+export async function getUser(id: string): Promise<ManagedUser | null> {
+  const response = await laravel(`_nevela/users/${encodeURIComponent(id)}`);
+  return response.ok ? (response.body as ManagedUser) : null;
+}
+
+export async function listRoles(): Promise<ManagedRole[]> {
+  const response = await laravel("_nevela/roles");
+  return response.ok ? (response.body as { data: ManagedRole[] }).data : [];
+}
+
+export async function getRole(id: string): Promise<ManagedRole | null> {
+  const response = await laravel(`_nevela/roles/${encodeURIComponent(id)}`);
+  return response.ok ? (response.body as ManagedRole) : null;
+}
+
+export async function getCatalog(): Promise<PermissionCatalog> {
+  const response = await laravel("_nevela/permissions");
+  return response.ok ? (response.body as PermissionCatalog) : { modules: [], total: 0 };
+}

package/template/web/lib/dashboard.ts

@@ -1,6 +1,6 @@
 import { cache } from "react";
 import { notFound, redirect } from "next/navigation";
-import { allowedActions, can, type Policy, type PolicyAction, type Resource } from "@flaredev/core";
+import { can, type Policy, type PolicyAction, type Resource } from "@flaredev/core";
 import { laravelStore, type ResourceStore } from "@/lib/resource";
 import { policies } from "@/policies";
 import { resources } from "@/resources";
@@ -16,23 +16,55 @@ import { getSession } from "./session";
  * (lib/session.ts); nothing here touches a database.
  */
 
-export const ADMIN_ROLES = ["admin", "staff"];
-
 /**
- * A display-only policy for hiding buttons a role can't use. Optional: Laravel's
- * policies (app/Policies) decide what is actually allowed, and a resource without an
- * entry here shows every action and lets Laravel answer 403.
+ * A further display-only policy, by role name (policies/index.ts). Optional, and on top of
+ * the person's permissions: an entry here can hide more, never show more.
  */
 export function policyFor(resourceName: string): Policy | undefined {
   return (policies as Record<string, Policy | undefined>)[resourceName];
 }
 
+/** What each of the dashboard's actions is called as a permission. */
+const VERB: Record<PolicyAction, string> = { list: "view", read: "view", create: "create", update: "edit", delete: "delete" };
+
+/** The permission an action on a resource asks for: "products.edit". */
+export function permissionFor(resource: Resource, action: PolicyAction): string {
+  return `${resource.table}.${VERB[action]}`;
+}
+
+/**
+ * The signed-in person and what they may do.
+ *
+ * `may("products.view")` answers from the permissions Laravel worked out from their roles.
+ * It is for showing and hiding: Laravel decides every request again for itself, so nothing
+ * here is what keeps anyone out.
+ */
 export async function dashboardSession() {
   const session = await getSession();
-  if (!session) return { session: null, role: null, allowed: false } as const;
-  const role = session.user.role ?? null;
-  const readable = allResources().some((resource) => can(policyFor(resource.name), role, "read"));
-  return { session, role, allowed: (role !== null && ADMIN_ROLES.includes(role)) || readable } as const;
+  if (!session) return { session: null, role: null, roles: [] as string[], allowed: false, isAdmin: false, may: () => false } as const;
+  const { user } = session;
+  // An API from before roles sends no list. Everyone could do everything then, and still can.
+  const everything = user.permissions === undefined || user.isAdmin === true;
+  const held = new Set(user.permissions ?? []);
+  const may = (permission: string) => everything || held.has(permission);
+  // Anyone signed in has a dashboard, if only for their own account.
+  return { session, role: user.role ?? null, roles: user.roles ?? (user.role ? [user.role] : []), allowed: true, isAdmin: everything, may } as const;
+}
+
+/** Whether the current person may do `action` on a resource: their permissions, and the display policy if there is one. */
+export async function mayDo(resource: Resource, action: PolicyAction): Promise<boolean> {
+  const { session, roles, may } = await dashboardSession();
+  if (!session || !may(permissionFor(resource, action))) return false;
+  const policy = policyFor(resource.name);
+  return !policy || roles.some((role) => can(policy, role, action)) || (roles.length === 0 && can(policy, null, action));
+}
+
+/** For a page that needs one permission: sends anyone without it back to the dashboard. */
+export async function requirePermission(permission: string, returnTo = "/dashboard") {
+  const { session, may } = await dashboardSession();
+  if (!session) redirect(`/sign-in?next=${encodeURIComponent(returnTo)}`);
+  if (!may(permission)) redirect("/dashboard?error=forbidden");
+  return { session, may };
 }
 
 /** For admin pages: redirects signed-out visitors to sign-in and users without access to the home page. */
@@ -50,17 +82,18 @@ export async function requireDashboard(returnTo = "/dashboard") {
  */
 export async function requireAccess(resource: Resource, action: PolicyAction) {
   const { session, role } = await requireDashboard(resourcePath(resource));
-  const policy = policyFor(resource.name);
-  if (!can(policy, role, action)) {
-    redirect(action !== "read" && can(policy, role, "read") ? resourcePath(resource) : "/dashboard?error=forbidden");
+  if (!(await mayDo(resource, action))) {
+    redirect(action !== "read" && (await mayDo(resource, "read")) ? resourcePath(resource) : "/dashboard?error=forbidden");
   }
   return { session, role };
 }
 
 /** What the current user may do with a resource, for hiding actions they can't use. */
-export async function adminPermissions(resourceName: string) {
-  const { role } = await dashboardSession();
-  return allowedActions(policyFor(resourceName), role);
+export async function adminPermissions(resourceName: string): Promise<Record<Exclude<PolicyAction, "list">, boolean>> {
+  const resource = allResources().find((item) => item.name === resourceName);
+  if (!resource) return { read: false, create: false, update: false, delete: false };
+  const [read, create, update, remove] = await Promise.all((["read", "create", "update", "delete"] as const).map((action) => mayDo(resource, action)));
+  return { read: read!, create: create!, update: update!, delete: remove! };
 }
 
 const stores = new Map<string, ResourceStore>();
@@ -121,8 +154,8 @@ export function allResources(): Resource[] {
 
 /** Resources the current user may read, for the sidebar and dashboard. */
 export async function visibleResources(): Promise<Resource[]> {
-  const { role } = await dashboardSession();
-  return allResources().filter((resource) => can(policyFor(resource.name), role, "read"));
+  const visible = await Promise.all(allResources().map((resource) => mayDo(resource, "read")));
+  return allResources().filter((_, index) => visible[index]);
 }
 
 export function resourcePath(resource: Resource, ...parts: string[]) {

package/template/web/lib/session.ts

@@ -6,7 +6,18 @@ export interface SessionUser {
   id: string;
   name: string | null;
   email: string;
+  /** The first of their roles, from when an account had one. */
   role: string | null;
+  /** The names of their roles. */
+  roles?: string[];
+  /**
+   * Everything they may do, as "feature.action" ("products.view"). Laravel works it out
+   * from their roles; lib/dashboard.ts uses it to hide what they can't use. Missing when
+   * the API is from before roles, when everyone could do everything.
+   */
+  permissions?: string[];
+  /** Whether their roles come to everything. */
+  isAdmin?: boolean;
   emailVerified: boolean;
   twoFactorEnabled: boolean;
   /** The key of the profile picture (an optimised upload), or null. Show it with fileUrl(). */

package/template/web/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nevela-web",
-  "version": "0.4.3",
+  "version": "0.5.0",
   "private": true,
   "type": "module",
   "scripts": {