Cruise Offer Management - UI Requirements Specification¶

1. Introduction¶

1.1 Purpose¶

This document defines the user interface requirements for the Cruise Offer Management module. It specifies the layout, components, interactions, and visual design for the three dedicated cruise management pages.

1.2 Scope¶

This specification covers the cruise management administration interface accessible to internal users across three pages: Dashboard, Itinerary Management, and Agent Booking. It does not cover the public-facing booking interface (which will be specified separately).

1.3 References¶

General Requirements: Cruise-Offer-General-Requirements.md
Functional Requirements: Cruise-Offer-Management-Requirements.md
Frontend Specification: frontend-spec.md
Phase 3 Details: phase3-itinerary-page.md

1.4 Design Language¶

The UI follows the established TQPro design language: - CSS Framework: Bootstrap 5.3.0 - Icons: Bootstrap Icons + FontAwesome 6 - Color Scheme: Primary (#362c5d), Secondary (#FFC166), semantic colors for status, company-specific colors - Typography: Inter/Noto Sans font family, Montserrat for body - Components: Accordions, card grids, pill buttons, modals, status badges, tables, breadcrumbs - JS Libraries: jQuery 3.7.1, ES6 Modules, Notify.js

2. Page Structure¶

2.1 Three-Page Architecture¶

The cruise management module is split across three dedicated pages, each with a focused responsibility. All three pages are accessible from the main navigation menu under "Cruises".

Page	URL	Purpose
Dashboard	`cruise-dash.html`	High-level overview, company/ship management, itinerary grid
Itinerary Management	`cruise-itin.html?itineraryId=N`	Single itinerary editing, template, pricing, sailing management
Agent Booking	`cruise-agt-book.html?cruiseId=N` or `?bookingId=N`	Booking creation and management for agents

Main Nav Menu
    └── Cruises → cruise-dash.html (Dashboard)
                      │
                      ├── "Manage" link on itinerary card
                      │       └── cruise-itin.html?itineraryId=N (Itinerary Page)
                      │               │
                      │               └── Booking row click
                      │                       └── cruise-agt-book.html?bookingId=N (Agent Booking)
                      │
                      └── (future: direct link to booking page)
                                └── cruise-agt-book.html?cruiseId=N (Agent Booking)

ID	Requirement
UI-NAV-001	The cruise management pages shall be accessible from the main navigation menu.
UI-NAV-002	A "Cruises" menu item shall appear in the top navigation bar.
UI-NAV-003	The menu item shall use an appropriate cruise/ship icon (`fa-ship`).
UI-NAV-004	Each page shall display a breadcrumb bar for context navigation (e.g., Dashboard > Cruises > [Itinerary Name]).

2.4 Shared Page Structure¶

ID	Requirement
UI-LAY-001	All pages use `<body class="cruise-page" style="visibility:hidden">` for auth-gated display.
UI-LAY-002	All pages include the shared header template `header_bootstrap.html`.
UI-LAY-003	All pages include `cruise.css` for shared cruise-specific styles.
UI-LAY-004	The main content container uses `container-fluid cruise-container` with `margin-top: 80px`.
UI-LAY-005	All pages use Bootstrap 5 grid system (`row`, `col-md-*`, `gx-3`).

2.5 Authentication Pattern¶

All pages use the same authentication pattern:

<body class="cruise-page" style="visibility:hidden">

await $site.setGlobalHandlers({ requireAuth: true });
document.body.style.visibility = 'visible';

3. Dashboard - Left Pane (Company Accordion)¶

3.1 Layout¶

The left pane occupies col-md-3 and contains a company accordion with management controls.

┌──────────────────────┐
│ <ship> Companies     │
│           [+ Co] [⚙] │
├──────────────────────┤
│ [Company 1]  ▼       │  ← company-colored header
│   Ship A             │
│   Ship B             │
│   [+ Ship] [Edit Co] │
│   [+ Itin] [Del Co]  │
├──────────────────────┤
│ [Company 2]  ►       │
│                      │
└──────────────────────┘

3.2 Company Accordion Header¶

ID	Requirement
UI-DASH-001	The header shall display title "Companies" with a ship icon (`fa-solid fa-ship`).
UI-DASH-002	The header shall contain two action buttons: Add Company (`btn btn-sm btn-primary`, `bi-plus-lg`) and Settings (`btn btn-sm btn-outline-secondary`, `bi-gear`).
UI-DASH-003	The Settings button shall open the Settings modal for managing dimensional data (areas, ports, cabin types, charge types).

3.3 Company Accordion Structure¶

ID	Requirement
UI-DASH-010	The accordion shall use Bootstrap's `.accordion` component (`id="companyAccordion"`).
UI-DASH-011	Each company shall be a collapsible accordion item with its name as the header text.
UI-DASH-012	Each company header shall use the company's `color` field as the background/accent color.
UI-DASH-013	Inside each expanded company section, the ship list shall be displayed.
UI-DASH-014	Each company section shall have action buttons: Add Ship, Edit Company, Add Itinerary, Delete Company.
UI-DASH-015	Clicking a company header shall expand/collapse its section.

3.4 Settings Dialog (Dimension Data)¶

ID	Requirement
UI-DASH-020	The Settings modal (`id="settingsModal"`) shall use Bootstrap tabs for different dimension data types.
UI-DASH-021	Tabs: Areas, Ports, Cabin Types, Charge Types.
UI-DASH-022	Each tab shall display a table with code, name/description, and action columns.
UI-DASH-023	Each tab shall have an Add button (`btn btn-success btn-sm`, `bi-plus-lg`) to open a sub-dialog for creating entries.
UI-DASH-024	Table action buttons shall include Edit (`btn btn-sm btn-primary`, `bi-pencil`) and Delete (`btn btn-sm btn-danger`, `bi-trash`).

4. Dashboard - Right Pane (Itinerary Overview)¶

4.1 Layout¶

The right pane occupies col-md-9 and contains KPI summary cards, a filter bar, and an itinerary card grid.

┌──────────────────────────────────────────┐
│  KPI Cards                               │
│  [Areas] [Ships] [Itineraries] [Sailings]│
├──────────────────────────────────────────┤
│  Filter Bar                              │
│  [Area ▼] [Company ▼] [Status ▼] [+New] │
├──────────────────────────────────────────┤
│  Itinerary Cards Grid                    │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│  │ Itin 1   │ │ Itin 2   │ │ Itin 3   │ │
│  │ 7N Gulf  │ │ 5N Med   │ │ 3N Greek │ │
│  │ [Manage] │ │ [Manage] │ │ [Manage] │ │
│  └──────────┘ └──────────┘ └──────────┘ │
└──────────────────────────────────────────┘

4.2 KPI Summary Cards¶

ID	Requirement
UI-DASH-030	The KPI strip shall display five summary cards in a CSS Grid row (`grid-template-columns: repeat(5, 1fr)`).
UI-DASH-031	Card 1: "Sailing Areas" (`bi-globe2`, primary color), showing total area count.
UI-DASH-032	Card 2: "Ships" (`fa-solid fa-ship`, info color), showing total ship count.
UI-DASH-033	Card 3: "Itineraries" (`fa-solid fa-route`, success color), showing total itinerary count.
UI-DASH-034	Card 4: "Sailings" (`bi-calendar3`, warning color), showing total sailing count.
UI-DASH-034a	Card 5: "Bookings" (`bi-person-vcard`, secondary color), showing total booking count across all sailings.
UI-DASH-035	Each KPI card shall use the `.kpi-card` class with icon, value, and title elements.

4.3 Filter Bar¶

ID	Requirement
UI-DASH-040	The filter bar shall display dropdown filters and an action button in a flex row.
UI-DASH-041	Filters: Area dropdown (`filterArea`), Company dropdown (`filterCompany`), Status dropdown (`filterStatus`).
UI-DASH-042	Status dropdown options: All Statuses, Draft, Active, Suspended, Archived.
UI-DASH-043	A "New Itinerary" button (`btn btn-primary btn-sm`, `bi-plus-lg`) shall appear at the right end. Creating a new itinerary shall redirect to `cruise-itin.html?itineraryId=N` after save.
UI-DASH-044	Changing any filter shall immediately refresh the itinerary card grid.

4.4 Itinerary Card Grid¶

ID	Requirement
UI-DASH-050	Itinerary cards shall be displayed in a responsive grid, 3 per row on desktop (`col-md-4`).
UI-DASH-051	Each card shall show: itinerary name, code, ship name, duration (nights), port count (loaded from templates), area name, status badge, sailing count.
UI-DASH-052	Each card footer shall have four buttons: Edit (opens itinerary dialog), Copy (opens itinerary dialog pre-populated with source data, name suffixed with "(Copy)", redirects after save), Manage (navigates to `cruise-itin.html?itineraryId=N`), Print (opens `cruise-itin.html?itineraryId=N&print=true` in new tab).
UI-DASH-053	Cards shall use the `.itin-card` CSS class from `cruise.css`.
UI-DASH-054	If no itineraries match filters, show empty state: "No Itineraries Found" with water icon (`bi-water`).

5. Itinerary Page - Left Pane¶

5.1 Layout¶

The itinerary page uses a two-pane, 50/50 split layout (col-md-6 each). The left pane contains the itinerary info form, template table, and pricing templates.

┌── Itinerary Information ───────┐
│ <route> Itinerary Information  │
│ [Status Badge]   [Save][St][X] │
│ Code: [____] Name: [________]  │
│ Duration: [__]                 │
│ Area: [▼_____] Ship: [▼_____] │
└────────────────────────────────┘
┌── Itinerary Template ──────────┐
│ <list> Itinerary Template [+]  │
│ # | Port | DayA | Arr | DayD.. │
│ 1 | Dubai | 0   | 08:00 | 0.. │
│ 2 | Doha  | 1   | 06:00 | 1.. │
└────────────────────────────────┘
┌── Pricing Template ────────────┐
│ <$> Pricing Template [Init]    │
│                                │
│ <bed> Cabin Prices (Default)   │
│ CabinType | Pax | Amt | Curr.. │
│                                │
│ <receipt> Other Charges [+]    │
│ Charge | Amt | Curr | Mand |.. │
└────────────────────────────────┘

5.2 Itinerary Info Form¶

ID	Requirement
UI-ITN-001	The itinerary info section shall display editable fields for the selected itinerary.
UI-ITN-002	Fields: Code (text, maxlength 10), Name (text, maxlength 100), Duration in nights (number, min 1, max 365).
UI-ITN-003	Dropdowns: Area (`edit_itin_area`, populated from dimension data), Ship (`edit_itin_ship`, populated from dimension data).
UI-ITN-004	A status badge (`itin_status_badge`) shall display the current itinerary status next to the section title.
UI-ITN-005	Action buttons in the section header: Save (`btn-success`, `bi-check-lg`), Status dropdown (`btn-secondary`, `bi-arrow-repeat`), Delete (`btn-danger`, `bi-trash`).
UI-ITN-006	The Status dropdown shall show valid status transitions (Draft, Active, Suspended, Archived).
UI-ITN-007	Delete itinerary shall show confirmation dialog and redirect to `cruise-dash.html` on success.
UI-ITN-008	When the page is loaded with `?print=true` URL parameter, `window.print()` shall be auto-triggered after a 500ms delay. Existing `@media print` CSS hides interactive elements.

5.3 Template Table¶

ID	Requirement
UI-ITN-010	The template section shall display the itinerary port sequence in a table.
UI-ITN-011	Table columns: # (stop sequence), Port, Day (Arr), Arrive (time), Day (Dep), Depart (time), Actions.
UI-ITN-012	An Add button (`btn-success`, `bi-plus-lg`) in the section header shall open the template entry dialog.
UI-ITN-013	Each row shall have Edit (`bi-pencil`) and Delete (`bi-trash`) action buttons.
UI-ITN-014	Template entries shall be sorted by stop sequence ascending.

5.4 Pricing Templates¶

The pricing template section has two sub-sections: cabin prices and other charges.

5.4.1 Cabin Price Templates¶

ID	Requirement
UI-ITN-020	The "Cabin Prices (Default)" sub-section shall display a table of default cabin pricing.
UI-ITN-021	Table columns: Cabin Type, Pax (max passengers), Amount, Curr (currency), Actions.
UI-ITN-022	An "Init Cabins" button (`fa-solid fa-wand-magic-sparkles`) in the section header shall auto-create templates for all ship cabins of the itinerary's ship.
UI-ITN-023	Each row shall have an Edit action button that opens the cabin price template dialog with exchange rate auto-fill.

5.4.2 Other Charge Templates¶

ID	Requirement
UI-ITN-030	The "Other Charges (Default)" sub-section shall display a table of default additional charges.
UI-ITN-031	Table columns: Charge (type name), Amount, Curr, Mand (mandatory flag), Ind (indicator badge), Pax (type), Actions.
UI-ITN-032	An Add button (`btn-success`, `bi-plus-lg`) shall open the charge template dialog.
UI-ITN-033	The Ind column shall display a single-letter indicator badge (`.indicator-badge` span) when set.
UI-ITN-034	Each row shall have Edit and Delete action buttons.

5.5 Itinerary Page - Right Pane¶

5.5.1 Layout¶

The right pane displays sailing management: a sailing bar and detailed sections for the selected sailing.

┌── Sailing Information ─────────┐
│ <cal> Sailing Information [+]  │
│ [15 Mar] [22 Mar] [29 Mar]    │  ← pill-shaped buttons
└────────────────────────────────┘

┌── Sailing Details ─────────────┐
│ Cruise: 15 Mar 2026 (7 nights) │
│ [Regen Points] [Status ▼] [X] │
│                                │
│ <anchor> Sailing Details        │
│ # | Port | Arrival | Departure │
│                                │
│ <bed> Cabin Pricing [Prebook]  │
│ Cabin|Pax|Amt|Curr|Prebk|Avail │
│                                │
│ <receipt> Other Charges    [+] │
│ Charge|Amt|Curr|Mand|Ind|Pax  │
│                                │
│ <person> Bookings              │
│ Customer|Cabin|#Pax|Amt|Status │
└────────────────────────────────┘

5.5.2 Sailing Bar¶

ID	Requirement
UI-SAL-001	The sailing bar shall display pill-shaped buttons for each sailing of the itinerary.
UI-SAL-002	Each pill shall show the start date formatted as "DD MMM" (e.g., "15 Mar").
UI-SAL-003	Pills shall be ordered by start date ascending.
UI-SAL-004	The selected sailing pill shall have a visual highlight (primary color background).
UI-SAL-005	An "Add New" button (`btn-success`, `bi-plus-lg`) shall appear in the section header to create a new sailing.
UI-SAL-006	If no sailings exist, show message: "No sailings. Click Add New to create one."

ID	Requirement
UI-SAL-010	When a sailing is selected, an action toolbar shall appear below the sailing bar.
UI-SAL-011	The toolbar shall show sailing date and duration text.
UI-SAL-012	Actions: Regen Points (`btn-info`, `fa-solid fa-rotate`), Status dropdown (`btn-secondary`, `bi-arrow-repeat`), Delete (`btn-warning`, `bi-trash`).
UI-SAL-013	Regen Points shall show a confirmation dialog before regenerating cruise points from the template.

5.5.4 Cruise Points Table¶

ID	Requirement
UI-SAL-020	The cruise points section shall display the sailing route in a table.
UI-SAL-021	Table columns: # (sequence), Port, Arrival (date/time), Departure (date/time), Actions.
UI-SAL-022	Each row shall have an Edit action button that opens the cruise point edit dialog.
UI-SAL-023	If no cruise points exist, show message prompting to generate from template.

5.5.5 Cabin Charges Table¶

ID	Requirement
UI-SAL-030	The cabin pricing section shall display cabin charges for the selected sailing.
UI-SAL-031	Table columns: Cabin (type name), Pax (max passengers), Amount, Curr, Prebk (pre-booking count), Avail (available pre-bookings), Actions.
UI-SAL-032	The Prebk column shall show the count of pre-bookings for this cabin type and sailing.
UI-SAL-033	The Avail column shall show pre-bookings minus booked/reserved (minimum 0).
UI-SAL-034	A "Prebook" button (`btn-primary`, `fa-solid fa-bookmark`) in the section header shall open the pre-booking management dialog.
UI-SAL-035	Each row shall have an Edit action button that opens the cabin charge edit dialog.

5.5.6 Other Charges Table¶

ID	Requirement
UI-SAL-040	The other charges section shall display additional charges for the selected sailing.
UI-SAL-041	Table columns: Charge (type name), Amt, Curr, Mand (mandatory), Ind (indicator badge), Pax (type), Actions.
UI-SAL-042	An Add button shall open the other charge dialog.
UI-SAL-043	The Ind column shall display the single-letter indicator badge when set.
UI-SAL-044	Each row shall have Edit and Delete action buttons.

5.5.7 Bookings Table¶

ID	Requirement
UI-SAL-050	The bookings section shall display current bookings for the selected sailing.
UI-SAL-051	Table columns: Customer (lead passenger name), Cabin / Add-ons (badges), #Pax, Amount, Status.
UI-SAL-052	Add-on badges shall be small indicator circles, deduplicated from the booking's add-ons.
UI-SAL-053	Rows shall be clickable, navigating to `cruise-agt-book.html?bookingId=N`.
UI-SAL-054	Status column shall use the `statusBadge()` helper for consistent badge rendering.

5.6 Agent Booking Page - Sailing Strip¶

5.6.1 Layout¶

The sailing strip spans the full page width and provides scrollable navigation across all available sailings.

┌─────────────────────────────────────────────────────────┐
│  <ship> Available Sailings                               │
│  ◄ [15 Mar MED7] [22 Mar MED7] [29 Mar GRK5] [5 Apr] ► │
└─────────────────────────────────────────────────────────┘

5.6.2 Sailing Strip Requirements¶

ID	Requirement
UI-AGT-001	The sailing strip shall display pill-shaped buttons for all available sailings across itineraries.
UI-AGT-002	Each pill shall show the start date and itinerary code (e.g., "15 Mar MED7").
UI-AGT-003	Pill borders shall use the company's `color` field for visual identification.
UI-AGT-004	The strip shall be horizontally scrollable with left/right scroll buttons (`bi-chevron-left`, `bi-chevron-right`).
UI-AGT-005	The strip container uses `.sailing-strip-container` with `.sailing-strip` inner div.
UI-AGT-006	Clicking a pill shall select that sailing and load its data (cabin availability, bookings).
UI-AGT-007	The selected pill shall have visual highlight (filled background).

5.7 Agent Booking Page - Left Pane¶

5.7.1 Layout¶

The left pane occupies col-md-6 (class booking-pane-left) and shows cabin availability and bookings for the selected sailing. Both left and right panes scroll independently with max-height: calc(100vh - 160px); overflow-y: auto; (disabled in @media print).

┌── Cabin Availability ─────────┐
│ <bed> Cabin Availability [Pbk] │
│ Type | Prebkd | Avail | Price  │
│ Suite|   2    |   1   | $500   │
│ Ocean|   0    |   0   | $300   │
└────────────────────────────────┘
┌── Bookings ───────────────────┐
│ <person> Bookings        [+]  │
│ ID | Cabins | Pax | Amt | St  │
│ PT-2302-AB.. | 2 | 4 | $800.. │
│ PT-2302-CD.. | 1 | 2 | $300.. │
└────────────────────────────────┘

5.7.2 Cabin Availability Table¶

ID	Requirement
UI-AGT-010	The cabin availability section shall display available cabin types for the selected sailing.
UI-AGT-011	Table columns: Type (cabin type name), Prebkd (pre-booked count, `---` if no prebooks), Avail (available count, `---` if no prebooks), Price (charge amount), Actions.
UI-AGT-012	The Prebkd column shall show the count of pre-bookings for each cabin type.
UI-AGT-013	The Avail column shall show pre-bookings minus booked/reserved (minimum 0).
UI-AGT-014	A "Prebook" button (`btn-primary`, `fa-solid fa-bookmark`) shall open the quick prebook management dialog.

5.7.3 Bookings List¶

ID	Requirement
UI-AGT-020	The bookings section shall display all bookings for the selected sailing.
UI-AGT-021	Table columns: ID (booking number, truncated), Customer (lead passenger name), Pax (total), Cabins (count), Amount, Status (badge).
UI-AGT-022	A "New" button (`btn-success`, `bi-plus-lg`) shall open the new booking dialog.
UI-AGT-023	Clicking a booking row shall select it and display its details in the right pane.
UI-AGT-024	The selected booking row shall have visual highlight.

5.8 Agent Booking Page - Right Pane¶

5.8.1 Layout¶

The right pane occupies col-md-6 (class booking-pane-right) and shows full booking details when a booking is selected. When no booking is selected, an empty state is shown. Scrolls independently from the left pane.

┌── Booking Header ─────────────┐
│ <ticket> PT-2302-AB12CD34      │
│ [Status Badge]                 │
│ [Status ▼] [Delete]           │
└────────────────────────────────┘
┌── Passengers ─────────────────┐
│ <users> Passengers        [+] │
│ Name | Nationality | Age | .. │
│ J. Smith | US [visa] | Adult  │
│ M. Smith | US [visa] | Child  │
└────────────────────────────────┘
┌── Cabins Booked ──────────────┐
│ <bed> Cabins Booked       [+] │
│ Cabin | Pax | Own | Amt | St  │
│ Suite | 4   | [Own]| $500 |.. │
│ Total:              $500      │
└────────────────────────────────┘
┌── Add-ons ────────────────────┐
│ <receipt> Add-ons         [+] │
│ Add-On | Passenger | Amt | .. │
│ Port Tax | J. Smith | $25 |.. │
│ Total:               $75     │
└────────────────────────────────┘

5.8.2 Booking Header¶

ID	Requirement
UI-AGT-030	The booking header shall display the booking number (format: PT-DDMM-XXXXXXXX).
UI-AGT-031	A status badge shall display the current booking status.
UI-AGT-032	Actions: Status dropdown (`btn-secondary`, `bi-arrow-repeat`) with valid transitions, Delete (`btn-danger`, `bi-trash`), New (`btn-success`, `bi-plus-lg`) to create a new booking.
UI-AGT-033	When no booking is selected, show empty state: "No Booking Selected" with ticket icon.

5.8.3 Passengers Table¶

ID	Requirement
UI-AGT-040	The passengers table shall display all passengers of the selected booking. The section header shall show a passenger count in "X of Y" format (current count of expected total).
UI-AGT-041	Table columns: Name (first + last, lead passenger marked), Nationality (ISO code), Age (category badge), Remark, Actions.
UI-AGT-041a	A capacity warning alert (`alert-danger`, hidden by default) shall appear below the passengers table when total passengers exceed the sum of `maxPax` across all booked cabins.
UI-AGT-042	Age column shall display a computed age category badge: Adult (>=12), Child (2-11), Infant (<2), based on date of birth relative to sailing start date.
UI-AGT-043	Visa information shall be displayed per passenger based on destination ports (via visa API).
UI-AGT-044	An Add button (`btn-success`, `bi-plus-lg`) shall open the passenger dialog.
UI-AGT-045	Each row shall have Edit (`bi-pencil`) and Delete (`bi-trash`) action buttons.

5.8.4 Booked Cabins Table¶

ID	Requirement
UI-AGT-050	The booked cabins table shall display cabins assigned to the booking.
UI-AGT-051	Table columns: Cabin (type name), Pax (number of passengers), Own (own/prebook badge), Amount (price), Status, Actions.
UI-AGT-052	The Own column shall display a badge indicating whether the cabin is from the company's own pre-booked inventory (`isOwn=true`) or external.
UI-AGT-053	A table footer (`<tfoot>`) shall display the cabin total amount.
UI-AGT-054	An Add button (`btn-success`, `bi-plus-lg`) shall open the add cabin dialog.
UI-AGT-055	Each row shall have a Delete action button.
UI-AGT-056	When adding a cabin, `numPax` shall be validated against the cabin type's `maxPax`. The NumPax input field shall have a dynamic `max` attribute set from the selected cabin type. Both client-side and server-side (error `CRU0207`) validation shall prevent exceeding cabin capacity.

5.8.5 Add-ons Table¶

ID	Requirement
UI-AGT-060	The add-ons table shall display optional charges attached to the booking.
UI-AGT-061	Table columns: Add-On (charge type name), Passenger (assigned passenger name or "All"), Amount, Actions.
UI-AGT-062	A table footer (`<tfoot>`) shall display the add-on total amount.
UI-AGT-063	An Add button (`btn-success`, `bi-plus-lg`) shall open the add add-on dialog.
UI-AGT-064	Each row shall have a Delete action button.
UI-AGT-065	Booking total amount shall be automatically recalculated from cabin prices plus add-on amounts whenever cabins or add-ons change.
UI-AGT-066	When adding an add-on, the passenger dropdown shall be filtered by the charge type's `paxType` attribute: `"adult"` excludes passengers with age < 12, `"child"` excludes passengers with age >= 12, `"per_cabin"` disables the passenger dropdown, `"all"` shows all passengers.

6. Dialogs¶

6.1 Dialog Design Standards¶

ID	Requirement
UI-DLG-001	All dialogs shall use Bootstrap 5's Modal component with `data-bs-backdrop="static"` and `data-bs-keyboard="false"`.
UI-DLG-002	Dialogs shall have consistent structure: `.modal-header` (icon + title + close button), `.modal-body` (form fields), `.modal-footer` (Cancel + Save/Confirm).
UI-DLG-003	Dialog headers shall include a FontAwesome icon and descriptive title.
UI-DLG-004	Dialog footers shall have Cancel (`btn btn-secondary`, `data-bs-dismiss="modal"`) and Save (`btn btn-success`, `bi-check-lg`).
UI-DLG-005	Destructive actions (delete) shall use danger-colored confirm buttons with `bi-trash` icon.
UI-DLG-006	Footer left side shall display "* Required" hint text (`small text-muted me-auto`).
UI-DLG-007	Form validation errors shall display inline below the relevant field.

Dialog Footer Pattern:

<div class="modal-footer">
    <small class="text-muted me-auto">* Required</small>
    <button class="btn btn-secondary" data-bs-dismiss="modal">Cancel</button>
    <button class="btn btn-success" id="entity_save"><i class="bi bi-check-lg"></i> Save</button>
</div>

6.2 Dashboard Dialogs¶

6.2.1 Company Dialog (`company_dlg`)¶

ID	Requirement
UI-DLG-010	Company dialog shall allow creating/editing a cruise company.
UI-DLG-011	Fields: Code (required, max 10 chars), Name (required, max 50 chars), Logo URL (optional), Color (color picker, default #362c5d).
UI-DLG-012	Title shall change based on mode: "New Company" or "Edit Company".

6.2.2 Ship Dialog (`ship_dlg`)¶

ID	Requirement
UI-DLG-020	Ship dialog shall allow creating/editing a cruise ship.
UI-DLG-021	Fields: Code (required, max 10 chars), Name (required, max 50 chars), Description (textarea), Document URL.
UI-DLG-022	Cabin Assignment sub-section: display all cabin types as checkboxes with Max Passengers input for each checked type.
UI-DLG-023	On save, system shall create/update/delete ship cabin assignments via `bulkAssignCabins()`.

6.2.3 Itinerary Dialog (`itinerary_dlg`)¶

ID	Requirement
UI-DLG-030	Itinerary dialog shall allow creating a new itinerary from the dashboard.
UI-DLG-031	Fields: Code (max 10), Name (max 100), Duration in nights, Ship dropdown (filtered by selected company), Area dropdown, Image URL.

6.2.4 Settings Sub-Dialogs¶

ID	Requirement
UI-DLG-040	Area dialog (`area_dlg`): Code (max 10), Name (max 50). Icon: `fa-solid fa-globe`.
UI-DLG-041	Port dialog (`port_dlg`): Code (max 10), Name (max 50), Country (max 50). Icon: `fa-solid fa-anchor`.
UI-DLG-042	Cabin Type dialog (`cabintype_dlg`): Code (max 10), Name (max 50), Description (textarea). Icon: `fa-solid fa-bed`.
UI-DLG-043	Charge Type dialog (`chargetype_dlg`): Code (max 10), Name (max 50), Description (textarea). Icon: `fa-solid fa-dollar-sign`.

6.3 Itinerary Page Dialogs¶

6.3.1 Template Entry Dialog (`template_dlg`)¶

ID	Requirement
UI-DLG-050	Template entry dialog shall allow creating/editing itinerary template entries.
UI-DLG-051	Fields: Stop Sequence (number, 1-99), Port (dropdown), Day Offset Arrival (number, 0-365), Arrival Time (time picker), Day Offset Departure, Departure Time, Description (textarea).

6.3.2 Cabin Price Template Dialog (`cabintemplate_dlg`)¶

ID	Requirement
UI-DLG-055	Cabin price template dialog shall allow editing default cabin pricing.
UI-DLG-056	Read-only fields: Cabin Type name, Max Passengers (displayed but not editable).
UI-DLG-057	Editable fields: Amount (number, step 0.01), Currency (dropdown, `cruise-currency-select`), Exchange Rate (number, step 0.0001, auto-filled but editable).

6.3.3 Charge Template Dialog (`chargetemplate_dlg`)¶

ID	Requirement
UI-DLG-060	Charge template dialog shall allow creating/editing default other charges.
UI-DLG-061	Fields: Charge Type (dropdown), Amount, Currency (auto-fill exrate), Exchange Rate, Passenger Type (All/Adults/Children/Per Cabin), Indicator (single character, max 1), Mandatory (checkbox).

6.3.4 Sailing Dialog (`sailing_dlg`)¶

ID	Requirement
UI-DLG-070	Sailing dialog shall allow creating a new cruise instance.
UI-DLG-071	Fields: Start Date (date picker, required).
UI-DLG-072	Display: Itinerary name for reference.
UI-DLG-073	Checkbox: "Generate sailing points from template" (checked by default).

6.3.5 Cruise Point Edit Dialog (`cruisepoint_dlg`)¶

ID	Requirement
UI-DLG-075	Cruise point dialog shall allow editing a sailing point.
UI-DLG-076	Fields: Stop # (number), Port (dropdown), Arrival Date/Time (datetime-local), Departure Date/Time (datetime-local), Description (textarea).

6.3.6 Cabin Charge Dialog (`cabincharge_dlg`)¶

ID	Requirement
UI-DLG-080	Cabin charge dialog shall allow editing sailing-specific cabin pricing.
UI-DLG-081	Read-only fields: Cabin Type name, Max Passengers.
UI-DLG-082	Editable fields: Amount, Currency (auto-fill exrate), Exchange Rate, Available (checkbox).

6.3.7 Other Charge Dialog (`othercharge_dlg`)¶

ID	Requirement
UI-DLG-085	Other charge dialog shall allow creating/editing sailing-specific charges.
UI-DLG-086	Fields: Charge Type (dropdown), Amount, Currency (auto-fill exrate), Exchange Rate, Passenger Type, Indicator (single char), Mandatory (checkbox).

6.3.8 Pre-Booking Dialog (`prebook_dlg`)¶

ID	Requirement
UI-DLG-090	Pre-booking dialog shall allow managing cabin pre-bookings for the selected sailing.
UI-DLG-091	Fields: Cabin Type (dropdown from ship cabins), Total Cabins (target count), Cost per Cabin, Price per Cabin, Commission %, "Apply price to all" checkbox.
UI-DLG-092	On cabin type selection: display info panel (`.prebook-info`) showing current count and booked/reserved count.
UI-DLG-093	Validation: target count cannot be reduced below the number of non-Available (Reserved + Booked) pre-bookings.
UI-DLG-094	Uses `CruiseAPI.managePrebookings()` for smart add/reduce logic.

6.4 Agent Booking Page Dialogs¶

6.4.1 New Booking Dialog (`newbooking_dlg`)¶

ID	Requirement
UI-DLG-100	New booking dialog shall allow creating a new booking for the selected sailing.
UI-DLG-101	Pax count fields: Adults (number, min 1, default 2), Children (number, min 0), Infants (number, min 0). Total auto-calculated.
UI-DLG-102	Cabin fields: Cabin Type (dropdown from available cabin charges), Cabins (count), Pax/Cabin.
UI-DLG-103	Lead passenger section: First Name, Last Name, Nationality (text input with autocomplete from restcountries.com), Date of Birth, Passport #.
UI-DLG-104	Nationality input shall have an autocomplete dropdown (`.nationality-autocomplete`) with a hidden field for alpha2 code.
UI-DLG-105	On save: generate booking number (PT-DDMM-XXXXXXXX), create booking with "Documents pending" status, create lead passenger, assign cabin (checking for available pre-bookings for own assignment), recalculate totals.
UI-DLG-106	Uses `modal-lg` size for wider layout.

6.4.2 Passenger Dialog (`passenger_dlg`)¶

ID	Requirement
UI-DLG-110	Passenger dialog shall allow adding/editing passengers.
UI-DLG-111	Fields: First Name, Last Name, Nationality (autocomplete), Date of Birth, Lead Passenger (checkbox), Passport #, Passport Expiry.
UI-DLG-112	Age indicator (`passenger_age_indicator`): shown below DOB field, displays computed category (Adult/Child/Infant) based on sailing start date.
UI-DLG-113	Visa info area (`passenger_visa_info`): displays visa requirement badges per destination port when nationality is selected.

6.4.3 Add Cabin Dialog (`addcabin_dlg`)¶

ID	Requirement
UI-DLG-120	Add cabin dialog shall allow adding a cabin to a booking.
UI-DLG-121	Fields: Cabin Type (dropdown), Num Passengers (number, min 1, max 10, default 2).
UI-DLG-122	Info panel (`.prebook-info`): shows prebook availability and own/non-own indicator when cabin type is selected.
UI-DLG-123	On save: check for Available pre-bookings, assign as own if available, otherwise assign as non-own. Price auto-filled from cabin charge.

6.4.4 Add Add-on Dialog (`addaddon_dlg`)¶

ID	Requirement
UI-DLG-130	Add add-on dialog shall allow adding optional charges to a booking.
UI-DLG-131	Fields: Charge Type (dropdown from sailing's non-mandatory other charges), Passenger (dropdown, optional, "All passengers" default), Amount (pre-filled from selected charge type).

6.4.5 Prebook Dialog (Agent Page) (`prebook_dlg`)¶

ID	Requirement
UI-DLG-135	Quick prebook dialog on the agent page shall function identically to the itinerary page prebook dialog (see UI-DLG-090 through UI-DLG-094).

6.5 Confirmation Dialog (`confirm_dlg`)¶

ID	Requirement
UI-DLG-140	All three pages include a generic confirmation dialog.
UI-DLG-141	The dialog shall display a message and have Cancel and Delete/Confirm buttons.
UI-DLG-142	Delete confirmations shall clearly state what will be deleted.

7. Exchange Rate Auto-Fill Behavior¶

7.1 Overview¶

When a currency dropdown (.cruise-currency-select) value changes in any pricing dialog, the exchange rate field is automatically populated.

7.2 Auto-Fill Logic¶

ID	Requirement
UI-EXR-001	If the selected currency equals the local currency (from server config), the exchange rate shall be set to 1.0.
UI-EXR-002	Otherwise, the rate shall be fetched from `exchange-rate-service.js` using the `fetchRates()` function.
UI-EXR-003	Rates are cached in `localStorage` with a 24-hour TTL (`tqpro_exchange_rates` key).
UI-EXR-004	The exchange rate field shall remain editable for manual override after auto-fill.
UI-EXR-005	Each rate field displays a hint: "Auto-filled, editable" (`small text-muted`).
UI-EXR-006	Currency config is loaded once via `loadCurrencyConfig()` and cached in memory.

7.3 Applied Dialogs¶

Exchange rate auto-fill is applied to the following dialogs: - Cabin Price Template (cabintemplate_dlg) - Charge Template (chargetemplate_dlg) - Cabin Charge (cabincharge_dlg) - Other Charge (othercharge_dlg)

ID	Requirement
UI-EXR-010	Currency dropdowns shall be populated by `populateCurrencySelect()` from the exchange rate service.
UI-EXR-011	Options include currency code and name (e.g., "USD - US Dollar").
UI-EXR-012	Available currencies come from the server-side `quotationCurrencies` config.

8. Status Indicators¶

8.1 Itinerary Status Colors¶

Status	Badge Class	Bootstrap Color
Draft	`bg-secondary`	Gray
Active	`bg-success`	Green
Suspended	`bg-warning`	Yellow
Archived	`bg-dark`	Dark

8.2 Sailing (Cruise) Status Colors¶

Status	Badge Class	Bootstrap Color
Draft	`bg-secondary`	Gray
Active	`bg-success`	Green
Suspended	`bg-warning`	Yellow
Cancelled	`bg-danger`	Red
Completed	`bg-info`	Blue

8.3 Booking Status Colors¶

Status	Badge Class	Bootstrap Color	Description
Documents pending	`bg-info`	Light blue	Initial status after booking creation
Availability pending	`bg-primary`	Blue	Documents received, checking availability
Payment pending	`bg-warning`	Yellow	Availability confirmed, awaiting payment
Voucher pending	`bg-secondary`	Gray	Payment received, generating voucher
Vouchered	`bg-success`	Green	Booking complete, voucher issued
Cancelled-NonRefundable	`bg-danger`	Red	Cancelled, no refund
Cancelled-RefundPending	`bg-dark`	Dark	Cancelled, refund in progress
Cancelled-Refunded	`bg-dark`	Dark	Cancelled, refund completed

8.4 Status Badge Rendering¶

All status badges are rendered via the shared statusBadge(status) function from cruise-common.js:

const statusColors = {
    'Draft': 'secondary',
    'Active': 'success',
    'Suspended': 'warning',
    'Archived': 'dark',
    'Cancelled': 'danger',
    'Completed': 'info'
};

export function statusBadge(status) {
    const color = statusColors[status] || 'secondary';
    return `<span class="badge bg-${color}">${escapeHtml(status || '')}</span>`;
}

8.5 Indicator Badges¶

ID	Requirement
UI-STS-001	Other charge templates and charges with an indicator field shall display a single-letter badge.
UI-STS-002	The badge uses the `.indicator-badge` CSS class from `cruise.css`.
UI-STS-003	The indicator is a single character (maxlength=1) set during charge creation/editing.

9. Empty States¶

9.1 Empty State Design¶

ID	Requirement
UI-EMP-001	Empty states shall have centered layout with icon, heading, and description.
UI-EMP-002	Empty states use the `.cruise-empty-state` CSS class.
UI-EMP-003	Icons shall use `display-1` or `display-4` size class.

9.2 Empty State Messages¶

Context	Page	Icon	Heading	Description
No itineraries match filters	Dashboard	`bi-water`	No Itineraries Found	Create a new itinerary to get started.
No sailing selected	Itinerary	`fa-solid fa-calendar`	No Sailing Selected	Select a sailing above or create a new one.
No booking selected	Agent Booking	`fa-solid fa-ticket`	No Booking Selected	Select a booking from the list or create a new one.

10. Form Validation¶

10.1 Validation Rules¶

Field	Validation	Error Message
Company Code	Required, max 10 chars	"Code is required"
Company Name	Required, max 50 chars	"Name is required"
Ship Code	Required, max 10 chars	"Code is required"
Ship Name	Required, max 50 chars	"Name is required"
Itinerary Code	Required, max 10 chars	"Code is required"
Itinerary Duration	Required, positive integer, 1-365	"Duration must be a positive number"
Template Sequence	Required, 1-99	"Sequence is required"
Template Port	Required (dropdown)	"Port is required"
Cruise Start Date	Required, valid date	"Start date is required"
Charge Amount	Required, positive number	"Amount must be positive"
Currency	Required, from config	"Select a valid currency"
Template Time	Required, HH:mm format	"Enter time in HH:mm format"
Booking Adults	Required, min 1	"At least one adult required"
Lead Passenger Name	Required (first + last)	"Lead passenger name is required"
Pre-Booking Count	Cannot reduce below reserved+booked	"Cannot reduce below reserved count"

10.2 Validation Display¶

ID	Requirement
UI-VAL-001	Invalid fields shall have red border (Bootstrap `is-invalid` class).
UI-VAL-002	Error messages shall appear below the field in red text.
UI-VAL-003	Form submission shall be blocked until all validations pass.
UI-VAL-004	First invalid field shall receive focus on validation failure.

11. Loading States¶

11.1 Loading Indicators¶

ID	Requirement
UI-LOD-001	API calls shall show loading indicator.
UI-LOD-002	Tables shall show "Loading..." row during data fetch.
UI-LOD-003	Buttons shall show spinner and be disabled during save operations.
UI-LOD-004	Page body uses `visibility:hidden` until auth completes.

12. Notifications¶

12.1 Notification Types¶

Type	Style	Duration	Use Case
Success	Green	3 seconds	Save successful, create successful
Error	Red	5 seconds	API error, validation error
Warning	Yellow	4 seconds	Cascade delete warning, validation warning
Info	Blue	3 seconds	Status change, informational

12.2 Notification Implementation¶

ID	Requirement
UI-NOT-001	Notifications shall use the `$.notify()` library (existing in project).
UI-NOT-002	Notifications shall appear in top-right corner.
UI-NOT-003	Multiple notifications shall stack vertically.
UI-NOT-004	Notifications shall be dismissible by clicking.

13. Responsive Behavior¶

13.1 Breakpoints¶

Breakpoint	Dashboard Left	Dashboard Right	Itinerary Panes	Booking Panes
Large (1200px+)	`col-md-3`	`col-md-9`	`col-md-6` each	`col-md-6` each
Medium (768-1199px)	Full width	Full width	Full width	Full width
Small (<768px)	Full width	Full width	Full width	Full width

13.2 Mobile Adaptations¶

ID	Requirement
UI-RES-001	On small screens, columns shall stack vertically.
UI-RES-002	The sailing strip shall remain horizontally scrollable with scroll buttons.
UI-RES-003	Tables shall become scrollable horizontally on small screens.
UI-RES-004	Dialogs shall be full-width on mobile.

14. Keyboard Accessibility¶

Key	Action
Tab	Move between interactive elements
Enter	Activate button/link, submit form
Escape	Close dialog, cancel operation
Space	Toggle checkbox, activate button

14.2 Focus Management¶

ID	Requirement
UI-ACC-001	Focus shall be visible with outline style.
UI-ACC-002	Dialog open shall move focus to first input.
UI-ACC-003	Dialog close shall return focus to triggering element.
UI-ACC-004	Form validation error shall move focus to first invalid field.

15. JavaScript Module Structure¶

15.1 Module Organization¶

tqweb-adm/
├── cruise-dash.html            # Dashboard page
├── cruise-itin.html            # Itinerary management page
├── cruise-agt-book.html        # Agent booking page
├── css/
│   └── cruise.css              # All cruise-specific styles (~680 lines)
└── js/modules/
    ├── cruise-common.js        # Shared CruiseAPI client + utilities (~200 lines)
    ├── exchange-rate-service.js # Currency config + rate fetching (~200 lines)
    ├── cruise-dash.js          # Dashboard module (~1060 lines)
    ├── cruise-itin.js          # Itinerary management module (~1500 lines)
    └── cruise-agt-book.js      # Agent booking module (~1600 lines)

15.2 Shared Module: cruise-common.js¶

Export	Type	Purpose
`CruiseAPI`	Object	All API endpoint methods (company, ship, itinerary, template, pricing, cruise, booking, etc.)
`initCommon()`	Function	Loads all dimension data (companies, areas, ports, cabin types, charge types, ships) in parallel
`getCompanies()`, `getAreas()`, `getPorts()`, `getCabinTypes()`, `getChargeTypes()`, `getShips()`	Functions	Cached dimension data getters
`findCompany()`, `findArea()`, `findPort()`, `findCabinType()`, `findChargeType()`, `findShip()`	Functions	Lookup by ID helpers
`reloadCompanies()`, `reloadAreas()`, etc.	Functions	Reload individual dimension from server
`statusBadge(status)`	Function	Returns Bootstrap badge HTML for a status value
`paxTypeLabels`	Object	Passenger type display labels: All, Adults, Children, Per Cabin

15.3 Shared Module: exchange-rate-service.js¶

Export	Type	Purpose
`loadCurrencyConfig()`	Function	Loads local currency and quotation currencies from server config
`fetchRates(baseCurrency)`	Function	Fetches rates from open.er-api.com with 24h localStorage cache
`populateCurrencySelect(selector)`	Function	Populates `<select>` elements with currency options
`convertToLocal(amount, currency, rates, localCurrency)`	Function	Converts amount to local currency
`convertFromLocal(amount, currency, rates, localCurrency)`	Function	Converts amount from local currency
`convertAmount(amount, from, to, rates, localCurrency)`	Function	Converts between any two currencies via local

15.4 Page Module: cruise-dash.js¶

State:

let companies = [];
let ships = [];
let itineraries = [];
let areas = [];
let selectedCompany = null;

Key Functions:

Function	Purpose
`initializePage()`	Load dimension data, companies, ships, itineraries; render UI
`renderCompanyAccordion()`	Build Bootstrap accordion HTML from companies + ships
`renderKpiCards()`	Display summary counts in KPI strip
`renderItineraryCards()`	Filter and display itinerary card grid
`applyFilters()`	Apply area/company/status filters to itinerary cards
`showCompanyDialog()`	Open company create/edit dialog
`showShipDialog()`	Open ship create/edit dialog with cabin assignment
`showSettingsModal()`	Open dimension data management tabs

15.5 Page Module: cruise-itin.js¶

State:

let itinerary = null;
let templates = [];
let cabinPriceTemplates = [];
let otherChargeTemplates = [];
let cruises = [];            // sailings for this itinerary
let selectedCruise = null;
let cruisePoints = [];
let cabinCharges = [];
let otherCharges = [];
let prebookings = [];
let bookings = [];
let shipCabins = [];
let currencyConfig = null;

Key Functions:

Function	Purpose
`initializePage()`	Parse URL params, load itinerary + all related data
`loadItineraryData()`	Load itinerary, templates, pricing templates
`renderItineraryInfo()`	Populate info form fields and status badge
`renderTemplateTable()`	Build template port sequence table
`renderCabinPriceTemplates()`	Build cabin pricing template table
`renderOtherChargeTemplates()`	Build charge template table with indicator badges
`renderSailingBar()`	Build sailing pill buttons
`selectSailing(cruiseId)`	Load all sailing detail sections
`renderCruisePoints()`	Build cruise points table
`renderCabinCharges()`	Build cabin charges with Prebk/Avail columns
`renderOtherCharges()`	Build other charges with indicator badges
`renderBookings()`	Build bookings table with clickable rows
`showPrebookDialog()`	Open pre-booking management dialog
`handleCurrencyChange()`	Auto-fill exchange rate from cached rates

15.6 Page Module: cruise-agt-book.js¶

State:

let allSailingData = [];      // all sailings across itineraries for the company
let selectedCruise = null;
let selectedItinerary = null;
let selectedCompany = null;
let shipCabins = [];
let cabinCharges = [];
let otherCharges = [];
let prebookings = [];
let cruisePoints = [];
let bookings = [];
let selectedBooking = null;
let passengers = [];
let bookedCabins = [];
let addons = [];
let countryList = [];
let currencyConfig = null;

Key Functions:

Function	Purpose
`initializePage()`	Parse URL params, load all sailings, render UI
`loadAllSailings()`	Load all cruises with itinerary data for the sailing strip
`renderSailingStrip()`	Build scrollable pill buttons with company-colored borders
`selectSailing(cruiseId)`	Load cabin availability, prebookings, bookings for a sailing
`renderCabinAvailability()`	Build cabin table with charge, prebook count
`renderBookingsList()`	Build bookings table for the selected sailing
`selectBooking(bookingId)`	Load and display booking details (passengers, cabins, addons)
`createNewBooking()`	Open new booking dialog, handle creation flow
`generateBookingNumber()`	Generate PT-DDMM-XXXXXXXX using `createId('', 8)`
`renderPassengers()`	Build passengers table with visa/age badges
`renderBookedCabins()`	Build cabins table with own badges and totals
`renderAddons()`	Build add-ons table with totals
`findAvailablePrebook(shipCabinId)`	Check for Available prebookings to assign as own
`checkVisaForPassenger(passengerId)`	Call visa API for each destination port
`setupNationalityAutocomplete(inputId)`	Attach country autocomplete to nationality input
`computeAgeCategory(dob, sailingDate)`	Return Adult/Child/Infant based on age
`updateBookingTotals()`	Recalculate and save totalAmount from cabins + addons

15.7 API Integration Pattern¶

import { CruiseAPI, initCommon, statusBadge } from './cruise-common.js';
import { loadCurrencyConfig, fetchRates, populateCurrencySelect } from './exchange-rate-service.js';
import { escapeHtml, formatDisplayDate, formatDisplayDateTime, createId, tlinq } from './globals.js';
import { modalShow, modalHide, loadBootstrapTemplates } from './pageutil.js';

Module import from HTML:

<script type="module">
    import * as $mod from './js/modules/cruise-dash.js';
    import * as $site from './js/modules/globals.js';

    $(document).ready(async function() {
        await $site.setGlobalHandlers({ requireAuth: true });
        $mod.initializePage();
        window.CruiseDash = $mod;
    });
</script>

16. File Deliverables¶

16.1 Delivered Files¶

File	Description	Lines
`tqweb-adm/cruise-dash.html`	Dashboard page with company accordion, KPI cards, itinerary grid, 8 modal dialogs	~517
`tqweb-adm/js/modules/cruise-dash.js`	Dashboard module: company/ship/itinerary CRUD, settings management, filtering	~1060
`tqweb-adm/cruise-itin.html`	Itinerary management page with two-pane layout, 9 modal dialogs	~759
`tqweb-adm/js/modules/cruise-itin.js`	Itinerary module: template, pricing, sailing, prebook, booking management	~1500
`tqweb-adm/cruise-agt-book.html`	Agent booking page with sailing strip, 6 modal dialogs	~496
`tqweb-adm/js/modules/cruise-agt-book.js`	Booking module: booking creation, passenger/cabin/addon management	~1600
`tqweb-adm/js/modules/cruise-common.js`	Shared CruiseAPI client, dimension data cache, status badge utility	~198
`tqweb-adm/js/modules/exchange-rate-service.js`	Currency config, rate fetching with 24h cache, select population	~204
`tqweb-adm/css/cruise.css`	All cruise-specific styles: CSS variables, components, tables, print rules	~681

16.2 Key Dependencies¶

Module	Used For
`cruise-common.js`	CruiseAPI, initCommon(), dimension getters/finders, statusBadge()
`exchange-rate-service.js`	loadCurrencyConfig(), fetchRates(), populateCurrencySelect(), convertAmount()
`globals.js`	escapeHtml, formatDisplayDate, formatDisplayDateTime, formatDateTimeLocal, createId, tlinq, getUserSession
`pageutil.js`	modalShow(), modalHide(), loadBootstrapTemplates()
`site.js`	setGlobalHandlers() for authentication

17. Appendix: Component Reference¶

17.1 Bootstrap Components Used¶

Grid System (container-fluid, row, col-md-*, gx-3)
Buttons (.btn, .btn-sm, .btn-group)
Forms (.form-control, .form-select, .form-check)
Tables (.table, .table-hover, .table-sm, .itin-table)
Modals (.modal, .modal-dialog, .modal-lg)
Accordion (.accordion, .accordion-item)
Tabs (.nav-tabs, .tab-content, .tab-pane)
Badges (.badge, .bg-*)
Breadcrumb (.breadcrumb, .breadcrumb-item)
Dropdowns (.dropdown-toggle, .dropdown-menu)

17.2 Button Style Reference¶

Action Type	Button Classes	Icon	Example
Add/Create	`btn btn-sm btn-success`	`bi-plus-lg`	`<button class="btn btn-sm btn-success"><i class="bi bi-plus-lg"></i></button>`
Save/Confirm	`btn btn-success`	`bi-check-lg`	`<button class="btn btn-success"><i class="bi bi-check-lg"></i> Save</button>`
Edit	`btn btn-sm btn-primary`	`bi-pencil`	`<button class="btn btn-sm btn-primary"><i class="bi bi-pencil"></i></button>`
Delete	`btn btn-sm btn-danger`	`bi-trash`	`<button class="btn btn-sm btn-danger"><i class="bi bi-trash"></i></button>`
Cancel	`btn btn-secondary`	(none)	`<button class="btn btn-secondary" data-bs-dismiss="modal">Cancel</button>`
Status	`btn btn-sm btn-secondary dropdown-toggle`	`bi-arrow-repeat`	Status dropdown toggle
Settings	`btn btn-sm btn-outline-secondary`	`bi-gear`	Settings button
Prebook	`btn btn-sm btn-primary`	`fa-solid fa-bookmark`	Prebook management button
Init Cabins	`btn btn-sm btn-success`	`fa-solid fa-wand-magic-sparkles`	Initialize cabin prices
Regen Points	`btn btn-sm btn-info`	`fa-solid fa-rotate`	Regenerate cruise points

17.3 CSS Variables (from cruise.css)¶

:root {
    --cruise-primary: #362c5d;
    --cruise-primary-dark: #2a2149;
    --cruise-secondary: #FFC166;
    --cruise-success: #28a745;
    --cruise-info: #17a2b8;
    --cruise-warning: #ffc107;
    --cruise-danger: #dc3545;
    --cruise-light-bg: #f8f9fa;
    --cruise-border: #e1e4e8;
}

17.4 Icon Reference¶

Purpose	Icon Class	Library
Company/Ship	`fa-solid fa-ship`	FontAwesome
Itinerary/Route	`fa-solid fa-route`	FontAwesome
Sailing/Calendar	`fa-solid fa-calendar`	FontAwesome
Port/Anchor	`fa-solid fa-anchor`	FontAwesome
Cabin/Bed	`fa-solid fa-bed`	FontAwesome
Pricing/Dollar	`fa-solid fa-dollar-sign`	FontAwesome
Booking/Ticket	`fa-solid fa-ticket`	FontAwesome
Passengers	`fa-solid fa-users`	FontAwesome
Passenger	`fa-solid fa-user`	FontAwesome
Charges/Receipt	`fa-solid fa-receipt`	FontAwesome
Globe/Area	`fa-solid fa-globe`	FontAwesome
Template/List	`fa-solid fa-list-ol`	FontAwesome
Regenerate	`fa-solid fa-rotate`	FontAwesome
Init Cabins	`fa-solid fa-wand-magic-sparkles`	FontAwesome
Bookmark/Prebook	`fa-solid fa-bookmark`	FontAwesome
Add	`bi-plus-lg`	Bootstrap Icons
Edit	`bi-pencil`	Bootstrap Icons
Delete/Trash	`bi-trash`	Bootstrap Icons
Save/Check	`bi-check-lg`	Bootstrap Icons
Settings/Gear	`bi-gear`	Bootstrap Icons
Status/Repeat	`bi-arrow-repeat`	Bootstrap Icons
Home	`bi-house-door`	Bootstrap Icons
Water/Cruise	`bi-water`	Bootstrap Icons
Warning	`bi-exclamation-triangle`	Bootstrap Icons
Close	`btn-close`	Bootstrap Icons
Scroll Left	`bi-chevron-left`	Bootstrap Icons
Scroll Right	`bi-chevron-right`	Bootstrap Icons
Person/Booking	`bi-person-vcard`	Bootstrap Icons
Calendar	`bi-calendar3`	Bootstrap Icons
Globe (KPI)	`bi-globe2`	Bootstrap Icons

17.5 CSS Class Reference (from cruise.css)¶

Class	Component	Page
`.cruise-page`	Body class for all cruise pages	All
`.cruise-container`	Main content container	All
`.cruise-breadcrumb`	Breadcrumb navigation bar	All
`.cruise-empty-state`	Centered empty state display	All
`.company-accordion`	Company accordion container	Dashboard
`.kpi-cards`	KPI strip flex container	Dashboard
`.kpi-card`	Individual KPI card	Dashboard
`.itin-card`	Itinerary card in grid	Dashboard
`.filter-bar`	Filter controls bar	Dashboard
`.itin-section`	Section container with title	Itinerary, Booking
`.itin-section-title`	Section header with flex layout	Itinerary, Booking
`.itin-table`	Compact data table	Itinerary, Booking
`.sailing-bar`	Sailing pill container (itinerary page)	Itinerary
`.sailing-pill`	Individual sailing date pill button	Itinerary, Booking
`.sailing-strip-container`	Full-width sailing strip wrapper	Booking
`.sailing-strip`	Scrollable sailing pill row	Booking
`.sailing-strip-scroll-btn`	Scroll arrow buttons	Booking
`.indicator-badge`	Single-letter charge indicator	Itinerary
`.prebook-info`	Pre-booking info display panel	Itinerary, Booking
`.bookings-table`	Bookings table with clickable rows	Itinerary, Booking
`.nationality-autocomplete`	Country autocomplete dropdown	Booking
`.visa-badge`	Visa requirement badge	Booking
`.age-badge`	Age category badge	Booking
`.own-badge`	Own cabin indicator badge	Booking

Cruise Offer Management - UI Requirements Specification¶

1. Introduction¶

1.1 Purpose¶

1.2 Scope¶

1.3 References¶

1.4 Design Language¶

2. Page Structure¶

2.1 Three-Page Architecture¶

2.2 Navigation Flow¶

2.3 Navigation Entry Point¶

2.4 Shared Page Structure¶

2.5 Authentication Pattern¶

3. Dashboard - Left Pane (Company Accordion)¶

3.1 Layout¶

3.2 Company Accordion Header¶

3.3 Company Accordion Structure¶

3.4 Settings Dialog (Dimension Data)¶

4. Dashboard - Right Pane (Itinerary Overview)¶

4.1 Layout¶

4.2 KPI Summary Cards¶

4.3 Filter Bar¶

4.4 Itinerary Card Grid¶

5. Itinerary Page - Left Pane¶

5.1 Layout¶

5.2 Itinerary Info Form¶

5.3 Template Table¶

5.4 Pricing Templates¶

5.4.1 Cabin Price Templates¶

5.4.2 Other Charge Templates¶

5.5 Itinerary Page - Right Pane¶

5.5.1 Layout¶

5.5.2 Sailing Bar¶

5.5.3 Sailing Action Toolbar¶

5.5.4 Cruise Points Table¶

5.5.5 Cabin Charges Table¶

5.5.6 Other Charges Table¶

5.5.7 Bookings Table¶

5.6 Agent Booking Page - Sailing Strip¶

5.6.1 Layout¶

5.6.2 Sailing Strip Requirements¶

5.7 Agent Booking Page - Left Pane¶

5.7.1 Layout¶

5.7.2 Cabin Availability Table¶

5.7.3 Bookings List¶

5.8 Agent Booking Page - Right Pane¶

5.8.1 Layout¶

5.8.2 Booking Header¶

5.8.3 Passengers Table¶

5.8.4 Booked Cabins Table¶

5.8.5 Add-ons Table¶

6. Dialogs¶

6.1 Dialog Design Standards¶

6.2 Dashboard Dialogs¶

6.2.1 Company Dialog (company_dlg)¶

6.2.2 Ship Dialog (ship_dlg)¶

6.2.3 Itinerary Dialog (itinerary_dlg)¶

6.2.4 Settings Sub-Dialogs¶

6.3 Itinerary Page Dialogs¶

6.3.1 Template Entry Dialog (template_dlg)¶

6.3.2 Cabin Price Template Dialog (cabintemplate_dlg)¶

6.3.3 Charge Template Dialog (chargetemplate_dlg)¶

6.3.4 Sailing Dialog (sailing_dlg)¶

6.3.5 Cruise Point Edit Dialog (cruisepoint_dlg)¶

6.3.6 Cabin Charge Dialog (cabincharge_dlg)¶

6.3.7 Other Charge Dialog (othercharge_dlg)¶

6.3.8 Pre-Booking Dialog (prebook_dlg)¶

6.4 Agent Booking Page Dialogs¶

6.4.1 New Booking Dialog (newbooking_dlg)¶

6.4.2 Passenger Dialog (passenger_dlg)¶

6.4.3 Add Cabin Dialog (addcabin_dlg)¶

6.4.4 Add Add-on Dialog (addaddon_dlg)¶

6.4.5 Prebook Dialog (Agent Page) (prebook_dlg)¶

6.5 Confirmation Dialog (confirm_dlg)¶

7. Exchange Rate Auto-Fill Behavior¶

7.1 Overview¶

7.2 Auto-Fill Logic¶

7.3 Applied Dialogs¶

7.4 Currency Dropdown Population¶

8. Status Indicators¶

8.1 Itinerary Status Colors¶

6.2.1 Company Dialog (`company_dlg`)¶

6.2.2 Ship Dialog (`ship_dlg`)¶

6.2.3 Itinerary Dialog (`itinerary_dlg`)¶

6.3.1 Template Entry Dialog (`template_dlg`)¶

6.3.2 Cabin Price Template Dialog (`cabintemplate_dlg`)¶

6.3.3 Charge Template Dialog (`chargetemplate_dlg`)¶

6.3.4 Sailing Dialog (`sailing_dlg`)¶

6.3.5 Cruise Point Edit Dialog (`cruisepoint_dlg`)¶

6.3.6 Cabin Charge Dialog (`cabincharge_dlg`)¶

6.3.7 Other Charge Dialog (`othercharge_dlg`)¶

6.3.8 Pre-Booking Dialog (`prebook_dlg`)¶

6.4.1 New Booking Dialog (`newbooking_dlg`)¶

6.4.2 Passenger Dialog (`passenger_dlg`)¶

6.4.3 Add Cabin Dialog (`addcabin_dlg`)¶

6.4.4 Add Add-on Dialog (`addaddon_dlg`)¶

6.4.5 Prebook Dialog (Agent Page) (`prebook_dlg`)¶

6.5 Confirmation Dialog (`confirm_dlg`)¶