feat(storefront): UX overhaul — context switcher, network screens, cards, panels, promotions hub, create order

[roncodes]

Storefront UX overhaul (single PR)

Replaces the stacked PRs #121–#136 with one branch targeting release/v0.4.25. Implements the Storefront redesign from the Claude Design canvas on @fleetbase/ember-ui primitives: store/network context switcher and context-scoped navigation, network overview / stores / orders / trucks / customers / categories / settings, resource cards on Layout::Resource::Card, order details panel, create order form (console orders through the app's checkout), products page, catalog editor, product editor, customer panel, promotions hub and builder, trucks page and panel, settings shell with a section rail, dashboard attention strip, network join flow.

Every screen was exercised in a running console in both store and network context (dark and light) before being marked done.

What changed since the last review

• Crashes fixed: truck create/edit and customer panel in network context, create-order line configurator (add-on relations read through the proxy), schedule manager on lowercase day names, sidebar group inside the wormhole.
• One palette, type scale and radius set for the stylesheet (tokens documented at the top of storefront-engine.css); one Storefront::ViewToggle; product grid card on the shared card anatomy.
• Settings: every page on one section anatomy (the old SettingsContainer shell is gone), Hours summary per location, Danger zone (delete store), rail counts; network settings rebuilt on the same shell.
• Dashboard header shows the store's open / closed state from its locations' hours in the store timezone, plus New order.
• Sidebar: "Member of" (store context) and "Your stores in this network" (network context) cross-link groups.
• Network: Categories page; Stores page per the board (status, orders 7d, share bar, joined, invitation rows) with suspend / reinstate (new network_stores.status); catalog card actions menu; trucks Map button and panel Location tab.
• Promotions: engine honours applies_to.segment once the customer is known.
• Approval queue: an invitation sent with "require my approval" now creates a pending membership on accept (hidden from the app); the Stores page gets an Awaiting approval tab with Approve / Reject row actions and a bulk Approve.
• Per-catalog price and availability: the catalog editor's product rows show the effective price with a click-to-set catalog price and a sold-here toggle; the app receives the catalog price and availability, and cart lines added with a catalog keep that price.
• Create order from the network context: a store step lists the network's active members, the rest of the form is the store form; the network Orders page gets a New order button.
• Dead coupons, broadcast and pages routes removed; muted light-mode text darkened to gray-500 for 4.5:1 at 12px.
• Board parity pass (every screen compared with its mockup): dashboard header leads with the store name and open state, Orders nav badge from the attention counts, recent-orders widget with the board's columns and a next-action button; Products titled Products with a sort control and a bulk Add to catalog; Settings gains a timezone field; Catalogs page gets status tabs and out-of-stock counts; customer overview shows the customer's segments; promotions table is selectable with bulk pause / resume / end; truck cards say which catalog is serving and when an offline vehicle last reported, truck panel opens the vehicle; network overview shows member cards with membership badges; the shareable join link now works end to end (token link, link joins with approval, Regenerate / expiry / category / auto-approve); customers page gets a Cards view with a customer card.

Server / API

• Migrations: 2026_10_11_000000_add_status_to_network_stores_table (status default active, also pending for memberships awaiting approval) and 2026_10_11_000001_add_overrides_to_catalog_category_products_table (price, is_available, both nullable).
• New internal endpoints: POST networks/{id}/suspend-stores, reinstate-stores, approve-stores, reject-stores ({ stores: [uuid] }); membership changes invalidate the cached store listings (ApiModelCache).
• Catalog payloads: each category accepts product_overrides ({ <product uuid>: { price, is_available } }, an explicit map is authoritative) and returns it internally; the public catalog product carries price (effective), store_price, catalog_price, is_available (effective) and catalog_available.
• Network join link: POST networks/{id}/shareable-link (enabled, regenerate, expires_in_days, category_uuid, requires_approval) manages the link; GET/POST networks/join/{uri} now also resolve a link token and create a link invitation + membership on accept; invitations carry via (email | link) and store_name; the overview's members carry category and membership_status; customer insights carry segments.
• Cart: POST carts/{id}/add/{product} accepts catalog (catalog id); the line keeps catalog_id and is priced at the catalog price on add and update; a product hidden in that catalog is refused. Checkout itself is unchanged: it prices from the cart lines. Needs human review (needs-human-review).
• Store resource: network_status (internal, when network is given); networks with with[]=networks.
• Public API: suspended members are excluded from the network's store and product listings.
• OrderFilter: customer / customer_uuid; ConsoleOrderController quote/place for console orders.
• Bug: store-locations?store_uuid= was ignored by the API (filter method is store); the console now queries with store=.

Screen audit after the 11 Oct review

• Reusable Storefront::PageHeader (avatar or icon, name, status badge, meta line, search, actions) and Storefront::SectionCard replace ContentPanel on the network overview, stores, orders and trucks pages; KPI tiles are compact (uppercase 11px label, single-line value).
• Network overview: header with logo, Online badge, currency · timezone · id; member cards with one ellipsis menu; the body scrolls (the overflow-y-scroll-i class is now defined).
• Network stores: Filters menu in the header (status, category), table inside a bordered card with an outer margin and a Showing footer, short bulk labels with a right-aligned Clear link, category column as an inline dropdown that assigns on pick.
• Network orders: compact rows, fulfillment as a badge, group rows expand to their child order rows (chevron in the reference cell), reference cell shows the checkout id with "N orders · M items", Filters (status, fulfillment, store) and a Columns picker in the header, Group by checkout / Flat as a plain segmented control, table card with pagination.
• Trucks: card header is the vehicle pill with the driver as subtitle, footer has edit plus one ellipsis menu (assign catalogs, open vehicle, delete), meta reads " service area · " and "N catalogs · M orders today" (or last online); the panel header is the truck image with id · owner · online state on the left and Open vehicle / ellipsis / close on the right, tabs are flush, Details holds the form, the catalogs list and a Today block (orders, revenue, avg prep) with a Leaflet position map; new Orders tab (orders stamped with the truck) and Location tab map; the Map button switches the page to a map of the trucks with a reported position instead of leaving for Fleet-Ops.
• Promotions in the network context: networks/:id/promotions (promotions, campaigns, segments, redemptions) reuse the hub templates and controllers with the network as owner; the builder gains a Stores target for network-owned promotions; one Promotions entry in each sidebar as the board specifies. The networks list query params are prefixed (n_page, n_query, …) so nested pages keep the plain keys.
• Settings: the rail scrolls the settings pane, not the console; content padding and width normalised. "Your stores in this network" sidebar group removed (not on the board).
• Order action labels in the actions menu are translated (were hard-coded).
• Create order form rebuilt to its board: flat numbered sections with uppercase headings, customer pill, location and address option cards, items as a table behind an Add products button, a gray summary rail (Promotion, Payment select, Tip, Summary) with a sticky Place order footer; the network variant keeps its store step.

Server / API (11 Oct additions)

• FoodTruck resource carries today (internal only): { orders, revenue, currency, avg_prep_minutes } for orders stamped meta.food_truck_id created today in the owner's timezone; the truck list eager-loads vehicle.driver.
• OrderFilter::foodTruck (?food_truck=<public id>), ProductFilter::network (?network=<uuid>, products of the network's member stores).

12 Oct review (store context, network context, UI and skeletons)

• Store context:
  • The attention strip is compact.
  • Opening a panel such as a new order, a customer or a product no longer reloads the list behind it.
  • The create order Deliver-to field puts its help under the input, and a new address is saved to the customer as a Fleet-Ops place.
  • Products is a single sidebar entry.
  • The product card was rebuilt.
  • The smart groups read Unavailable instead of Out of stock, and On sale has its icon.
  • The products list view is a real table with select-all and single-line identity cells.
  • The products skeleton follows the chosen view.
  • The product form is one page with a rail.
  • Add-ons are managed in a panel.
  • The catalogs header has no subtitle or rule, and the catalog editor rows line up on one line.
  • The customer panel was rebuilt with in-panel edit, a working orders tab and a New order action that preselects the customer.
  • The new truck panel reads cleanly.
  • Promotion status tabs filter instantly and show counts. A promotion past its end date reads Ended, as the server applies it.
  • Builder choices sit on the step surface, BOGO fields are aligned and the footer is flush.
  • Settings section headings are compact and uppercase, and the save bar spans the content.
• Network context:
  • The overview shows member stores four to a row.
  • Recent orders list each order with customer and store identity cells, row hover, row click into the order panel and right-aligned totals.
  • Network and store Customers lists now come from Storefront's customers endpoint. They used Fleet-Ops' combined customers-and-vendors query, which ignored the store and network scope, sorted by name and never paged.
  • The table row menu's Edit opens the customer's details form.
  • Network orders are left for the next pass, as agreed.
• UI:
  • Table card footers keep the row rhythm at 37px.
  • Rows sit on the card surface.
  • Row hover reaches the sticky ID and action cells. The old dark rule never matched because the wrapper class sits on the table wrapper itself.
  • Dashboard widget rows are single-line, with a Placed column.
• Skeletons: every page loads with a skeleton drawn from that page. Each skeleton follows its page's header, avatar, subtitle and action count, its tab strips, columns and checkbox, its identity column, its cards, and the products and settings rails. Network pages have their own skeletons, and the network promotions pages reuse the store templates through loading routes. The new ember-ui arguments are in release/v0.4.6: skeleton loading components and dark palette tiers ember-ui#189.
• ember-ui: the button and input restyles were reverted until the platform pass.

Server / API (12 Oct)

• The network overview's recent_orders lists each order, not one per checkout. Each entry carries customer_id, customer_photo_url and store_logo_url (internal endpoint).
• No new endpoints. The console now reads GET storefront/int/v1/customers?storefront=|network= (existing) for its customer lists.

12 Oct, second review

• Root cause of the network, categories and notification channel errors: core-api's Comment::publish left every model unguarded in the Octane worker after a failed note, so request parameters became where clauses. The fix is fix(comments): a failed comment publish no longer leaves every model unguarded core-api#298. Separately, the products page no longer sends its view mode to the categories query.
• Customer notes: they save. The comment thread now sends the contact's uuid (release/v0.4.6: skeleton loading components and dark palette tiers ember-ui#189).
• Order panel:
  • Items load when the order is opened from a list, not only after a refresh.
  • The tracking number is the title, with the ID beside it.
  • The status steps have room around them, and the customer shows their phone.
  • Header actions share one compact height.
  • The Store section is now a store profile: backdrop, logo, name, online state and stacked facts.
  • Section headings are compact and aligned with their content.
  • Breakdown strings are translated.
• Tracking number: the Order column (with ID beside it), the dashboard widget, the customer panel, checkout siblings, truck orders, the incoming-order modal and the network overview all use it.
• Tables and dashboard:
  • Row buttons share one 26px height.
  • Dashboard widgets use the Orders page's identity cells.
  • Delivery badges have their own colour.
• New order:
  • The "+" opens an address modal and saves the address to the customer; a chosen address reads as a place card with Change address.
  • Tips add 20% and 30%.
  • The notes field is full width with room below.
• Customers: Places has a real empty state and Add address, and a row's Edit opens the form.
• Products:
  • Cards keep their full height in the scrolling grid. They have a 4:3 image or a placeholder, a two-line title so prices align, and hover and selection.
  • The list pins the Product and actions columns.
  • Skeletons follow the grid and the bare list.
• Product form:
  • Name and SKU have placeholders.
  • Video links are rows with thumbnails.
  • Variants and add-on groups share one group anatomy.
  • Availability is a compact week, which also applies to catalogs and store locations.
  • Translations is its own section: language chips over the name and description, with the originals as hints.
  • The save bar counts every change.
• Catalogs, trucks and settings:
  • The catalog editor's actions header no longer overflows.
  • A long truck badge ellipsizes before the buttons move.
  • Card buttons share one height.
  • Settings sections are single cards with compact headings, and nested panels align with their heading.
• Skeletons: card grids use the real grid's breakpoints.

12 Oct, third review

• Store context:

  • Order IDs line up with their row.
  • The identity strip uses 1.2/1.2/1.2/0.8 columns.
  • The products grid fits below its toolbar with room to scroll the last row clear.
  • Catalog and truck card footers sit on the card's bottom edge, and card buttons share one line.

• Network overview:

  • Store cards are four across, with the store's backdrop and its logo over it.
  • The card action reads "Manage this store", and the menu adds "View store details".
  • The loading skeleton is shared by every way into the overview, including coming back from another network page, which used to show a header-over-table skeleton.

• Store details (new, networks/:id/stores/:store_id):

  • A header with "Manage this store".
  • The store's week (orders, revenue and its share of the network), plus orders and customers through the network.
  • Customers show their order count and open the customer panel.
  • Reached from the stores table name, the overview cards and a customer's "Stores ordered from" rows (now with hover and a chevron; an order placed on the network itself stays static).
  • The sidebar keeps Stores active.

• Network orders:

  • The store cell is one line.
  • A multi-store checkout shows round store logos with the summary card on hover, including the network when an order was placed on it.
  • The Checkout/Order and actions columns are sticky.
  • The "part of chkt_…" subtext is gone (it remains in the order panel header).

• New order: store, location and address cards use the promotion builder's choice-card styling in both themes.

• Hover: recent order rows (customer panel and network overview) have a visible hover in light.

• Stores table: the category caret sits at the far right.

• Switching to a network:

  • It lands on the overview.
  • The networks list (every network with gateways and channels) is no longer queried on the way into a network, so no network cards flash above the skeleton.
  • The list loads when it is shown.

• Server: the network overview's members include backdrop_url.

• Network orders, final polish:

  • Every order row is one line.
  • The Order column shows the tracking number, with the order id on hover.
  • Store and driver are identity cells (20px image, name only, no phone or currency).
  • Totals drop the tip line, which moves to a hover title; a checkout row keeps one tip line.
  • A checkout's stores are evenly spaced 20px logos.
  • The child branch follows the view, so Flat shows none (it used to stay on the records after grouping).

• Trucks:

  • Saved catalogs stay on the truck. FoodTruck::setCatalogs loaded the relation before syncing and never reloaded it, so the save answered with the old catalogs, and the next save deleted the new row. It now reloads the relation and clears the cached truck lists, because a catalogs-only change fires no updated event. New Pest test, which fails without the fix.
  • The card title opens the truck. It used to open Fleet-Ops' vehicle panel, which crashed inside Storefront (vehicle/panel-header not found). The general fix for opening Fleet-Ops records from other engines is fix(descriptors): open Fleet-Ops records on their page outside Fleet-Ops fleetops-data#88.

• Incoming order modal, redesigned as a ticket:

  • Store, total and payment up top.
  • The tracking number with status, fulfillment and timing chips.
  • The route as stops; a pickup shows one stop and needs no driver.
  • Customer and driver side by side.
  • The customer's note, when there is one.
  • The order panel's items and totals, now a shared Storefront::Order::LineItems (zero tips are left out).
  • The label codes for handover.
  • Accept is green on the socket alert too.

Validation

• npx eslint addon app tests, npx ember-template-lint ., stylelint on the stylesheet: clean.
• ember test (12 Oct, third review, customer-panel integration test excluded): 275 tests, 28 skipped, 246 pass, 1 failure in a new route test's stub, fixed and rerun green with the affected modules (20/20). New tests: network order cells (single-line store, avatar stack, reference without the checkout), the networks list skip and reload, Stores staying active on store details.
• ember test (12 Oct, second review, customer-panel integration test excluded): 271 tests, 28 skipped; three tests written against replaced markup were updated and pass. Earlier run: 271 tests, 28 skipped, the rest pass after the 12 Oct fixes. That run's 7 failures were stale tests: the error controller resolving outside the engine, the widget list and the network customers query. Each was fixed and rerun green. The customer-panel integration render still hangs in this environment for reasons unrelated to this branch, as before.
• ember-ui skeleton tests: 15 pass.
• Server: php scripts/pest-runner.php --log-junit … server/tests on this branch: 657 tests, 17 failures + 27 errors, all remaining failures pre-existing on the base commit (missing SocketCluster classes in the local vendor, invites meta column, etc.; the base commit has 18 failures + 43 errors). No new failures. New tests: promotion segments, hidden memberships in the public store listing, catalog overrides (category sync, resource, cart pricing). The Pest console printer prints nothing under PHP 8.4 locally, so results were read from the JUnit log.
• php-cs-fixer clean on the touched server files. phpstan is not run in CI; its pre-existing findings on PromotionEngine are unchanged.

Not in this PR (follow-ups)

• Multi-store carts from the console (one checkout, one order per store): the network create order places a single-store order; the app keeps the multi-store path.
• ember-ui extractions (Resource::Card generics, Form::SaveBar, Form::Steps, Notice, ContextSwitcher, HoursStrip) once the patterns settle here; they live in the ember-ui package.
• The nine non-English locales still miss the settings and notification keys; they need translators, not a code change.
• Board items the API cannot honour yet, left out rather than faked: settings toggles for reviews, account requirement and scheduled orders (no server rule reads them), truck pickup radius, network order bulk dispatch, Export on the orders and trucks pages (no export endpoint for these resources).
• Saved filters on order and product lists (P2 on the board).

Console dependency

• Extension loading templates only render if the console's console/app/routes/application.js loading action returns true. That change is on fleetbase/fleetbase release/v0.7.69 (e50764aa1).

Docs / API spec

User-facing behaviour, navigation and internal endpoints change: fleetbase.io storefront docs (networks, settings, promotions, create order) and the fleetbase/postman collections (network overview members[].backdrop_url, suspend/reinstate/approve/reject, console order quote/place, order customer and food_truck filters, product network filter, food truck today, store network_status, catalog product_overrides, cart add catalog, public catalog product price fields) need updates. Labels: needs-docs, needs-api-spec, module:storefront.