Skip to content

Decision 0005 — Photo Ordering And Group-Scoped Lightbox

  • Status: ACCEPTED
  • Date: 2026-08-14
  • Owner Task: NS0-002
  • Restriction delta: RD-000 / NONE
  • Runtime effect: NOT PERFORMED

Context

The current shared KJPhoto capability already provides media groups, persisted SEQUENCE, drag reorder, Sort by Name, thumbnail preview, previous/next, zoom and rotate. The Platform UI Pilot also demonstrates a PhotoSwipe lightbox adapter.

Relevant current-source evidence:

public/assets/js/modules/shared/kj-photo-plugin.js
frontend/pages/platform/ui/pilot.php

The Logistics Workspace design must preserve and formalize these capabilities rather than replace them with a page-local photo input or one-off gallery.

Decision

Ordering

Each media group has one authoritative manual sequence.

Sequence = persisted operational order
Name A-Z / Name Z-A / Newest / Oldest = view order

A view sort changes persisted sequence only after the user explicitly chooses Save order. Editable Sequence mode supports drag/drop and keyboard Move Earlier/Later. Sorting never silently changes media group.

Preview

Preview is a group-scoped lightbox.

opened thumbnail's group
+ current visible group order
= lightbox collection

The viewer supports Previous/Next, Left/Right, Home/End, thumbnail selection, index/total, zoom, rotate when supported, Open Original, Escape and focus return. It stops at group boundaries by default.

Consequences

  • Product pages use PhotoAttachmentTool; they do not implement their own photo ordering or viewer.
  • Existing KJPhoto remains the coexistence capability source until an accepted successor adapter owns the same contract.
  • Sequence persistence uses the shared file bulk-change authority and authoritative readback.
  • A sort, preview or lightbox navigation never changes business state.
  • Group reassignment remains a separate explicit command and permission.
  • NS1 UI Catalog must demonstrate sorting, keyboard reorder and the group-scoped lightbox before a photo surface is accepted.

Evidence Boundary

This decision approves UI/component behavior only. It does not change current PHP/JavaScript Runtime, file data, DB sequence, routes, writers, providers or Production behavior.

---

Source: new-system/docs/decisions/0005-photo-ordering-and-group-lightbox.md — ctc repository · This page is an English translation of the source document. Identifiers, file paths and code symbols are unchanged.