create-nevela 0.5.0 → 0.5.2

package/README.md

@@ -1,6 +1,13 @@
 # create-nevela
 
-Create a new [Nevela](https://nevela-docs.vercel.app) app: a Laravel API and a Next.js dashboard, generated from one resource description.
+The `nevela` command. It creates a new [Nevela](https://nevela-docs.vercel.app) app, a Laravel API and a Next.js dashboard generated from one resource description, and runs everything inside one.
+
+```sh
+npm install -g create-nevela    # once
+nevela new my-app
+```
+
+Or without installing anything:
 
 ```sh
 pnpm create nevela my-app
@@ -16,41 +23,35 @@ You need PHP 8.3 or newer, Composer, and Node.js 20 or newer.
 my-app/
 ├─ apps/api/    a Laravel app with Sanctum and Nevela installed
 ├─ apps/web/    the Next.js dashboard, pointed at the API
-└─ nevela       every command, from this folder: php nevela
+└─ nevela       the app's own launcher: php nevela does what nevela does
 ```
 
 Then:
 
 ```sh
 cd my-app
-php nevela dev
+nevela dev
 ```
 
-Open http://localhost:3000/sign-in and sign in as `admin@example.com` with the password `password`. That starter account is in your local database only; add your own with `php artisan nevela:user`.
+Open http://localhost:3000/sign-in and sign in as `admin@example.com` with the password `password`. That starter account is in your local database only; add your own with `nevela user`.
 
 The app starts with an administrator and ten sample users (two editors, eight users), in your local database only, so its Users and Roles screens have something to show. Leave the samples out with `--no-sample-users`.
 
 Add your first resource, from the same folder:
 
 ```sh
-php nevela resource Product --fields="name:string, sku:string!, price:money"
+nevela resource Product --fields="name:string, sku:string!, price:money"
 ```
 
-That writes the Laravel code and the dashboard pages, and creates the table. `php nevela` lists everything else.
+That writes the Laravel code and the dashboard pages, and creates the table. `nevela` on its own lists everything else.
 
-## The nevela command
-
-Install this package once and you have a `nevela` command, in every shell:
-
-```sh
-npm install -g create-nevela
-```
+## Every command
 
 ```sh
 nevela                 # anywhere: everything it can do
 nevela new my-app      # anywhere: create an app (leave the name off and it asks)
 nevela update          # anywhere: update the nevela command itself
-nevela version         # anywhere: the command's version, and the app's when in one
+nevela --version       # anywhere: the command's version, and the app's when in one
 nevela dev             # inside an app: run the API and the dashboard
 nevela upgrade         # inside an app: bring it to the latest Nevela
 ```
@@ -79,7 +80,7 @@ Without the command installed, `npx create-nevela upgrade` does the same, in any
 | `--bundled-package` | Use the copy of `nevela/laravel` inside this installer instead of the release on Packagist. |
 | `-y`, `--yes` | Ask nothing. Only the app name is ever asked for. |
 
-With npm, put options after `--`: `npm create nevela@latest my-app -- --no-install`.
+Through npm's `create`, put options after `--`: `npm create nevela@latest my-app -- --no-install`.
 
 ## How it installs the Laravel package
 

package/index.mjs

@@ -68,14 +68,14 @@ const HELP = `  Create a new Nevela app: a Laravel API and a Next.js dashboard.
     nevela new [name] [options]   Create an app. It asks for the name if you leave it off.
                                   Without the command: pnpm create nevela <name>
     nevela update                 Update the nevela command itself to the latest version
-    nevela version                Which version the nevela command is, and this app when in one
+    nevela --version              Which version the nevela command is, and this app when in one
 
   ${bold('Inside an app')}
     nevela upgrade             Bring this app to the latest Nevela: the package and the dashboard
     nevela dev                 Run the API and the dashboard
     nevela status              Check versions, migrations, users and the dashboard
     nevela resource <Name> --fields="…" [--seed]
-    nevela seed | user | generate | version | migrate | artisan <command>
+    nevela seed | user | generate | migrate | artisan <command>
 
   ${bold('Options')}
     --pm <pnpm|npm|yarn|bun>   Package manager for the dashboard. Default: the one you ran this with.
@@ -89,7 +89,7 @@ const HELP = `  Create a new Nevela app: a Laravel API and a Next.js dashboard.
                                instead of the release on Packagist.
     -y, --yes                  Ask nothing. (Only the app name is ever asked for.)
     -h, --help                 Show this.
-    -v, --version              Show the version.
+    -v, --version              Show the version. Piped or captured, the number alone.
 
   ${bold('Needs')}  PHP 8.3+, Composer, Node.js 20+
   ${bold('Docs')}   ${DOCS}
@@ -361,6 +361,10 @@ async function inProject(name, args) {
   }
   if (name !== 'upgrade') process.exit(forward(project, name, args));
 
+  // The name first, before anything that waits on the network. A newer installer this
+  // one hands over to knows it has been shown, and prints one line in its place.
+  showTitle();
+
   // Upgrading is the one command that must not run on stale code itself: it is the newest
   // installer that knows what an older app needs repaired. So even a nevela command that
   // hasn't been updated in a while upgrades an app correctly.
@@ -371,9 +375,18 @@ async function inProject(name, args) {
       if (status !== null) process.exit(status);
     }
   }
-  console.log(`\n  ${indigo(bold('Nevela'))} ${dim('upgrade')}\n`);
+  const before = appVersion(project);
+  const looking = args.includes('--check') ? ' (checking only: nothing will be changed)' : '';
+  console.log(`  ${indigo(`Nevela upgrade — this app: ${before ? `v${before}` : 'Nevela not installed in it yet'}`)}${dim(looking)}\n`);
   const releases = await latestRelease();
   const status = await upgrade(project, args, { latest: releases, say: (line) => console.log(`  ${green('✔')} ${line}`) });
+  // Where it ended up, read from the app itself and not from what was asked for.
+  if (status === 0 && !args.includes('--check') && !args.includes('--undo')) {
+    const now = appVersion(project);
+    if (now) {
+      console.log(`\n  ${green(`✔ ${now === before ? `This app is on Nevela v${now}, the version it was on.` : `This app is now on Nevela v${now}.`}`)}\n`);
+    }
+  }
   process.exit(status);
 }
 
@@ -445,7 +458,10 @@ function appVersion(project) {
   }
 }
 
-/** `nevela version`, from anywhere: the command's version, and the app's when in one. */
+/**
+ * `nevela --version`, from anywhere: the command's version, and the app's when in one.
+ * `nevela version` is the same thing by its older name.
+ */
 function showVersion() {
   const project = findProject(process.cwd());
   const install = installed();
@@ -574,6 +590,13 @@ async function main() {
   if (argv[0] === 'new') argv.shift();
   else if (argv[0] === 'update') return updateTool(argv.slice(1));
   else if (argv[0] === 'version') return showVersion();
+  else if ((argv[0] === '--version' || argv[0] === '-v') && argv.length === 1) {
+    // To a person, the whole answer. To a script (and to `nevela update`, which asks
+    // this of the installed command to check its work), the number and nothing else.
+    if (process.stdout.isTTY) return showVersion();
+    console.log(VERSION);
+    return;
+  }
   else if (COMMANDS.includes(argv[0])) await inProject(argv[0], argv.slice(1));
   else if (argv[0] === 'help' || (startedAsNevela && argv.length === 0)) {
     // `nevela` on its own says what it can do. `pnpm create nevela` on its own starts an

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-nevela",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "description": "Create a new Nevela app: a Laravel API and a Next.js dashboard from one resource description.",
   "type": "module",
   "bin": {

package/template/laravel/README.md

@@ -3,18 +3,20 @@
 The Laravel side of [Nevela](https://nevela-docs.vercel.app): describe a resource once and get its model, migration, validation, policy and REST API, plus the Next.js dashboard screens for it.
 
 ```sh
-php artisan nevela:resource Product --fields="name:string, sku:string!, price:money, kind:enum(stock|digital), notes:text?"
-php artisan migrate
+nevela resource Product --fields="name:string, sku:string!, price:money, kind:enum(stock|digital), notes:text?"
 ```
 
 ## Start a new app
 
-The quickest way is the create command, which sets up Laravel, this package and the dashboard together:
+The quickest way is the `nevela` command, which sets up Laravel, this package and the dashboard together:
 
 ```sh
-pnpm create nevela my-app
+npm install -g create-nevela    # once
+nevela new my-app
 ```
 
+Without installing it, `pnpm create nevela my-app` does the same.
+
 ## Add it to an existing Laravel app
 
 ```sh

package/template/laravel/config/nevela.php

@@ -114,6 +114,12 @@ return [
     'per_page' => 25,
     'max_per_page' => 100,
 
+    /*
+    | The most rows POST /{slug}/_bulk creates in one request (the dashboard's "Add several"
+    | grid). They are saved in one transaction, so this is also how long one can run.
+    */
+    'bulk_max' => 500,
+
     /*
     | File and image fields (image:image, manual:file(pdf)).
     |

package/template/laravel/src/Generator/ResourceGenerator.php

@@ -382,6 +382,8 @@ final class ResourceGenerator
         foreach ($all as $d) {
             $controller = "\\App\\Http\\Controllers\\Api\\{$d->name}Controller::class";
             $lines[] = "Route::get('{$d->slug}/_stats', [{$controller}, 'stats'])->name('{$d->slug}.stats');";
+            $lines[] = "Route::get('{$d->slug}/_insights', [{$controller}, 'insights'])->name('{$d->slug}.insights');";
+            $lines[] = "Route::post('{$d->slug}/_bulk', [{$controller}, 'bulk'])->name('{$d->slug}.bulk');";
             $lines[] = "Route::apiResource('{$d->slug}', {$controller});";
         }
         $body = implode("\n", $lines);
@@ -749,6 +751,13 @@ final class ResourceGenerator
                 return Nevela::stats({$d->name}::query(), '{$d->name}', \$request);
             }
 
+            public function insights(Request \$request): JsonResponse
+            {
+                Gate::authorize('viewAny', {$d->name}::class);
+
+                return Nevela::insights({$d->name}::query(), '{$d->name}', \$request);
+            }
+
             public function store({$d->name}Request \$request): JsonResponse
             {
                 \${$var} = {$d->name}::create(\$request->values());
@@ -759,6 +768,13 @@ final class ResourceGenerator
                     ->header('Location', \$request->url().'/'.\${$var}->getKey());
             }
 
+            public function bulk(Request \$request): JsonResponse
+            {
+                Gate::authorize('create', {$d->name}::class);
+
+                return Nevela::createMany({$d->name}::class, {$d->name}Request::class, {$d->name}Resource::class, \$request);
+            }
+
             public function show({$d->name} \${$var}): {$d->name}Resource
             {
                 Gate::authorize('view', \${$var});

package/template/laravel/src/Http/ResourceRequest.php

@@ -3,6 +3,8 @@
 namespace Nevela\Laravel\Http;
 
 use Illuminate\Foundation\Http\FormRequest;
+use Illuminate\Support\Facades\Validator as Validation;
+use Illuminate\Validation\Rules\Unique;
 use Illuminate\Validation\Validator;
 
 /**
@@ -52,6 +54,79 @@ abstract class ResourceRequest extends FormRequest
         });
     }
 
+    /**
+     * Many rows, each checked by the rules for creating one.
+     *
+     * The same rules as a single create, on purpose: a second way into the table with its
+     * own idea of what is valid would let through a row the form then refuses to save.
+     * Rows are numbered from 1, as a person counts them.
+     *
+     * Two rows of one batch can't share a unique value either. The database would refuse
+     * the second, but only after the first was written and with no row number to show.
+     *
+     * @param  list<mixed>  $rows
+     * @return array{values: list<array<string, mixed>>, problems: list<array{row: int, issues: list<array{path: string, message: string}>}>}
+     */
+    public function many(array $rows): array
+    {
+        $rules = $this->rules();
+        $columns = $this->columns();
+        $known = array_keys($columns);
+        $computed = array_map(fn (string $field) => $field.'File', $known);
+        $unique = array_keys(array_filter($rules, fn ($rule) => is_array($rule) && array_filter($rule, fn ($one) => $one instanceof Unique) !== []));
+
+        $values = [];
+        $problems = [];
+        $taken = [];
+        foreach (array_values($rows) as $index => $row) {
+            $number = $index + 1;
+            if (! is_array($row) || array_is_list($row)) {
+                // An empty JSON object arrives as an empty list; anything else here is not fields at all.
+                $problems[] = ['row' => $number, 'issues' => [['path' => '', 'message' => $row === [] ? 'This row is empty.' : 'This row is not a record.']]];
+
+                continue;
+            }
+            $issues = [];
+            foreach (array_keys($row) as $key) {
+                if (! in_array($key, $known, true) && ! in_array($key, self::READ_ONLY, true) && ! in_array($key, $computed, true)) {
+                    $issues[] = ['path' => (string) $key, 'message' => 'Unknown field.'];
+                }
+            }
+            $validator = Validation::make($row, $rules);
+            if ($validator->fails()) {
+                array_push($issues, ...FlareErrors::issues($validator->errors()->toArray()));
+            }
+            foreach ($unique as $field) {
+                $value = $row[$field] ?? null;
+                if (! is_scalar($value) || (string) $value === '') {
+                    continue;
+                }
+                $mark = $field."\0".$value;
+                if (isset($taken[$mark])) {
+                    $issues[] = ['path' => $field, 'message' => "The same as row {$taken[$mark]}. Each one needs its own."];
+                } else {
+                    $taken[$mark] = $number;
+                }
+            }
+            if ($issues !== []) {
+                $problems[] = ['row' => $number, 'issues' => $issues];
+
+                continue;
+            }
+
+            $validated = $validator->validated();
+            $mapped = [];
+            foreach ($columns as $field => $column) {
+                if (array_key_exists($field, $validated)) {
+                    $mapped[$column] = $validated[$field];
+                }
+            }
+            $values[] = $mapped;
+        }
+
+        return ['values' => $values, 'problems' => $problems];
+    }
+
     /** Validated input keyed by column, ready for create()/update(). @return array<string, mixed> */
     public function values(): array
     {

package/template/laravel/src/Nevela.php

@@ -3,11 +3,14 @@
 namespace Nevela\Laravel;
 
 use Illuminate\Database\Eloquent\Builder;
+use Illuminate\Database\UniqueConstraintViolationException;
 use Illuminate\Http\JsonResponse;
 use Illuminate\Http\Request;
+use Illuminate\Support\Facades\DB;
 use InvalidArgumentException;
 use Nevela\Laravel\Media\Uploads;
 use Nevela\Laravel\Support\Descriptor;
+use Nevela\Laravel\Support\Insights;
 use Nevela\Laravel\Support\ListQuery;
 use Nevela\Laravel\Support\Naming;
 
@@ -18,7 +21,7 @@ use Nevela\Laravel\Support\Naming;
 final class Nevela
 {
     /** Written by `pnpm release`; the same number as the repository's git tag. */
-    public const VERSION = '0.5.0';
+    public const VERSION = '0.5.2';
 
     /** @var array<string, Descriptor> */
     private static array $descriptors = [];
@@ -79,6 +82,35 @@ final class Nevela
             return response()->json(['error' => 'Invalid query.', 'issues' => $list->issues], 400);
         }
 
+        self::narrow($query, $resource, $list);
+
+        $query->reorder()
+            ->orderBy($list->sort['column'], $list->sort['direction'])
+            ->orderBy($query->getModel()->getKeyName(), $list->sort['direction']);
+
+        $page = $query->paginate($list->perPage, ['*'], 'page', $list->page);
+
+        // One query for every file on the page, instead of one per record.
+        foreach ($resource->fields as $field) {
+            if ($field->kind === 'file') {
+                Uploads::preload($page->getCollection()->pluck($field->column()));
+            }
+        }
+
+        return response()->json([
+            'data' => $resourceClass::collection($page->getCollection())->resolve($request),
+            'meta' => [
+                'page' => $page->currentPage(),
+                'perPage' => $page->perPage(),
+                'total' => $page->total(),
+                'totalPages' => max(1, $page->lastPage()),
+            ],
+        ]);
+    }
+
+    /** The search and the filters of a list request, applied. Its insights are narrowed the same way. */
+    private static function narrow(Builder $query, Descriptor $resource, ListQuery $list): void
+    {
         if ($list->q !== null) {
             $columns = array_map(fn ($f) => $f->column(), array_values(array_filter($resource->fields, fn ($f) => $f->searchable())));
             if ($columns !== []) {
@@ -96,31 +128,146 @@ final class Nevela
                 ? $query->whereNull($filter['column'])
                 : $query->where($filter['column'], $filter['value']);
         }
+    }
 
-        $query->reorder()
-            ->orderBy($list->sort['column'], $list->sort['direction'])
-            ->orderBy($query->getModel()->getKeyName(), $list->sort['direction']);
+    /**
+     * GET /{slug}/_insights?unit=day|week|month&q&filter[field] → { total, unit, series, breakdown }.
+     *
+     * What the dashboard's insights panel draws: how many records were created in each
+     * period, and how they split across each field that is a choice (an enum or a yes/no).
+     *
+     * It takes the list's own search and filters, so the charts describe the rows the
+     * table is showing. A whole-table chart above a filtered table would be wrong in a
+     * prominent place.
+     */
+    public static function insights(Builder $query, string $name, Request $request): JsonResponse
+    {
+        $resource = self::resource($name);
+        $unit = $request->query('unit', 'day');
+        if (! is_string($unit) || ! isset(Insights::PERIODS[$unit])) {
+            return response()->json(['error' => 'Invalid query.', 'issues' => [['param' => 'unit', 'message' => 'Must be day, week or month.']]], 400);
+        }
+        // The same parameters as the list. Where in the list someone is makes no difference to a count.
+        $params = array_diff_key($request->query(), array_flip(['unit', 'page', 'perPage', 'sort', 'columns']));
+        $list = ListQuery::parse($resource, $params, (int) config('nevela.per_page', 25), (int) config('nevela.max_per_page', 100));
+        if (! $list->ok()) {
+            return response()->json(['error' => 'Invalid query.', 'issues' => $list->issues], 400);
+        }
+        self::narrow($query, $resource, $list);
+        $base = fn () => (clone $query)->reorder();
 
-        $page = $query->paginate($list->perPage, ['*'], 'page', $list->page);
+        // Counted per day by the database, one grouped query over the created_at index,
+        // and added up into weeks or months here: see Support\Insights.
+        $now = now();
+        $table = $query->getModel()->getTable();
+        $day = $query->getConnection()->getDriverName() === 'sqlsrv' ? "CAST({$table}.created_at AS date)" : "DATE({$table}.created_at)";
+        $perDay = $base()->toBase()
+            ->where("{$table}.created_at", '>=', Insights::since($unit, $now))
+            ->selectRaw("{$day} as day, count(*) as aggregate")
+            ->groupByRaw($day)
+            ->get()
+            ->map(fn ($row) => [(string) $row->day, (int) $row->aggregate]);
 
-        // One query for every file on the page, instead of one per record.
+        $breakdown = [];
         foreach ($resource->fields as $field) {
-            if ($field->kind === 'file') {
-                Uploads::preload($page->getCollection()->pluck($field->column()));
+            if (! in_array($field->kind, ['enum', 'boolean'], true)) {
+                continue;
+            }
+            if (count($breakdown) === 4) {
+                break; // one grouped query each, and four charts is already a lot to read
             }
+            $column = $field->column();
+            $counts = [];
+            foreach ($base()->toBase()->select($column.' as value')->selectRaw('count(*) as aggregate')->groupBy($column)->get() as $row) {
+                $value = $row->value === null ? '' : ($field->kind === 'boolean' ? ($row->value ? 'true' : 'false') : (string) $row->value);
+                $counts[$value] = ($counts[$value] ?? 0) + (int) $row->aggregate;
+            }
+            // Every choice the field has, in its own order, so one nobody has picked shows as zero.
+            $values = $field->kind === 'boolean' ? ['true', 'false'] : $field->options;
+            $slices = array_map(fn (string $value) => ['value' => $value, 'count' => $counts[$value] ?? 0], $values);
+            if (($counts[''] ?? 0) > 0) {
+                $slices[] = ['value' => '', 'count' => $counts['']];
+            }
+            $breakdown[] = ['field' => $field->name, 'kind' => $field->kind, 'slices' => $slices];
         }
 
         return response()->json([
-            'data' => $resourceClass::collection($page->getCollection())->resolve($request),
-            'meta' => [
-                'page' => $page->currentPage(),
-                'perPage' => $page->perPage(),
-                'total' => $page->total(),
-                'totalPages' => max(1, $page->lastPage()),
-            ],
+            'total' => $base()->count(),
+            'unit' => $unit,
+            'series' => Insights::series($unit, $now, $perDay),
+            'breakdown' => $breakdown,
         ]);
     }
 
+    /**
+     * POST /{slug}/_bulk { items: [ … ] } → 201 { created, data }, or 422 { error, rows }.
+     *
+     * Several records in one go, for the dashboard's grid. Every row is checked before
+     * anything is written, and they are saved in one transaction: a mistake on row 7
+     * is reported against row 7 and nothing is created, where saving six and stopping
+     * would leave someone working out which six.
+     *
+     * @param  class-string<\Illuminate\Database\Eloquent\Model>  $modelClass
+     * @param  class-string<Http\ResourceRequest>  $requestClass
+     * @param  class-string<\Illuminate\Http\Resources\Json\JsonResource>  $resourceClass
+     */
+    public static function createMany(string $modelClass, string $requestClass, string $resourceClass, Request $request): JsonResponse
+    {
+        $most = max(1, (int) config('nevela.bulk_max', 500));
+        $items = $request->input('items');
+        if (! is_array($items) || ! array_is_list($items) || $items === []) {
+            return response()->json(['error' => 'Send the rows to create as "items", a list with at least one row.'], 422);
+        }
+        if (count($items) > $most) {
+            return response()->json(['error' => 'That is '.number_format(count($items))." rows. At most {$most} can be created at once; for more, import a file."], 422);
+        }
+
+        $checked = (new $requestClass)->many($items);
+        if ($checked['problems'] !== []) {
+            return self::rowsRefused($checked['problems'], count($items));
+        }
+
+        try {
+            $created = DB::transaction(function () use ($modelClass, $checked) {
+                $created = [];
+                foreach ($checked['values'] as $index => $values) {
+                    try {
+                        $created[] = $modelClass::create($values);
+                    } catch (UniqueConstraintViolationException $e) {
+                        // Someone else created the same value between the check and the write.
+                        throw new \RuntimeException((string) ($index + 1), 0, $e);
+                    }
+                }
+
+                return $created;
+            });
+        } catch (\RuntimeException $e) {
+            if (! $e->getPrevious() instanceof UniqueConstraintViolationException) {
+                throw $e;
+            }
+
+            return self::rowsRefused([['row' => (int) $e->getMessage(), 'issues' => [['path' => '', 'message' => 'A record with one of these values was created a moment ago.']]]], count($items));
+        }
+
+        return response()->json([
+            'created' => count($created),
+            'data' => array_map(fn ($model) => (new $resourceClass($model->refresh()))->resolve($request), $created),
+        ], 201);
+    }
+
+    /** @param list<array{row: int, issues: list<array{path: string, message: string}>}> $problems */
+    private static function rowsRefused(array $problems, int $sent): JsonResponse
+    {
+        $wrong = count($problems);
+
+        return response()->json([
+            'error' => $wrong === 1
+                ? "Nothing was created: row {$problems[0]['row']} needs fixing."
+                : "Nothing was created: {$wrong} of the {$sent} rows need fixing.",
+            'rows' => $problems,
+        ], 422);
+    }
+
     /**
      * GET /{slug}/_stats?field=status&days=7 → { total, current, previous, values }.
      * What Flare's ResourceStats card shows above a table.

package/template/laravel/src/Support/Insights.php

@@ -0,0 +1,78 @@
+<?php
+
+namespace Nevela\Laravel\Support;
+
+use Carbon\CarbonImmutable;
+use Carbon\CarbonInterface;
+
+/**
+ * The periods a "created per day, week or month" chart is drawn in.
+ *
+ * The database is only ever asked for counts per day, which every database can give
+ * with the same expression. Weeks and months are added up here, so a week starts on
+ * Monday and a month is a calendar month whichever database is underneath.
+ */
+final class Insights
+{
+    /** How many periods of each kind a chart shows: a month of days, half a year of weeks, a year of months. */
+    public const PERIODS = ['day' => 30, 'week' => 26, 'month' => 12];
+
+    /**
+     * The periods up to and including the one `$now` is in, oldest first.
+     *
+     * @return list<string> A day or a week as "2026-10-05" (a week by its Monday), a month as "2026-10"
+     */
+    public static function buckets(string $unit, CarbonInterface $now): array
+    {
+        $current = CarbonImmutable::instance($now)->startOfDay();
+        $buckets = [];
+        for ($back = self::PERIODS[$unit] - 1; $back >= 0; $back--) {
+            $buckets[] = match ($unit) {
+                'day' => $current->subDays($back)->format('Y-m-d'),
+                'week' => $current->startOfWeek(CarbonInterface::MONDAY)->subWeeks($back)->format('Y-m-d'),
+                // From the first of the month: stepping back from the 31st would skip the short months.
+                'month' => $current->startOfMonth()->subMonthsNoOverflow($back)->format('Y-m'),
+            };
+        }
+
+        return $buckets;
+    }
+
+    /** The first moment the chart covers. */
+    public static function since(string $unit, CarbonInterface $now): CarbonImmutable
+    {
+        $first = self::buckets($unit, $now)[0];
+
+        return CarbonImmutable::parse($unit === 'month' ? "{$first}-01" : $first, $now->getTimezone())->startOfDay();
+    }
+
+    /** Which period a day ("2026-10-09") belongs to. */
+    public static function bucketOf(string $unit, string $day): string
+    {
+        return match ($unit) {
+            'day' => substr($day, 0, 10),
+            'week' => CarbonImmutable::parse(substr($day, 0, 10))->startOfWeek(CarbonInterface::MONDAY)->format('Y-m-d'),
+            'month' => substr($day, 0, 7),
+        };
+    }
+
+    /**
+     * Counts per day, added up into the chart's periods. A period with nothing in it is
+     * still there, as zero: a gap in a chart should look like a gap.
+     *
+     * @param  iterable<array{0: string, 1: int}>  $perDay  Pairs of day and count
+     * @return list<array{bucket: string, count: int}>
+     */
+    public static function series(string $unit, CarbonInterface $now, iterable $perDay): array
+    {
+        $counts = array_fill_keys(self::buckets($unit, $now), 0);
+        foreach ($perDay as [$day, $count]) {
+            $bucket = self::bucketOf($unit, $day);
+            if (isset($counts[$bucket])) {
+                $counts[$bucket] += $count;
+            }
+        }
+
+        return array_map(fn (string $bucket, int $count) => ['bucket' => $bucket, 'count' => $count], array_keys($counts), array_values($counts));
+    }
+}