@flaredev/cli 0.1.0

package/templates/app/components/admin/fields/relation-field.tsx

@@ -0,0 +1,132 @@
+"use client";
+
+import { useEffect, useState } from "react";
+import { CheckIcon, ChevronsUpDownIcon, XIcon } from "lucide-react";
+import { Button } from "@/components/ui/button";
+import { Command, CommandEmpty, CommandGroup, CommandInput, CommandItem, CommandList } from "@/components/ui/command";
+import { Popover, PopoverContent, PopoverTrigger } from "@/components/ui/popover";
+import { Spinner } from "@/components/ui/spinner";
+import { cn } from "@/lib/utils";
+import type { RelationMeta } from "./field-widget";
+
+interface Option {
+  id: string;
+  title: string;
+}
+
+interface Props {
+  id: string;
+  value: string;
+  onChange: (value: string) => void;
+  invalid: boolean;
+  disabled?: boolean;
+  required: boolean;
+  relation: RelationMeta & { initialTitle?: string };
+}
+
+/**
+ * Picker for a `belongsTo` field: searches the related resource through its generated
+ * REST API (so the same authorization applies) and stores the chosen record's id.
+ */
+export function RelationField({ id, value, onChange, invalid, disabled, required, relation }: Props) {
+  const [open, setOpen] = useState(false);
+  const [query, setQuery] = useState("");
+  const [options, setOptions] = useState<Option[]>([]);
+  const [loading, setLoading] = useState(false);
+  const [title, setTitle] = useState(relation.initialTitle ?? "");
+
+  useEffect(() => {
+    if (!open) return;
+    const controller = new AbortController();
+    const timer = setTimeout(async () => {
+      setLoading(true);
+      try {
+        const search = new URLSearchParams({ perPage: "20", sort: relation.titleField });
+        if (query.trim()) search.set("q", query.trim());
+        const response = await fetch(`/api/${relation.slug}?${search}`, { signal: controller.signal, credentials: "same-origin" });
+        if (!response.ok) throw new Error(String(response.status));
+        const body = (await response.json()) as { data: Record<string, unknown>[] };
+        setOptions(body.data.map((row) => ({ id: String(row.id), title: String(row[relation.titleField] ?? row.id) })));
+      } catch (error) {
+        if ((error as Error).name !== "AbortError") setOptions([]);
+      } finally {
+        setLoading(false);
+      }
+    }, 200);
+    return () => {
+      controller.abort();
+      clearTimeout(timer);
+    };
+  }, [open, query, relation.slug, relation.titleField]);
+
+  return (
+    <div className="flex items-center gap-1">
+      <Popover open={open} onOpenChange={setOpen}>
+        <PopoverTrigger asChild>
+          <Button
+            id={id}
+            type="button"
+            variant="outline"
+            role="combobox"
+            aria-expanded={open}
+            aria-invalid={invalid || undefined}
+            disabled={disabled}
+            className={cn("w-full justify-between font-normal", !value && "text-muted-foreground")}
+          >
+            {value ? (title || value) : `Choose ${relation.label.toLowerCase()}`}
+            <ChevronsUpDownIcon className="opacity-50" />
+          </Button>
+        </PopoverTrigger>
+        <PopoverContent className="w-(--radix-popover-trigger-width) p-0" align="start">
+          <Command shouldFilter={false}>
+            <CommandInput
+              placeholder={`Search ${relation.pluralLabel.toLowerCase()}…`}
+              value={query}
+              onValueChange={setQuery}
+            />
+            <CommandList>
+              {loading ? (
+                <div className="flex items-center justify-center gap-2 py-6 text-sm text-muted-foreground">
+                  <Spinner /> Searching…
+                </div>
+              ) : (
+                <CommandEmpty>No {relation.pluralLabel.toLowerCase()} found.</CommandEmpty>
+              )}
+              <CommandGroup>
+                {options.map((option) => (
+                  <CommandItem
+                    key={option.id}
+                    value={option.id}
+                    onSelect={() => {
+                      onChange(option.id);
+                      setTitle(option.title);
+                      setOpen(false);
+                    }}
+                  >
+                    {option.title}
+                    <CheckIcon className={cn("ml-auto", option.id === value ? "opacity-100" : "opacity-0")} />
+                  </CommandItem>
+                ))}
+              </CommandGroup>
+            </CommandList>
+          </Command>
+        </PopoverContent>
+      </Popover>
+      {value && !required && (
+        <Button
+          type="button"
+          variant="ghost"
+          size="icon"
+          aria-label={`Clear ${relation.label.toLowerCase()}`}
+          disabled={disabled}
+          onClick={() => {
+            onChange("");
+            setTitle("");
+          }}
+        >
+          <XIcon />
+        </Button>
+      )}
+    </div>
+  );
+}

package/templates/app/components/admin/query.ts

@@ -0,0 +1,25 @@
+export type SearchParams = Record<string, string | string[] | undefined>;
+
+export function toSearchParams(params: SearchParams): URLSearchParams {
+  const search = new URLSearchParams();
+  for (const [key, value] of Object.entries(params)) {
+    if (Array.isArray(value)) value.forEach((item) => search.append(key, item));
+    else if (value !== undefined) search.set(key, value);
+  }
+  return search;
+}
+
+/**
+ * `path?query` with `changes` applied (`null` removes a param). Changing anything other
+ * than the page resets pagination, so results never start on a page that no longer exists.
+ */
+export function hrefWith(path: string, current: URLSearchParams, changes: Record<string, string | null>): string {
+  const next = new URLSearchParams(current);
+  for (const [key, value] of Object.entries(changes)) {
+    if (value === null || value === "") next.delete(key);
+    else next.set(key, value);
+  }
+  if (!("page" in changes)) next.delete("page");
+  const query = next.toString();
+  return query ? `${path}?${query}` : path;
+}

package/templates/app/components/admin/resource-form-page.tsx

@@ -0,0 +1,55 @@
+import { notFound } from "next/navigation";
+import { formatValue, storedFields, type Resource } from "@flaredev/core";
+import { adminPath, adminResources, adminStore, requireAccess } from "@/lib/admin";
+import type { RelationMeta } from "./fields/field-widget";
+import { ResourceForm } from "./resource-form";
+
+/** Server wrapper for create/edit pages: loads the record and relation titles, renders the heading and form. */
+export async function ResourceFormPage({ resource, id }: { resource: Resource; id?: string }) {
+  await requireAccess(resource, id ? "update" : "create");
+  let record: Record<string, unknown> | null = null;
+  if (id) {
+    const result = await adminStore(resource.name).get(id);
+    if (!result.ok) notFound();
+    record = result.data;
+  }
+
+  const byName = new Map(adminResources().map((r) => [r.name, r]));
+  const relations: Record<string, RelationMeta & { initialTitle?: string }> = {};
+  for (const [key, def] of storedFields(resource)) {
+    if (def.kind !== "belongsTo") continue;
+    const target = byName.get(def.target);
+    if (!target) continue;
+    const value = record?.[key];
+    const titles = typeof value === "string" ? await adminStore(target.name).titles([value]) : {};
+    relations[key] = {
+      name: target.name,
+      label: target.label,
+      pluralLabel: target.pluralLabel,
+      slug: target.slug,
+      titleField: target.titleField,
+      initialTitle: typeof value === "string" ? titles[value] : undefined,
+    };
+  }
+
+  const titleDef = resource.fields[resource.titleField];
+  const title =
+    record && titleDef && titleDef.kind !== "hasMany" ? formatValue(titleDef, record[resource.titleField]) : `New ${resource.label.toLowerCase()}`;
+
+  return (
+    <div className="flex flex-col gap-6">
+      <div className="flex flex-col gap-1">
+        <h1 className="text-2xl font-semibold">{title}</h1>
+        {record && <p className="text-xs text-muted-foreground">Edit {resource.label.toLowerCase()}</p>}
+      </div>
+      <ResourceForm
+        resource={resource}
+        mode={record ? "edit" : "create"}
+        id={id}
+        record={record}
+        relations={relations}
+        listHref={adminPath(resource)}
+      />
+    </div>
+  );
+}

package/templates/app/components/admin/resource-form.tsx

@@ -0,0 +1,139 @@
+"use client";
+
+import Link from "next/link";
+import { useRouter } from "next/navigation";
+import { useMemo, useState, useTransition, type FormEvent } from "react";
+import { createValidators, formValuesToInput, initialFormValues, issuesByField, storedFields, type Resource } from "@flaredev/core";
+import { toast } from "sonner";
+import { createRecordAction, updateRecordAction } from "@/app/admin/actions";
+import { Alert, AlertDescription } from "@/components/ui/alert";
+import { Button } from "@/components/ui/button";
+import { Card, CardContent, CardFooter } from "@/components/ui/card";
+import { Field, FieldDescription, FieldError, FieldGroup, FieldLabel } from "@/components/ui/field";
+import { Spinner } from "@/components/ui/spinner";
+import { FieldWidget, type RelationMeta } from "./fields/field-widget";
+
+export interface ResourceFormProps {
+  resource: Resource;
+  mode: "create" | "edit";
+  /** Record id (edit mode). */
+  id?: string;
+  record?: Record<string, unknown> | null;
+  /** belongsTo field key → related resource metadata and the current value's title. */
+  relations?: Record<string, RelationMeta & { initialTitle?: string }>;
+  /** Where Cancel and a successful save go. */
+  listHref: string;
+}
+
+const WIDE = new Set(["text", "file"]);
+
+/**
+ * Create/edit form rendered from field metadata. Values are validated in the browser
+ * with the descriptor's zod schemas, then again on the server by the same store the
+ * REST API uses; server errors (e.g. unique conflicts) land on their fields.
+ */
+export function ResourceForm({ resource, mode, id, record, relations = {}, listHref }: ResourceFormProps) {
+  const router = useRouter();
+  const validators = useMemo(() => createValidators(resource), [resource]);
+  const fields = useMemo(() => storedFields(resource), [resource]);
+  const [values, setValues] = useState(() => initialFormValues(resource, record));
+  const [errors, setErrors] = useState<Record<string, string>>({});
+  const [pending, startTransition] = useTransition();
+
+  const setValue = (key: string, value: string | boolean) => {
+    setValues((current) => ({ ...current, [key]: value }));
+    if (errors[key]) setErrors(({ [key]: _removed, ...rest }) => rest);
+  };
+
+  function focusFirstError(fieldErrors: Record<string, string>) {
+    const first = fields.find(([key]) => fieldErrors[key]);
+    if (first) document.getElementById(`field-${first[0]}`)?.focus();
+  }
+
+  function onSubmit(event: FormEvent) {
+    event.preventDefault();
+    const input = formValuesToInput(resource, values, mode);
+    const parsed = (mode === "create" ? validators.create : validators.update).safeParse(input);
+    if (!parsed.success) {
+      const fieldErrors = issuesByField(parsed.error.issues);
+      setErrors(fieldErrors);
+      focusFirstError(fieldErrors);
+      return;
+    }
+
+    startTransition(async () => {
+      const result = mode === "create" ? await createRecordAction(resource.name, input) : await updateRecordAction(resource.name, id!, input);
+      if (result.ok) {
+        toast.success(`${resource.label} ${mode === "create" ? "created" : "saved"}.`);
+        router.push(listHref);
+        router.refresh();
+        return;
+      }
+      const fieldErrors = result.issues ? issuesByField(result.issues) : result.field ? { [result.field]: result.error } : { _form: result.error };
+      setErrors(fieldErrors);
+      focusFirstError(fieldErrors);
+    });
+  }
+
+  return (
+    <form onSubmit={onSubmit} noValidate>
+      <Card>
+        <CardContent>
+          {errors._form && (
+            <Alert variant="destructive" className="mb-6">
+              <AlertDescription>{errors._form}</AlertDescription>
+            </Alert>
+          )}
+          <FieldGroup className="grid gap-6 md:grid-cols-2">
+            {fields.map(([key, def]) => {
+              const error = errors[key];
+              const widgetId = `field-${key}`;
+              const horizontal = def.kind === "boolean";
+              return (
+                <Field
+                  key={key}
+                  data-invalid={error ? true : undefined}
+                  className={WIDE.has(def.kind) ? "md:col-span-2" : undefined}
+                >
+                  <FieldLabel htmlFor={widgetId}>
+                    {def.label}
+                    {def.required && def.kind !== "boolean" && (
+                      <span className="ml-0.5 text-muted-foreground" aria-hidden>
+                        *
+                      </span>
+                    )}
+                  </FieldLabel>
+                  <div className={horizontal ? "flex h-9 items-center" : undefined}>
+                    <FieldWidget
+                      id={widgetId}
+                      name={key}
+                      resourceName={resource.name}
+                      fieldKey={key}
+                      field={def}
+                      value={values[key] ?? ""}
+                      onChange={(value) => setValue(key, value)}
+                      invalid={Boolean(error)}
+                      disabled={pending}
+                      relation={relations[key]}
+                    />
+                  </div>
+                  {def.helpText && <FieldDescription>{def.helpText}</FieldDescription>}
+                  {error && <FieldError>{error}</FieldError>}
+                </Field>
+              );
+            })}
+          </FieldGroup>
+        </CardContent>
+        <CardFooter className="justify-end gap-2 border-t">
+          <Button variant="outline" asChild>
+            <Link href={listHref}>Cancel</Link>
+          </Button>
+          <Button type="submit" disabled={pending}>
+            {pending && <Spinner data-icon="inline-start" />}
+            {mode === "create" ? `Create ${resource.label.toLowerCase()}` : "Save changes"}
+          </Button>
+        </CardFooter>
+      </Card>
+    </form>
+  );
+}

package/templates/app/components/admin/resource-icon.tsx

@@ -0,0 +1,85 @@
+import {
+  BellIcon,
+  BookIcon,
+  BoxIcon,
+  BriefcaseIcon,
+  Building2Icon,
+  CalendarIcon,
+  ChartBarIcon,
+  ClipboardListIcon,
+  CreditCardIcon,
+  DatabaseIcon,
+  DollarSignIcon,
+  FileTextIcon,
+  FolderIcon,
+  GlobeIcon,
+  HeartIcon,
+  ImageIcon,
+  LayersIcon,
+  MailIcon,
+  MapPinIcon,
+  MessageSquareIcon,
+  PackageIcon,
+  PhoneIcon,
+  ReceiptIcon,
+  SettingsIcon,
+  ShieldAlertIcon,
+  RadioIcon,
+  ShieldIcon,
+  ShoppingCartIcon,
+  StarIcon,
+  TagIcon,
+  TicketIcon,
+  TruckIcon,
+  UserIcon,
+  UsersIcon,
+  WrenchIcon,
+  type LucideIcon,
+} from "lucide-react";
+
+/**
+ * Icons a resource descriptor can name (`icon: "users"`). Imported by name so unused
+ * ones are tree-shaken; add the lucide icons your app needs.
+ */
+export const RESOURCE_ICONS: Record<string, LucideIcon> = {
+  bell: BellIcon,
+  book: BookIcon,
+  box: BoxIcon,
+  briefcase: BriefcaseIcon,
+  building: Building2Icon,
+  calendar: CalendarIcon,
+  chart: ChartBarIcon,
+  clipboard: ClipboardListIcon,
+  "credit-card": CreditCardIcon,
+  database: DatabaseIcon,
+  dollar: DollarSignIcon,
+  file: FileTextIcon,
+  folder: FolderIcon,
+  globe: GlobeIcon,
+  heart: HeartIcon,
+  image: ImageIcon,
+  layers: LayersIcon,
+  mail: MailIcon,
+  "map-pin": MapPinIcon,
+  message: MessageSquareIcon,
+  package: PackageIcon,
+  phone: PhoneIcon,
+  receipt: ReceiptIcon,
+  settings: SettingsIcon,
+  radio: RadioIcon,
+  shield: ShieldIcon,
+  "shield-alert": ShieldAlertIcon,
+  cart: ShoppingCartIcon,
+  star: StarIcon,
+  tag: TagIcon,
+  ticket: TicketIcon,
+  truck: TruckIcon,
+  user: UserIcon,
+  users: UsersIcon,
+  wrench: WrenchIcon,
+};
+
+/** The icon for a resource, falling back to a generic document icon. */
+export function resourceIcon(name: string | undefined): LucideIcon {
+  return (name && RESOURCE_ICONS[name]) || FileTextIcon;
+}

package/templates/app/components/admin/resource-nav.tsx

@@ -0,0 +1,109 @@
+"use client";
+
+import Link from "next/link";
+import { usePathname } from "next/navigation";
+import { LayoutDashboardIcon } from "lucide-react";
+import {
+  Sidebar,
+  SidebarContent,
+  SidebarGroup,
+  SidebarGroupContent,
+  SidebarGroupLabel,
+  SidebarHeader,
+  SidebarMenu,
+  SidebarMenuButton,
+  SidebarMenuItem,
+} from "@/components/ui/sidebar";
+import { resourceIcon } from "./resource-icon";
+
+export interface NavResource {
+  name: string;
+  pluralLabel: string;
+  slug: string;
+  icon?: string;
+  /** Optional count badge (off by default). */
+  badge?: number;
+}
+
+/**
+ * Sidebar navigation, one item per registered resource. The icon comes from the
+ * descriptor's `icon`, the label from its plural label, and the active item from the
+ * current path.
+ */
+export function ResourceNav({
+  appName,
+  resources,
+  links = [],
+}: {
+  appName: string;
+  resources: NavResource[];
+  /** Extra pages (see lib/admin-nav.ts), shown under "Platform". */
+  links?: Array<{ label: string; href: string; icon: string }>;
+}) {
+  const pathname = usePathname();
+
+  return (
+    <Sidebar collapsible="icon">
+      <SidebarHeader>
+        <SidebarMenu>
+          <SidebarMenuItem>
+            <SidebarMenuButton asChild size="lg" tooltip={appName}>
+              <Link href="/admin">
+                <div className="flex aspect-square size-8 items-center justify-center rounded-md bg-primary text-primary-foreground">
+                  <LayoutDashboardIcon className="size-4" />
+                </div>
+                <span className="truncate font-semibold">{appName}</span>
+              </Link>
+            </SidebarMenuButton>
+          </SidebarMenuItem>
+        </SidebarMenu>
+      </SidebarHeader>
+
+      <SidebarContent>
+        <SidebarGroup>
+          <SidebarGroupLabel>Resources</SidebarGroupLabel>
+          <SidebarGroupContent>
+            <SidebarMenu>
+              {resources.map((resource) => {
+                const href = `/admin/${resource.slug}`;
+                const Icon = resourceIcon(resource.icon);
+                return (
+                  <SidebarMenuItem key={resource.name}>
+                    <SidebarMenuButton asChild isActive={pathname === href || pathname.startsWith(`${href}/`)} tooltip={resource.pluralLabel}>
+                      <Link href={href}>
+                        <Icon />
+                        <span>{resource.pluralLabel}</span>
+                      </Link>
+                    </SidebarMenuButton>
+                  </SidebarMenuItem>
+                );
+              })}
+            </SidebarMenu>
+          </SidebarGroupContent>
+        </SidebarGroup>
+        {links.length > 0 && (
+          <SidebarGroup>
+            <SidebarGroupLabel>Platform</SidebarGroupLabel>
+            <SidebarGroupContent>
+              <SidebarMenu>
+                {links.map((link) => {
+                  const Icon = resourceIcon(link.icon);
+                  return (
+                    <SidebarMenuItem key={link.href}>
+                      <SidebarMenuButton asChild isActive={pathname === link.href || pathname.startsWith(`${link.href}/`)} tooltip={link.label}>
+                        <Link href={link.href}>
+                          <Icon />
+                          <span>{link.label}</span>
+                        </Link>
+                      </SidebarMenuButton>
+                    </SidebarMenuItem>
+                  );
+                })}
+              </SidebarMenu>
+            </SidebarGroupContent>
+          </SidebarGroup>
+        )}
+      </SidebarContent>
+    </Sidebar>
+  );
+}

package/templates/app/components/admin/resource-table-toolbar.tsx

@@ -0,0 +1,95 @@
+"use client";
+
+import { usePathname, useRouter, useSearchParams } from "next/navigation";
+import { useState, type FormEvent } from "react";
+import { SearchIcon, XIcon } from "lucide-react";
+import { optionLabel, storedFields, type Resource } from "@flaredev/core";
+import { Button } from "@/components/ui/button";
+import { InputGroup, InputGroupAddon, InputGroupInput } from "@/components/ui/input-group";
+import { Select, SelectContent, SelectGroup, SelectItem, SelectTrigger, SelectValue } from "@/components/ui/select";
+import { hrefWith } from "./query";
+
+const ALL = "__all__";
+
+/** Search box and enum/boolean filters for ResourceTable; all state goes into the URL. */
+export function ResourceTableToolbar({ resource }: { resource: Resource }) {
+  const router = useRouter();
+  const pathname = usePathname();
+  const params = new URLSearchParams(useSearchParams().toString());
+  const [q, setQ] = useState(params.get("q") ?? "");
+
+  const fields = storedFields(resource);
+  const searchable = fields.some(([, def]) => def.searchable ?? def.kind === "string");
+  // Relation filters need a lookup UI; the toolbar offers the ones with fixed options.
+  const filters = fields.filter(([, def]) => (def.filterable ?? ["enum", "boolean"].includes(def.kind)) && ["enum", "boolean"].includes(def.kind));
+  const hasActive = params.has("q") || [...params.keys()].some((key) => key.startsWith("filter["));
+
+  const go = (changes: Record<string, string | null>) => router.push(hrefWith(pathname, params, changes));
+
+  function onSearch(event: FormEvent) {
+    event.preventDefault();
+    go({ q: q.trim() || null });
+  }
+
+  if (!searchable && filters.length === 0) return null;
+
+  return (
+    <div className="flex flex-wrap items-center gap-2">
+      {searchable && (
+        <form onSubmit={onSearch} role="search" className="w-full sm:w-72">
+          <InputGroup>
+            <InputGroupAddon>
+              <SearchIcon />
+            </InputGroupAddon>
+            <InputGroupInput
+              type="search"
+              value={q}
+              onChange={(event) => setQ(event.target.value)}
+              placeholder={`Search ${resource.pluralLabel.toLowerCase()}…`}
+              aria-label={`Search ${resource.pluralLabel.toLowerCase()}`}
+            />
+          </InputGroup>
+        </form>
+      )}
+
+      {filters.map(([key, def]) => {
+        const param = `filter[${key}]`;
+        const options = def.kind === "enum" ? def.options.map((value) => ({ value, label: optionLabel(def, value) })) : [
+          { value: "true", label: "Yes" },
+          { value: "false", label: "No" },
+        ];
+        return (
+          <Select key={key} value={params.get(param) ?? ALL} onValueChange={(value) => go({ [param]: value === ALL ? null : value })}>
+            <SelectTrigger className="min-w-36" aria-label={`Filter by ${def.label}`}>
+              <span className="text-muted-foreground">{def.label}:</span>
+              <SelectValue />
+            </SelectTrigger>
+            <SelectContent>
+              <SelectGroup>
+                <SelectItem value={ALL}>Any</SelectItem>
+                {options.map((option) => (
+                  <SelectItem key={option.value} value={option.value}>
+                    {option.label}
+                  </SelectItem>
+                ))}
+              </SelectGroup>
+            </SelectContent>
+          </Select>
+        );
+      })}
+
+      {hasActive && (
+        <Button
+          variant="ghost"
+          onClick={() => {
+            setQ("");
+            router.push(pathname);
+          }}
+        >
+          <XIcon data-icon="inline-start" />
+          Clear
+        </Button>
+      )}
+    </div>
+  );
+}