Order Timeline (#88)

Co-authored-by: Claude <[email protected]>

Author: duncanmcclean

composer.json

@@ -33,6 +33,7 @@
             "providers": [
                 "DuncanMcClean\\Cargo\\ServiceProvider",
                 "DuncanMcClean\\Cargo\\Discounts\\DiscountServiceProvider",
+                "DuncanMcClean\\Cargo\\Orders\\OrderServiceProvider",
                 "DuncanMcClean\\Cargo\\Payments\\PaymentServiceProvider",
                 "DuncanMcClean\\Cargo\\Shipping\\ShippingServiceProvider"
             ]

docs/docs/migrating-from-simple-commerce.md

@@ -160,11 +160,6 @@ Since orders are no longer stored in collections, Cargo provides its own "Order"
 
 During the migration process, Cargo will have attempted to copy across any custom fields you added to the order collection's blueprint.
 
-### Status Log
-The "Status Log" feature present in Simple Commerce doesn't exist in Cargo. Cargo simply displays the current status of orders.
-
-If you need to occasionally reference the history of order statuses, you may wish to take advantage of [Statamic's Git Automation](https://statamic.dev/git-automation) if you're storing orders in flat files, or use a package like [`spatie/laravel-activitylog`](https://github.com/spatie/laravel-activitylog) if you're using a database.
-
 ## Customers
 By default, Simple Commerce stored information about your customers in a customers collection or `customers` database table.
 

docs/docs/orders.md

@@ -36,6 +36,72 @@ If you want to customise the packing slip, you may publish it with the following
 php artisan vendor:publish --tag=cargo-packing-slip
 ```
 
+## Timeline
+The Timeline feature provides a complete audit trail of order changes, visible when viewing orders in the Control Panel. It automatically tracks key events including:
+
+- Order creation and updates
+- Status changes
+- Refunds
+
+Each event records the authenticated user who made the change and any relevant metadata.
+
+![Order Timeline](/images/order-timeline.png)
+
+### Custom Timeline Events
+You can extend the Timeline by registering custom event types to track additional order activities beyond the built-in events.
+
+Create a PHP class that extends `TimelineEventType` to represent your custom event:
+
+```php
+// app/TimelineEventTypes/OrderDelivered.php
+
+use DuncanMcClean\Cargo\Orders\TimelineEventType;
+
+class OrderDelivered extends TimelineEventType
+{
+    public function message() : string
+    {
+        return "Order Delivered by Royal Mail";
+    }
+}
+```
+
+Register your custom event type in your `AppServiceProvider`:
+
+```php
+// app/Providers/AppServiceProvider.php
+
+public function boot(): void
+{
+	OrderDelivered::register();
+}
+```
+
+Then listen for the relevant event in your application and append your custom timeline event to the order:
+
+```php
+// app/Listeners/RoyalMailPackageDeliveredListener.php
+
+use DuncanMcClean\Cargo\Facades\Order;
+use RoyalMail\Events\PackageDelivered;
+
+class RoyalMailPackageDeliveredListener
+{
+    public function handle(PackageDelivered $event)
+    {
+        $order = Order::find('the-order-id');
+        
+        $order->appendTimelineEvent(
+            type: OrderDelivered::class, 
+            metadata: [
+                'Foo' => 'bar',
+                'Baz' => 'qux', 
+            ],
+        );
+    }
+}
+```
+
 ## Storage
 Out of the box, orders are stored as YAML files in the `content/cargo/orders` directory. If you wish, you can change the directory in the `cargo.php` config file:
 

docs/extending/events/list.md

@@ -195,6 +195,20 @@ public function handle(OrderSaved $event)
 }
 ```
 
+### OrderStatusUpdated
+`DuncanMcClean\Cargo\Events\OrderStatusUpdated`
+
+Dispatched when an order's status is changed.
+
+```php
+public function handle(OrderStatusUpdated $event)
+{
+	$event->order;
+	$event->originalStatus;
+	$event->updatedStatus;
+}
+```
+
 ### OrderShipped
 `DuncanMcClean\Cargo\Events\OrderShipped`
 

docs/images/order-timeline.png

@@ -24,4 +24,10 @@
     'tax_zones_intro' => 'Tax Rates allow you to define the tax rates for each tax class, with different rates per country, state or postal code.',
     'tax_zones_rates_instructions' => 'Define the tax rates available for this zone, per tax class.',
     'tax_zones_type_instructions' => 'Where should this tax zone apply?',
+    'timeline_events' => [
+        'order_created' => 'Order was created',
+        'order_refunded' => 'Order was refunded for :amount',
+        'order_status_changed' => 'Status changed to :status',
+        'order_updated' => 'Order was updated',
+    ],
 ];

lang/en/messages.php

@@ -0,0 +1,104 @@
+<script setup>
+import { Fieldtype, DateFormatter } from '@statamic/cms';
+import { Heading, Subheading, Avatar, Table, TableRows, TableRow, TableCell, Icon } from '@statamic/cms/ui';
+import { ref } from 'vue';
+
+const emit = defineEmits(Fieldtype.emits);
+const props = defineProps(Fieldtype.props);
+const { expose } = Fieldtype.use(emit, props);
+defineExpose(expose);
+
+const events = ref(props.value);
+
+const formatRelativeDate = (value) => {
+    const today = new Date();
+    today.setHours(0, 0, 0, 0);
+    
+    const isToday = value === Math.floor(today.getTime() / 1000);
+
+    return isToday
+        ? __('Today')
+        : DateFormatter.format(value * 1000, {
+            month: 'long',
+            day: 'numeric',
+            year: 'numeric',
+        });
+};
+
+const formatTime = (date) => DateFormatter.format(date * 1000, 'time');
+
+const selected = ref([]);
+
+const toggleSelection = (event) => {
+    if (selected.value.includes(event.id)) {
+        selected.value = selected.value.filter((id) => id !== event.id);
+        return;
+    }
+
+	if (event.metadata.length === 0) return;
+
+    selected.value.push(event.id);
+};
+</script>
+
+<template>
+    <div class="flex flex-col gap-y-6">
+        <div v-for="group in events" :key="group.day">
+            <Heading size="sm" class="mb-1 text-gray-600 dark:text-gray-300" v-text="formatRelativeDate(group.day)" />
+
+            <div class="relative grid">
+                <div class="absolute inset-y-0 left-3 top-3 border-l-1 border-gray-400 dark:border-gray-600 border-dashed" />
+
+                <div v-for="event in group.events" class="relative block py-2">
+                    <div class="flex gap-3">
+                        <Avatar v-if="event.user" :user="event.user" class="size-6 shrink-0 mt-1" />
+
+	                    <div v-else class="size-6 flex items-center justify-center shrink-0 bg-white dark:bg-gray-900 rounded-full p-1 border border-gray-200 dark:border-white/15">
+		                    <Icon :name="meta.cargoMark" class="w-full" />
+	                    </div>
+
+                        <div class="grid gap-1 w-full">
+                            <button
+                                class="flex items-center gap-1"
+                                :class="{ 'cursor-pointer': event.metadata.length != 0 }"
+                                @click="toggleSelection(event)"
+                            >
+                                <Heading class="font-medium" v-text="event.message" />
+	                            <Icon
+		                            v-if="event.metadata.length != 0"
+		                            name="chevron-down"
+		                            class="text-gray-400 dark:text-white/40"
+		                            :class="{ 'rotate-180': selected.includes(event.id) }"
+	                            />
+                            </button>
+
+                            <Subheading
+	                            class="text-xs text-gray-500! dark:text-gray-400!"
+	                            :class="{ 'text-gray-800! dark:text-white!': false }"
+                            >
+                                {{ formatTime(event.timestamp) }}
+                                <template v-if="event.user">
+                                    by {{ event.user.name || event.user.email }}
+                                </template>
+                            </Subheading>
+
+                            <div
+	                            v-if="event.metadata && selected.includes(event.id)"
+	                            class="border border-gray-200 dark:border-white/15 rounded-md py-0.5 px-2 mt-2 mb-4"
+                            >
+                                <Table class="w-full">
+                                    <TableRows>
+                                        <TableRow v-for="(value, key) in event.metadata">
+                                            <TableCell class="font-medium text-sm" v-text="__(key)" />
+                                            <TableCell class="break-all text-sm" v-text="__(value)" />
+                                        </TableRow>
+                                    </TableRows>
+                                </Table>
+                            </div>
+                        </div>
+                    </div>
+                </div>
+            </div>
+        </div>
+    </div>
+</template>

resources/js/components/fieldtypes/OrderTimelineFieldtype.vue

@@ -7,6 +7,7 @@ import MoneyFieldtype from './components/fieldtypes/MoneyFieldtype.vue';
 import OrderReceiptFieldtype from './components/fieldtypes/OrderReceiptFieldtype.vue';
 import ProductVariantsFieldtype from './components/fieldtypes/ProductVariantsFieldtype.vue';
 import OrderStatusFieldtypeIndex from './components/fieldtypes/OrderStatusFieldtypeIndex.vue';
+import OrderTimelineFieldtype from './components/fieldtypes/OrderTimelineFieldtype.vue';
 import PaymentDetailsFieldtype from './components/fieldtypes/PaymentDetailsFieldtype.vue';
 import ShippingDetailsFieldtype from './components/fieldtypes/ShippingDetailsFieldtype.vue';
 import StatesFieldtype from './components/fieldtypes/StatesFieldtype.vue';
@@ -31,7 +32,7 @@ Statamic.booting(() => {
     Statamic.$components.register('order_receipt-fieldtype', OrderReceiptFieldtype);
     Statamic.$components.register('product_variants-fieldtype', ProductVariantsFieldtype);
     Statamic.$components.register('order_status-fieldtype-index', OrderStatusFieldtypeIndex);
-    
+    Statamic.$components.register('order_timeline-fieldtype', OrderTimelineFieldtype);
     Statamic.$components.register('payment_details-fieldtype', PaymentDetailsFieldtype);
     Statamic.$components.register('shipping_details-fieldtype', ShippingDetailsFieldtype);
     Statamic.$components.register('states-fieldtype', StatesFieldtype);

resources/js/cp.js

@@ -0,0 +1,56 @@
+<?php
+
+namespace DuncanMcClean\Cargo\Commands\Migration\Concerns;
+
+use Carbon\Carbon;
+use Illuminate\Support\Collection;
+
+trait MapsTimelineEvents
+{
+    private function mapTimelineEvents(Collection $data): array
+    {
+        $previousStatus = null;
+
+        return collect($data->get('status_log'))
+            ->map(function (array $statusLogEvent) use (&$previousStatus): ?array {
+                $status = $statusLogEvent['status'];
+                $datetime = Carbon::parse($statusLogEvent['timestamp'])->format('Y-m-d H:i:s');
+
+                $mappedStatus = $this->mapStatusLogStatus($status);
+
+                if ($status === 'placed') {
+                    return [
+                        'datetime' => $datetime,
+                        'type' => 'order_created',
+                    ];
+                }
+
+                $event = [
+                    'datetime' => $datetime,
+                    'type' => 'order_status_changed',
+                    'metadata' => array_filter([
+                        'Original Status' => $previousStatus,
+                        'New Status' => $mappedStatus,
+                    ]),
+                ];
+
+                $previousStatus = $mappedStatus;
+
+                return $event;
+            })
+            ->values()
+            ->all();
+    }
+
+    private function mapStatusLogStatus(string $status): string
+    {
+        return match ($status) {
+            'placed' => 'payment_pending',
+            'paid' => 'payment_received',
+            'dispatched', 'delivered' => 'shipped',
+            'cancelled' => 'cancelled',
+            'returned' => 'returned',
+            default => $status,
+        };
+    }
+}

src/Commands/Migration/Concerns/MapsTimelineEvents.php

@@ -22,7 +22,11 @@
 
 class MigrateCarts extends Command
 {
-    use \DuncanMcClean\Cargo\Commands\Migration\Concerns\MapsAddresses, \DuncanMcClean\Cargo\Commands\Migration\Concerns\MapsCustomData, \DuncanMcClean\Cargo\Commands\Migration\Concerns\MapsLineItems, \DuncanMcClean\Cargo\Commands\Migration\Concerns\MapsOrderDates, RunsInPlease;
+    use Concerns\MapsAddresses,
+        Concerns\MapsCustomData,
+        Concerns\MapsLineItems,
+        Concerns\MapsOrderDates,
+        RunsInPlease;
 
     protected $signature = 'statamic:cargo:migrate:carts';