Package Management System

Package Management System

Functional Requirement Document

BA & Ideation: Deval Chauhan

Reviewed By: Keval Gajjar

Updated Date:13 November 2025
Status:

Version: 1.0

SECTION 1 — PACKAGE LIST VIEW

• For listing, sorting, filtering, and managing all package groups.

SECTION 2 — PACKAGE GROUP CREATION FLOW

• For setting up package group structure using events, services, and primary event logic.

SECTION 3 — PACKAGE BUILDER (MAIN EDITOR)

• For building each package with line items, smart fields, deliverables, tax rules, and publishing.

SECTION 4 — A-LA-CARTE ADD-ON ITEMS (SIMPLE ADD-ON)

• For creating add-on items with price, quantity toggle, and mapping to events/services.

SECTION 5 — A-LA-CARTE EVENT-CREATION ADD-ON

• For creating event-type add-ons that generate new events in the project after signing.

1. Package List View - Listing, sorting, filtering, and managing package groups
2. Package Group Creation Flow - Setting up package group structure with events and services
3. Package Builder (Main Editor) - Building packages with line items, smart fields, deliverables, and tax rules
4. A-La-Carte Add-On Items - Creating simple add-on items with pricing and quantity options
5. A-La-Carte Event-Creation Add-On - Creating event-type add-ons that generate new project events

✅ PACKAGE LIST VIEW

Package List View

Functional Requirement Document

BA & Ideation: Paul

Reviewed By: KG (Project Manager)

Updated Date: 8 April 2026

Updated By: Sehal Maheshwari
Status: Approved

Version 2.0

PACKAGE LIST VIEW

1. MODULE OVERVIEW

1.1. Purpose

The Package List View is the central administrative interface for managing all Package Groups within the Pixally CRM system. It provides comprehensive listing, search, filtering, sorting, and management capabilities for package groups containing 1-6 packages each, tied to a single brand.

1.2. Business Goals

• Efficiently manage multiple package groups across different brands
• Quickly locate specific packages using search and filtering
• Control package lifecycle through edit, duplicate, and delete operations
• Ensure data integrity by protecting packages used in active proposals
• Maintain organized package libraries with collapsible row display

2. USER ROLES & PERMISSIONS

Role

View Packages

Create New Group

Edit Group

Duplicate Group

Delete Group

Owner

✔

✔

✔

✔

✔

Admin

✔

✔

✔

✔

✔

Project Manager

✔

✖

✖

✖

✖

3. USER FLOW

3.1. Access & Initial Load

• Navigate to the Packages menu → Package List View loads
• Default: 10 groups per page, sorted by Created Date (newest first), all rows collapsed

3.2. Search & Filter

• Search: Real-time across group/package names (case-insensitive, partial match)
• Sort: Click column headers (Name A-Z/Z-A, Brand, Created Date)
• Filter: Brand, Event Type, Service Type (cumulative AND logic)
• Pagination: 10/25/50 per page(default: 10), Previous/Next controls

3.3. Expand/Collapse

• Click the chevron icon to expand row → reveals internal packages with details (name, price, events, services, line items preview, ALC items)
• Click chevron-up to collapse → returns to single-line view

3.4. Delete Package Group

• User clicks the three-dot Actions menu on a package group row.
• User selects "Delete" from the dropdown menu.
• System checks if the package group is linked to any proposals.
• If linked to proposals: System displays "Cannot Delete" warning modal listing all linked proposals. User clicks "Close" to dismiss.
• If NOT linked to proposals: System displays confirmation modal with message "Are you sure you want to delete '[Package Group Name]'? This action cannot be undone."
• User clicks "Delete" to confirm or "Cancel" to abort.
• If confirmed: Package group is removed from the list, success toast displays "Package group deleted successfully."

4. FUNCTIONAL LOGIC

4.1 Package Groups & Packages

Package Group

• A Package Group is a logical container that bundles multiple related packages (minimum 1, maximum 6) under a single brand.
• It allows agencies to organize offerings into tiered or themed structures such as Bronze, Silver, Gold, or event-specific (wedding, engagement, etc.) collections.
• All packages within a group inherit the brand assigned to the group.
• Each package inside the group maintains its own independent configuration, including pricing, line items, deliverables, and A-La-Carte add-ons.

Package

• A Package is a predefined service offering that bundles events, services, line items, deliverables, and pricing into a single sellable unit that clients can select within proposals.
• A Package defines which events are covered, which services are provided for each event, the deliverables included, and the total price for the offering.
• Packages can be customized with line items (custom or smart-field based), tax configurations, deliverable due dates, and A-La-Carte add-ons.
• When a client signs a proposal that contains a Package, the system converts the package details into a project with scheduled events, applied services, and tracked deliverables.

4.2 Empty State Handling

• When no Package Groups exist, the system displays an empty state instead of the Package Listing table.
• The empty state message is displayed as: “No packages found. Create your first package group to start building your service offerings.”
• The primary CTA button “Create Package” is shown, and clicking it opens the Package Creation flow.
• If the agency has no brands set up, clicking “Create Package” triggers a pop-up informing the user that they must create a brand before creating a package. The system does not proceed to the Package Creation flow until at least one brand is available.

4.3. Package Group List View

• When the user navigates to the Package List View, the system retrieves all package groups associated with the user's agency and the brands they have access to.
• The system applies the default sort order, Created Date — Newest First, when loading the package group data.
• All package group rows are rendered in a collapsed state on initial load.

4.3.1 Table Structure & Display Columns

• The list view displays the following columns: Package Group Name (with the number of packages in the group), Status, Brand, Services, Events, Created Date, and Actions.
• Each collapsed row shows only the group-level information.
• For users without edit, duplicate, or delete permissions (e.g., Project Manager, Coordinator), the entire "Actions" column including the column header is hidden from the table. These users view the list in read-only mode.
• Refer- Click Here

4.3.2 Expand & Collapse Interaction

• The user can expand any package group by clicking on the row or the chevron icon.
• When a package group is expanded, the system retrieves detailed information for all packages within that group.
• If a group contains more than 3 packages, the system enables a horizontal scroll within the expanded section.
• For each package inside a group, the system loads the package name, events array, services array, line items, A-La-Carte items, and package price.
• The user can expand multiple package groups simultaneously. Expanding one group does not collapse previously expanded groups.
• The user can collapse any expanded group by clicking the chevron icon again.
• Refer- Click Here

4.4. Search Logic

• The user can search for package groups using either the package group name or any package name contained within a group.
• The search bar is positioned at the top of the table area, adjacent to the filter icon, and is available on both the Packages tab and the A La Carte Items tab.
• When the user begins typing in the search input field, the system updates the displayed list in real-time to show only matching package groups.
• Search is case-insensitive and matches partial strings within the name fields.
• If no matching results are found, the system displays an empty state with the message: "No results found" along with the subtext: "No items match your search. Try adjusting your keywords or clearing the search."
• The empty state is consistent across both the Packages tab and the A La Carte Items tab when no results match the search query.
• Clearing the search bar restores the full list of package groups with any other active filters or sort orders still applied.
• The search bar remains visible and functionally active even when the listing is in an empty state (zero package groups exist).
• When a search query is entered or modified, all expanded package groups are automatically collapsed. The list re-renders with all rows in a collapsed state to ensure consistent display of filtered results.
• Search is applied on top of any active filters. Results must satisfy both the active filter criteria AND the search query simultaneously. For example, if the user has filtered by Brand "Emma Taylor" and searches for "Wedding", only package groups that belong to "Emma Taylor" brand AND contain "Wedding" in the group or package name will be displayed.

4.5. Sorting Logic

• The user can sort package groups by clicking on the column name in the table header.
• Sorting is supported on the following columns: Package Group Name, Status, Brand, and Created Date.
• Package Group Name and Brand sort alphabetically in both directions: Ascending (A–Z) and Descending (Z–A).
• Created Date sorts based on the group’s creation timestamp, toggling between Latest to Oldest and Oldest to Latest
• Status (Draft / Published) is sorted alphabetically to maintain consistency with other text-based columns:
  • Ascending: Draft → Published
  • Descending: Published → Draft

4.6. Filter Logic

• The user can filter Package Groups by clicking the Filter icon, which opens the filter panel.
• The filter panel provides filter options for: Brands, Events and Services
• The Brand filter lists all brands accessible to the logged-in user.
• Events and Services filter values are fetched from the selected Brand.
• By default, Events and Services filters display values from all brands.
• When the user selects a specific Brand, the Event Type and Service Type lists are auto-populated based on the selected Brand only.
• Filters are applied immediately upon selection; no Apply button is required.
• Filters across different categories are applied using AND logic.
• Multiple selections within the same filter category are applied using OR logic.
• When the applied filters return no matching results, the system displays the empty state message:
  • No results found “No items match the selected filters. Try adjusting or reset your filters to see results.”
• The system displays a red dot indicator on the Filter icon when any filter is active, regardless of the number of filters applied. The red dot disappears when all filters are cleared.
• Clicking the "Reset" button in the filter panel removes all active filters, hides the red dot indicator on the Filter icon, and restores the full Package Group list.
• Filter selections persist within the user session while navigating inside the Package List View.
• When filters are applied or changed, all expanded package groups are automatically collapsed. The list re-renders with all rows in a collapsed state to ensure consistent display of filtered results.
• The user can close the filter panel using any of the following methods:
• Clicking the Close (X) button inside the filter panel.
• Clicking anywhere outside the filter panel.
• Pressing the ESC key on the keyboard.
• When the filter panel is closed, any selected filters remain applied until explicitly cleared.

4.7. Actions

• The user can perform Edit, Duplicate, and Delete actions on any package group by clicking the three-dot Actions menu.
• Refer- Click Here

4.7.1 Delete Package Group — Dependency Validation

• When a user attempts to delete a package group that is currently used in one or more proposals, the system blocks the deletion and displays a "Cannot Delete Package Group" modal.
• The modal displays a warning message in a highlighted banner: "This package group is used in one or more proposals and cannot be deleted. Please remove it from the listed proposals before trying again."
• Below the warning banner, the modal lists all proposals that reference the package group (e.g., "My Proposal 1", "My Proposal 2") so the user can identify and resolve the dependencies.The system displays the current proposal name at the time of the delete attempt, even if the proposal was renamed after being linked to the package group.
• Each listed proposal is displayed with a proposal icon and the proposal name.
• The modal includes a "Close" button at the bottom-right to dismiss the dialog and return to the Package List View without any changes.
• The system does not perform a soft delete or archive; the package group remains fully active and unchanged until all proposal dependencies are removed.
• Once all proposal references are removed, the user can reattempt the deletion, which will proceed with the standard delete confirmation flow.

4.7.2 Delete Package Group —If No Dependencies (Allowed)

• When a user attempts to delete a package group that is NOT used in any proposals, the system displays a confirmation modal.
• The modal title displays: "Delete Package Group?"
• The modal message displays: "Are you sure you want to delete '[Package Group Name]'? This action cannot be undone."
• The modal includes two buttons: "Cancel" (secondary/gray) and "Delete" (destructive/red).
• If the user clicks "Cancel", the system closes the modal without taking any action and returns to the Package List View.
• If the user clicks "Delete", the system permanently deletes the package group and all packages within it from the database.
• After successful deletion, the system removes the package group row from the list view immediately without requiring a page refresh.
• The system displays a success toast: "Package group deleted successfully."
• If the deleted package group was the only item on the current page (e.g., page 3), the system automatically redirects the user to the previous page (e.g., page 2) after deletion. The system does not display an empty page

5. FIELD DETAILS & VALIDATIONS

5.1 Header & Navigation Elements

Field Name

Field Type

Description

Validation Rules

Page Title

Text (Display)

Module title displayed at the top of the page

Read-only; displays "Packages."

Packages Tab

Tab Button (Toggle)

Primary tab showing the package groups list

Clickable; active state indicated by filled green background; selected by default on page load

A La Carte Items Tab

Tab Button (Toggle)

Secondary tab for A-La-Carte items list

Clickable; inactive state with outline/border style; navigates to A-La-Carte listing view when clicked

Search Input

Text Input

Search icon with empty input field

Minimum 1 character; searches across package group names and package names within groups; real-time filtering as user types; case-insensitive partial match

Watch Tutorial

Button (Secondary/Outline)

Opens tutorial or help content

Clickable; opens & redirects to tutorial modal

Create New Group

Button (Primary/Green)

Initiates package group creation flow

Clickable; opens Package Group Creation wizard; if no brands exist in athe gency, displays error modal: "Please create a brand before creating a package group" and blocks navigation to the wizard

5.2 Package Group Listing Table Fields

Field Name

Field Type

Description

Validation Rules

Package Group Name

Text (Display) + Badge

Group name with package count indicator (e.g., "Photography" with "3 PACKAGES" badge)

Read-only in listing view; clicking the row or the chevron expands the group

Status

Badge/Tag

Status label with color-coded indicator (e.g., Draft, Published)

Read-only in listing view; displays the current publication status of the group

Brand

Avatar + Text (Display)

Brand logo/avatar with brand name

Read-only in listing view; displays the brand associated with the group

Service

Tag/Badge (Display)

Service types are included across all packages in the group

Read-only; displays aggregated service types (e.g., "Photography", "Videography")

Events

Tag/Badge (Display)

Event types included across all packages in the group

Read-only; displays event names with "+N" overflow indicator if more than 2 events (e.g., "Rehearsal Dinner, +1")

Created

Date (Display)

Package group creation date

Read-only; format as per General Settings (e.g., "Jan 24, 2025")

Actions

Icon Button (3-dot menu)

Dropdown menu with Edit, Duplicate, and Delete options

Clickable; opens action menu on click

Expand/Collapse Icon

Icon Button (Chevron)

Toggles the expanded/collapsed state of the package group row

Clickable; chevron-down when collapsed, chevron-up when expanded

5.3 Expanded Package Card Fields

Field Name

Field Type

Description

Validation Rules

Package Name

Text (Display)

Name of the individual package within the group

Read-only in listing view; displayed as card header (e.g., "Simple Photography", "Advanced Photography", "Pro Photography")

Event Section Header

Tag/Badge (Display)

Event type header with colored background

Read-only; displays event name in uppercase (e.g., "WEDDING", "REHEARSAL DINNER") with distinct background color per event type

Package Price

Currency (Display)

Total package price with currency code

Read-only; format as currency with 2 decimal places and currency code (e.g., "$350.00 USD", "$550.00 USD", "$850.00 USD")

Package Card Actions

Icon Button (3-dot menu)

Per-package action menu within expanded view

Clickable; opens action menu for individual package editing

Horizontal Scroll

Scroll Container

Enables horizontal scrolling when the group contains more than 3 packages

Auto-enabled when package count exceeds visible area; maximum 6 packages per group

5.4 Pagination Controls

Field Name

Field Type

Description

Validation Rules

Rows per page

Dropdown Select

Number of rows displayed per page

Dropdown with selectable values; options limited to 10, 25, 50; default value is 10

Page Indicator

Text (Display)

Current page position out of total pages

Read-only; format as "X of Y" (e.g., "1 of 1", "2 of 5")

Previous Page Button

Icon Button (Chevron Left)

Navigate to the previous page

Clickable when current page > 1; disabled and grayed out on first page

Next Page Button

Icon Button (Chevron Right)

Navigate to the next page

Clickable when current page < total pages; disabled and grayed out on last page

6. SUCCESS MESSAGE HANDLING

Validation Scenario

Success Message

Package group list loaded successfully

No explicit message - Table renders with data

Package group expanded successfully

No explicit message - Expanded view displays instantly with package cards

Package group collapsed successfully

No explicit message - Row collapses instantly

Search results found

No explicit message - Table updates in real-time with matching results

Sort applied successfully

No explicit message - Table reorders instantly based on the selected column

7. ERROR MESSAGE HANDLING

Field

Validation Scenario

Error Message

Package Group List

Failed to load package groups

"Unable to load package groups. Please try again."

Search

No matching results found

No results found. No items match your search criteria.

Expand

Failed to load package details

"Unable to load package details. Please try again."

Create New Group

No brands exist in the agency

"Please create a brand before creating a package group."

8. EDGE CASES

Scenario

Expected Behavior

The package group contains more than 3 packages

System enables horizontal scroll within the expanded section; all packages (up to 6) remain accessible via scrolling

The package group contains a maximum of 6 packages

System displays all 6 packages in horizontal scroll view; no option to add more packages to this group from listing view

User duplicates a group with a name that already exists

System displays an inline error: "Group name already exists. Please enter a unique name." Duplication does not proceed until a unique name is provided

Search query matches the package name but not the group name

System returns the parent package group in results; the group is displayed in a collapsed state with the matching package inside

Multiple package groups are expanded simultaneously

The system keeps all expanded groups open; expanding a new group does not collapse previously expanded groups

Package group name exceeds display width

System truncates the group name with ellipsis (...); full name shown on hover via tooltip

The Events column has more than 2 event types

System displays first 2 event names with "+N" overflow indicator (e.g., "Wedding, Rehearsal Dinner, +1"); full list shown on hover or expand

User loses network connection while expanding a group

System displays error toast: "Unable to load package details. Please try again." Row remains in a collapsed state

User without edit permission clicks the Edit action

Edit option is hidden or disabled in the Actions menu; only users with the Owner/Admin role can see and use the Edit action

The package inside the group has no price set

Package card displays "Price not set" or "$0.00 USD" placeholder; visual indicator prompts user to complete package setup

User rapidly clicks expand/collapse on the same row

System debounces clicks and processes only the final state; prevents multiple API calls and UI flickering

User deletes the only remaining package group on current page (e.g., page 3)

System redirects user to the previous page (page 2). Empty page is not displayed.

User searches while filters are active

Search applies on top of active filters using AND logic. Results must match both filter criteria AND search query.

User has expanded package groups and then applies search or filter

All expanded rows automatically collapse. List re-renders in collapsed state.

9. ACCEPTANCE CRITERIA

• Package Group Definition – System must allow creation of Package Groups (1–6 packages) tied to a single brand, each grouping multiple independent packages.

• Package Definition – System must treat each Package as an independent sellable offering with its own events, services, pricing, line items, deliverables, and A-La-Carte add-ons.

• Brand Inheritance – System must auto-assign all packages within a group to the brand selected for that group.

• Proposal Conversion – When a client signs a proposal containing a package, the system must auto-convert package details into a project with events, services, and deliverables.

• Empty State Display – If no Package Groups exist, the system must show “No packages found…” with a “Create Package” CTA.

• No Brand Blocker – If “Create Package” is clicked and no brands exist, the system must show a pop-up requiring brand creation before package creation can proceed.

• Package Group Retrieval – On list-view load, the system must fetch all package groups for the agency and apply default sorting: Created Date → Newest First.

• Initial Collapse State – All package groups must load in a collapsed state.

• Table Columns – List view must display: Package Group Name (+ package count), Brand, Services, Events, Created Date, and Actions.

• Expand/Collapse – Clicking a group row/chevron must expand or collapse that group without affecting others.

• Package Load on Expand – Expanding a group must retrieve and display all of its packages with names, events, services, line items, A-La-Carte items, and pricing.

• Horizontal Scroll – If a group contains more than 3 packages, horizontal scroll must appear within the expanded area.

• Multi-Group Expansion – System must allow multiple groups to remain expanded simultaneously.

• Search by Group/Package – Search must filter results live using matches from either group names or package names.

• Search Empty State – f no matches are found, the system must show "No results found" with subtext "No items match your search criteria."

• Sorting Support – System must support sortable columns: Package Group Name, Status,Brand, and Created Date.

• Sorting Rules – Package Group Name and Brand must sort alphabetically (A–Z / Z–A), and Created Date must sort by timestamp (Newest→Oldest / Oldest→Newest).

• Filters - The system shall allow users to filter Package Groups by Brand, Event Type, and Service Type with real-time application, cumulative AND logic across filter categories, OR logic within the same category, visible filter count indication, and a functional Clear All option that restores the unfiltered list.

• Filters - The system shall correctly auto-populate Event Type and Service Type values based on the selected Brand, display an appropriate empty state message when no results match the applied filters, and persist filter selections within the user session while navigating the Package List View.

• Search with Filters – When search is performed with active filters, system must apply AND logic, returning only results that match both the filter criteria and the search query.

• Delete on Last Page Item – If user deletes the only item on current page, system must redirect to the previous valid page automatically.

• Actions Column Visibility – For users without edit/duplicate/delete permissions (Project Manager, Coordinator), the entire Actions column including the header must be hidden.

10. DEPENDENCIES

Module/System

Dependency Type

Impact if Unavailable

Brand Module

Data dependency

Package groups cannot be created; "Create New Group" button triggers error: "Please create a brand before creating a package group"; Brand column displays empty or error state

Package Builder

Navigation dependency

Edit action fails; user cannot navigate to edit package group details; error message displayed: "Unable to open Package Builder. Please try again."

Package Group Creation Wizard

Navigation dependency

"Create New Group" button fails to open the wizard; new package groups cannot be created from the listing view

Proposal Module

Data dependency

Delete validation cannot verify if the package group is used in proposals; the system may block all deletions as a precaution, or allow deletions without a usage check

User & Authentication Module

Access dependency

Role-based permissions are not enforced; all users may see all actions or no actions; session validation fails, and the user is redirected to login

Event Types Master Data

Data dependency

Events column displays empty or "Unknown Event"; package cards in expanded view show events without proper labels

Service Types Master Data

Data dependency

The Services column displays empty or "Unknown Service"; package cards in expanded view show services without proper labels

A-La-Carte Module (Sections 4 & 5)

Data dependency

A-La-Carte item count not displayed in expanded package cards; linked items information unavailable

Database Service

System dependency

Package group list fails to load; all CRUD operations fail; system displays error: "Unable to load package groups. Please try again."

Session Management

System dependency

User authentication state not maintained; unauthorized access possible or legitimate users blocked; session expiry not handled

11. REFERENCES

11.1. Figma Design References

https://www.figma.com/design/ej0kxwP45mDKmZCZfAJ5O8/Pixally?node-id=19313-54982&t=BAkQ9BaQzOENaQKr-0

For Reference only

PACKAGE LIST VIEW - FUNCTIONAL REQUIREMENTS DOCUMENT

Module: Package List View
Document Version: 2.0

1. MODULE OVERVIEW

1.1 Module Name

Package List View

1.2 Purpose

The Package List View is the central administrative interface where users manage all Package Groups created for proposals and projects within the Pixally CRM system. This module serves as the primary entry point for users to view, search, sort, filter, and access their package offerings organized by brand.

1.3 Business Goals

• Enable agencies to efficiently view and manage multiple package groups across different brands.
• Provide quick access to specific packages using search and filtering capabilities.
• Maintain organized package libraries with sorting and pagination functionality.
• Allow users to expand package groups inline to preview internal package details without navigation.
• Serve as the launching point for package creation, editing, and management workflows.

1.4 Key Definitions

Package Group A Package Group is a logical container that bundles multiple related packages (minimum 1, maximum 6) under a single brand. It allows agencies to organize offerings into tiered or themed structures such as Bronze, Silver, Gold, or event-specific (wedding, engagement, etc.) collections. All packages within a group inherit the brand assigned to the group. Each package inside the group maintains its own independent configuration, including pricing, line items, deliverables, and A-La-Carte add-ons.

Package A Package is a predefined service offering that bundles events, services, line items, deliverables, and pricing into a single sellable unit that clients can select within proposals. A Package defines which events are covered, which services are provided for each event, the deliverables included, and the total price for the offering. Packages can be customized with line items (custom or smart-field based), tax configurations, deliverable due dates, and A-La-Carte add-ons. When a client signs a proposal that contains a Package, the system converts the package details into a project with scheduled events, applied services, and tracked deliverables.

2. USER ROLES & PERMISSIONS

2.1 Roles That Can Access the Module

Role

Access Level

Owner

Full Access

Admin

Full Access

Project Manager

View Only

Coordinator / Staff

View Only

Contractor

No Access

Client

No Access

2.2 Granular Permissions

Permission

Owner

Admin

Project Manager

Coordinator

Contractor

Client

View Package List

✔

✔

✔

✔

✖

✖

Search Packages

✔

✔

✔

✔

✖

✖

Sort Packages

✔

✔

✔

✔

✖

✖

Filter Packages

✔

✔

✔

✔

✖

✖

Expand/Collapse Rows

✔

✔

✔

✔

✖

✖

Create New Group

✔

✔

✖

✖

✖

✖

Access Actions Menu

✔

✔

✖

✖

✖

✖

2.3 Brand-Based Visibility

• Users working within a single brand context see only package groups assigned to that brand.
• Users with access to multiple brands can view package groups from all accessible brands and filter by specific brands.
• Each package group belongs to exactly one brand and cannot be reassigned after creation.

3. USER FLOW

3.1 The user logs into the Pixally CRM system with valid credentials.

3.2 The user navigates to the left sidebar menu and clicks on the "Template" section to expand the submenu.

3.3 The user clicks on "Packages" menu item from the expanded submenu.

3.4 The system loads the Package List View page with two tabs displayed: "Packages" (active by default) and "A La Carte Items".

3.5 The system retrieves all package groups associated with the user's agency and accessible brands from the database.

3.6 The system displays the package groups in a table format with columns: Package Group Name (with package count badge), Brand, Service, Events, Created Date, and Actions.

3.7 The system applies the default sort order of "Created Date - Newest First" to the displayed package groups.

3.8 The system renders all package group rows in collapsed state by default.

3.9 The system displays pagination controls at the bottom showing "Rows per page: 10" dropdown, page indicator "1 of X", and Previous/Next navigation buttons.

3.10 The user clicks on the search input field at the top of the list to search for specific packages.

3.11 The user types a search query (package group name or package name) into the search input field.

3.12 The system performs a real-time case-insensitive search across package group names and individual package names within each group.

3.13 The system updates the displayed list instantly to show only matching package groups.

3.14 The user clicks the expand chevron icon on a package group row to view internal packages.

3.15 The system expands the row to reveal package cards displayed horizontally within the expanded section.

3.16 The system displays each package card showing: Package Name, Event sections with colored headers, Service types listed under each event, Line items preview, and Package Price.

3.17 The system enables horizontal scrolling within the expanded section if the package group contains more than 3 packages.

3.18 The user clicks the collapse chevron icon to hide the internal package details.

3.19 The system collapses the row back to the single-line display showing only group-level information.

3.20 The user clicks on a sortable column header (Package Group, Brand, or Created) to sort the list.

3.21 The system sorts the entire list by the selected column and displays a sort direction indicator arrow next to the active column header.

3.22 The user clicks the filter icon to open the filter panel for filtering package groups.

3.23 The system displays the filter panel with available filter options for Brand, Event Type, and Service Type.

3.24 The user selects one or more filter options from the available filter categories.

3.25 The system applies the selected filters immediately using cumulative AND logic and updates the displayed list.

3.26 The user clicks "Clear All" in the filter panel to remove all active filters.

3.27 The system removes all filters and restores the full list with current sort settings.

3.28 The user clicks the "Rows per page" dropdown to change the number of displayed rows.

3.29 The user selects a new value (10, 25, or 50) from the dropdown options.

3.30 The system updates the list to display the selected number of rows per page and resets to page 1.

3.31 The user clicks the Next or Previous pagination button to navigate between pages.

3.32 The system loads the requested page and updates the page indicator accordingly.

3.33 The user clicks the three-dot Actions menu icon on a package group row to access available actions.

3.34 The system displays a dropdown menu with options: Edit, Duplicate, and Delete (detailed functionality covered in FRD #4: Edit, Delete & Duplicate Package).

3.35 The user clicks the "+ Create New Group" button to initiate package group creation.

3.36 The system navigates to the Package Group Creation Flow (detailed functionality covered in FRD #2: Package Group Creation Flow).

4. FUNCTIONAL LOGIC

4.1 Package Group & Package Definitions

• A Package Group is a logical container that bundles multiple related packages (minimum 1, maximum 6) under a single brand.
• A Package Group allows agencies to organize offerings into tiered or themed structures such as Bronze, Silver, Gold, or event-specific collections.
• All packages within a group inherit the brand assigned to the group at the time of creation.
• Each package inside the group maintains its own independent configuration, including pricing, line items, deliverables, and A-La-Carte add-ons.
• A Package is a predefined service offering that bundles events, services, line items, deliverables, and pricing into a single sellable unit.
• A Package defines which events are covered, which services are provided for each event, the deliverables included, and the total price for the offering.
• Packages can be customized with line items (custom or smart-field based), tax configurations, deliverable due dates, and A-La-Carte add-ons.
• When a client signs a proposal that contains a Package, the system converts the package details into a project with scheduled events, applied services, and tracked deliverables.

4.2 Empty State Handling

• When no Package Groups exist in the system, the system displays an empty state view instead of the Package Listing table.
• The empty state message is displayed as: "No packages found. Create your first package group to start building your service offerings."
• The primary CTA button labeled "Create Package" is displayed prominently in the empty state view.
• When the user clicks "Create Package" and at least one brand exists in the agency, the system opens the Package Group Creation Flow.
• When the user clicks "Create Package" but no brands exist in the agency, the system displays a pop-up modal informing the user that they must create a brand before creating a package group.
• The system does not proceed to the Package Group Creation Flow until at least one brand is available in the agency.

4.3 Package Group List View Loading

• When the user navigates to the Package List View, the system retrieves all package groups associated with the user's agency and the brands they have access to.
• The system applies the default sort order of "Created Date — Newest First" when loading the package group data.
• All package group rows are rendered in a collapsed state on initial load to optimize page performance.
• The system loads package group data including: group name, package count, brand information, aggregated service types, aggregated event types, and creation date.
• The system determines the user's role and displays or hides the Actions menu and "Create New Group" button accordingly.

4.4 Table Structure & Display Columns

• The list view displays the following columns: Package Group Name (with the number of packages displayed as a badge below the name), Brand (with avatar and name), Services, Events, Created Date, and Actions.
• The Package Group Name column displays the group name along with a count badge showing the number of packages in the format "X PACKAGES" (e.g., "3 PACKAGES").
• The Brand column displays the brand avatar/logo followed by the brand name.
• The Services column displays service type tags aggregated from all packages within the group (e.g., "Photography", "Videography").
• The Events column displays event type tags aggregated from all packages within the group, with "+N" overflow indicator if more than 2 event types exist (e.g., "Rehearsal Dinner, +1").
• The Created column displays the creation date formatted according to agency general settings (e.g., "Jan 24, 2025").
• The Actions column displays a three-dot menu icon that opens a dropdown with Edit, Duplicate, and Delete options when clicked.
• Each collapsed row shows only the group-level aggregated information without internal package details.

4.5 Expand & Collapse Interaction

• The user can expand any package group by clicking on the row or the chevron icon next to the package group name.
• When a package group is expanded, the system retrieves and displays detailed information for all packages within that group.
• The expanded section displays package cards arranged horizontally within the package group row.
• If a group contains more than 3 packages, the system enables horizontal scrolling within the expanded section to access all package cards.
• For each package inside a group, the system displays: package name, event sections with colored headers (e.g., "WEDDING" in beige, "REHEARSAL DINNER" in blue), service types listed under each event section, line items preview, and package price.
• The user can expand multiple package groups simultaneously without affecting other expanded rows.
• Expanding one package group does not automatically collapse previously expanded groups.
• The user can collapse any expanded group by clicking the chevron icon again.
• When collapsed, the row returns to displaying only group-level aggregated information.
• The expand/collapse state is not persisted across page refreshes; all rows default to collapsed state on page reload.

4.6 Search Logic

• The user can search for package groups using either the package group name or any package name contained within a group.
• The search input field is located at the top of the list view next to the filter icon.
• When the user begins typing in the search input field, the system updates the displayed list in real-time to show only matching package groups.
• The search is case-insensitive and supports partial matching (substring search).
• If the search query matches a package name within a group, the parent package group is displayed in the results.
• If no matching results are found, the system displays an empty state message: "No package groups found, please try again."
• The search operates on the currently filtered/sorted list, further narrowing the results.
• When the user clears the search input, the system restores the full list with previously applied sort and filter settings.

4.7 Sorting Logic

• The user can sort package groups by clicking on the column header in the table.
• Sorting is supported on the following columns: Package Group Name, Brand, and Created Date.
• Package Group Name and Brand columns sort alphabetically in both directions: Ascending (A–Z) and Descending (Z–A).
• Created Date column sorts based on the group's creation timestamp, toggling between "Latest to Oldest" (descending) and "Oldest to Latest" (ascending).
• The default sort order on page load is "Created Date - Newest First" (descending).
• When the user clicks a column header, the system sorts the entire dataset (not just the current page) by the selected column.
• The system displays a sort direction indicator (up or down arrow) next to the active sorted column header.
• Clicking the same column header again toggles the sort direction between ascending and descending.
• After applying a sort, the system resets pagination to page 1.
• Sort settings persist during the user's session but reset to default when the user navigates away and returns.

4.8 Filter Logic

• The user can filter package groups by clicking the filter icon to open the filter panel.
• The filter panel provides filter options for: Brand, Event Type, and Service Type.
• When the user selects filter options, the system applies the filters immediately without requiring an "Apply" button click.
• Filters are applied cumulatively using AND logic across different filter categories.
• Multiple selections within the same filter category use OR logic.
• Example: Selecting Brand = "Emma Taylor" AND Event Type = "Wedding" displays only groups assigned to "Emma Taylor" brand that also contain at least one package with "Wedding" event type.
• When filters return zero matching results, the system displays an empty state message: "No package groups match the selected filters."
• The system displays a filter count badge on the filter icon showing the number of active filters.
• When the user clicks "Clear All" in the filter panel, the system removes all active filters and restores the full list.
• Filter settings persist during the user's session while navigating within the Package List View.

4.9 Pagination Logic

• The system provides pagination controls at the bottom of the list view.
• The "Rows per page" dropdown allows the user to select: 10, 25, or 50 rows per page.
• The default rows per page value is 10.
• The page indicator displays the current page and total pages in the format "X of Y" (e.g., "1 of 5").
• The Previous button (left arrow) navigates to the previous page and is disabled when on the first page.
• The Next button (right arrow) navigates to the next page and is disabled when on the last page.
• When the user changes the "Rows per page" value, the system recalculates pagination and resets to page 1.
• When the user navigates between pages, the system loads the requested page data and updates the page indicator.
• Pagination operates on the filtered and sorted dataset.

4.10 Actions Menu

• The Actions menu (three-dot icon) is displayed in the Actions column for each package group row.
• The Actions menu is only visible to users with Owner or Admin role.
• When clicked, the Actions menu displays a dropdown with three options: Edit, Duplicate, and Delete.
• The detailed functionality for Edit, Duplicate, and Delete actions is covered in FRD #4: Edit, Delete & Duplicate Package.
• The Delete option is displayed in red (destructive styling) to indicate its permanent nature.

4.11 Create New Group Button

• The "+ Create New Group" button is displayed at the top right of the Package List View.
• The button is only visible to users with Owner or Admin role.
• When clicked, the system initiates the Package Group Creation Flow.
• The detailed functionality for package group creation is covered in FRD #2: Package Group Creation Flow.
• If no brands exist in the agency, clicking the button displays an error modal instead of proceeding to creation.

4.12 Tabs Navigation

• The Package List View displays two tabs at the top: "Packages" and "A La Carte Items".
• The "Packages" tab is selected by default when the user navigates to the Packages module.
• Clicking the "A La Carte Items" tab navigates to the A La Carte Items List View (covered in FRD #5).
• The active tab is indicated by a filled/highlighted background style.

5. FIELD DETAILS & VALIDATIONS

5.1 Package Group Listing Table Fields

Field Name

Field Type

Validation Rules

Package Group Name

Text (Display) + Badge

Read-only in listing view; displays group name with package count badge below; clicking row or chevron expands the group

Brand

Avatar + Text (Display)

Read-only in listing view; displays brand logo/avatar with brand name

Service

Tag/Badge (Display)

Read-only; displays aggregated service types from all packages in the group

Events

Tag/Badge (Display)

Read-only; displays event names with "+N" overflow indicator if more than 2 events exist

Created

Date (Display)

Read-only; format as per General Settings (e.g., "Jan 24, 2025")

Actions

Icon Button (3-dot menu)

Clickable; opens dropdown menu with Edit, Duplicate, Delete options; visible only to Owner/Admin roles

Expand/Collapse Icon

Icon Button (Chevron)

Clickable; toggles expanded/collapsed state of package group row

5.2 Expanded Package Card Fields

Field Name

Field Type

Validation Rules

Package Name

Text (Display)

Read-only; displayed as card header

Event Section Header

Tag/Badge (Display)

Read-only; displays event name in uppercase with colored background

Line Items List

Text List (Display)

Read-only; displays line item names; truncated if more than 3-5 items

Package Price

Currency (Display)

Read-only; format as currency with 2 decimal places and currency code (e.g., "$350.00 USD")

5.3 Search, Filter & Sort Controls

Field Name

Field Type

Validation Rules

Search Input

Text Input

Optional; real-time search as user types; case-insensitive partial match

Filter Button

Icon Button

Clickable; opens filter panel; displays badge count when filters are active

Sort Column Headers

Clickable Headers

Clickable on Package Group, Brand, Created columns; displays sort direction indicator

5.4 Pagination Controls

Field Name

Field Type

Validation Rules

Rows per page

Dropdown Select

Options: 10, 25, 50; default value is 10

Page Indicator

Text (Display)

Read-only; format as "X of Y"

Previous Button

Icon Button

Clickable when current page > 1; disabled on first page

Next Button

Icon Button

Clickable when current page < total pages; disabled on last page

5.5 Header & Navigation Elements

Field Name

Field Type

Validation Rules

Page Title

Text (Display)

Read-only; displays "Packages"

Packages Tab

Tab Button

Clickable; active by default; indicated by filled background

A La Carte Items Tab

Tab Button

Clickable; navigates to A La Carte Items list view

Watch Tutorial

Button (Secondary)

Clickable; opens tutorial/help content

Create New Group

Button (Primary)

Clickable; visible only to Owner/Admin; triggers creation flow or error if no brands exist

6. SUCCESS MESSAGE HANDLING

Validation Scenario

Success Message

Package group list loaded successfully

No explicit message - Table renders with data

Package group expanded successfully

No explicit message - Expanded view displays instantly with package cards

Package group collapsed successfully

No explicit message - Row collapses instantly

Search results found

No explicit message - Table updates in real-time with matching results

Sort applied successfully

No explicit message - Table reorders instantly based on selected column

Filter applied successfully

No explicit message - Table updates in real-time with filtered results

Filter cleared successfully

No explicit message - Table resets to show all package groups

Pagination changed successfully

No explicit message - Table updates with new page data

Rows per page changed successfully

No explicit message - Table updates with new row count

7. ERROR MESSAGE HANDLING

Field

Validation Scenario

Error Message

Package Group List

Failed to load package groups

"Unable to load package groups. Please try again."

Package Group List

Server error during data retrieval

"Something went wrong. Please refresh the page or try again later."

Search

No matching results found

"No package groups found, please try again."

Filter

No results match applied filters

"No package groups match the selected filters."

Expand

Failed to load package details

"Unable to load package details. Please try again."

Create New Group

No brands exist in agency

"Please create a brand before creating a package group."

Session

User session expired

"Your session has expired. Please log in again."

Network

Connection lost during operation

"Connection lost. Please check your internet connection and try again."

8. EDGE CASES

Scenario

Expected Behavior

No package groups exist in the system

System displays empty state with message: "No packages found. Create your first package group to start building your service offerings." and shows "Create Package" CTA button

User clicks "Create New Group" but no brands exist

System displays pop-up modal: "Please create a brand before creating a package group." and does not proceed to creation flow

Package group contains more than 3 packages

System enables horizontal scroll within the expanded section; all packages (up to 6) remain accessible via scrolling

Package group contains maximum 6 packages

System displays all 6 packages in horizontal scroll view within the expanded section

Search query matches package name but not group name

System returns the parent package group in results; group is displayed with matching package inside

Search query returns no matching results

System displays empty state message: "No package groups found, please try again."

Multiple package groups are expanded simultaneously

System keeps all expanded groups open; expanding a new group does not collapse previously expanded groups

Brand is deleted after package group was created

Package group remains in listing; Brand column displays "Archived Brand" indicator; group becomes read-only or restricted

Package group name exceeds display width

System truncates the group name with ellipsis (...); full name shown on hover via tooltip

Events column has more than 2 event types

System displays first 2 event names with "+N" overflow indicator (e.g., "Wedding, Rehearsal Dinner, +1")

User loses network connection while expanding a group

System displays error toast: "Unable to load package details. Please try again." and row remains in collapsed state

User without edit permission views the list

Actions menu is hidden for non-Owner/Admin users; list displays in read-only mode

Package inside group has no price set

Package card displays placeholder text "Price not set" or "$0.00 USD"

User rapidly clicks expand/collapse on same row

System debounces clicks and processes only the final state to prevent UI flickering

User navigates away and returns to page

Sort and filter settings reset to default; all rows display in collapsed state

9. ACCEPTANCE CRITERIA

AC1: Package List View Loading

• Given the user has Owner, Admin, Project Manager, or Coordinator role,
• When the user navigates to the Packages module,
• Then the system displays the Package List View with all accessible package groups loaded in a table format.

AC2: Default Sort Order

• Given the Package List View is loaded,
• When no sort action has been taken by the user,
• Then the system displays package groups sorted by "Created Date - Newest First" by default.

AC3: Default Collapsed State

• Given the Package List View is loaded,
• When the page finishes rendering,
• Then all package group rows are displayed in collapsed state showing only group-level information.

AC4: Search Across Group and Package Names

• Given the user enters a search query,
• When the search query matches either a package group name or a package name within a group,
• Then the system displays the matching package groups in real-time as the user types.

AC5: Search No Results

• Given the user enters a search query,
• When the search query does not match any package group name or package name,
• Then the system displays the message: "No package groups found, please try again."

AC6: Expand Package Group Row

• Given the user clicks the expand chevron icon on a package group row,
• When the row expands,
• Then the system displays all packages within the group as horizontal cards showing package name, events, services, line items, and price.

AC7: Horizontal Scroll for More Than 3 Packages

• Given a package group contains more than 3 packages,
• When the user expands the package group row,
• Then the system enables horizontal scrolling within the expanded section to access all package cards.

AC8: Multiple Groups Expanded Simultaneously

• Given the user has expanded one or more package group rows,
• When the user expands an additional package group row,
• Then the system keeps all previously expanded rows open without collapsing them.

AC9: Sort by Column Header

• Given the user clicks on a sortable column header (Package Group, Brand, or Created),
• When the sort is applied,
• Then the system sorts the entire dataset by the selected column and displays a sort direction indicator.

AC10: Filter with AND Logic

• Given the user selects filters from multiple categories (e.g., Brand and Event Type),
• When the filters are applied,
• Then the system displays only package groups that match ALL selected filter criteria (AND logic).

AC11: Clear All Filters

• Given the user has active filters applied,
• When the user clicks "Clear All" in the filter panel,
• Then the system removes all filters and displays the full list of package groups.

AC12: Pagination Navigation

• Given the package group list has multiple pages,
• When the user clicks the Next or Previous button,
• Then the system loads the requested page and updates the page indicator accordingly.

AC13: Rows Per Page Change

• Given the user changes the "Rows per page" dropdown value,
• When a new value is selected (10, 25, or 50),
• Then the system updates the list to display the selected number of rows and resets to page 1.

AC14: Empty State Display

• Given no package groups exist in the system,
• When the user navigates to the Package List View,
• Then the system displays the empty state message: "No packages found. Create your first package group to start building your service offerings."

AC15: Create New Group Without Brands

• Given the agency has no brands configured,
• When the user clicks "+ Create New Group" button,
• Then the system displays an error modal: "Please create a brand before creating a package group."

AC16: Actions Menu Visibility

• Given the user has Owner or Admin role,
• When the user views the Package List View,
• Then the Actions menu (three-dot icon) is visible on each package group row.

AC17: Actions Menu Hidden for Non-Admins

• Given the user has Project Manager or Coordinator role,
• When the user views the Package List View,
• Then the Actions menu is not visible and the list is displayed in read-only mode.

10. MANUAL TEST CASES

Test cases for this module will be documented in a separate Excel file.

Test Case Excel File: [To be generated after all 8 FRDs are complete]

11. DEPENDENCIES

Module/System

Dependency Type

Impact if Unavailable

Brand Module

Data Dependency

Package groups cannot be created; "Create New Group" button triggers error; Brand column displays empty or error state

Package Builder (FRD #3)

Navigation Dependency

Edit action from Actions menu cannot navigate to Package Builder; users cannot edit package details

Package Group Creation Flow (FRD #2)

Navigation Dependency

"Create New Group" button fails to open creation wizard; new package groups cannot be created

Edit, Delete & Duplicate (FRD #4)

Functional Dependency

Actions menu options do not function; users cannot edit, delete, or duplicate package groups

User & Authentication Module

Access Dependency

Role-based permissions not enforced; session validation fails; users may be redirected to login

Event Types Master Data

Data Dependency

Events column displays empty or "Unknown Event"; filter by Event Type unavailable

Service Types Master Data

Data Dependency

Services column displays empty or "Unknown Service"; filter by Service Type unavailable

Database Service

System Dependency

Package group list fails to load; all operations fail; system displays error message

Session Management

System Dependency

User authentication state not maintained; unauthorized access possible or legitimate users blocked

12. REFERENCES

Figma

☑️ PACKAGE GROUP CREATION FLOW

Package Group Creation Flow

Functional Requirement Document

BA & Ideation: Paul

Reviewed By: KG (Project Manager)

Updated Date: 8 April 2026

Updated By: Sehal Maheshwari
Status: App

roved

Version 2.0

PACKAGE GROUP CREATION

1. MODULE OVERVIEW

1.1. Purpose

The Package Group Creation Flow is a guided, multi-step wizard that enables users to create a new Package Group from scratch. This wizard systematically configures group name, brand assignment, package count (1-6), events, services, and primary event designation before transitioning to the Package Builder for detailed configuration.

1.2. Business Goals

• Establish a foundational package structure with a logical, step-by-step flow
• Define the number of packages (1-6) within a single group
• Configure events and services for each package
• Establish primary event for multi-event packages
• Streamline setup with "Same Services" toggle option
• Ensure consistency across packages

2. USER ROLES & PERMISSIONS

Role

Create Group

Edit Group Structure

Add/Remove Packages

Change Brand

Delete Group

Owner

✔

✔

✔

✔

✔

Admin

✔

✔

✔

✔

✔

Project Manager

✖

✖

✖

✖

✖

Coordinator / Staff

✖

✖

✖

✖

✖

3. USER FLOW

3.1. Initiate Wizard

• Click "Create New Group" in Package List View → Wizard opens
• Left sidebar: "GROUP SETTINGS" (active), Package slots locked

3.2. Step 0: Group Settings

1. Enter Group Name (required, unique within brand)
2. Select Number of Packages (1-6 dropdown)
3. Select Brand (required, locked after creation)
4. Click "Next" → Sidebar dynamically shows package slots (Package 1-6 based on count)

3.3. Package Step 1: Name & Events (Per Package)

1. Enter Package Name (required, unique within group)
2. Select Event Types (multi-select: Wedding, Rehearsal Dinner, etc.)
3. If 2+ events selected: Select Primary Event (dropdown, required)
4. Click "Next" → Unlocks Step 2

3.4. Package Step 2: Choose Services (Per Package)

1. "Same Services For All Events" Toggle:
   • ON (default for multi-event): Select services once (Photo/Video/Both); applies to ALL events
   • OFF: Select services separately for each event
2. Click "Next" (or "Finish" if last package) → Completes package configuration

3.5. Complete All Packages

• Repeat Step 1 & Step 2 for each package (2-6 if selected)
• Click "Finish" on last package → Auto-saves to Draft → Navigates to Package Builder

3.6. Cancel/Exit

• * Click "Cancel" or "X" → Confirmation modal → If user confirms exit, all entered data is discarded → Returns to Package List View

3.7. Single-Service Brand Flow

• After completing Group Settings (Step 0), the system checks the number of services configured under the selected brand.
• If the brand has only one service configured, the package setup is simplified to a single screen per package — no step indicators or step labels are shown.
• Package Setup: Name & Events — User enters Package Name, selects Events, and selects Primary Event (if 2+ events). This is the only screen shown per package.
• On clicking "Next," the system auto-assigns the single available service to all selected events in the background and directly navigates to the next package.
• On the last package, the "Next" button changes to "Finish." Clicking "Finish" triggers final validation and navigates to Package Builder.
• The "Back" button on Package 2+ navigates to the previous package's setup screen.
• The left sidebar displays package slots without any step indicators — each slot shows only the package label (e.g., PACKAGE 1, PACKAGE 2) with a lock icon (pending), active state, or green checkmark (complete).

4. FUNCTIONAL LOGIC

4.1 Set Up Packages Group

• When the user clicks the “Create New Group” button from the Package Group List View, the system opens the Set Up Packages Group pop-up.
• The left section displays a vertical navigation menu titled Group Settings, which includes:
  • Main Details → Group Set Up (active by default)
  • Package 1, Package 2, Package 3, etc., based on the number of packages selected
• The Package tabs in the left section are dynamic. Their count is automatically generated based on the value selected in the Number of Packages field.
  • For example, if the user selects 3 packages, the left navigation displays Package 1, Package 2, and Package 3.
  • All package tabs remain locked (disabled state) until the user completes the Group Set Up step and clicks Next.
• In the main content area, the user must enter or select the following fields:
  • Group Name — free-text input.
  • Number of Packages — dropdown with options 1 to 6.
  • Brand — dropdown list of the agency’s all brands
• The Next button remains enabled as long as all required fields are completed.
• * Group name uniqueness is validated on Next button click. If the brand is changed after a name has been entered, the uniqueness check re-runs on the subsequent Next click against the newly selected brand.
• The Group Name field label includes an info icon (ℹ️). On hover or click, the system displays a tooltip with the following guidance text:
• "Use Groups to organize how packages appear on your booking proposal. For example, you might create separate groups like Photography and Videography so clients can browse each section easily.
• Groups are just for presentation and organization — they don't limit what you can include. Packages within a group can contain multiple services and/or multiple events, like photo + video + content creation, and wedding day + rehearsal dinner + engagement session. Organize groups in whatever way matches how you sell."
• The tooltip closes when the user clicks outside of it or hovers away.

4.2 Set Up Individual Package(General)

• Once the user completes the Package Group setup and clicks Next, the system redirects the user to the Individual Package Setup flow.
• The user must configure each package individually based on the number of packages selected during the Package Group setup.
• Each package follows a two-step setup process:
  • Step 1: Name and Events
  • Step 2: Choose Services

4.2.1 Step 1 – Name and Events

• In this step, the user is required to configure the package name and event details.
• The user can enter the Package Name, which is a mandatory field and is displayed as the package title throughout the system.
• The user can select one or more Events that are part of the package.
• The list of events is fetched from the events configured under the selected Brand during the Package Group setup (refer to section 4.1).
• The user can select multiple events from the available event list.
• The Primary Event dropdown displays only the events selected in the Events selection section.
• The user can select any of the chosen events as the Primary Event.
• If only one event is selected, that event is automatically set as the Primary Event and the dropdown is disabled (read-only).
• Clicking Next moves the user to Step 2: Choose Services.
• * Clicking **Back** navigates as follows: *
  • On Package 1 Step 1, Back navigates to Group Settings.
  • On Package 2+ Step 1, Back navigates to the previous package's Step 2.

4.2.2 Step 2 – Choose Services

• In this step, the user selects the services offered for the events included in the package.
• The list of services is fetched from the services configured under the selected Brand during the Package Group setup.
• A toggle option “Same services for all events” is displayed to control how services are applied across events.
• * If the package has **only one event** selected in Step 1, the toggle is displayed in a **disabled (greyed out) state** set to ON.
• * If the selected Brand has **only one service** configured, the toggle is displayed in a **disabled (greyed out) state** set to ON.

4.2.2.1 Same Services for All Events – Toggle ON

• If the package has only one event selected in Step 1, the toggle is enabled by default and cannot be turned off.
• If the selected Brand has only one service configured, the toggle is enabled by default and cannot be turned off.
• When the toggle is ON and multiple events are selected:
  • The user selects the services that apply uniformly to all events in the package.
  • The user can select one or multiple services such as Photography, Videography, or Content Creation (based on brand configuration).
  • The selected services are automatically linked to each event included in the package.

4.2.2.2 Same Services for All Events – Toggle OFF

• When the toggle is turned OFF, the system displays separate service selection sections for each event selected in Step 1.
• Each event section displays:
  • The event name as a header (e.g., Wedding, Rehearsal Dinner), along with the event color indicator.
  • Service selection buttons below the header, fetched from the selected Brand’s configured services.
• The user can independently select one or multiple services for each event.
• Different events within the same package can have different service combinations.
  • For example:
    • Wedding may have Photography and Videography selected.
    • Rehearsal Dinner may have only Photography selected.

4.3 Single-Service Brand Detection & Auto-Assignment

• When the user completes Group Settings and clicks "Next," the system queries the service count for the selected brand.
• If the brand is changed mid-wizard, all Event selections in Step 1 and all Service selections in Step 2 for every package are cleared. All package slots revert to locked/incomplete state (lock icon) regardless of prior completion status, and the user is returned to Package 1 Step 1.
• If the brand changes from single-service to multi-service (or vice versa), previously assigned or selected services are cleared and packages revert to incomplete, where the two-step flow is now required (or no longer required).
• * When the selected brand has only one service configured and the package contains multiple events, the "Same services for all events" toggle is displayed in a disabled (greyed out) state set to ON.
• Each package displays a single setup screen with Package Name, Event Selection, and Primary Event fields. No step labels (Step 1, Step 2) or step indicators are shown anywhere in the UI.
• Upon clicking "Next," the system automatically assigns the single available service to every event selected in that package.
• The sidebar shows package slots without step breakdowns — only the package name with a lock icon (pending), active highlight, or green checkmark (complete).
• Clicking a completed package in the sidebar reopens that package's setup screen for editing.
• The auto-assigned service data is saved to the database as part of the standard auto-save trigger, identical in structure to manually selected service data.
• The "Finish" button appears on the last package instead of "Next."
• Final validation still checks that every event in every package has at least one service assigned. The auto-assigned service satisfies this requirement.

4.4 Package Completion and Navigation

• When the user clicks "Next" from Step 2 and validation passes, the system marks the current package as complete with a checkmark in the sidebar.
• If more packages exist in the group, the system unlocks the next package slot and navigates to that package's Step 1.
• The "Next" button text changes to "Finish" when the user is on the last package's Step 2.
• When the user clicks "Finish" on the last package, the system performs a final validation to ensure all packages are fully configured.
• Each package must have a name, at least one event selected, a primary event designated (if multi-event), and at least one service selected for each event.
• If all packages pass validation, the system saves the complete package group structure, closes the wizard, and navigates to the Package Builder.

4.5 Adding Packages After Initial Setup

• Users can return to Group Settings during the wizard and increase the Number of Packages value.
• When the package count is increased (e.g., from 3 to 4), the system adds a new package slot to the sidebar with a lock icon.

4.6 Removing Packages After Initial Setup

• Users can return to Group Settings during the wizard and decrease the Number of Packages value.
• When the package count is decreased, the system identifies all packages to be removed.
• **Single Package Removal:** If only one package is being removed (e.g., from 4 to 3), the system displays a confirmation modal with the title "Remove Package" and the message "Reducing the number of packages will permanently delete Package 4 and all its configuration. This action cannot be undone. Continue?" with "Cancel" and "Remove Package" buttons.
• **Multiple Package Removal:** If more than one package is being removed (e.g., from 6 to 2), the system displays a confirmation modal with the title "Remove Packages" and the message listing all affected packages: "Reducing the number of packages will permanently delete the following packages and all their configurations: - Package 3 - Package 4 - Package 5 - Package 6 . This action cannot be undone. Continue?" The modal displays "Cancel" and "Remove Packages" buttons.
• If the user clicks "Remove Package" or "Remove Packages", the system permanently deletes the affected package records, removes the slots from the sidebar, and updates the package count.
• If the user clicks "Cancel", no changes are made and the package count reverts to the original value.

4.7 Cancel and Close Wizard Behavior

• When the user clicks the "Cancel" button or the "X" close button, the system displays a confirmation modal.
• The confirmation modal displays the title "Cancel Package Group Creation?" and the message "Are you sure you want to exit? All unsaved progress will be lost. This action cannot be undone." with "Stay" and "Exit" buttons.
• If the user clicks "Exit", the system discards all entered data, closes the wizard, and returns the user to the Package List View.
• If the user clicks "Stay", the wizard remains open with no changes.
• **Draft Group Resume Behavior:** Draft groups visible in the Package List View can be resumed by clicking Edit, which opens the Package Builder — not the Creation Wizard. The wizard is only used for initial creation.

4.8 Transition to Package Builder

• Upon successful wizard completion, the system navigates to the Package Builder.
• The Package Builder loads with all packages displayed in the left sidebar with settings icons next to each package name.
• The first package is automatically selected and displayed in the center canvas.
• The center canvas displays the package name (editable), an empty description field, an empty price field with placeholder "Specify the price", event sections with colored headers for each event, service types listed under each event, empty line item slots with placeholder text, and an "Assign A La Carte Items +" button.
• Users proceed in the Package Builder to add line items, configure deliverables, set pricing, upload images, configure tax settings, and link A-La-Carte items before publishing.

5. FIELD DETAILS & VALIDATIONS

5.1 Group Settings Fields

Field Name

Field Type

Required

Validation Rules

Group Name

Text Input

Yes

Minimum 1 character; maximum 100 characters; must be unique within brand (case-insensitive); cannot be empty or whitespace only

Number of Packages

Dropdown Select

Yes

Options: 1, 2, 3, 4, 5, 6; must select one value; determines the number of package slots created

Brand

Dropdown Select

Yes

Populated with brands accessible to current user; must select one brand; locked after proceeding to Package 1

Group Name Info Tooltip

Icon + Tooltip

Yes

Informational only. Displays on hover/click of ℹ️ icon next to Group Name label. No user input. Dismisses on outside click or hover away.

5.2 Package Step 1 Fields

Field Name

Field Type

Required

Validation Rules

Package Name

Text Input

Yes

Minimum 1 character; maximum 100 characters; must be unique within package group (case-insensitive); cannot be empty or whitespace only

Event Selection

Multi-Select Buttons

Yes

At least one event must be selected; populated from Event Types Master Data

Primary Event

Dropdown Select

Conditional

Required only if 2+ events selected; populated with selected events only; must select one primary event

Finish Button (Single-Service)

Button (Primary)

Conditional

Displayed on the last package only when the brand has one service. Replaces the Next button. Triggers final validation.

5.3 Package Step 2 Fields

Field Name

Field Type

Required

Validation Rules

Same Services Toggle

Toggle Switch

No

Displayed for all packages; default ON; disabled (greyed out) for single-event packages or single-service brands

Service Selection (Unified)

Multi-Select Buttons

Conditional

Required when toggle ON; at least one service must be selected; options: Photography, Videography, Content Creation

Service Selection (Per Event)

Multi-Select Buttons

Conditional

Required when toggle OFF; at least one service must be selected for each event

5.4 Wizard Navigation Controls

Field Name

Field Type

Description

Validation Rules

Next Button

Button (Primary)

Proceeds to next step after validation

Enabled when current step fields are valid; disabled during validation processing

Finish Button

Button (Primary)

Completes wizard on final package Step 2

Replaces Next button on last package; triggers final validation of all packages

Cancel Button

Button (Secondary)

Exits wizard with draft save

Displays confirmation modal before exiting; discards all entered data if user confirms exit

Close (X) Button

Icon Button

Closes wizard

Behaves identically to Cancel button

6. SUCCESS MESSAGE HANDLING

Validation Scenario

Success Message

Group Settings saved successfully

No explicit message - System navigates to Package 1 Step 1

Package Step 1 saved successfully

No explicit message - System navigates to Step 2

Package Step 2 saved successfully

No explicit message - System navigates to next package or displays Finish button

Package marked as complete

No explicit message - Checkmark icon appears in sidebar

Wizard completed successfully

"Package group created successfully." (Toast notification)

Wizard cancelled

No explicit message - Returns to Package List View

Package removed successfully

"Package removed successfully." (Toast notification)

Auto-save completed

No explicit message - Data saved silently in background

7. ERROR MESSAGE HANDLING

Field

Validation Scenario

Error Message

Group Name

Field is empty

"Group name is required."

Group Name

Exceeds maximum length

"Group name cannot exceed 100 characters."

Group Name

Duplicate name exists in brand

"Group name already exists."

Number of Packages

No selection made

"Please select the number of packages."

Brand

No selection made

"Brand is required."

Package Name

Field is empty

"Package name is required."

Package Name

Exceeds maximum length

"Package name cannot exceed 100 characters."

Package Name

Duplicate name in group

"Package name already exists within this group."

Event Selection

No events selected

"Please select at least one event."

Primary Event

Not selected when required

"Please select a primary event."

Service Selection (Toggle ON)

No services selected

"Please select at least one service."

Service Selection (Toggle OFF)

Event missing services

"Please select at least one service for [Event Name]."

Brand Check

No brands exist in agency

"Please create a brand before creating a package group."

Server Error

Failed to save data

"Failed to save package group. Please try again."

Session

User session expired

"Your session has expired. Please log in again."

8. EDGE CASES

Scenario

Expected Behavior

User attempts to create package group but no brands exist

System displays error modal: "Please create a brand before creating a package group." and does not open wizard

User selects only one event in Step 1

Primary Event dropdown is hidden; single event is automatically designated as primary

User selects multiple events then deselects to single event

Primary Event dropdown disappears; remaining single event becomes primary automatically

User toggles Same Services from ON to OFF after selecting services

System displays confirmation modal; if confirmed, clears previous selections

User toggles Same Services from OFF to ON after selecting per-event services

System displays confirmation modal; if confirmed, clears per-event selections

User increases package count from 3 to 4 during wizard

New package slot added

User decreases package count from 4 to 3 during wizard

Confirmation modal displayed; if confirmed, Package 4 is permanently deleted with all configuration

User enters group name that differs only in case from existing name

System treats as duplicate and displays error: "Group name already exists."

User enters package name that differs only in case from sibling package

System treats as duplicate and displays error: "Package name already exists within this group."

User attempts to skip to locked package in sidebar

System prevents navigation; locked packages cannot be accessed until previous packages are complete

User navigates backward to edit completed package

Previous step loaded with saved data; changes auto-saved when navigating away

User selects all available event types for a package

System allows all events; Primary Event dropdown displays all selected events

User selects all three service types for all events

System allows all services; no maximum service limit

Network error occurs during auto-save

System displays error toast: "Failed to save. Please check your connection." and retries on next action

Single-service brand with single event

Primary Event dropdown gets default. Package completes after entering name and selecting the single event. Simplest possible flow.

User changes brand mid-wizard after completing some packages

All package slots revert to locked/incomplete state (lock icon) regardless of prior completion status; all Event and Service selections are cleared; user is returned to Package 1 Step 1

User decreases package count from 6 to 1 (removing 5 packages)

System displays confirmation modal with title "Remove Packages?" listing all affected packages (Package 2, 3, 4, 5, 6) with "Remove Packages" button

9. ACCEPTANCE CRITERIA

AC1: Wizard Access Control

• Given the user has Project Manager, Coordinator, Contractor, or Client role,
• When the user views the Package List View,
• Then the "+ Create New Group" button is not visible or is disabled.

AC2: Brand Prerequisite Check

• Given no brands exist in the agency,
• When a user with Owner or Admin role clicks "+ Create New Group",
• Then the system displays an error modal with the message "Please create a brand before creating a package group."

AC3: Group Settings Validation

• Given the user is on the Group Settings step,
• When the user clicks "Next" without completing all required fields,
• Then the system displays inline error messages for each incomplete field and prevents navigation.

AC4: Group Name Uniqueness

• Given a package group with name "Wedding Collection" exists in brand "Emma Taylor",
• When the user enters "Wedding Collection" (or "wedding collection") as the group name for the same brand,
• Then the system displays the error message "Group name already exists."

AC5: Dynamic Package Slot Generation

• Given the user is on Group Settings,
• When the user selects "4" from the Number of Packages dropdown,
• Then the system displays four package slots (PACKAGE 1, PACKAGE 2, PACKAGE 3, PACKAGE 4) in the left sidebar with lock icons.

AC6: Single Event Primary Designation

• Given the user is on Package Step 1,
• When the user selects only one event (e.g., "Wedding"),
• Then the Primary Event dropdown is disabled and the single event is automatically designated as primary.

AC7: Multi-Event Primary Requirement

• Given the user is on Package Step 1 and has selected multiple events,
• When the user clicks "Next" without selecting a primary event from the dropdown,
• Then the system displays the error message "Please select a primary event."

AC8: Same Services Toggle Default State

• Given the user completes Step 1 with multiple events selected,
• When the user navigates to Step 2,
• Then the "Same services for all events" toggle is displayed and set to ON by default.

AC9: Same Services Toggle Hidden for Single Event

• Given the user completes Step 1 with only one event selected,
• When the user navigates to Step 2,
• Then the "Same services for all events" toggle is displayed in a disabled (greyed out) state set to ON.

AC10: Toggle Change Confirmation

• Given the user has selected services with the toggle ON,
• When the user switches the toggle to OFF,
• Then the system displays a confirmation modal warning that selections will be reset.

AC11: Per-Event Service Validation

• Given the toggle is OFF and multiple events exist,
• When the user clicks "Next" without selecting services for all events,
• Then the system displays error messages for each event missing services.

AC12: Sequential Package Configuration

• Given the user has completed Package 1,
• When the user views the sidebar,
• Then PACKAGE 1 shows a green checkmark, PACKAGE 2 is unlocked, and remaining packages show lock icons.

AC13: Finish Button Display

• Given the user is on the last package's Step 2,
• When the step loads,
• Then the "Next" button is replaced with a "Finish" button.

AC14: Wizard Completion Validation

• Given all packages are fully configured with required fields,
• When the user clicks "Finish",
• Then the system saves the package group and navigates to the Package Builder.

AC15: Transition to Package Builder

• Given all packages are fully configured,
• When the user clicks "Finish",
• Then the system closes the wizard, navigates to Package Builder with the group loaded, and displays a success toast.

AC16: Cancel Wizard with Draft Save

• Given the user has entered data in the wizard,
• When the user clicks "Cancel" and confirms exit,
• Then all entered data is discarded and the user returns to Package List View. No draft is created.

AC17: Decrease Package Count Confirmation

• Given the user has configured 4 packages,
• When the user returns to Group Settings and changes Number of Packages to 3,
• Then the system displays a confirmation modal warning that Package 4 will be permanently deleted.

AC18: Auto-Save on Navigation

• Given the user has entered data in Package 1 Step 1,
• When the user clicks "Next" to proceed to Step 2,
• Then the system automatically saves Package 1 Step 1 data to draft before navigating.

10. MANUAL TEST CASES

Test cases for this module will be documented in a separate Excel file.

Test Case Excel File:

11. DEPENDENCIES

Module/System

Dependency Type

Impact if Unavailable

Brand Module

Data Dependency

Wizard cannot open if no brands exist; Brand dropdown cannot be populated; error modal displayed to user

Event Types Master Data

Data Dependency

Event selection buttons cannot be populated; Step 1 cannot be completed; users cannot configure events

Service Types Master Data

Data Dependency

Service selection buttons cannot be populated; Step 2 cannot be completed; users cannot configure services

Package List View (FRD #1)

Navigation Dependency

Users cannot initiate wizard; cannot return to list after cancel; draft groups not visible

Package Builder (FRD #3)

Navigation Dependency

Wizard completion fails to navigate; users cannot proceed to line item configuration

User & Authentication Module

Access Dependency

Role validation fails; unauthorized users may access wizard; session management unavailable

Database Service

System Dependency

Auto-save fails; draft records cannot be created; wizard progress lost

Session Management

System Dependency

Wizard state not maintained across page refreshes; user may lose unsaved progress

12. REFERENCES

Figma Design-

https://www.figma.com/design/ej0kxwP45mDKmZCZfAJ5O8/Pixally?node-id=19582-148303&t=BAkQ9BaQzOENaQKr-0

☑️ PACKAGE BUILDER

Package Builder

Functional Requirement Document

BA & Ideation: Paul

Reviewed By: KG (Project Manager)

Updated Date: 18 June 2026

Updated By: Claude AI

Status: Approved

Version 2.1

PACKAGE BUILDER (MAIN EDITOR) - FUNCTIONAL REQUIREMENTS DOCUMENT

Module: Package Builder (Main Editor) Document Version: 2.1

Change Note (v2.1): Added A La Carte tab empty-state handling for packages that have no events configured. When a user opens the A La Carte tab (via the package card's "Assign A La Carte Items +" link or the Package Settings panel) for a package with zero events, the system now displays a guidance message instructing the user to add events and services before assigning A-La-Carte items. Updates span Section 3 (User Flow), Section 4 (Functional Logic), Section 7 (Error Message Handling), Section 8 (Edge Cases), and Section 9 (Acceptance Criteria).

1. MODULE OVERVIEW

1.1 Module Name

Package Builder (Main Editor)

1.2 Purpose

The Package Builder is the core configuration interface where users design and customize individual packages within a Package Group. This module serves as the comprehensive editor for all package-level details, including naming, pricing, imagery, line items, deliverables, smart fields, tax settings, and A-La-Carte item linkage. Users access this module after completing the Package Group Creation wizard or by editing an existing package group from the Package List View.

1.3 Business Goals

• Enable agencies to configure detailed package offerings with a professional presentation, including name, description, and image.

• Define service deliverables through line items with due date rules for post-production workflow integration.

• Implement flexible tax structures supporting package-level or item-level taxation approaches.

• Integrate Smart Fields for dynamic data mapping to proposals, contracts, and projects including coverage hours, image counts, and crew assignments.

• Link A-La-Carte items to packages for client customization options during proposal selection.

• Maintain version control through Draft/Publish workflow ensuring active proposals remain protected from retroactive changes.

• Provide intuitive editing capabilities for events, services, and line items inherited from the Package Group Creation wizard.

1.4 Key Definitions

Line Item A Line Item is a specific deliverable or service component within a package that describes what the client will receive. Line items are categorized into two types: Custom (user-created items with free-text names) and Smart Field (predefined system fields that map to proposals, contracts, and projects). Each line item can be marked as a deliverable with due date rules for post-production tracking.

Smart Field A Smart Field is a predefined, hardcoded field type that captures dynamic data values which are mapped to proposals, contracts, and project details. Smart Fields enable automation workflows and standardized data capture. Users cannot create new Smart Field types; they can only select from the predefined list of 9 Smart Fields.

Deliverable A Deliverable is a line item marked for delivery to the client with an associated due date calculated from the event date. Deliverables are automatically added to the Post-Production board after the event occurs, enabling workflow tracking and completion management.

Tax Mode Tax Mode determines how taxes are calculated for a package. Three options are available: Entire Package Taxable (tax on full package price), Entire Package Non-Taxable (no tax), and Line Item Based Tax (tax calculated on individual line items with taxable toggles).

2. USER ROLES & PERMISSIONS

2.1 Roles That Can Access the Module

Role

Access Level

Owner

Full Access

Admin

Full Access

Project Manager

View + Limited Edit (Agency Configurable)

Contractor

No Access

Client

No Access

2.2 Granular Permissions

Permission

Owner

Admin

Project Manager

View Package Builder

✔

✔

✔

Edit Package Name/Description

✔

✔

✔*

Upload Package Image

✔

✔

✔*

Edit Package Price

✔

✔

✔*

Add/Edit/Delete Line Items

✔

✔

✔*

Configure Deliverables

✔

✔

✔*

Change Tax Mode

✔

✔

✖

Link A-La-Carte Items

✔

✔

✔*

Edit Events and Services

✔

✔

✖

Edit Group Settings

✔

✔

✖

Publish/Republish Package

✔

✔

✖

Duplicate Package

✔

✔

✖

Permissions marked with asterisk () are configurable at the agency level and may be enabled or disabled by Owner/Admin.

2.3 Permission Notes

• Only Owner and Admin roles can publish packages to make them available for proposals.

• Only Owner and Admin roles can change tax mode settings.

• Only Owner and Admin roles can modify group-level settings including package count.

• Contractors and Clients never access the Package Builder interface.

3. USER FLOW

3.1 The user navigates to the Package Builder by clicking "Edit" on a package group from the Package List View or by completing the Package Group Creation wizard which automatically redirects to the builder.

3.2 The system validates that the user has appropriate permissions (Owner, Admin, or authorized PM/Coordinator) to access the Package Builder.

3.3 The system retrieves the package group data from the database using the group ID from the URL (/packages/builder/{group_id}).

3.4 The system loads the Package Builder interface displaying three main sections: left sidebar with package list, center canvas with package details, and right panel for Package Settings.

3.4.1 When the user hovers over the truncated group name, the system displays a tooltip showing the full group name (e.g., "Photography/Videography Combo").

3.5 The system displays all packages within the group in the left sidebar (e.g., Package 1, Package 2, Package 3) with settings icons next to each package name.

3.6 The system auto-selects the first package and displays its details in the center canvas.

3.7 The center canvas displays the selected package's name, description placeholder, price field, image placeholder, event sections with service types, and line item slots.

3.8 The system displays a status badge (Draft or Published) near the package name indicating the current publication status of the package.

3.9 The user clicks on a different package in the left sidebar to switch to that package for editing.

3.9.1 The system auto-saves any unsaved changes to the previously selected package and loads the newly selected package into the center canvas.

3.10 The user clicks on the package name field in the center canvas to edit the package name.

3.11 The system enables inline editing for the package name field allowing the user to type a new name (maximum 100 characters).

3.12 The system validates that the package name is not empty and is unique within the package group.

3.13 The system auto-saves the updated package name to draft status.

3.14 The user clicks on the package description area to add or edit the description.

3.15 The system displays a rich text editor supporting bold, italic, underline, bullet lists, numbered lists, and headers.

3.16 The user enters the package description and the system auto-saves the content to draft status.

3.17 The user clicks "Add Image" or the image placeholder area to upload a package image.

3.18 The system opens a file picker dialog accepting only JPG and PNG file formats with a maximum file size of 15MB.

3.19 The user selects an image file from their device.

3.20 The system validates the file format and size, then opens a crop tool with aspect ratio options.

3.21 The user adjusts the crop area and clicks "Crop & Save" to finalize the image.

3.22 The system uploads the cropped image to file storage and displays the thumbnail in the Package Builder.

3.23 The user clicks on the price field (placeholder: "Specify the price") to enter the package price.

3.24 The system displays a numeric input field with currency formatting.

3.25 The user enters the package price (e.g., 450.00) and the system validates that the value is numeric, includes exactly two decimal places, and meets the minimum required amount of $5.00.

3.26 The system auto-saves the package price to draft status.

3.27 The user views the event sections in the center canvas (e.g., WEDDING section with beige background, REHEARSAL DINNER section with blue background).

3.28 Each event section displays the service types included (e.g., Photography, Videography) with line item slots beneath each service.

3.29 The user hovers over a line item slot within an event's service section and sees a "+" icon appear.

3.30 The user clicks the "+" icon to add a new line item to that specific event's service section.

3.31 The system opens the Line Item Settings panel on the right side displaying fields for Type, Text/Name, Description, Quantity, Deliverable toggle, and conditional fields based on selections.

3.32 The user selects the line item type from the dropdown: either "Custom" or "Smart Field".

3.33 If the user selects "Custom" as the line item type, the system displays a text input field for the line item name.

3.34 The user enters a custom line item name (e.g., "Basic Retouch") with maximum 250 characters.

3.35 If the user selects "Smart Field" as the line item type, the system displays a dropdown with 9 predefined smart field options.

3.36 The user selects a smart field from the dropdown (e.g., "Hours of Coverage", "Number of Edited Images", "Number of Photographers").

3.37 The system displays a secondary mandatory field based on the selected smart field type (e.g., number input for hours, images, or crew count).

3.38 The user enters the value for the secondary smart field (e.g., 8 hours, 200 images, 2 photographers).

3.39 The user optionally enters a description for the line item in the description text area.

3.40 The user enters the quantity for the line item (required field, default value: 1, maximum: 999).

3.41 The user toggles the Deliverable switch to ON if this line item should be tracked as a deliverable in Post-Production.

3.42 If Deliverable toggle is ON, the system displays due date configuration fields: a numeric value dropdown (1-99 or "No Due Date") and a unit dropdown (Days, Weeks, Months).

3.43 The user selects a due date value and unit (e.g., 10 Days after event) or selects "No Due Date" to skip due date calculation.

3.44 If the tax mode is set to "Line Item Based Tax", the system displays a Taxable toggle and Price of Line Item field for the line item.

3.45 The user toggles Taxable ON if the line item should be taxed, then enters the line item price for tax calculation purposes.

3.45.1 If the user enters a Price of Line Item value that exceeds the current Package Price, the system displays a warning message: "The line item price exceeds the total package price. Please verify the amount." The warning is non-blocking and the user can proceed with saving the line item.

3.45.2 The Line Item Settings panel displays a "Save as preset" toggle with an info icon. When hovered or clicked, the tooltip displays: "Turn this on to save these settings as a preset. It will appear in the Add Deliverable list when manually adding deliverables."

3.45.3 The "Save as preset" toggle is OFF by default. When the user toggles it ON and saves the line item, the system saves the line item configuration as a reusable preset.

3.45.4 Saved presets appear in the Add Deliverable list when manually adding deliverables in other modules.

3.46 The user clicks "Save" to save the line item configuration.

3.47 The system validates all required fields (name/smart field selection, quantity, secondary smart field value if applicable, due date if deliverable ON).

3.48 If validation passes, the system saves the line item to draft and displays it in the appropriate event's service section in the center canvas.

3.49 The user clicks on an existing line item in the center canvas to edit it.

3.50 The system opens the Line Item Settings panel with all fields pre-populated with the existing values.

3.51 The user modifies the desired fields and it gets auto-saved.

3.52 The system validates the updated line item and auto-saves it to draft status.

3.53 The user clicks the delete icon (trash) on a line item to remove it.

3.54 The system displays a confirmation modal: "Delete Line Item? Are you sure you want to delete '[Line Item Name]'? This action cannot be undone."

3.55 The user clicks "Delete" to confirm or "Cancel" to abort the deletion.

3.56 If confirmed, the system removes the line item from the canvas and saves the change to draft.

3.57 The user drags a line item within the same event's service section to reorder it.

3.58 The system updates the display order immediately and auto-saves the new order to draft.

3.59 The user clicks on the Package Settings panel (right sidebar) to access the General tab.

3.60 The General tab displays package name, description, price, tax mode dropdown, and events/services structure.

3.61 The user clicks the Tax Mode dropdown to change the tax setting.

3.62 The system displays three options: "Not taxable", "Tax entire package", and "Tax specific line items".

3.63 If the user switches from "Tax specific line items" to another mode, the system displays a confirmation modal warning that line item tax settings will be cleared.

3.64 The user confirms the tax mode change and the system updates the line item interface accordingly (enabling or disabling taxable toggles).

3.65 The user clicks "Edit Events and Services" button in the Package Settings panel.

3.66 The system opens a modal displaying current events with their assigned services and options to modify.

3.67 The user can change an event type using the dropdown, add new events using "+ Add New Event Type", or remove events using the delete icon.

3.68 The user can add services to an event using the "+" icon or remove services using the delete icon.

3.69 The user clicks "Proceed to Builder" to save event/service changes and return to the canvas.

3.70 The system validates that at least one event exists and each event has at least one service, then saves changes to draft.

3.71 The system updates the center canvas to reflect the new event/service structure while retaining existing line items.

3.72 A La Carte Tab and Item Assignment

3.72 The user opens the A La Carte tab for a package in one of two ways: (a) by clicking the "Assign A La Carte Items +" link at the bottom of the package card on the center canvas, or (b) by selecting the package and clicking the "A La Carte" tab in the Package Settings panel (right drawer). Both entry points open the Package Settings drawer with the "A La Carte" tab pre-selected.

3.73 The system displays the A La Carte tab content based on whether the selected package has events configured:

3.73.1 If the package has one or more events configured: The A La Carte tab displays each configured event (e.g., "ENGAGEMENT PHOTOSHOOT") as a collapsible row, with a "+ Add A La Carte Items" button beneath each event. A-La-Carte items are assigned per event.

3.73.2 If the package has no events configured: The A La Carte tab displays an empty-state message in place of the event list: "This package has no events configured yet. Add events and services to this package first before assigning A La Carte items." No "+ Add A La Carte Items" button is shown because there is no event to assign items to.

3.73.3 The empty-state message is informational only (no CTA button). The user is expected to configure events via the "General" tab / "Edit Events and Services" modal, or directly on the package card, and then return to the A La Carte tab.

3.73.4 The "Assign A La Carte Items +" link on the package card remains enabled for every package regardless of event configuration; packages without events are not visually disabled or greyed out. The guidance is provided through the empty-state message after the drawer opens.

3.74 For a package that has events, the user clicks the "+ Add A La Carte Items" button under an event to open the assignment modal.

3.75 The system opens a modal with two tabs: "Add-on" (showing Custom Items and Smart Items) and "Event" (showing Event-Creation Add-ons).

3.76 The user selects the "Add-on" tab and views available A-La-Carte items with checkboxes.

3.77 The user selects one or more items by clicking checkboxes (multi-select supported).

3.78 The user clicks the "Event" tab to view Event-Creation A-La-Carte items (add-on events like Engagement Shoot).

3.79 The user selects desired Event-Creation items by clicking checkboxes.

3.80 The user clicks "Assign" to link the selected items to the package.

3.81 The system saves the A-La-Carte links to draft and displays the linked items in the A La Carte tab.

3.82 The user clicks the "X" icon next to a linked A-La-Carte item to unlink it.

3.83 The system removes the link (not the item itself) and auto-saves to draft.

3.84 The user clicks the settings icon next to the package group name to open Group Settings.

3.85 The system displays Group Settings panel showing Group Name (editable), Number of Packages (editable dropdown 1-6), and Brand (read-only, locked).

3.86 The user can edit the Group Name and click outside the field to auto-save.

3.87 The user can change the Number of Packages to add packages to the group. To remove a package, the user must delete it directly from the package card using the delete action.

3.88 If the user increases the package count, the system adds new package slots to the left sidebar requiring configuration. Newly added packages have no events configured until the user sets them up; see Section 3.73.2 for A La Carte tab behavior on such packages.

3.89 Decreasing package count from Group Settings is not supported. Users must delete packages individually from the package card.

3.90 The user clicks the "Publish" button (top right) to publish the package for use in proposals.

3.91 The system validates that all mandatory fields are complete: Package Name is not empty, Package Price is set, and at least one line item exists in each event's service section.

3.92 If validation fails, the system displays an error toast: "Publish blocked — complete all mandatory fields" and highlights the incomplete fields.

3.93 If validation passes, the system changes the package status from Draft to Published and displays a success toast: "Package published successfully."

3.94 The system makes the package available in the Proposal Builder and changes the "Publish" button to "Republish" for future edits.

3.95 The user edits a previously published package by modifying any fields (name, price, line items, etc.).

3.96 The system auto-saves all changes to draft status without affecting existing proposals that use this package.

3.96.1 When a user edits a previously published package, the system displays an alert banner at the top of the Package Builder with a warning icon and the message: "Unpublished changes detected. Publish to update proposals with your latest edits."

3.96.2 The banner includes a "Publish Changes" button on the right side.

3.96.3 Clicking "Publish Changes" triggers the same validation and publish flow as the main Publish button.

3.96.4 The banner remains visible until the user publishes the changes or reverts to the last published state.

3.97 The user clicks "Republish" to finalize the changes and make them available for new proposals.

3.98 The system publishes the updated package and displays a success toast: "Package republished successfully. Future proposals will use the updated version."

3.99 Existing proposals retain their original package snapshots and are not affected by the republished changes.

3.100 The user clicks the "Preview" button located in the top action bar to preview how the package group will appear to clients in a proposal.

3.101 The system opens a preview overlay within the same tab displaying all packages in the group as they would appear in a proposal.

3.102 The preview displays up to 3 packages side by side by default; if more than 3 packages exist, users can horizontally scroll to view additional packages.

3.103 The user can click the left or right navigation arrows to view other packages in the group.

3.104 The user clicks the close button (X) to exit preview mode and return to the Package Builder. Clicking outside the overlay does not close the preview.

3.105 Single-Service Brand in Package Builder

• When the package group's brand has only one service configured, the center canvas does not display service type headers (e.g., Photography, Videography) under each event section.

• Line items appear directly under the event header without any service sub-grouping.

• The "Edit Events and Services" modal does not show service selection options. The single service is pre-assigned and locked for all events.

3.106 Single-Event Brand in Package Builder

• When the package group's brand has only one event type configured, the "Edit Events and Services" button in the Package Settings panel is hidden entirely.

• The single event is pre-assigned to the package and cannot be modified from the builder.

• The center canvas displays line items under the single event header without the option to add, remove, or change events.

3.107 Tax Warning on Publish (Line Item Based Tax)

• When the tax mode is set to "Tax specific line items" and the user clicks Publish/Republish, the system checks whether at least one line item has the Taxable toggle set to ON.

• If no line items have Taxable toggled ON, the system displays a warning modal: "You've selected line item based tax but haven't marked any line items as taxable. Do you want to continue publishing without any taxable items?" with "Go Back" and "Continue" buttons.

• If the user clicks "Continue," the package is published as-is. If the user clicks "Go Back," the user returns to the builder to configure tax settings.

• This is a non-blocking warning — publishing is not prevented.

3.108 Taxable Toggle and Price of Line Item Visibility

• When the tax mode is "Tax specific line items," each line item displays a Taxable toggle in the Line Item Settings panel.

• When the Taxable toggle is OFF, the "Price of Line Item" field is hidden.

• When the Taxable toggle is switched ON, the "Price of Line Item" field appears below the toggle and is required.

Configuring Package Color Styling

3.109 The user clicks the "Colors" tab in the left sidebar of the Package Builder.

3.110 The system displays the Color Styling panel with configurable color options for the package group.

3.111 A tooltip is displayed at the top of the panel: "The right panel reflects color updates in real-time as you edit. To see exactly how clients will view your package, click 'Preview' in the top-right corner."

3.112 The Color Styling panel displays the following sections: Package Area, Event Section, Service Section, Item Rows, Background, and System Button Color.

3.113 The user clicks on a color picker for any field to select a custom color.

3.114 The system updates the preview in real-time as colors are changed.

3.115 All color changes are auto-saved and apply to ALL packages within the package group (group-level setting).

3.116 The user can click "Preview" in the top-right corner to see exactly how clients will view the package with the applied colors.

3.117 Package Area Colors

3.117.1 The user configures the following colors under Package Area:

• Header Text Color: Controls the package name text color

• Price Color: Controls the price display text color

• Body Text Color: Controls the description text color

3.117.2 An info icon displays tooltip on hover: "These colors apply to the main package card: the package name, price display, and description text."

3.118 Event Section Colors

3.118.1 The user configures the following colors under Event Section:

• Header Text Color: Controls the event header text color (e.g., "WEDDING")

• Border Color: Controls the event section border color

3.118.2 An info icon displays tooltip on hover: "These colors apply to event headers within the package. Note: Event background color is inherited from your brand's event color."

3.119 Service Section Colors

3.119.1 The user configures the following colors under Service Section:

• Header Text Color: Controls the service label text color (e.g., "Photography")

• Background Color: Controls the service tag background color

3.119.2 An info icon displays tooltip on hover: "These colors apply to service labels displayed under each event. Background color affects the service tag appearance."

3.120 Item Rows Colors

3.120.1 The user configures the following color under Item Rows:

• Text Color: Controls the line item text color

3.120.2 An info icon displays tooltip on hover: "This color applies to line item text. Any A-La-Carte items linked to this package will also use this color by default."

3.121 Background Color

3.121.1 The user configures the Background Color which sets the overall package display background.

3.121.2 An info icon displays tooltip on hover: "This color sets the overall background for the package display. Event and service section background colors are not affected by this setting."

3.122 System Button Color

3.122.1 The user configures the Button Color which controls the "Select" button appearance.

3.122.2 An info icon displays tooltip on hover: "This color applies to the system-generated 'Select' button in the package preview. This button style is not individually configurable within the builder."

Configuring Package Font Styling

3.123 The user clicks the "Fonts" tab in the left sidebar of the Package Builder.

3.124 The system displays the Font Styling panel with configurable font options for the package group.

3.125 The Font Styling panel displays the following sections: Event Heading, Service Heading, and Body Text.

3.126 All font changes are auto-saved and apply to ALL packages within the package group (group-level setting).

3.127 Event Heading Font

3.127.1 The user clicks the Font dropdown under Event Heading.

3.127.2 The system displays available font style options.

3.127.3 The user selects a font style for event headings (e.g., "WEDDING", "REHEARSAL DINNER"). Default: Sans Serif.

3.128 Service Heading Font

3.128.1 The user clicks the Font dropdown under Service Heading.

3.128.2 The system displays available font style options.

3.128.3 The user selects a font style for service headings (e.g., "Photography", "Videography"). Default: Sans Serif.

3.129 Body Text Font

3.129.1 The user views the Body Text section with an info icon.

3.129.2 An info icon displays tooltip on hover: "This font will be used for the Event Description and all Line Items."

3.129.3 The user clicks the Font Family dropdown under Body Text.

3.129.4 The system displays available font family options.

3.129.5 The user selects a font family for body text, event descriptions, and line items. Default: Sans Serif.

3.130 Package Area heading (package name) and price default to Sans Serif and are not configurable in this panel.

4. FUNCTIONAL LOGIC

4.1 Package Builder Initialization

• When the Package Builder loads from the Package List View edit action or after wizard completion, the system retrieves the package group ID from the URL path (/packages/builder/{group_id}).

• The system validates that the package group exists in the database and belongs to the current user's agency.

• The system validates that the user has appropriate permissions based on their role and the agency's configuration settings.

• The system fetches all packages within the group including their names, descriptions, images, prices, tax modes, events, services, line items, and A-La-Carte links.

• The system loads the Package Builder interface with three main sections: left sidebar for package list, center canvas for package details, and right panel for Package Settings.

• The system displays all packages in the left sidebar with settings icons next to each package name.

• The system auto-selects the first package in the list and displays its full details in the center canvas.

• The system displays a status badge (Draft or Published) near the package name indicating the current publication status.

• The top action bar displays the Preview button, Settings button, and Publish/Republish button.

• The Package Settings panel on the right displays the General tab by default showing the selected package's configuration options.

• If the package group name exceeds the available display width, the system displays a tooltip on hover showing the full group name.

4.2 Package Selection and Navigation

• When the user clicks a different package in the left sidebar, the system first auto-saves any pending changes to the currently displayed package.

• The system then loads the selected package's data into the center canvas including all events, services, and line items.

• The system updates the Package Settings panel to reflect the newly selected package's details.

• The system visually highlights the selected package in the sidebar with an active state indicator (e.g., background color change or border).

• Users can edit multiple packages in sequence without closing or reloading the Package Builder.

• The expand/collapse state of packages in the sidebar persists during the editing session.

• When the user clicks a package card, the center canvas becomes editable for that selected package.

• Users can directly select any field on the canvas (e.g., cover photo, package name, price, description, events, line items) and type to edit.

• The system simultaneously opens the Package Settings panel on the right, allowing users to edit package details from either the canvas or the settings panel.

• The system visually highlights the selected package card with an active state indicator (e.g., background color change or border).

• Any changes made on the canvas are reflected in the Package Settings panel and vice versa (real-time sync).

• Users can switch between packages by clicking different package cards; the system auto-saves any pending changes before loading the newly selected package.

• Users can edit multiple packages in sequence without closing or reloading the Package Builder.

4.3 Package Header Configuration

• The package name field supports inline editing with a maximum length of 100 characters.

• The system trims leading and trailing whitespace from the package name before validation and storage.

• The package name must not be empty; if empty, the system displays the error message "Package name is required."

• The package name must be unique within the package group; if a duplicate exists (case-insensitive), the system displays the error message "Package name already exists within this group."

• All package name changes are auto-saved to draft status immediately after validation passes.

• Package name changes do not affect existing proposals; proposals retain the original name from their snapshot.

• The package description field uses a rich text editor supporting formatting options including bold, italic, underline, bullet lists, numbered lists, and headers (H1, H2, H3).

• The package description has a maximum length of 5000 characters and is auto-saved to draft.

• The package description is optional and not required for publishing.

• The package image accepts only JPG and PNG file formats with a maximum file size of 15MB.

• When the user uploads an image, the system opens a crop tool with aspect ratio options (16:9, 4:3, 1:1).

• After cropping, the system uploads the image to file storage (AWS S3 or similar) and saves the image reference to the package record.

• The package image is optional and not required for publishing.

• If image upload fails due to invalid format or size, the system displays the error toast: "Image upload failed. File must be JPG or PNG and under 15MB."

• The package price field accepts numeric values only with currency formatting.

• The package price must be at least $5 or positive with two decimal; negative values display the error message "Price must be a positive number."

• The package price is required for publishing; if not set, the system blocks publish with appropriate error messaging.

4.4 Line Item Types and Configuration

• Line items are categorized into two types: Custom and Smart Field.

• Custom line items allow users to enter any text as the line item name with a maximum of 250 characters.

• Smart Field line items use predefined system fields that map to proposals, contracts, and projects.

• The system provides 9 predefined Smart Fields: Hours of Coverage, Number of Edited Images, Number of Photographers, Number of Videographers, Number of Content Creators, Number of Drone Operators, Number of Assistants.

• When a user selects a Smart Field type, the system displays a secondary mandatory field for entering the associated value.

• For "Hours of Coverage", the secondary field captures the number of hours (e.g., 8 hours).

• For "Number of Edited Images", the secondary field captures the image count (e.g., 200 images).

• For "Number of Photographers", "Number of Videographers", "Number of Content Creators", "Number of Drone Operators", and "Number of Assistants", the secondary field captures the crew count.

• For all crew count Smart Fields, the secondary field minimum value is 1. Entering 0 displays the error: "Value must be at least 1."

• For crew count Smart Fields, if the value is greater than 1, the system will assign 1 as lead shooter and the rest as second shooters when the package is used in a project (e.g., 3 Videographers = 1 lead + 2 second shooters).

• The secondary Smart Field value is required when Smart Field type is selected; validation prevents saving without this value.

4.5 Line Item Scope and Event Association

• Line items are added to specific event service sections within the package (e.g., Wedding > Photography, Rehearsal Dinner > Videography).

• When the user hovers over a line item slot within an event's service section, the system displays a "+" icon indicating the ability to add a new line item.

• Clicking the "+" icon opens the Line Item Settings panel pre-configured for that specific event and service context.

• Each line item belongs to exactly one event's service section and cannot span multiple events or services.

• Line items within the same event's service section can be reordered via drag-and-drop functionality.

• Drag-and-drop reordering is restricted to within the same event's service section; line items cannot be moved across different events or services.

• Line item order is preserved when the package is used in proposals and projects.

4.6 Line Item Quantity Configuration

• Every line item requires a quantity value with a default of 1.

• The quantity field accepts numeric values with a maximum of 3 digits (range: 1 to 999).

• The quantity value is for display and informational purposes only; it does not affect package pricing calculations.

• The quantity field must not be empty; if empty, the system displays the error message "Quantity is required."

• The default tax mode for all new packages is "Not taxable". Users can change the tax mode from the Package Settings panel.

4.7 Deliverable Configuration and Due Dates

• Each line item has a Deliverable toggle that determines whether the item is tracked in the Post-Production module after the event.

• When the Deliverable toggle is ON, the system displays due date configuration fields.

• The due date configuration consists of two fields: a value field (dropdown with numeric options 1-99 and "No Due Date") and a unit field (dropdown with Days, Weeks, Months).

• The due date value accepts a maximum of 2 digits (range: 1 to 99) or the special option "No Due Date".

• If Deliverable is ON AND the Due Date Value is empty, show error message: "Deliverable due date value is required." Block user from proceeding to the next step.

• If the user selects "No Due Date", the Deliverable toggle remains ON but the system does not calculate a specific due date; the deliverable appears in Post-Production without a deadline.

• The due date calculation formula is: Event Date + Value + Unit (e.g., Wedding Date + 10 Days = Due Date).

• For packages with multiple events, the due date calculation uses the specific event date associated with the line item's event section.

• Deliverable line items are automatically added to the Post-Production board when the proposal is signed and converted to a project.

• The Post-Production task name is derived from the line item name, and the due date is calculated based on the configured rule.

4.8 Tax Mode Configuration

• The Package Builder supports three tax modes: "Not taxable" (Entire Package Non-Taxable), "Tax entire package" (Entire Package Taxable), and "Tax specific line items" (Line Item Based Tax).

• When "Not taxable" is selected, no tax is calculated for the package and all line item taxable toggles are disabled (grayed out).

• When "Tax entire package" is selected, tax is calculated on the full package price and all line item taxable toggles are disabled (grayed out).

• When "Tax specific line items" is selected, each line item has an individual Taxable toggle and Price of Line Item field.

• If a line item's Taxable toggle is ON, the user must enter a Price of Line Item value for tax calculation purposes.

• The line item price is used only for tax calculation; it does not automatically affect the overall package price.

• When switching from "Tax specific line items" to another tax mode, the system displays a confirmation modal warning that all line item tax toggles and amounts will be cleared.

• If the user confirms the tax mode change, the system disables all line item taxable toggles and clears all line item tax amounts.

• Tax mode changes are auto-saved to draft status.

4.9 Smart Field Behavior and Mapping

• Smart Fields capture dynamic data that is mapped to multiple system components including proposals, contracts, and projects.

• When a package with Smart Fields is added to a proposal, the Proposal Builder displays the Smart Field values as editable fields allowing customization.

• Clients or agency users can modify Smart Field values during proposal customization to adjust coverage hours, image counts, or crew assignments.

• When a proposal is signed and converted to a project, the system extracts Smart Field values and maps them to project details.

• Hours of Coverage maps to project schedule and contractor time assignments.

• Number of Edited Images maps to deliverable quantities in the Post-Production module.

• Crew count Smart Fields (Photographers, Videographers, Content Creators, Drone Operators, Assistants) map to contractor assignment logic.

• For crew counts greater than 1, the system automatically designates 1 as lead shooter and the remainder as second shooters.

• Smart Field data is used for automation triggers including reminders, task creation, and workflow progression.

4.10 A-La-Carte Item Linkage

• The Package Builder allows linking A-La-Carte items to packages for client customization options during proposal selection.

• A-La-Carte items are created and managed in the A La Carte module (FRD #6 and #7) and linked to packages through the Package Builder.

• The A La Carte tab in the Package Settings panel is organized by event. Each configured event is shown as a collapsible row with a "+ Add A La Carte Items" button beneath it, allowing items to be assigned per event.

• Empty state — no events configured: When the A La Carte tab is opened for a package that has zero events configured, the system does not render any event rows or "+ Add A La Carte Items" button. Instead, it displays the empty-state message: "This package has no events configured yet. Add events and services to this package first before assigning A La Carte items." This message is centered within the A La Carte tab content area and is informational only (no CTA button).

• The empty-state evaluation occurs when the A La Carte tab is opened (or when the package selection changes while the tab is open). The system checks the count of events configured on the selected package: if the count is zero, the empty-state message is shown; otherwise the event list is shown.

• The "Assign A La Carte Items +" link on each package card and the A La Carte tab remain enabled for all packages regardless of event configuration. No package is visually disabled or greyed out for lacking events; the user is guided through the empty-state message after the drawer opens rather than being blocked from opening it.

• Once the user adds at least one event to the package (via the General tab / "Edit Events and Services" modal or directly on the canvas) and reopens the A La Carte tab, the empty-state message is replaced by the event list with "+ Add A La Carte Items" buttons.

• The A-La-Carte assignment modal (opened from "+ Add A La Carte Items") displays two tabs: "Add-on" (for Simple Add-on items) and "Event" (for Event-Creation Add-on items).

• The "Add-on" tab shows two categories: Custom Items (user-created add-ons) and Smart Items (Smart Field-based add-ons that allow client quantity selection).

• Smart Items in A-La-Carte include: Additional Hours Coverage, Additional Photographer, Additional Videographer, Additional Content Creator, Assistant, and Drone Operator.

• The "Event" tab shows Event-Creation Add-on items that generate new project events when selected by the client (e.g., Engagement Shoot, Elopement).

• Users can select multiple items using checkboxes and click "Assign" to link them to the package.

• A-La-Carte items are filtered by brand to show only items belonging to the same brand as the package group.

• Linked A-La-Carte items appear in the package's A La Carte tab in the Package Settings panel.

• Users can unlink A-La-Carte items by clicking the "X" icon next to the item; this removes the link but does not delete the A-La-Carte item itself.

• When a package with linked A-La-Carte items is used in a proposal, the items appear as optional add-ons that clients can select.

• If "Customer Can Select Quantity" was enabled for an A-La-Carte item, clients can choose quantities (typically 1-10).

• Selected A-La-Carte item prices are added to the total proposal amount dynamically.

• Empty state — no items for brand (within the assignment modal): If events exist but no A-La-Carte items exist for the package's brand, the assignment modal displays the empty state: "No A-La-Carte items found for this brand. Create items in the A-La-Carte module to assign them here." (This is distinct from the no-events empty state on the A La Carte tab described above.)

4.11 Edit Events and Services

• Users with the Owner or Admin role can modify the event and service structure of a package through the "Edit Events and Services" modal.

• The modal displays all events in the package with their assigned services.

• Users can change an event type by selecting a different option from the event dropdown.

• Users can add new events by clicking "+ Add New Event Type" and selecting from the Event Types Master Data.

• Users can remove services from an event by clicking the delete icon next to a service. The delete icon is disabled and visually greyed out when only one service exists for the event, preventing removal of the last service.

• Users can add services to an event by clicking the "+" icon next to the service list and selecting from available service types.

• Users can remove events by clicking the delete icon next to an event. The delete icon is disabled and visually greyed out when only one event exists, preventing removal of the last event.

• Validation requires at least one event to exist and each event to have at least one service.

• When the user clicks "Proceed to Builder", the system saves the changes to draft and updates the center canvas to reflect the new structure.

• Removing an event permanently deletes all line items associated with that event's service sections. Similarly, removing a service from an event permanently deletes all line items under that service. The system does not retain or reassign orphaned line items.

• Adding the first event to a package that previously had none enables A-La-Carte assignment for that package: the A La Carte tab transitions from the no-events empty state (Section 4.10) to the event list with "+ Add A La Carte Items" buttons.

4.12 Group Settings Configuration

• The Group Settings panel is accessible by clicking the settings icon next to the package group name.

• Group Settings displays three fields: Group Name (editable), Number of Packages (editable dropdown 1-6), and Brand (read-only).

• The Brand field is permanently locked after the Package Group Creation wizard is completed and cannot be modified in the Package Builder.

• Users can edit the Group Name with the same validation rules as during creation (not empty, unique within brand, max 100 characters).

• Users can increase the Number of Packages to add new empty package slots to the group (maximum 6 packages per group).

• The new package card appears and it requires manual configuration of events and services. Until events are configured, the newly added package's A La Carte tab shows the no-events empty state (Section 4.10).

• Users cannot decrease the number of packages from Group Settings. The Number of Packages dropdown only allows selecting a value equal to or greater than the current package count. To remove a package, users must delete it directly from the Package Builder using the delete icon on the individual package card.

• When deleting the package from the card, the system displays a confirmation modal: "Are you sure you want to delete [Package Name]? All package configurations will be permanently removed." The modal includes two action buttons: "Cancel" to dismiss and "Delete" to confirm deletion.

• If confirmed, the system permanently deletes the selected package(s) and all associated line items, deliverables, and A-La-Carte links.

4.13 Draft and Auto-Save Behavior

• All changes made in the Package Builder are automatically saved to draft status without requiring manual save actions.

• Auto-save triggers include: field value changes (on blur), line item additions/edits/deletions, A-La-Carte link changes, tax mode changes, event/service modifications, and group settings changes.

• Draft packages are not available for use in proposals; only published packages appear in the Proposal Builder.

• Draft packages appear in the Package List View with a "Draft" badge or label indicating they require publishing.

• Users can close the Package Builder at any time; all changes are preserved in draft status.

• When returning to edit a draft package, all previously saved draft data is loaded.

• When a published package has unpublished draft changes, the system displays an alert banner at the top of the Package Builder canvas area.

• The banner displays a warning icon (yellow) and the message: "Unpublished changes detected. Publish to update proposals with your latest edits." A "Publish Changes" button is displayed on the right side of the banner.

• Clicking "Publish Changes" triggers the standard publish validation and workflow.

• The banner is hidden when the package is in Draft status (never published) or when no changes exist since the last publish. The banner remains visible across package switches within the same group if any package has unpublished changes.

4.14 Publish and Republish Workflow

• The Publish button is located in the top right area of the Package Builder interface.

• Clicking Publish triggers validation of all mandatory fields before changing the package status.

• Mandatory fields for publishing include: Package Name (not empty), Package Price (set and non-negative), and at least one line item in each event's service section.

• If validation fails, the system displays an error toast: "Publish blocked — complete all mandatory fields" and highlights the fields or sections that are incomplete.

• If validation passes, the system changes the package status from Draft to Published and displays a success toast: "Package published successfully."

• Published packages become available in the Proposal Builder for selection when creating new proposals.

• After initial publishing, the Publish button changes to "Republish" for subsequent edits.

• When a user edits a published package, all changes are saved to draft without affecting the published version or existing proposals.

• Clicking Republish validates and publishes the updated version, making it available for new proposals.

• The success toast for republishing states: "Package published successfully. Future proposals will use the updated version."

• Once a package has been published, it remains available in the Proposal Builder as its last published version even while draft edits are in progress. The Proposal Builder always uses the last published snapshot, never the draft state.

4.15 Version Control and Snapshot Protection

• The system uses snapshot-based protection rather than maintaining multiple package versions.

• When a proposal is created using a package, the system saves a complete snapshot of the package configuration at that moment.

• The snapshot includes: package name, description, image, price, tax mode, all events and services, all line items with their full configuration, and all A-La-Carte links.

• Editing and republishing a package does NOT update existing proposal snapshots.

• Proposals that were created before an edit retain their original snapshot and display the original package configuration.

• Projects created from signed proposals also retain the snapshot and are not affected by subsequent package edits.

• This ensures data integrity and prevents retroactive changes to active client proposals or projects.

• All package edits are logged in the system's activity/audit log including: timestamp, user who made the change, field changed, old value, and new value.

4.16 Package Duplication Within Builder

• Users with the Owner or Admin role can duplicate a package using the three-dot kebab menu, available both in the Package Listing and within the Package Group.

• Duplicating a package creates a full copy including: package name, description, image reference, price, tax mode, all line items with their complete configuration, and all A-La-Carte links.

• The duplicate package name follows these rules:

• First duplicate of "Advanced Photography" → "Copy of Advanced Photography"

• Second duplicate of "Advanced Photography" → "Copy of Advanced Photography (1)"

• Third duplicate → "Copy of Advanced Photography (2)", and so on.

• If "Copy of Advanced Photography (1)" is duplicated, the system creates "Copy of Advanced Photography (2)" by incrementing the highest existing number.

• The duplicated package is added to the package group and increments the group's package count (e.g., from 3 to 4).

• Duplication is blocked if the group already has the maximum of 6 packages; the system displays an error toast: "Cannot duplicate package. Group already has the maximum number of packages (6)."

• The duplicated package is saved with Draft status regardless of the source package's status.

• After duplication, the system displays the duplicated package in the listing for the user to edit.

• A success toast is displayed: "Package duplicated successfully."

4.17 Package Status Badge Display

• The Package Builder displays a status badge near the package name indicating the current publication status of each package.

• The status badge shows "Draft" for packages that have not yet been published or have unpublished changes pending.

• The status badge shows "Published" for packages that have been published and are available for use in proposals.

• When a published package is edited, the status badge may show "Draft" or "Changes Pending" to indicate unpublished modifications exist.

• The status badge updates automatically when the user publishes or republishes a package.

• The status badge provides visual clarity to users about which packages are ready for proposal use and which require publishing.

4.18 Package Preview Functionality

• The Preview button is located in the top action bar of the Package Builder interface.

• Clicking the Preview button opens a preview page within the same browser tab (not a new tab).

• The preview displays all packages in the package group as they would appear to clients viewing a proposal.

• The preview shows package images, names, descriptions, prices, and included line items in a client-facing format.

• By default, the preview displays up to 3 packages side by side in a horizontal layout.

• If the package group contains more than 3 packages, left and right navigation arrows appear to allow scrolling through additional packages.

• Users can click the navigation arrows to move between packages in the preview carousel.

• The preview page includes a close button (X) in the top-right corner to exit preview mode.

• Preview can only be closed via the X button. Clicking outside the overlay does not close the preview.

• The preview reflects the current state of packages including any unsaved draft changes.

• Preview is available to all users who have access to the Package Builder regardless of their publish permissions.

4.19 Single-Service Brand Handling in Package Builder

• When the Package Builder loads, the system checks the number of services configured under the package group's brand.

• If the brand has exactly one service configured:

• The center canvas displays event sections without service type sub-headers. Line item slots appear directly beneath each event header.

• The "+" icon for adding line items appears directly under the event header. Line items added are automatically associated with the single available service in the background.

• The "Edit Events and Services" modal does not display service selection options. The service column or service add/remove controls are hidden. Only event management is available (if applicable — see Section 4.20).

• When a new event is added (if the brand has multiple event types), the single service is auto-assigned to it.

• Existing line items retain their service association. The service data is preserved in the database — it is simply not displayed in the UI.

4.20 Single-Event Brand Handling in Package Builder

• When the Package Builder loads, the system checks the number of event types configured under the package group's brand.

• If the brand has exactly one event type configured:

• The "Edit Events and Services" button in the Package Settings panel is hidden entirely.

• The center canvas displays the single event header with services (or line items directly, if also a single-service brand) beneath it.

• Users cannot add, remove, or change events from the Package Builder. The single event is locked.

• When duplicating a package within the group, the duplicated package retains the same single event assignment.

• Group Settings still allows changing the Number of Packages — new packages are auto-assigned the single event type. (Because the single event is auto-assigned, newly added packages in single-event brands will have an event present and therefore will not show the no-events A La Carte empty state.)

• If the brand has exactly one event type AND one service configured:

• Both event and service UI elements are simplified. The center canvas shows only the package header fields (name, description, price, image) and line item slots with no event/service grouping visible.

• The "Edit Events and Services" button is hidden.

• All line items are automatically associated with the single event and single service in the background.

4.21 Tax Warning on Publish Without Taxable Line Items

• When the user clicks "Publish" or "Republish" and the package's tax mode is set to "Tax specific line items," the system performs an additional check after standard validation passes.

• The system scans all line items across all event/service sections to determine whether at least one line item has the Taxable toggle set to ON.

• If no line items have Taxable set to ON:

• The system displays a warning modal with the title "No Taxable Items" and the message: "You've selected line item based tax but haven't marked any line items as taxable. Do you want to continue publishing without any taxable items?"

• The modal includes two buttons: "Go Back" (secondary) and "Continue" (primary).

• If the user clicks "Continue," the system proceeds with publishing. The package is published with "Tax specific line items" mode but zero taxable items — effectively resulting in no tax being applied.

• If the user clicks "Go Back," the modal closes and the user returns to the Package Builder. No publish action occurs.

• This warning is non-blocking and does not prevent publishing. It serves as a safety check to catch unintentional tax misconfiguration.

4.22 Taxable Toggle and Price of Line Item Visibility

• When the tax mode is "Tax specific line items," each line item in the Line Item Settings panel displays a Taxable toggle.

• When the Taxable toggle is OFF:

• The "Price of Line Item" field is hidden from the UI.

• No tax-related data is stored for the line item.

• When the Taxable toggle is switched ON:

• The "Price of Line Item" field appears immediately below the toggle.

• The field is required — the user must enter a numeric value ≥ 0.

• If the user switches the toggle back to OFF, the "Price of Line Item" field is hidden and its value is cleared.

4.23 Line Item Price Exceeds Package Price Warning

• When the tax mode is "Tax specific line items" and the user enters or updates the Price of Line Item field, the system compares the entered value against the current Package Price.

• If the line item price is greater than the package price, the system displays a non-blocking warning message: "The line item price exceeds the total package price. Please verify the amount."

• The warning is displayed inline below the Price of Line Item field or as a warning toast.

• This validation is triggered on field blur (when the user clicks or tabs out of the Price of Line Item field) and also when the user updates the Package Price to a value lower than any existing line item price.

• The warning does not prevent saving the line item or publishing the package. It serves as an informational alert to help users catch potential data entry errors.

• If the Package Price has not been set yet (field is empty), this comparison is skipped and no warning is shown.

4.24 Save as Preset for Line Items

• The Line Item Settings panel includes a "Save as preset" toggle located below the line item configuration fields.

• The toggle is OFF by default for all new line items.

• An info icon (ℹ️) is displayed next to the toggle. On hover or click, the system displays a tooltip: "Turn this on to save these settings as a preset. It will appear in the Add Deliverable list when manually adding deliverables."

• When the user toggles "Save as preset" to ON and saves the line item, the system saves the complete line item configuration as a reusable preset.

• Saved presets are available in the Add Deliverable list when manually adding deliverables in other modules (e.g., Post-Production).

• The preset saves all line item settings including: type (Custom/Smart Field), name, description, deliverable toggle state, due date configuration, taxable toggle, and price of line item (if applicable).

4.25 Color Styling Configuration

• Color styling is a group-level setting that applies uniformly to all packages within the package group. Individual packages cannot have different color configurations.

• The Colors tab in the left sidebar provides access to all color customization options. Changes are reflected in real-time in the right panel preview and are auto-saved.

4.25.1 Color Settings Scope

• All color settings apply to the entire package group, not individual packages.

• When colors are changed, all packages within the group inherit the same styling.

• Color changes are auto-saved and do not require manual save action.

4.25.2 Package Area Colors

• Header Text Color: Controls the color of the package name displayed on the package card. Default: Black (#000000).

• Price Color: Controls the color of the price text displayed on the package card. Default: Black (#000000).

• Body Text Color: Controls the color of the package description text. Default: Black (#000000).

4.25.3 Event Section Colors

• Header Text Color: Controls the color of event header text (e.g., "WEDDING", "REHEARSAL DINNER"). Default: Black (#000000).

• Border Color: Controls the border color of the event section container. Default: Light Gray.

• Event background color is NOT configurable here; it is inherited from the brand's event color settings configured in Brand Master Data.

4.25.4 Service Section Colors

• Header Text Color: Controls the color of service label text (e.g., "Photography", "Videography"). Default: Black (#000000).

• Background Color: Controls the background color of the service tag/badge. Default: Light Gray.

4.25.5 Item Rows Colors

• Text Color: Controls the color of line item text displayed within service sections. Default: Black (#000000).

• This color also applies to any A-La-Carte items linked to packages in this group.

4.25.6 Background Color

• Background Color: Controls the overall background color of the package display area. Default: White (#FFFFFF).

• This setting does NOT affect event section or service section background colors, which have their own settings.

4.25.7 System Button Color

• Button Color: Controls the color of the system-generated "Select" button displayed on package cards. Default: Brand primary color or system default.

• This button style is not individually configurable per package; it applies uniformly to all packages in the group.

• The "Show Details" link styling is not affected by this setting.

4.25.8 Real-Time Preview

• As the user changes any color setting, the preview in the right panel updates in real-time.

• For an accurate client-facing preview, the user should click the "Preview" button in the top-right corner.

4.25.9 Color Persistence

• Color settings are persisted at the package group level in the database.

• There is no "Reset to Default" option; users must manually select default colors if they wish to revert.

• Color settings are included when a package group is duplicated.

4.26 Font Styling Configuration

• Font styling is a group-level setting that applies uniformly to all packages within the package group. Individual packages cannot have different font configurations.

• The Fonts tab in the left sidebar provides access to all font customization options. Changes are reflected in real-time in the preview and are auto-saved.

4.26.1 Font Settings Scope

• All font settings apply to the entire package group, not individual packages.

• When fonts are changed, all packages within the group inherit the same styling.

• Font changes are auto-saved and do not require manual save action.

4.26.2 Event Heading Font

• Font: Controls the font style of event heading text (e.g., "WEDDING", "REHEARSAL DINNER"). Default: Sans Serif.

4.26.3 Service Heading Font

• Font: Controls the font style of service heading text (e.g., "Photography", "Videography"). Default: Sans Serif.

4.26.4 Body Text Font

• Font Family: Controls the font family used for event descriptions and all line items. Default: Sans Serif.

• This font applies to: event descriptions, line item text, and A-La-Carte item text.

4.26.5 Package Area Fonts (Non-Configurable)

• Package name (heading) and price text default to Sans Serif.

• These fonts are not configurable through the Fonts panel; they use system defaults.

4.26.6 Font Persistence

• Font settings are persisted at the package group level in the database.

• Font settings are included when a package group is duplicated.

5. FIELD DETAILS & VALIDATIONS

5.1 Package Header Fields

Field Name

Field Type

Required

Max Length

Validation Rules

Package Name

Text Input

Yes (for publish)

100 chars

Cannot be empty; must be unique within package group (case-insensitive); auto-trim whitespace

Package Description

Rich Text Editor

No

5000 chars

Optional; supports bold, italic, underline, lists, headers

Package Image

File Upload

No

15 MB

Must be JPG or PNG format; max file size 15MB; crop required before save

Package Price

Numeric Input

Yes (for publish)

N/A

Must be numeric; must be ≥ $5; cannot be negative

Tax Mode

Dropdown Select

Yes

N/A

Options: Not taxable, Tax entire package, Tax specific line items; default: "Not taxable"

5.2 Line Item Fields

Field Name

Field Type

Required

Max Length

Validation Rules

Line Item Type

Dropdown Select

Yes

N/A

Options: Custom, Smart Field; must select one

Line Item Name (Custom)

Text Input

Yes (if Custom)

250 chars

Cannot be empty when Custom type selected

Smart Field Type

Dropdown Select

Yes (if Smart Field)

N/A

Options: 9 predefined smart fields; must select one when Smart Field type selected

Smart Field Value

Numeric/Boolean Input

Yes (if Smart Field)

Varies

Required secondary field; varies by smart field type (hours, count, yes/no)

Description

Text Area

No

500 chars

Optional description for the line item

Quantity

Numeric Input

Yes

3 digits

Required; default 1; range 1-999; does not affect pricing

Deliverable Toggle

Toggle Switch

No

N/A

Default OFF; enables due date fields when ON

Due Date Value

Dropdown Select

Yes (if Deliverable ON)

2 digits

Options: 1-99 or "No Due Date"; required when Deliverable is ON

Due Date Unit

Dropdown Select

Yes (if Deliverable ON)

N/A

Options: Days, Weeks, Months; required when Deliverable is ON and value is not "No Due Date"

Taxable Toggle

Toggle Switch

Conditional

N/A

Only visible when Tax Mode is "Tax specific line items"; default OFF

Price of Line Item

Numeric Input

Conditional

N/A

Required when Taxable toggle is ON; must be numeric and ≥ 0. If the entered value exceeds the Package Price, a non-blocking warning is displayed.

Smart Field Crew Count Value

Numeric Input

Yes (when crew Smart Field selected)

N/A

Minimum value 1; entering 0 displays "Value must be at least 1."

Save as Preset

Toggle Switch

No

N/A

Default: OFF; when ON, saves line item configuration as reusable preset for Add Deliverable list

Save as Preset Info Icon

Icon + Tooltip

N/A

N/A

Displays tooltip on hover: "Turn this on to save these settings as a preset. It will appear in the Add Deliverable list when manually adding deliverables."

5.3 Smart Field Types Reference

Smart Field

Secondary Field Type

Secondary Field Label

Notes

Hours of Coverage

Numeric Input

Number of hours

e.g., 8 hours

Number of Edited Images

Numeric Input

Number of images

e.g., 200 images

Number of Photographers

Numeric Input

Number of photographers

1 = lead, rest = second shooters

Number of Videographers

Numeric Input

Number of videographers

1 = lead, rest = second shooters

Number of Content Creators

Numeric Input

Number of content creators

1 = lead, rest = second shooters

Number of Drone Operators

Numeric Input

Number of drone operators

Crew count

Number of Assistants

Numeric Input

Number of assistants

Crew count

5.4 Group Settings Fields

Field Name

Field Type

Required

Validation Rules

Group Name

Text Input

Yes

Cannot be empty; max 100 chars; must be unique within brand

Number of Packages

Dropdown Select

Yes

Options: 1-6; changing value adds/removes packages

Brand

Text Display

N/A

Read-only; permanently locked after wizard completion

5.5 A-La-Carte Linkage Fields

Field Name

Field Type

Required

Validation Rules

A-La-Carte Item Selection

Multi-Select Checkboxes

No

Items filtered by brand; multiple selections allowed

Add-on Tab Items

Checkbox List

No

Custom Items and Smart Items categories

Event Tab Items

Checkbox List

No

Event-Creation Add-on items

5.6 UI Display Elements

Element Name

Type

Description

Status Badge

Badge/Label

Displays "Draft" or "Published" near package name; updates automatically on publish/republish

Preview Button

Button

Opens preview overlay; located in top action bar

Publish/Republish Button

Button

Changes from "Publish" to "Republish" after initial publication

Preview Overlay

Modal Overlay

Displays package group preview in proposal format; shows 3 packages by default

Preview Navigation Arrows

Icon Buttons

Left/right arrows for scrolling through packages; visible when more than 3 packages exist

Preview Close Button

Icon Button (X)

Closes preview overlay and returns to builder

Unpublished Changes Banner

Alert Banner

Displays warning icon + message "Unpublished changes detected. Publish to update proposals with your latest edits." + "Publish Changes" button; visible only when published package has draft edits

Group Name Tooltip

Tooltip

Displays full group name on hover when name is truncated due to length constraints

A La Carte Tab Empty State (No Events)

Inline Message

Displayed in the A La Carte tab content area when the selected package has no events configured: "This package has no events configured yet. Add events and services to this package first before assigning A La Carte items." Informational only (no CTA button).

Section 5.7 - Color Styling Fields

Field Name

Field Type

Required

Default Value

Description

Header Text Color (Package Area)

Color Picker

No

Black (#000000)

Controls package name text color

Price Color

Color Picker

No

Black (#000000)

Controls price display text color

Body Text Color

Color Picker

No

Black (#000000)

Controls description text color

Header Text Color (Event Section)

Color Picker

No

Black (#000000)

Controls event header text color

Border Color (Event Section)

Color Picker

No

Light Gray

Controls event section border color

Header Text Color (Service Section)

Color Picker

No

Black (#000000)

Controls service label text color

Background Color (Service Section)

Color Picker

No

Light Gray

Controls service tag background color

Text Color (Item Rows)

Color Picker

No

Black (#000000)

Controls line item text color; applies to A-La-Carte items

Background Color

Color Picker

No

White (#FFFFFF)

Controls overall package display background

Button Color

Color Picker

No

Brand primary or system default

Controls "Select" button color

5.8 Color Styling Tooltips

Section

Tooltip Content

Colors Tab Header

The right panel reflects color updates in real-time as you edit. To see exactly how clients will view your package, click 'Preview' in the top-right corner.

Package Area

These colors apply to the main package card: the package name, price display, and description text.

Event Section

These colors apply to event headers within the package. Note: Event background color is inherited from your brand's event color.

Service Section

These colors apply to service labels displayed under each event. Background color affects the service tag appearance.

Item Rows

This color applies to line item text. Any A-La-Carte items linked to this package will also use this color by default.

Background

This color sets the overall background for the package display. Event and service section background colors are not affected by this setting.

System Button Color

This color applies to the system-generated 'Select' button in the package preview. This button style is not individually configurable within the builder.

5.9 Font Styling Fields

Field Name

Field Type

Required

Default Value

Description

Event Heading Font

Dropdown

No

Sans Serif

Controls font style for event headings (e.g., "WEDDING")

Service Heading Font

Dropdown

No

Sans Serif

Controls font style for service headings (e.g., "Photography")

Body Text Font Family

Dropdown

No

Sans Serif

Controls font family for event descriptions and all line items

5.10 Font Styling Tooltips

Section

Tooltip Content

Body Text

This font will be used for the Event Description and all Line Items.

6. SUCCESS MESSAGE HANDLING

Validation Scenario

Success Message

Display Type

Post-Success Action

Package published successfully

"Package published successfully."

Toast (green, below)

Package available in Proposal Builder; Publish button changes to Republish

Package republished successfully

"Package published successfully."

Toast (green, below)

Updated package available for new proposals; existing proposals unchanged

Line item added successfully

No explicit message

Visual feedback - item appears in canvas

Line item saved to draft; user can continue editing

Line item updated successfully

No explicit message

Visual feedback - changes reflected in canvas

Changes saved to draft

Line item deleted successfully

"Line item deleted successfully."

Toast (green, below)

Line item removed from canvas; draft updated

A-La-Carte items assigned

"A-La-Carte items assigned successfully."

Toast (green, below)

Items appear in A La Carte tab; saved to draft

A-La-Carte item unlinked

No explicit message

Visual feedback - item removed from list

Link removed; draft updated

Package duplicated successfully

"Package duplicated successfully."

Toast (green, below)

New package in sidebar; auto-selected for editing

Events and services updated

"Events and services updated successfully."

Toast (green, below)

Canvas refreshes with new structure

Package removed from group

"Package removed successfully."

Toast (green, below)

Package removed from sidebar; count updated

Auto-save completed

No explicit message or small "Saved" indicator

Brief visual indicator (optional)

Changes persisted to draft

Image uploaded successfully

No explicit message

Visual feedback - thumbnail displayed

Image saved to package record

Publish Tax Warning

Tax mode is "Tax specific line items" but no line items have taxable ON

"You have selected line item based tax but have not marked any line items as taxable. Do you want to continue publishing without taxable items?"

Warning modal (non-blocking) with "Go Back" and "Continue" buttons

Line item price exceeds package price

"The line item price exceeds the total package price. Please verify the amount."

Inline warning below field or warning toast

Non-blocking; user can proceed with saving

7. ERROR MESSAGE HANDLING

Field

Validation Scenario

Error Message

Display Type

Package Name

Field is empty

"Package name is required."

Toast error message below; warning icon on package card (hover to view message)

Package Name

Duplicate name in group

"Package name already exists within this group."

Toast error message below; warning icon on package card (hover to view message)

Package Name

Exceeds max length

"Package name cannot exceed 100 characters."

Toast error message below; warning icon on package card (hover to view message)

Package Price

Field is empty (at publish)

"Package price is required."

Toast error message below; warning icon on package card (hover to view message)

Package Price

Negative value entered

"Price must be a positive number."

Toast error message below; warning icon on package card (hover to view message)

Package Image

Invalid file format

"Image upload failed. File must be JPG or PNG and under 15MB."

Toast error message below; warning icon on package card (hover to view message)

Package Image

File size exceeds 15MB

"Image upload failed. File must be JPG or PNG and under 15MB."

Toast error message below; warning icon on package card (hover to view message)

Line Item Name

Field is empty (Custom type)

"Line item name is required."

Toast error message below; warning icon on package card (hover to view message)

Line Item Name

Exceeds max length

"Line item name cannot exceed 250 characters."

Toast error message below; warning icon on package card (hover to view message)

Smart Field Type

Not selected (Smart Field type)

"Smart field type is required."

Toast error message below; warning icon on package card (hover to view message)

Smart Field Value

Not entered (Smart Field type)

"Smart field value is required."

Toast error message below; warning icon on package card (hover to view message)

Quantity

Field is empty

"Quantity is required."

Toast error message below; warning icon on package card (hover to view message)

Quantity

Exceeds 3 digits

"Quantity cannot exceed 999."

Toast error message below; warning icon on package card (hover to view message)

Due Date Value

Not selected (Deliverable ON)

"Deliverable due date value is required."

Toast error message below; warning icon on package card (hover to view message)

Due Date Unit

Not selected (Deliverable ON, value set)

"Deliverable due date unit is required."

Toast error message below; warning icon on package card (hover to view message)

Taxable Amount

Not entered (Taxable ON)

"Taxable amount is required."

Toast error message below; warning icon on package card (hover to view message)

Line Item Price

Not entered (Taxable ON)

"Line item price is required."

Toast error message below; warning icon on package card (hover to view message)

Publish Validation

Missing mandatory fields

"Publish blocked — complete all mandatory fields."

Toast error message; warning icon on package card (hover to view message)

Publish Validation

No line items in event's service

"At least one line item is required in each event's service section."

Toast error message; warning icon on package card (hover to view message)

Duplicate Package

Group at maximum (6)

"Cannot duplicate package. Group already has the maximum number of packages (6)."

Toast error message

Edit Events

No events remaining

"At least one event is required."

Toast error message

Edit Events

No services for event

"Each event must have at least one service."

Toast error message

Auto-Save

Save failed

"Failed to save your changes. Please check your connection and try again."

Toast error message

Load Package

Failed to load

"Failed to load package. Please try again."

Toast error message

Tax Mode Change

Confirmation required

Modal: "Switching tax mode will clear line item tax settings. Continue?"

Confirmation modal

Remove Package

Confirmation required

Modal: "Reducing the number of packages will permanently delete Package [N]. Continue?"

Confirmation modal

Smart Field Crew Count

Value is 0

"Value must be at least 1."

Inline error below field

A La Carte Tab (No Events)

Package has no events configured when A La Carte tab is opened

Empty state: "This package has no events configured yet. Add events and services to this package first before assigning A La Carte items."

Inline message in A La Carte tab content area (centered); informational, non-blocking

A-La-Carte Assignment

No items exist for brand

Empty state: "No A-La-Carte items found for this brand. Create items in the A-La-Carte module to assign them here."

Displayed in modal

8. EDGE CASES

Scenario

Expected Behavior

User switches tax mode after setting line item taxes

System displays confirmation modal; if confirmed, all line item tax toggles disabled and amounts cleared

User deletes event that has line items

System allows deletion; deleting the event also removes all associated line items permanently.

User uploads image larger than 15MB

System rejects upload; displays error toast; user must compress or choose different image

User attempts to publish without line items

System blocks publish; displays error highlighting event/service sections needing line items

User duplicates package when group has 6 packages

System blocks duplication; displays error toast about maximum package limit

User edits published package used in multiple proposals

System allows edits; changes saved to draft; old proposals retain original snapshots; user must republish

User toggles Deliverable ON without setting due date

System allows saving with "No Due Date" option; deliverable tracked without specific deadline

Smart Field selected but value not entered

System blocks save; displays error requiring smart field value entry

Brand deleted after package created

Package remains accessible; brand displays as "Archived Brand"; package may become read-only

User attempts to remove all events from package

System blocks action; at least one event required; error displayed

User attempts to remove all services from event

System blocks action; each event requires at least one service; error displayed

User drags line item to different event section

System does not allow cross-event drag; drag-drop restricted to same event's service section

User enters 4-digit quantity

System blocks entry; maximum 3 digits (999) allowed

User enters due date value > 99

System limits dropdown to 2 digits; values 1-99 only

Network connection lost during editing

System displays error on next auto-save attempt; user can retry when connection restored

User closes browser without publishing

All draft changes preserved; user can resume editing later

Multiple users edit same package simultaneously

Last save wins; system does not support real-time collaboration

Smart Field with crew count > 1

System will assign 1 lead shooter and rest as second shooters in project

User unlinks A-La-Carte item used in proposal

Package updated; existing proposals retain original snapshot with item linked

User adds a new package via Group Settings, then opens its A La Carte tab before configuring events

Package Settings drawer opens with A La Carte tab selected; system displays empty state: "This package has no events configured yet. Add events and services to this package first before assigning A La Carte items." No "+ Add A La Carte Items" button is shown.

User clicks "Assign A La Carte Items +" on a package card that has no events

Right drawer opens to the A La Carte tab and displays the no-events empty-state message; the card link is not disabled or greyed out

User configures the first event on a package that previously showed the no-events empty state, then reopens the A La Carte tab

A La Carte tab now lists the event with a "+ Add A La Carte Items" button; the empty-state message no longer appears

User removes all events from a package that previously had events and A-La-Carte items assigned

Removing events deletes their line items; the A La Carte tab reverts to the no-events empty state and previously linked items are no longer assignable until an event is re-added

User duplicates a package that has no events configured

The duplicated package also has no events; opening its A La Carte tab shows the no-events empty-state message

User opens Preview with incomplete packages

Preview displays all packages including incomplete ones; incomplete fields show placeholders or empty states

User opens Preview with only 1 package

Preview displays single package centered; no navigation arrows shown

User opens Preview with exactly 3 packages

Preview displays all 3 packages; no navigation arrows needed

User opens Preview with more than 3 packages

Preview displays first 3 packages; navigation arrows appear for scrolling

User clicks outside Preview overlay

Preview remains open; user must click X button to close

Network error while loading Preview

System displays error message; user can retry or close preview

User duplicates "Advanced Photography" multiple times

First duplicate: "Copy of Advanced Photography"; Second: "Copy of Advanced Photography (1)"; Third: "Copy of Advanced Photography (2)"

User enters 0 for crew count Smart Field

System displays error "Value must be at least 1" and blocks save

User opens A-La-Carte assignment modal but brand has no items

Modal displays empty state: "No A-La-Carte items found for this brand. Create items in the A-La-Carte module to assign them here."

User changes colors and exits without clicking Save

Colors are auto-saved; changes persist

User duplicates package group

Duplicated group inherits all color settings from original

User wants to reset colors to default

No reset option available; user must manually select default color values

Event background color appears different than expected

Event background color is inherited from brand's event color settings, not configurable in Package Builder

Color changes don't appear in preview

User should click "Preview" button to see accurate client-facing view; right panel shows real-time updates but may differ slightly

A-La-Carte item linked to package

Item inherits Item Rows text color from the package group's color settings

User changes fonts and exits without clicking Save

Fonts are auto-saved; changes persist

User duplicates package group (fonts)

Duplicated group inherits all font settings from original

User wants to change package name or price font

Not configurable; these default to Sans Serif

9. ACCEPTANCE CRITERIA

AC1: Package Builder Loading

• Given a user with Owner or Admin role clicks "Edit" on a package group from the Package List View,
• When the Package Builder loads,
• Then the system must display all packages in the left sidebar, auto-select the first package, and display its details in the center canvas with Package Settings panel on the right.

AC2: Package Name Validation

• Given a user enters a package name that already exists within the same group,
• When the user clicks outside the name field,
• Then the system must display an inline error: "Package name already exists within this group."

AC3: Package Image Upload

• Given a user uploads an image file (JPG or PNG, under 15MB),
• When the upload completes,
• Then the system must open the crop tool and save the cropped image as the package thumbnail after user confirmation.

AC4: Add Custom Line Item

• Given a user selects "Custom" as line item type and enters a name,
• When the user fills all required fields and clicks Save,
• Then the system must save the line item to draft and display it in the appropriate event's service section.

AC5: Add Smart Field Line Item

• Given a user selects "Smart Field" as line item type and selects "Hours of Coverage",
• When the secondary field appears,
• Then the user must be able to enter the number of hours and save the line item successfully.

AC6: Smart Field Secondary Value Required

• Given a user selects a Smart Field type but does not enter the secondary value,
• When the user attempts to save,
• Then the system must display an error: "Smart field value is required."

AC7: Deliverable Toggle with Due Date

• Given a user toggles Deliverable ON and selects 10 Days as the due date,
• When the line item is saved,
• Then the system must store the due date rule for post-production calculation.

AC8: Deliverable Toggle with No Due Date

• Given a user toggles Deliverable ON and selects "No Due Date",
• When the line item is saved,
• Then the system must save the deliverable without a calculated due date.

AC9: Tax Mode - Line Item Based

• Given a user selects "Tax specific line items" as tax mode,
• When the user views line items,
• Then the system must enable Taxable toggles and Price fields for each line item.

AC10: Tax Mode Change Confirmation

• Given a user has set line item taxes and switches to "Tax entire package",
• When the switch is initiated,
• Then the system must display a confirmation modal warning that line item tax settings will be cleared.

AC11: Line Item Quantity Validation

• Given a user enters a quantity value,
• When the value exceeds 999 (3 digits),
• Then the system must prevent entry and limit to 3 digits maximum.

AC12: Drag-Drop Within Same Section

• Given a user drags a line item within the same event's service section,
• When the item is dropped,
• Then the system must update the order and auto-save to draft.

AC13: Drag-Drop Across Sections Blocked

• Given a user attempts to drag a line item to a different event's service section,
• When the drag is attempted,
• Then the system must not allow the drop and the item must return to original position.

AC14: A-La-Carte Item Assignment

• Given a user clicks "+ Add A La Carte Items" under an event and selects multiple items,
• When the user clicks Assign,
• Then the system must link all selected items to the package and display them in the A La Carte tab.

AC15: Publish Validation - Missing Price

• Given a user attempts to publish without setting a package price,
• When Publish is clicked,
• Then the system must block publish and display: "Publish blocked — complete all mandatory fields."

AC16: Publish Validation - Missing Line Items

• Given a package has an event's service section with no line items,
• When the user attempts to publish,
• Then the system must block publish and indicate which sections need line items.

AC17: Publish Success

• Given all mandatory fields are complete (name, price, line items per section),
• When the user clicks Publish,
• Then the system must change status to Published and display: "Package published successfully."

AC18: Edit Published Package - Snapshot Protection

• Given a user edits a published package that is used in 5 proposals,
• When changes are made and republished,
• Then the 5 existing proposals must retain their original snapshots and remain unchanged.

AC19: Group Settings - Brand Locked

• Given a user opens Group Settings in Package Builder,
• When the user views the Brand field,
• Then the Brand must be displayed as read-only and not editable.

AC20: Duplicate Package Success

• Given a group has 4 packages and user duplicates one,
• When duplication completes,
• Then the group must have 5 packages and the new package must be auto-selected.

AC21: Duplicate Package Blocked at Maximum

• Given a group already has 6 packages,
• When user attempts to duplicate a package,
• Then the system must display: "Cannot duplicate package. Group already has the maximum number of packages (6)."

AC22: Smart Field Crew Assignment Logic

• Given a package has "Number of Videographers" smart field set to 3,
• When the proposal is signed and converted to project,
• Then the system must assign 1 as lead shooter and 2 as second shooters.

AC23: Status Badge Display - Draft

• Given a package has not been published,
• When the Package Builder loads,
• Then the system must display a "Draft" status badge near the package name.

AC24: Status Badge Display - Published

• Given a package has been published,
• When the Package Builder loads,
• Then the system must display a "Published" status badge near the package name.

AC25: Preview Button Opens Overlay

• Given a user clicks the Preview button in the Package Builder,
• When the preview opens,
• Then the system must display a preview overlay in the same tab showing all packages as they would appear in a proposal.

AC26: Preview Navigation with More Than 3 Packages

• Given a package group has 5 packages,
• When the user opens the Preview,
• Then the system must display 3 packages by default with navigation arrows to view the remaining 2 packages.

AC27: Preview Close Functionality

• Given the Preview overlay is open,
• When the user clicks the close button (X),
• Then the system must close the preview and return to the Package Builder.

AC28: Single-Service Brand Canvas Display

• Given the package group's brand has one service configured,
• When the Package Builder loads,
• Then service type sub-headers are not displayed under event sections and line items appear directly beneath event headers.

AC29: Single-Event Brand Hides Edit Events

• Given the package group's brand has one event type configured,
• When the user views the Package Settings panel,
• Then the "Edit Events and Services" button is not visible.

AC30: Single-Event + Single-Service Simplified Canvas

• Given the brand has one event and one service,
• When the Package Builder loads,
• Then the canvas displays package header fields and line items without any event/service grouping visible.

AC31: Tax Warning on Publish — No Taxable Items

• Given tax mode is "Tax specific line items" and no line items have Taxable toggled ON,
• When the user clicks Publish,
• Then the system displays a non-blocking warning modal with "Go Back" and "Continue" options.

AC32: Tax Warning — Continue Publishes

• Given the tax warning modal is displayed,
• When the user clicks "Continue,"
• Then the package is published successfully with no taxable items.

AC33: Taxable Toggle OFF Hides Price Field

• Given tax mode is "Tax specific line items,"
• When the Taxable toggle for a line item is OFF,
• Then the "Price of Line Item" field is not visible.

AC34: Taxable Toggle ON Shows Price Field

• Given tax mode is "Tax specific line items,"
• When the user switches Taxable toggle to ON,
• Then the "Price of Line Item" field appears and is required.

AC35: Line Item Price Exceeds Package Price Warning

• Given the tax mode is "Tax specific line items" and the Package Price is set to $500,
• When the user enters a Price of Line Item value of $600,
• Then the system must display a non-blocking warning: "The line item price exceeds the total package price. Please verify the amount." and allow the user to save the line item.

AC36: Duplicate Package Naming Convention

• Given a user duplicates a package named "Advanced Photography",
• When the duplication completes,
• Then the system must name the first duplicate "Copy of Advanced Photography", the second duplicate "Copy of Advanced Photography (1)", and subsequent duplicates with incrementing numbers.

AC37: Smart Field Crew Count Minimum Value

• Given a user selects a crew count Smart Field (Photographers, Videographers, etc.),
• When the user enters 0 as the value,
• Then the system must display an error "Value must be at least 1" and prevent saving.

AC38: A-La-Carte Modal Empty State (No Items for Brand)

• Given a user opens the A-La-Carte assignment modal and no items exist for the brand,
• When the modal opens,
• Then the system must display: "No A-La-Carte items found for this brand. Create items in the A-La-Carte module to assign them here."

AC39: Save as Preset Toggle

• Given a user configures a line item and toggles "Save as preset" to ON,
• When the line item is saved,
• Then the system must save the configuration as a preset available in the Add Deliverable list.

AC40: Unpublished Changes Banner Display

• Given a user edits a previously published package,
• When draft changes exist that have not been published,
• Then the system must display a banner at the top: "Unpublished changes detected. Publish to update proposals with your latest edits." with a "Publish Changes" button.

AC41: Group Name Tooltip on Truncation

• Given a package group name is too long to display fully in the header,
• When the user hovers over the truncated name,
• Then the system must display a tooltip showing the complete group name.

AC42: Colors Tab Accessible

• Given a user is in the Package Builder,
• When the user clicks the "Colors" tab in the left sidebar,
• Then the Color Styling panel must display with all configurable color sections.

AC43: Color Changes Apply to All Packages in Group

• Given a user changes the Header Text Color to red,
• When the color is applied,
• Then all packages within the package group must display the red header text color.

AC44: Real-Time Color Preview

• Given a user is editing colors in the Colors tab,
• When the user selects a new color,
• Then the right panel preview must update in real-time to reflect the change.

AC45: Color Changes Auto-Save

• Given a user changes any color setting,
• When the color picker closes,
• Then the system must auto-save the change without requiring a manual save action.

AC46: Event Background Color Inherited from Brand

• Given a user views the Event Section color options,
• When the user looks for event background color,
• Then there must be no option to change it, as it is inherited from the brand's event color settings.

AC47: A-La-Carte Items Inherit Item Rows Color

• Given a user sets Item Rows text color to blue,
• When an A-La-Carte item is linked to a package in this group,
• Then the A-La-Carte item must display with blue text color.

AC48: Tooltip Display on Hover

• Given a user hovers over the info icon next to any color section,
• When the hover occurs,
• Then the system must display the appropriate tooltip explaining what the color setting affects.

AC49: Fonts Tab Accessible

• Given a user is in the Package Builder,
• When the user clicks the "Fonts" tab in the left sidebar,
• Then the Font Styling panel must display with Event Heading, Service Heading, and Body Text sections.

AC50: Font Changes Apply to All Packages in Group

• Given a user changes the Body Text font family,
• When the font is applied,
• Then all packages within the package group must display the selected font for event descriptions and line items.

AC51: Font Changes Auto-Save

• Given a user changes any font setting,
• When the dropdown closes,
• Then the system must auto-save the change without requiring a manual save action.

AC52: Body Text Tooltip Display

• Given a user hovers over the info icon next to Body Text,
• When the hover occurs,
• Then the system must display: "This font will be used for the Event Description and all Line Items."

AC53: Package Area Fonts Not Configurable

• Given a user views the Fonts panel,
• When the user looks for package name or price font options,
• Then there must be no option to change them, as they default to Sans Serif.

AC54: A La Carte Tab Empty State — Package Without Events

• Given a package exists with no events configured,
• When the user opens the A La Carte tab for that package (via the package card's "Assign A La Carte Items +" link or the Package Settings panel),
• Then the system must display the empty-state message "This package has no events configured yet. Add events and services to this package first before assigning A La Carte items." in the A La Carte tab content area, with no "+ Add A La Carte Items" button shown, and the package card link must remain enabled (not greyed out).

AC55: A La Carte Tab Shows Events Once Configured

• Given a package previously displayed the no-events empty state and the user has now added at least one event,
• When the user reopens the A La Carte tab,
• Then the system must display the configured event(s) with a "+ Add A La Carte Items" button beneath each, and the empty-state message must no longer appear.

10. MANUAL TEST CASES

Test cases for this module will be documented in a separate Excel file.

Test Case Excel File: [To be generated after all 8 FRDs are complete]

11. DEPENDENCIES

Module/System

Dependency Type

Impact if Unavailable

Package Group Creation Flow (FRD #2)

Navigation Dependency

Package Builder loads groups created in wizard; if wizard incomplete, builder may fail to load or show incomplete data

Package List View (FRD #1)

Navigation Dependency

Entry point via "Edit" and clicking on the package action; if unavailable, users cannot access Package Builder

A-La-Carte Add-On Items (FRD #6)

Data Dependency

Simple Add-on items linked to packages; if unavailable, A-La-Carte assignment modal shows empty or error

A-La-Carte Event-Creation Add-On (FRD #7)

Data Dependency

Event-Creation items linked to packages; if unavailable, Event tab in assignment modal empty

Proposal Builder

Functional Dependency

Published packages used in Proposal Builder; if unavailable, packages cannot be added to proposals

Project Module

Functional Dependency

Signed proposals convert to projects using package data; deliverables and smart fields map to project

Post-Production Module

Functional Dependency

Deliverable line items sent to Post-Production board; due dates calculated from event dates

Brand Master Data

Data Dependency

Package groups assigned to brands; A-La-Carte filtering by brand; if unavailable, brand displays as error

Event Type Master Data

Data Dependency

Events selected from master data; if unavailable, event dropdowns empty

Service Type Master Data

Data Dependency

Services selected from master data; if unavailable, service selections fail

File Storage (AWS S3)

System Dependency

Package images uploaded to file storage; if unavailable, image uploads fail

Database Service

System Dependency

All package data stored in database; if unavailable, builder cannot load or save

Session Management

System Dependency

User authentication and permissions; if session expires, user redirected to login

Brand Master Data (Event Colors)

Data Dependency

Event background colors cannot be displayed; event sections may show default or no background

12. REFERENCES

Figma Link

[To be added]

☑️ EDIT, DELETE & DUPLICATE PACKAGE

Edit,Delete,Duplicate

Functional Requirement Document

BA & Ideation: Paul

Reviewed By: KG (Project Manager)

Updated Date: 9 April 2026

Updated By: Sehal Maheshwari
Status: App

roved

Version 2.0

EDIT, DELETE & DUPLICATE PACKAGE - FUNCTIONAL REQUIREMENTS DOCUMENT

Module: Edit, Delete & Duplicate Package (Group Level)
Document Version: 2.0

1. MODULE OVERVIEW

1.1 Module Name

Edit, Delete & Duplicate Package (Group Level)

1.2 Purpose

This module defines the functionality for managing existing Package Groups through the Actions menu available in the Package List View. Users can edit package groups by navigating to the Package Builder, duplicate package groups to create copies for modification, and delete unused package groups. These operations are performed at the Package Group level (not individual packages within a group) and are accessible through the three-dot Actions menu in the Package List View.

1.3 Business Goals

• Enable agencies to efficiently modify existing package group configurations through the Edit action which navigates to the Package Builder for comprehensive editing capabilities.
• Allow rapid creation of new package groups by duplicating existing successful configurations, reducing setup time and ensuring consistency.
• Provide controlled deletion of unused package groups while protecting data integrity for groups actively used in proposals.
• Maintain proposal integrity by blocking deletion of package groups that are referenced in any proposal.
• Support workflow efficiency by keeping users on the Package List View after duplication for immediate visibility of the new copy.

1.4 Key Definitions

Package Group A Package Group is a container that holds 1 to 6 individual packages, all sharing a common brand assignment. Package Groups are created through the Package Group Creation wizard and managed through the Package Builder.

Actions Menu The Actions Menu is a three-dot (vertical ellipsis) icon displayed in the Actions column of each package group row in the Package List View. Clicking this icon reveals a dropdown with three options: Edit, Duplicate, and Delete.

Proposal Usage A Package Group is considered "used" and blocks deletion if it is referenced in any proposal with Draft or Published status. Draft proposals are those still being worked on, while Published proposals are ready to be sent to clients or used in projects. Once a proposal is sent to a client from a project, a snapshot is created and the package group reference no longer blocks deletion. Users must manually remove the package group from all Draft and Published proposals before the group can be deleted.

Snapshot Protection When a proposal is sent to a client from a project, the system saves a complete snapshot of the package group configuration. This snapshot is independent of the live package group, meaning edits to the original group after the snapshot is created do not affect the sent proposal or project. Draft and Published proposals do not have snapshots; they always fetch the latest package data until the proposal is sent to the client.

2. USER ROLES & PERMISSIONS

2.1 Roles That Can Access the Module

Role

Access Level

Owner

Full Access (Edit, Duplicate, Delete)

Admin

Full Access (Edit, Duplicate, Delete)

Project Manager

No Access (Actions menu hidden)

2.2 Granular Permissions

Permission

Owner

Admin

Project Manager

View Actions Menu

✔

✔

✖

Edit Package Group

✔

✔

✖

Duplicate Package Group

✔

✔

✖

Delete Package Group

✔

✔

✖

2.3 Permission Notes

• Only Owner and Admin roles can see and interact with the Actions menu in the Package List View.
• Project Managers can view the Package List View in read-only mode but cannot access Edit, Duplicate, or Delete actions.
• The Actions column and three-dot menu icon are completely hidden for users without appropriate permissions.

3. USER FLOW

3.1 Edit Package Group Flow

3.1.1 The user navigates to the Package List View from the left sidebar menu under Packages.

3.1.2 The system displays all package groups in a table format with the Actions column showing a three-dot menu icon for each row.

3.1.3 The user identifies the package group they want to edit and clicks the three-dot menu icon in the Actions column.

3.1.4 The system displays a dropdown menu with three options: Edit, Duplicate, and Delete (displayed in red).

3.1.5 The user clicks the "Edit" option from the dropdown menu.

3.1.6 The system captures the package group ID from the selected row.

3.1.7 The system navigates the user to the Package Builder at the URL /packages/builder/{group_id}.

3.1.8 The Package Builder loads with all packages in the group displayed in the left sidebar.

3.1.9 The system auto-selects the first package and displays its details in the center canvas.

3.1.10 The user makes desired changes to the package group configuration including package names, descriptions, prices, line items, events, services, or A-La-Carte links.

3.1.11 The system auto-saves all changes to Draft status as the user edits.

3.1.12 The user clicks "Publish" or "Republish" to make the updated package available for future proposals.

3.1.13 The system validates all mandatory fields and publishes the package if validation passes.

3.1.14 The system displays a success toast confirming the publish action.

3.2 Duplicate Package Group Flow

3.2.1 The user navigates to the Package List View from the left sidebar menu under Packages.

3.2.2 The system displays all package groups in a table format with the Actions column showing a three-dot menu icon for each row.

3.2.3 The user identifies the package group they want to duplicate and clicks the three-dot menu icon in the Actions column.

3.2.4 The system displays a dropdown menu with three options: Edit, Duplicate, and Delete (displayed in red).

3.2.5 The user clicks the "Duplicate" option from the dropdown menu.

3.2.6 The system captures the package group ID and retrieves all associated data including packages, events, services, line items, and A-La-Carte links.

3.2.7 The system generates a new group name using the format "Copy of [Original Group Name]".

3.2.8 If "Copy of [Original Group Name]" already exists within the same brand, the system appends an auto-increment number such as "Copy of [Original Group Name] (1)", "(2)", etc.

3.2.9 The system creates a complete deep copy of the package group with the generated unique name.

3.2.10 The system assigns the same brand as the original group to the duplicated group (brand is locked).

3.2.11 The system saves the duplicated group with Draft status.

3.2.12 The system adds the new duplicated group to the Package List View immediately.

3.2.13 The system displays a success toast: "Package group duplicated successfully."

3.2.14 The user remains on the Package List View and can see the newly duplicated group in the list.

3.2.15 If the user wants to rename the duplicated group, they must click Edit to open the Package Builder and navigate to Group Settings to change the name.

3.3 Delete Package Group Flow (Unused Group)

3.3.1 The user navigates to the Package List View from the left sidebar menu under Packages.

3.3.2 The system displays all package groups in a table format with the Actions column showing a three-dot menu icon for each row.

3.3.3 The user identifies the package group they want to delete and clicks the three-dot menu icon in the Actions column.

3.3.4 The system displays a dropdown menu with three options: Edit, Duplicate, and Delete (displayed in red).

3.3.5 The user clicks the "Delete" option from the dropdown menu.

3.3.6 The system checks if the package group is used in any proposal with Draft or Published status.

3.3.7 The system determines that the package group is NOT used in any Draft or Published proposal.

3.3.8 The system displays a confirmation modal with the title "Delete Package Group?" and the message "Are you sure you want to delete '[Group Name]'? This action cannot be undone."

3.3.9 The confirmation modal displays two buttons: "Cancel" (gray) and "Delete" (red, destructive).

3.3.10 The user clicks the "Delete" button to confirm deletion.

3.3.11 The system permanently deletes the package group record from the database.

3.3.12 The system permanently deletes all packages inside the group.

3.3.13 The system permanently deletes all line items inside each package.

3.3.14 The system removes all A-La-Carte links associated with the packages (but does not delete the A-La-Carte items themselves).

3.3.15 The system removes the package group from the Package List View immediately.

3.3.16 The system displays a success toast: "Package group deleted successfully."

3.3.17 If the user clicks "Cancel" on the confirmation modal, the system closes the modal and takes no action.

3.4 Delete Package Group Flow (Used Group - Blocked)

3.4.1 The user navigates to the Package List View from the left sidebar menu under Packages.

3.4.2 The system displays all package groups in a table format with the Actions column showing a three-dot menu icon for each row.

3.4.3 The user identifies the package group they want to delete and clicks the three-dot menu icon in the Actions column.

3.4.4 The system displays a dropdown menu with three options: Edit, Duplicate, and Delete (displayed in red).

3.4.5 The user clicks the "Delete" option from the dropdown menu.

3.4.6 The system checks if the package group is used in any proposal with Draft or Published status.

3.4.7 The system determines that the package group IS used in one or more Draft or Published proposals.

3.4.8 The system displays a warning modal with the title "Cannot Delete Package Group".

3.4.9 The warning modal displays a message explaining that the group is used in proposals and lists all proposal names where the group is referenced.

3.4.10 Each proposal name in the list is displayed as a clickable link that navigates to that proposal when clicked.

3.4.11 The warning modal displays only a "Close" button (no "Delete Anyway" option as deletion is completely blocked).

3.4.12 The user clicks the "Close" button to dismiss the warning modal.

3.4.13 The system closes the modal and the package group remains in the list unchanged.

3.4.14 If the user wants to delete this group, they must first manually remove the group from all listed proposals.

4. FUNCTIONAL LOGIC

4.1 Actions Menu Display and Access

• The Actions menu (three-dot icon) is displayed in the Actions column for each package group row in the Package List View.
• The Actions menu is only visible to users with Owner or Admin role; it is completely hidden for all other roles.
• When the user clicks the three-dot icon, the system displays a dropdown menu overlay positioned below the icon.
• The dropdown menu contains three options displayed vertically: Edit (top), Duplicate (middle), and Delete (bottom).
• The Delete option is styled with red text color to indicate its destructive nature.
• Clicking outside the dropdown menu closes the menu without taking any action.
• Only one Actions menu can be open at a time; opening a new menu closes any previously open menu.

4.2 Edit Action Logic

• When the user selects Edit from the Actions menu, the system captures the package group ID from the row's data attribute.
• The system constructs the Package Builder URL using the format /packages/builder/{group_id}.
• The system initiates navigation to the Package Builder, passing the group ID as a URL parameter.
• The Package Builder loads and retrieves all data associated with the group including all packages, events, services, line items, deliverables, tax settings, and A-La-Carte links.
• The Package Builder displays all packages in the left sidebar with the first package auto-selected.
• All user edits in the Package Builder are auto-saved to Draft status and do not immediately affect published packages.
• Editing a package group does NOT affect proposals that have already been sent to clients because those proposals have static snapshots of package data.
• Draft and Published proposals that reference this package group will automatically reflect the edits because they fetch the latest package data.
• Once a proposal is sent to a client from a project, subsequent edits to the source package group do not affect that sent proposal.

4.3 Duplicate Action Logic

• When the user selects Duplicate from the Actions menu, the system captures the package group ID from the row's data attribute.
• The system retrieves the complete package group record including all nested data structures.
• The system generates a new unique group name using the format "Copy of [Original Group Name]".
• The system checks if the generated name already exists within the same brand (case-insensitive comparison).
• If a name conflict exists, the system appends an auto-increment number: "Copy of [Original Group Name] (1)", "(2)", "(3)", etc., until a unique name is found.
• The system creates a complete deep copy of the package group including: Group Name (newly generated unique name), Brand Assignment (same as original, locked), Number of Packages (same as original), all packages inside the group with their names, descriptions, images, prices, and tax modes, all events and services inside each package, all line items with their complete configuration including deliverable settings and due dates, and all A-La-Carte links.
• The duplicated group is assigned a new unique identifier (UUID) distinct from the original.
• The duplicated group is saved with Draft status, meaning it is not immediately available for use in proposals.
• The system does NOT open a rename modal; the duplication happens directly with the auto-generated name.
• After successful duplication, the system adds the new group to the Package List View at the appropriate position based on current sort order.
• The system displays a success toast: "Package group duplicated successfully."
• The user remains on the Package List View after duplication (no navigation to Package Builder).
• To rename the duplicated group, the user must click Edit to open the Package Builder, then access Group Settings to modify the name.
• The brand assignment cannot be changed during or after duplication; it remains locked to the original brand.
• Package images are duplicated as reference copies — the new group stores the same image URL as the original. Deleting the original group does not delete the image file from storage; images are managed independently and are not deleted unless explicitly removed from all packages referencing them.

4.4 Delete Action Logic - Usage Detection

• When the user selects Delete from the Actions menu, the system first performs a usage check before displaying any modal.
• The system queries the proposals table to find any proposals that reference the package group ID with status Draft or Published.
• The usage check includes only proposals with status: Draft and Published.
• The usage check does NOT include proposals that have already been sent to clients because those proposals have snapshots and are independent of the live package group.
• The usage check does NOT include Projects; projects have snapshot data that is independent of the live package group.
• If the query returns zero results (no Draft or Published proposals found), the package group is classified as "unused" and eligible for deletion.
• If the query returns one or more results (Draft or Published proposals found), the package group is classified as "used" and deletion is blocked.
• The system stores the list of proposal names and IDs for display in the warning modal if the group is used.

4.5 Delete Action Logic - Unused Groups

• For package groups that are NOT used in any proposal, the system displays a confirmation modal.
• The confirmation modal has the title "Delete Package Group?" displayed at the top.
• The confirmation modal displays the message: "Are you sure you want to delete '[Group Name]'? This action cannot be undone."
• The [Group Name] placeholder is replaced with the actual package group name.
• The modal displays two buttons: "Cancel" (gray/secondary styling) on the left and "Delete" (red/destructive styling) on the right.
• If the user clicks "Cancel", the system closes the modal immediately without taking any action.
• If the user clicks "Delete", the system performs a second usage check immediately before executing deletion. If the group is now found to be used in a Draft or Published proposal (e.g., another user published a proposal referencing this group while the modal was open), the confirmation modal is replaced with the warning modal listing the blocking proposals, and deletion is blocked.
• If the second usage check confirms the group is still unused, the system proceeds with permanent deletion.
• The deletion process removes: the package group record, all package records inside the group (1-6 packages), all line item records inside each package, all deliverable configuration records associated with line items that have Deliverable toggle ON, and all package-to-A-La-Carte link records.
• If any line items within the deleted group have Deliverable toggle ON, all associated deliverable configuration records are also permanently deleted as part of the cascade. Post-Production tasks that were already created from a signed proposal retain their own snapshot data and are not affected.
• The deletion does NOT remove A-La-Carte items themselves; only the links between packages and A-La-Carte items are removed.
• After successful deletion, the system removes the package group row from the Package List View immediately without requiring a page refresh.
• If the deleted row was the only item on the current page and the current page is not page 1, the system automatically navigates the user to the previous page.
• The system displays a success toast: "Package group deleted successfully."
• The deletion is permanent and cannot be undone; there is no recycle bin or soft delete functionality.
• Package image files stored in file storage are permanently deleted as part of the group deletion cascade, provided the image is not referenced by any other package (e.g., a duplicate group). If the image is shared, only the reference is removed — the file is retained

4.6 Delete Action Logic - Used Groups (Blocked)

• For package groups that ARE used in one or more proposals, the system displays a warning modal instead of a confirmation modal.
• The warning modal has the title "Cannot Delete Package Group" displayed at the top.
• The warning modal displays the message: "This package group is used in one or more proposals and cannot be deleted. Remove it from all listed proposals before trying again."
• Below the message, the modal displays a list of all proposal names where the package group is referenced.
• Each proposal name is displayed as a clickable hyperlink that navigates to the respective proposal when clicked.
• Clicking a proposal link opens the proposal in a new tab or navigates to the proposal detail view.
• The warning modal displays only a "Close" button; there is no "Delete Anyway" or force delete option.
• Deletion is completely blocked for used groups to maintain proposal data integrity.
• The user must manually remove the package group from all listed proposals before the group can be deleted.
• After removing the group from all proposals, the user can return to the Package List View and attempt deletion again.
• The warning modal can be closed by clicking the "Close" button or by clicking outside the modal overlay.

4.7 Impact on Proposals and Projects

• Editing a package group through the Edit action does NOT retroactively update proposals that have already been sent to clients from projects.
• Draft and Published proposals do NOT store a snapshot of package data; they only store the Package Group ID and fetch the latest package data each time the proposal is opened or previewed.
• If the user makes changes to a package group that is referenced by a Draft or Published proposal, those changes will be reflected when the proposal is next sent.
• A snapshot of the package data is created only when the proposal is sent to the client from a project.
• Once a snapshot is created (at send time from the project), subsequent edits to the source package group do NOT affect that sent proposal or project.
• The snapshot includes all package names, descriptions, prices, line items, deliverables, and A-La-Carte configurations as they existed at the moment the proposal was sent to the client.
• Projects retain their snapshot data and are not affected by package group edits or deletions.
• Duplicating a package group creates an independent copy; changes to the original do not affect the duplicate and vice versa.
• Deleting a package group is blocked if it is referenced by any Draft or Published proposal to prevent breaking proposal references; proposals that have been sent to clients have snapshots and do not block deletion.

4.8 Duplicate Name Conflict Resolution

• The system uses an auto-increment algorithm to resolve name conflicts during duplication.
• When duplicating a group named "Wedding Photography", the system first attempts "Copy of Wedding Photography".
• If "Copy of Wedding Photography" exists, the system attempts "Copy of Wedding Photography (1)".
• If that also exists, the system continues incrementing: "(2)", "(3)", "(4)", etc.
• The system performs case-insensitive comparison when checking for name conflicts.
• The name uniqueness check is scoped to the same brand; duplicate names can exist across different brands.
• The maximum increment number is not explicitly limited, but practically will not exceed the number of duplications performed.
  If "Copy of [Original Name]" exceeds 100 characters, the system truncates the original name portion to fit, ensuring the prefix "Copy of " and any suffix "(N)" are always fully preserved. Example: a 95-character original name is truncated to 89 characters to accommodate "Copy of " (8 chars) and fit within 100 total. If a suffix is required due to name conflict (e.g., "(1)"), the original name is further truncated to accommodate both the prefix and suffix.

5. FIELD DETAILS & VALIDATIONS

5.1 Actions Menu Fields

Field Name

Field Type

Description

Validation Rules

Actions Icon

Icon Button (3-dot)

Vertical ellipsis icon triggering dropdown menu

Clickable; visible only to Owner/Admin roles

Edit Option

Menu Item

Opens Package Builder for selected group

Clickable; navigates to /packages/builder/{group_id}

Duplicate Option

Menu Item

Creates copy of selected group

Clickable; triggers duplication process

Delete Option

Menu Item (Destructive)

Initiates deletion process

Clickable; styled in red; triggers usage check

5.2 Delete Confirmation Modal Fields (Unused Groups)

Field Name

Field Type

Description

Validation Rules

Modal Title

Text (Display)

"Delete Package Group?"

Read-only display

Confirmation Message

Text (Display)

"Are you sure you want to delete '[Group Name]'? This action cannot be undone."

Read-only; [Group Name] dynamically replaced

Cancel Button

Button (Secondary)

Closes modal without action

Clickable; gray/outline styling

Delete Button

Button (Destructive)

Confirms and executes deletion

Clickable; red background; triggers permanent deletion

5.3 Delete Warning Modal Fields (Used Groups)

Field Name

Field Type

Description

Validation Rules

Modal Title

Text (Display)

"Cannot Delete Package Group"

Read-only display

Warning Message

Text (Display)

"This package group is used in one or more proposals and cannot be deleted. Remove it from all listed proposals before trying again."

Read-only display

Proposal List

Link List

List of proposal names as clickable links

Each item clickable; navigates to respective proposal

Close Button

Button (Primary)

Closes warning modal

Clickable; closes modal without any action

5.4 Duplicate Success Toast Fields

Field Name

Field Type

Description

Validation Rules

Toast Message

Text (Display)

"Package group duplicated successfully."

Auto-dismiss after 5 seconds

New Group Name

Text (Display)

Generated name shown in list

Format: "Copy of [Original Name]" or "Copy of [Original Name] (N)"

6. SUCCESS MESSAGE HANDLING

Validation Scenario

Success Message

Display Type

Post-Success Action

Edit action initiated

No explicit message

Navigation

System navigates to Package Builder with group loaded

Duplicate completed successfully

"Package group duplicated successfully."

Toast (green, top-right, 5 seconds)

New group appears in Package List View; user remains on list

Delete completed successfully (unused group)

"Package group deleted successfully."

Toast (green, top-right, 5 seconds)

Group removed from Package List View immediately

Cancel delete action

No explicit message

Modal closes

No changes made; user returns to list view

Close warning modal (used group)

No explicit message

Modal closes

No changes made; user returns to list view

7. ERROR MESSAGE HANDLING

Field

Validation Scenario

Error Message

Delete Action

Package group is used in proposals

Warning modal: "Cannot Delete Package Group" with list of proposal names

Delete Action

Server error during deletion

"Failed to delete package group. Please try again."

Duplicate Action

Server error during duplication

"Failed to duplicate package group. Please try again."

Duplicate Action

Maximum name increment exceeded (edge case)

"Unable to generate unique name. Please try again."

Edit Action

Failed to navigate to Package Builder

"Unable to open Package Builder. Please try again."

Edit Action

Package group not found (deleted by another user)

"Package group not found. It may have been deleted."

Duplicate Action

Package group deleted by another user before duplication

"Package group no longer exists. It may have been deleted by another user."

Actions Menu

User does not have permission

Actions menu is hidden; no error message displayed

Network

Connection lost during operation

"Connection lost. Please check your internet connection and try again."

Session

User session expired

"Your session has expired. Please log in again."

Delete Warning Modal

Proposal link clicked but proposal no longer exists

"This proposal no longer exists." (Toast error; warning modal remains open)

8. EDGE CASES

Scenario

Expected Behavior

User duplicates a group while another user deletes the original

System completes duplication if data was already retrieved; displays error if original is deleted before data retrieval

User attempts to delete group used in 50+ proposals

Warning modal displays all 50+ proposal names as scrollable list with clickable links

User duplicates same group multiple times rapidly

System generates unique names with incrementing numbers: "(2)", "(3)", "(4)", etc.

Duplicate name reaches "Copy of [Name] (99)"

System continues incrementing; no practical upper limit

User clicks Delete, then navigates away before confirming

Modal closes; no deletion occurs; group remains unchanged

Two users attempt to delete same group simultaneously

First deletion succeeds; second user sees "Package group not found" error

User with Admin role is downgraded to Project Manager while viewing list

Actions menu remains visible until page refresh; actions will fail with permission error

Package group has 6 packages (maximum) and is duplicated

Duplicate includes all 6 packages; duplicate has same maximum

Original group is edited after duplication

Changes to original do not affect duplicate; they are independent

Proposal is deleted after group deletion was blocked

User must re-attempt deletion; system re-checks usage and may now allow deletion

User clicks proposal link in warning modal

System navigates to proposal in new tab; warning modal may remain open or close based on implementation

Browser back button pressed after Edit navigation

System navigates back to Package List View; any unsaved changes in Builder are preserved as draft

Delete confirmation modal is open when session expires

Modal remains visible but Delete action fails; user redirected to login

Duplicate group inherits Draft status

Duplicated group is always Draft regardless of original's published status

User attempts to duplicate group with very long name

System truncates if necessary to fit "Copy of [Name]" within max length (100 chars)

User edits package group referenced by Draft or Published proposal

Proposal automatically reflects changes when next opened (no snapshot until sent to client)

User edits package group after proposal sent to client

Sent proposal retains original snapshot; changes do not affect sent proposal

Package group deleted while Draft or Published proposal references it

Deletion blocked; user must remove package group from proposals first

Package group used only in sent proposals (not Draft or Published)

Deletion allowed; sent proposals have snapshots and are not affected

User clicks proposal link in warning modal but proposal was deleted by another user

System displays error toast: "This proposal no longer exists." The warning modal remains open and user can close it or click other links.

User opens delete confirmation modal (group unused), another user publishes a proposal referencing this group, first user clicks Delete

System performs second usage check before deletion. Since group is now used, confirmation modal is replaced with warning modal listing the blocking proposal. Deletion is blocked.

9. ACCEPTANCE CRITERIA

AC1: Actions Menu Visibility for Authorized Users

• Given a user with Owner or Admin role is viewing the Package List View,
• When the page loads,
• Then the Actions column must display a three-dot menu icon for each package group row.

AC2: Actions Menu Hidden for Unauthorized Users

• Given a user with Project Manager or Coordinator role is viewing the Package List View,
• When the page loads,
• Then the Actions column must not display the three-dot menu icon and no Edit/Duplicate/Delete options are accessible.

AC3: Actions Menu Dropdown Display

• Given an authorized user clicks the three-dot menu icon,
• When the dropdown appears,
• Then it must display three options: Edit, Duplicate, and Delete, with Delete styled in red.

AC4: Edit Action Navigation

• Given an authorized user selects Edit from the Actions menu,
• When the action is triggered,
• Then the system must navigate to the Package Builder at /packages/builder/{group_id} with all group data loaded.

AC5: Edit Does Not Affect Sent Proposals

• Given a user edits a package group that is used in 3 proposals (1 Draft, 1 Published, 1 already sent to client),
• When the user publishes the changes,
• Then the Draft and Published proposals will reflect the updated package data when next opened, while the sent proposal retains its original snapshot unchanged.

AC6: Duplicate Creates Full Copy

• Given an authorized user selects Duplicate from the Actions menu,
• When the duplication completes,
• Then a new package group must appear in the list with name "Copy of [Original Name]" containing all packages, events, services, line items, and A-La-Carte links from the original.

AC7: Duplicate Name Conflict Resolution

• Given "Copy of Wedding Photography" already exists,
• When the user duplicates "Wedding Photography",
• Then the system must create a group named "Copy of Wedding Photography (1)".

AC8: Duplicate Brand Locked

• Given a user duplicates a package group assigned to "Brand A",
• When the duplication completes,
• Then the duplicated group must also be assigned to "Brand A" with no option to change the brand during duplication.

AC9: Duplicate User Stays on List View

• Given an authorized user completes a duplication,
• When the success toast is displayed,
• Then the user must remain on the Package List View (not navigated to Package Builder).

AC10: Duplicate Saved as Draft

• Given a user duplicates a published package group,
• When the duplication completes,
• Then the duplicated group must have Draft status and not be available for new proposals until published.

AC11: Delete Unused Group - Confirmation Modal

• Given an authorized user selects Delete for a group NOT used in any proposals,
• When the action is triggered,
• Then the system must display a confirmation modal with title "Delete Package Group?" and Cancel/Delete buttons.

AC12: Delete Unused Group - Successful Deletion

• Given the user confirms deletion in the confirmation modal,
• When the Delete button is clicked,
• Then the package group and all its contents must be permanently deleted and removed from the list.

AC13: Delete Used Group - Warning Modal

• Given an authorized user selects Delete for a group used in 2 Draft or Published proposals,
• When the action is triggered,
• Then the system must display a warning modal titled "Cannot Delete Package Group" with both proposal names listed as clickable links.

AC14: Delete Used Group - Completely Blocked

• Given a package group is used in one or more Draft or Published proposals,
• When the warning modal is displayed,
• Then there must be no "Delete Anyway" option and deletion must be completely blocked.

AC15: Delete Used Group - Proposal Links Functional

• Given the warning modal displays proposal names as links,
• When the user clicks a proposal name,
• Then the system must navigate to that proposal's detail view.

AC16: Delete Allowed When Only Sent Proposals Exist

• Given a package group was used in proposals that have all been sent to clients (no Draft or Published proposals reference it),
• When the user attempts to delete the group,
• Then the system must allow deletion because sent proposals have snapshots and do not block deletion.

AC17: Cancel Button Closes Modal

• Given the delete confirmation modal is displayed,
• When the user clicks Cancel,
• Then the modal must close and no deletion must occur.

AC18: Success Toast Display - Duplicate

• Given a successful duplication,
• When the operation completes,
• Then the system must display "Package group duplicated successfully." as a toast notification.

AC19: Success Toast Display - Delete

• Given a successful deletion,
• When the operation completes,
• Then the system must display "Package group deleted successfully." as a toast notification.

10. MANUAL TEST CASES

Test cases for this module will be documented in a separate Excel file.

Test Case Excel File: [To be generated after all 8 FRDs are complete]

11. DEPENDENCIES

Module/System

Dependency Type

Impact if Unavailable

Package List View (FRD #1)

Parent Module

Actions menu not accessible; Edit/Duplicate/Delete cannot be initiated

Package Builder (FRD #3)

Navigation Dependency

Edit action cannot navigate to Package Builder; users cannot modify group details

Package Group Creation Flow (FRD #2)

Data Dependency

Original group data must exist for duplication; created structure defines what is copied

Proposal Module

Data Dependency

Usage check cannot verify if group is used in proposals; system may block all deletions as precaution

Database Service

System Dependency

All CRUD operations fail; Edit/Duplicate/Delete actions cannot complete

User & Authentication Module

Access Dependency

Role-based permissions not enforced; Actions menu visibility cannot be determined

Brand Master Data

Data Dependency

Brand assignment cannot be validated during duplication; duplicate may fail

Session Management

System Dependency

User authentication state not maintained; actions fail with session errors

12. REFERENCES

Figma Link:

☑️ A La Carte Items List View

A La Carte Items List view

Functional Requirement Document

BA & Ideation: Paul

Reviewed By: KG (Project Manager)

Updated Date: 9 April 2026

Updated By: Sehal Maheshwari
Status: App

roved

Version 2.0

A LA CARTE ITEMS LIST VIEW - FRD

Module: A La Carte Items List View
Document Version: 1.0

1. MODULE OVERVIEW

1.1 Module Name

A La Carte Items List View

1.2 Purpose

This module provides a centralized listing interface for all A-La-Carte items within the Packages module. A-La-Carte items are optional add-on services or events that can be linked to packages and offered to clients during the proposal process. The list view displays both Simple Add-On items and Event-Creation items in a unified table, allowing users to search, filter, sort, and manage these items efficiently. Users can create new items, edit existing items, duplicate items for rapid creation, and delete unused items from this interface.

1.3 Business Goals

• Provide a single view for managing all A-La-Carte items across both types (Add-On and Event) for streamlined administration.
• Enable quick discovery of items through search functionality across item names, brands, events, and services.
• Support multi-dimensional filtering by Brand, Event Type, Service Type, and Item Type to help users locate specific items.
• Allow rapid creation of new A-La-Carte items through the "Create New" button that opens a tabbed wizard interface.
• Protect data integrity by blocking deletion of items that are actively linked to packages.
• Display status badges for Event-type items to indicate Draft vs Published status for workflow visibility.
• Support agency scalability with pagination for organizations with large numbers of A-La-Carte items.

1.4 Key Definitions

A-La-Carte Item A-La-Carte items are optional add-on products or services that can be linked to packages and offered to clients during the proposal process. There are two types: Add-On (simple enhancements) and Event (items that create new project events when selected).

Add-On Type Simple Add-On items enhance existing packages with optional services such as additional hours, drone footage, extra edited images, or physical deliverables. They do not create new events in projects. Add-On items are immediately published upon creation with no Draft status.

Event Type Event-Creation items are specialized add-ons that automatically generate new sub-events within a project when selected by clients. Examples include Engagement Shoots, Rehearsal Dinners, or Pre-Wedding Sessions as separate bookable events. Event items have Draft and Published statuses.

Package Link A-La-Carte items are connected to packages through the Package Builder (FRD #3). When an item is linked to a package, it becomes available as an option in proposals that use that package. Items can be linked to multiple packages.

2. USER ROLES & PERMISSIONS

2.1 Roles That Can Access the Module

Role

Access Level

Owner

Full Access (View, Create, Edit, Duplicate, Delete)

Admin

Full Access (View, Create, Edit, Duplicate, Delete)

Project Manager

View Only (based on agency settings)

2.2 Granular Permissions

Permission

Owner

Admin

Project Manager

View A-La-Carte Items List

✔

✔

✔

Create New A-La-Carte Item

✔

✔

✖

Edit A-La-Carte Item

✔

✔

✖

Duplicate A-La-Carte Item

✔

✔

✖

Delete A-La-Carte Item

✔

✔

✖

2.3 Permission Notes

• The "Create New" button is visible only to users with Owner or Admin role.
• The Actions menu (three-dot icon) is visible only to users with Owner or Admin role.
• Project Managers can view the A-La-Carte Items list in read-only mode based on agency-level settings.
• Delete permission is available only to Owner and Admin roles; deletion is blocked if the item is linked to any package.

3. USER FLOW

3.1 Accessing A-La-Carte Items List View

3.1.1 The user navigates to the Packages section from the left sidebar menu.

3.1.2 The system displays the Packages module with two tabs: "Packages" and "A La Carte Items".

3.1.3 The user clicks the "A La Carte Items" tab.

3.1.4 The system loads the A-La-Carte Items list view at the URL /packages/alacarte.

3.1.5 The system retrieves all A-La-Carte items (both Add-On and Event types) for the current user's agency and accessible brands.

3.1.6 The system displays the items in a table format with columns: Name, Type, Service, Event, Brand, Created, and Actions.

3.1.7 The system applies the default sort order: Created Date - Newest First.

3.1.8 The system displays the first 10 items and shows pagination controls at the bottom.

3.1.9 For Event-type items that are in Draft status, the system displays a "Draft" badge next to the item name or in the Type column.

3.1.10 The system displays the "Create New" button in the top-right corner (visible only to Owner and Admin roles).

3.2 Viewing Item Details

3.2.1 The user views the A-La-Carte Items list with all items displayed.

3.2.2 Each row displays: Item Name, Type badge (Add-on or Event), Service types, Event types, Brand name, Created date, and Actions menu icon.

3.2.3 The Type column displays a badge indicating "Add-on" for Simple Add-On items or "Event" for Event-Creation items.

3.2.4 For Event-type items in Draft status, an additional "Draft" badge is displayed to indicate the item has not been published.

3.2.5 The Service column displays the associated service types (e.g., Photography, Videography).

3.2.6 The Event column displays the associated event types (e.g., Wedding, Rehearsal Dinner).

3.2.7 If multiple services or events are associated, the system displays them with comma separation or "+N" overflow indicator if space is limited.

3.3 Searching for Items

3.3.1 The user locates the search input field in the top-right area of the list view.

3.3.2 The user enters a search query in the search field.

3.3.3 The system performs a case-insensitive search on the Item Name field only. Users can use filters for Brand, Event type, and Service type filtering.

3.3.4 The system filters the list in real-time to show only items matching the search query.

3.3.4.1 Search is applied on top of any active filters. Results must satisfy both the active filter criteria AND the search query simultaneously.

3.3.5 The system updates the pagination to reflect the filtered result count.

3.3.6 If no matching results are found, the system displays an empty state with the message: "No results found" along with the subtext: "No items match your search. Try adjusting your keywords or clearing the search."

3.3.7 The user can clear the search by clicking the "X" icon in the search field or deleting all text.

3.3.8 When the search is cleared, the system restores the full list with original sort and filter settings.

3.4 Filtering Items

3.4.1 The user clicks the Filter icon to open the filter panel.

3.4.2 The system displays filter options: Brand, Events, Services, and A-La-Carte Item Type.

3.4.3 The user selects one or more brands from the Brand filter dropdown.

3.4.4 The user selects one or more event types from the Events filter dropdown.

3.4.5 The user selects one or more service types from the Services filter dropdown.

3.4.6 The user selects the A-La-Carte Item Type filter: Add-on, Event, or both (default).

3.4.7 The system applies cumulative AND logic across filter types: items must match all selected filter criteria to appear.

3.4.8 The system updates the list in real-time to show only items matching the filter criteria.

3.4.9 The system displays a red dot indicator on the Filter icon when any filter is active. The red dot disappears when all filters are cleared.

3.4.10 The user can clear all filters by clicking "Clear All" within the filter panel.

3.4.11 When filters are cleared, the system restores the full list with original sort settings.

3.4.12 If no result matches the applied filter, Message - No results found “No items match the selected filters. Try adjusting or reset your filters to see results.”

3.5 Sorting Items

3.5.1 The user clicks on a column header to sort by that column.

3.5.2 The system supports sorting by: Name (A-Z, Z-A), Created Date (Newest First, Oldest First), Brand (A-Z, Z-A).

3.5.3 The first click on a column header sorts in ascending order; the second click toggles to descending order.

3.5.4 The system displays a sort direction indicator (arrow) on the active sort column.

3.5.5 The system reorders the list based on the selected sort criteria.

3.5.6 The system resets pagination to page 1 after a sort change.

3.6 Navigating Pages (Pagination)

3.6.1 The user views the pagination controls at the bottom-right of the list view.

3.6.2 The system displays: "Rows per page" dropdown, current page indicator (e.g., "1 of 5"), and Previous/Next buttons.

3.6.3 The user clicks the "Rows per page" dropdown and selects 10, 25, or 50.

3.6.4 The system updates the list to display the selected number of rows and recalculates total pages.

3.6.5 The user clicks the Next button to navigate to the next page.

3.6.6 The system loads the next set of items and updates the page indicator.

3.6.7 The user clicks the Previous button to navigate to the previous page.

3.6.8 The system loads the previous set of items and updates the page indicator.

3.6.9 The Previous button is disabled on the first page; the Next button is disabled on the last page.

3.7 Creating a New A-La-Carte Item

3.7.1 The user clicks the "Create New" button in the top-right corner.

3.7.2 The system opens the A-La-Carte Item creation wizard with two tabs: "Add-on" and "Event".

3.7.3 The "Add-on" tab is selected by default.

3.7.4 The user selects the appropriate tab based on the type of item they want to create.

3.7.5 The user completes the wizard steps (detailed in FRD #6 for Add-On type and FRD #7 for Event type).

3.7.6 Upon successful creation, the system returns the user to the A-La-Carte Items list view.

3.7.7 The newly created item appears in the list according to the current sort order.

3.7.8 The system displays a success toast: "A-La-Carte item created successfully."

3.8 Editing an A-La-Carte Item

3.8.1 The user clicks the three-dot Actions menu icon on the row of the item they want to edit.

3.8.2 The system displays a dropdown menu with options: Edit, Duplicate, and Delete (Delete shown in red).

3.8.3 The user clicks "Edit" from the dropdown menu.

3.8.4 The system opens the A-La-Carte Item wizard with all fields pre-filled with the item's current data.

3.8.5 For Add-On type items, the wizard opens to the Add-on tab.

3.8.6 For Event type items, the wizard opens to the Event tab or the Event Builder (depending on where the item was in the creation flow).

3.8.7 The user makes desired changes to the item configuration.

3.8.8 The user clicks the save/update button to confirm changes.

3.8.9 The system saves the changes and returns the user to the A-La-Carte Items list view.

3.8.10 The system displays a success toast: "A-La-Carte item updated successfully."

3.8.11 The updated data will be reflected in existing Draft and Published proposals when the proposal is next opened or sent to the client.

3.9 Duplicating an A-La-Carte Item

3.9.1 The user clicks the three-dot Actions menu icon on the row of the item they want to duplicate.

3.9.2 The system displays a dropdown menu with options: Edit, Duplicate, and Delete.

3.9.3 The user clicks "Duplicate" from the dropdown menu.

3.9.4 The system generates a new item name using the format "Copy of [Original Item Name]".

3.9.5 If "Copy of [Original Item Name]" already exists within the same brand, the system appends an auto-increment number: "Copy of [Original Item Name] (1)", "(2)", etc.

3.9.6 The system creates a complete copy of the item including all configuration settings (name, description, price, brand, event types, service types, quantity toggle, and for Event type: line items and deliverables).

3.9.7 For Add-On type items, the duplicate is created with Published status.

3.9.8 For Event type items, the duplicate is created with Draft status.

3.9.9 The system adds the duplicated item to the list view immediately.

3.9.10 The system displays a success toast: "A-La-Carte item duplicated successfully."

3.9.11 The user remains on the A-La-Carte Items list view after duplication.

3.10 Deleting an A-La-Carte Item (Allowed)

3.10.1 The user clicks the three-dot Actions menu icon on the row of the item they want to delete.

3.10.2 The system displays a dropdown menu with options: Edit, Duplicate, and Delete (Delete shown in red).

3.10.3 The user clicks "Delete" from the dropdown menu.

3.10.4 The system checks if the A-La-Carte item is linked to any package in any package group.

3.10.5 The system determines that the item is NOT linked to any package.

3.10.6 The system displays a confirmation modal with the title "Delete A-La-Carte Item?" and the message "Are you sure you want to delete '[Item Name]'? This action cannot be undone."

3.10.7 The confirmation modal displays two buttons: "Cancel" (gray) and "Delete" (red, destructive).

3.10.8 The user clicks the "Delete" button to confirm deletion.

3.10.9 The system permanently deletes the A-La-Carte item from the database.

3.10.10 The system removes the item from the list view immediately.

3.10.11 The system displays a success toast: "A-La-Carte item deleted successfully."

3.10.13 If the user clicks "Cancel", the system closes the modal without taking any action.

3.11 Deleting an A-La-Carte Item (Blocked)

3.11.1 The user clicks the three-dot Actions menu icon on the row of the item they want to delete.

3.11.2 The system displays a dropdown menu with options: Edit, Duplicate, and Delete (Delete shown in red).

3.11.3 The user clicks "Delete" from the dropdown menu.

3.11.4 The system checks if the A-La-Carte item is linked to any package in any package group.

3.11.5 The system determines that the item IS linked to one or more packages.

3.11.6 The system displays a warning modal with the title "Cannot Delete A-La-Carte Item".

3.11.7 The warning modal displays a message explaining that the item is linked to packages and lists all Package Group names where the item is linked.
Message “This A La Carte item is currently linked to the following package(s). To delete this item, you must first remove it from all linked packages”

3.11.8 Each Package Group name in the list is displayed as a clickable link that navigates to that Package Group in the Package Builder .Each Package Group name in the list is displayed as a clickable link that navigates to that Package Group in the Package Builder. Individual package names are displayed as text (not clickable) under their respective Package Group.

3.11.9 The warning modal displays only a "Close" button (no "Delete Anyway" option as deletion is completely blocked).

3.11.10 The user clicks the "Close" button to dismiss the warning modal.

3.11.11 The system closes the modal and the item remains in the list unchanged.

3.11.12 If the user wants to delete this item, they must first unlink it from all listed packages via the Package Builder.

3.12 Empty State

3.12.1 If there are no A-La-Carte items in the system, the system displays an empty state view.

3.12.2 The empty state displays an illustration and message: "No A-La-Carte items found. Create your first item to offer optional services to your clients."

3.12.3 The empty state displays a "Create New" button (visible only to Owner and Admin roles).

3.12.4 Clicking the "Create New" button opens the A-La-Carte Item creation wizard.

4. FUNCTIONAL LOGIC

4.1 List View Initialization

• When a user navigates to the A-La-Carte Items tab within the Packages module, the system validates that the user has appropriate permissions to view the list.
• The system identifies the user's agency ID and determines which brands the user has access to.
• The system retrieves all A-La-Carte items from the database where the agency_id matches the current user's agency and the brand_id is in the list of accessible brands.
• The retrieval includes both Add-On type items (type = "simple_addon") and Event-Creation type items (type = "event_creation") in a single query.
• For each item, the system loads: item name, type designation, associated service types (joined from service_types_master), associated event types (joined from event_types_master), brand name (joined from brands table), creation date, and status (for Event type items).
• The system applies the default sort order (Created Date - Newest First) to the retrieved items.
• The system loads the first 25 items for display and calculates the total page count for pagination.
• The system renders a table with columns: Name, Type, Service, Event, Brand, Created, and Actions.
• The Actions column displays a three-dot menu icon for users with Owner or Admin role; the column is hidden for other roles.

4.2 Empty State Logic

• When the A-La-Carte Items list has zero items (after accounting for the user's brand access), the system displays an empty state view instead of the table.
• The empty state displays an illustration/icon, a heading message, and an optional call-to-action button.
• The message reads: "No A-La-Carte items found. Create your first item to offer optional services to your clients."
• The "Create New" button in the empty state is visible only to users with Owner or Admin role.
• For users without create permission, the empty state displays only the message without a button.
• When search or filter results return zero items, the system displays a different message: "No A-La-Carte items found matching your criteria." with an option to clear filters.

4.3 Type Badge Display

• In the Type column, the system displays a badge indicating the item type: "Add-on" for Simple Add-On items or "Event" for Event-Creation items.
• The badges use distinct styling (colors or icons) to help users quickly differentiate between the two types.
• For Event-type items that have not been published (status = "draft"), the system additionally displays a "Draft" badge to indicate the item is not yet available for use in proposals.
• Add-On type items do not display a status badge because they are immediately published upon creation.

4.4 Search Functionality

• The search input field is located in the top-right area of the list view, visible to all users who can access the list.
• When a user enters text in the search input field, the system performs a case-insensitive search on the Item Name field only. Brand, Event type, and Service type are not included in search; users should use filters for those fields.
• The search supports partial matching, returning any item whose name contains the search query as a substring.
• The system updates the displayed list in real-time to show only matching results.
• The system updates pagination to reflect the filtered result count.
• If no matching results are found, the system displays an empty state with the message: "No results found" along with the subtext: "No items match your search. Try adjusting your keywords or clearing the search."
• Clearing the search input restores the full list with original sort and filter settings preserved.
• Search is applied cumulatively on top of any active filters. Results must satisfy both the active filter criteria AND the search query simultaneously. For example, if the user filters by Brand "Emma Taylor" and searches for "Hours", only items assigned to "Emma Taylor" brand whose name contains "Hours" will be displayed.

4.5 Filter Application Logic

• The system implements cumulative AND logic for filters: items must satisfy all active filter criteria to appear in results.
• Brand Filter: When one or more brands are selected, the system shows only items where the brand_id matches one of the selected brands.
• Events Filter: When one or more event types are selected, the system shows only items where the event_types array contains at least one of the selected event type IDs.
• Services Filter: When one or more service types are selected, the system shows only items where the service_types array contains at least one of the selected service type IDs.
• A-La-Carte Item Type Filter: When "Add-on" is selected, the system shows only items where type = "simple_addon"; when "Event" is selected, the system shows only items where type = "event_creation"; when both are selected or no selection is made, the system shows all types.
• The Events and Services filter dropdowns display all events and services from all brands (no cascading dependency on Brand filter selection).
• When filters are applied, the system displays a red dot indicator on the Filter icon. The red dot appears when any filter is active and disappears when all filters are cleared. No count is displayed
• Clearing filters restores the full list with original sort settings preserved.
• If no result matches the applied filter, Message - No results found “No items match the selected filters. Try adjusting or reset your filters to see results.”

4.6 Sorting Logic

• The system supports sorting by the following columns: Name (alphabetical A-Z or Z-A), Created Date (Newest First or Oldest First), and Brand (alphabetical A-Z or Z-A).
• The default sort order is Created Date - Newest First.
• Clicking a column header toggles the sort direction: first click sorts ascending, second click sorts descending.
• The system displays a sort direction indicator (arrow icon) on the currently active sort column.
• When sort order changes, the system reorders the entire dataset and resets pagination to page 1.
• Sort settings are preserved when filters are applied or cleared.

4.7 Pagination Logic

• The system displays pagination controls at the bottom-right of the list view.
• Pagination controls include: "Rows per page" dropdown with options 10, 25, 50 (default is 10), page indicator showing current page out of total pages (e.g., "1 of 5"), and Previous/Next navigation buttons.
• The system calculates total pages based on total item count divided by rows per page, rounded up.
• Changing the rows per page value recalculates pagination and resets to page 1.
• The Previous button is disabled when on page 1; the Next button is disabled when on the last page.
• Pagination is recalculated when search or filter results change the total item count.

4.8 Create New Item Logic

• The "Create New" button is displayed in the top-right corner of the list view and is visible only to users with Owner or Admin role.
• Clicking the "Create New" button opens a creation wizard modal or page with two tabs: "Add-on" and "Event".
• The "Add-on" tab is selected by default when the wizard opens.
• Selecting the "Add-on" tab initiates the Simple Add-On creation flow (detailed in FRD #6).
• Selecting the "Event" tab initiates the Event-Creation Add-On creation flow (detailed in FRD #7).
• For Add-On type items, completing the wizard creates the item with Published status immediately.
• For Event type items, the item is saved as Draft until the user completes all steps and clicks "Create Item" in the Event Builder.
• Upon successful creation, the system displays a success toast and returns the user to the list view.

4.9 Edit Item Logic

• The Edit action is available in the Actions dropdown menu for all A-La-Carte items when the user has Owner or Admin role.
• When the user selects Edit, the system captures the item ID and retrieves all associated data.
• The system opens the creation wizard with all fields pre-filled with the item's current configuration.
• For Add-On type items, the wizard opens to the Add-on tab with Step 1 displayed.
• For Event type items in Draft status, the system opens the Event Builder where the user left off.
• For Event type items in Published status, the system opens the wizard/builder with all data loaded for editing.
• The Brand field is read-only (locked) and cannot be changed after creation; users must duplicate to create a version with a different brand.
• Saving edits updates the live item record in the database.
• Editing an A-La-Carte item affects Draft and Published proposals that reference this item: the updated data will be fetched when the proposal is next opened or sent to the client.
• Proposals that have already been sent to clients have snapshots and are not affected by edits.

4.10 Duplicate Item Logic

• The Duplicate action is available in the Actions dropdown menu for all A-La-Carte items when the user has Owner or Admin role.
• When the user selects Duplicate, the system captures the item ID and retrieves all associated data.
• The system generates a new unique name using the format "Copy of [Original Item Name]".
• If a name conflict exists within the same brand, the system appends an auto-increment number: "Copy of [Original Item Name] (1)", "(2)", "(3)", etc., until a unique name is found (case-insensitive comparison).
• The system creates a complete deep copy of the item including: name (newly generated), description, price, brand (same as original, locked), event types array, service types array, customer quantity toggle, and for Event type items: all line items with deliverable settings, smart fields, and due date rules.
• For Add-On type items, the duplicate is created with Published status.
• For Event type items, the duplicate is created with Draft status regardless of the original's status.
• The system does NOT open a wizard or modal; the duplication happens directly with the auto-generated name.
• After successful duplication, the system adds the new item to the list view at the appropriate position based on current sort order.
• The system displays a success toast: "A-La-Carte item duplicated successfully."
• The user remains on the A-La-Carte Items list view after duplication (no navigation to wizard or builder).

4.11 Delete Item Logic - Link Detection

• When the user selects Delete from the Actions menu, the system first performs a link check before displaying any modal.
• The system queries the package_alacarte_links table to find any packages that have this A-La-Carte item linked.
• The link check considers all packages regardless of the package group's status (Draft or Published).
• If the query returns zero results (no package links found), the item is classified as "unlinked" and eligible for deletion.
• If the query returns one or more results (package links found), the item is classified as "linked" and deletion is blocked.
• The system retrieves the Package Group names for all packages where the item is linked, for display in the warning modal.

4.12 Delete Item Logic - Unlinked Items

• For A-La-Carte items that are NOT linked to any package, the system displays a confirmation modal.
• The confirmation modal has the title "Delete A-La-Carte Item?" displayed at the top.
• The confirmation modal displays the message: "Are you sure you want to delete '[Item Name]'? This action cannot be undone."
• The modal displays two buttons: "Cancel" (gray/secondary styling) and "Delete" (red/destructive styling).
• If the user clicks "Cancel", the system closes the modal without taking any action.
• If the user clicks "Delete", the system permanently deletes the item record from the database.
• Deleting an Add-On item removes only the item record and its service/event type associations.
• Deleting an Event-type item also permanently deletes all associated line items, deliverable configurations, smart field entries, and due date rules linked to that item.
• After successful deletion, the system removes the item row from the list view immediately without requiring a page refresh.
• The system displays a success toast: "A-La-Carte item deleted successfully."
• New proposals will no longer show this item as an option because it no longer exists in the database.

4.13 Delete Item Logic - Linked Items (Blocked)

• For A-La-Carte items that ARE linked to one or more packages, the system displays a warning modal instead of a confirmation modal.
• The warning modal has the title "Cannot Delete A-La-Carte Item" displayed at the top.
• The warning modal displays a message explaining that the item is linked to packages and cannot be deleted. “This A La Carte item is currently used in one or more packages. To delete this item, you must first remove it from all linked packages”
• Below the message, the modal displays a list of all Package Group names where the item is linked.Under each Package Group name, the system displays the individual package names within that group where the item is linked.
• Each Package Group name is displayed as a clickable hyperlink that navigates to that Package Group in the Package Builder when clicked.
• The user must remove the A-La-Carte item from all listed individual packages before the item can be deleted.
• The warning modal displays only a "Close" button; there is no "Delete Anyway" or force delete option.
• Deletion is completely blocked for linked items to prevent breaking package configurations.
• The user must unlink the item from all listed packages via the Package Builder before the item can be deleted.
• The warning modal can be closed by clicking the "Close" button or by clicking outside the modal overlay.

5. FIELD DETAILS & VALIDATIONS

5.1 A-La-Carte Items List Table Columns

Field Name

Field Type

Description

Validation Rules

Name

Text (Display)

A-La-Carte item name

Read-only in list view; displays item name; truncated with ellipsis if exceeds column width; full name shown on hover tooltip

Type

Badge (Display)

Item type indicator

Read-only; displays "Add-on" badge for simple add-ons or "Event" badge for event-creation items; uses distinct colors

Status Badge

Badge (Display)

Draft status indicator for Event items

Read-only; displays "Draft" badge only for Event-type items in draft status; hidden for published items and all Add-on items

Service

Tag/Badge (Display)

Associated service types

Read-only; displays service names; uses "+N" overflow if more than 2 services

Event

Tag/Badge (Display)

Associated event types

Read-only; displays event names; uses "+N" overflow if more than 2 events

Brand

Text (Display)

Brand assignment

Read-only; displays brand name

Created

Date (Display)

Creation date

Read-only; displays date in system format (e.g., "Jan 24, 2025")

Actions

Icon Button (3-dot)

Actions menu trigger

Clickable; visible only to Owner/Admin; opens dropdown with Edit, Duplicate, Delete options

5.2 Search Field

Field Name

Field Type

Required

Validation Rules

Search Input

Text Input

No

Minimum 0 characters; searches across Name only; case-insensitive; partial match; real-time filtering

5.3 Filter Panel Fields

Field Name

Field Type

Required

Options

Validation Rules

Brand Filter

Multi-Select Dropdown

No

All brands accessible to user

No validation; shows all items if not selected

Events Filter

Multi-Select Dropdown

No

All event types from all brands

No validation; shows all items if not selected

Services Filter

Multi-Select Dropdown

No

All service types from all brands

No validation; shows all items if not selected

Item Type Filter

Single/Multi-Select

No

Add-on, Event

No validation; shows all types if not selected

5.4 Pagination Controls

Field Name

Field Type

Description

Validation Rules

Rows per page

Dropdown

Number of rows per page

Options: 10, 25, 50; default: 10

Page Indicator

Text (Display)

Current page position

Read-only; format: "X of Y"

Previous Button

Icon Button

Navigate to previous page

Disabled on page 1

Next Button

Icon Button

Navigate to next page

Disabled on last page

5.5 Delete Confirmation Modal Fields

Field Name

Field Type

Description

Validation Rules

Modal Title

Text (Display)

"Delete A-La-Carte Item?"

Read-only

Confirmation Message

Text (Display)

"Are you sure you want to delete '[Item Name]'? This action cannot be undone."

Read-only; [Item Name] dynamically replaced

Cancel Button

Button (Secondary)

Closes modal without action

Clickable

Delete Button

Button (Destructive)

Confirms and executes deletion

Clickable; red styling

5.6 Delete Warning Modal Fields (Linked Items)

Field Name

Field Type

Description

Validation Rules

Modal Title

Text (Display)

"Cannot Delete A-La-Carte Item"

Read-only

Warning Message

Text (Display)

Explanation that item is linked to packages

Read-only

Package Group List

Link List

List of Package Group names as clickable links

Each item clickable; navigates to Package Builder

Close Button

Button (Primary)

Closes warning modal

Clickable

6. SUCCESS MESSAGE HANDLING

Validation Scenario

Success Message

Post-Success Action

A-La-Carte item created successfully

"A-La-Carte item created successfully."

New item appears in list; user returned to list view

A-La-Carte item updated successfully

"A-La-Carte item updated successfully."

Changes reflected in list; user returned to list view

A-La-Carte item duplicated successfully

"A-La-Carte item duplicated successfully."

Duplicate appears in list; user remains on list view

A-La-Carte item deleted successfully

"A-La-Carte item deleted successfully."

Item removed from list immediately

Search results found

No explicit message

Matching items displayed

Filter applied successfully

No explicit message

Filtered items displayed

Filter cleared successfully

No explicit message

Full list restored

7. ERROR MESSAGE HANDLING

Field

Validation Scenario

Error Message

List View

Failed to load A-La-Carte items

"Unable to load A-La-Carte items. Please try again."

Search

No matching results found

"No A-La-Carte items found."

Filter

No items match filter criteria

" No results found “No items match the selected filters. Try adjusting or reset your filters to see results.”

Delete

Item is linked to packages

“This A La Carte item is currently linked to the following package(s). To delete this item, you must first remove it from all linked packages”

Delete

Server error during deletion

"Failed to delete A-La-Carte item. Please try again."

Duplicate

Server error during duplication

"Failed to duplicate A-La-Carte item. Please try again."

Duplicate

Unable to generate unique name (edge case)

"Unable to generate unique name. Please try again."

Edit

Failed to load item data

"Unable to load item details. Please try again."

Edit

Server error during update

"Failed to update A-La-Carte item. Please try again."

Actions Menu

User does not have permission

Actions menu is hidden; no error message

Network

Connection lost during operation

"Connection lost. Please check your internet connection and try again."

Session

User session expired

"Your session has expired. Please log in again."

8. EDGE CASES

Scenario

Expected Behavior

User searches for item that was just deleted by another user

Item does not appear in results; no error if item not found

User attempts to delete item while another user links it to a package

System re-checks links before deletion; if now linked, shows warning modal

User duplicates item with maximum name length (100 chars)

System truncates "Copy of [Name]" to fit within 100 character limit

User duplicates same item multiple times rapidly

System generates unique names with incrementing numbers: "(2)", "(3)", "(4)", etc.

Duplicate name reaches "Copy of [Name] (99)"

System continues incrementing; no practical upper limit

User applies multiple filters that result in zero items

System displays empty state: "No A-La-Carte items found matching your criteria." with clear filters option

Large dataset with 1000+ items

System paginates efficiently; only loads current page data

User opens Actions menu, then loses network connection

Actions menu remains visible; selected action fails with network error toast

Event-type item left in Draft status for extended period

Item remains in list with Draft badge; can be edited or deleted

Add-On item linked to package that is then deleted

Link is removed automatically; Add-On deletion now allowed

User without Admin role views list with items

Can see all items but Actions menu is hidden; read-only mode

User clicks Package Group link in delete warning modal

System navigates to Package Builder with that group loaded

Multiple Package Groups link to same A-La-Carte item

Warning modal displays all Package Group names in list

User clears search while filters are active

Search cleared but filters remain active; shows filtered results

Browser refresh while viewing filtered/searched results

System reloads with default view; filters and search cleared

User changes brand context in top navigation

List reloads showing only items for selected brand

User searches while filters are active

Search is applied on top of filters; results must match both filter criteria AND search query; clearing search restores filtered results

User deletes Event-type item with line items and deliverables

System permanently deletes all associated line items, deliverable configurations, smart field entries, and due date rules as part of the cascade deletion

9. ACCEPTANCE CRITERIA

AC1: List View Default Display

• Given a user with appropriate permissions navigates to the A-La-Carte Items tab,
• When the page loads,
• Then the system must display all items sorted by Created Date (Newest First) with 25 items per page.

AC2: Both Item Types Displayed

• Given the list contains both Add-On and Event type items,
• When the user views the list,
• Then both types must be displayed together with appropriate Type badges ("Add-on" or "Event").

AC3: Draft Status Badge for Event Items

• Given an Event-type item has Draft status,
• When the user views the list,
• Then a "Draft" badge must be displayed for that item in addition to the "Event" type badge.

AC4: Search Across Multiple Fields

• Given a user enters "Wedding" in the search field,
• When the search executes,
• Then the system must return items where Item Name contains "Wedding". Brand, Event type, and Service type are not included in search.

AC5: Filter by Item Type

• Given a user selects "Event" in the Item Type filter,
• When the filter is applied,
• Then only Event-type items must be displayed and Add-On items must be hidden.

AC6: Cumulative Filter Logic

• Given a user selects Brand "Emma Taylor" AND Event "Wedding",
• When filters are applied,
• Then only items assigned to "Emma Taylor" brand AND associated with "Wedding" event must be displayed.

AC7: Create New Button Visibility

• Given a user with Project Manager role views the list,
• When the page loads,
• Then the "Create New" button must NOT be visible.

AC8: Create New Button Opens Wizard

• Given a user with Owner role clicks "Create New",
• When the button is clicked,
• Then the system must open the creation wizard with "Add-on" tab selected by default.

AC9: Edit Opens Pre-filled Wizard

• Given a user clicks Edit on an Add-On type item,
• When Edit is selected,
• Then the system must open the wizard with all current item data pre-filled.

AC10: Duplicate Creates Copy with Auto-Name

• Given a user duplicates an item named "Extra Hours",
• When duplication completes,
• Then a new item named "Copy of Extra Hours" must appear in the list.

AC11: Duplicate Name Conflict Resolution

• Given "Copy of Extra Hours" already exists,
• When the user duplicates "Extra Hours",
• Then the system must create "Copy of Extra Hours (1)".

AC12: Duplicate Status for Event Items

• Given a user duplicates a Published Event-type item,
• When duplication completes,
• Then the duplicate must have Draft status.

AC13: Delete Unlinked Item - Confirmation Modal

• Given a user selects Delete on an item NOT linked to any package,
• When Delete is selected,
• Then the system must display a confirmation modal with Cancel and Delete buttons.

AC14: Delete Linked Item - Warning Modal

• Given a user selects Delete on an item linked to 2 Package Groups,
• When Delete is selected,
• Then the system must display a warning modal listing both Package Group names as clickable links.

AC15: Delete Blocked for Linked Items

• Given an item is linked to one or more packages,
• When the warning modal is displayed,
• Then there must be no "Delete Anyway" option and deletion must be completely blocked.

AC16: Package Group Links are Clickable

• Given the delete warning modal displays Package Group names,
• When the user clicks a Package Group name,
• Then the system must navigate to the Package Builder with that group loaded.

AC17: Actions Menu Hidden for Non-Admins

• Given a user with Coordinator role views the list,
• When the page loads,
• Then the Actions column must be hidden or Actions menu must not be visible.

AC18: Pagination Default Settings

• Given the list contains 75 items,
• When the page loads with default settings,
• Then 10 items must be displayed on page 1 with page indicator showing "1 of 3".

AC19: Empty State Display

• Given there are no A-La-Carte items for the user's agency,
• When the user views the list,
• Then an empty state message must be displayed with "Create New" button (for Owner/Admin only).

AC20: Filter Active Indicator

• * Given a user applies one or more filters,
• * When filters are active,
• * Then the system must display a red dot indicator on the Filter icon. The red dot must disappear when all filters are cleared.

AC21: Search Combined with Filters

• * Given a user has active filters (e.g., Brand = "Emma Taylor") and enters a search query (e.g., "Hours"),
• * When both are applied,
• * Then the system must display only items that match both the filter criteria AND the search query simultaneously.

10. MANUAL TEST CASES

Test cases for this module will be documented in a separate Excel file.

Test Case Excel File:

11. DEPENDENCIES

Module/System

Dependency Type

Impact if Unavailable

Package Builder (FRD #3)

Data Dependency

Cannot verify package links for delete blocking; Package Group links in warning modal non-functional

A-La-Carte Item Creation - Add-On (FRD #6)

Navigation Dependency

"Create New" button Add-on tab non-functional; new Add-On items cannot be created

A-La-Carte Item Creation - Event (FRD #7)

Navigation Dependency

"Create New" button Event tab non-functional; new Event items cannot be created

Brand Master Data

Data Dependency

Brand column displays empty; Brand filter non-functional

Event Types Master Data

Data Dependency

Event column displays empty; Event filter non-functional; search by event non-functional

Service Types Master Data

Data Dependency

Service column displays empty; Service filter non-functional; search by service non-functional

User & Authentication Module

Access Dependency

Role-based permissions not enforced; Actions menu visibility cannot be determined

Database Service

System Dependency

List fails to load; all CRUD operations fail

Session Management

System Dependency

User authentication state not maintained; actions fail with session errors

12. REFERENCES

Figma Link-

☑️ A La Carte Items Creation (Add-On)

A La Carte Items Creation

Functional Requirement Document

BA & Ideation: Paul

Reviewed By: KG (Project Manager)

Updated Date: 30th April 2026

Updated By: Sehal Maheshwari
Status: App

roved

Version 2.0

A LA CARTE ITEMS CREATION (ADD-ON) - FRD

Module: A La Carte Items Creation (Add-On Type)
Document Version: 2.0

1. MODULE OVERVIEW

1.1 Module Name

A La Carte Items Creation (Add-On Type)

1.2 Purpose

This module defines the functionality for creating Simple Add-On type A-La-Carte items through a 2-step wizard interface. Add-On items are optional service enhancements that can be linked to packages and offered to clients during the proposal process. Unlike Event-type A-La-Carte items (covered in FRD #7), Add-On items do not create new events in projects; they simply add optional services like additional hours, drone footage, extra photographers, or other service enhancements. Users access this wizard by clicking the "Create New" button from the A-La-Carte Items List View and selecting the "Add-on" tab.

1.3 Business Goals

• Enable agencies to create reusable add-on items that can be linked to multiple packages for upsell opportunities.
• Provide two item type options: Custom (free-form) and Smart Items (predefined industry-standard add-ons with quantity selection enabled by default).
• Allow configuration of visibility rules through Event Type and Service Type selection to ensure add-ons appear only in relevant proposals.
• Support flexible pricing with optional client quantity selection for scalable add-on pricing.
• Enable tax configuration per add-on item to support varied tax requirements across different service types.
• Support deliverable tracking by allowing add-ons to be marked as deliverables with configurable due dates for post-production workflow integration.
• Streamline add-on creation with a simple 2-step wizard that guides users through all required configuration.

1.4 Key Definitions

Add-On Type A-La-Carte Item A Simple Add-On is an optional service enhancement that can be attached to packages. Add-ons do not create new events in projects; they enhance existing package services. Examples include additional hours of coverage, extra photographers, drone footage, highlight reels, or physical deliverables like albums.

Custom Item Type A Custom item allows users to create any add-on with a free-form name and description. The "Customer can choose quantity" toggle defaults to OFF for Custom items.

Smart Item Type Smart Items are predefined, industry-standard add-on types that are commonly used in the photography and videography industry. When a Smart Item is selected, the "Customer can choose quantity" toggle is automatically enabled (ON) by default. Smart Items include: Additional Hours Coverage, Additional Photographer, Additional Videographer, Additional Content Creator, Assistant, and Drone Operator.

Visibility Rules Add-ons appear in proposals only when the selected package includes a matching Event Type AND Service Type. Each Add-On item is assigned exactly one Event Type and one Service Type, and the add-on will only be visible for packages that include both.

Deliverable When an add-on is marked as a Deliverable, it is tracked in the Post-Production module after the event. A due date can be configured to calculate when the deliverable should be completed relative to the event date.

2. USER ROLES & PERMISSIONS

2.1 Roles That Can Access the Module

Role

Access Level

Owner

Full Access (Create, Edit)

Admin

Full Access (Create, Edit)

Project Manager

No Access

2.2 Granular Permissions

Permission

Owner

Admin

Project Manager

Access Create New Wizard

✔

✔

✖

Create Add-On Item

✔

✔

✖

Edit Add-On Item

✔

✔

✖

Configure Deliverable Settings

✔

✔

✖

2.3 Permission Notes

• Only Owner and Admin roles can access the "Create New" button and the creation wizard.
• The "Add-on" tab in the creation wizard is visible to all users who can access the wizard.
• Editing an existing Add-On item follows the same permission rules as creation.
• Project Managers cannot create or edit A-La-Carte items even if they have view access to the list.

3. USER FLOW

3.1 Accessing the Add-On Creation Wizard

3.1.1 The user navigates to the A-La-Carte Items List View within the Packages module.

3.1.2 The user clicks the "Create New" button located in the top-right corner of the list view.

3.1.3 The system opens the A-La-Carte Item creation wizard as a modal or full-page view.

3.1.4 The wizard displays two tabs at the top: "Add-on" (selected by default) and "Event".

3.1.4.1 Each tab displays an info icon (ℹ️). On hover, the system displays a tooltip explaining when to use that item type.

3.1.4.2 The "Add-on" tab tooltip displays: "Use this for a single line item added to an existing package or event. Examples: extra hours of coverage, an Instagram video, extra edits, or another upgrade. Does not create a separate event, folder, or schedule."

3.1.4.3 The "Event" tab tooltip displays: "Use this when the à la carte item is a separate event the client may book in addition to the main one. Examples: rehearsal dinner, welcome party, or engagement session. Creates its own event/folder in the project so you can assign shooters, manage details, and track it separately."

3.1.5 The system displays Step 1: General Details with all input fields ready for entry.

3.1.6 The wizard header displays "Create A La Carte - Add-on: Step 1".

3.2 Step 1: General Details - Custom Item

3.2.1 The user views the Step 1 form with the following fields: A La Carte Item Type dropdown, Name, Description, Price, Brand, and Customer can choose quantity toggle.

3.2.2 The user clicks the "A La Carte Item Type" dropdown.

3.2.3 The system displays two options: "Custom" and "Smart Item".

3.2.4 The user selects "Custom" from the dropdown.

3.2.5 The system keeps the Name field empty for user input.

3.2.6 The user enters a name for the add-on item in the Name field (e.g., "Drone Footage Package").

3.2.7 The user optionally enters a description in the Description field explaining what the add-on includes.

3.2.8 The user enters a price in the Price field (e.g., "$250.00").

3.2.9 The user clicks the Brand dropdown and selects a brand from the list of available brands.

3.2.10 The user views the "Customer can choose quantity" toggle which is OFF by default for Custom items.

3.2.11 The user optionally toggles "Customer can choose quantity" to ON if clients should be able to select quantity (1-99) in proposals.

3.2.12 The user clicks the "Next" button to proceed to Step 2.

3.2.13 The system validates all required fields (Name, Price, Brand).

3.2.14 If validation passes, the system navigates to Step 2.

3.2.15 If validation fails, the system displays inline error messages below the respective fields and prevents navigation.

3.3 Step 1: General Details - Smart Item

3.3.1 The user views the Step 1 form with the A La Carte Item Type dropdown.

3.3.2 The user clicks the "A La Carte Item Type" dropdown.

3.3.3 The system displays two options: "Custom" and "Smart Item".

3.3.4 The user selects "Smart Item" from the dropdown.

3.3.5 The system displays an additional dropdown labeled "Select Smart Item" below the Item Type dropdown.

3.3.6 The user clicks the "Select Smart Item" dropdown.

3.3.7 The system displays the list of available Smart Items: Additional Hours Coverage, Number of edited images, Additional Photographer, Additional Videographer, Additional Content Creator, Assistant, and Drone Operator.

3.3.8 The user selects a Smart Item from the dropdown (e.g., "Additional Photographer").

3.3.9 The system automatically enables the "Customer can choose quantity" toggle to ON.

3.3.10 The user enters a name for the add-on item in the Name field (can customize or use a descriptive name).

3.3.11 The user optionally enters a description in the Description field.

3.3.12 The user enters a price in the Price field.

3.3.13 The user clicks the Brand dropdown and selects a brand.

3.3.14 The user can optionally toggle "Customer can choose quantity" to OFF if needed, but it defaults to ON for Smart Items.

3.3.15 The user clicks the "Next" button to proceed to Step 2.

3.3.16 The system validates all required fields (Smart Item selection, Name, Price, Brand).

3.3.17 If validation passes, the system navigates to Step 2.

3.4 Step 2: Event & Service Types and Settings

3.4.1 The system displays Step 2 with the header "Create A La Carte - Add-on: Step 2".

3.4.2 The user views the Step 2 form with the following fields: Event Type dropdown, Service Type dropdown, Save as preset toggle, Deliverable toggle, and Taxable toggle.

3.4.3 The user clicks the Event Type dropdown.

3.4.4 The system displays a list of event types filtered based on the Brand selected in Step 1.

3.4.5 The user selects exactly one event type from the dropdown.

3.4.6 The user clicks the Service Type dropdown.

3.4.7 The system displays a list of service types filtered based on the Brand selected in Step 1.

3.4.8 The user selects exactly one service type from the dropdown.

3.4.9 The user views the "Save as preset" toggle which is OFF by default, located above the Deliverable toggle.

3.4.9.1 An info icon (ℹ️) is displayed next to the toggle. On hover, the system displays a tooltip: "Turn this on to save these settings as a preset. It will appear in the Add Deliverable list when manually adding deliverables."

3.4.9.2 The user optionally toggles "Save as preset" to ON if they want to save this configuration as a reusable preset.

3.4.10 The user views the Deliverable toggle which is OFF by default with the label "After event" displayed below it.

3.4.11 The user optionally toggles Taxable to OFF if the add-on should not be taxed. Taxable is ON by default.

3.4.12 If the add-on should be tracked as a deliverable in Post-Production, the user toggles Deliverable to ON.

3.4.13 When Deliverable is toggled ON, the system displays the Due Date configuration fields.

3.4.14 The user selects a due date value from the dropdown (options: 1-99 or "No Due Date").

3.4.15 If a numeric value is selected, the user selects a due date unit from the dropdown (options: Days, Weeks, Months).

3.4.16 If "No Due Date" is selected, the unit dropdown is hidden or disabled.

3.4.17 The user clicks the "Create New Item" button to complete the creation.

3.4.18 The system validates all required fields (Event Type, Service Type, Due Date if Deliverable ON).

3.4.19 The system re-validates that the item name is still unique within the selected brand at the time of final save. If a conflict has been created since Step 1, the system displays: "Item name already exists." and prevents saving.

3.4.20 If validation passes, the system creates the add-on item with Published status.

3.4.21 The system closes the wizard and returns the user to the A-La-Carte Items List View.

3.4.22 The system displays a success toast: "A-La-Carte item created successfully."

3.4.23 The newly created item appears in the list according to the current sort order.

3.5 Navigating Back from Step 2

3.5.1 While on Step 2, the user clicks the "Back" button.

3.5.2 The system navigates back to Step 1 with all previously entered data preserved.

3.5.3 The user can modify any Step 1 fields.

3.5.4 The user clicks "Next" to return to Step 2 with Step 2 data also preserved.

3.6 Canceling the Creation Wizard

3.6.1 At any point during the wizard, the user clicks the "Cancel" button or clicks outside the modal (if modal view).

3.6.2 The system displays a confirmation dialog with a warning icon and title "Cancel A La Carte Item Creation?" and message "Are you sure you want to cancel? All entered data will be lost." The dialog displays two buttons: "Stay" (secondary) and "Exit" (primary/yellow).

3.6.3 If the user clicks "Exit", the system closes the wizard without saving and returns to the A-La-Carte Items List View.

3.6.4 If the user clicks "Stay", the system keeps the wizard open with all data intact.

3.7 Editing an Existing Add-On Item

3.7.1 The user clicks "Edit" from the Actions menu on an existing Add-On item in the A-La-Carte Items List View.

3.7.2 The system opens the Edit wizard as a single-screen form (not a 2-step wizard) with the header "Edit A La Carte Item".

3.7.3 All fields are displayed on a single screen: A La Carte Item Type, Select Smart Item (if applicable), Name, Description, Price, Brand (read-only/locked), Customer can choose quantity toggle, Event Type, Service Type, Save as preset toggle, Deliverable toggle with due date fields (if ON), and Taxable toggle.

3.7.4 The Brand field is displayed as read-only with greyed/disabled styling and cannot be modified.

3.7.5 All other fields are pre-filled with the item's current data and are editable.

3.7.6 The user makes desired changes to any editable field.

3.7.7 The user clicks "Save Changes" to update the item.

3.7.8 The system validates all required fields and checks that the item name is still unique within the brand.

3.7.9 If validation passes, the system updates the item record and closes the wizard.

3.7.10 The system displays a success toast: "A-La-Carte item updated successfully."

3.7.11 The user is returned to the A-La-Carte Items List View.

3.7.12 If the user clicks "Cancel", the system displays a confirmation dialog before discarding changes.

3.7.13 When the edit modal opens, the system checks if the item is linked to any packages (Draft or Published status).

3.7.14 If the item is linked to one or more packages, the system displays a warning banner at the top of the modal with a warning icon: "Item Type, Event Type and Service Type cannot be changed because this item is linked to one or more packages. Remove from all packages to edit."

3.7.15 When linked to packages, the following fields are displayed as greyed/disabled and cannot be modified:

• A La Carte Item Type dropdown
• Select Smart Item dropdown (if Smart Item type was selected)
• Event Type dropdown
• Service Type dropdown

3.7.16 All other fields remain editable: Name, Description, Price, Customer can choose quantity, Save as preset, Deliverable settings, and Taxable.

3.7.17 If the item is not linked to any packages, all fields are fully editable and no warning banner is displayed.

4. FUNCTIONAL LOGIC

4.1 Wizard Initialization

• When the user clicks "Create New" from the A-La-Carte Items List View, the system opens the creation wizard.
• The wizard displays two tabs: "Add-on" and "Event", with the "Add-on" tab selected by default.
• Each tab has an info icon (ℹ️) that displays a tooltip on hover explaining the purpose of that item type.
• Add-on Tab Tooltip: "Use this for a single line item added to an existing package or event. Examples: extra hours of coverage, an Instagram video, extra edits, or another upgrade. Does not create a separate event, folder, or schedule."
• Event Tab Tooltip: "Use this when the à la carte item is a separate event the client may book in addition to the main one. Examples: rehearsal dinner, welcome party, or engagement session. Creates its own event/folder in the project so you can assign shooters, manage details, and track it separately."
• Selecting the "Add-on" tab initiates the Simple Add-On creation flow (this FRD).
• Selecting the "Event" tab initiates the Event-Creation Add-On flow (FRD #7).
• The wizard header dynamically updates to show the current step: "Create A La Carte - Add-on: Step 1" or "Create A La Carte - Add-on: Step 2".
• The system initializes all form fields with default values: Item Type as empty/unselected, Name as empty, Description as empty, Price as "$0.00", Brand as "Select a brand", Quantity toggle as OFF, Taxable as ON, Deliverable as OFF.

4.2 Item Type Selection Logic

• The A La Carte Item Type dropdown provides two options: "Custom" and "Smart Item".
• When "Custom" is selected, no additional dropdown appears; the user enters a free-form name.
• When "Smart Item" is selected, the system displays a secondary dropdown labeled "Select Smart Item".
• The Smart Item dropdown contains predefined options: Additional Hours Coverage, Additional Photographer, Additional Videographer, Additional Content Creator, Assistant, and Drone Operator.
• When any Smart Item is selected, the system automatically sets the "Customer can choose quantity" toggle to ON.
• The user can manually override the quantity toggle to OFF even for Smart Items, but it defaults to ON.
• The Item Type selection determines internal categorization but does not restrict naming or pricing.
• When the user returns to Step 1 via Back and changes the Item Type, the Smart Item dropdown and quantity toggle are reset immediately upon type selection change — not deferred to the Next click. If the user changes from "Smart Item" to "Custom", the Smart Item dropdown is hidden and quantity toggle reverts to OFF. If the user changes from "Custom" to "Smart Item", the Smart Item dropdown appears and quantity toggle is set to ON upon Smart Item selection.

4.3 Step 1 Field Validation

• Name Field: Required; maximum 100 characters; must be unique within the selected brand (case-insensitive comparison); leading and trailing whitespace is automatically trimmed.
• Description Field: Optional; maximum 500 characters; no uniqueness requirement.
• Price Field: Required; must be a valid numeric value; must be greater than or equal to 0; negative values are not allowed; price of $0.00 is valid for free add-ons.
• Brand Field: Required; must select a valid brand from the dropdown; brand becomes locked (read-only) after creation and cannot be changed during editing.
• Item Type Field: Required if "Smart Item" is selected, the secondary Smart Item dropdown must also have a selection.
• Customer Can Choose Quantity Toggle: Optional; defaults to OFF for Custom items and ON for Smart Items; when ON, clients can select quantity 1-99 in proposals; when OFF, quantity is fixed at 1.

4.4 Step 1 to Step 2 Navigation

• When the user clicks "Next" on Step 1, the system performs validation on all required fields.
• If Name is empty after trimming, the system displays: "Item name is required."
• If Name already exists within the selected brand, the system displays: "Item name already exists."
• If Price is empty, the system displays: "Price is required."
• If Price is not a valid number or is negative, the system displays: "Price must be a positive number."
• If Brand is not selected, the system displays: "Brand is required."
• If Item Type is "Smart Item" but no Smart Item is selected, the system displays: "Please select a smart item."
• If any validation fails, the system prevents navigation and displays inline error messages below the respective fields.
• If all validations pass, the system stores the Step 1 data in memory and navigates to Step 2.

4.5 Step 2 Field Configuration

• Event Type Dropdown: Required; single-select dropdown populated with event types filtered based on the Brand selected in Step 1. User must select exactly one event type. Event types from other brands are not displayed.
• Service Type Dropdown: Required; single-select dropdown populated with service types filtered based on the Brand selected in Step 1. User must select exactly one service type. Service types from other brands are not displayed.
• Save as Preset Toggle: Optional; defaults to OFF; located above the Deliverable toggle. When ON, the system saves the item configuration as a reusable preset that appears in the Add Deliverable list when manually adding deliverables. An info icon displays tooltip on hover: "Turn this on to save these settings as a preset. It will appear in the Add Deliverable list when manually adding deliverables."
• Taxable Toggle: Optional; defaults to ON; determines whether tax is applied to this add-on in proposals.
• Deliverable Toggle: Optional; defaults to OFF; when ON, the add-on is tracked in the Post-Production module after the event.
• Due Date Value: Required when Deliverable is ON; dropdown with options 1-99 and "No Due Date"; determines the number of time units after the event when the deliverable is due.
• Due Date Unit: Required when Deliverable is ON and a numeric value is selected; dropdown with options Days, Weeks, Months; hidden or disabled when "No Due Date" is selected.
• Event Type and Service Type dropdowns in Step 2 are filtered to show only the event types and service types configured for the brand selected in Step 1. This ensures that Add-On items can only be assigned to event/service combinations that exist within their brand.

4.6 Visibility Rules Logic

• The Event Type and Service Type selections determine when the add-on appears in proposals.
• When a client views a proposal and selects a package, the system retrieves all add-ons linked to that package.
• For each linked add-on, the system checks if the add-on's Event Type matches any event in the package AND if the add-on's Service Type matches any service in the package.
• If BOTH conditions are true (Event Type match AND Service Type match), the add-on is displayed as an option in the proposal.
• If either condition is false, the add-on is hidden from the proposal.
• Each Add-On item has exactly one Event Type and one Service Type, making the visibility rule a direct match rather than an intersection.

4.7 Deliverable Configuration Logic

• When the Deliverable toggle is OFF, no due date fields are displayed; the add-on is not tracked in Post-Production.
• When the Deliverable toggle is switched ON, the system displays the Due Date configuration fields immediately below the toggle.
• The Due Date Value dropdown contains numeric options 1 through 99, plus the special option "No Due Date".
• When a numeric value (1-99) is selected, the Due Date Unit dropdown is enabled with options: Days, Weeks, Months.
• When "No Due Date" is selected, the Due Date Unit dropdown is hidden or disabled; the deliverable will be tracked in Post-Production without a specific deadline.
• The due date calculation formula is: Event Date + Value + Unit (e.g., Event Date + 10 Days = Due Date).
• Deliverable add-ons are automatically added to the Post-Production board when the proposal is signed and converted to a project.

4.8 Creating the Add-On Record

• When the user clicks "Create New Item" on Step 2, the system performs final validation on all fields from both steps.
• If Event Type is not selected, the system displays: "Event type is required."
• If Service Type is not selected, the system displays: "Service type is required."
• If Deliverable is ON and Due Date Value is not selected, the system displays: "Deliverable due date value is required."
• If Deliverable is ON, a numeric value is selected, and Due Date Unit is not selected, the system displays: "Deliverable due date unit is required."
• The system re-validates that the item name is still unique within the selected brand at the time of final save. If a conflict has been created since Step 1 (e.g., another user created an item with the same name), the system displays: "Item name already exists." and prevents saving.
• If all validations pass, the system creates a new record in the database with the following data: unique ID (UUID), name (trimmed), description (trimmed or null), price, brand_id, item_type ("custom" or the specific smart item type), type: "simple_addon", customer_quantity_toggle (boolean), event_type_id (single ID), service_type_id (single ID), taxable (boolean), is_deliverable (boolean), due_date_value (integer or null), due_date_unit (string or null), status: "published", created_at (current timestamp), created_by (current user ID), and agency_id (current agency).
• Add-On items are created with "published" status immediately; there is no draft state for Add-On type items.
• After successful creation, the system closes the wizard, displays a success toast, and returns the user to the list view.

4.9 Data Preservation During Navigation

• When the user navigates from Step 1 to Step 2 and back, all entered data is preserved in memory.
• Data is only cleared when the user explicitly cancels the wizard or closes the modal.
• If the user switches from the "Add-on" tab to the "Event" tab, the system first checks if any data has been entered in the Add-on form. If data exists, the system displays a confirmation dialog: "Switching tabs will clear all data entered on this tab. Are you sure?" with "Stay" and "Switch Tab" buttons. If the user clicks "Switch Tab", the Add-on form data is cleared and the Event tab loads. If the user clicks "Stay", the Add-on tab remains active with all data intact. If no data has been entered, the tab switch proceeds without confirmation.
• The system does not auto-save partial data; data is only persisted to the database upon clicking "Create New Item".

4.10 Edit Mode Logic

• When the user clicks "Edit" from the Actions menu on an existing Add-On item, the system opens a single-screen edit form (not a 2-step wizard).
• The edit form displays all fields on a single screen: A La Carte Item Type, Select Smart Item (if applicable), Name, Description, Price, Brand, Customer can choose quantity, Event Type, Service Type, Save as preset, Deliverable with due date fields, and Taxable.
• The Brand field is displayed as read-only with greyed/disabled styling. The brand cannot be changed after creation; users must duplicate the item to create a version for a different brand.
• All other fields are pre-filled with the item's current data and are fully editable.
• The "Save Changes" button replaces "Create New Item" in edit mode.
• When "Save Changes" is clicked, the system validates all required fields using the same validation rules as creation.
• The system re-validates that the item name is still unique within the brand at the time of save. If a conflict has been created by another user since the edit form was opened, the system displays: "Item name already exists." and prevents saving.
• If validation passes, the system updates the item record in the database and displays success toast: "A-La-Carte item updated successfully."
• The Save as preset toggle is available in edit mode and functions identically to create mode.

4.11 Package Link Detection for Edit Restrictions

• When the edit modal opens, the system queries whether the A La Carte item is currently linked to any package (Draft or Published status).
• If the item is linked to one or more packages:
  • A warning banner is displayed at the top of the edit modal with warning icon.
  • Warning message: "Item Type, Event Type and Service Type cannot be changed because this item is linked to one or more packages. Remove from all packages to edit."
  • The following fields are locked (greyed/disabled): A La Carte Item Type, Select Smart Item (if applicable), Event Type, Service Type.
  • The locked state is determined at modal open time. If packages are unlinked while the modal is open, the fields remain locked until the user closes and reopens the modal.
• If the item is not linked to any packages:
  • All fields are fully editable.
  • No warning banner is displayed.
• Brand remains locked regardless of package link status (as defined in Section 4.10).

5. FIELD DETAILS & VALIDATIONS

5.1 Step 1: General Details Fields

Field Name

Field Type

Required

Max Length

Default Value

Validation Rules

A La Carte Item Type

Dropdown

Yes

N/A

Empty

Must select "Custom" or "Smart Item"

Select Smart Item

Dropdown

Yes (if Smart Item)

N/A

Empty

Required when Item Type is "Smart Item"; options: Additional Hours Coverage, Additional Photographer, Additional Videographer, Additional Content Creator, Assistant, Drone Operator

Name

Text Input

Yes

100 chars

Empty

Cannot be empty; must be unique within brand (case-insensitive); auto-trim whitespace

Description

Text Area

No

500 chars

Empty

Optional; no validation

Price

Numeric Input

Yes

N/A

$0.00

Must be numeric; must be >= 0; cannot be negative

Brand

Dropdown

Yes

N/A

"Select a brand"

Must reference valid brand; locked after creation (displayed as read-only with greyed/disabled styling in edit mode)

Customer can choose quantity

Toggle

No

N/A

OFF (Custom) / ON (Smart Item)

Optional; determines if clients can select quantity 1-99

5.2 Step 2: Event & Service Types and Settings Fields

Field Name

Field Type

Required

Max Length

Default Value

Validation Rules

Event Type

Dropdown

Yes

N/A

Empty

Must select exactly one event type; filtered by Brand selected in Step 1

Service Type

Dropdown

Yes

N/A

Empty

Must select exactly one service type; filtered by Brand selected in Step 1

Save as preset

Toggle

No

N/A

OFF

Optional; when ON, saves item configuration as reusable preset for Add Deliverable list

Taxable

Toggle

No

N/A

ON

Optional; determines tax applicability

Deliverable

Toggle

No

N/A

OFF

Optional; enables due date fields when ON

Due Date Value

Dropdown

Yes (if Deliverable ON)

2 digits

Empty

Options: 1-99 or "No Due Date"; required when Deliverable is ON

Due Date Unit

Dropdown

Yes (if Deliverable ON and value is numeric)

N/A

Empty

Options: Days, Weeks, Months; required when value is 1-99

5.3 Wizard Navigation Buttons

Button

Location

Action

Cancel

Step 1, Step 2 (left side)

Shows confirmation dialog; closes wizard if confirmed

Next

Step 1 (right side)

Validates Step 1 fields; navigates to Step 2

Back

Step 2 (left side)

Returns to Step 1; preserves all data

Create New Item

Step 2 (right side)

Validates all fields; creates item; closes wizard

Save Changes

Edit mode (right side)

Validates all fields; updates existing item; closes wizard

5.4 Cancel Confirmation Dialog Fields

Field Name

Field Type

Description

Warning Icon

Icon

Yellow warning triangle icon at top of dialog

Dialog Title

Text (Display)

"Cancel A La Carte Item Creation?"

Dialog Message

Text (Display)

"Are you sure you want to cancel? All entered data will be lost."

Stay Button

Button (Secondary)

Closes dialog; keeps wizard open with data intact

Exit Button

Button (Primary/Yellow)

Confirms cancellation; closes wizard; discards all data

5.5 Tab Tooltips

Section

Tooltip Content

Add-on Tab

"Use this for a single line item added to an existing package or event. Examples: extra hours of coverage, an Instagram video, extra edits, or another upgrade. Does not create a separate event, folder, or schedule."

Event Tab

"Use this when the à la carte item is a separate event the client may book in addition to the main one. Examples: rehearsal dinner, welcome party, or engagement session. Creates its own event/folder in the project so you can assign shooters, manage details, and track it separately."

Save as preset

"Turn this on to save these settings as a preset. It will appear in the Add Deliverable list when manually adding deliverables."

5.6 Edit Mode - Locked Fields When Linked to Packages

Field Name

Locked When Linked

Visual State

A La Carte Item Type

Yes

Greyed/disabled dropdown

Select Smart Item

Yes (if visible)

Greyed/disabled dropdown

Event Type

Yes

Greyed/disabled dropdown

Service Type

Yes

Greyed/disabled dropdown

Brand

Always locked

Greyed/disabled dropdown

Name

No

Editable

Description

No

Editable

Price

No

Editable

Customer can choose quantity

No

Editable

Save as preset

No

Editable

Deliverable

No

Editable

Taxable

No

Editable

5.7 Edit Mode Warning Banner

Element

Description

Warning Icon

Yellow/orange warning icon

Warning Message

"Item Type, Event Type and Service Type cannot be changed because this item is linked to one or more packages. Remove from all packages to edit."

Position

Top of edit modal, below header

Visibility

Only when item is linked to one or more packages

6. SUCCESS MESSAGE HANDLING

Validation Scenario

Success Message

Display Type

Post-Success Action

Add-On item created successfully

"A-La-Carte item created successfully."

Toast (green, top-right, 5 seconds)

Wizard closes; user returned to list view; new item appears in list

Add-On item updated successfully

"A-La-Carte item updated successfully."

Toast (green, top-right, 5 seconds)

Wizard closes; user returned to list view; updated data reflected in list

Navigation from Step 1 to Step 2

No explicit message

Visual transition

Step 2 form displayed with header updated

Navigation from Step 2 to Step 1 (Back)

No explicit message

Visual transition

Step 1 form displayed with all data preserved

Line item saved with preset

No explicit message

Visual feedback (toggle remains ON)

Preset saved and available in Add Deliverable list

7. ERROR MESSAGE HANDLING

Field

Validation Scenario

Error Message

A La Carte Item Type

Not selected

"Item type is required."

Select Smart Item

Smart Item type selected but no item chosen

"Please select a smart item."

Name

Empty after trimming

"Item name is required."

Name

Duplicate within same brand

"Item name already exists."

Name

Exceeds 100 characters

"Item name must be 100 characters or less."

Name

Duplicate created by another user between Step 1 and Step 2 save

"Item name already exists."

Description

Exceeds 500 characters

"Description must be 500 characters or less."

Price

Empty

"Price is required."

Price

Not a valid number

"Price must be a valid number."

Price

Negative value

"Price must be a positive number."

Brand

Not selected

"Brand is required."

Event Type

Not selected

"Event type is required."

Service Type

Not selected

"Service type is required."

Due Date Value

Deliverable ON but value not selected

"Deliverable due date value is required."

Due Date Unit

Deliverable ON, numeric value selected, unit not selected

"Deliverable due date unit is required."

Save Operation

Server error during creation

"Failed to create A-La-Carte item. Please try again."

Network

Connection lost

"Connection lost. Please check your internet connection and try again."

Session

User session expired

"Your session has expired. Please log in again."

8. EDGE CASES

Scenario

Expected Behavior

User selects Smart Item then switches back to Custom

System clears the Smart Item selection; quantity toggle reverts to OFF (Custom default)

User enters name that matches existing item in different brand

System allows; name uniqueness is scoped to brand

User enters price as "$0.00" with quantity toggle ON

System allows; valid free add-on; clients can select quantity 1-99 at no cost

User toggles Deliverable ON then OFF before saving

System hides due date fields; deliverable data cleared; item saved without deliverable tracking

User selects "No Due Date" for deliverable

System saves item with deliverable ON but no due date; appears in Post-Production without deadline

User clicks Next without filling required fields

System shows inline errors; prevents navigation to Step 2

User clicks Back after filling Step 2, modifies Step 1, then proceeds

System preserves Step 2 data; user can complete creation with modified Step 1 data

User closes browser while on Step 2

Data is lost; no auto-save; user must restart creation

Two users create items with same name simultaneously for same brand

First save succeeds; second save shows "Item name already exists" error

User selects Smart Item, then changes Item Type to Custom

System hides Smart Item dropdown; quantity toggle changes to OFF; previous Smart Item selection cleared immediately

Event Type or Service Type is deleted from master data after item creation

Item retains reference; may display warning; visibility rules may be affected

User enters very long name (100 chars) and long description (500 chars)

System accepts both; displays properly in list with truncation if needed

User loses connection while clicking Create New Item

System displays network error; data not saved; user must retry

User switches from Add-on tab to Event tab after entering data

System displays confirmation dialog before clearing data; user can choose "Stay" or "Switch Tab"

Another user creates item with same name and brand between Step 1 and Step 2 save

System re-validates name uniqueness at final save; displays "Item name already exists." error and prevents saving

User opens edit modal for item linked to packages

Warning banner displayed; A La Carte Item Type, Event Type, and Service Type fields are greyed/disabled

User opens edit modal for item not linked to any packages

No warning banner; all fields are fully editable

Item is unlinked from all packages while edit modal is open

Fields remain locked until modal is closed and reopened

User attempts to click on locked dropdown

No action; dropdown does not open

9. ACCEPTANCE CRITERIA

AC1: Wizard Opens with Add-on Tab Selected

• Given a user with Owner or Admin role clicks "Create New" from the A-La-Carte Items List View,
• When the wizard opens,
• Then the "Add-on" tab must be selected by default and Step 1 form must be displayed.

AC2: Custom Item Type Default Quantity Toggle

• Given a user selects "Custom" as the Item Type,
• When the selection is made,
• Then the "Customer can choose quantity" toggle must be OFF by default.

AC3: Smart Item Type Default Quantity Toggle

• Given a user selects "Smart Item" and chooses "Additional Photographer" from the Smart Item dropdown,
• When the selection is made,
• Then the "Customer can choose quantity" toggle must be automatically set to ON, allowing clients to select quantity 1-99 in proposals.

AC4: Smart Item Dropdown Appears When Smart Item Selected

• Given a user selects "Smart Item" from the Item Type dropdown,
• When the selection is made,
• Then a secondary dropdown labeled "Select Smart Item" must appear with all Smart Item options.

AC5: Name Uniqueness Within Brand

• Given "Drone Footage" already exists for Brand "Emma Taylor",
• When a user tries to create another item named "Drone Footage" for the same brand,
• Then the system must display "Item name already exists" error and prevent saving.

AC6: Same Name Allowed Across Brands

• Given "Drone Footage" exists for Brand "Emma Taylor",
• When a user creates an item named "Drone Footage" for Brand "John Smith Photography",
• Then the system must allow the creation successfully.

AC7: Single Event Type Selection

• Given the user is on Step 2,
• When the user clicks the Event Type dropdown,
• Then only one event type can be selected (single-select, not multi-select) and only event types for the selected brand are displayed.

AC8: Single Service Type Selection

• Given the user is on Step 2,
• When the user clicks the Service Type dropdown,
• Then only one service type can be selected (single-select, not multi-select) and only service types for the selected brand are displayed.

AC9: Deliverable Due Date Fields Appear When Toggle ON

• Given the user toggles Deliverable to ON,
• When the toggle changes,
• Then the Due Date Value and Due Date Unit dropdowns must appear.

AC10: Deliverable Due Date Fields Hidden When Toggle OFF

• Given the Deliverable toggle is OFF,
• When the user views Step 2,
• Then no Due Date fields must be visible.

AC11: No Due Date Option Works Correctly

• Given the user toggles Deliverable ON and selects "No Due Date" from the value dropdown,
• When the selection is made,
• Then the Due Date Unit dropdown must be hidden or disabled and the item can be saved without a unit selection.

AC12: Item Created with Published Status

• Given a user completes the wizard and clicks "Create New Item",
• When the item is saved successfully,
• Then the item must have "published" status immediately (no draft state).

AC13: Back Button Preserves Data

• Given a user has filled Step 1, navigated to Step 2, and filled Step 2,
• When the user clicks "Back",
• Then all Step 1 and Step 2 data must be preserved.

AC14: Cancel Shows Confirmation

• Given a user has entered data in the wizard,
• When the user clicks "Cancel",
• Then a confirmation dialog must appear with title "Cancel A La Carte Item Creation?", message "Are you sure you want to cancel? All entered data will be lost.", and buttons "Stay" and "Exit".

AC15: Taxable Toggle Default

• Given a user navigates to Step 2,
• When the form loads,
• Then the Taxable toggle must be ON by default.

AC16: Validation Prevents Empty Required Fields

• Given a user leaves Name, Price, or Brand empty on Step 1,
• When the user clicks "Next",
• Then inline error messages must appear and navigation must be prevented.

AC17: Edit Mode Opens Single Screen

• Given a user clicks "Edit" on an existing Add-On item,
• When the edit form opens,
• Then all fields must be displayed on a single screen (not a 2-step wizard) with "Save Changes" button.

AC18: Brand Locked in Edit Mode

• Given a user opens Edit mode for an existing Add-On item,
• When the form loads,
• Then the Brand field must be displayed as read-only with greyed/disabled styling and cannot be modified.

AC19: Tab Switch Confirmation

• Given a user has entered data in the Add-on tab,
• When the user clicks the "Event" tab,
• Then the system must display a confirmation dialog: "Switching tabs will clear all data entered on this tab. Are you sure?" with "Stay" and "Switch Tab" buttons.

AC20: Save as Preset Toggle

• Given a user is on Step 2 of the creation wizard or in Edit mode,
• When the user views the form,
• Then a "Save as preset" toggle must be displayed above the Deliverable toggle with an info icon showing tooltip on hover.

AC21: Event and Service Types Filtered by Brand

• Given a user selects "Brand A" in Step 1,
• When the user proceeds to Step 2,
• Then the Event Type and Service Type dropdowns must only display event types and service types configured for "Brand A".

AC22: Tab Tooltips Display

• Given a user opens the A La Carte creation wizard,
• When the user hovers over the info icon next to the "Add-on" or "Event" tab,
• Then the system must display the appropriate tooltip explaining when to use that item type.

AC23: Locked Fields When Linked to Packages

• Given a user opens the edit modal for an Add-On item that is linked to one or more packages,
• When the modal loads,
• Then the system must display a warning banner at the top and the A La Carte Item Type, Event Type, and Service Type fields must be greyed/disabled.

AC24: Editable Fields When Not Linked to Packages

• Given a user opens the edit modal for an Add-On item that is not linked to any packages,
• When the modal loads,
• Then all fields must be fully editable and no warning banner must be displayed.

AC25: Warning Banner Message

• Given a user opens the edit modal for an item linked to packages,
• When the modal loads,
• Then the warning banner must display: "Item Type, Event Type and Service Type cannot be changed because this item is linked to one or more packages. Remove from all packages to edit."

10. MANUAL TEST CASES

Test cases for this module will be documented in a separate Excel file.

Test Case Excel File:

11. DEPENDENCIES

Module/System

Dependency Type

Impact if Unavailable

A-La-Carte Items List View (FRD #5)

Navigation Dependency

Cannot access "Create New" button; cannot return to list after creation

Package Builder (FRD #3)

Functional Dependency

Created items cannot be linked to packages; visibility rules cannot be applied

Brand Master Data

Data Dependency

Brand dropdown empty; cannot create items without brand selection

Event Types Master Data

Data Dependency

Event Type dropdown empty; cannot complete Step 2

Service Types Master Data

Data Dependency

Service Type dropdown empty; cannot complete Step 2

Post-Production Module

Functional Dependency

Deliverable items cannot be tracked; due date calculations non-functional

Proposal Module

Functional Dependency

Items cannot appear in proposals; visibility rules not applied

User & Authentication Module

Access Dependency

Cannot verify user permissions; wizard access not controlled

Database Service

System Dependency

Cannot save or retrieve items; all operations fail

12. REFERENCES

Figma Link:

☑️ A La Carte Items Creation (Event)

A LA CARTE ITEMS CREATION (EVENT) - FRD

Module: A La Carte Items Creation (Event Type)
Document Version: 2.0

1. MODULE OVERVIEW

1.1 Module Name

A La Carte Items Creation (Event Type)

1.2 Purpose

This module defines the functionality for creating Event-type A-La-Carte items through a 2-step wizard followed by a Builder interface. Event-type items are specialized add-ons that automatically generate new events within a project when selected by clients during the proposal process. Unlike Add-On type items (FRD #6) which only enhance existing packages, Event-type items expand the project scope by creating entirely new sub-events with their own services, deliverables, and timelines. Users access this wizard by clicking the "Create New" button from the A-La-Carte Items List View and selecting the "Event" tab.

1.3 Business Goals

• Enable agencies to offer clients the ability to add complete events to their project scope (e.g., Engagement Shoot, Rehearsal Dinner, Pre-Wedding Session).
• Automatically generate new project events upon proposal signing with configured services and deliverables.
• Allow configuration of event-specific services independent of the main package services.
• Enable line item and deliverable configuration specific to the new event for post-production workflow integration.
• Support quantity-selectable event add-ons for multi-day or multi-location scenarios.
• Expand project revenue through strategic event upsells while maintaining clear project scope management.

1.4 Key Definitions

Event-Type A-La-Carte Item An Event-type item is a specialized add-on that automatically generates a new event within a project when selected by a client and the proposal is signed. Unlike Add-On type items which enhance existing packages, Event-type items create entirely new sub-events with their own date, services, contractors, and deliverables.

Event Type The category of event that will be created in the project when this A-La-Carte item is selected. Examples include Rehearsal Dinner, Engagement Shoot, Elopement, Pre-Wedding Session, or Day-After Session. Each Event-type A-La-Carte item is associated with exactly one Event Type.

Service Section In the Builder interface, each selected service (Photography, Videography, Content Creation) is displayed as a separate section. Users must configure at least one line item per service section.

Draft Status Event-type items are saved as Draft when the user proceeds to the Builder but exits without clicking "Publish". Draft items appear in the list view with a Draft badge and can be edited to complete the configuration.

Published Status Event-type items are Published when the user clicks "Publish" in the Builder. Published items are available for linking to packages and appearing in proposals.

2. USER ROLES & PERMISSIONS

2.1 Roles That Can Access the Module

Role

Access Level

Owner

Full Access (Create, Edit, Publish)

Admin

Full Access (Create, Edit, Publish)

Project Manager

No Access

2.2 Granular Permissions

Permission

Owner

Admin

Project Manager

Access Create New Wizard

✔

✔

✖

Create Event Item

✔

✔

✖

Edit Event Item

✔

✔

✖

Publish Event Item

✔

✔

✖

Configure Line Items

✔

✔

✖

2.3 Permission Notes

• Only Owner and Admin roles can access the "Create New" button and the creation wizard.
• Only Owner and Admin roles can publish Event-type items by clicking "Publish" in the Builder.
• Editing an existing Event-type item follows the same permission rules as creation.
• Project Managers and Coordinators cannot create or edit A-La-Carte items even if they have view access to the list.

3. USER FLOW

3.1 Accessing the Event Creation Wizard

3.1.1 The user navigates to the A-La-Carte Items List View within the Packages module.

3.1.2 The user clicks the "Create New" button located in the top-right corner of the list view.

3.1.3 The system opens the A-La-Carte Item creation wizard as a modal or full-page view.

3.1.4 The wizard displays two tabs at the top: "Add-on" (selected by default) and "Event".

3.1.4.1 Each tab displays an info icon (ℹ️). On hover, the system displays a tooltip explaining when to use that item type.

3.1.4.2 The "Add-on" tab tooltip displays: "Use this for a single line item added to an existing package or event. Examples: extra hours of coverage, an Instagram video, extra edits, or another upgrade. Does not create a separate event, folder, or schedule."

3.1.4.3 The "Event" tab tooltip displays: "Use this when the à la carte item is a separate event the client may book in addition to the main one. Examples: rehearsal dinner, welcome party, or engagement session. Creates its own event/folder in the project so you can assign shooters, manage details, and track it separately."

3.1.5 The user clicks the "Event" tab to switch to the Event-type creation flow.

3.1.6 The system displays Step 1: General Details with all input fields ready for entry.

3.1.7 The wizard header displays "Create A La Carte - Event: Step 1".

3.2 Step 1: General Details

3.2.1 The user views the Step 1 form with the following fields: Name, Description, Price, Brand, and Customer can choose quantity toggle.

3.2.2 The user enters a name for the event item in the Name field (e.g., "Rehearsal Dinner Coverage").

3.2.3 The user optionally enters a description in the Description field explaining what the event includes.

3.2.4 The user enters a price in the Price field (e.g., "$500.00").

3.2.5 The user clicks the Brand dropdown and selects a brand from the list of available brands.

3.2.6 The user clicks the "Next" button to proceed to Step 2.

3.2.7 The system validates all required fields (Name, Price, Brand).

3.2.8 If validation passes, the system navigates to Step 2.

3.2.9 If validation fails, the system displays inline error messages below the respective fields and prevents navigation.

3.3 Step 2: Event & Service Types

3.3.1 The system displays Step 2 with the header "Create A La Carte - Event: Step 2".

3.3.2 The user views the Step 2 form with the following fields: Event Type dropdown and Service Type multi-select.

3.3.3 The user clicks the Event Type dropdown.

3.3.4 The system displays a list of event types filtered based on the Brand selected in Step 1.

3.3.5 The user selects exactly one event type from the dropdown (e.g., "Rehearsal Dinner").

3.3.6 The system displays the selected event type in the dropdown field.

3.3.7 The user views the Service Type selection area showing available services (Photography, Videography, Content Creation) filtered based on the Brand selected in Step 1.

3.3.8 The user selects one or more service types by clicking on the service buttons.

3.3.9 Each selected service is visually highlighted to indicate selection.

3.3.10 The user must select at least one service type.

3.3.11 The user clicks the "Proceed to Builder" button to open the Event A-La-Carte Builder.

3.3.12 The system validates that Event Type is selected and at least one Service Type is selected.

3.3.13 If validation passes, the system saves the item as Draft and opens the Builder interface.

3.3.14 If validation fails, the system displays inline error messages and prevents navigation.

3.3.15 If the Draft save fails when "Proceed to Builder" is clicked, the system displays: "Failed to save item. Please try again." and keeps the user on Step 2. The Builder does not open. The user can retry by clicking "Proceed to Builder" again.

3.4 Builder Interface - Overview

3.4.1 The system opens the Event A-La-Carte Builder interface.

3.4.2 The Builder displays a center canvas showing the item configuration and a right sidebar for settings (Item Settings).

3.4.3 The center canvas displays the item name with a "Draft" badge indicating the item is not yet published.

3.4.4 The center canvas shows the Price field which can be edited (pre-filled from Step 1 if entered).

3.4.5 The center canvas shows the Description field which can be edited (pre-filled from Step 1 if entered).

3.4.6 Below the description, the system displays Event Section(s) based on the Event Type selected in Step 2.

3.4.7 The Event Section header displays the Event Type name in uppercase (e.g., "REHEARSAL DINNER").

3.4.8 Under the Event Section, the system displays each selected Service as a sub-section.

3.4.9 Each Service sub-section shows an area for Line Items with an "Add Line Item" button or placeholder.

3.4.10 The right sidebar displays Item Settings including Item Name, Item Description, Item Price, and the Package Events and Services section showing current Event Type and Service Types.

3.5 Builder Interface - Adding Line Items

3.5.1 The user clicks the "Add Line Item" button or the "+" icon within a Service section.

3.5.2 The system adds a new line item row to the Service section.

3.5.3 The line item row displays a placeholder text (e.g., "Line item") indicating a new item.

3.5.4 The user clicks on the line item row to open the Line Item Settings panel.

3.5.5 The system opens the Line Item Settings panel in the right sidebar.

3.5.6 The Line Item Settings panel displays fields for configuring the line item (same as FRD #3 Package Builder).

3.6 Builder Interface - Configuring Line Items

3.6.1 The user views the Line Item Settings panel with fields: Line Item Type dropdown, Name/Smart Field, Description, Quantity, Save as preset toggle, Deliverable toggle, and conditional Due Date fields, and Taxable toggle.

3.6.2 The user selects the Line Item Type from the dropdown: "Custom" or "Smart Field".

3.6.3 If "Custom" is selected, the user enters a custom name in the Name field.

3.6.4 If "Smart Field" is selected, the system displays a Smart Field dropdown with predefined options (e.g., Hours Coverage, Number of Edited Images, Additional Hours).

3.6.5 The user selects a Smart Field from the dropdown.

3.6.6 If the Smart Field requires a secondary value (e.g., Number of Edited Images requires quantity), the system displays the appropriate input field.

3.6.7 The user optionally enters a description for the line item.

3.6.8 The user sets the quantity for the line item (default is 1).

3.6.9 The user views the "Save as preset" toggle which is OFF by default, located above the Deliverable toggle.

3.6.9.1 An info icon (ℹ️) is displayed next to the toggle. On hover, the system displays a tooltip: "Turn this on to save these settings as a preset. It will appear in the Add Deliverable list when manually adding deliverables."

3.6.9.2 The user optionally toggles "Save as preset" to ON if they want to save this line item configuration as a reusable preset.

3.6.10 The user views the Deliverable toggle which is OFF by default.

3.6.11 If the line item should be tracked as a deliverable, the user toggles Deliverable to ON.

3.6.12 When Deliverable is toggled ON, the system displays Due Date configuration fields.

3.6.13 The user selects a due date value from the dropdown (options: 1-99 or "No Due Date").

3.6.14 If a numeric value is selected, the user selects a due date unit from the dropdown (options: Days, Weeks, Months).

3.6.15 The user clicks outside the panel or clicks a save/close button to save the line item configuration.

3.6.16 The system saves the line item and updates the display in the center canvas.

3.6.17 The user repeats steps 3.5.1 through 3.6.16 to add additional line items as needed.

3.6.18 The user must add at least one line item per service section before the item can be published.

3.7 Builder Interface - Completing Creation

3.7.1 The user reviews the complete configuration in the center canvas: Item Name, Price, Description, Event Section with Services, and Line Items.

3.7.2 The user ensures all required fields are completed: Price is set, at least one line item exists per service section.

3.7.3 The user clicks the "Publish" button to publish the item.

3.7.4 The system validates all required fields and configurations.

3.7.5 Before publishing, the system verifies that the selected Event Type still exists in master data. If it has been deleted, the system blocks publish and displays: "The selected event type no longer exists. Please edit the item setup and select a valid event type."

3.7.6 If validation passes, the system changes the item status from Draft to Published.

3.7.7 The system closes the Builder and returns the user to the A-La-Carte Items List View.

3.7.8 The system displays a success toast: "A-La-Carte item created successfully."

3.7.9 The newly created item appears in the list without a Draft badge.

3.8 Exiting Builder Without Publishing

3.8.1 At any point in the Builder, the user clicks the close button, back button, or navigates away.

3.8.2 The system displays a confirmation dialog: "Your changes have been saved as Draft. You can continue editing later."

3.8.3 The user clicks "OK" or "Leave" to confirm exit.

3.8.4 The system returns the user to the A-La-Carte Items List View.

3.8.5 The item appears in the list with a "Draft" badge indicating it is not yet published.

3.8.6 The user can click Edit on the Draft item to return to the Builder and continue configuration.

3.9 Navigating Back from Step 2

3.9.1 While on Step 2, the user clicks the "Back" button.

3.9.2 The system navigates back to Step 1 with all previously entered data preserved.

3.9.3 The user can modify any Step 1 fields.

3.9.4 If the user changes the Brand selection, all Step 2 fields (Event Type and Service Types) are cleared when the user navigates to Step 2 again. The Event Type dropdown repopulates from the newly selected brand.

3.9.5 The user clicks "Next" to return to Step 2.

3.10 Canceling the Creation Wizard

3.10.1 While on Step 1 or Step 2 (before proceeding to Builder), the user clicks the "Cancel" button.

3.10.2 The system displays a confirmation dialog with a warning icon and title "Cancel A La Carte Item Creation?" and message "Are you sure you want to cancel? All entered data will be lost." The dialog displays two buttons: "Stay" (secondary) and "Exit" (primary/yellow).

3.10.3 If the user clicks "Exit", the system closes the wizard without saving and returns to the A-La-Carte Items List View.

3.10.4 If the user clicks "Stay", the system keeps the wizard open with all data intact.

3.11 Editing Package Events and Services in Builder

3.11.1 While in the Builder, the user clicks the "Edit Event and Services" button in the Item Settings sidebar under "Package Events and Services".

3.11.2 The system opens the "Edit Package Events and Services" modal.

3.11.3 The modal displays the currently selected Event Type with a dropdown to change it, and the selected Service Types with options to add or remove services.

3.11.4 Each Service Type row displays: Service name dropdown, a "+" button to add another service, and a delete (trash) icon to remove the service.

3.11.5 The user can change the Event Type by selecting a different option from the Event Type dropdown. The dropdown is filtered by the item's brand.

3.11.6 The user can add a new Service Type by clicking the "+" button and selecting from the "Select service type" dropdown.

3.11.7 The user can remove a Service Type by clicking the delete icon next to the service. At least one service must remain.

3.11.8 If the user removes a service that has existing line items, the system displays a warning: "Removing this service will delete all associated line items. This action cannot be undone." with "Cancel" and "Remove" buttons.

3.11.9 The user clicks "Proceed to Builder" to apply changes and return to the Builder.

3.11.10 The system updates the Builder to reflect the new Event Type and Service configuration.

3.11.11 If a service was removed, all line items under that service are permanently deleted.

3.11.12 The user clicks "Cancel" to close the modal without applying changes.

3.12 Editing an Existing Event-Type Item

3.12.1 The user clicks "Edit" from the Actions menu on an existing Event-type item in the A-La-Carte Items List View.

3.12.2 The system opens the Builder directly with all item data loaded. The wizard steps (Step 1, Step 2) are bypassed.

3.12.3 The Builder displays the item name, price, description, event section with services, and all configured line items.

3.12.4 If the item is in Draft status, the primary action button displays "Publish".

3.12.5 If the item is in Published status, the primary action button displays "Publish Changes".

3.12.6 The user can edit all fields: price, description, line items, deliverable settings, and taxable settings.

3.12.7 The user can click "Edit Event and Services" to modify the Event Type or Service Types (see Section 3.11), unless the item is linked to packages.

3.12.8 The Brand is locked and cannot be changed. It is displayed in the sidebar as read-only with greyed/disabled styling. To use a different brand, the user must duplicate the item.

3.12.9 When the user clicks "Publish" (for Draft items), the system validates and publishes the item. Success toast: "A-La-Carte item created successfully."

3.12.10 When the user clicks "Publish Changes" (for Published items), the system validates and updates the existing record. The item remains Published. Success toast: "A-La-Carte item updated successfully."

3.12.11 All changes in edit mode are auto-saved.

3.12.12 When the Builder opens for editing, the system checks if the item is linked to any packages (Draft or Published status).

3.12.13 If the item is linked to one or more packages, the system displays a warning banner at the top of the Item Settings sidebar with a warning icon: "Item Type, Event Type and Service Type cannot be changed because this item is linked to one or more packages. Remove from all packages to edit."

3.12.14 When linked to packages, the "Edit Event and Services" button is hidden/disabled. The Package Events and Services section displays the current Event Type and Service Types as read-only.

3.12.15 All other fields remain editable: Item Name, Description, Item Price, line item configurations, Save as preset, Deliverable settings, and Taxable.

3.12.16 If the item is not linked to any packages, the "Edit Event and Services" button is visible and functional, allowing full editing of Event Type and Service Types.

4. FUNCTIONAL LOGIC

4.1 Wizard Initialization

• When the user clicks "Create New" from the A-La-Carte Items List View, the system opens the creation wizard.
• The wizard displays two tabs: "Add-on" and "Event", with the "Add-on" tab selected by default.
• Each tab has an info icon (ℹ️) that displays a tooltip on hover explaining the purpose of that item type.
• Add-on Tab Tooltip: "Use this for a single line item added to an existing package or event. Examples: extra hours of coverage, an Instagram video, extra edits, or another upgrade. Does not create a separate event, folder, or schedule."
• Event Tab Tooltip: "Use this when the à la carte item is a separate event the client may book in addition to the main one. Examples: rehearsal dinner, welcome party, or engagement session. Creates its own event/folder in the project so you can assign shooters, manage details, and track it separately."
• Selecting the "Event" tab initiates the Event-type creation flow (this FRD).
• The wizard header dynamically updates to show the current step: "Create A La Carte - Event: Step 1" or "Create A La Carte - Event: Step 2".
• The system initializes all form fields with default values: Name as empty, Description as empty, Price as "$0.00", Brand as "Select a brand".

4.2 Step 1 Field Validation

• Name Field: Required; maximum 100 characters; must be unique within the selected brand (case-insensitive comparison); leading and trailing whitespace is automatically trimmed.
• Description Field: Optional; maximum 500 characters; no uniqueness requirement.
• Price Field: Required; must be a valid numeric value; must be greater than or equal to 0; negative values are not allowed; price of $0.00 is valid. Price can also be modified in the Builder.
• Brand Field: Required; must select a valid brand from the dropdown; brand becomes locked (read-only) after creation and cannot be changed during editing.

4.3 Step 1 to Step 2 Navigation

• When the user clicks "Next" on Step 1, the system performs validation on all required fields.
• If Name is empty after trimming, the system displays: "Item name is required."
• If Name already exists within the selected brand, the system displays: "Item name already exists."
• If Price is empty, the system displays: "Price is required."
• If Price is not a valid number or is negative, the system displays: "Price must be a positive number."
• If Brand is not selected, the system displays: "Brand is required."
• If any validation fails, the system prevents navigation and displays inline error messages below the respective fields.
• If all validations pass, the system stores the Step 1 data in memory and navigates to Step 2.
• If the user returns to Step 1 via Back and changes the Brand selection, all Step 2 fields (Event Type and Service Types) are cleared when the user navigates to Step 2 again. The Event Type dropdown repopulates from the newly selected brand.

4.4 Step 2 Field Configuration

• Event Type Dropdown: Required; single-select dropdown; populated with event types filtered based on the Brand selected in Step 1; user must select exactly one event type.
• Service Types: Required; multi-select interface; displays available services (Photography, Videography, Content Creation) filtered based on the Brand selected in Step 1; user must select at least one service; multiple services can be selected.
• The Event Type selected determines which new event will be created in the project when the proposal is signed.
• The Service Types selected determine which service sections will appear in the Builder, each requiring at least one line item.

4.5 Step 2 to Builder Navigation

• When the user clicks "Proceed to Builder", the system performs validation on Step 2 fields.
• If Event Type is not selected, the system displays: "Event type is required."
• If no Service Type is selected, the system displays: "Select at least one service."
• If validation passes, the system creates a Draft record in the database with: unique ID, name, description, price, brand_id, type: "event_creation", event_type_id (single ID), service_types (array of IDs), status: "draft", created_at, created_by, and agency_id.
• The system then opens the Builder interface with the Draft item loaded.
• If the Draft save fails when "Proceed to Builder" is clicked, the system displays: "Failed to save item. Please try again." and keeps the user on Step 2. The Builder does not open. The user can retry by clicking "Proceed to Builder" again.

4.6 Builder Interface Structure

• The Builder interface consists of a center canvas for visual configuration and a right sidebar for detailed settings.
• The center canvas displays: Item Name (with Draft badge), Price field (editable), Description field (editable), and Event Section(s).
• The Event Section is labeled with the Event Type name in uppercase (e.g., "REHEARSAL DINNER").
• Under each Event Section, the system displays Service sub-sections for each selected service type.
• Each Service sub-section has an area for line items.
• The right sidebar displays contextual settings panels: Item Settings (default) or Line Item Settings (when line item clicked).
• The Item Settings sidebar includes the Package Events and Services section showing current Event Type and Service Types with an "Edit Event and Services" button.

4.7 Line Item Configuration

• Line items are added within each Service sub-section in the Builder.
• Each service section must have at least one line item before the item can be published.
• Line item configuration follows the same logic as Package Builder (FRD #3): Type (Custom or Smart Field), Name or Smart Field selection, Description (optional), Quantity, Deliverable toggle, and Due Date configuration.
• Type - Custom: User enters a free-form name for the line item.
• Type - Smart Field: User selects from predefined smart fields (e.g., Hours Coverage, Number of Edited Images, Additional Hours). Some smart fields require secondary value input.
• Save as Preset Toggle: Optional; defaults to OFF; located above the Deliverable toggle. When ON, the system saves the line item configuration as a reusable preset that appears in the Add Deliverable list when manually adding deliverables. An info icon displays tooltip on hover: "Turn this on to save these settings as a preset. It will appear in the Add Deliverable list when manually adding deliverables."
• Deliverable Toggle: When ON, the line item is tracked in Post-Production with a configurable due date.
• Due Date Configuration: Value dropdown (1-99 or "No Due Date") and Unit dropdown (Days, Weeks, Months). Due date is calculated from the event date.

4.8 Line Item Validation

• Each line item must have either a Custom name entered or a Smart Field selected.
• If Deliverable toggle is ON and no Due Date value is selected, the system displays: "Deliverable due date value is required."
• If Deliverable toggle is ON, a numeric value is selected, and no Unit is selected, the system displays: "Deliverable due date unit is required."
• Line items with incomplete configuration are highlighted with an error indicator.

4.9 Publishing the Event Item

• The "Publish" button is displayed in the Builder interface for Draft items.
• The "Publish Changes" button is displayed for Published items being edited.
• When clicked, the system performs final validation: Price must be set, each service section must have at least one configured line item, all line items must be complete.
• Before publishing, the system verifies that the selected Event Type still exists in master data. If it has been deleted, the system blocks publish and displays: "The selected event type no longer exists. Please edit the item setup and select a valid event type."
• The system re-validates that the item name is still unique within the selected brand at the time of final save. If a conflict has been created since creation, the system displays: "Item name already exists." and prevents saving.
• If validation fails, the system displays an error message listing the issues and prevents publishing.
• If validation passes for a Draft item, the system updates the item record: changes status from "draft" to "published", updates the modified_at timestamp.
• If validation passes for a Published item, the system updates the existing record and the item remains Published.
• After successful publishing, the system closes the Builder, displays a success toast, and returns to the list view.
• The item appears in the list without a Draft badge and is now available for linking to packages.

4.10 Draft Auto-Save Behavior

• When the user clicks "Proceed to Builder", the system saves the item as Draft immediately.
• Any changes made in the Builder (price, description, line items) are auto-saved to the Draft record.
• If the user exits the Builder without clicking "Publish", the item remains in Draft status.
• Draft items appear in the A-La-Carte Items List View with a "Draft" badge.
• Draft items can be edited by clicking the Edit action, which reopens the Builder with all previously saved data.
• Draft items cannot be linked to packages; only Published items can be linked.
• If the user exits the Builder immediately after entering (no changes made beyond what was saved at "Proceed to Builder"), the exit behavior is the same — the Draft item is preserved. There is no discard option once a Draft has been created. Users who wish to remove an accidental Draft must delete it from the A-La-Carte Items List View.

4.11 Data Preservation During Wizard Navigation

• When the user navigates from Step 1 to Step 2 and back, all entered data is preserved in memory.
• Data is only cleared when the user explicitly cancels the wizard (before proceeding to Builder).
• If the user switches from the "Event" tab to the "Add-on" tab, the system first checks if any data has been entered in the Event form. If data exists, the system displays a confirmation dialog: "Switching tabs will clear all data entered on this tab. Are you sure?" with "Stay" and "Switch Tab" buttons. If the user clicks "Switch Tab", the Event form data is cleared and the Add-on tab loads. If the user clicks "Stay", the Event tab remains active with all data intact. If no data has been entered, the tab switch proceeds without confirmation.
• Once the user proceeds to the Builder, the item is saved as Draft and data persists even if the browser is closed.

4.12 Edit Package Events and Services

• The "Edit Event and Services" button is accessible from within the Builder in the Item Settings sidebar under "Package Events and Services".
• The modal displays the current Event Type and Service Types configuration.
• Event Type: Single-select dropdown filtered by the item's brand. The user can change the selected event type. Changing the event type updates the Event Section header in the Builder.
• Service Types: The user can add or remove services. At least one service must remain at all times.
• Adding a Service: Clicking the "+" button displays a "Select service type" dropdown. Selecting a service adds it to the list and creates a new service section in the Builder.
• Removing a Service: Clicking the delete icon next to a service removes it. If the service has existing line items, the system displays a warning before removal. Confirming removal permanently deletes all line items under that service.
• Changes made in this modal are applied when the user clicks "Proceed to Builder" (or "Apply Changes").
• Clicking "Cancel" closes the modal without applying any changes.

4.13 Edit Mode Logic

• When the user clicks "Edit" from the Actions menu on an existing Event-type item, the system opens the Builder directly. The wizard steps (Step 1, Step 2) are bypassed.
• The Builder loads all existing data: item name, price, description, event type, services, line items, deliverable settings, and taxable settings.
• The Brand field is locked and cannot be changed. It is displayed in the sidebar as read-only with greyed/disabled styling.
• For Draft Items: The primary action button displays "Publish". Clicking it validates and publishes the item. Success toast: "A-La-Carte item created successfully."
• For Published Items: The primary action button displays "Publish Changes". Clicking it runs the same validation and updates the existing record. The item remains Published. Success toast: "A-La-Carte item updated successfully."
• All changes in edit mode are auto-saved.
• Proposal Impact: Editing a Published Event-type item follows the same proposal impact rules as editing A-La-Carte Add-On items: Draft and Published proposals reflect the updated item when next opened. Proposals already sent to clients retain their snapshot and are unaffected.

4.14 Package Link Detection for Edit Restrictions

• When the Builder opens for editing, the system queries whether the Event-type A La Carte item is currently linked to any package (Draft or Published status).
• If the item is linked to one or more packages:
  • A warning banner is displayed at the top of the Item Settings sidebar with warning icon.
  • Warning message: "Item Type, Event Type and Service Type cannot be changed because this item is linked to one or more packages. Remove from all packages to edit."
  • The "Edit Event and Services" button is hidden/disabled.
  • The Package Events and Services section displays the current configuration as read-only text.
  • Event Type and Service Types cannot be modified.
  • The locked state is determined at Builder open time. If packages are unlinked while the Builder is open, the restrictions remain until the user closes and reopens the Builder.
• If the item is not linked to any packages:
  • The "Edit Event and Services" button is visible and functional.
  • Event Type and Service Types can be modified via the Edit modal.
  • No warning banner is displayed.
• Line items within the Event item remain fully editable regardless of package link status.

5. FIELD DETAILS & VALIDATIONS

5.1 Step 1: General Details Fields

Field Name

Field Type

Required

Max Length

Default Value

Validation Rules

Name

Text Input

Yes

100 chars

Empty

Cannot be empty; must be unique within brand (case-insensitive); auto-trim whitespace

Description

Text Area

No

500 chars

Empty

Optional; no validation

Price

Numeric Input

Yes

N/A

$0.00

Must be numeric; must be >= 0; cannot be negative; editable in Builder too

Brand

Dropdown

Yes

N/A

"Select a brand"

Must reference valid brand; locked after creation (displayed as read-only with greyed/disabled styling in edit mode)

Customer can choose quantity

Toggle

No

N/A

OFF

Optional; determines if clients can select quantity 1-99

5.2 Step 2: Event & Service Types Fields

Field Name

Field Type

Required

Max Length

Default Value

Validation Rules

Event Type

Dropdown

Yes

N/A

Empty

Must select exactly one event type; filtered by Brand

Service Types

Multi-Select Buttons

Yes

N/A

None selected

Must select at least one service; multiple allowed; filtered by Brand

5.3 Builder: Item Settings Fields

Field Name

Field Type

Required

Max Length

Default Value

Validation Rules

Item Name

Text Input

Yes

100 chars

Pre-filled from Step 1

Cannot be empty; unique within brand

Item Description

Text Area

No

500 chars

Pre-filled from Step 1

Optional

Item Price

Numeric Input

Yes

N/A

Pre-filled from Step 1

Must be numeric; >= 0

5.4 Builder: Line Item Settings Fields

Field Name

Field Type

Required

Max Length

Default Value

Validation Rules

Line Item Type

Dropdown

Yes

N/A

Empty

Must select "Custom" or "Smart Field"

Name

Text Input

Yes (if Custom)

250 chars

Empty

Required when Type is Custom; matches Package Builder line item name limit

Smart Field

Dropdown

Yes (if Smart Field)

N/A

Empty

Required when Type is Smart Field

Secondary Value

Numeric Input

Conditional

N/A

Empty

Required for certain Smart Fields

Description

Text Area

No

500 chars

Empty

Optional

Quantity

Numeric Input

No

N/A

1

Must be positive integer

Save as Preset

Toggle

No

N/A

OFF

Optional; when ON, saves line item configuration as reusable preset for Add Deliverable list

Deliverable

Toggle

No

N/A

OFF

Enables due date fields when ON

Due Date Value

Dropdown

Yes (if Deliverable ON)

2 digits

Empty

Options: 1-99 or "No Due Date"

Due Date Unit

Dropdown

Yes (if numeric value)

N/A

Empty

Options: Days, Weeks, Months

Taxable

Toggle

No

N/A

ON

Determines tax applicability

5.5 Edit Package Events and Services Modal Fields

Field Name

Field Type

Required

Description

Event Type

Dropdown

Yes

Single-select; filtered by item's brand; displays current event type

Service Type

Dropdown

Yes

Service selection for each row

Add Service (+)

Button

N/A

Adds a new service type row

Delete Service (trash)

Icon Button

N/A

Removes the service; shows warning if line items exist

Cancel

Button (Secondary)

N/A

Closes modal without applying changes

Proceed to Builder

Button (Primary)

N/A

Applies changes and returns to Builder

5.6 Cancel Confirmation Dialog Fields

Field Name

Field Type

Description

Warning Icon

Icon

Yellow warning triangle icon at top of dialog

Dialog Title

Text (Display)

"Cancel A La Carte Item Creation?"

Dialog Message

Text (Display)

"Are you sure you want to cancel? All entered data will be lost."

Stay Button

Button (Secondary)

Closes dialog; keeps wizard open with data intact

Exit Button

Button (Primary/Yellow)

Confirms cancellation; closes wizard; discards all data

5.7 Navigation Buttons

Button

Location

Action

Cancel

Step 1, Step 2 (left side)

Shows confirmation dialog; closes wizard if confirmed

Next

Step 1 (right side)

Validates Step 1 fields; navigates to Step 2

Back

Step 2 (left side)

Returns to Step 1; preserves all data

Proceed to Builder

Step 2 (right side)

Validates Step 2 fields; saves as Draft; opens Builder

Publish

Builder (primary action) - Draft items

Validates all; publishes item; closes Builder

Publish Changes

Builder (primary action) - Published items

Validates all; updates existing record; item remains Published

5.8 Tab Tooltips

Section

Tooltip Content

Add-on Tab

"Use this for a single line item added to an existing package or event. Examples: extra hours of coverage, an Instagram video, extra edits, or another upgrade. Does not create a separate event, folder, or schedule."

Event Tab

"Use this when the à la carte item is a separate event the client may book in addition to the main one. Examples: rehearsal dinner, welcome party, or engagement session. Creates its own event/folder in the project so you can assign shooters, manage details, and track it separately."

Save as preset

"Turn this on to save these settings as a preset. It will appear in the Add Deliverable list when manually adding deliverables."

5.9 Edit Mode - Locked Configuration When Linked to Packages

Element

Locked When Linked

Visual State

Edit Event and Services button

Yes

Hidden/disabled

Event Type

Yes (via Edit modal)

Read-only display in sidebar

Service Types

Yes (via Edit modal)

Read-only display in sidebar

Item Name

No

Editable

Description

No

Editable

Item Price

No

Editable

Line Items

No

Editable

Save as preset (line item)

No

Editable

Deliverable (line item)

No

Editable

Taxable (line item)

No

Editable

5.10 Edit Mode Warning Banner (Event Builder)

Element

Description

Warning Icon

Yellow/orange warning icon

Warning Message

"Item Type, Event Type and Service Type cannot be changed because this item is linked to one or more packages. Remove from all packages to edit."

Position

Top of Item Settings sidebar

Visibility

Only when item is linked to one or more packages

6. SUCCESS MESSAGE HANDLING

Validation Scenario

Success Message

Display Type

Post-Success Action

Event item created and published

"A-La-Carte item created successfully."

Toast (green, top-right, 5 seconds)

Builder closes; user returned to list view; item appears without Draft badge

Event item updated (Published item)

"A-La-Carte item updated successfully."

Toast (green, top-right, 5 seconds)

Builder closes; user returned to list view

Item saved as Draft

"Your changes have been saved as Draft."

Dialog or Toast

User can exit; item appears with Draft badge

Navigation from Step 1 to Step 2

No explicit message

Visual transition

Step 2 form displayed

Navigation from Step 2 to Builder

No explicit message

Visual transition

Builder interface displayed with Draft badge

Line item added successfully

No explicit message

Visual update

Line item appears in service section

Service removed via Edit modal

No explicit message

Visual update

Service section removed from Builder; associated line items deleted

7. ERROR MESSAGE HANDLING

Field

Validation Scenario

Error Message

Name

Empty after trimming

"Item name is required."

Name

Duplicate within same brand

"Item name already exists."

Name

Exceeds 100 characters

"Item name must be 100 characters or less."

Description

Exceeds 500 characters

"Description must be 500 characters or less."

Price

Empty

"Price is required."

Price

Not a valid number

"Price must be a valid number."

Price

Negative value

"Price must be a positive number."

Brand

Not selected

"Brand is required."

Event Type

Not selected

"Event type is required."

Event Type

Deleted from master data before publish

"The selected event type no longer exists. Please edit the item setup and select a valid event type."

Service Types

None selected

"Select at least one service."

Line Items

Service section has no line items

"Each service must have at least one line item."

Line Item Type

Not selected

"Line item type is required."

Line Item Name

Empty (when Custom type)

"Line item name is required."

Smart Field

Not selected (when Smart Field type)

"Please select a smart field."

Due Date Value

Deliverable ON but value not selected

"Deliverable due date value is required."

Due Date Unit

Deliverable ON, numeric value, unit not selected

"Deliverable due date unit is required."

Publish

Incomplete configuration

"Please complete all required fields before publishing."

Proceed to Builder

Server error during Draft save

"Failed to save item. Please try again."

Save Operation

Server error

"Failed to save A-La-Carte item. Please try again."

Edit Events and Services

Removing service with existing line items

Warning: "Removing this service will delete all associated line items. This action cannot be undone."

Network

Connection lost

"Connection lost. Please check your internet connection and try again."

Session

User session expired

"Your session has expired. Please log in again."

8. EDGE CASES

Scenario

Expected Behavior

User selects 3 services then removes one before proceeding to Builder

Builder displays only 2 service sections; removed service is not shown

User creates item with Price $0.00

System allows; valid free event add-on

User exits Builder without adding any line items

Item saved as Draft; cannot be published until line items added

User adds line item to one service but not the other

Publish blocked; error indicates which service needs line items

User changes Event Type in Step 2 after initially selecting one

System updates; Builder will show new event type as section header

Draft item exists; user starts new creation

System allows; multiple Draft items can exist

User closes browser while in Builder

Item already saved as Draft; user can resume by editing

User tries to link Draft item to package

System prevents; only Published items can be linked

Two users edit same Draft item simultaneously

Last save wins; no conflict resolution

Brand has no event types configured

Event Type dropdown shows empty; user cannot proceed

User enters very long description (500 chars)

System accepts; displays with scroll if needed

User deletes all line items from a service section

Publish blocked until at least one line item added

Network disconnects while auto-saving Draft

System retries; shows error if persistent failure

User returns to Step 1 via Back and changes Brand

All Step 2 fields (Event Type, Service Types) are cleared when navigating to Step 2 again; Event Type dropdown repopulates from new brand

User exits Builder immediately after entering (no changes made)

Draft item is preserved; no discard option exists; user must delete from List View to remove accidental Draft

Event Type deleted from master data before user clicks Publish

System blocks publish and displays: "The selected event type no longer exists. Please edit the item setup and select a valid event type."

User edits Published Event-type item linked to proposals

Draft and Published proposals reflect updated item when next opened; proposals already sent to clients retain their snapshot and are unaffected

Server error when clicking "Proceed to Builder"

System displays "Failed to save item. Please try again." and keeps user on Step 2; Builder does not open

User switches from Event tab to Add-on tab after entering data

System displays confirmation dialog before clearing data; user can choose "Stay" or "Switch Tab"

User removes service with existing line items via Edit modal

System displays warning; confirming removal permanently deletes all line items under that service

User opens Builder for Event item linked to packages

Warning banner displayed in sidebar; "Edit Event and Services" button is hidden/disabled

User opens Builder for Event item not linked to any packages

No warning banner; "Edit Event and Services" button is visible and functional

Item is unlinked from all packages while Builder is open

Restrictions remain until Builder is closed and reopened

User tries to modify Event Type or Services when linked to packages

Not possible; "Edit Event and Services" button is hidden/disabled

9. ACCEPTANCE CRITERIA

AC1: Event Tab Opens Event Creation Flow

• Given a user clicks "Create New" and selects the "Event" tab,
• When the tab is selected,
• Then the system must display Step 1 for Event-type item creation with Name, Description, Price, Brand, and Quantity toggle fields.

AC2: Event Type Filtered by Brand

• Given a user selects Brand "Emma Taylor" in Step 1,
• When the user proceeds to Step 2 and opens the Event Type dropdown,
• Then only event types associated with "Emma Taylor" brand must be displayed.

AC3: Multiple Service Selection Allowed

• Given the user is on Step 2,
• When the user clicks on Photography and Videography service buttons,
• Then both services must be selected and highlighted, showing only services configured for the selected brand.

AC4: Proceed to Builder Saves as Draft

• Given a user completes Step 1 and Step 2 and clicks "Proceed to Builder",
• When the Builder opens,
• Then the item must be saved with Draft status and appear in the list view with a Draft badge if the user exits.

AC5: Builder Displays Service Sections

• Given a user selected Photography and Videography in Step 2,
• When the Builder opens,
• Then two service sections must be displayed under the Event Section header.

AC6: Event Section Header Shows Event Type

• Given a user selected "Rehearsal Dinner" as the Event Type in Step 2,
• When the Builder opens,
• Then the Event Section header must display "REHEARSAL DINNER" in uppercase.

AC7: At Least One Line Item Per Service Required

• Given a user has two service sections and added line items only to Photography,
• When the user clicks "Publish",
• Then the system must display an error indicating Videography section needs at least one line item.

AC8: Line Item Configuration Same as Package Builder

• Given the user clicks on a line item in the Builder,
• When the Line Item Settings panel opens,
• Then it must display the same fields as Package Builder: Type, Name/Smart Field, Description, Quantity, Save as preset, Deliverable toggle, Due Date, and Taxable.

AC9: Publish Publishes the Event Item

• Given a user has completed all required configuration in the Builder,
• When the user clicks "Publish",
• Then the item status must change from Draft to Published and the Draft badge must be removed.

AC10: Draft Items Cannot Be Linked to Packages

• Given an Event item has Draft status,
• When a user tries to link it to a package in the Package Builder,
• Then the item must not appear in the available items list (only Published items shown).

AC11: Exit Without Publishing Preserves Draft

• Given a user is in the Builder with unsaved changes,
• When the user clicks close or navigates away,
• Then the system must save changes to Draft and display a confirmation message.

AC12: Canceling Wizard Before Builder Discards Data

• Given a user is on Step 1 or Step 2 and has entered data,
• When the user clicks "Cancel" and clicks "Exit",
• Then all entered data must be discarded and no Draft item created.

AC13: Back Button Preserves Data

• Given a user has filled Step 1, navigated to Step 2, and filled Step 2,
• When the user clicks "Back",
• Then all Step 1 and Step 2 data must be preserved.

AC14: Deliverable Due Date Same as Package Builder

• Given a user toggles Deliverable ON for a line item,
• When configuring the due date,
• Then the same options must be available as Package Builder: 1-99 or "No Due Date" for value, Days/Weeks/Months for unit.

AC15: Cancel Confirmation Dialog

• Given a user has entered data in the wizard,
• When the user clicks "Cancel",
• Then a confirmation dialog must appear with title "Cancel A La Carte Item Creation?", message "Are you sure you want to cancel? All entered data will be lost.", and buttons "Stay" and "Exit".

AC16: Tab Tooltips Display

• Given a user opens the A La Carte creation wizard,
• When the user hovers over the info icon next to the "Add-on" or "Event" tab,
• Then the system must display the appropriate tooltip explaining when to use that item type.

AC17: Edit Package Events and Services Accessible

• Given a user is in the Builder for an Event-type item not linked to any packages,
• When the user clicks "Edit Event and Services" in the sidebar,
• Then the Edit modal must open displaying the current Event Type and Service Types with options to modify them.

AC18: Service Removal Warning

• Given a user is in the Edit Package Events and Services modal and a service has existing line items,
• When the user clicks the delete icon for that service,
• Then the system must display a warning before allowing removal.

AC19: Draft Item Edit Button Label

• Given a user opens the Builder to edit a Draft Event-type item,
• When the Builder loads,
• Then the primary action button must display "Publish".

AC20: Published Item Edit Button Label

• Given a user opens the Builder to edit a Published Event-type item,
• When the Builder loads,
• Then the primary action button must display "Publish Changes".

AC21: Published Item Update Success Message

• Given a user clicks "Publish Changes" on a Published Event-type item,
• When the update completes successfully,
• Then the system must display: "A-La-Carte item updated successfully."

AC22: Tab Switch Confirmation

• Given a user has entered data in the Event tab,
• When the user clicks the "Add-on" tab,
• Then the system must display a confirmation dialog: "Switching tabs will clear all data entered on this tab. Are you sure?" with "Stay" and "Switch Tab" buttons.

AC23: Save as Preset Toggle in Builder

• Given a user is configuring a line item in the Builder,
• When the user views the Line Item Settings panel,
• Then a "Save as preset" toggle must be displayed above the Deliverable toggle with an info icon showing tooltip on hover.

AC24: Brand Change Clears Step 2

• Given a user is on Step 2 and navigates Back to Step 1,
• When the user changes the Brand selection and clicks Next,
• Then all Step 2 fields (Event Type, Service Types) must be cleared and Event Type dropdown must show options for the new brand.

AC25: Edit Event and Services Disabled When Linked to Packages

• Given a user opens the Builder for an Event item that is linked to one or more packages,
• When the Builder loads,
• Then the "Edit Event and Services" button must be hidden/disabled and a warning banner must be displayed in the Item Settings sidebar.

AC26: Edit Event and Services Enabled When Not Linked

• Given a user opens the Builder for an Event item that is not linked to any packages,
• When the Builder loads,
• Then the "Edit Event and Services" button must be visible and functional with no warning banner.

AC27: Warning Banner Message in Event Builder

• Given a user opens the Builder for an Event item linked to packages,
• When the Builder loads,
• Then the warning banner must display: "Item Type, Event Type and Service Type cannot be changed because this item is linked to one or more packages. Remove from all packages to edit."

10. MANUAL TEST CASES

Test cases for this module will be documented in a separate Excel file.

Test Case Excel File:

11. DEPENDENCIES

Module/System

Dependency Type

Impact if Unavailable

A-La-Carte Items List View (FRD #5)

Navigation Dependency

Cannot access "Create New" button; cannot return to list after creation

Package Builder (FRD #3)

Reference Dependency

Line item configuration logic referenced; consistency required

Brand Master Data

Data Dependency

Brand dropdown empty; Event Type filtering non-functional

Event Types Master Data

Data Dependency

Event Type dropdown empty; cannot complete Step 2

Service Types Master Data

Data Dependency

Service selection unavailable; cannot proceed to Builder

Post-Production Module

Functional Dependency

Deliverable items cannot be tracked; due date calculations non-functional

Project Module

Functional Dependency

New events cannot be created when proposal signed

Proposal Module

Functional Dependency

Event items cannot appear in proposals

User & Authentication Module

Access Dependency

Cannot verify user permissions; wizard access not controlled

Database Service

System Dependency

Cannot save Draft or Published items; all operations fail

12. REFERENCES

Figma Link:

☑️ Package Impact on Other Modules

PACKAGE IMPACT ON OTHER MODULES - FRD

Module: Package Impact on Other Modules
Document Version: 1.0

1. MODULE OVERVIEW

1.1 Document Name

Package Impact on Other Modules

1.2 Purpose

This document serves as a reference guide documenting how the Packages module integrates with and impacts other system modules. It consolidates the cross-module interactions, data flows, and business logic that occur when packages are used throughout the application lifecycle—from proposal creation to project completion and reporting. This document does not define new functionality but rather provides a comprehensive view of existing integrations documented across FRDs #1-7.

1.3 Scope

This document covers the impact of Packages and A-La-Carte items on the following modules:

• Proposal Module (package selection, client interaction, snapshot creation)
• Project Module (event and service creation after proposal signing)
• Post-Production Module (deliverable tracking and due date management)
• Invoice Module (automatic invoice line item generation)
• Reports Module (sales tracking and analytics)

1.4 Key Integration Points

Proposal Integration Packages are the primary pricing and service configuration units used in proposals. Users select Package Groups when creating proposal templates, and clients interact with packages to choose their preferred options and optional A-La-Carte items.

Project Integration When a proposal is signed, the selected package configuration is used to automatically create events and services within the existing project. Smart field values from packages map to project and event details.

Post-Production Integration Line items marked as deliverables in packages are tracked in the Post-Production module after the event date, with due dates calculated based on configured rules.

Invoice Integration Package prices and A-La-Carte item prices are automatically used to generate invoice line items when a proposal is signed.

Reports Integration Package and A-La-Carte item selection data feeds into the Sales Report for tracking which items are sold most frequently.

2. PROPOSAL MODULE INTEGRATION

2.1 Package Group Selection in Proposals

• When a user creates a proposal template, they select one or more Package Groups to include in the proposal.
• A single proposal can contain multiple Package Groups, allowing clients to choose options from different categories.
• The user selects Package Groups (not individual packages); the client sees all packages within each selected group.
• Only Package Groups with "Published" status are available for selection in proposal templates.
• Draft Package Groups do not appear in the proposal template builder.

2.2 Client View of Packages in Proposals

• When a client views a proposal, they see all packages within each Package Group included by the agency.
• The client must select exactly one package from each Package Group in the proposal.
• Package details displayed to the client include: package name, description, price, and associated events and services.
• Line items within packages are displayed to show what deliverables and services are included.
• The client cannot modify package contents; they can only select which package they prefer.

2.3 A-La-Carte Items in Proposals

• A-La-Carte items linked to a package (via the Package Builder) are automatically displayed when the client selects that package.
• A-La-Carte items appear as optional add-ons below the selected package.
• The client can select or deselect any A-La-Carte items according to their preferences.
• There is no limit to how many A-La-Carte items a client can select.
• When the "Customer can choose quantity" toggle is ON for an A-La-Carte item, the client can select a quantity between 1 and 10.
• Selecting or deselecting A-La-Carte items dynamically updates the total proposal price shown to the client.
• Both Add-On type and Event-type A-La-Carte items appear in the proposal if linked to the selected package.

2.4 Visibility Rules for A-La-Carte Items

• Add-On type A-La-Carte items appear in proposals only when the selected package includes a matching Event Type AND Service Type.
• Each Add-On item has one Event Type and one Service Type configured; visibility requires both to match the package.
• Event-type A-La-Carte items follow the same visibility rules based on their configured Event Type and Service Types.
• If a package does not match the A-La-Carte item's visibility rules, the item is hidden from the client.Y

2.5 Proposal Pricing Calculation

• The base proposal price is determined by the selected package price from each Package Group.
• A-La-Carte item prices are added to the base price when selected by the client.
• If quantity selection is enabled for an A-La-Carte item, the item price is multiplied by the selected quantity.
• Tax calculations are applied based on the taxable settings of each package line item and A-La-Carte item.
• The total proposal price updates in real-time as the client makes selections.

2.6 Draft and Published Proposal States

• Draft Proposals: Proposals being created or edited by agency users. Draft proposals do NOT store a snapshot of package data; they store only the Package Group ID and fetch the latest package data each time the proposal is opened or previewed.
• Published Proposals: Proposals that are ready to be sent to clients or used in projects. Published proposals also do NOT store a snapshot; they fetch the latest package data.
• Sent Proposals: Proposals that have been sent to a client from a project. A snapshot is created at send time, capturing the complete package configuration.

2.7 Snapshot Creation

• A snapshot of all package data is created only when a proposal is sent to a client from a project.
• The snapshot captures the complete state of all package configurations at the moment of sending.
• Snapshot contents include: all Package Group details (names and descriptions), all packages within each group, all line items with their complete configurations (name, description, quantity, deliverable settings, due date rules, tax settings), all linked A-La-Carte items (both Add-On and Event types), service settings (number of contractors and hours of coverage), and all smart field values.
• Once a snapshot is created, subsequent edits to the source Package Group do NOT affect the sent proposal.
• The snapshot ensures that the client sees the exact configuration that was sent, regardless of later changes to packages.

2.8 Impact of Package Edits on Proposals

• Editing a Package Group updates the live record in the database.
• Draft and Published proposals that reference the edited Package Group will automatically reflect the changes when next opened or previewed.
• Sent proposals are NOT affected by package edits because they have independent snapshots.
• Users should be aware that editing a Package Group may affect multiple Draft and Published proposals simultaneously.

3. PROJECT MODULE INTEGRATION

3.1 Project and Proposal Relationship

• A project must exist before a proposal can be sent to a client.
• Projects are created either through a lead form submission or manual creation by agency users.
• Users cannot send a proposal without an existing project; proposals are sent only from within a project context.
• When a client signs a proposal, the selected package configuration is applied to the existing project.

3.2 Automatic Event and Service Creation

• When a proposal is signed, the system automatically creates events and services in the project based on the selected package configuration.
• Events are created according to the Event Types defined in the package (e.g., Wedding, Rehearsal Dinner, Engagement).
• Services are created within each event according to the Service Types defined in the package (e.g., Photography, Videography, Content Creation).
• The number of services and their configurations match the package settings.
• Contractors are NOT automatically assigned to services; only the service placeholders are created based on the package configuration.

3.3 Package Data Transfer to Project

• All package data from the signed proposal snapshot is transferred to the project.
• The project stores: event names and types, service types and configurations (number of contractors, hours of coverage), line items with descriptions and quantities, deliverable settings and due date rules, smart field values.
• This data becomes the project's working configuration and can be modified by agency users after signing.

3.4 Smart Field Mapping

• Smart fields configured in packages are mapped to specific fields in the project's event and service details.
• Examples of smart field mappings: "Hours Coverage" maps to the event service hours field, "Number of Edited Images" maps to the deliverable quantity field, "Second Shooter" maps to the additional contractor field.
• Smart field values are displayed primarily in the Event details section of the project.
• The mapping ensures consistency between what was promised in the proposal and what is tracked in the project.

3.5 Event-Type A-La-Carte Item Impact

• When a client selects an Event-type A-La-Carte item and signs the proposal, a new event is automatically created in the project.
• The new event's type matches the Event Type configured in the A-La-Carte item (e.g., Rehearsal Dinner, Engagement Shoot).
• The new event's date is set based on client input: if the client provided a date during proposal selection, that date is used; otherwise, the date is marked as "TBD" (To Be Determined).
• Services configured in the Event-type A-La-Carte item are assigned to the new event.
• Line items from the Event-type A-La-Carte item are copied to the project and associated with the new event.
• Service settings (number of contractors, hours of coverage) from the A-La-Carte item are applied to the new event's services.

3.6 Quantity Selection for Event-Type Items

• If the client selected a quantity greater than 1 for an Event-type A-La-Carte item, multiple events of the same type are created.
• Each event instance is created with the same configuration but with individual dates (typically marked as TBD for subsequent instances).
• This supports scenarios like multi-day events or multiple locations requiring separate event instances.

4. POST-PRODUCTION MODULE INTEGRATION

4.1 Deliverable Tracking Overview

• Line items marked as "Deliverable" in packages are tracked in the Post-Production module.
• Deliverables represent items that must be completed and delivered to the client after the event.
• The Post-Production module provides workflow tracking and deadline management for all deliverables.

4.2 When Deliverables Appear in Post-Production

• Deliverables are added to the Post-Production board after the associated event date has passed.
• At the time of proposal signing, deliverables are shown in the project's Post-Production widget as upcoming items.
• The full Post-Production board view becomes active after the event is completed.
• This timing ensures that post-production work is tracked only after the event has occurred and raw materials (photos, videos) are available.

4.3 Deliverable Data Transfer

• When deliverables are added to Post-Production, the following data is transferred: Deliverable name (from line item name or smart field name), Project name, Event name, Due date (calculated from event date plus configured offset).
• The deliverable appears as a task or item in the Post-Production board for assignment and tracking.

4.4 Due Date Calculation

• Due dates for deliverables are calculated from the associated event date.
• The calculation formula is: Event Date + Due Date Value + Due Date Unit.
• Example: If the event date is January 15 and the deliverable is configured as "10 Days after event," the due date is January 25.
• For deliverables with "No Due Date" configured, the item appears in Post-Production without a specific deadline.
• Due date units can be Days, Weeks, or Months as configured in the package line item.

4.5 Deliverables from A-La-Carte Items

• Deliverables from Add-On type A-La-Carte items are also tracked in Post-Production if the item has deliverable settings configured.
• Deliverables from Event-type A-La-Carte items are tracked under the new event created by that item.
• The due date calculation for A-La-Carte deliverables uses the associated event date (either the main event or the new event for Event-type items).

5. INVOICE MODULE INTEGRATION

5.1 Automatic Invoice Generation

• When a proposal is signed, an invoice is automatically created for the project.
• The invoice is generated based on the package and A-La-Carte item selections made by the client.
• Invoice generation is automatic; users do not need to manually create invoices after signing.

5.2 Package Price as Invoice Line Items

• The price of the selected package is added as a line item on the invoice.
• If the proposal contains multiple Package Groups and the client selected one package from each, each package price becomes a separate invoice line item.
• The package line item includes the package name and total price.
• Tax settings from the package determine whether the line item is taxable.

5.3 A-La-Carte Items as Invoice Line Items

• Each A-La-Carte item selected by the client is added as a separate line item on the invoice.
• The A-La-Carte line item includes the item name, quantity (if applicable), and price.
• If the client selected a quantity greater than 1, the line item shows the unit price multiplied by quantity.
• Tax settings from each A-La-Carte item determine whether the line item is taxable.

5.4 Tax Calculation

• Invoice line items are marked as taxable or non-taxable based on the package and A-La-Carte item configurations.
• The system calculates applicable taxes based on the agency's tax settings and the taxable status of each line item.
• Taxable amounts are itemized on the invoice according to tax rules.

5.5 Invoice Line Item Details

• Each invoice line item generated from packages includes: Item name (package name or A-La-Carte item name), Description (if configured), Quantity, Unit price, Total price (quantity × unit price), Tax status (taxable or non-taxable).

6. REPORTS MODULE INTEGRATION

6.1 Sales Report Integration

• Package and A-La-Carte item data feeds into the Sales Report within the Reports module.
• The Sales Report tracks which packages and A-La-Carte items are sold most frequently.
• This data helps agencies understand which offerings are most popular with clients.

6.2 Data Tracked for Reporting

• When a proposal is signed, the system records: Package Group selected, Specific package selected within each group, A-La-Carte items selected, Quantities selected for each item, Total revenue from packages, Total revenue from A-La-Carte items.
• This data is aggregated for reporting purposes.

6.3 Report Metrics

• The Sales Report provides metrics including: Most sold packages (by count and revenue), Most sold A-La-Carte items (by count and revenue), Revenue breakdown by package type, A-La-Carte item attach rate (percentage of proposals that include A-La-Carte selections).
• These metrics support business analysis and pricing strategy decisions.

📝 Note: The detailed Sales Report functionality will be documented in a separate FRD for the Reports module.

7. DATA FLOW SUMMARY

7.1 Package Lifecycle Data Flow

Stage

Data Flow

Source Module

Target Module

Package Creation

Package Group, Packages, Line Items, A-La-Carte Links created

Packages

Database

Proposal Creation

Package Group ID stored in proposal template

Packages

Proposals

Proposal Preview

Live package data fetched for display

Database

Proposals

Proposal Sent

Complete snapshot created and stored

Packages

Proposals

Proposal Signed

Snapshot data transferred to project

Proposals

Projects

Event Created

Services and line items created from snapshot

Projects

Projects

Deliverables Tracked

Deliverable data sent after event date

Projects

Post-Production

Invoice Generated

Package and A-La-Carte prices to line items

Proposals

Invoices

Sales Recorded

Selection data aggregated for reporting

Proposals

Reports

7.2 Snapshot Data Contents

Data Category

Included in Snapshot

Used By

Package Group Name & Description

✔ Yes

Proposals, Projects

Package Names & Descriptions

✔ Yes

Proposals, Projects, Invoices

Package Prices

✔ Yes

Proposals, Invoices

Line Items (All Fields)

✔ Yes

Projects, Post-Production

Deliverable Settings

✔ Yes

Post-Production

Due Date Rules

✔ Yes

Post-Production

Smart Field Values

✔ Yes

Projects

Service Settings (Contractors, Hours)

✔ Yes

Projects

A-La-Carte Items (Add-On Type)

✔ Yes

Proposals, Invoices

A-La-Carte Items (Event Type)

✔ Yes

Proposals, Projects, Invoices

Tax Settings

✔ Yes

Invoices

8. INTEGRATION RULES AND CONSTRAINTS

8.1 Package Status Rules

Package Status

Available in Proposals

Affects Sent Proposals

Can Be Deleted

Draft

❌ No

N/A

✔ Yes (if no Draft/Published proposals)

Published

✔ Yes

❌ No (snapshot independent)

Blocked if in Draft/Published proposals

8.2 Proposal Status Rules

Proposal Status

Has Snapshot

Affected by Package Edits

Blocks Package Deletion

Draft

❌ No

✔ Yes (fetches live data)

✔ Yes

Published

❌ No

✔ Yes (fetches live data)

✔ Yes

Sent

✔ Yes

❌ No (uses snapshot)

❌ No

Signed

✔ Yes

❌ No (uses snapshot)

❌ No

8.3 A-La-Carte Item Constraints

Constraint

Add-On Type

Event Type

Creates New Event in Project

❌ No

✔ Yes

Has Line Items

❌ No

✔ Yes

Has Service Settings

❌ No

✔ Yes

Visible Based on Event/Service Match

✔ Yes

✔ Yes

Client Can Select Quantity

✔ Yes (if enabled)

✔ Yes (if enabled)

Tracked in Post-Production

✔ Yes (if deliverable)

✔ Yes (if deliverable)

9. ACCEPTANCE CRITERIA

AC1: Package Group Selection in Proposals

• Given a user is creating a proposal template,
• When the user selects Package Groups to include,
• Then only Published Package Groups must be available for selection.

AC2: Client Package Selection

• Given a client views a proposal with 2 Package Groups,
• When the client makes selections,
• Then the client must select exactly one package from each group.

AC3: A-La-Carte Items Display

• Given a client selects a package that has linked A-La-Carte items,
• When the package is selected,
• Then all linked A-La-Carte items matching visibility rules must be displayed.

AC4: A-La-Carte Price Update

• Given a client selects an A-La-Carte item priced at $200,
• When the selection is made,
• Then the total proposal price must increase by $200.

AC5: Quantity Selection

• Given an A-La-Carte item has quantity selection enabled,
• When the client selects quantity 3 at $100 each,
• Then the total for that item must be $300.

AC6: Snapshot Creation on Send

• Given a user sends a proposal to a client from a project,
• When the proposal is sent,
• Then a complete snapshot of all package data must be created.

AC7: Snapshot Independence

• Given a proposal has been sent and a snapshot exists,
• When the source Package Group is edited,
• Then the sent proposal must NOT reflect the edits.

AC8: Events Created After Signing

• Given a client signs a proposal with a package containing Wedding and Engagement events,
• When the proposal is signed,
• Then Wedding and Engagement events must be automatically created in the project.

AC9: Services Created in Events

• Given a package has Photography and Videography services for Wedding event,
• When the proposal is signed,
• Then Photography and Videography services must be created under the Wedding event.

AC10: Event-Type A-La-Carte Creates Event

• Given a client selected an Event-type A-La-Carte item for "Rehearsal Dinner",
• When the proposal is signed,
• Then a new Rehearsal Dinner event must be created in the project.

AC11: Deliverables in Post-Production

• Given a package has line items marked as deliverables,
• When the event date passes,
• Then the deliverables must appear on the Post-Production board.

AC12: Due Date Calculation

• Given a deliverable is configured as "10 Days" after event,
• When the event date is January 15,
• Then the deliverable due date must be January 25.

AC13: Invoice Line Items from Package

• Given a client signed a proposal with a $3,000 package,
• When the invoice is generated,
• Then the package must appear as a $3,000 line item.

AC14: Invoice Line Items from A-La-Carte

• Given a client selected 2 A-La-Carte items at $200 and $150,
• When the invoice is generated,
• Then two separate line items must appear for $200 and $150.

AC15: Smart Fields Map to Project

• Given a package has "Hours Coverage" smart field set to 8,
• When the proposal is signed,
• Then the project event service must show 8 hours coverage.

10. DEPENDENCIES

Module

Dependency Type

Description

Proposal Module

Bidirectional

Packages provide content for proposals; proposals store package selections

Project Module

Downstream

Projects receive package data after proposal signing

Post-Production Module

Downstream

Receives deliverable data from projects

Invoice Module

Downstream

Receives pricing data for invoice generation

Reports Module

Downstream

Receives sales data for analytics

Database Service

Core

Stores all package, proposal, and project data

User Authentication

Core

Controls access to package and proposal features

❌ Deprecated Versions

Depracated-1. PACKAGE LIST VIEW

SECTION 1: PACKAGE LIST VIEW

1. MODULE OVERVIEW

1.1. Purpose

The Package List View is the central administrative interface where users manage all Package Groups created for proposals and projects within the Pixally CRM system. This module serves as the primary entry point for users to access, organize, and maintain their package offerings.

1.2. Business Goals

The Package List View enables agencies to:

• Efficiently manage multiple package groups across different brands
• Quickly locate specific packages using search and filtering capabilities
• Maintain organized package libraries with sorting and pagination
• Duplicate successful package structures for rapid deployment
• Control package lifecycle through edit and delete operations
• Ensure data integrity by protecting packages used in active proposals

1.3. Functional Summary

Each Package Group displayed in this view contains 1 to 6 individual packages and is tied to a single brand. The module provides comprehensive management capabilities including search, filter, sort, view, edit, duplicate, and delete operations. Users can expand package group rows to view internal package details without navigating away from the list view.

1.4. Module Boundaries

This module handles:

• Listing all package groups with pagination
• Search functionality across group and package names
• Sorting by name, brand, and created date
• Filtering by brand, event type, and service type
• Collapsible row display showing internal packages
• Edit navigation to Package Builder
• Duplicate operations with rename modal
• Delete operations with usage validation
• Multi-brand package group organization

This module does NOT handle:

• Package creation logic (covered in Section 2: Package Group Creation Flow)
• Line item editing (covered in Section 3: Package Builder)
• A-la-carte item creation (covered in Sections 4 & 5)
• Proposal generation using packages (handled by Proposal Builder module)
• Project creation from signed proposals (handled by Project module)

2. USER ROLES & PERMISSIONS

2.1. Role-Based Access Control

The Package List View implements role-based permissions to control access to package management functionality.

Role

View Packages

Create New Group

Edit Group

Duplicate Group

Delete Group

Owner

✔

✔

✔

✔

✔

Admin

✔

✔

✔

✔

✔

Project Manager

✔

✖

✖

✖

✖

Coordinator / Staff

✔

✖

✖

✖

✖

Contractor

✖

✖

✖

✖

✖

Client

✖

✖

✖

✖

✖

2.2. Permission Rules

2.2.1. View Permission

• Owners and Admins can view all package groups within their agency.
• Project Managers and Coordinators can view packages but cannot modify them.
• Contractors and Clients never interact with package management interfaces.

2.2.2. Create Permission

• Only Owners and Admins can create new package groups.
• The "Create New Group" button is visible only to users with create permissions.
• Users without create permissions see the list in read-only mode.

2.2.3. Edit Permission

• Only Owners and Admins can edit existing package groups.
• Editing a package group opens the Package Builder (Section 3).
• Edit operations do not affect proposals already created using the group.

2.2.4. Duplicate Permission

• Only Owners and Admins can duplicate package groups.
• Duplicate operation requires renaming to prevent conflicts.
• Duplicated groups include all internal packages, events, services, and line items.

2.2.5. Delete Permission

• Only Owners and Admins can delete package groups.
• Delete operations are blocked if the group is used in any proposal (draft, sent, or signed).
• Locked groups can still be duplicated and edited for future use.

2.3. Brand-Based Visibility

2.3.1. Single Brand Context

• Users working within a single brand see only packages assigned to that brand.
• Brand filter is automatically applied based on user's current brand context.

2.3.2. Multi-Brand Context

• Users with access to multiple brands can filter by brand.
• Package list automatically updates when brand context changes.
• Each package group belongs to exactly one brand and cannot be reassigned.

3. USER FLOW

3.1. Accessing Package List View

3.1.1. Navigation Entry Points

1. User logs into Pixally CRM.
2. User navigates to the left sidebar menu.
3. User clicks on Template section to expand submenu.
4. User clicks on Packages menu item.
5. System loads the Package List View showing all package groups.

3.1.2. Direct URL Access

1. User navigates directly to /packages URL.
2. System validates user authentication and permissions.
3. System loads the Package List View with default settings (newest first, 25 per page).

3.2. Viewing Package Groups (Default State)

3.2.1. Initial Page Load

1. System fetches all package groups for the logged-in user's agency and current brand context.
2. System displays groups in table format with the following columns:
   • Package Group Name (with expand/collapse icon)
   • Brand
   • Service Types (tags)
   • Events (tags)
   • Created Date
   • Actions (three-dot menu)
3. System displays groups sorted by Created Date - Newest First by default.
4. System shows 25 groups per page with pagination controls at the bottom.
5. All rows are displayed in collapsed state by default.

3.3. Expanding/Collapsing Package Groups

3.3.1. Expanding a Group

1. User clicks the expand icon (chevron down) next to a package group name.
2. System expands the row to reveal internal packages.
3. System displays each package within the group showing:
   • Package Name
   • Package Price (if set)
   • Event Types (tags)
   • Service Types (tags)
   • A-La-Carte items count (if any)
4. Expand icon changes to collapse icon (chevron up).

3.3.2. Collapsing a Group

1. User clicks the collapse icon (chevron up) on an expanded group.
2. System collapses the row back to single-line display.
3. Collapse icon changes back to expand icon (chevron down).

3.4. Searching for Packages

3.4.1. Search Execution

1. User clicks on the search input field at the top right of the list.
2. User types search query (group name or package name).
3. System performs real-time search across:
   • Package Group Names
   • Individual Package Names within groups
4. System displays matching results instantly (case-insensitive, partial match).
5. System shows "No package groups found" message if no matches exist.

3.4.2. Clearing Search

1. User clicks the "X" icon in the search field or deletes all text.
2. System clears the search filter.
3. System restores the full list with previous sort and filter settings.

3.5. Sorting Package Groups

3.5.1. Applying Sort

1. User clicks on a sortable column header (Package Group, Brand, or Created).
2. System sorts the entire list (not just current page) by the selected column.
3. First click sorts ascending (A-Z for text, oldest-newest for dates).
4. Second click sorts descending (Z-A for text, newest-oldest for dates).
5. Sort indicator (arrow icon) appears next to the active column header.

3.5.2. Sort Options

• Name: Alphabetical (A-Z) or Reverse Alphabetical (Z-A)
• Brand: Alphabetical by brand name
• Created Date: Oldest First or Newest First (default)

3.6. Filtering Package Groups

3.6.1. Opening Filter Panel

1. User clicks the Filter icon at the top right of the list.
2. System opens the filter panel displaying three filter categories:
   • Brand
   • Event Type
   • Service Type

3.6.2. Applying Single Filter

1. User selects one or more options from a filter category dropdown.
2. System applies the filter immediately (no "Apply" button needed).
3. System updates the list to show only matching package groups.
4. Filter count badge appears on the filter icon showing active filter count.

3.6.3. Applying Multiple Filters (Cumulative AND Logic)

1. User selects filters from multiple categories.
2. System applies filters cumulatively using AND logic.
3. Example: Brand = "Emma Taylor" AND Event Type = "Wedding" shows only groups matching both criteria.
4. System displays "No package groups found" if no groups match all selected filters.

3.6.4. Clearing Filters

1. User clicks "Clear All" button in the filter panel.
2. System removes all active filters.
3. System restores the full list with current sort settings.
4. Filter count badge disappears from the filter icon.

3.7. Navigating Pages (Pagination)

3.7.1. Using Pagination Controls

1. User views pagination controls at the bottom right of the list.
2. Pagination displays:
   • "Rows per page: 10" dropdown (options: 10, 25, 50)
   • "1 of 1" page indicator
   • Previous (←) and Next (→) arrow buttons
3. User clicks Next arrow to view the next page.
4. System loads the next 25 groups and updates page indicator.
5. User clicks Previous arrow to return to the previous page.
6. Arrow buttons are disabled when on first/last page.

3.7.2. Changing Rows Per Page

1. User clicks the "Rows per page" dropdown.
2. User selects desired number (10, 25, or 50).
3. System updates the list to display the selected number of groups per page.
4. System resets to page 1 if current page no longer exists with new pagination.

3.8. Editing a Package Group

3.8.1. Opening Edit Flow

1. User clicks the three-dot menu (Actions) for a package group.
2. User selects Edit from the dropdown menu.
3. System navigates to the Package Builder (Section 3) with the selected group loaded.
4. User makes changes to the group structure, packages, or line items.
5. System auto-saves changes to the Draft version.

3.8.2. Edit Impact Rules

• Editing a group does NOT affect proposals already created using this group.
• Existing proposals retain the original package snapshot.
• User must republish packages to make them available for future proposals.

3.9. Duplicating a Package Group

3.9.1. Initiating Duplicate

1. User clicks the three-dot menu (Actions) for a package group.
2. User selects Duplicate from the dropdown menu.
3. System opens a rename modal with:
   • Pre-filled name: "Copy of [Original Group Name]"
   • Editable text input field
   • "Cancel" button
   • "Create Duplicate" button

3.9.2. Completing Duplicate

1. User enters a new, unique group name (required).
2. User clicks Create Duplicate button.
3. System validates that the new name does not conflict with existing group names.
4. System creates a full copy including:
   • All packages inside the group (1-6 packages)
   • All events and services inside each package
   • All line items in their original state
   • All A-la-carte item links
   • Brand assignment
5. System saves the new group in Draft mode.
6. System navigates user to the Package Builder with the duplicated group loaded.
7. System displays success message: "Package group duplicated successfully."

3.9.3. Duplicate Validation

• If user leaves the name field empty, system shows error: "Group name is required."
• If user enters a name that already exists, system shows error: "Group name already exists."

3.10. Deleting a Package Group

3.10.1. Delete Allowed (Unused Group)

1. User clicks the three-dot menu (Actions) for a package group.
2. User selects Delete from the dropdown menu (shown in red).
3. System validates that the group is NOT used in any proposal (draft, sent, or signed).
4. System opens a confirmation modal:
   • Title: "Delete Package Group?"
   • Message: "Are you sure you want to delete '[Group Name]'? This action cannot be undone."
   • "Cancel" button
   • "Delete" button (red, destructive)
5. User clicks Delete button.
6. System permanently deletes the package group and all its internal packages.
7. System removes the group from the list immediately.
8. System displays success message: "Package group deleted successfully."

3.10.2. Delete Blocked (Used Group)

1. User clicks the three-dot menu (Actions) for a package group that is used in one or more proposals.
2. User selects Delete from the dropdown menu.
3. System detects that the group is used in proposals.
4. System opens a warning modal:
   • Title: "Cannot Delete Package Group"
   • Message: "This package group is already used in proposals and cannot be deleted."
   • "Close" button
5. Delete option is disabled in the actions menu (grayed out with lock icon).

3.10.3. Behavior for Used Groups

• Used groups cannot be deleted to preserve proposal integrity.
• Users can still duplicate used groups to create new versions.
• Users can still edit used groups, but changes only affect future proposals.

3.11. Creating a New Package Group

3.11.1. Initiating Creation

1. User clicks the "+ Create New Group" button (yellow, top right).
2. System navigates to the Package Group Creation Flow (Section 2).
3. User completes the multi-step wizard to set up the group structure.
4. System saves the new group as Draft and opens it in the Package Builder (Section 3).

4. FUNCTIONAL LOGIC

4.1. Package Group Data Loading

4.1.1. Initial Data Fetch

When the Package List View loads, the system retrieves all package groups for the current user's agency and brand context using the following logic:

1. System identifies the logged-in user's agency ID.
2. System determines the user's current brand context (single brand or multi-brand).
3. System queries the database for all package groups where:
   • agency_id = current user's agency ID
   • brand_id = current brand context (if single brand) OR IN (user's accessible brands) if multi-brand
4. System fetches associated data for each group:
   • Total package count (number of packages within the group)
   • List of unique event types across all packages in the group
   • List of unique service types across all packages in the group
   • Created timestamp
   • Usage status (whether used in any proposals)
5. System sorts the retrieved groups by created date (newest first) by default.
6. System paginates the results to display 25 groups per page.

4.1.2. Data Display Format

Each package group row displays the following columns in the table:

• Package Group Name: The user-defined name of the package group, displayed with an expand/collapse chevron icon.
• Brand: The brand name to which the package group is assigned, displayed as a label.
• Service Types: A list of service tags (e.g., "Photography", "Videography") auto-generated from all packages in the group.
• Events: A list of event type tags (e.g., "Wedding", "Rehearsal Dinner") auto-generated from all packages in the group.
• Created Date: The date when the package group was created, displayed in MM/DD/YYYY format.
• Actions: A three-dot menu icon that opens a dropdown with Edit, Duplicate, and Delete options.

4.1.3. Default Sort Order

The system applies the default sort order as Created Date - Newest First, ensuring users see the most recently created package groups at the top of the list.

4.2. Search Functionality

4.2.1. Search Scope

The search input field searches across the following data:

1. Package Group Name: The name of the package group itself.
2. Package Names: The names of individual packages inside each group.

The search does NOT include:

• Event types
• Service types
• Brand names
• Line item names
• A-la-carte item names

4.2.2. Search Matching Logic

1. User types a search query into the search input field.
2. System performs a case-insensitive, partial match search.
3. System returns any package group where:
   • The group name contains the search query (exact or partial match), OR
   • Any package name inside the group contains the search query (exact or partial match)
4. System updates the list view instantly to display only matching groups.

4.2.3. Search Results Behavior

• If the search returns one or more matches, the system displays the matching groups with highlighting on the matched text.
• If the search returns zero matches, the system displays an empty state message: "No package groups found."
• Sorting and filtering remain active during search; search narrows the already filtered/sorted list.

4.2.4. Clearing Search

When the user clears the search input (by clicking the "X" icon or deleting all text), the system restores the full list of package groups with the previously applied sort and filter settings intact.

4.3. Sorting Logic

4.3.1. Sortable Columns

The system allows sorting by the following columns:

1. Package Group Name:
   • First click: A-Z (alphabetical ascending)
   • Second click: Z-A (alphabetical descending)
2. Brand:
   • First click: A-Z by brand name (alphabetical ascending)
   • Second click: Z-A by brand name (alphabetical descending)
3. Created Date:
   • First click: Oldest First (ascending)
   • Second click: Newest First (descending, default)

4.3.2. Sort Application

1. User clicks on a column header (Package Group, Brand, or Created).
2. System sorts the entire list (not just the current page).
3. System applies the sort direction:
   • If the column is not currently sorted, apply ascending sort.
   • If the column is already sorted ascending, toggle to descending sort.
   • If the column is sorted descending, toggle back to ascending sort.
4. System displays a sort indicator (up or down arrow) next to the active column header.
5. System resets pagination to page 1 after applying sort.

4.3.3. Sort Persistence

• Sort settings persist during the user's session while navigating within the Package List View.
• Sort settings reset to default (Created Date - Newest First) when the user navigates away and returns to the page.

4.4. Filtering Logic

4.4.1. Available Filter Categories

The filter panel provides three filter categories:

1. Brand Filter: Dropdown list of all brands accessible to the current user.
2. Event Type Filter: Dropdown list of all event types defined in the agency's Event Master Data (e.g., Wedding, Rehearsal Dinner, Engagement Shoot).
3. Service Type Filter: Dropdown list of all service types (Photography, Videography, Content Creation).

4.4.2. Filter Selection Behavior

1. User opens the filter panel by clicking the filter icon.
2. User selects one or more options from any filter category.
3. System applies the filter immediately (auto-apply, no "Apply" button required).
4. System updates the list to display only package groups that match the selected criteria.

4.4.3. Cumulative Filter Logic (AND)

Filters are applied cumulatively using AND logic, meaning:

• If user selects Brand = "Emma Taylor" AND Event Type = "Wedding", the system displays only groups where:
  • The group is assigned to the "Emma Taylor" brand, AND
  • The group contains at least one package with the "Wedding" event type.
• Multiple selections within the same filter category use OR logic:
  • Example: Event Type = "Wedding" OR "Rehearsal Dinner" shows groups containing either event type.

4.4.4. Filter Results Behavior

• If filters return one or more matching groups, the system displays the filtered list.
• If filters return zero matching groups, the system displays an empty state message: "No package groups found."
• Active filter count badge appears on the filter icon (e.g., "3" if three filters are active).

4.4.5. Clearing Filters

1. User clicks the "Clear All" button in the filter panel.
2. System removes all active filters from all categories.
3. System restores the full list of package groups with the current sort settings intact.
4. Filter count badge disappears from the filter icon.

4.5. Pagination Logic

4.5.1. Rows Per Page Options

The system provides three options for rows per page:

• 10 rows per page
• 25 rows per page (default)
• 50 rows per page

4.5.2. Pagination Calculation

1. System counts the total number of package groups matching current search and filter criteria.
2. System divides the total count by the selected rows per page value to calculate total pages.
3. System displays current page number and total pages (e.g., "1 of 5").

4.5.3. Navigation Controls

• Previous Button (←): Navigates to the previous page; disabled when on page 1.
• Next Button (→): Navigates to the next page; disabled when on the last page.
• Page Indicator: Displays "X of Y" where X is the current page and Y is the total number of pages.

4.5.4. Page Change Behavior

1. User clicks the Next or Previous button.
2. System loads the requested page and updates the displayed groups.
3. System updates the page indicator to reflect the new current page.
4. System scrolls the page to the top of the list.

4.5.5. Rows Per Page Change Behavior

1. User selects a new rows per page value from the dropdown.
2. System recalculates pagination based on the new value.
3. System resets to page 1 (because current page may no longer exist with the new pagination).
4. System displays the first set of groups according to the new rows per page setting.

4.6. Collapsible Row Logic

4.6.1. Collapsed State (Default)

When a package group row is in collapsed state:

1. The row displays only group-level information:
   • Package Group Name
   • Brand
   • Service Types (aggregated tags from all packages)
   • Events (aggregated tags from all packages)
   • Created Date
   • Actions menu
2. A chevron-down icon appears next to the group name, indicating the row can be expanded.
3. No internal package details are visible.

4.6.2. Expanded State

When a user clicks the chevron icon to expand a package group row:

1. The chevron icon changes to chevron-up, indicating the row can be collapsed.
2. The row expands vertically to reveal internal package cards.
3. Each package card displays:
   • Package Name: The name of the package (e.g., "Photo/Video Bronze", "Photo/Video Silver").
   • Package Price: The set price for the package (e.g., "$450.00 USD") or "Specify the price" if not yet set.
   • Package Image: A thumbnail of the uploaded package image, or a placeholder with "Add Image" if not uploaded.
   • Events: A list of event types included in the package, displayed as colored tag sections (e.g., "WEDDING" in beige, "REHEARSAL DINNER" in blue).
   • Service Types: Listed under each event (e.g., "Photography", "Videography").
   • Line Items: A preview of the first few line items (e.g., "10 hours of Photoshooting", "Basic Retouch", "1 Photographer").
   • A-La-Carte Section: A button labeled "Assign A La Carte Items +" if no items are assigned, or a list of assigned A-la-carte items if any.
4. Package cards are displayed horizontally if space allows, or stacked vertically on smaller screens.
5. Each package card includes a settings icon (gear icon) that opens the Package Builder for that specific package.

4.6.3. Collapsing Behavior

1. User clicks the chevron-up icon on an expanded row.
2. The row collapses back to its default single-line view.
3. The chevron icon changes back to chevron-down.
4. Internal package details are hidden.

4.6.4. Multi-Expand Behavior

• Users can expand multiple package group rows simultaneously.
• Expanding one row does not collapse other expanded rows.
• Collapse state is not persisted across page refreshes; all rows default to collapsed state on reload.

4.7. Edit Package Group Logic

4.7.1. Edit Action Availability

The Edit action is available in the Actions dropdown menu for all package groups when the user has Owner or Admin role.

4.7.2. Edit Navigation

1. User clicks the three-dot menu icon in the Actions column for a package group.
2. User selects Edit from the dropdown menu.
3. System captures the package group ID.
4. System navigates to the Package Builder (Section 3) with the following URL structure: /packages/builder/{group_id}
5. Package Builder loads with:
   • All packages in the group displayed in the left sidebar
   • First package automatically selected and displayed in the center canvas
   • All events, services, and line items loaded for editing

4.7.3. Edit Impact on Proposals

Critical Rule: Editing a package group does NOT affect proposals that have already been created using this group.

• Existing Proposals: Retain a static snapshot of the package as it existed at the time the proposal was created.
• Future Proposals: Use the updated package configuration after the user republishes the package.
• Draft Proposals: If a draft proposal exists using the old version, it continues to use the old version until manually updated by the user.

4.7.4. Edit and Republish Flow

1. User edits a package group in the Package Builder.
2. System saves changes to the Draft version of the package.
3. User clicks Publish in the Package Builder.
4. System marks the package as "Published" and makes it available for future proposals.
5. Old proposals remain unaffected.

4.8. Duplicate Package Group Logic

4.8.1. Duplicate Action Availability

The Duplicate action is available in the Actions dropdown menu for all package groups when the user has Owner or Admin role.

4.8.2. Initiating Duplicate

1. User clicks the three-dot menu icon in the Actions column for a package group.
2. User selects Duplicate from the dropdown menu.
3. System captures the package group ID and retrieves all associated data.

4.8.3. Rename Modal

The system opens a modal with the following elements:

• Title: "Duplicate Package Group"
• Input Field: Pre-filled with "Copy of [Original Group Name]"
• Placeholder: User can edit the name
• Validation: Name must be unique within the brand
• Buttons:
  • "Cancel" (closes modal without action)
  • "Create Duplicate" (proceeds with duplication)

4.8.4. Duplicate Data Scope

When the user confirms the duplication, the system creates a full copy of:

1. Package Group Data:
   • Group Name (user-provided new name)
   • Brand Assignment (same as original)
   • Number of Packages (same as original, 1-6)
2. All Packages Inside the Group:
   • Package Names (unchanged)
   • Package Descriptions (unchanged)
   • Package Images (copied references)
   • Package Prices (unchanged)
   • Tax Mode settings (unchanged)
3. All Events and Services:
   • Event Types (unchanged)
   • Service Types (unchanged)
   • Primary Event designation (unchanged)
   • Same Services toggle state (unchanged)
4. All Line Items:
   • Line Item Names (unchanged)
   • Line Item Types (Standard or Smart Field, unchanged)
   • Deliverable toggles and due date rules (unchanged)
   • Taxable toggles and amounts (unchanged)
   • Prices (unchanged)
5. All A-La-Carte Links:
   • Linked add-on items (unchanged)
   • Linked event-creation items (unchanged)

4.8.5. Draft Mode for Duplicates

The duplicated package group is automatically saved in Draft mode, meaning:

• It is NOT immediately available for use in proposals.
• User must open the Package Builder and click Publish to make it available.
• User can make modifications before publishing.

4.8.6. Post-Duplication Navigation

1. System saves the duplicated group.
2. System navigates the user to the Package Builder (Section 3) with the new group loaded.
3. System displays a success message: "Package group duplicated successfully."

4.8.7. Duplicate Validation Errors

Error: Group Name Required

• Trigger: User leaves the name field empty in the rename modal.
• Message: "Group name is required."
• Action: Prevent duplication and keep modal open for user to enter a name.

Error: Group Name Already Exists

• Trigger: User enters a name that conflicts with an existing group name within the same brand.
• Message: "Group name already exists."
• Action: Prevent duplication and keep modal open for user to enter a unique name.

4.9. Delete Package Group Logic

4.9.1. Delete Action Availability

The Delete action appears in the Actions dropdown menu, but its availability depends on usage status:

• Unused Groups: Delete option is enabled and displayed in red.
• Used Groups: Delete option is disabled (grayed out) and may display a lock icon.

4.9.2. Usage Detection

The system checks whether a package group is used in any proposals by querying:

• Draft Proposals: Proposals in draft state that reference the group.
• Sent Proposals: Proposals sent to clients that reference the group.
• Signed Proposals: Proposals signed by clients that reference the group.

If the group is found in any proposal (regardless of status), it is marked as "used" and cannot be deleted.

4.9.3. Delete Flow for Unused Groups

1. User clicks the three-dot menu icon in the Actions column.
2. User selects Delete (displayed in red).
3. System validates that the group is NOT used in any proposal.
4. System opens a confirmation modal:
   • Title: "Delete Package Group?"
   • Message: "Are you sure you want to delete '[Group Name]'? This action cannot be undone."
   • Buttons:
     • "Cancel" (closes modal without deleting)
     • "Delete" (red, destructive action)
5. User clicks Delete.
6. System permanently deletes:
   • The package group record
   • All packages inside the group
   • All line items inside each package
   • All A-la-carte links (but NOT the A-la-carte items themselves)
7. System removes the group from the list immediately.
8. System displays a success message: "Package group deleted successfully."

4.9.4. Delete Blocked for Used Groups

1. User clicks the three-dot menu icon in the Actions column.
2. User selects Delete.
3. System detects that the group is used in one or more proposals.
4. System opens a warning modal:
   • Title: "Cannot Delete Package Group"
   • Message: "This package group is already used in proposals and cannot be deleted."
   • Button: "Close" (closes modal)
5. Delete option remains disabled in the Actions menu for this group.

4.9.5. Alternative Actions for Used Groups

When a package group cannot be deleted due to usage:

• Duplicate: User can duplicate the group to create a new version for future use.
• Edit: User can edit the group, but changes only affect future proposals (old proposals remain static).
• Archive Suggestion: The system may suggest archiving the group in a future release (not currently implemented).

4.10. Multi-Brand Behavior

4.10.1. Single Brand Context

When a user operates within a single brand:

1. System automatically filters the package list to show only groups assigned to that brand.
2. Brand column displays the same brand name for all rows.
3. Brand filter is not shown in the filter panel (redundant since all groups belong to the same brand).

4.10.2. Multi-Brand Context

When a user has access to multiple brands:

1. System displays package groups from all accessible brands by default.
2. Brand column displays different brand names across rows.
3. Brand filter appears in the filter panel, allowing users to filter by specific brands.

4.10.3. Brand Assignment Rules

• Each package group is assigned to exactly one brand at the time of creation.
• The brand assignment cannot be changed from the Package List View.
• To reassign a group to a different brand, the user must:
  • Duplicate the group (which retains the original brand)
  • Open the duplicated group in the Package Builder
  • Change the brand assignment in the Group Settings (Section 2)

4.10.4. Brand Context Switching

1. User switches the active brand context using the brand selector in the top navigation bar.
2. System detects the brand context change.
3. System reloads the Package List View, automatically filtering to show only groups assigned to the newly selected brand.
4. Sort and filter settings are preserved across brand context switches.

5. FIELD DETAILS & VALIDATIONS

5.1. Package Group List Fields

5.1.1. Package Group Name

• Field Type: Text
• Data Type: String
• Display Format: Plain text with expand/collapse chevron icon
• Max Length: 100 characters
• Required: Yes (set during group creation)
• Editable: Yes (via Edit action in Package Builder)
• Validation Rules:
  • Cannot be empty
  • Must be unique within the brand
  • Automatically trims leading and trailing whitespace
• Display Behavior:
  • Displayed as the first column in the table
  • Truncated with ellipsis (...) if longer than column width
  • Full name shown on hover tooltip

5.1.2. Brand

• Field Type: Label
• Data Type: Reference to Brand Master Data
• Display Format: Brand name as plain text
• Required: Yes (set during group creation)
• Editable: No (cannot be changed from Package List View)
• Validation Rules:
  • Must reference a valid brand in the Brand Master Data
  • Cannot be null
• Display Behavior:
  • Displayed as a label in the Brand column
  • If brand is deleted or archived, displays "Archived Brand" or the original brand name

5.1.3. Service Types

• Field Type: Tag List
• Data Type: Array of references to Service Type Master Data
• Display Format: Multiple colored tags (e.g., "Photography", "Videography")
• Required: No (auto-generated from packages)
• Editable: No (auto-calculated from internal packages)
• Validation Rules:
  • Auto-generated by aggregating all unique service types from all packages in the group
  • If no services are defined, displays empty (should not occur in valid packages)
• Display Behavior:
  • Displayed as horizontal list of tags
  • Each tag has a distinct background color
  • If more than 3 services, displays "+X more" tag

5.1.4. Events

• Field Type: Tag List
• Data Type: Array of references to Event Type Master Data
• Display Format: Multiple colored tags (e.g., "Wedding", "Rehearsal Dinner")
• Required: No (auto-generated from packages)
• Editable: No (auto-calculated from internal packages)
• Validation Rules:
  • Auto-generated by aggregating all unique event types from all packages in the group
  • If no events are defined, displays empty (should not occur in valid packages)
• Display Behavior:
  • Displayed as horizontal list of tags
  • Each tag has a distinct background color
  • If more than 3 events, displays "+X more" tag

5.1.5. Created Date

• Field Type: Date
• Data Type: Timestamp
• Display Format: MM/DD/YYYY (e.g., "Jan 24, 2025")
• Required: Yes (auto-set by system on creation)
• Editable: No (immutable)
• Validation Rules:
  • Auto-set to current date/time when group is created
  • Cannot be manually changed
• Display Behavior:
  • Displayed in short date format for readability
  • Full timestamp available in database but not shown in UI
  • Used for sorting (newest first by default)

5.1.6. Package Count

• Field Type: Number
• Data Type: Integer (1-6)
• Display Format: Displayed in expanded row as "(X PACKAGES)" label
• Required: Yes (set during group creation)
• Editable: Yes (via Edit action in Package Builder)
• Validation Rules:
  • Must be between 1 and 6 (inclusive)
  • Cannot be less than the number of packages already created
• Display Behavior:
  • Not displayed as a separate column in the table
  • Visible in the expanded row header
  • Determines the number of package slots available in the group

5.2. Search and Filter Fields

5.2.1. Search Input

• Field Type: Text input
• Data Type: String
• Max Length: 100 characters
• Required: No (optional)
• Validation Rules:
  • No special character restrictions
  • Case-insensitive matching
  • Partial match allowed
• Display Behavior:
  • Displays magnifying glass icon inside input field
  • Displays "X" clear icon when text is entered
  • Placeholder text: "Search packages..."

5.2.2. Brand Filter

• Field Type: Multi-select dropdown
• Data Type: Array of Brand IDs
• Display Format: Dropdown with checkboxes
• Required: No (optional)
• Validation Rules:
  • Must reference valid brands from Brand Master Data
  • User can only select brands they have access to
• Display Behavior:
  • Displays all accessible brands in alphabetical order
  • Selected brands show checkmarks
  • "Select all" and "Clear all" options available

5.2.3. Event Type Filter

• Field Type: Multi-select dropdown
• Data Type: Array of Event Type IDs
• Display Format: Dropdown with checkboxes
• Required: No (optional)
• Validation Rules:
  • Must reference valid event types from Event Type Master Data
• Display Behavior:
  • Displays all event types in alphabetical order
  • Selected event types show checkmarks
  • "Select all" and "Clear all" options available

5.2.4. Service Type Filter

• Field Type: Multi-select dropdown
• Data Type: Array of Service Type IDs
• Display Format: Dropdown with checkboxes
• Required: No (optional)
• Validation Rules:
  • Must reference valid service types from Service Type Master Data
• Display Behavior:
  • Displays all service types in alphabetical order
  • Selected service types show checkmarks
  • "Select all" and "Clear all" options available

5.3. Action Menu Fields

5.3.1. Edit Action

• Field Type: Button
• Display Format: Text link "Edit" in dropdown menu
• Required: N/A
• Enabled Conditions:
  • User has Owner or Admin role
• Validation Rules:
  • None (action always available to authorized users)

5.3.2. Duplicate Action

• Field Type: Button
• Display Format: Text link "Duplicate" in dropdown menu
• Required: N/A
• Enabled Conditions:
  • User has Owner or Admin role
• Validation Rules:
  • New group name must be unique within brand
  • Group must not exceed maximum package count for the agency

5.3.3. Delete Action

• Field Type: Button
• Display Format: Text link "Delete" in red in dropdown menu
• Required: N/A
• Enabled Conditions:
  • User has Owner or Admin role
  • Group is NOT used in any proposals
• Validation Rules:
  • Group cannot be used in any draft, sent, or signed proposals
  • If used, action is disabled with lock icon

5.4. Expanded Row Package Card Fields

5.4.1. Package Name

• Field Type: Text
• Data Type: String
• Display Format: Bold header text in package card
• Max Length: 100 characters
• Required: Yes
• Validation Rules:
  • Must be unique within the package group
  • Cannot be empty

5.4.2. Package Price

• Field Type: Currency
• Data Type: Decimal (two decimal places)
• Display Format: "$XXX.XX USD" or "Specify the price" if not set
• Required: Yes (for published packages)
• Validation Rules:
  • Must be >= 0
  • Cannot be negative

5.4.3. Package Image

• Field Type: Image
• Data Type: File reference (JPG, PNG)
• Display Format: Thumbnail image (aspect ratio 16:9 or 4:3)
• Max File Size: 5 MB
• Required: No (optional)
• Validation Rules:
  • Accepted formats: JPG, PNG
  • Max file size: 5 MB
• Display Behavior:
  • If no image uploaded, displays placeholder with "Add Image" text

5.4.4. Event Types (Package Card)

• Field Type: Tag list
• Data Type: Array of Event Type references
• Display Format: Colored section headers (e.g., "WEDDING" in beige)
• Required: Yes (at least one event)
• Validation Rules:
  • Must have at least one event defined
• Display Behavior:
  • Each event displayed as a colored section within the package card
  • Primary event may have a star icon or special indicator

5.4.5. Service Types (Package Card)

• Field Type: Tag list
• Data Type: Array of Service Type references
• Display Format: Listed under each event (e.g., "Photography", "Videography")
• Required: Yes (at least one service per event)
• Validation Rules:
  • Each event must have at least one service assigned

5.4.6. Line Items Preview

• Field Type: Text list
• Data Type: Array of line item names
• Display Format: Bulleted list or plain text list
• Required: No (packages can be empty in draft mode)
• Display Behavior:
  • Displays first 3-5 line items
  • If more than 5, displays "...and X more" indicator

5.4.7. A-La-Carte Items Button

• Field Type: Button
• Display Format: "Assign A La Carte Items +" button or list of assigned items
• Required: No (optional)
• Validation Rules:
  • A-la-carte items must belong to the same brand as the package
• Display Behavior:
  • If no items assigned, displays "Assign A La Carte Items +" button
  • If items assigned, displays count (e.g., "3 Add-ons")

6. SUCCESS MESSAGE HANDLING

6.1. Success Message Display Rules

Success messages are displayed as non-blocking toast notifications that appear at the top-right corner of the screen. Each success message:

• Displays for 5 seconds before auto-dismissing
• Can be manually dismissed by clicking the "X" icon
• Uses a green checkmark icon to indicate success
• Does not block user interaction with the page

6.2. Package Group Duplicate Success

6.2.1. Trigger Condition

This success message is displayed when a user successfully duplicates a package group.

6.2.2. Success Message

Message Text: "Package group duplicated successfully."

6.2.3. Message Details

• Display Location: Top-right toast notification
• Icon: Green checkmark
• Duration: 5 seconds
• Dismissible: Yes

6.2.4. Post-Success Actions

1. System displays the success message.
2. System navigates the user to the Package Builder with the duplicated group loaded.
3. User can immediately begin editing the duplicated group.

6.3. Package Group Delete Success

6.3.1. Trigger Condition

This success message is displayed when a user successfully deletes an unused package group.

6.3.2. Success Message

Message Text: "Package group deleted successfully."

6.3.3. Message Details

• Display Location: Top-right toast notification
• Icon: Green checkmark
• Duration: 5 seconds
• Dismissible: Yes

6.3.4. Post-Success Actions

1. System displays the success message.
2. System immediately removes the deleted group from the list view.
3. System updates pagination if necessary (e.g., if the deleted group was the last item on a page).
4. User remains on the Package List View.

6.4. Filter Applied Success (Implicit)

6.4.1. Trigger Condition

This implicit success state occurs when a user applies filters and matching results are found.

6.4.2. Visual Feedback (No Toast)

• Filter count badge appears on the filter icon (e.g., "3" if three filters are active).
• List updates immediately to show filtered results.
• No explicit success message is displayed (visual feedback is sufficient).

6.5. Search Results Found Success (Implicit)

6.5.1. Trigger Condition

This implicit success state occurs when a user performs a search and matching results are found.

6.5.2. Visual Feedback (No Toast)

• List updates immediately to show search results.
• Matching text is highlighted in the group/package names.
• No explicit success message is displayed (visual feedback is sufficient).

6.6. Sort Applied Success (Implicit)

6.6.1. Trigger Condition

This implicit success state occurs when a user applies sorting to the list.

6.6.2. Visual Feedback (No Toast)

• Sort indicator (up or down arrow) appears next to the active column header.
• List reorders immediately according to the selected sort direction.
• No explicit success message is displayed (visual feedback is sufficient).

7. ERROR MESSAGE HANDLING

7.1. Error Message Display Rules

Error messages are displayed in two formats depending on the error type:

1. Inline Errors: Displayed directly below the relevant input field (e.g., in modals).
2. Toast Notifications: Displayed as non-blocking notifications at the top-right corner of the screen for system-level errors.

Error messages use:

• Red text color for inline errors
• Red error icon for toast notifications
• Clear, actionable language
• Auto-dismiss after 7 seconds for toast notifications (longer than success messages)

7.2. Duplicate Package Group Errors

7.2.1. Error: Group Name Required

**Trigger Condition:
**User attempts to duplicate a package group but leaves the group name field empty in the rename modal.

**Error Message:
**"Group name is required."

Display Type: Inline error below the group name input field

**User Action Required:
**User must enter a valid group name before proceeding.

System Behavior:

• The "Create Duplicate" button remains enabled but does not proceed.
• Error message disappears when the user starts typing in the name field.
• Modal remains open until the user enters a valid name or clicks Cancel.

7.2.2. Error: Group Name Already Exists

**Trigger Condition:
**User attempts to duplicate a package group with a name that conflicts with an existing group within the same brand.

**Error Message:
**"Group name already exists."

Display Type: Inline error below the group name input field

**User Action Required:
**User must enter a unique group name.

System Behavior:

• System checks for name uniqueness when the user clicks "Create Duplicate".
• If duplicate name detected, system prevents duplication and displays error.
• User can edit the name and retry.
• Modal remains open until a unique name is entered or user clicks Cancel.

7.3. Delete Package Group Errors

7.3.1. Error: Cannot Delete Used Package Group

**Trigger Condition:
**User attempts to delete a package group that is used in one or more proposals (draft, sent, or signed).

**Error Message:
**"This package group is already used in proposals and cannot be deleted."

Display Type: Modal dialog

Modal Details:

• Title: "Cannot Delete Package Group"
• Message: "This package group is already used in proposals and cannot be deleted."
• Button: "Close" (closes the modal)

**User Action Required:
**User must close the modal. Deletion is not possible.

System Behavior:

• Delete option is disabled (grayed out) in the Actions menu for used groups.
• If user somehow bypasses the disabled state and attempts deletion, this modal is shown.
• System prevents deletion entirely; no data is modified.

Alternative Actions:

• User can duplicate the group to create a new version.
• User can edit the group for future proposals.

7.4. Search and Filter Errors

7.4.1. Error: No Package Groups Found (Search)

**Trigger Condition:
**User performs a search, but no package groups match the search query.

**Error Message:
**"No package groups found."

Display Type: Empty state message in the list area

**User Action Required:
**User can:

• Modify the search query
• Clear the search to restore the full list

System Behavior:

• Displays an empty state illustration with the message.
• Search input remains active and editable.
• User can immediately try a different search term.

7.4.2. Error: No Package Groups Found (Filter)

**Trigger Condition:
**User applies one or more filters, but no package groups match the filter criteria.

**Error Message:
**"No package groups found."

Display Type: Empty state message in the list area

**User Action Required:
**User can:

• Modify the filter selections
• Clear all filters to restore the full list

System Behavior:

• Displays an empty state illustration with the message.
• Filter panel remains open and active.
• User can adjust filters and see results update immediately.

7.5. System-Level Errors

7.5.1. Error: Failed to Load Package Groups

**Trigger Condition:
**System encounters a server error or network issue while fetching package groups.

**Error Message:
**"Failed to load package groups. Please try again."

Display Type: Toast notification (top-right, red error icon)

**User Action Required:
**User should refresh the page or wait and retry.

System Behavior:

• Toast notification displays for 7 seconds.
• List area shows an empty state with a "Retry" button.
• User can click "Retry" to attempt reloading the data.

7.5.2. Error: Failed to Duplicate Package Group

**Trigger Condition:
**System encounters a server error while attempting to duplicate a package group.

**Error Message:
**"Failed to duplicate package group. Please try again."

Display Type: Toast notification (top-right, red error icon)

**User Action Required:
**User should retry the duplication operation.

System Behavior:

• Toast notification displays for 7 seconds.
• Rename modal remains open.
• User can click "Create Duplicate" again to retry.

7.5.3. Error: Failed to Delete Package Group

**Trigger Condition:
**System encounters a server error while attempting to delete a package group.

**Error Message:
**"Failed to delete package group. Please try again."

Display Type: Toast notification (top-right, red error icon)

**User Action Required:
**User should retry the delete operation.

System Behavior:

• Toast notification displays for 7 seconds.
• Confirmation modal remains open.
• User can click "Delete" again to retry.
• Package group remains in the list (not deleted).

7.6. Permission Errors

7.6.1. Error: Insufficient Permissions

**Trigger Condition:
**A user without Owner or Admin role attempts to access edit, duplicate, or delete functionality (e.g., via direct URL manipulation or API call).

**Error Message:
**"You do not have permission to perform this action."

Display Type: Toast notification (top-right, red error icon)

**User Action Required:
**None. User cannot proceed with the action.

System Behavior:

• Toast notification displays for 7 seconds.
• System blocks the action entirely.
• User is redirected back to the Package List View if they attempted direct URL access.

8. EDGE CASES

8.1. Brand Deletion Impact

8.1.1. Edge Case Description

A package group's assigned brand is deleted or archived by an admin while the package group still exists.

8.1.2. Expected System Behavior

• The package group remains in the system and is not automatically deleted.
• The brand field displays "Archived Brand" or the original brand name (marked as archived).
• The package group becomes read-only and cannot be edited unless the brand is restored.
• Users can still duplicate the group, which creates a new draft with the archived brand reference.
• The group does not appear in the list if the user filters by active brands only.

8.1.3. User Action Required

• User must contact an admin to restore the archived brand, or
• User must duplicate the group and reassign it to an active brand in the Package Builder.

8.2. Repeated Duplication of the Same Group

8.2.1. Edge Case Description

A user repeatedly duplicates the same package group multiple times without changing the auto-generated "Copy of [Name]" format.

8.2.2. Expected System Behavior

• System always forces the user to rename the duplicate.
• System prevents silent duplication with the same name.
• If the user tries to use "Copy of [Name]" and it already exists, the system shows the error: "Group name already exists."
• User must manually modify the name each time (e.g., "Copy of Photography Package 2", "Copy of Photography Package 3").

8.2.3. User Action Required

• User must provide a unique name for each duplicate.

8.3. Very Large Number of Package Groups

8.3.1. Edge Case Description

An agency has created hundreds or thousands of package groups over time, leading to potential performance issues.

8.3.2. Expected System Behavior

• Pagination handles performance by loading only 25 (or 10/50) groups per page.
• System queries are optimized to fetch only the current page's data, not the entire dataset.
• Search and filter operations remain performant by using indexed database queries.
• If performance degrades, system displays a loading spinner during data fetch.

8.3.3. User Action Required

• Users can use search and filters to narrow down the list.
• Users can adjust rows per page to 10 if experiencing slow performance.

8.4. All Filters Cleared

8.4.1. Edge Case Description

User applies multiple filters, then clicks "Clear All" to reset the list.

8.4.2. Expected System Behavior

• System immediately removes all active filters from all filter categories.
• Filter count badge disappears from the filter icon.
• List resets to show all package groups with the current sort order intact (not reset to default).
• Pagination resets to page 1.
• Search query (if any) remains active and is not cleared by the "Clear All" action.

8.4.3. User Action Required

• None. The list restores automatically.

8.5. User Changes Brand Context Mid-Session

8.5.1. Edge Case Description

A user with access to multiple brands switches the active brand context using the brand selector in the top navigation while viewing the Package List.

8.5.2. Expected System Behavior

• System detects the brand context change immediately.
• System reloads the Package List View, automatically filtering to show only groups assigned to the newly selected brand.
• Sort settings are preserved (e.g., if sorted by Name A-Z, it remains sorted by Name A-Z after brand switch).
• Active filters are preserved if they are still valid for the new brand context (e.g., Event Type filter remains active).
• Search query is cleared because it may no longer be relevant to the new brand context.
• Pagination resets to page 1.

8.5.3. User Action Required

• None. The list updates automatically.

8.6. Expanding Multiple Rows Simultaneously

8.6.1. Edge Case Description

A user expands multiple package group rows at the same time to compare packages visually.

8.6.2. Expected System Behavior

• System allows multiple rows to be expanded simultaneously without restriction.
• Expanding one row does not collapse other expanded rows.
• Page height increases dynamically as more rows are expanded.
• Vertical scrollbar appears if the expanded rows exceed the viewport height.
• All expanded rows remain expanded when the user navigates to the next page and then returns (within the same session, if browser allows).

8.6.3. User Action Required

• User can manually collapse rows that are no longer needed to reduce page clutter.

8.7. Editing a Group That Was Duplicated from Another Group

8.7.1. Edge Case Description

A user duplicates a package group, edits the duplicate, and then attempts to edit the original group.

8.7.2. Expected System Behavior

• The duplicate and original group are completely independent.
• Edits to the duplicate do NOT affect the original group.
• Edits to the original group do NOT affect the duplicate.
• Both groups can be edited, published, and used in proposals independently.

8.7.3. User Action Required

• None. Groups are treated as separate entities.

8.8. Attempting to Delete a Recently Used Group

8.8.1. Edge Case Description

A user creates a proposal using a package group, then immediately returns to the Package List and attempts to delete the group.

8.8.2. Expected System Behavior

• System detects that the group is now used in a draft proposal.
• Delete option is immediately disabled (grayed out with lock icon) in the Actions menu.
• If user attempts to delete, system shows the warning modal: "This package group is already used in proposals and cannot be deleted."
• The group remains in the list and cannot be deleted.

8.8.3. User Action Required

• User can duplicate or edit the group for future use.
• User cannot delete the group as long as it is referenced in any proposal.

8.9. Package Group with No Internal Packages

8.9.1. Edge Case Description

A package group is created but no packages have been configured yet (e.g., group is in incomplete draft state).

8.9.2. Expected System Behavior

• The group appears in the Package List View with group-level information.
• When expanded, the row displays an empty state message: "No packages configured yet."
• A button labeled "Add Packages" appears, which navigates the user to the Package Builder.
• The group cannot be published or used in proposals until at least one package is configured.

8.9.3. User Action Required

• User must click "Add Packages" and complete the package setup in the Package Builder.

8.10. User Loses Internet Connection While Viewing the List

8.10.1. Edge Case Description

User's internet connection is lost while they are viewing the Package List View.

8.10.2. Expected System Behavior

• Existing data on the page remains visible (cached data is not cleared).
• If user attempts to perform an action (edit, duplicate, delete, search, filter), system detects the network error.
• System displays a toast notification: "No internet connection. Please check your network and try again."
• Actions are blocked until the connection is restored.

8.10.3. User Action Required

• User must restore internet connection.
• User can retry the action after reconnection.

9. ACCEPTANCE CRITERIA

9.1. List Rendering

AC1.1: Package Group List Loads Successfully

Given a user with Owner or Admin role navigates to the Package List View,
When the page loads,
Then the system must display all package groups for the user's agency and brand context, showing up to 25 groups per page with the following columns: Package Group Name, Brand, Service Types, Events, Created Date, and Actions.

AC1.2: Default Sort Order Applied

Given the Package List View loads for the first time,
When the page displays,
Then the system must sort package groups by Created Date in descending order (newest first) by default.

AC1.3: Pagination Displays Correctly

Given there are more than 25 package groups in the system,
When the Package List View loads,
Then the system must display pagination controls at the bottom showing "Rows per page: 10" dropdown, page indicator (e.g., "1 of 5"), and Previous/Next arrow buttons.

9.2. Sorting

AC2.1: Sort by Name (Ascending)

Given a user clicks on the "Package Group" column header,
When the sort is applied,
Then the system must sort all package groups alphabetically by name (A-Z) and display a sort indicator (up arrow) next to the column header.

AC2.2: Sort by Name (Descending)

Given a user clicks on the "Package Group" column header for the second time,
When the sort is toggled,
Then the system must sort all package groups in reverse alphabetical order (Z-A) and display a sort indicator (down arrow).

AC2.3: Sort by Brand

Given a user clicks on the "Brand" column header,
When the sort is applied,
Then the system must sort all package groups alphabetically by brand name in ascending order, then descending on second click.

AC2.4: Sort by Created Date

Given a user clicks on the "Created" column header,
When the sort is applied,
Then the system must sort all package groups by created date, first click showing oldest first, second click showing newest first.

9.3. Filtering

AC3.1: Single Filter Applied

Given a user selects a single brand from the Brand filter dropdown,
When the filter is applied,
Then the system must display only package groups assigned to the selected brand.

AC3.2: Multiple Filters Applied (AND Logic)

Given a user selects "Brand = Emma Taylor" and "Event Type = Wedding",
When both filters are applied,
Then the system must display only package groups that are assigned to "Emma Taylor" AND contain at least one package with the "Wedding" event type.

AC3.3: Filter Returns No Results

Given a user applies filters that have no matching package groups,
When the filter is applied,
Then the system must display an empty state message: "No package groups found."

AC3.4: Clear All Filters

Given a user has multiple active filters applied,
When the user clicks "Clear All",
Then the system must remove all filters and restore the full list of package groups with the current sort order intact.

9.4. Collapse/Expand

AC4.1: Expand Package Group Row

Given a package group row is in collapsed state,
When the user clicks the expand icon (chevron down),
Then the system must expand the row to reveal all internal packages with package names, prices, images, events, services, line items preview, and A-la-carte assignment button.

AC4.2: Collapse Package Group Row

Given a package group row is in expanded state,
When the user clicks the collapse icon (chevron up),
Then the system must collapse the row back to single-line display showing only group-level information.

AC4.3: Multiple Rows Expanded Simultaneously

Given a user expands multiple package group rows,
When multiple rows are expanded,
Then the system must allow all expanded rows to remain expanded simultaneously without collapsing others.

9.5. Duplicate

AC5.1: Duplicate Requires Rename

Given a user selects the Duplicate action from the Actions menu,
When the rename modal opens,
Then the system must pre-fill the name field with "Copy of [Original Group Name]" and require the user to provide a unique name before proceeding.

AC5.2: Duplicate Creates Full Copy

Given a user successfully duplicates a package group,
When the duplication is completed,
Then the system must create an exact copy including all packages, events, services, line items, and A-la-carte links, saving the new group in Draft mode.

AC5.3: Duplicate Validation - Empty Name

Given a user attempts to duplicate a package group with an empty name,
When the user clicks "Create Duplicate",
Then the system must display an inline error: "Group name is required."

AC5.4: Duplicate Validation - Name Conflict

Given a user attempts to duplicate a package group with a name that already exists,
When the user clicks "Create Duplicate",
Then the system must display an inline error: "Group name already exists."

9.6. Delete

AC6.1: Delete Allowed for Unused Groups

Given a package group is NOT used in any proposal,
When the user selects Delete and confirms the action,
Then the system must permanently delete the package group and display a success message: "Package group deleted successfully."

AC6.2: Delete Blocked for Used Groups

Given a package group is used in one or more proposals (draft, sent, or signed),
When the user attempts to delete the group,
Then the system must block the delete action and display a warning modal: "This package group is already used in proposals and cannot be deleted."

AC6.3: Delete Option Disabled for Used Groups

Given a package group is used in one or more proposals,
When the Actions menu is opened,
Then the Delete option must be disabled (grayed out) with a lock icon.

9.7. Search

AC7.1: Search Across Group and Package Names

Given a user types a search query in the search input field,
When the search is executed,
Then the system must return package groups where the group name OR any internal package name contains the search query (case-insensitive, partial match).

AC7.2: Search Returns No Results

Given a user enters a search query that does not match any groups or packages,
When the search is executed,
Then the system must display an empty state message: "No package groups found."

AC7.3: Clear Search

Given a user has entered a search query,
When the user clears the search input,
Then the system must restore the full list of package groups with the current sort and filter settings intact.

10. DEPENDENCIES

10.1. Internal Module Dependencies

10.1.1. Package Builder (Section 3)

Dependency Type: REQUIRED
Relationship: The Package List View provides navigation to the Package Builder for editing and duplicating package groups.

Impact:

• When a user clicks Edit on a package group, the system navigates to the Package Builder (Section 3) with the selected group loaded.
• When a user clicks Duplicate and confirms, the system creates a copy and navigates to the Package Builder with the new draft group loaded.
• The Package Builder is responsible for all package-level editing, including line items, smart fields, deliverables, and tax settings.

Expected Behavior:

• If the Package Builder module is unavailable or broken, edit and duplicate actions will fail, and users will not be able to modify package groups.

10.1.2. Proposal Builder

Dependency Type: INDIRECT
Relationship: Published package groups from the Package List are used in the Proposal Builder to create client proposals.

Impact:

• Only published package groups are available for selection in the Proposal Builder.
• Draft package groups do NOT appear in the Proposal Builder.
• Editing a package group does NOT update proposals that have already been created using the old version.

Expected Behavior:

• If a package group is edited after being used in a proposal, the proposal retains a static snapshot of the original package configuration.
• New proposals created after the edit will use the updated package configuration.

10.1.3. A-La-Carte Module (Sections 4 & 5)

Dependency Type: INDIRECT
Relationship: The Package List View displays A-la-carte item counts for expanded package rows. A-la-carte items are linked to packages in the Package Builder.

Impact:

• When a package group is expanded, the system displays the number of A-la-carte items assigned to each package.
• Deleting a package group does NOT delete the A-la-carte items themselves; only the links are removed.

Expected Behavior:

• If an A-la-carte item is deleted, the package no longer displays it in the expanded view or in proposals.

10.1.4. Project Module

Dependency Type: INDIRECT
Relationship: Package groups selected in proposals are converted into project structure after a client signs the contract.

Impact:

• When a client signs a proposal, the system creates a project using the selected package group's configuration.
• Smart fields from the package are mapped to project details.
• Deliverables from the package are sent to the Post-Production module.

Expected Behavior:

• Once a project is created, editing the original package group does NOT update the project.
• Projects remain static after creation.

10.1.5. Brand Module

Dependency Type: REQUIRED
Relationship: Each package group is assigned to exactly one brand. The Package List View filters groups by brand context.

Impact:

• The brand determines which package groups are visible to the user.
• Users with access to multiple brands can filter the list by brand.
• If a brand is deleted or archived, package groups assigned to that brand display "Archived Brand" and become read-only.

Expected Behavior:

• Changing the user's active brand context automatically updates the Package List View to show only groups assigned to the new brand.
• Package groups cannot be reassigned to a different brand from the Package List View; brand assignment must be changed in the Package Builder.

10.2. External Data Dependencies

10.2.1. Events Master Data

Dependency Type: REQUIRED
Relationship: The Package List View displays event types aggregated from all packages in a group. Event types are defined in the Events Master Data module.

Impact:

• Event types displayed in the "Events" column are pulled from the Events Master Data.
• If an event type is deleted from the master data, it may still appear in existing package groups but will no longer be available for new packages.

Expected Behavior:

• The system should validate that event types referenced in packages still exist in the master data.
• If an event type is missing, display "Unknown Event" or the original event name with a warning icon.

10.2.2. Service Types Master Data

Dependency Type: REQUIRED
Relationship: The Package List View displays service types aggregated from all packages in a group. Service types are defined in the Service Types Master Data module.

Impact:

• Service types displayed in the "Service Types" column are pulled from the Service Types Master Data.
• If a service type is deleted from the master data, it may still appear in existing package groups but will no longer be available for new packages.

Expected Behavior:

• The system should validate that service types referenced in packages still exist in the master data.
• If a service type is missing, display "Unknown Service" or the original service name with a warning icon.

10.3. Technical Dependencies

10.3.1. Database

Dependency Type: REQUIRED
Relationship: The Package List View relies on database queries to fetch and display package groups.

Impact:

• If the database is unavailable, the Package List View cannot load data.
• System must display an error message: "Failed to load package groups. Please try again."

Expected Behavior:

• Implement retry logic for database connection failures.
• Display a "Retry" button to allow users to attempt reloading data.

10.3.2. Authentication and Session Management

Dependency Type: REQUIRED
Relationship: The Package List View requires the user to be authenticated and have an active session.

Impact:

• If the user's session expires while viewing the list, system must detect the expired session.
• System must redirect the user to the login page with a message: "Your session has expired. Please log in again."

Expected Behavior:

• Implement session validation on page load and before executing actions (edit, duplicate, delete).
• Auto-save user's last position (sort, filter settings) to restore after re-login.

10.3.3. File Storage (for Package Images)

Dependency Type: INDIRECT
Relationship: The expanded package rows display package images stored in the file storage system (AWS S3 or similar).

Impact:

• If the file storage system is unavailable, package images may fail to load.
• System should display a placeholder image with an error icon.

Expected Behavior:

• Use lazy loading for images to improve performance.
• Implement fallback placeholder images if the original image fails to load.

11. REFERENCES

11.1. Figma Design References

https://www.figma.com/design/ej0kxwP45mDKmZCZfAJ5O8/Pixally?node-id=19582-107240&t=s48OXpFph7n7OniV-0

Depracated-2. PACKAGE GROUP CREATION FLOW

SECTION 2: PACKAGE GROUP CREATION FLOW

1. MODULE OVERVIEW

1.1. Purpose

The Package Group Creation Flow is a guided, multi-step wizard that enables users to create a new Package Group from scratch. This wizard-based interface ensures users systematically configure all essential group-level settings before proceeding to detailed package configuration in the Package Builder.

1.2. Business Goals

The Package Group Creation Flow enables agencies to:

Establish the foundational structure for a new package offering

Define the number of packages (1-6) within a single group

Assign the group to a specific brand for organizational clarity

Configure events and services for each package in the group

Establish a primary event for packages with multiple events

Streamline the package setup process with a logical, step-by-step flow

Ensure consistency across packages through the "Same Services" toggle option

1.3. Functional Summary

This module guides users through a structured wizard consisting of:

Initial Setup Step: Define group name, select brand, and choose number of packages (1-6)

Package Configuration Steps (per package):

Step 1: Select events and designate primary event (if multiple events)

Step 2: Choose services for events (with "Same Services For All Events" toggle option)

The wizard dynamically adapts based on user selections, displaying package slots in the left sidebar and validating each step before allowing progression. Upon completion, the system prepares the group structure and transitions users to the Package Builder (Section 3) for detailed line item configuration.

1.4. Module Boundaries

This module handles:

Group name definition and validation

Brand assignment (locked after creation)

Number of packages selection (1-6)

Dynamic package slot creation in left sidebar

Event selection for each package (single or multiple events)

Primary event designation for multi-event packages

Service selection per event or unified across all events

"Same Services For All Events" toggle behavior

Auto-save to draft status during wizard progression

Transition to Package Builder upon completion

This module does NOT handle:

Line item creation or configuration

Deliverable setup and due date rules

Smart field configuration

Tax mode settings

Package pricing

Package image uploads

A-la-carte item linkage

Publishing or version control (handled in Package Builder)

2. USER ROLES & PERMISSIONS

2.1. Role-Based Access Control

The Package Group Creation Flow implements strict role-based permissions to ensure only authorized users can create and modify package group structures.

Role

Create Group

Edit Group Structure

Add/Remove Packages

Change Brand

Delete Group

Owner

✔

✔

✔

✔

✔

Admin

✔

✔

✔

✔

✔

Project Manager

✖

✖

✖

✖

✖

Coordinator / Staff

✖

✖

✖

✖

✖

Contractor

✖

✖

✖

✖

✖

Client

✖

✖

✖

✖

✖

2.2. Permission Rules

2.2.1. Create Group Permission

Only users with Owner or Admin roles can initiate the Package Group Creation Flow.

The "Create New Group" button in the Package List View (Section 1) is visible only to authorized users.

Project Managers, Coordinators, Contractors, and Clients cannot access the creation wizard.

2.2.2. Edit Group Structure Permission

Only Owners and Admins can modify group-level settings (name, brand, package count).

Editing is accessed through the Package List View "Edit" action or the Package Builder "Group Settings" button.

Changes to group structure (e.g., increasing package count) can be made after initial creation.

2.2.3. Add/Remove Packages Permission

Only Owners and Admins can increase or decrease the number of packages in a group.

Increasing package count adds new empty package slots requiring event/service configuration.

Decreasing package count removes the last package(s) and permanently deletes their configuration.

2.2.4. Change Brand Permission

Only Owners and Admins can reassign a package group to a different brand.

Brand reassignment is only available during the initial setup or through the Package Builder Group Settings.

Changing brand affects visibility in the Package List View for users with brand-specific access.

2.2.5. Delete Group Permission

Only Owners and Admins can delete package groups.

Deletion is blocked if the group is used in any proposal (handled in Section 1).

Groups in draft mode can be deleted at any time without restrictions.

2.3. Brand-Based Access

2.3.1. Brand Assignment

Each package group must be assigned to exactly one brand during creation.

Users can only assign groups to brands they have access to.

Brand selection is presented as a dropdown showing only accessible brands.

2.3.2. Brand Lock After Creation

Once a package group is created and saved, the brand assignment is locked.

To change the brand, users must use the Group Settings in the Package Builder.

Brand changes do not affect proposals already created using the group.

3. USER FLOW

3.1. Initiating Package Group Creation

3.1.1. Navigation from Package List View

User is on the Package List View (Section 1).

User clicks the "+ Create New Group" button (yellow button, top right).

System validates user permissions (Owner or Admin role required).

System opens the Package Group Creation Wizard in a modal or new page view.

Wizard displays Step 0: Group Settings as the initial step.

3.1.2. Wizard Interface Layout

The wizard interface consists of:

Left Sidebar: Displays "GROUP SETTINGS" (active) and placeholder package slots (Package 1, Package 2, etc., initially locked)

Center Canvas: Displays the active step's form fields and configuration options

Top Navigation: Shows wizard title "Set Up Packages Group" and close button (X)

Bottom Actions: "Cancel" and "Next" buttons (Next becomes "Finish" on final step)

3.2. Step 0: Group Settings (Initial Setup)

3.2.1. Accessing Group Settings

Wizard opens with GROUP SETTINGS highlighted in the left sidebar.

Center canvas displays three input fields:

Group Name (text input, required)

Number of Packages (dropdown, 1-6, required)

Brand (dropdown, required)

Informational tooltip appears: "Feel free to switch things up while building your package — your choices aren't set in stone."

3.2.2. Entering Group Name

User clicks on the Group Name input field.

System displays placeholder text: "e.g., Photography/Videography Combo".

User types the group name (max 100 characters).

System validates in real-time:

Name cannot be empty

Name must be unique within the selected brand

If validation fails, inline error appears below the field.

3.2.3. Selecting Number of Packages

User clicks on the Number of Packages dropdown.

System displays options: 1, 2, 3, 4, 5, 6.

User selects a number (e.g., 3).

System dynamically updates the left sidebar to show:

PACKAGE 1 (locked with lock icon)

PACKAGE 2 (locked with lock icon)

PACKAGE 3 (locked with lock icon)

System enables the "Next" button.

3.2.4. Selecting Brand

User clicks on the Brand dropdown.

System displays a list of brands the user has access to (alphabetically sorted).

User selects a brand (e.g., "Emma Taylor").

System assigns the selected brand to the group.

Brand selection is locked after clicking "Next" (cannot be changed within the wizard).

3.2.5. Proceeding to Package Configuration

User reviews the entered information.

User clicks "Next" button.

System validates all required fields:

Group Name is not empty and is unique

Number of Packages is selected

Brand is selected

If validation passes:

System saves the group settings to draft

System unlocks PACKAGE 1 in the left sidebar

System navigates to Package 1: Step 1 (Name and Events)

If validation fails, system displays inline errors and prevents navigation.

3.3. Package 1: Step 1 - Name and Events

3.3.1. Accessing Package 1 Configuration

Wizard highlights PACKAGE 1 in the left sidebar.

Left sidebar expands to show sub-steps under PACKAGE 1:

STEP 1: Name and Events (active, orange indicator)

STEP 2: Choose Services (locked, gray)

Center canvas displays:

Package Name input field

Which Events Are Part of This Package? section with event type buttons

Select Primary Event dropdown (appears only if 2+ events selected)

Informational tooltip explaining primary event logic

3.3.2. Entering Package Name

User clicks on the Package Name input field.

System displays placeholder text: "e.g., Photo/Video Bronze".

User types the package name (max 100 characters).

System validates in real-time:

Name cannot be empty

Name must be unique within the package group

If validation fails, inline error appears.

3.3.3. Selecting Events

User views the "Which Events Are Part of This Package?" section.

System displays event type buttons in a grid layout:

Wedding

Rehearsal Dinner

Engagement Photoshoot

Elopement

Proposal

Newborn Photography

Family Portraits

Birthday Parties

Maternity Shoot

Corporate Shoot

Graduation

Anniversary

Real Estate

Music Video

Product Photography

Fashion Shoot

Baby Shower

Holiday Party

Senior Portraits

Bar Mitzvah

Bat Mitzvah

User clicks on one or more event buttons to select them (e.g., "Wedding", "Rehearsal Dinner").

Selected events display with an orange/yellow background color and checkmark.

System requires at least one event to be selected before proceeding.

3.3.4. Selecting Primary Event (Multi-Event Logic)

If user selects only one event:

The Select Primary Event dropdown does NOT appear.

The single selected event is automatically designated as the primary event.

If user selects multiple events (2 or more):

System displays the Select Primary Event dropdown below the event buttons.

Dropdown contains all selected events (e.g., "Wedding", "Rehearsal Dinner").

User selects one event as the primary (e.g., "Wedding").

System marks the selected event as primary.

Primary event is used for:

Default deliverable due date calculations (based on primary event date)

Automation triggers in other modules

Event ordering in proposals

Informational Tooltip:

System displays a tooltip explaining: "While most packages likely only include one event, some may include multiple. For example, a package might include both a wedding and a rehearsal dinner or engagement shoot. You will be able to add line items for each event after you complete this stepper process."

3.3.5. Proceeding to Step 2 (Choose Services)

User reviews the entered package name and selected events.

User clicks "Next" button.

System validates:

Package name is not empty and is unique

At least one event is selected

If 2+ events selected, primary event is designated

If validation passes:

System saves Package 1 Step 1 data to draft

System unlocks STEP 2: Choose Services for Package 1

System navigates to Package 1: Step 2 (Choose Services)

If validation fails, system displays inline errors and prevents navigation.

3.4. Package 1: Step 2 - Choose Services

3.4.1. Accessing Step 2

Wizard highlights STEP 2: Choose Services under PACKAGE 1 in the left sidebar.

Center canvas displays:

"Same services for all events" toggle (ON by default if multiple events selected)

"Which Services Are Part of This Package?" section

Service selection interface (layout depends on toggle state)

3.4.2. Same Services Toggle - ON (Default for Multi-Event Packages)

When the toggle is ON:

System displays a single unified service selection section.

Section shows three service type buttons:

Photography

Videography

Content Creation

User selects one or more services by clicking buttons.

Selected services display with an orange/yellow background and checkmark.

System applies the selected services to all events in the package.

Example: If user selects "Photography" and "Videography", both services are assigned to "Wedding" AND "Rehearsal Dinner" events.

Informational Tooltip:

System displays tooltip: "When enabled, the same service types will apply to all events in this package. Disable this if you need different services for different events."

3.4.3. Same Services Toggle - OFF (Different Services Per Event)

When the user toggles OFF:

System displays a separate service selection section for each event selected in Step 1.

Each event section shows:

Event name as a header (e.g., "Wedding", "Rehearsal Dinner")

Three service type buttons: Photography, Videography, Content Creation

User selects services independently for each event.

Example:

Wedding: User selects "Photography" and "Videography"

Rehearsal Dinner: User selects "Photography" only

System validates that at least one service is selected for each event before proceeding.

Toggle Change Confirmation:

If user toggles from ON to OFF after selecting services:

System displays confirmation modal: "Switching to event-specific services will reset your current selections. Continue?"

If user confirms, system clears previous selections and displays event-specific sections.

If user cancels, toggle remains in ON state.

3.4.4. Completing Package 1 Configuration

User reviews the selected services.

User clicks "Next" button.

System validates:

At least one service is selected for each event (if toggle OFF)

At least one service is selected (if toggle ON)

If validation passes:

System saves Package 1 Step 2 data to draft

System marks Package 1 as complete (checkmark icon in sidebar)

If more packages exist (e.g., user selected 3 packages):

System unlocks PACKAGE 2 in the left sidebar

System navigates to Package 2: Step 1 (Name and Events)

If Package 1 is the only package:

"Next" button changes to "Finish"

System prepares to transition to Package Builder

If validation fails, system displays inline errors.

3.5. Configuring Additional Packages (Package 2, 3, 4, 5, 6)

3.5.1. Repeating Steps for Each Package

After completing Package 1, system unlocks Package 2.

User follows the same two-step process for Package 2:

Step 1: Enter package name and select events (with primary event if applicable)

Step 2: Choose services (with same services toggle option)

System repeats this flow for each package in the group (up to 6 packages).

Left sidebar displays completion status:

Completed packages show a green checkmark icon

Current package shows an orange indicator

Locked packages show a gray lock icon

3.5.2. Navigating Between Packages

Moving Forward:

User completes current package steps and clicks "Next" to proceed to the next package.

Moving Backward:

User can click on a previously completed package in the left sidebar to edit its configuration.

System loads the selected package's Step 1 or Step 2 for editing.

Changes are auto-saved to draft.

Skipping Packages:

Users cannot skip packages; all must be configured sequentially.

System enforces linear progression until all packages are completed.

3.5.3. Last Package Completion

User completes the final package's Step 2 (e.g., Package 3 if user selected 3 packages).

System changes the "Next" button to "Finish" button.

User clicks "Finish".

System validates that all packages are fully configured.

If validation passes:

System saves the entire package group structure to draft

System closes the wizard

System navigates to the Package Builder (Section 3) with the new group loaded

3.6. Editing Package Count After Initial Setup

3.6.1. Increasing Package Count

User is in the wizard or Package Builder and opens Group Settings.

User increases the Number of Packages (e.g., from 3 to 4).

System dynamically adds a new package slot (e.g., PACKAGE 4) to the left sidebar.

New package slot is locked and requires configuration.

If "Same Services For All Events" was ON:

New package automatically inherits the same events and services as the previous packages.

User can modify the inherited configuration for the new package.

If "Same Services For All Events" was OFF:

System opens a modal prompting user to configure events and services for the new package.

User must complete Step 1 and Step 2 for the new package before proceeding.

3.6.2. Decreasing Package Count

User is in the wizard or Package Builder and opens Group Settings.

User decreases the Number of Packages (e.g., from 4 to 3).

System displays a confirmation modal:

Title: "Remove Package?"

Message: "Reducing the number of packages will permanently delete Package 4 and all its configuration. This action cannot be undone. Continue?"

Buttons: "Cancel" and "Remove Package" (red, destructive)

If user confirms:

System deletes the last package (Package 4) and all its internal data.

System removes the package slot from the left sidebar.

System updates the group's package count to 3.

If user cancels, no changes are made.

3.7. Canceling the Wizard

3.7.1. Clicking Cancel Button

User clicks the "Cancel" button at the bottom left of the wizard.

System displays a confirmation modal:

Title: "Cancel Package Group Creation?"

Message: "Your progress will be saved as a draft. You can resume editing later from the Package List. Continue?"

Buttons: "Stay" and "Exit"

If user clicks "Exit":

System saves all entered data to draft

System closes the wizard

System returns user to the Package List View (Section 1)

Draft group appears in the list with "Draft" label

If user clicks "Stay", wizard remains open with no changes.

3.7.2. Clicking Close (X) Button

User clicks the X close button at the top right of the wizard.

System behavior is identical to clicking "Cancel" button (see 3.7.1).

3.8. Auto-Save and Draft Behavior

3.8.1. Auto-Save Trigger Points

The system automatically saves progress to draft at the following points:

After user completes Group Settings (Step 0) and clicks "Next"

After user completes each package's Step 1 and clicks "Next"

After user completes each package's Step 2 and clicks "Next"

When user navigates backward to edit a previous step

When user closes the wizard (all data saved as draft)

3.8.2. Draft Status

All groups created or edited via the wizard are saved in Draft status.

Draft groups appear in the Package List View with a "Draft" label or badge.

Draft groups are NOT available for use in proposals until published.

Users can resume editing draft groups at any time from the Package List View.

3.9. Transition to Package Builder

3.9.1. Completing the Wizard

User completes all packages and clicks "Finish" on the last package's Step 2.

System validates that all packages are fully configured.

System saves the group structure to draft.

System closes the wizard modal/page.

System navigates to the Package Builder (Section 3) with the following URL: /packages/builder/{group_id}

3.9.2. Package Builder Initial State

When the Package Builder loads:

Left Sidebar displays all packages in the group (e.g., Package 1, Package 2, Package 3).

First package is automatically selected and displayed in the center canvas.

Center Canvas shows:

Package name (editable)

Package description field (empty)

Package price field (empty, placeholder: "Specify the price")

Event sections for each event (e.g., WEDDING, REHEARSAL DINNER)

Service type labels under each event (e.g., Photography, Videography)

Empty line item slots with placeholder text: "Line item"

"Assign A La Carte Items +" button

User can now proceed to configure line items, deliverables, smart fields, tax settings, and pricing in the Package Builder.

4. FUNCTIONAL LOGIC

4.1. Wizard Initialization Logic

4.1.1. Opening the Wizard

When a user with Owner or Admin role clicks "Create New Group" in the Package List View:

System validates user permissions.

System initializes a new package group record in the database with:

Status: Draft

Created timestamp: Current date/time

Created by: Current user ID

Agency ID: Current user's agency

System generates a unique group ID (UUID or auto-increment).

System opens the wizard interface (modal or full-page view).

System displays Group Settings as the initial step.

Left sidebar shows "GROUP SETTINGS" (active) and no package slots yet.

4.1.2. Wizard State Management

The wizard maintains state across steps using:

Session storage (for temporary wizard state during creation)

Database draft records (for persistent auto-save)

In-memory state (for immediate validation and UI updates)

System tracks:

Current active step (Group Settings, Package 1 Step 1, Package 1 Step 2, etc.)

Completion status of each step (incomplete, complete, edited)

User input for all fields (name, brand, events, services, toggle state)

4.2. Group Settings Logic (Step 0)

4.2.1. Group Name Validation

When user enters a group name:

System trims leading and trailing whitespace.

System validates:

Not Empty: Name must have at least 1 character.

Max Length: Name cannot exceed 100 characters.

Uniqueness: Name must be unique within the selected brand.

Uniqueness check:

System queries the database for existing groups where:

brand_id = selected brand ID

group_name = entered name (case-insensitive)

If match found, display error: "Group name already exists."

Validation occurs:

On blur (when user clicks outside the field)

On "Next" button click

4.2.2. Number of Packages Selection

When user selects a number from the dropdown:

System captures the selected value (1-6).

System dynamically generates package slots in the left sidebar:

If user selects 3: Display "PACKAGE 1", "PACKAGE 2", "PACKAGE 3" (all locked initially).

If user selects 6: Display "PACKAGE 1" through "PACKAGE 6".

System stores the package count in the group record.

System displays lock icons next to each package slot (unlocked sequentially as user progresses).

4.2.3. Brand Assignment

When user selects a brand:

System retrieves all brands accessible to the current user from the Brand Master Data.

System displays brands in alphabetical order in the dropdown.

User selects one brand.

System assigns the brand ID to the package group record.

Brand Lock Rule: Once user clicks "Next" and proceeds to Package 1, the brand cannot be changed within the wizard.

To change brand later, user must open Group Settings in the Package Builder.

4.2.4. Proceeding to Package 1

When user clicks "Next":

System validates all three fields (Group Name, Number of Packages, Brand).

If validation passes:

System saves Group Settings to database:

group_name = entered name

brand_id = selected brand

package_count = selected number

status = Draft

System unlocks PACKAGE 1 in the left sidebar (removes lock icon).

System navigates to Package 1: Step 1 (Name and Events).

"GROUP SETTINGS" in sidebar changes from active (orange) to complete (green checkmark).

If validation fails, system displays inline errors and prevents navigation.

4.3. Package Step 1 - Name and Events Logic

4.3.1. Package Name Validation

When user enters a package name:

System trims leading and trailing whitespace.

System validates:

Not Empty: Name must have at least 1 character.

Max Length: Name cannot exceed 100 characters.

Uniqueness: Name must be unique within the package group.

Uniqueness check:

System queries existing package names within the current group.

If match found (case-insensitive), display error: "Package name already exists within this group."

Validation occurs on blur and on "Next" button click.

4.3.2. Event Selection Logic

When user selects events:

System displays all event types from the Event Type Master Data in a grid layout.

User clicks on event buttons to select/deselect.

Selected events display with:

Orange/yellow background color

Checkmark icon (optional)

System allows multi-select (user can select 1 to N events).

System stores selected event IDs in an array: selected_events = [event_id_1, event_id_2, ...]

4.3.3. Primary Event Logic (Multi-Event Packages)

If user selects only 1 event:

System automatically designates the single event as the primary event.

primary_event_id = selected event ID.

Select Primary Event dropdown does NOT appear.

If user selects 2 or more events:

System displays the Select Primary Event dropdown below the event buttons.

Dropdown is populated with all selected events.

Dropdown is required (user cannot proceed without selecting a primary event).

User selects one event from the dropdown (e.g., "Wedding").

System stores the selected event ID as primary_event_id.

Primary Event Purpose:

Deliverable Due Dates: Line items marked as deliverable use the primary event's date to calculate due dates (Event Date + X days/weeks/months).

Automation Triggers: Other modules (e.g., Post-Production, Project Management) use the primary event for workflow automation.

Event Ordering: In proposals and projects, the primary event is displayed first or prioritized in calendars.

4.3.4. Proceeding to Step 2

When user clicks "Next":

System validates:

Package name is not empty and is unique within the group.

At least one event is selected.

If 2+ events selected, primary event is designated (dropdown value is not null).

If validation passes:

System saves Package Step 1 data to database:

package_name = entered name

selected_events = array of event IDs

primary_event_id = primary event ID

System unlocks STEP 2: Choose Services for the current package in the sidebar.

System navigates to Package Step 2 (Choose Services).

STEP 1 in sidebar changes from active (orange) to complete (green checkmark).

If validation fails, system displays inline errors.

4.4. Package Step 2 - Choose Services Logic

4.4.1. Same Services Toggle - Default State

Default Behavior:

If user selected multiple events in Step 1: Toggle is ON by default.

If user selected only one event in Step 1: Toggle is hidden (not needed; services apply to the single event by default).

4.4.2. Same Services Toggle - ON

When the toggle is ON:

System displays a single unified service selection section.

Section header: "Which Services Are Part of This Package?"

System displays three service type buttons:

Photography

Videography

Content Creation

User selects one or more services by clicking buttons.

Selected services are highlighted (orange/yellow background, checkmark).

System stores selected services in an array: selected_services = [service_id_1, service_id_2, ...]

Service Application Logic:

System applies the selected services to all events in the package.

Example: If user selected "Wedding" and "Rehearsal Dinner" in Step 1, and selects "Photography" and "Videography" in Step 2 (toggle ON):

Wedding gets Photography + Videography

Rehearsal Dinner gets Photography + Videography

4.4.3. Same Services Toggle - OFF

When the user toggles OFF:

System displays separate service selection sections for each event selected in Step 1.

Each section shows:

Event name as a header (e.g., "WEDDING", "REHEARSAL DINNER")

Three service type buttons: Photography, Videography, Content Creation

User selects services independently for each event.

System stores services per event in a nested structure:

event_services = { event_id_1: [service_id_1, service_id_2], event_id_2: [service_id_3]}

Example:

Wedding: User selects "Photography" and "Videography"

Rehearsal Dinner: User selects "Photography" only

System validates that at least one service is selected for each event before allowing user to proceed.

4.4.4. Toggle Change Confirmation Logic

Scenario: User toggles from ON to OFF after selecting services

System detects toggle state change.

System displays a confirmation modal:

Title: "Change Service Selection Mode?"

Message: "Switching to event-specific services will reset your current selections. You will need to select services for each event individually. Continue?"

Buttons: "Cancel" and "Continue"

If user clicks "Continue":

System clears the previously selected unified services.

System displays event-specific service sections.

User must reselect services for each event.

If user clicks "Cancel":

Toggle reverts to ON state.

Previously selected services remain intact.

Scenario: User toggles from OFF to ON after selecting event-specific services

System detects toggle state change.

System displays a confirmation modal:

Title: "Change Service Selection Mode?"

Message: "Switching to unified services will apply the same services to all events. Your current event-specific selections will be replaced. Continue?"

Buttons: "Cancel" and "Continue"

If user clicks "Continue":

System clears event-specific service selections.

System displays unified service selection section.

User must select services that will apply to all events.

If user clicks "Cancel":

Toggle reverts to OFF state.

Event-specific services remain intact.

4.4.5. Proceeding to Next Package or Finishing

When user clicks "Next" (or "Finish" if this is the last package):

System validates:

If toggle ON: At least one service is selected (applies to all events).

If toggle OFF: At least one service is selected for each event.

If validation passes:

System saves Package Step 2 data to database:

If toggle ON: selected_services = array of service IDs (applies to all events)

If toggle OFF: event_services = nested object mapping event IDs to service ID arrays

same_services_toggle = ON/OFF state

System marks the current package as complete (green checkmark in sidebar).

If more packages exist:

System unlocks the next package (e.g., PACKAGE 2) in the sidebar.

System navigates to Package 2: Step 1 (Name and Events).

If this is the last package:

System marks the entire group as structurally complete.

System displays "Finish" button instead of "Next".

User clicks "Finish" to proceed to Package Builder.

If validation fails, system displays inline errors.

4.5. Adding or Removing Packages After Initial Setup

4.5.1. Increasing Package Count

Trigger: User edits Group Settings and increases the Number of Packages value.

Logic:

System detects the change (e.g., from 3 packages to 4 packages).

System adds a new package slot (PACKAGE 4) to the left sidebar.

New package is locked and requires configuration.

If "Same Services For All Events" was ON for existing packages:

System auto-inherits events and services from the last configured package.

Example: If Package 3 had "Wedding" + "Photography/Videography", Package 4 inherits the same by default.

User can edit inherited configuration.

If "Same Services For All Events" was OFF:

System opens a modal prompting user to configure the new package.

Modal displays:

Title: "Configure New Package"

Message: "Please configure events and services for Package 4."

Button: "Start Configuration"

User clicks "Start Configuration" and is taken to Package 4: Step 1.

4.5.2. Decreasing Package Count

Trigger: User edits Group Settings and decreases the Number of Packages value.

Logic:

System detects the change (e.g., from 4 packages to 3 packages).

System identifies the package(s) to be removed (last package(s), e.g., PACKAGE 4).

System displays a confirmation modal:

Title: "Remove Package?"

Message: "Reducing the number of packages will permanently delete Package 4 and all its configuration (events, services, line items). This action cannot be undone. Continue?"

Buttons: "Cancel" (gray) and "Remove Package" (red, destructive)

If user clicks "Remove Package":

System deletes the package record from the database.

System removes the package slot from the left sidebar.

System updates package_count to 3.

System displays success toast: "Package removed successfully."

If user clicks "Cancel":

No changes are made.

Package count reverts to original value.

4.6. Auto-Save and Draft Management

4.6.1. Auto-Save Trigger Points

System automatically saves data to the database at the following points:

After Group Settings Step: When user clicks "Next" from Group Settings.

After Each Package Step 1: When user clicks "Next" from a package's Name and Events step.

After Each Package Step 2: When user clicks "Next" from a package's Choose Services step.

On Navigation Backward: When user clicks on a previous step to edit.

On Wizard Close: When user clicks "Cancel" or "X" to exit the wizard.

Periodic Auto-Save: Every 30 seconds while the wizard is open (optional, for added data safety).

4.6.2. Draft Status Rules

All package groups created via the wizard are saved with status = Draft.

Draft groups appear in the Package List View with a "Draft" badge or label.

Draft groups are not available for use in proposals.

Only Published groups can be used in proposals.

4.6.3. Resuming Draft Groups

User can click "Edit" on a draft group from the Package List View.

System loads the group in the Package Builder (Section 3), not the wizard.

User can modify group structure via "Group Settings" button in the Package Builder.

User must complete all packages and publish the group to make it available for proposals.

4.7. Transition to Package Builder Logic

4.7.1. Wizard Completion Validation

When user clicks "Finish" on the last package's Step 2:

System validates that all packages in the group are fully configured:

Each package has a unique name.

Each package has at least one event selected.

Each package has a primary event designated (if multi-event).

Each package has at least one service selected (unified or per-event).

If validation fails:

System displays a modal: "Incomplete Configuration - Please complete all packages before finishing."

System highlights the incomplete package(s) in the sidebar with a warning icon.

User must complete the missing steps before proceeding.

If validation passes:

System saves all data to the database.

System marks the group structure as complete.

System closes the wizard.

System navigates to the Package Builder.

4.7.2. Package Builder Initial Load

When the Package Builder loads after wizard completion:

URL: /packages/builder/{group_id}

Left Sidebar: Displays all packages (e.g., Package 1, Package 2, Package 3) with settings icons.

First Package Auto-Selected: System automatically selects and displays Package 1 in the center canvas.

Center Canvas Displays:

Package Name: Pre-filled from wizard (editable).

Package Description: Empty text area (user can add description).

Package Price: Empty field with placeholder "Specify the price" (user must enter price before publishing).

Package Image: Placeholder with "Add Image" button (user can upload image).

Event Sections: Each event selected in wizard is displayed as a colored section (e.g., "WEDDING" in beige, "REHEARSAL DINNER" in blue).

Service Types: Listed under each event (e.g., "Photography", "Videography").

Line Items: Empty slots with placeholder text "Line item" (user can add line items).

"Assign A La Carte Items +" button at the bottom.

User Next Steps in Package Builder:

Add line items for each event.

Configure deliverables and due dates.

Add smart fields (if applicable).

Set package price.

Upload package image.

Configure tax mode.

Link A-la-carte items.

Publish the package group.

5. FIELD DETAILS & VALIDATIONS

5.1. Group Settings Fields (Step 0)

5.1.1. Group Name

Field Type: Text input

Data Type: String

Max Length: 100 characters

Required: Yes

Validation Rules:

Cannot be empty (must have at least 1 character after trimming whitespace)

Must be unique within the selected brand (case-insensitive)

Special characters allowed (e.g., "&", "-", "/", spaces)

Leading and trailing whitespace is automatically trimmed

Error Messages:

"Group name is required." (if empty)

"Group name already exists." (if duplicate within brand)

Placeholder Text: "e.g., Photography/Videography Combo"

Display Behavior:

Inline validation on blur and on "Next" button click

Error message displayed below the field in red text

5.1.2. Number of Packages

Field Type: Dropdown (single-select)

Data Type: Integer

Allowed Values: 1, 2, 3, 4, 5, 6

Required: Yes

Validation Rules:

User must select a value from the dropdown

Default value: None (user must make an explicit selection)

Error Messages:

"Number of packages is required." (if user clicks "Next" without selecting)

Display Behavior:

Dropdown displays all six options

After selection, left sidebar dynamically updates to show corresponding package slots (e.g., 3 packages → PACKAGE 1, PACKAGE 2, PACKAGE 3)

5.1.3. Brand

Field Type: Dropdown (single-select)

Data Type: Reference to Brand Master Data

Required: Yes

Validation Rules:

User must select a brand from the dropdown

User can only select brands they have access to (based on role and permissions)

Default value: None (user must make an explicit selection)

Error Messages:

"Brand is required." (if user clicks "Next" without selecting)

Placeholder Text: "Select a brand"

Display Behavior:

Dropdown displays all accessible brands in alphabetical order

After selection, brand is locked (cannot be changed within the wizard)

To change brand later, user must open Group Settings in Package Builder

5.1.4. Informational Tooltip

Field Type: Tooltip (informational, non-editable)

Content: "Feel free to switch things up while building your package — your choices aren't set in stone."

Display Behavior:

Appears as a blue info icon (i) next to the "Number of Packages" field

Tooltip displays on hover or click

Provides reassurance that users can edit configurations later

5.2. Package Step 1 - Name and Events Fields

5.2.1. Package Name

Field Type: Text input

Data Type: String

Max Length: 100 characters

Required: Yes

Validation Rules:

Cannot be empty (must have at least 1 character after trimming whitespace)

Must be unique within the package group (cannot duplicate other package names in the same group)

Special characters allowed

Leading and trailing whitespace is automatically trimmed

Error Messages:

"Package name is required." (if empty)

"Package name already exists within this group." (if duplicate)

Placeholder Text: "e.g., Photo/Video Bronze"

Display Behavior:

Inline validation on blur and on "Next" button click

Error message displayed below the field in red text

5.2.2. Event Type Selection (Multi-Select Buttons)

Field Type: Multi-select button group

Data Type: Array of Event Type IDs (references Event Type Master Data)

Required: Yes (at least one event must be selected)

Validation Rules:

User must select at least one event

User can select multiple events (no upper limit)

Selected events display with orange/yellow background and checkmark

Deselecting all events triggers validation error

Error Messages:

"Select at least one event." (if user clicks "Next" with no events selected)

Available Event Types:

Wedding

Rehearsal Dinner

Engagement Photoshoot

Elopement

Proposal

Newborn Photography

Family Portraits

Birthday Parties

Maternity Shoot

Corporate Shoot

Graduation

Anniversary

Real Estate

Music Video

Product Photography

Fashion Shoot

Baby Shower

Holiday Party

Senior Portraits

Bar Mitzvah

Bat Mitzvah

Display Behavior:

Event buttons displayed in a responsive grid layout (3-4 columns)

Selected buttons change background color to orange/yellow with checkmark

Unselected buttons display with gray background

5.2.3. Select Primary Event (Dropdown)

Field Type: Dropdown (single-select)

Data Type: Event Type ID (reference)

Required: Yes, only if 2 or more events are selected

Validation Rules:

If 1 event selected: Dropdown is hidden; single event is auto-designated as primary

If 2+ events selected: Dropdown is required; user must explicitly select one event as primary

Dropdown options populated with only the events selected in the multi-select buttons above

Error Messages:

"Primary event must be selected." (if user clicks "Next" without selecting when 2+ events are selected)

Placeholder Text: "Select primary event"

Display Behavior:

Dropdown appears only when user selects 2 or more events

Dropdown options dynamically update based on selected events

Once user selects primary event, dropdown shows the selected value

5.2.4. Informational Tooltip (Primary Event)

Field Type: Tooltip (informational, non-editable)

Content: "While most packages likely only include one event, some may include multiple. For example, a package might include both a wedding and a rehearsal dinner or engagement shoot. You will be able to add line items for each event after you complete this stepper process."

Display Behavior:

Appears as a blue info icon (i) next to the "Select Primary Event" dropdown

Tooltip displays on hover or click

5.3. Package Step 2 - Choose Services Fields

5.3.1. Same Services For All Events (Toggle)

Field Type: Toggle switch (boolean)

Data Type: Boolean (true = ON, false = OFF)

Required: No (optional; default is ON for multi-event packages, hidden for single-event packages)

Validation Rules:

Toggle state determines UI layout and service selection behavior

If toggled ON → OFF: System displays confirmation modal before clearing selections

If toggled OFF → ON: System displays confirmation modal before clearing event-specific selections

Default Value:

ON if package has 2+ events (default for multi-event packages)

Hidden if package has only 1 event (not applicable)

Display Behavior:

Toggle switch displayed at the top of the services selection section

Label: "Same services for all events"

Info icon with tooltip explaining toggle behavior

5.3.2. Service Type Selection (Unified - Toggle ON)

Field Type: Multi-select button group

Data Type: Array of Service Type IDs (references Service Type Master Data)

Required: Yes (at least one service must be selected)

Validation Rules:

User must select at least one service

User can select multiple services (up to all three)

Selected services apply to all events in the package

Deselecting all services triggers validation error

Error Messages:

"Select at least one service." (if user clicks "Next" with no services selected)

Available Service Types:

Photography

Videography

Content Creation

Display Behavior:

Three large buttons displayed horizontally or in a grid

Selected buttons display with orange/yellow background and checkmark

Unselected buttons display with gray background

5.3.3. Service Type Selection (Per-Event - Toggle OFF)

Field Type: Multi-select button groups (one per event)

Data Type: Nested object mapping Event IDs to arrays of Service Type IDs

Required: Yes (at least one service must be selected per event)

Validation Rules:

Each event section must have at least one service selected

User can select different services for each event

If any event has no services selected, validation error is triggered

Error Messages:

"Select at least one service for [Event Name]." (e.g., "Select at least one service for Wedding.")

Display Behavior:

Separate sections displayed for each event selected in Step 1

Each section shows:

Event name as a header (e.g., "WEDDING", "REHEARSAL DINNER")

Three service type buttons: Photography, Videography, Content Creation

Selected buttons display with orange/yellow background and checkmark

Unselected buttons display with gray background

5.3.4. Informational Tooltip (Same Services Toggle)

Field Type: Tooltip (informational, non-editable)

Content: "When enabled, the same service types will apply to all events in this package. Disable this if you need different services for different events."

Display Behavior:

Appears as a blue info icon (i) next to the toggle switch

Tooltip displays on hover or click

6. SUCCESS MESSAGE HANDLING

6.1. Success Message Display Rules

Success messages in the Package Group Creation Flow are displayed as:

Toast Notifications: Non-blocking notifications at the top-right corner of the screen for major actions (e.g., saving draft, completing wizard)

Visual Feedback: Checkmarks and color changes in the left sidebar to indicate completed steps

All toast notifications:

Display for 5 seconds before auto-dismissing

Can be manually dismissed by clicking the "X" icon

Use a green checkmark icon

Do not block user interaction with the wizard

6.2. Step Completion Success (Implicit)

6.2.1. Trigger Condition

User successfully completes a step (Group Settings, Package Step 1, or Package Step 2) and clicks "Next".

6.2.2. Visual Feedback

No toast notification is displayed (visual feedback is sufficient).

The completed step in the left sidebar changes from active state (orange indicator) to completed state (green checkmark icon).

The next step is automatically unlocked and highlighted in the sidebar.

System smoothly transitions to the next step's interface.

6.3. Package Configuration Complete Success (Implicit)

6.3.1. Trigger Condition

User completes the final step (Step 2) for a package, and the package is marked as fully configured.

6.3.2. Visual Feedback

No toast notification is displayed.

The package in the left sidebar displays a green checkmark icon next to its name (e.g., "✓ PACKAGE 1").

If more packages exist, the next package is automatically unlocked.

If this was the last package, the "Next" button changes to "Finish" button.

6.4. Draft Auto-Save Success (Implicit)

6.4.1. Trigger Condition

System automatically saves user progress to draft at trigger points (after each step completion, on navigation backward, on wizard close).

6.4.2. Visual Feedback

No toast notification is displayed (to avoid interrupting user flow).

Optionally, a small "Saving..." indicator may briefly appear in the top right (e.g., a rotating spinner icon) and disappear once save is complete.

Draft status is persisted in the database, allowing users to resume later.

6.5. Wizard Canceled Success

6.5.1. Trigger Condition

User clicks "Cancel" or "X" close button, confirms exit in the modal, and the wizard closes.

6.5.2. Success Message

Message Text: "Your progress has been saved as a draft."

6.5.3. Message Details

Display Location: Top-right toast notification

Icon: Green checkmark

Duration: 5 seconds

Dismissible: Yes

6.5.4. Post-Success Actions

System displays the success message.

System closes the wizard modal/page.

System returns user to the Package List View (Section 1).

Draft group appears in the list with a "Draft" badge.

User can resume editing the draft later by clicking "Edit" on the draft group.

6.6. Package Group Structure Complete Success

6.6.1. Trigger Condition

User clicks "Finish" on the last package's Step 2, all validation passes, and the wizard prepares to transition to the Package Builder.

6.6.2. Success Message

Message Text: "Package group structure created successfully. You can now configure line items and pricing."

6.6.3. Message Details

Display Location: Top-right toast notification

Icon: Green checkmark

Duration: 5 seconds

Dismissible: Yes

6.6.4. Post-Success Actions

System displays the success message.

System closes the wizard.

System navigates to the Package Builder (Section 3) with the new group loaded.

User can immediately begin configuring packages with line items, smart fields, deliverables, pricing, and images.

6.7. Package Count Increased Success

6.7.1. Trigger Condition

User edits Group Settings and increases the number of packages, and the system successfully adds a new package slot.

6.7.2. Success Message

Message Text: "Package slot added successfully."

6.7.3. Message Details

Display Location: Top-right toast notification

Icon: Green checkmark

Duration: 5 seconds

Dismissible: Yes

6.7.4. Post-Success Actions

System displays the success message.

System adds the new package slot to the left sidebar (e.g., PACKAGE 4).

New package is locked and requires configuration.

User can click on the new package to begin configuring it.

6.8. Package Removed Success

6.8.1. Trigger Condition

User edits Group Settings, decreases the number of packages, confirms the removal, and the system successfully deletes the package.

6.8.2. Success Message

Message Text: "Package removed successfully."

6.8.3. Message Details

Display Location: Top-right toast notification

Icon: Green checkmark

Duration: 5 seconds

Dismissible: Yes

6.8.4. Post-Success Actions

System displays the success message.

System removes the package slot from the left sidebar.

System updates the package count in Group Settings.

User can continue configuring remaining packages.

7. ERROR MESSAGE HANDLING

7.1. Error Message Display Rules

Error messages in the Package Group Creation Flow are displayed in two formats:

Inline Errors: Displayed directly below the relevant input field with red text and an error icon.

Modal Dialogs: Displayed as blocking modals for critical validation errors or confirmation prompts.

Toast Notifications: Displayed for system-level errors (e.g., server failures) at the top-right corner.

All error messages use:

Red text color for inline errors

Red error icon for toast notifications

Clear, actionable language

Specific guidance on how to resolve the error

7.2. Group Settings Errors (Step 0)

7.2.1. Error: Group Name Required

**Trigger Condition:

**User leaves the Group Name field empty and clicks "Next".

**Error Message:

**"Group name is required."

Display Type: Inline error below the Group Name input field

**User Action Required:

**User must enter a valid group name (at least 1 character after trimming whitespace).

System Behavior:

Error message appears immediately when user clicks "Next".

"Next" button remains enabled, but system prevents navigation.

Error disappears when user starts typing in the field.

7.2.2. Error: Group Name Already Exists

**Trigger Condition:

**User enters a group name that duplicates an existing group name within the selected brand (case-insensitive).

**Error Message:

**"Group name already exists."

Display Type: Inline error below the Group Name input field

**User Action Required:

**User must enter a unique group name.

System Behavior:

System checks for uniqueness when user clicks "Next" (or on blur).

If duplicate detected, error message appears.

Error disappears when user modifies the name.

7.2.3. Error: Number of Packages Required

**Trigger Condition:

**User does not select a value from the Number of Packages dropdown and clicks "Next".

**Error Message:

**"Number of packages is required."

Display Type: Inline error below the dropdown

**User Action Required:

**User must select a value from 1 to 6.

System Behavior:

Error appears when user clicks "Next" without selecting a value.

Error disappears when user selects a value.

7.2.4. Error: Brand Required

**Trigger Condition:

**User does not select a brand from the Brand dropdown and clicks "Next".

**Error Message:

**"Brand is required."

Display Type: Inline error below the dropdown

**User Action Required:

**User must select a brand from the dropdown.

System Behavior:

Error appears when user clicks "Next" without selecting a brand.

Error disappears when user selects a brand.

7.3. Package Step 1 Errors (Name and Events)

7.3.1. Error: Package Name Required

**Trigger Condition:

**User leaves the Package Name field empty and clicks "Next".

**Error Message:

**"Package name is required."

Display Type: Inline error below the Package Name input field

**User Action Required:

**User must enter a valid package name.

System Behavior:

Error appears when user clicks "Next" with empty field.

Error disappears when user starts typing.

7.3.2. Error: Package Name Already Exists

**Trigger Condition:

**User enters a package name that duplicates another package name within the same group (case-insensitive).

**Error Message:

**"Package name already exists within this group."

Display Type: Inline error below the Package Name input field

**User Action Required:

**User must enter a unique package name.

System Behavior:

System checks for uniqueness within the group when user clicks "Next".

If duplicate detected, error message appears.

Error disappears when user modifies the name.

7.3.3. Error: Select At Least One Event

**Trigger Condition:

**User does not select any events and clicks "Next".

**Error Message:

**"Select at least one event."

Display Type: Inline error below the event selection button group (or above the "Next" button)

**User Action Required:

**User must select at least one event from the available event types.

System Behavior:

Error appears when user clicks "Next" with no events selected.

Error disappears when user selects at least one event.

7.3.4. Error: Primary Event Must Be Selected

**Trigger Condition:

**User selects 2 or more events but does not select a primary event from the dropdown, then clicks "Next".

**Error Message:

**"Primary event must be selected."

Display Type: Inline error below the "Select Primary Event" dropdown

**User Action Required:

**User must select one event as the primary event from the dropdown.

System Behavior:

Error appears when user clicks "Next" without selecting primary event (when 2+ events are selected).

Error disappears when user selects a primary event.

7.4. Package Step 2 Errors (Choose Services)

7.4.1. Error: Select At Least One Service (Toggle ON)

**Trigger Condition:

**"Same services for all events" toggle is ON, user does not select any services, and clicks "Next".

**Error Message:

**"Select at least one service."

Display Type: Inline error below the service selection button group

**User Action Required:

**User must select at least one service (Photography, Videography, or Content Creation).

System Behavior:

Error appears when user clicks "Next" with no services selected.

Error disappears when user selects at least one service.

7.4.2. Error: Select At Least One Service Per Event (Toggle OFF)

**Trigger Condition:

**"Same services for all events" toggle is OFF, user leaves one or more events without any services selected, and clicks "Next".

**Error Message:

**"Select at least one service for [Event Name]."
(Example: "Select at least one service for Wedding.")

Display Type: Inline error below the event section that has no services selected

**User Action Required:

**User must select at least one service for each event.

System Behavior:

Error appears for each event that has no services selected.

Multiple error messages may appear if multiple events have no services.

Each error disappears when user selects at least one service for that event.

7.5. Package Configuration Errors

7.5.1. Error: Cannot Add Package - Complete Previous Package First

**Trigger Condition:

**User attempts to increase the number of packages (e.g., from 3 to 4) while a previous package (e.g., Package 3) is incomplete.

**Error Message:

**"Cannot add package. Complete previous package first."

Display Type: Toast notification (top-right, red error icon)

**User Action Required:

**User must complete the incomplete package before adding a new one.

System Behavior:

Toast notification displays for 7 seconds.

System prevents adding a new package slot.

User must navigate to the incomplete package and finish its configuration.

7.6. Toggle Change Confirmation Errors

7.6.1. Confirmation Modal: Toggle ON to OFF

**Trigger Condition:

**User toggles "Same services for all events" from ON to OFF after selecting services.

Modal Details:

Title: "Change Service Selection Mode?"

Message: "Switching to event-specific services will reset your current selections. You will need to select services for each event individually. Continue?"

Buttons: "Cancel" (gray) and "Continue" (orange/yellow)

**User Action Required:

**User must confirm or cancel the toggle change.

System Behavior:

If user clicks "Continue": Clear current selections, display event-specific sections, allow user to select services per event.

If user clicks "Cancel": Revert toggle to ON state, preserve current selections.

7.6.2. Confirmation Modal: Toggle OFF to ON

**Trigger Condition:

**User toggles "Same services for all events" from OFF to ON after selecting event-specific services.

Modal Details:

Title: "Change Service Selection Mode?"

Message: "Switching to unified services will apply the same services to all events. Your current event-specific selections will be replaced. Continue?"

Buttons: "Cancel" (gray) and "Continue" (orange/yellow)

**User Action Required:

**User must confirm or cancel the toggle change.

System Behavior:

If user clicks "Continue": Clear event-specific selections, display unified service section, allow user to select services for all events.

If user clicks "Cancel": Revert toggle to OFF state, preserve event-specific selections.

7.7. Wizard Cancellation Confirmation

7.7.1. Confirmation Modal: Cancel Wizard

**Trigger Condition:

**User clicks "Cancel" button or "X" close button to exit the wizard.

Modal Details:

Title: "Cancel Package Group Creation?"

Message: "Your progress will be saved as a draft. You can resume editing later from the Package List. Continue?"

Buttons: "Stay" (gray) and "Exit" (orange/yellow)

**User Action Required:

**User must confirm or cancel the exit action.

System Behavior:

If user clicks "Exit": Save all data to draft, close wizard, return to Package List View, display success toast: "Your progress has been saved as a draft."

If user clicks "Stay": Close modal, keep wizard open with no changes.

7.8. System-Level Errors

7.8.1. Error: Failed to Save Draft

**Trigger Condition:

**System encounters a server error or network issue while attempting to auto-save draft data.

**Error Message:

**"Failed to save your progress. Please check your connection and try again."

Display Type: Toast notification (top-right, red error icon)

**User Action Required:

**User should check their internet connection and retry the action (e.g., click "Next" again).

System Behavior:

Toast notification displays for 7 seconds.

Wizard remains open; user can retry.

If error persists, user can click "Cancel" to exit and resume later.

7.8.2. Error: Failed to Load Brand Data

**Trigger Condition:

**System encounters an error while fetching brand data for the Brand dropdown.

**Error Message:

**"Failed to load brand data. Please try again."

Display Type: Toast notification (top-right, red error icon)

**User Action Required:

**User should refresh the page or retry opening the wizard.

System Behavior:

Toast notification displays for 7 seconds.

Brand dropdown displays empty or with an error state.

User can close the wizard and try again later.

7.8.3. Error: Failed to Load Event Types

**Trigger Condition:

**System encounters an error while fetching event types for the event selection buttons.

**Error Message:

**"Failed to load event types. Please try again."

Display Type: Toast notification (top-right, red error icon)

**User Action Required:

**User should refresh the page or retry navigating to Package Step 1.

System Behavior:

Toast notification displays for 7 seconds.

Event selection section displays empty or with an error state.

User can navigate back or close the wizard.

8. EDGE CASES

8.1. User Switches Brand Context Mid-Creation

8.1.1. Edge Case Description

A user with access to multiple brands starts creating a package group, selects a brand (e.g., "Brand A"), and then switches the active brand context in the top navigation bar to a different brand (e.g., "Brand B") before completing the wizard.

8.1.2. Expected System Behavior

System detects the brand context switch.

System displays a warning modal:

Title: "Brand Context Changed"

Message: "You are currently creating a package group for Brand A, but your active context is now Brand B. Do you want to continue with Brand A or restart with Brand B?"

Buttons: "Continue with Brand A" and "Restart with Brand B"

If user clicks "Continue with Brand A": Wizard remains open with Brand A selected; no changes made.

If user clicks "Restart with Brand B": Wizard resets; all entered data is discarded; user starts fresh with Brand B selected.

8.1.3. User Action Required

User must decide whether to continue with the original brand or restart with the new brand.

8.2. User Reduces Number of Packages to Less Than Configured

8.2.1. Edge Case Description

User configures 4 packages (completes Step 1 and Step 2 for all 4), then opens Group Settings and reduces the number of packages to 2.

8.2.2. Expected System Behavior

System detects that reducing package count from 4 to 2 will delete Package 3 and Package 4 (which are already configured).

System displays a confirmation modal:

Title: "Remove Configured Packages?"

Message: "Reducing the number of packages to 2 will permanently delete Package 3 and Package 4, including all their configuration (events, services, line items). This action cannot be undone. Continue?"

Buttons: "Cancel" and "Remove Packages" (red, destructive)

If user clicks "Remove Packages":

System deletes Package 3 and Package 4 records from the database.

System removes Package 3 and Package 4 from the left sidebar.

System updates package count to 2.

System displays success toast: "Packages removed successfully."

If user clicks "Cancel": No changes made; package count remains 4.

8.2.3. User Action Required

User must confirm or cancel the removal of configured packages.

8.3. User Deselects All Events After Selecting Multiple

8.3.1. Edge Case Description

User selects 3 events (e.g., Wedding, Rehearsal Dinner, Engagement Photoshoot), then deselects all events by clicking each button again.

8.3.2. Expected System Behavior

System allows user to deselect all events (buttons return to gray background).

"Select Primary Event" dropdown disappears (since no events are selected).

When user clicks "Next", system displays inline error: "Select at least one event."

User cannot proceed until at least one event is selected.

8.3.3. User Action Required

User must reselect at least one event to proceed.

8.4. User Deselects All Services After Selecting Multiple

8.4.1. Edge Case Description

User selects 2 services (e.g., Photography and Videography), then deselects both services.

8.4.2. Expected System Behavior

System allows user to deselect all services (buttons return to gray background).

When user clicks "Next", system displays inline error: "Select at least one service."

User cannot proceed until at least one service is selected.

8.4.3. User Action Required

User must reselect at least one service to proceed.

8.5. User Closes Wizard Without Saving (Browser Closed)

8.5.1. Edge Case Description

User is in the middle of the wizard (e.g., configuring Package 2), and closes the browser tab or window without clicking "Cancel" or "Finish".

8.5.2. Expected System Behavior

System attempts to auto-save progress at the last trigger point (e.g., last completed step or last 30-second interval).

If auto-save was successful, draft data is preserved in the database.

When user returns to the Package List View and clicks "Edit" on the draft group:

System loads the wizard with the last saved state (e.g., Package 1 complete, Package 2 incomplete).

User can resume from where they left off.

If auto-save failed (e.g., due to network issue), user loses unsaved changes made after the last successful save.

8.5.3. User Action Required

User should resume editing the draft group to complete the wizard.

8.6. Duplicate Package Names Within Group

8.6.1. Edge Case Description

User enters the same package name for Package 1 and Package 2 (e.g., both named "Bronze Package").

8.6.2. Expected System Behavior

When user completes Package 2 Step 1 and clicks "Next", system validates package name uniqueness within the group.

System displays inline error: "Package name already exists within this group."

User cannot proceed until they change the package name to a unique value.

8.6.3. User Action Required

User must enter a different package name for Package 2.

8.7. User Edits Completed Package After Moving Forward

8.7.1. Edge Case Description

User completes Package 1 (both Step 1 and Step 2), moves to Package 2, then clicks back on Package 1 in the sidebar to edit it.

8.7.2. Expected System Behavior

System allows user to navigate back to Package 1.

System loads Package 1 Step 1 (Name and Events) or Step 2 (Choose Services) based on which step user clicks.

User can modify package name, events, or services.

Changes are auto-saved to draft.

Package 1 remains marked as complete (checkmark) after edits.

User can click on Package 2 again to resume configuring it.

8.7.3. User Action Required

None. System supports non-linear editing of completed packages.

8.8. User Attempts to Create Group with Same Name as Existing Draft

8.8.1. Edge Case Description

User creates a draft package group named "Photography Package", exits the wizard, then starts a new wizard and enters "Photography Package" again for the same brand.

8.8.2. Expected System Behavior

System checks for name uniqueness when user clicks "Next" from Group Settings.

System detects that "Photography Package" already exists (even if it's a draft).

System displays inline error: "Group name already exists."

User cannot proceed until they enter a unique name.

8.8.3. User Action Required

User must enter a different group name or edit the existing draft group instead.

8.9. User Selects Events Not Available in Event Master Data

8.9.1. Edge Case Description

An event type that was previously available in the Event Master Data is deleted or archived by an admin while a user is in the middle of the wizard.

8.9.2. Expected System Behavior

If user already selected the deleted event, it remains selected in the wizard (does not disappear).

If user navigates to a new package and tries to select events, the deleted event no longer appears in the button list.

System validates selected events against the current master data when user clicks "Next".

If a selected event is no longer valid, system displays inline error: "One or more selected events are no longer available. Please refresh and try again."

8.8.3. User Action Required

User should refresh the page and reselect valid events.

8.10. User Creates Group with Maximum (6) Packages

8.10.1. Edge Case Description

User selects the maximum number of packages (6) in Group Settings and completes all 6 packages.

8.10.2. Expected System Behavior

System allows user to configure all 6 packages without restrictions.

Left sidebar displays all 6 packages (PACKAGE 1 through PACKAGE 6).

User completes Step 1 and Step 2 for each package.

On Package 6 Step 2, the "Next" button changes to "Finish".

User clicks "Finish" to complete the wizard and transition to Package Builder.

All 6 packages appear in the Package Builder for detailed configuration.

8.10.3. User Action Required

None. System fully supports the maximum of 6 packages.

9. ACCEPTANCE CRITERIA

9.1. Wizard Initialization

AC1.1: Wizard Opens Successfully

Given a user with Owner or Admin role clicks "Create New Group" in the Package List View,

When the system loads the wizard,
Then the wizard must display Group Settings (Step 0) with three input fields: Group Name, Number of Packages, and Brand, and the left sidebar must show "GROUP SETTINGS" as active.

AC1.2: Wizard Displays Correct Number of Package Slots

Given a user selects a number from the Number of Packages dropdown (e.g., 3),

When the selection is made,
Then the system must dynamically update the left sidebar to display the corresponding number of package slots (e.g., PACKAGE 1, PACKAGE 2, PACKAGE 3) with lock icons.

9.2. Event Selection

AC2.1: Single Event Auto-Designated as Primary

Given a user selects only one event in Package Step 1,

When the user proceeds,
Then the system must automatically designate the single event as the primary event, and the "Select Primary Event" dropdown must not appear.

AC2.2: Primary Event Required for Multi-Event Packages

Given a user selects two or more events in Package Step 1,

When the user clicks "Next",
Then the system must require the user to select a primary event from the dropdown, and display an error if no primary event is selected.

AC2.3: Primary Event Dropdown Populated Correctly

Given a user selects multiple events (e.g., Wedding, Rehearsal Dinner, Engagement Photoshoot),

When the "Select Primary Event" dropdown appears,
Then the dropdown must contain only the events selected by the user (Wedding, Rehearsal Dinner, Engagement Photoshoot).

9.3. Service Selection

AC3.1: Same Services Toggle ON Behavior

Given the "Same services for all events" toggle is ON,

When the user selects one or more services (e.g., Photography, Videography),
Then the system must apply the selected services to all events in the package.

AC3.2: Same Services Toggle OFF Behavior

Given the "Same services for all events" toggle is OFF,

When the user views the service selection interface,
Then the system must display separate service selection sections for each event, and require at least one service to be selected per event.

AC3.3: Toggle Change Confirmation Modal

Given a user toggles "Same services for all events" from ON to OFF after selecting services,

When the toggle change occurs,
Then the system must display a confirmation modal warning that current selections will be reset, and allow the user to cancel or continue.

9.4. Add/Remove Package Logic

AC4.1: Increasing Package Count Adds New Slot

Given a user edits Group Settings and increases the number of packages (e.g., from 3 to 4),

When the change is saved,
Then the system must add a new package slot (PACKAGE 4) to the left sidebar, and the new package must be locked until configured.

AC4.2: Decreasing Package Count Removes Last Package

Given a user edits Group Settings and decreases the number of packages (e.g., from 4 to 3),

When the user confirms the removal,
Then the system must permanently delete Package 4 and all its configuration, and remove it from the left sidebar.

AC4.3: Confirmation Modal for Package Removal

Given a user reduces the number of packages,

When the change affects an already-configured package,
Then the system must display a confirmation modal warning that the package will be permanently deleted, and allow the user to cancel or proceed.

9.5. Auto-Save

AC5.1: Auto-Save After Each Step

Given a user completes a step (Group Settings, Package Step 1, or Package Step 2) and clicks "Next",

When the system validates and saves the data,
Then the data must be saved to draft status in the database.

AC5.2: Auto-Save on Wizard Exit

Given a user clicks "Cancel" or "X" to exit the wizard,

When the confirmation modal is displayed,
Then the system must save all entered data to draft before closing the wizard.

9.6. Handoff to Package Builder

AC6.1: Transition to Package Builder on Finish

Given a user completes all packages and clicks "Finish" on the last package's Step 2,

When the wizard completes,
Then the system must close the wizard and navigate to the Package Builder (Section 3) with the new group loaded.

AC6.2: Package Builder Initial State Correct

Given the Package Builder loads after wizard completion,

When the page displays,
Then the left sidebar must show all packages in the group, the first package must be auto-selected, and the center canvas must display the package configuration interface with events, services, and empty line item slots.

10. DEPENDENCIES

10.1. Internal Module Dependencies

10.1.1. Package List View (Section 1)

Dependency Type: REQUIRED

Relationship: The Package Group Creation Flow is initiated from the Package List View when users click "Create New Group".

Impact:

The "Create New Group" button in the Package List View triggers the wizard.

Draft groups created via the wizard appear in the Package List View with a "Draft" label.

Users can resume editing draft groups by clicking "Edit" in the Package List View.

Expected Behavior:

If the Package List View is unavailable, users cannot access the wizard.

10.1.2. Package Builder (Section 3)

Dependency Type: REQUIRED

Relationship: The Package Group Creation Flow transitions to the Package Builder upon wizard completion.

Impact:

After completing the wizard, users are automatically navigated to the Package Builder.

The Package Builder loads with the group structure (events, services, packages) configured in the wizard.

Users complete detailed package configuration (line items, deliverables, pricing, images) in the Package Builder.

Expected Behavior:

If the Package Builder is unavailable, users cannot proceed after completing the wizard, and the transition will fail.

10.2. External Data Dependencies

10.2.1. Brand Master Data

Dependency Type: REQUIRED

Relationship: The Brand dropdown in Group Settings pulls data from the Brand Master Data module.

Impact:

Users can only assign package groups to brands they have access to.

If the Brand Master Data is unavailable, the Brand dropdown will be empty or show an error.

Expected Behavior:

System should validate that the selected brand still exists when saving the group.

If a brand is deleted after assignment, the group should display "Archived Brand" and remain accessible for editing.

10.2.2. Event Type Master Data

Dependency Type: REQUIRED

Relationship: The event selection buttons in Package Step 1 pull data from the Event Type Master Data.

Impact:

Events displayed in the wizard are defined in the Event Type Master Data.

If an event type is deleted from the master data, it will no longer appear in the wizard for new packages.

Existing packages that reference deleted event types remain intact but display a warning.

Expected Behavior:

System should validate that selected events still exist in the master data when saving.

If an event is deleted, system should display an error or warning and prevent saving.

10.2.3. Service Type Master Data

Dependency Type: REQUIRED

Relationship: The service selection buttons in Package Step 2 pull data from the Service Type Master Data.

Impact:

Services displayed in the wizard (Photography, Videography, Content Creation) are defined in the Service Type Master Data.

If a service type is deleted, it will no longer appear in the wizard.

Expected Behavior:

System should validate that selected services still exist in the master data when saving.

10.3. Technical Dependencies

10.3.1. Database

Dependency Type: REQUIRED

Relationship: The wizard relies on database operations for saving draft data, validating uniqueness, and storing group/package configurations.

Impact:

If the database is unavailable, the wizard cannot save progress or validate data.

System must display an error toast: "Failed to save your progress. Please check your connection and try again."

Expected Behavior:

Implement retry logic for database connection failures.

Allow users to exit the wizard and resume later if connection issues persist.

10.3.2. Session Management

Dependency Type: REQUIRED

Relationship: The wizard maintains state across steps using session storage and in-memory state.

Impact:

If the user's session expires while in the wizard, system must detect the expired session.

System must prompt user to log in again and restore their wizard progress from the last auto-save point.

Expected Behavior:

Implement session validation before saving data at each step.

Redirect to login page if session is invalid, with a message: "Your session has expired. Please log in to resume."

11. REFERENCES

11.1. Figma Design References

https://www.figma.com/design/ej0kxwP45mDKmZCZfAJ5O8/Pixally?node-id=19582-148303&t=BAkQ9BaQzOENaQKr-0

Deprecated_PACKAGE BUILDER

SECTION 3: PACKAGE BUILDER (MAIN EDITOR)

1. MODULE OVERVIEW

1.1. Purpose

The Package Builder is the core configuration interface where users design and customize individual packages within a Package Group. This module serves as the comprehensive editor for all package-level details including naming, pricing, imagery, line items, deliverables, smart fields, tax settings, and A-La-Carte item linkage.

1.2. Business Goals

The Package Builder enables agencies to:

• Configure detailed package offerings with professional presentation (name, description, image)
• Define service deliverables with line items and due date rules
• Implement flexible tax structures (package-level or item-level taxation)
• Integrate Smart Fields for dynamic data mapping to proposals, contracts, and projects
• Link A-La-Carte items for client customization options
• Maintain version control through Draft/Publish workflow
• Ensure data integrity by preventing retroactive changes to active proposals

1.3. Functional Summary

The Package Builder provides a multi-panel workspace where users:

1. Select packages from the left sidebar (created in Section 2)
2. Configure package header fields (name, description, image, price, tax mode)
3. Add and manage line items (Standard or Smart Field types)
4. Configure deliverable settings and due date calculations
5. Manage item-level tax settings (when applicable)
6. Link A-La-Carte items for client add-on options
7. Publish packages to make them available for proposals

The builder operates in Draft mode by default, auto-saving all changes. Only published packages are available for use in the Proposal Builder. Changes to published packages do NOT retroactively update existing proposals or projects.

1.4. Module Boundaries

This module handles:

• Package-level configuration (name, description, image, price)
• Line item creation and management (Standard and Smart Field types)
• Deliverable toggle and due date rule configuration
• Tax mode selection and item-level tax settings
• A-La-Carte item linkage to packages
• Draft/Publish workflow and version management
• Package duplication within the builder
• Event and service structure editing (inherited from Section 2)

This module does NOT handle:

• Initial package group structure creation (handled in Section 2)
• Package group deletion (handled in Section 1)
• Proposal generation using packages (handled by Proposal Builder)
• Project creation from signed proposals (handled by Project Module)
• Post-production deliverable pipeline execution (handled by Post-Production Module)
• A-La-Carte item creation (handled in Sections 4 & 5)

2. USER ROLES & PERMISSIONS

Role

View Packages

Edit Package Details

Add/Edit/Delete Line Items

Change Tax Mode

Link A-La-Carte Items

Publish Package

Delete Package

Owner

✔

✔

✔

✔

✔

✔

✔

Admin

✔

✔

✔

✔

✔

✔

✔

Project Manager

✔

✔ (optional, agency setting)

✔ (optional, agency setting)

✖

✔ (optional)

✖

✖

Coordinator

✔

✔ (optional, agency setting)

✔ (optional, agency setting)

✖

✔ (optional)

✖

✖

Contractor

✖

✖

✖

✖

✖

✖

✖

Client

✖

✖

✖

✖

✖

✖

✖

Notes:

• PM and Coordinator permissions are configurable at the agency level
• Only Owner and Admin can publish packages (make available for proposals)
• Only Owner and Admin can change tax mode settings
• Contractors and Clients never access the Package Builder

3. USER FLOW (MINIMIZED)

3.1. Accessing Package Builder

Entry Points:

1. From Package List View → Click "Edit" on a package group
2. After completing Package Group Creation wizard (Section 2) → Auto-redirected
3. Direct URL: /packages/builder/{group_id}

Initial Load:

• Left sidebar displays all packages in the group (Package 1, Package 2, etc.)
• First package auto-selected and displayed in center canvas
• Right sidebar shows Package Settings panel

3.2. Package Selection

• Click any package in left sidebar to load it in center canvas
• Settings icon next to package name opens Package Settings panel
• Multiple packages can be edited in sequence without closing builder

3.3. Editing Package Header

1. Edit package name directly in header field
2. Add/edit description in rich text editor
3. Upload and crop package image (JPG/PNG, max 5MB)
4. Enter package price (required for publishing)
5. Select tax mode from dropdown (Entire Package Taxable, Non-Taxable, or Line Item Based)

3.4. Managing Line Items

Adding Line Items:

1. Click "+ Add Line Item" button
2. Enter line item name and description
3. Select type: Standard or Smart Field
4. If Smart Field: Select from predefined smart field dropdown
5. Toggle Deliverable ON/OFF
6. If Deliverable ON: Set due date rule (X days/weeks/months after event)
7. If tax mode is Line Item Based: Toggle taxable ON/OFF and enter tax amount
8. Enter line item price (required if taxable)
9. Click "Save"

Editing/Deleting Line Items:

• Click line item to open edit panel
• Modify fields and click "Update"
• Click delete icon to remove (soft delete, instant removal)

3.5. Linking A-La-Carte Items

1. Click "Assign A La Carte Items +" button
2. Modal opens showing available A-La-Carte items (grouped by Simple Add-ons and Event-Creation Add-ons)
3. Select items to link (multi-select)
4. Click "Assign"
5. Linked items appear in package preview and will show in proposals

3.6. Editing Events and Services

1. Click "Edit Events and Services" in Package Settings panel
2. Modal opens showing current events and services
3. Add/remove events or services
4. Click "Save"
5. Line items remain intact; only event/service structure updates

3.7. Publishing Package

1. Ensure all required fields are complete (name, description, image, price, at least one line item)
2. Click "Publish" button (top right)
3. System validates and publishes package
4. Package becomes available in Proposal Builder
5. Success toast displayed

3.8. Draft Auto-Save

• All changes auto-save to Draft immediately
• No manual save button required
• Draft packages not available for proposals until published

4. FUNCTIONAL LOGIC

4.1. Package Builder Initialization

4.1.1. Loading Package Builder

When the Package Builder loads (from Package List View edit action or after wizard completion):

1. System retrieves the package group ID from the URL (/packages/builder/{group_id})
2. System validates that:
   • Package group exists in the database
   • User has permission to access the group (based on brand and role)
   • Package group belongs to the user's agency
3. System fetches all packages within the group with their associated data:
   • Package names, descriptions, images, prices
   • Events and services (inherited from Section 2)
   • Line items (name, type, deliverable status, due date rules, tax settings, prices)
   • Linked A-La-Carte items
   • Tax mode setting
   • Draft/Published status
4. System displays the left sidebar with all packages listed
5. System auto-selects and displays the first package in the center canvas
6. System displays the Package Settings panel in the right sidebar

4.1.2. Package Selection from Sidebar

When user clicks a package in the left sidebar:

1. System saves any unsaved changes to the currently displayed package (auto-save)
2. System loads the selected package's data into the center canvas
3. System updates the Package Settings panel with the selected package's details
4. System highlights the selected package in the sidebar with an active state indicator

4.2. Package Header Configuration

4.2.1. Package Name Editing

When user edits the package name:

1. System displays the name field as editable (inline editing)
2. User types the new name (max 100 characters)
3. System validates in real-time:
   • Name cannot be empty
   • Name must be unique within the package group
4. System auto-saves the new name to Draft
5. If validation fails, inline error appears below the field
6. Name change does NOT affect existing proposals (proposals retain old name snapshot)

4.2.2. Package Description Editing

When user edits the package description:

1. System displays a rich text editor (similar to Lead Form Builder)
2. User can format text with:
   • Bold, italic, underline
   • Bullet lists, numbered lists
   • Headers (H1, H2, H3)
   • Links
3. System auto-saves description changes to Draft
4. Description appears in proposals when package is selected

4.2.3. Package Image Upload and Crop

When user uploads a package image:

1. User clicks "Add Image" or "Change Image" button
2. System opens file picker (accepts JPG, PNG only)
3. User selects an image file
4. System validates:
   • File format is JPG or PNG
   • File size is ≤ 5MB
5. If validation passes:
   • System opens crop tool with aspect ratio options (16:9, 4:3, 1:1)
   • User adjusts crop area and clicks "Crop & Save"
   • System uploads cropped image to file storage (AWS S3 or similar)
   • System saves image reference to package record
   • System displays thumbnail in Package Builder
6. If validation fails, error toast appears: "Image upload failed. File must be JPG or PNG and under 5MB."

4.2.4. Package Price Configuration

When user enters a package price:

1. User clicks on the price field (placeholder: "Specify the price")
2. System displays numeric input field with currency formatting ($)
3. User enters price value (e.g., 450.00)
4. System validates:
   • Price must be numeric
   • Price must be ≥ 0 (cannot be negative)
5. System auto-saves price to Draft
6. Price is required for publishing (validation at publish time)
7. Price becomes the base package price in proposals (modifiable in proposal if needed)

4.2.5. Tax Mode Selection

When user selects a tax mode:

1. User clicks on the Tax Mode dropdown in Package Settings panel
2. System displays three options:
   • Entire Package Taxable: Tax applied to the full package price
   • Entire Package Non-Taxable: No tax applied
   • Line Item Based Tax: Tax applied individually to selected line items
3. User selects one option
4. System immediately updates the line item interface:
   • If Entire Package Taxable/Non-Taxable: Line item taxable toggles are disabled (grayed out)
   • If Line Item Based Tax: Line item taxable toggles are enabled for each line item
5. System auto-saves tax mode to Draft

Tax Mode Impact:

• Entire Package Taxable: System calculates tax on the full package price when used in proposals. Line items cannot have individual tax settings.
• Entire Package Non-Taxable: No tax is calculated. Line items cannot have individual tax settings.
• Line Item Based Tax: Each line item has its own taxable toggle. If toggle is ON, user must enter a taxable amount. Tax is calculated only on the sum of taxable line items, NOT the package price.

4.3. Line Item Management

4.3.1. Adding a Line Item

When user clicks "+ Add Line Item":

1. System opens a line item creation modal/panel with the following fields:
   • Line Item Name (text, required)
   • Line Item Type (dropdown: Standard or Smart Field, required)
   • Description (text area, optional)
   • Deliverable (toggle, default OFF)
   • Deliverable Due Date Rule (shown only if Deliverable toggle ON)
   • Taxable (toggle, shown only if tax mode is Line Item Based)
   • Taxable Amount (numeric, required if Taxable toggle ON)
   • Price (numeric, required if Taxable toggle ON)
2. User fills in the fields
3. If Line Item Type = Smart Field:
   • System displays a dropdown of predefined smart fields:
     • Hours Coverage
     • Number of Edited Images
     • Second Shooter
     • Additional Hours
   • User selects one smart field
   • Smart field name auto-populates the Line Item Name field (user can override)
4. If Deliverable Toggle = ON:
   • System displays due date rule fields:
     • Due Date Value (numeric, e.g., 10)
     • Due Date Unit (dropdown: Days, Weeks, Months)
   • System displays a tooltip: "Deliverable due date is calculated as Event Date + X days/weeks/months"
   • Critical Clarification from MOM: Deliverable due dates stick to the individual event date where deliverable values are available (not always the primary event)
5. If Taxable Toggle = ON (Line Item Based Tax mode only):
   • System displays Taxable Amount field (required)
   • System displays Price field (required)
6. User clicks "Save"
7. System validates all required fields
8. If validation passes:
   • System saves line item to Draft
   • System adds line item to the package's line item list
   • Line item appears in the center canvas
9. If validation fails, inline errors appear

4.3.2. Editing a Line Item

When user clicks on an existing line item:

1. System opens the line item edit panel with all fields pre-filled
2. User modifies fields as needed
3. System validates changes
4. User clicks "Update"
5. System saves changes to Draft immediately
6. Updated line item reflects changes in the canvas

4.3.3. Deleting a Line Item

When user clicks the delete icon on a line item:

1. System displays a confirmation modal:
   • Title: "Delete Line Item?"
   • Message: "Are you sure you want to delete '[Line Item Name]'? This action cannot be undone."
   • Buttons: "Cancel" and "Delete" (red)
2. If user clicks "Delete":
   • System performs soft delete (marks as deleted)
   • System removes line item from the canvas immediately
   • System auto-saves changes to Draft
3. If user clicks "Cancel", no changes are made

4.3.4. Line Item Ordering

Line items can be reordered within the package:

1. User drags a line item to a new position (drag-and-drop)
2. System updates the display order immediately
3. System auto-saves the new order to Draft
4. Line item order is preserved in proposals and projects

4.4. Smart Fields Logic

4.4.1. Smart Field Definition

Smart Fields are hardcoded, predefined fields (per Ambiguity #3 clarification) that map dynamic data to:

• Proposal details
• Contract placeholders
• Project details after signing
• Automation workflows

Available Smart Fields:

1. Hours Coverage: Number of hours for the event (e.g., 8 hours)
2. Number of Edited Images: Total edited photos to be delivered (e.g., 200 images)
3. Second Shooter: Whether a second photographer/videographer is included (Yes/No or quantity)
4. Additional Hours: Extra hours beyond base coverage (e.g., +2 hours)

Important: Users CANNOT create new smart fields. Custom fields created by users are NOT smart fields (per clarification).

4.4.2. Smart Field Behavior in Proposals

When a package with smart fields is used in a proposal:

1. Proposal Builder displays smart field values as editable fields
2. Client or agency can modify smart field values during proposal customization
3. Smart field values are captured and stored with the proposal

4.4.3. Smart Field Mapping to Projects

When a proposal is signed and converted to a project:

1. System extracts smart field values from the proposal
2. System maps smart fields to project details:
   • Hours Coverage → Project schedule and contractor assignments
   • Number of Edited Images → Deliverable quantities in Post-Production
   • Second Shooter → Contractor assignment logic
   • Additional Hours → Adjusted project timeline
3. Smart field data is used for automation triggers (e.g., reminders, task creation)

4.5. Deliverable Logic

4.5.1. Deliverable Toggle Behavior

When user toggles Deliverable ON for a line item:

1. System displays additional fields:
   • Due Date Value (numeric, required)
   • Due Date Unit (dropdown: Days, Weeks, Months, required)
2. System displays a tooltip: "Deliverable items will be added to the Post-Production board after the event. Due date is calculated as Event Date + X days/weeks/months."
3. User enters due date rule (e.g., 10 Days)
4. System saves the rule with the line item

4.5.2. Due Date Calculation Logic (Multi-Event Packages)

From MOM Clarification: Deliverable due dates stick to the individual event date where deliverable values are available.

Logic:

1. Single-Event Package: Due date = Event Date + X days/weeks/months (straightforward)
2. Multi-Event Package:
   • Each line item can be tied to a specific event
   • If line item is event-specific (e.g., "Wedding Photography"), due date = Wedding Event Date + X days/weeks/months
   • If line item is shared across events, system uses the primary event date as the default
   • In the Package Builder, user can optionally specify which event a line item is tied to (future enhancement, not currently required)

Example:

• Package has Wedding (primary) and Rehearsal Dinner events
• Line Item: "10 edited wedding photos" → Deliverable toggle ON, Due Date = 10 Days
• System calculates: Wedding Date + 10 Days
• Line Item: "Rehearsal dinner highlight reel" → Due Date tied to Rehearsal Dinner Date + 7 Days

4.5.3. Deliverable Pipeline Integration

When a proposal is signed and converted to a project:

1. System identifies all line items with Deliverable toggle ON
2. System creates deliverable tasks in the Post-Production module:
   • Task Name = Line Item Name
   • Due Date = Calculated date (Event Date + rule)
   • Assigned to contractor based on service type
3. Post-Production board displays all deliverables with due dates
4. Project pipeline stage only advances when all deliverables are marked complete

4.6. A-La-Carte Item Linkage

4.6.1. Linking A-La-Carte Items to Package

When user clicks "Assign A La Carte Items +":

1. System opens a modal displaying available A-La-Carte items
2. Modal has two tabs:
   • Simple Add-ons: Items created in Section 4 (e.g., extra hours, drone footage, highlight reel)
   • Event-Creation Add-ons: Items created in Section 5 (e.g., engagement shoot, rehearsal dinner as add-on event)
3. System filters A-La-Carte items by:
   • Brand (only items from the same brand as the package group)
   • Event type and service type compatibility
4. User selects one or more items (checkboxes)
5. User clicks "Assign"
6. System links selected items to the package
7. System auto-saves changes to Draft
8. Linked items appear in the package's A-La-Carte section

4.6.2. Unlinking A-La-Carte Items

When user clicks the "X" icon next to a linked A-La-Carte item:

1. System removes the link between the item and the package
2. System auto-saves changes to Draft
3. Item no longer appears in the package's A-La-Carte section
4. Important: Unlinking does NOT delete the A-La-Carte item itself (item remains available for other packages)

4.6.3. A-La-Carte Behavior in Proposals

When a package with linked A-La-Carte items is used in a proposal:

1. Proposal Builder displays the package with all linked A-La-Carte items below it
2. Client can select/deselect A-La-Carte items as add-ons
3. If "Customer Can Select Quantity" toggle was ON for the item, client can choose quantity (1-10)
4. A-La-Carte item prices are added to the total proposal amount dynamically

4.7. Draft and Publish Workflow

4.7.1. Draft Mode Behavior

All package changes in the builder are auto-saved to Draft status by default.

Draft Rules:

• Draft packages are NOT available for use in proposals
• Draft packages appear with a "Draft" badge in the Package List View
• Users can edit draft packages without restrictions
• No versioning for drafts; all changes overwrite the previous draft state

4.7.2. Publishing a Package

When user clicks "Publish" button:

1. System validates that all required fields are complete:
   • Package Name (not empty, unique within group)
   • Package Description (recommended but not strictly required)
   • Package Image (required)
   • Package Price (required, ≥ 0)
   • At least one line item exists
2. If validation fails:
   • System displays an error toast: "Publish blocked — complete all mandatory fields."
   • System highlights missing fields with red borders
   • Publish action is blocked
3. If validation passes:
   • System changes package status from Draft to Published
   • System saves a snapshot of the package configuration
   • System makes the package available in the Proposal Builder
   • System displays success toast: "Package published successfully."
   • Publish button changes to "Republish" for future edits

4.7.3. Editing a Published Package

When user edits a published package:

1. System allows all edits (name, description, image, price, line items, tax mode, A-La-Carte links)
2. All changes are saved to Draft immediately
3. Package remains in Published status, but a "draft changes pending" indicator may appear
4. Critical Rule: Changes do NOT affect existing proposals or projects
   • Proposals created before the edit retain the old package snapshot (static data)
   • Projects created from old proposals also retain the old configuration
5. User must click "Republish" to finalize changes
6. After republishing:
   • New proposals use the updated package configuration
   • Old proposals remain unchanged

4.7.4. Versioning and Change Protection

From MOM: Published packages, versioning, and change logging ensure active proposals are protected.

Versioning Logic:

• System does NOT create multiple versions of a package (no version 1, version 2, etc.)
• Instead, system uses snapshot-based protection:
  • When a proposal is created, system saves a complete snapshot of the package at that moment
  • Snapshot includes all line items, prices, events, services, A-La-Carte links
  • Editing the package after proposal creation does NOT update the proposal's snapshot
• Activity Log: All edits to packages are logged in the system's activity/audit log (per MOM)
  • Log records: timestamp, user, field changed, old value, new value

4.8. Editing Events and Services (Group-Level)

4.8.1. Accessing Edit Events and Services Modal

When user clicks "Edit Events and Services" in Package Settings panel:

1. System opens a modal displaying the current package's events and services
2. Modal shows:
   • Event Type 1 (e.g., Wedding) with dropdown to change event type
   • Service Types for Event 1: Photography, Videography (with delete icons)
   • Event Type 2 (e.g., Rehearsal Dinner) with dropdown
   • Service Types for Event 2: Photography, Videography (with delete icons)
3. User can:
   • Change an event type using the dropdown
   • Add a new event type by clicking "+ Add New Event Type"
   • Delete an event by clicking the delete icon (if more than one event exists)
   • Add a new service to an event by clicking the "+" icon next to services
   • Delete a service from an event by clicking the delete icon (if more than one service exists)

4.8.2. Modifying Events and Services

When user makes changes in the modal:

1. User changes Event Type dropdown (e.g., from "Rehearsal Dinner" to "Engagement Shoot")
2. System updates the event type immediately
3. User clicks "Proceed to Builder" button
4. System validates:
   • At least one event exists
   • Each event has at least one service
5. If validation passes:
   • System saves changes to Draft
   • System updates the package canvas to reflect new events/services
   • Line items remain intact (not deleted when events/services change)
   • User can re-assign line items to new events if needed

4.9. Tax Mode Change Impact

4.9.1. Switching from Line Item Based to Entire Package Tax

When user switches tax mode from "Line Item Based Tax" to "Entire Package Taxable" or "Entire Package Non-Taxable":

1. System displays a confirmation modal:
   • Title: "Change Tax Mode?"
   • Message: "Switching to package-level tax will disable all line item taxable toggles and amounts. Continue?"
   • Buttons: "Cancel" and "Continue"
2. If user clicks "Continue":
   • System disables all line item taxable toggles (grayed out)
   • System clears all line item tax amounts
   • System applies tax to the full package price (if "Entire Package Taxable" selected)
   • System auto-saves changes to Draft
3. If user clicks "Cancel", no changes are made

4.9.2. Switching from Entire Package Tax to Line Item Based

When user switches tax mode from "Entire Package Taxable/Non-Taxable" to "Line Item Based Tax":

1. System displays a confirmation modal:
   • Title: "Change Tax Mode?"
   • Message: "Switching to line item based tax will allow you to set tax individually for each line item. Package-level tax will no longer apply. Continue?"
   • Buttons: "Cancel" and "Continue"
2. If user clicks "Continue":
   • System enables line item taxable toggles for all line items
   • System allows user to set tax amounts for each line item
   • System auto-saves changes to Draft
3. If user clicks "Cancel", no changes are made

4.10. Package Duplication Within Builder

4.10.1. Duplicating a Package (Within Same Group)

When user clicks "Duplicate" in the Package Settings panel:

1. System creates a full copy of the current package including:
   • Package Name (appended with "Copy of")
   • Package Description
   • Package Image (reference copied)
   • Package Price
   • Tax Mode
   • All line items (names, types, deliverable settings, tax settings, prices)
   • All A-La-Carte links
   • Events and services
2. System adds the duplicated package to the package group
3. System increments the group's package count (e.g., from 3 to 4)
4. System saves duplicated package as Draft
5. System displays the duplicated package in the left sidebar
6. System automatically selects the duplicated package for editing
7. System displays success toast: "Package duplicated successfully."

5. FIELD DETAILS & VALIDATIONS

Field Name

Type

Data Type

Required

Max Length

Validation Rules

Error Messages

Package Name

Text Input

String

Yes

100 chars

Cannot be empty; must be unique within group; auto-trim whitespace

"Package name is required." / "Package name already exists within this group."

Package Description

Rich Text Editor

HTML/Text

No

5000 chars

Optional; supports formatting (bold, italic, lists, headers)

None

Package Image

File Upload

Image (JPG, PNG)

Yes (for publish)

5 MB

Must be JPG or PNG; max file size 5MB; crop required before save

"Image upload failed. File must be JPG or PNG and under 5MB."

Package Price

Numeric Input

Decimal

Yes (for publish)

N/A

Must be numeric; must be ≥ 0; cannot be negative

"Package price is required." / "Price must be a positive number."

Tax Mode

Dropdown

Enum

Yes

N/A

Must select one: Entire Package Taxable, Entire Package Non-Taxable, Line Item Based Tax

"Tax mode is required."

Line Item Name

Text Input

String

Yes

100 chars

Cannot be empty; no uniqueness requirement

"Line item name is required."

Line Item Type

Dropdown

Enum

Yes

N/A

Must select: Standard or Smart Field

"Line item type is required."

Smart Field Type

Dropdown

Enum

Yes (if type = Smart Field)

N/A

Must select from predefined list: Hours Coverage, Number of Edited Images, Second Shooter, Additional Hours

"Smart field type is required."

Line Item Description

Text Area

String

No

500 chars

Optional

None

Deliverable Toggle

Toggle Switch

Boolean

No

N/A

Default OFF; optional

None

Deliverable Due Date Value

Numeric Input

Integer

Yes (if Deliverable ON)

N/A

Must be numeric; must be > 0

"Deliverable due date value is required."

Deliverable Due Date Unit

Dropdown

Enum

Yes (if Deliverable ON)

N/A

Must select: Days, Weeks, or Months

"Deliverable due date unit is required."

Line Item Taxable Toggle

Toggle Switch

Boolean

No

N/A

Only enabled if tax mode = Line Item Based; default OFF

None

Line Item Taxable Amount

Numeric Input

Decimal

Yes (if Taxable ON)

N/A

Must be numeric; must be ≥ 0

"Taxable amount is required."

Line Item Price

Numeric Input

Decimal

Yes (if Taxable ON)

N/A

Must be numeric; must be ≥ 0

"Line item price is required."

Event Type

Dropdown

Reference (Event Master)

Yes

N/A

Must reference valid event from Event Master Data

"Event type is required."

Service Type

Dropdown

Reference (Service Master)

Yes

N/A

Must reference valid service from Service Type Master Data

"Service type is required."

A-La-Carte Item Selection

Multi-Select Checkboxes

Array of IDs

No

N/A

Must belong to same brand as package; no uniqueness requirement

None

6. SUCCESS MESSAGE HANDLING

Trigger Condition

Success Message

Display Type

Duration

Post-Success Action

Package Published

"Package published successfully."

Toast (top-right, green checkmark)

5 seconds

Package becomes available in Proposal Builder; Publish button changes to "Republish"

Package Republished

"Package republished successfully. Future proposals will use the updated version."

Toast (top-right, green checkmark)

5 seconds

Updated package available for new proposals; old proposals unchanged

Line Item Added

Visual feedback only (no toast)

Line item appears in canvas instantly

N/A

Line item saved to Draft; user can continue editing

Line Item Updated

Visual feedback only (no toast)

Updated line item reflects changes in canvas

N/A

Changes saved to Draft; user can continue editing

Line Item Deleted

"Line item deleted successfully."

Toast (top-right, green checkmark)

5 seconds

Line item removed from canvas; changes saved to Draft

A-La-Carte Items Linked

"A-La-Carte items assigned successfully."

Toast (top-right, green checkmark)

5 seconds

Items appear in package A-La-Carte section; saved to Draft

A-La-Carte Item Unlinked

Visual feedback only (no toast)

Item removed from A-La-Carte section instantly

N/A

Link removed; changes saved to Draft

Package Duplicated

"Package duplicated successfully."

Toast (top-right, green checkmark)

5 seconds

Duplicated package appears in left sidebar; auto-selected for editing

Events and Services Updated

"Events and services updated successfully."

Toast (top-right, green checkmark)

5 seconds

Package canvas refreshes with new event/service structure

Tax Mode Changed

Visual feedback only (no toast)

Tax mode updates immediately; line item interface adjusts

N/A

Tax mode saved to Draft; user can continue editing

Auto-Save Complete

Visual feedback only (optional: small "Saved" indicator)

Brief "Saving..." indicator in top right

1-2 seconds

All changes persisted to Draft; no user action required

7. ERROR MESSAGE HANDLING

Trigger Condition

Error Message

Display Type

User Action Required

Package Name Empty

"Package name is required."

Inline (below field, red text)

Enter a valid package name

Package Name Duplicate

"Package name already exists within this group."

Inline (below field, red text)

Enter a unique package name

Package Price Invalid

"Package price is required." / "Price must be a positive number."

Inline (below field, red text)

Enter a valid price ≥ 0

Publish Blocked - Missing Fields

"Publish blocked — complete all mandatory fields."

Toast (top-right, red error icon) + highlighted fields

Complete all required fields (name, image, price, at least one line item)

Image Upload Failed

"Image upload failed. File must be JPG or PNG and under 5MB."

Toast (top-right, red error icon)

Upload a valid image file

Line Item Name Empty

"Line item name is required."

Inline (below field, red text)

Enter a line item name

Smart Field Type Not Selected

"Smart field type is required."

Inline (below dropdown, red text)

Select a smart field type from the dropdown

Deliverable Due Date Missing

"Deliverable due date value is required." / "Deliverable due date unit is required."

Inline (below field, red text)

Enter a due date value and select a unit (Days/Weeks/Months)

Taxable Amount Missing

"Taxable amount is required."

Inline (below field, red text)

Enter a taxable amount for the line item

Line Item Price Missing

"Line item price is required."

Inline (below field, red text)

Enter a price for the line item

Event Type Not Selected

"Event type is required."

Inline (below dropdown, red text)

Select an event type from the dropdown

Service Type Not Selected

"Service type is required."

Inline (below dropdown, red text)

Select a service type from the dropdown

Failed to Save Draft

"Failed to save your changes. Please check your connection and try again."

Toast (top-right, red error icon)

Check internet connection; retry the action

Failed to Publish

"Failed to publish package. Please try again."

Toast (top-right, red error icon)

Retry publishing; if error persists, contact support

Failed to Load Package

"Failed to load package. Please try again."

Toast (top-right, red error icon)

Refresh the page or navigate back to Package List View

Tax Mode Change Blocked

Confirmation modal appears (not an error)

Modal dialog

User must confirm or cancel the tax mode change

Delete Line Item Used in Event-Creation ALC

"Cannot delete line item. It is referenced by an event-creation A-La-Carte item."

Toast (top-right, red error icon)

Unlink the ALC item first, then delete the line item

8. EDGE CASES

Edge Case

Description

Expected System Behavior

Switch Tax Mode After Setting Line Item Taxes

User sets tax amounts for multiple line items (tax mode = Line Item Based), then switches to "Entire Package Taxable"

System displays confirmation modal; if user confirms, all line item tax toggles disabled and amounts cleared; package-level tax applied

Delete Event Referenced by Line Items

User deletes an event that has line items tied to it

System allows deletion; line items remain in package but lose event association; user can reassign line items to other events

Upload Very Large Image (>5MB)

User attempts to upload an image larger than 5MB

System rejects upload; error toast: "Image upload failed. File must be JPG or PNG and under 5MB."; user must compress or choose different image

Publish Without Line Items

User attempts to publish a package with zero line items

System blocks publish; error toast: "Publish blocked — at least one line item is required."; user must add at least one line item

Duplicate Package in Group with 6 Packages

User attempts to duplicate a package when group already has 6 packages (maximum)

System blocks duplication; error toast: "Cannot duplicate package. Group already has the maximum number of packages (6)."

Edit Published Package Used in Multiple Proposals

User edits a package that is used in 10+ active proposals

System allows edits; all changes saved to Draft; old proposals remain unaffected with static snapshots; user must republish for future proposals

Change Primary Event After Line Items Created

User changes the primary event (e.g., from Wedding to Rehearsal Dinner) after deliverables are configured

System allows change; deliverable due dates tied to primary event are recalculated using new primary event date; deliverables tied to specific events remain unchanged

Unlink A-La-Carte Item Used in Active Proposals

User unlinks an A-La-Carte item from a package that is used in active proposals

System allows unlinking; item removed from package; old proposals retain static snapshot with item still linked; future proposals do not show the item

User Loses Internet Connection While Editing

User's internet connection drops while editing package

System detects connection loss; displays warning toast: "No internet connection. Changes will be saved when connection is restored."; changes buffered in browser; auto-save resumes when connection restored

User Closes Browser Without Publishing

User edits a package but closes browser/tab without clicking Publish

All changes saved to Draft (auto-save); package remains in Draft status; user can resume editing later; changes not lost

Deliverable Toggle ON Without Due Date

User toggles Deliverable ON but does not enter due date value/unit, then tries to save

System blocks save; inline error: "Deliverable due date value is required."; user must enter due date before saving

Smart Field Selected But No Value Entered

User selects a smart field type but does not enter a value (e.g., "Hours Coverage" but no number)

System allows save (value can be entered later in Proposal Builder or Project); smart field appears in package but with placeholder or empty value

Brand Deleted After Package Created

Package's assigned brand is deleted or archived by admin

Package remains accessible; brand displays as "Archived Brand"; package becomes read-only or editable only by Owner/Admin; user can duplicate package to reassign to active brand

9. ACCEPTANCE CRITERIA

9.1. Package Builder Loading

AC1.1: Package Builder Loads Successfully

Given a user with Owner or Admin role clicks "Edit" on a package group from the Package List View,
When the Package Builder loads,
Then the system must display all packages in the left sidebar, auto-select the first package, and display its details in the center canvas with the Package Settings panel on the right.

AC1.2: Multiple Packages Displayed in Sidebar

Given a package group contains 3 packages,
When the Package Builder loads,
Then the system must display all 3 packages in the left sidebar (PACKAGE 1, PACKAGE 2, PACKAGE 3) with settings icons.

9.2. Package Header Configuration

AC2.1: Package Name Uniqueness Validation

Given a user enters a package name that already exists within the same group,
When the user clicks outside the name field,
Then the system must display an inline error: "Package name already exists within this group."

AC2.2: Package Image Upload and Crop

Given a user uploads an image file (JPG or PNG, under 5MB),
When the upload completes,
Then the system must open the crop tool, allow the user to crop the image, and save the cropped image as the package thumbnail.

AC2.3: Package Price Validation

Given a user enters a negative price (e.g., -100),
When the user clicks outside the price field,
Then the system must display an inline error: "Price must be a positive number."

9.3. Tax Mode Behavior

AC3.1: Entire Package Taxable - Line Item Toggles Disabled

Given a user selects "Entire Package Taxable" as the tax mode,
When the user views line items,
Then the system must disable all line item taxable toggles and display them as grayed out.

AC3.2: Line Item Based Tax - Toggles Enabled

Given a user selects "Line Item Based Tax" as the tax mode,
When the user views line items,
Then the system must enable all line item taxable toggles and allow the user to set tax amounts individually.

AC3.3: Tax Mode Change Confirmation

Given a user switches tax mode from "Line Item Based Tax" to "Entire Package Taxable",
When the user makes the switch,
Then the system must display a confirmation modal warning that line item tax settings will be cleared, and allow the user to cancel or continue.

9.4. Line Item Management

AC4.1: Add Line Item Successfully

Given a user fills in all required fields for a new line item and clicks "Save",
When the system validates the data,
Then the system must save the line item to Draft and display it in the package canvas.

AC4.2: Edit Line Item Successfully

Given a user modifies an existing line item and clicks "Update",
When the system validates the changes,
Then the system must save the updated line item to Draft and reflect the changes in the canvas.

AC4.3: Delete Line Item Successfully

Given a user clicks the delete icon on a line item and confirms deletion,
When the confirmation is accepted,
Then the system must remove the line item from the canvas immediately and auto-save changes to Draft.

AC4.4: Smart Field Selection

Given a user selects "Smart Field" as the line item type and chooses "Hours Coverage" from the dropdown,
When the selection is made,
Then the system must auto-populate the line item name with "Hours Coverage" and allow the user to save the line item.

9.5. Deliverable Configuration

AC5.1: Deliverable Toggle ON - Due Date Required

Given a user toggles Deliverable ON for a line item but does not enter a due date value or unit,
When the user attempts to save,
Then the system must display inline errors: "Deliverable due date value is required." and "Deliverable due date unit is required."

AC5.2: Deliverable Due Date Calculation

Given a package has a single event (Wedding) scheduled for June 1, 2025, and a line item with Deliverable toggle ON and due date "10 Days",
When the proposal is signed and converted to a project,
Then the system must calculate the deliverable due date as June 11, 2025 (Wedding Date + 10 Days).

9.6. A-La-Carte Item Linkage

AC6.1: Link A-La-Carte Items Successfully

Given a user clicks "Assign A La Carte Items +" and selects 2 items from the modal,
When the user clicks "Assign",
Then the system must link both items to the package, display them in the A-La-Carte section, and auto-save to Draft.

AC6.2: Unlink A-La-Carte Item Successfully

Given a user clicks the "X" icon next to a linked A-La-Carte item,
When the unlink action is triggered,
Then the system must remove the link, remove the item from the A-La-Carte section, and auto-save to Draft.

9.7. Draft and Publish Workflow

AC7.1: Publish Blocked - Missing Required Fields

Given a user attempts to publish a package with no image or price set,
When the user clicks "Publish",
Then the system must block the publish action and display an error toast: "Publish blocked — complete all mandatory fields."

AC7.2: Publish Successfully

Given a user completes all required fields (name, image, price, at least one line item) and clicks "Publish",
When the system validates the data,
Then the system must change the package status to Published, display a success toast: "Package published successfully.", and make the package available in the Proposal Builder.

AC7.3: Edit Published Package - Proposals Unaffected

Given a user edits a published package that is used in 5 active proposals,
When the user makes changes and republishes,
Then the system must update the package for future proposals, but the 5 active proposals must retain their original package snapshots (no changes).

9.8. Events and Services Editing

AC8.1: Edit Events and Services Successfully

Given a user opens the "Edit Events and Services" modal and changes an event from "Rehearsal Dinner" to "Engagement Shoot",
When the user clicks "Proceed to Builder",
Then the system must update the package canvas with the new event, retain all existing line items, and auto-save to Draft.

AC8.2: Add New Event Successfully

Given a user clicks "+ Add New Event Type" in the modal and selects "Elopement",
When the user clicks "Proceed to Builder",
Then the system must add "Elopement" as a new event to the package and display it in the canvas.

10. DEPENDENCIES

Dependency

Type

Relationship

Impact

Expected Behavior

Package Group Creation Flow (Section 2)

Internal (REQUIRED)

Package Builder loads groups created in Section 2

Provides initial package structure (events, services, package count)

If Section 2 is unavailable or group incomplete, Package Builder cannot load properly

Package List View (Section 1)

Internal (REQUIRED)

Entry point via "Edit" action

Provides navigation to Package Builder

If Section 1 is unavailable, users cannot access Package Builder

A-La-Carte Add-On Items (Section 4)

Internal (INDIRECT)

Package Builder links Simple Add-ons from Section 4

Provides A-La-Carte items for client customization

If Section 4 items deleted, package no longer shows them; old proposals unaffected

A-La-Carte Event-Creation Add-On (Section 5)

Internal (INDIRECT)

Package Builder links Event-Creation Add-ons from Section 5

Provides event-creation items for project expansion

Same as Section 4

Proposal Builder

Internal (INDIRECT)

Published packages used in Proposal Builder

Determines which packages clients can select

Only published packages appear; draft packages invisible

Project Module

Internal (INDIRECT)

Signed proposals convert to projects using package data

Package line items → project deliverables; smart fields → project details

Once project created, editing package does NOT update project

Post-Production Module

Internal (INDIRECT)

Deliverable line items sent to Post-Production board

Deliverables with due dates become tasks

Post-Production depends on deliverable configuration in Package Builder

Brand Master Data

External (REQUIRED)

Package groups assigned to brands

Determines visibility and access control

If brand deleted, package displays "Archived Brand"

Event Type Master Data

External (REQUIRED)

Events selected from master data

Defines available event types

If event deleted, package retains reference but displays warning

Service Type Master Data

External (REQUIRED)

Services selected from master data

Defines available service types

Same as Event Type Master Data

Lead Form Builder (Theme/Text Style)

Internal (INDIRECT)

Package description uses rich text editor similar to Lead Form Builder

Provides consistent text formatting experience

If Lead Form Builder unavailable, Package Builder uses generic rich text editor

File Storage (AWS S3 or similar)

External (REQUIRED)

Package images uploaded to file storage

Stores and serves package images

If file storage unavailable, image uploads fail; existing images may not load

Database

Technical (REQUIRED)

All package data stored in database

Stores packages, line items, settings, draft/published status

If database unavailable, Package Builder cannot load or save data

Session Management

Technical (REQUIRED)

Maintains user session during editing

Validates user authentication and permissions

If session expires, user redirected to login; draft auto-saved

11. REFERENCES

11.1. Figma Design References

https://www.figma.com/design/ej0kxwP45mDKmZCZfAJ5O8/Pixally?node-id=19313-55353&t=BAkQ9BaQzOENaQKr-0

Deprecated_A-LA-CARTE ADD-ON ITEMS

SECTION 4: A-LA-CARTE ADD-ON ITEMS (SIMPLE ADD-ON)

1. MODULE OVERVIEW

1.1. Purpose

The A-La-Carte Add-On Items module manages simple, optional add-on services that can be attached to any package. These add-ons provide clients with customization options during the proposal process, such as additional hours, drone footage, highlight reels, extra edited images, physical deliverables, and other service enhancements.

1.2. Business Goals

The A-La-Carte Add-On module enables agencies to:

• Create reusable add-on items that can be linked to multiple packages
• Offer client flexibility through optional service upgrades
• Implement quantity-selectable add-ons for scalable pricing
• Filter add-on visibility by event type and service type
• Maintain brand-specific add-on libraries
• Increase proposal value through strategic upsell opportunities

1.3. Functional Summary

Simple Add-Ons are standalone items that enhance base packages with optional services. Key characteristics:

• Type: Simple Add-On (does NOT create new events, unlike Event-Creation Add-Ons in Section 5)
• Linkage: Can be linked to multiple packages in the Package Builder (Section 3)
• Visibility: Appear in proposals when linked to the selected package
• Quantity: Optional "Customer Can Choose Quantity" toggle (1-10 range)
• Pricing: Fixed price set during creation (can be overridden in proposals)
• Scope: Tied to event types and service types for targeted availability

1.4. Module Boundaries

This module handles:

• Add-on listing view with search, filter, sort, pagination
• Add-on creation (3-step wizard: General Details → Event & Service Types → Confirmation)
• Add-on editing (same 3-step flow)
• Add-on duplication with rename
• Add-on deletion (always allowed; proposals keep static snapshots)
• Quantity toggle configuration
• Event type and service type mapping for visibility rules
• Brand assignment for multi-brand filtering

This module does NOT handle:

• Event-Creation Add-Ons (handled in Section 5)
• Linking add-ons to packages (handled in Package Builder, Section 3)
• Proposal generation logic (handled by Proposal Builder)
• Project creation from add-ons (handled by Project Module)
• Add-on fulfillment or deliverables pipeline (handled by Post-Production)

2. USER ROLES & PERMISSIONS

Role

View Add-Ons

Create Add-On

Edit Add-On

Duplicate Add-On

Delete Add-On

Owner

✔

✔

✔

✔

✔

Admin

✔

✔

✔

✔

✔

Project Manager

✔

✔ (optional, agency setting)

✔ (optional)

✔ (optional)

✖

Coordinator

✔

✔ (optional, agency setting)

✔ (optional)

✔ (optional)

✖

Contractor

✖

✖

✖

✖

✖

Client

✖

✖

✖

✖

✖

Notes:

• PM and Coordinator permissions configurable at agency level
• Only Owner and Admin can delete add-ons
• Contractors and Clients never access A-La-Carte management interfaces

3. USER FLOW (MINIMIZED)

3.1. Accessing A-La-Carte List View

Entry Points:

• Navigate to Packages → A La Carte Items tab
• Direct URL: /packages/alacarte

Initial Load:

• Displays table with columns: Name, Type, Service, Event, Brand, Created, Actions
• Default sort: Created Date - Newest First
• Pagination: 25 items per page

3.2. Creating Add-On Item

3-Step Wizard:

Step 1: General Details

1. Select Add-on tab (not Event tab)
2. Enter Item Name, Description (optional), Price
3. Select Brand (required, locked after creation)
4. Toggle "Customer can choose quantity" (ON = client selects 1-10, OFF = fixed quantity 1)
5. Click "Next"

Step 2: Event & Service Types

1. Select one or more Event Types (Wedding, Rehearsal Dinner, etc.)
2. Select one or more Service Types (Photography, Videography, Content Creation)
3. Tooltip explains visibility rules: Add-on appears in proposals only when package includes selected event+service combinations
4. Click "Create New Item"

Step 3: Confirmation (implicit)

• System saves add-on as Draft
• Success toast displayed
• User returned to list view

3.3. Editing Add-On Item

1. Click "Edit" from Actions menu
2. Same 3-step wizard loads with pre-filled data
3. Make changes
4. Click "Update Item"
5. Changes saved to Draft
6. Important: Changes do NOT affect existing proposals (static snapshots retained)

3.4. Duplicating Add-On Item

1. Click "Duplicate" from Actions menu
2. Rename modal appears with "Copy of [Item Name]" pre-filled
3. Enter unique name
4. Click "Create Duplicate"
5. Full copy created (same brand, events, services, price, quantity toggle)
6. New item saved as Draft

3.5. Deleting Add-On Item

1. Click "Delete" from Actions menu
2. Confirmation modal appears
3. Click "Delete"
4. Item permanently deleted
5. Critical: Simple Add-Ons can ALWAYS be deleted (no usage blocking)
6. Old proposals retain static snapshot; new proposals no longer show item

3.6. Linking to Packages (in Package Builder)

1. Open Package Builder (Section 3)
2. Click "Assign A La Carte Items +"
3. Modal shows available add-ons (filtered by brand, event, service)
4. Select add-on(s)
5. Click "Assign"
6. Add-ons linked to package; appear in proposals

4. FUNCTIONAL LOGIC

4.1. A-La-Carte List View Initialization

4.1.1. Loading the A-La-Carte List View

When a user navigates to the A-La-Carte Items tab within the Packages module:

1. The system validates that the user has appropriate permissions (Owner, Admin, or optionally Project Manager/Coordinator based on agency settings).
2. The system identifies the user's agency ID and determines which brands the user has access to.
3. The system retrieves all A-La-Carte add-on items from the database where:
   • The agency_id matches the current user's agency.
   • The brand_id is in the list of accessible brands for the user.
   • The type field is set to "simple_addon" (filters out event-creation add-ons, which are covered in Section 5).
4. For each add-on, the system loads: item name, type badge, associated service types (joined from service_types_master), associated event types (joined from event_types_master), brand name (joined from brands table), and creation date.
5. The system applies the default sort order (Created Date - Newest First) to the retrieved add-ons.
6. The system loads the first 25 add-ons for display and calculates the total page count for pagination.
7. The system renders a table with columns: Name, Type, Service, Event, Brand, Created, and Actions.

4.1.2. Type Badge Display

In the Type column, the system displays an "Add-on" badge (distinct from "Event" badge for event-creation add-ons) to help users quickly identify simple add-ons versus event-creation add-ons in the combined list view.

4.2. Search and Filter Logic

4.2.1. Search Functionality

When a user enters text in the search input field:

1. The system captures the search query as the user types.
2. The system performs a case-insensitive search by converting both the search query and database values to lowercase.
3. The system searches across two fields: item name and item description.
4. For item names, the system checks if the name contains the search query as a substring (partial match allowed).
5. For descriptions, the system checks if the description (if not null) contains the search query.
6. The system returns an add-on if either the name matches OR the description matches.
7. The system updates the displayed list in real-time to show only matching results.
8. If no matches are found, the system displays an empty state message: "No A-La-Carte items found."

4.2.2. Filter Application Logic

The system implements cumulative AND logic for filters:

1. Brand Filter: When selected, the system filters to show only add-ons where the brand_id matches the selected brand.
2. Event Type Filter: When selected, the system filters to show only add-ons where the event_types array contains the selected event type ID.
3. Service Type Filter: When selected, the system filters to show only add-ons where the service_types array contains the selected service type ID.
4. Combined Filters: When multiple filter types are active, the system applies AND logic across filter types. An add-on must satisfy all filter criteria to appear in results.
5. The system displays a filter count badge on the filter icon showing the number of active filters.

4.2.3. Sorting Logic

The system supports three sort options:

1. Created Date (Default): Sorts add-ons by creation timestamp in descending order (newest first).
2. Name A-Z: Sorts add-ons alphabetically by name in ascending order (A to Z).
3. Price Low-High: Sorts add-ons by price in ascending order (lowest price first).

When a user selects a sort option, the system reorders the entire dataset and resets pagination to page 1.

4.3. Create Add-On Wizard

4.3.1. Wizard Initialization

When a user clicks the "Create New A-La-Carte Item" button and selects the Add-on tab (not the Event tab):

1. The system opens a 3-step wizard modal or page.
2. The system displays two tabs at the top: "Add-on" (active, orange indicator) and "Event" (inactive, gray).
3. The system loads Step 1: General Details form in the center.

4.3.2. Step 1 - General Details Validation

Item Name Validation: When a user enters an item name:

1. The system captures the entered text value.
2. When the user clicks "Next" or focus leaves the field, the system performs validation:
   • The system trims leading and trailing whitespace from the entered name.
   • The system checks if the trimmed name is empty.
   • If empty, the system displays an inline error below the field: "Item name is required."
3. If the name is not empty, the system performs a uniqueness check:
   • The system queries the database for existing A-La-Carte items within the selected brand.
   • The system performs a case-insensitive comparison.
   • If a match is found, the system displays an inline error: "Item name already exists."
4. If validation passes, the system proceeds without error.

Description Validation: The description field is optional. The system allows a maximum of 500 characters. No uniqueness check is required.

Price Validation: When a user enters a price:

1. The system validates that the entered value is numeric.
2. The system validates that the price is greater than or equal to 0 (cannot be negative).
3. If validation fails, the system displays an inline error: "Price must be a positive number."
4. If the price is 0, the system allows it (valid for free add-ons).

Brand Selection: The system displays a dropdown populated with all brands accessible to the current user. When a user selects a brand, the system validates that the brand ID exists. The brand selection is required before proceeding.

Customer Can Choose Quantity Toggle: The toggle is optional and defaults to OFF (false). When the toggle is ON, clients will be able to select a quantity between 1 and 10 in proposals. When OFF, the quantity is fixed at 1.

4.3.3. Proceeding from Step 1 to Step 2

When a user clicks "Next":

1. The system performs validation on all required fields (name, price, brand).
2. If any validation fails, the system displays inline errors and prevents navigation.
3. If all validations pass, the system temporarily stores the entered data in memory and navigates to Step 2.

4.3.4. Step 2 - Event & Service Types Configuration

Event Type Selection: When Step 2 loads:

1. The system displays a multi-select interface showing all event types from the event_types_master table.
2. Event types are displayed as buttons in a responsive grid layout.
3. When a user clicks an event type button:
   • If unselected, the system selects it and changes its appearance (orange background, checkmark).
   • If already selected, the system deselects it and returns to default appearance.
4. The system stores selected event type IDs in an array.
5. The system validates that at least one event type is selected before allowing progression.
6. An informational tooltip explains: "Select the event type(s) where this add-on should be available. The add-on will only appear for packages that include these event types."

Service Type Selection: Below the event type selection:

1. The system displays a multi-select interface showing all service types from the service_types_master table (typically: Photography, Videography, Content Creation).
2. Service types are displayed as buttons.
3. Users select service types using the same click interaction as events.
4. The system stores selected service type IDs in an array.
5. The system validates that at least one service type is selected before allowing progression.

4.3.5. Visibility Rules Logic

The system uses the selected event types and service types to determine visibility in proposals:

1. When a client views a proposal and selects a package, the system retrieves all add-ons linked to that package.
2. For each add-on, the system checks:
   • Does the add-on's event_types array contain at least one event type that matches an event in the package?
   • Does the add-on's service_types array contain at least one service type that matches a service in the package?
3. If BOTH conditions are true, the add-on is displayed in the proposal.
4. If either condition is false, the add-on is hidden.

Example:

• Add-on has Event Types: [Wedding, Rehearsal Dinner] and Service Types: [Photography]
• Package has Events: [Wedding] and Services: [Photography, Videography]
• Match found: Wedding event matches AND Photography service matches → Add-on is displayed.

4.3.6. Creating the Add-On

When a user clicks "Create New Item":

1. The system performs final validation on all fields from Step 1 and Step 2.
2. If validation passes, the system creates a new add-on record in the database with the following data:
   • Unique ID (generated UUID)
   • Name (user-provided, trimmed)
   • Description (user-provided, trimmed, or null if empty)
   • Price (user-provided)
   • Brand ID (user-selected)
   • Type: "simple_addon" (hardcoded for this section)
   • customer_quantity_toggle (boolean, user-selected)
   • event_types (array of event type IDs, user-selected)
   • service_types (array of service type IDs, user-selected)
   • Status: "draft"
   • Created timestamp: current date and time
   • Created by: current user's ID
   • Agency ID: current user's agency ID
3. The system saves the record to the database.
4. The system closes the wizard.
5. The system displays a success toast: "A-La-Carte item created successfully."
6. The system returns the user to the A-La-Carte list view where the new item appears at the top (newest first sort).

4.4. Edit Add-On Logic

4.4.1. Edit Initiation

When a user clicks the "Edit" option from the Actions menu:

1. The system validates that the user has appropriate permissions.
2. The system captures the add-on ID from the selected row.
3. The system retrieves the full add-on record from the database.
4. The system opens the same 3-step wizard used for creation.
5. The system pre-fills all form fields with the add-on's current data:
   • Step 1: Name, description, price, brand (read-only), quantity toggle
   • Step 2: Event types (pre-selected), service types (pre-selected)

4.4.2. Brand Field Lock

In edit mode, the Brand dropdown is read-only (disabled/grayed out). Users cannot change the brand assignment after creation. To reassign an add-on to a different brand, users must duplicate the add-on and then edit the duplicate.

4.4.3. Updating the Add-On

When a user clicks "Update Item":

1. The system performs the same validations as creation.
2. If validation passes, the system updates the add-on record in the database with the new values:
   • Name (if changed)
   • Description (if changed)
   • Price (if changed)
   • event_types array (if changed)
   • service_types array (if changed)
   • customer_quantity_toggle (if changed)
   • Updated timestamp: current date and time
3. The system saves the updated record.
4. The system displays a success toast: "A-La-Carte item updated successfully."
5. The system returns the user to the list view where the updated item reflects the changes.

4.4.4. Edit Impact Rules

Critical Rule: Editing Does Not Affect Existing Proposals

1. When an add-on is edited, the system updates the live add-on record in the alacarte_items table.
2. Proposals that were created before the edit contain a static snapshot of the add-on as it existed at the time of proposal creation.
3. These proposal snapshots are stored in a separate proposal_snapshots table and are never modified when the source add-on is edited.
4. Existing proposals (draft, sent, or signed) continue to display the original add-on configuration (name, price, etc.).
5. New proposals created after the edit will fetch the current live data from the alacarte_items table and will reflect the updated configuration.
6. Projects created from old proposals also retain the original add-on configuration and are not affected by edits.

4.5. Duplicate Add-On Logic

4.5.1. Duplicate Initiation

When a user clicks the "Duplicate" option from the Actions menu:

1. The system validates that the user has appropriate permissions.
2. The system captures the add-on ID from the selected row.
3. The system retrieves the full add-on record from the database.
4. The system opens a rename modal with a text input field pre-filled with "Copy of [Original Item Name]".

4.5.2. Name Validation for Duplicate

In the rename modal:

1. The user can edit the suggested name to any desired value (max 100 characters).
2. When the user clicks "Create Duplicate", the system trims whitespace from the entered name.
3. The system performs a uniqueness check within the same brand.
4. The system performs a case-insensitive comparison.
5. If a duplicate name exists, the system displays an inline error: "Item name already exists."
6. If the name is unique, the system proceeds with duplication.

4.5.3. Duplication Process

When validation passes:

1. The system creates a new add-on record with a new unique ID.
2. The system copies all fields from the original add-on:
   • Name: user-provided new name
   • Description: copied from original
   • Price: copied from original
   • Brand ID: copied from original (same brand)
   • Type: "simple_addon" (same as original)
   • customer_quantity_toggle: copied from original
   • event_types: deep copy of array (same event types)
   • service_types: deep copy of array (same service types)
   • Status: "draft"
   • Created timestamp: current date and time
   • Created by: current user's ID
3. The system saves the new record to the database.
4. The system closes the rename modal.
5. The system displays a success toast: "A-La-Carte item duplicated successfully."
6. The system shows the duplicate in the list view (appears at the top with newest first sort).

4.6. Delete Add-On Logic

4.6.1. Delete Initiation

When a user clicks the "Delete" option from the Actions menu:

1. The system validates that the user has Owner or Admin role (Project Managers and Coordinators cannot delete).
2. The system captures the add-on ID from the selected row.
3. The system displays a confirmation modal:
   • Title: "Delete A-La-Carte Item?"
   • Message: "Are you sure you want to delete '[Item Name]'? This action cannot be undone."
   • Buttons: "Cancel" (gray) and "Delete" (red, destructive)

4.6.2. No Usage Check Required

Critical Difference from Package Groups:

Unlike package groups (Section 1), the system does NOT check if the add-on is used in any proposals before allowing deletion. Simple Add-Ons can always be deleted regardless of usage.

4.6.3. Deletion Process

When the user confirms deletion:

1. The system deletes the add-on record from the alacarte_items table.
2. The system also deletes all package-to-add-on link records from the package_alacarte_links table where the alacarte_id matches the deleted add-on ID.
   • This removes the add-on from all packages that had it linked.
3. The system immediately removes the item from the A-La-Carte list view display.
4. The system updates pagination if necessary.
5. The system displays a success toast: "A-La-Carte item deleted successfully."

4.6.4. Delete Impact Rules

Critical Rules:

1. Deleting an add-on does NOT affect existing proposals or projects.
2. Proposals created before the deletion retain a static snapshot of the add-on and continue to display it.
3. Projects created from old proposals also retain the add-on in their scope.
4. Packages that had the add-on linked will no longer show it in the Package Builder (link removed).
5. New proposals created after deletion will not show the add-on as an option (because it no longer exists in the database).

4.7. Proposal Visibility and Behavior Logic

4.7.1. Displaying Add-Ons in Proposals

When a client views a proposal and selects a package from the package list:

1. The system retrieves all add-ons linked to the selected package from the package_alacarte_links table.
2. For each linked add-on, the system loads the full add-on record from the alacarte_items table.
3. The system applies the visibility rules:
   • The system checks if the add-on's event_types array intersects with the package's events array.
   • The system checks if the add-on's service_types array intersects with the package's services array.
   • If both checks pass (at least one matching event AND at least one matching service), the add-on is included in the display list.
   • If either check fails, the add-on is excluded from the display.
4. The system displays qualifying add-ons as optional selections under the package in a dedicated "Add-Ons" section.

4.7.2. Quantity Selection Behavior

For each displayed add-on:

1. The system checks the customer_quantity_toggle field.
2. If toggle is true (ON):
   • The system displays a quantity selector next to the add-on (dropdown or +/- buttons).
   • The quantity selector allows values from 1 to 10.
   • The client can select their desired quantity.
3. If toggle is false (OFF):
   • The system does not display a quantity selector.
   • The quantity is fixed at 1.
   • The client can only choose to include or exclude the add-on (checkbox or toggle).

4.7.3. Price Calculation in Proposals

When calculating the total proposal price:

1. For each selected add-on, the system retrieves the add-on's price field.
2. The system multiplies the price by the selected quantity:
   • Formula: add-on_total_price = add-on.price × selected_quantity
3. The system adds the calculated add-on total price to the overall proposal total.
4. If the add-on price is 0 and quantity toggle is ON, the client can select multiple quantities at no cost (free add-on).

4.7.4. Add-On Selection State

The client's add-on selections (which add-ons are selected and their quantities) are stored with the proposal record. When the proposal is saved (as draft, sent, or signed), these selections are persisted.

4.8. Version Control and Snapshot Logic

4.8.1. Snapshot Creation on Proposal Generation

When a proposal is created (saved as draft, sent, or signed):

1. The system identifies all add-ons selected by the client.
2. For each selected add-on, the system creates a complete snapshot including:
   • Add-on ID (for reference)
   • Name (as it exists at the time of proposal creation)
   • Description
   • Price (as it exists at the time of proposal creation)
   • customer_quantity_toggle state
   • event_types array
   • service_types array
   • All other configuration fields
   • Selected quantity (from client's selection)
3. The system stores these snapshots in the proposal_snapshots table linked to the proposal ID.
4. These snapshots are immutable and never modified after creation.

4.8.2. Edit Protection Through Snapshots

When an add-on is edited after being used in proposals:

1. The system updates the live record in the alacarte_items table with the new values.
2. The system does NOT touch any records in the proposal_snapshots table.
3. Old proposals continue to reference their immutable snapshots.
4. When a user views an old proposal, the system displays the add-on exactly as it was configured at the time of proposal creation (using the snapshot data).
5. When a user creates a new proposal, the system fetches current data from the alacarte_items table (not from snapshots).

4.8.3. Delete Protection Through Snapshots

When an add-on is deleted after being used in proposals:

1. The system deletes the record from the alacarte_items table.
2. The system does NOT delete any records from the proposal_snapshots table.
3. Old proposals continue to display the deleted add-on (using snapshot data) as if it still exists.
4. New proposals will not show the add-on because it no longer exists in the live alacarte_items table.

This snapshot-based architecture ensures that editing or deleting add-ons never causes data loss or inconsistencies in existing proposals or projects.

5. FIELD DETAILS & VALIDATIONS

Field Name

Type

Data Type

Required

Max Length

Validation Rules

Error Messages

Item Name

Text Input

String

Yes

100 chars

Cannot be empty; must be unique within brand (case-insensitive); auto-trim whitespace

"Item name is required." / "Item name already exists."

Description

Text Area

String

No

500 chars

Optional

None

Price

Numeric Input

Decimal

Yes

N/A

Must be numeric; must be >= 0; cannot be negative

"Price is required." / "Price must be a positive number."

Brand

Dropdown

UUID (FK)

Yes

N/A

Must reference valid brand from brands table; locked after creation

"Brand is required."

Customer Can Choose Quantity

Toggle

Boolean

No

N/A

Default OFF; optional

None

Event Types

Multi-Select

Array<UUID>

Yes

N/A

At least 1 event must be selected; must reference valid events from event_types_master

"Select at least one event."

Service Types

Multi-Select

Array<UUID>

Yes

N/A

At least 1 service must be selected; must reference valid services from service_types_master

"Select at least one service."

Internal Notes

Text Area

String

No

1000 chars

Optional; internal only (not shown to clients)

None

6. SUCCESS MESSAGE HANDLING

Trigger Condition

Success Message

Display Type

Duration

Post-Success Action

Add-On Created

"A-La-Carte item created successfully."

Toast (green checkmark)

5 seconds

User returned to list view; new item appears in table

Add-On Updated

"A-La-Carte item updated successfully."

Toast (green checkmark)

5 seconds

User returned to list view; changes reflected in table

Add-On Duplicated

"A-La-Carte item duplicated successfully."

Toast (green checkmark)

5 seconds

Duplicate appears in list; user can edit immediately

Add-On Deleted

"A-La-Carte item deleted successfully."

Toast (green checkmark)

5 seconds

Item removed from list; old proposals unaffected

Filter Applied

Visual feedback only (no toast)

Filter count badge appears

N/A

List updates to show filtered results

Search Results Found

Visual feedback only (no toast)

Matching results displayed

N/A

List updates instantly

7. ERROR MESSAGE HANDLING

Trigger Condition

Error Message

Display Type

User Action Required

Item Name Empty

"Item name is required."

Inline (below field, red text)

Enter a valid item name

Item Name Duplicate

"Item name already exists."

Inline (below field, red text)

Enter a unique item name

Price Invalid

"Price is required." / "Price must be a positive number."

Inline (below field, red text)

Enter a valid price >= 0

Brand Not Selected

"Brand is required."

Inline (below dropdown, red text)

Select a brand from the dropdown

No Events Selected

"Select at least one event."

Inline (below multi-select, red text)

Select at least one event type

No Services Selected

"Select at least one service."

Inline (below multi-select, red text)

Select at least one service type

Failed to Save

"Failed to save A-La-Carte item. Please try again."

Toast (red error icon)

Check connection; retry

Failed to Delete

"Failed to delete A-La-Carte item. Please try again."

Toast (red error icon)

Retry deletion

No Items Found (Search)

"No A-La-Carte items found."

Empty state message

Modify search query or clear search

No Items Found (Filter)

"No A-La-Carte items found."

Empty state message

Modify filters or clear all filters

8. EDGE CASES

Edge Case

Description

Expected System Behavior

Delete Add-On Linked to Multiple Packages

User deletes an add-on that is linked to 5 packages

System allows deletion; links removed from all packages; old proposals retain static snapshots; new proposals no longer show item

Duplicate Add-On with Same Name

User duplicates an add-on but tries to use "Copy of [Name]" which already exists

System displays error: "Item name already exists."; user must enter unique name

Edit Add-On Used in Active Proposals

User edits an add-on that is used in 10+ active proposals

System allows edits; all changes saved; old proposals unaffected (static snapshots); new proposals use updated version

Change Brand After Creation

User attempts to change the brand dropdown in edit mode

Brand dropdown is read-only (locked); user cannot change brand; must duplicate to reassign brand

Quantity Toggle ON with Price = 0

User sets price to $0 and enables quantity toggle

System allows (valid free add-on); client can select quantity 1-10 at no cost

Select All Event Types

User selects all 21 event types for an add-on

System allows; add-on appears in proposals for packages with any event type (as long as service type matches)

Unlink Add-On From Package in Builder

User unlinks add-on from package in Package Builder after it's been used in proposals

System allows; link removed from package; old proposals retain add-on; new proposals don't show add-on

User Loses Connection While Creating

User fills form but loses internet before clicking "Create New Item"

System displays error toast: "No internet connection."; data not saved; user must retry after reconnection

Brand Deleted After Add-On Created

Add-on's brand is deleted by admin

Add-on remains; brand displays as "Archived Brand"; add-on becomes read-only or editable only by Owner/Admin

Event Type Deleted After Add-On Created

Event type referenced by add-on is deleted from master data

Add-on retains reference but displays warning icon; add-on no longer appears in proposals for that event type

9. ACCEPTANCE CRITERIA (MINIMAL - CRITICAL TESTS ONLY)

AC1: Create Add-On Successfully

Given user fills all required fields (name, price, brand, event types, service types) and clicks "Create New Item",
When validation passes,
Then system must save add-on to database and display success toast.

AC2: Item Name Uniqueness Validation

Given user enters an add-on name that already exists within the same brand,
When user clicks outside the name field,
Then system must display error: "Item name already exists."

AC3: Quantity Toggle Behavior in Proposal

Given add-on has customer_quantity_toggle = true,
When add-on appears in proposal,
Then system must display quantity selector (1-10); if false, quantity fixed at 1.

AC4: Delete Always Allowed

Given add-on is linked to 5 packages and used in 10 proposals,
When user deletes add-on,
Then system must allow deletion, remove links, keep old proposals unchanged.

AC5: Edit Does Not Affect Proposals

Given user edits add-on price from $50 to $75 after it's been used in proposals,
When edit is saved,
Then old proposals must retain $50; new proposals must use $75.

AC6: Visibility Rules in Proposal

Given add-on has Event = "Wedding" and Service = "Photography",
When package includes "Wedding" event with "Photography" service,
Then add-on must appear in proposal; otherwise hidden.

10. DEPENDENCIES

Dependency

Type

Relationship

Impact

Expected Behavior

Package Builder (Section 3)

Internal (REQUIRED)

Add-ons linked to packages in Package Builder

Provides attachment mechanism for add-ons

If Package Builder unavailable, add-ons cannot be linked to packages

Proposal Builder

Internal (INDIRECT)

Add-ons appear in proposals when linked to selected package

Determines client visibility and pricing

Only linked add-ons with matching event/service types appear

Project Module

Internal (INDIRECT)

Add-ons included in project details after signing

Add-on data flows to project scope

Once project created, editing add-on does NOT update project

Brand Master Data

External (REQUIRED)

Add-ons assigned to brands

Determines visibility and filtering

If brand deleted, add-on shows "Archived Brand"

Event Type Master Data

External (REQUIRED)

Event types selected from master data

Defines add-on visibility rules

If event deleted, add-on loses that visibility rule

Service Type Master Data

External (REQUIRED)

Service types selected from master data

Defines add-on visibility rules

Same as Event Type Master Data

Database

Technical (REQUIRED)

All add-on data stored in database

Stores add-ons, links, snapshots

If database unavailable, add-on management fails

Session Management

Technical (REQUIRED)

Validates user authentication

Ensures authorized access only

If session expires, user redirected to login

11. REFERENCES

11.1. Figma Design References

https://www.figma.com/design/ej0kxwP45mDKmZCZfAJ5O8/Pixally?node-id=20576-26312&t=BAkQ9BaQzOENaQKr-0

Deprecated_ALA-CARTE ITEMS (EVENT-CREATION ADD-ON)

SECTION 5: A-LA-CARTE EVENT-CREATION ADD-ON

1. MODULE OVERVIEW

1.1. Purpose

The A-La-Carte Event-Creation Add-On module manages special add-ons that automatically generate new events within a project when selected by clients during the proposal process. Unlike Simple Add-Ons (Section 4) which only enhance existing packages, Event-Creation Add-Ons expand the project scope by creating entirely new sub-events with their own services, deliverables, and timelines.

1.2. Business Goals

The Event-Creation Add-On module enables agencies to:

• Offer clients the ability to add complete events to their project scope (e.g., Engagement Shoot, Rehearsal Dinner as separate event, Pre-Wedding Session)
• Automatically generate new project events upon proposal signing
• Configure event-specific services and deliverables independent of the main package
• Implement quantity-selectable event add-ons for multi-day or multi-location scenarios
• Expand project revenue through strategic event upsells
• Maintain separate event timelines and contractor assignments

1.3. Functional Summary

Event-Creation Add-Ons are specialized items that differ from Simple Add-Ons in the following ways:

Key Differences:

• Type: Event-Creation Add-On (creates new events, unlike Simple Add-Ons)
• Project Impact: Generates a new sub-event in the project after proposal signing
• Service Configuration: Requires its own service types (does NOT inherit from main package per Ambiguity #2 clarification)
• Line Items: Can optionally include line items, smart fields, and deliverables specific to the new event
• Timeline: New event has its own date, separate from main package events
• Contractor Assignment: New event requires its own contractor assignments based on selected services

Workflow:

1. Admin creates Event-Creation Add-On with event type, services, optional line items
2. Add-on linked to packages in Package Builder (Section 3)
3. Add-on appears in proposals under linked packages
4. Client selects add-on (with optional quantity)
5. Client signs proposal
6. System automatically creates new event in project with configured services and deliverables

1.4. Module Boundaries

This module handles:

• Event-Creation add-on listing view (shared with Simple Add-Ons, filtered by type)
• Event-Creation add-on creation (4-step wizard: General → Event Details → Optional Line Items → Confirmation)
• Event-Creation add-on editing (same 4-step flow)
• Event-Creation add-on duplication with rename
• Event-Creation add-on deletion (always allowed; proposals keep static snapshots)
• Event type and service type configuration (independent of main package)
• Optional line items, smart fields, and deliverables for the new event
• Quantity toggle configuration for multi-event scenarios
• Brand assignment and visibility rules

This module does NOT handle:

• Simple Add-Ons (handled in Section 4)
• Linking add-ons to packages (handled in Package Builder, Section 3)
• Proposal generation logic (handled by Proposal Builder)
• Actual project event creation logic (handled by Project Module after signing)
• Event scheduling and contractor assignments (handled by Project/Events Module)
• Service inheritance from main package (explicitly NOT supported per clarification)

2. USER ROLES & PERMISSIONS

Role

View Event Add-Ons

Create Event Add-On

Edit Event Add-On

Duplicate Event Add-On

Publish Event Add-On

Delete Event Add-On

Owner

✔

✔

✔

✔

✔

✔

Admin

✔

✔

✔

✔

✔

✔

Project Manager

✔

✔ (optional, agency setting)

✔ (optional)

✔ (optional)

✖

✖

Coordinator

✔

✔ (optional, agency setting)

✔ (optional)

✔ (optional)

✖

✖

Contractor

✖

✖

✖

✖

✖

✖

Client

✖

✖

✖

✖

✖

✖

Notes:

• Only Owner and Admin can publish Event-Creation Add-Ons
• PM and Coordinator permissions configurable at agency level
• Contractors and Clients never access A-La-Carte management

3. USER FLOW (MINIMIZED)

3.1. Accessing A-La-Carte List View

Entry Points:

• Navigate to Packages → A La Carte Items tab
• Filter by Type = "Event-Creation" to show only event add-ons
• Direct URL: /packages/alacarte?type=event_creation

List View:

• Columns: Name, Type (Event-Creation), Event Type, Service Types, Price, Created, Actions
• Shared list with Simple Add-Ons (Section 4); filtered by type

3.2. Creating Event-Creation Add-On

4-Step Wizard:

Step 1: General Information

1. Select Event tab (not Add-on tab)
2. Enter Add-On Name (e.g., "Rehearsal Dinner Event", "Engagement Shoot")
3. Enter Description (optional)
4. Enter Price (required, >= 0)
5. Select Brand (required, locked after creation)
6. Toggle "Customer Can Select Quantity" (ON = client selects 1-10 events, OFF = fixed 1 event)
7. Click "Next"

Step 2: Event Details

1. Select Event Type (single-select dropdown: e.g., Rehearsal Dinner, Engagement Shoot, Elopement)
   • This determines which NEW event will be created in the project
2. Select Service Types (multi-select: Photography, Videography, Content Creation)
   • Critical: Services are configured here, NOT inherited from main package (per Ambiguity #2 clarification)
3. Tooltip explains: "This event will be created as a separate event in the project with its own date and services"
4. Click "Next"

Step 3: Optional Line Items & Smart Fields

1. Optionally add line items specific to this new event:
   • Line Item Name, Type (Standard or Smart Field), Description
   • Deliverable toggle and due date rule
   • Taxable toggle and amount (if applicable)
2. Optionally add Smart Fields for dynamic mapping
3. Click "Next"

Step 4: Finish

1. Review summary of configuration
2. Click "Create Event Add-On"
3. System saves as Draft
4. Success toast displayed

3.3. Editing Event-Creation Add-On

1. Click "Edit" from Actions menu
2. Same 4-step wizard loads with pre-filled data
3. Make changes
4. Click "Update Event Add-On"
5. Changes do NOT affect existing proposals (static snapshots)
6. New proposals use updated configuration

3.4. Duplicating Event-Creation Add-On

1. Click "Duplicate" from Actions menu
2. Rename modal appears
3. Enter unique name
4. Full copy created (event type, services, line items, price, quantity toggle)
5. New item saved as Draft

3.5. Deleting Event-Creation Add-On

1. Click "Delete" from Actions menu
2. Confirmation modal appears
3. Click "Delete"
4. Item permanently deleted
5. Critical: Event-Creation Add-Ons can ALWAYS be deleted (no usage blocking)
6. Old proposals retain static snapshot; old projects retain created events; new proposals no longer show item

3.6. Behavior After Proposal Signing

When client signs proposal with Event-Creation Add-On selected:

1. System creates new event in Project Module:
   • Event Type = configured event type (e.g., Rehearsal Dinner)
   • Event Date = to be scheduled (separate from main events)
   • Services = configured service types (e.g., Photography, Videography)
   • Line Items = configured deliverables with due date rules
   • Smart Fields = mapped to project details
2. New event appears in project timeline
3. Contractors assigned based on service types
4. Deliverables routed to Post-Production module

4. FUNCTIONAL LOGIC

4.1. Data Model and Key Differences

4.1.1. Event-Creation Add-On Data Structure

Each Event-Creation Add-On record contains the following core data elements:

1. Unique identifier (UUID)
2. Item name (max 100 characters)
3. Optional description (max 500 characters)
4. Price (decimal value, minimum 0)
5. Brand assignment (foreign key reference)
6. Type designation (always set to "event_creation" for this section)
7. Customer quantity toggle (boolean value determining if clients can select quantity 1-10)
8. Event type (SINGLE UUID) - specifies which new event to create in the project
9. Service types array - services for the new event (NOT inherited from main package)
10. Optional line items array with nested structure containing: name, type (standard or smart field), smart field type, description, deliverable toggle, due date rule, taxable toggle, taxable amount, and price
11. Status (draft or published)
12. Creation timestamp
13. Creator user reference

4.1.2. Key Differences from Simple Add-Ons (Section 4)

Event-Creation Add-Ons differ from Simple Add-Ons in three critical ways:

1. **Event Type Field:
   **
   • Simple Add-Ons: Use an event_types array (plural) with multiple event types for visibility rules.
   • Event-Creation Add-Ons: Use a single event_type field (singular) specifying which NEW event to create in the project.
2. **Line Items Support:
   **
   • Simple Add-Ons: Do not have line items (they enhance existing package line items).
   • Event-Creation Add-Ons: Have an optional line_items array allowing event-specific deliverables, smart fields, and tax settings.
3. **Project Impact:
   **
   • Simple Add-Ons: Do not create new events; they only add optional services to existing package structure.
   • Event-Creation Add-Ons: Automatically generate new events in the Project Module when a proposal is signed, expanding the project scope.

4.2. List View and Filtering

4.2.1. Loading Event-Creation Add-Ons in List View

When a user accesses the A-La-Carte Items section:

1. The system retrieves all add-on items where the type field equals "event_creation" (filtering out simple add-ons).
2. The system applies the same agency and brand access filters as Simple Add-Ons.
3. The system displays Event-Creation Add-Ons in the same table as Simple Add-Ons but with a distinct "Event-Creation" badge in the Type column.
4. The Event Type column displays a single event name (e.g., "Rehearsal Dinner") rather than multiple event tags.
5. The Service Types column displays all selected services that will be assigned to the new event.

4.2.2. Sorting and Filtering

Event-Creation Add-Ons share the same sorting and filtering functionality as Simple Add-Ons with one difference:

1. The Event Type column shows the single event that will be created (not multiple events for visibility).
2. All other sorting (by name, date, price) and filtering (by brand, event type, service type) work identically.

4.3. Create Event-Creation Add-On Flow

4.3.1. Wizard Initialization

When a user clicks "Create New A-La-Carte Item" and selects the Event tab:

1. The system opens a 4-step wizard (one more step than Simple Add-Ons).
2. The wizard displays two tabs: "Add-on" (inactive) and "Event" (active with orange indicator).
3. The system displays Step 1: General Information in the center canvas.

4.3.2. Step 1 - General Information (Same as Simple Add-Ons)

Step 1 is identical to Simple Add-Ons (Section 4):

1. Users enter: Add-On Name, Description (optional), Price, Brand, and Customer Quantity Toggle.
2. The system performs the same validations: name uniqueness within brand, price >= 0, brand required.
3. Brand assignment is locked after creation and cannot be changed later.
4. When validation passes and user clicks "Next", the system proceeds to Step 2.

4.3.3. Step 2 - Event Details Configuration

This step differs significantly from Simple Add-Ons:

Event Type Selection (Single-Select):

1. The system displays a dropdown labeled "Event Type" (not multi-select buttons like Simple Add-Ons).
2. The dropdown is populated with all event types from the event types master data table.
3. Users can select only ONE event type (e.g., "Rehearsal Dinner", "Engagement Shoot", "Elopement").
4. The system validates that an event type is selected before allowing progression.
5. An informational tooltip explains: "This event will be created as a separate event in the project with its own date and services."
6. The selected event type determines which NEW event will be created in the project when the proposal is signed.

Service Types Selection:

1. The system displays three service type buttons: Photography, Videography, Content Creation.
2. Users can select one or more services.
3. The system validates that at least one service is selected.
4. Critical: These services are configured independently and will be assigned to the NEW event only.
5. From Ambiguity #2 Clarification: Services are NOT inherited from the main package. If the main package has Photography + Videography, and the event add-on has only Photography, then the new event gets only Photography.

When validation passes and user clicks "Next", the system proceeds to Step 3.

4.3.4. Step 3 - Optional Line Items Configuration

This step is unique to Event-Creation Add-Ons and does not exist for Simple Add-Ons:

Line Item Addition (Optional):

1. The system displays an interface similar to the Package Builder's line item section.

2. Users can optionally add line items specific to the new event by clicking "+ Add Line Item".

3. For each line item, users configure:

   • Line Item Name (required, max 100 characters)
   • Line Item Type (Standard or Smart Field)
   • If Smart Field: Select from predefined smart fields (Hours Coverage, Number of Edited Images, Second Shooter, Additional Hours)
   • Description (optional)
   • Deliverable toggle (ON or OFF)
   • If Deliverable ON: Due date rule (X Days/Weeks/Months after event)
   • Taxable toggle (if applicable based on tax mode)
   • If Taxable ON: Taxable amount and price

4. Users can add multiple line items (no upper limit).

5. Users can choose to skip this step entirely (line items are optional for Event-Creation Add-Ons).

6. When user clicks "Next", the system validates any added line items and proceeds to Step 4.

4.3.5. Step 4 - Review and Save

When user clicks "Create Event Add-On":

1. The system validates all fields from Steps 1-3.
2. The system creates a new add-on record in the database with:
   • Type: "event_creation"
   • Event type: Single UUID (not an array)
   • Service types: Array of service type UUIDs
   • Line items: Optional nested array structure (or null if no line items added)
   • All other fields from Step 1 (name, description, price, brand, quantity toggle)
   • Status: "draft"
   • Timestamps and user references
3. The system displays a success toast: "Event-Creation add-on created successfully."
4. The system closes the wizard and returns to the list view.

4.4. Edit Event-Creation Add-On Logic

4.4.1. Loading Existing Data

When a user clicks "Edit" on an Event-Creation Add-On:

1. The system loads the 4-step wizard with all fields pre-filled.
2. The Brand field is read-only (locked) - cannot be changed after creation.
3. The Event Type dropdown shows the currently selected single event.
4. The Service Types show currently selected services.
5. Step 3 displays any existing line items or shows an empty state if none were configured.

4.4.2. Editing Event Type and Services

Users can modify the event type and services:

1. Changing the event type from "Rehearsal Dinner" to "Engagement Shoot" is allowed.
2. Adding or removing services (e.g., changing from Photography-only to Photography + Videography) is allowed.
3. These changes do NOT affect proposals or projects already created.

4.4.3. Editing Line Items

Users can modify line items in Step 3:

1. Users can add new line items to an existing Event-Creation Add-On.
2. Users can edit existing line items (names, deliverable settings, due dates, tax settings).
3. Users can delete line items by clicking the delete icon.
4. These changes do NOT affect projects already created from old proposals.

4.4.4. Saving Edits

When user clicks "Update Event Add-On":

1. The system updates the add-on record with new values.
2. The system records the current timestamp as updated_at.
3. Critical Rule: The system does NOT update existing proposals or projects.
4. Proposals store static snapshots - old proposals retain the original event add-on configuration.
5. Projects that already have events created from this add-on retain those events with their original configuration (event type, services, line items).
6. Only new proposals created after the edit will use the updated configuration.

4.5. Duplicate Event-Creation Add-On Logic

4.5.1. Duplication Process

When a user clicks "Duplicate":

1. The system opens a rename modal pre-filled with "Copy of [Original Item Name]".
2. The system validates name uniqueness within the brand.
3. If validation passes, the system creates a complete copy including:
   • All Step 1 fields (name set to new unique name, same description, price, brand, quantity toggle)
   • Event type (same single event as original)
   • Service types array (deep copy)
   • Line items array (deep copy of all line items with their full configuration)
4. The system assigns a new unique ID to the duplicate.
5. The system sets status to "draft".
6. The duplicate appears in the list view and can be edited immediately.

4.6. Delete Event-Creation Add-On Logic

4.6.1. Delete Process

When a user deletes an Event-Creation Add-On:

1. The system displays a confirmation modal.
2. If confirmed, the system deletes the add-on record and all package links.
3. Critical Rule: Event-Creation Add-Ons can ALWAYS be deleted, just like Simple Add-Ons.

4.6.2. Impact on Existing Projects

Important Behavior:

1. Deleting an Event-Creation Add-On does NOT delete events already created in projects.
2. If the add-on was used in 10 signed proposals and created 10 events in 10 projects, those 10 events remain intact in their projects.
3. The events continue to function normally with their configured services, line items, and deliverables.
4. Only new proposals will no longer be able to select this add-on (because the live record is deleted).
5. Packages linked to this add-on will no longer show it in their A-La-Carte section.

4.7. Proposal Display and Client Selection

4.7.1. Display in Proposals

When a client views a proposal with an Event-Creation Add-On:

1. The add-on appears as a separate section under the package (distinct from Simple Add-Ons).
2. The system displays:
   • Add-on name
   • Description
   • Price
   • Event type that will be created (e.g., "Rehearsal Dinner")
   • Services that will be assigned to the new event (e.g., "Photography, Videography")
   • Quantity selector (if customer quantity toggle is ON) or fixed quantity 1 (if toggle is OFF)

4.7.2. Quantity Selection

If the customer quantity toggle is ON:

1. The client sees a quantity selector (dropdown or number input).
2. The client can select a quantity from 1 to 10.
3. Each quantity unit represents one complete event to be created.
4. Example: Client selects "Engagement Shoot" with quantity 3 → Three separate engagement shoot events will be created in the project, each requiring its own date and contractor assignments.

4.7.3. Price Calculation

The system calculates the add-on's contribution to the proposal total:

1. Add-on price × selected quantity = Total contribution.
2. Example: Add-on price = $200, quantity = 2 → Contribution = $400.
3. This amount is added to the proposal subtotal.

4.8. Project Event Creation After Signing

4.8.1. Trigger Point

When a client signs a proposal containing Event-Creation Add-Ons:

1. The Proposal Builder sends the signed proposal data to the Project Module.
2. The Project Module identifies all selected Event-Creation Add-Ons and their quantities.
3. For each add-on, the Project Module initiates event creation.

4.8.2. Event Generation Logic

For each Event-Creation Add-On selected with quantity N:

1. The system creates N separate events in the Project Module.
2. Each event is a distinct, independent sub-event within the project.

Example:

• Add-on: "Rehearsal Dinner Event" with quantity 2
• Result: Two separate "Rehearsal Dinner" events are created in the project timeline
• Each event has its own date (to be scheduled by the user), services, deliverables, and contractor assignments

4.8.3. Event Configuration

For each generated event, the system configures:

1. Event Type: Set to the event type configured in the add-on (e.g., "Rehearsal Dinner").
2. Event Name: Auto-generated as "[Add-On Name] [Number]" (e.g., "Rehearsal Dinner Event 1", "Rehearsal Dinner Event 2").
3. Event Date: Initially set to null (user must schedule the event date separately from main package events).
4. Service Types: Set to the services configured in the add-on (e.g., ["Photography", "Videography"]).
5. Status: Set to "pending_schedule" indicating the event needs a date assignment.
6. Source Reference: Stored with metadata indicating the event was created from an A-La-Carte add-on (not from the main package).

4.8.4. Line Item and Deliverable Creation

If the add-on has line items configured in Step 3:

1. For each line item where deliverable toggle is ON:
   • The system creates a deliverable task in the Post-Production module.
   • The deliverable is linked to the new event (not the main package events).
   • The due date is calculated as: Event Date + X days/weeks/months (using the due date rule from the line item configuration).
   • The deliverable is assigned to a contractor based on the service type.
   • The deliverable status is set to "pending" until completed.
2. For smart field line items:
   • The smart field values are mapped to project details.
   • Example: "Hours Coverage" smart field with value 4 → The new event is scheduled for 4 hours of coverage.

4.8.5. Service Independence (No Inheritance)

From Ambiguity #2 Clarification:

The system does NOT inherit services from the main package. Event-Creation Add-Ons must configure their own services independently.

Logic:

1. Main Package: Wedding event with Photography + Videography + Content Creation services.
2. Event-Creation Add-On: Rehearsal Dinner event with Photography only (configured in Step 2).
3. Result in Project:
   • Wedding event: Photography + Videography + Content Creation (from main package)
   • Rehearsal Dinner event: Photography only (from add-on, NO inheritance)
4. The two events are completely independent in terms of service assignments.

4.9. Version Control and Snapshot Logic

4.9.1. Snapshot Creation on Proposal Creation

When a proposal is created:

1. The system captures all Event-Creation Add-Ons selected by the client.
2. For each add-on, the system creates a complete snapshot including:
   • Add-on ID (reference to original)
   • Name, description, price
   • Event type (which event will be created)
   • Service types (which services will be assigned)
   • Line items array (complete nested structure with all deliverable and tax settings)
   • Customer quantity toggle state
   • Selected quantity (client's choice, 1-10)
3. The snapshot is stored in the proposals_snapshots table or as a JSON field within the proposal record.
4. The snapshot is immutable.

4.9.2. Edit Protection

After a proposal is created and signed:

1. Users can edit the Event-Creation Add-On in the A-La-Carte list view.
2. The system updates the live add-on record.
3. The system does NOT update proposal snapshots.
4. The system does NOT modify or delete events already created in projects.
5. Old proposals continue to reference their immutable snapshots.
6. Old projects continue to have their events with the original configuration.
7. New proposals created after the edit will use the updated add-on configuration and create events with the new settings.

5. FIELD DETAILS & VALIDATIONS

Field Name

Type

Data Type

Required

Max Length

Validation Rules

Error Messages

Add-On Name

Text Input

String

Yes

100 chars

Cannot be empty; must be unique within brand; auto-trim whitespace

"Add-on name is required." / "Name already exists."

Description

Text Area

String

No

500 chars

Optional

None

Price

Numeric Input

Decimal

Yes

N/A

Must be numeric; >= 0; cannot be negative

"Price is required." / "Price must be positive."

Brand

Dropdown

UUID (FK)

Yes

N/A

Must reference valid brand; locked after creation

"Brand is required."

Customer Can Select Quantity

Toggle

Boolean

No

N/A

Default OFF; optional

None

Event Type

Dropdown (single-select)

UUID (FK)

Yes

N/A

Must reference valid event from event_types_master; single selection only

"Event type is required."

Service Types

Multi-Select

Array<UUID>

Yes

N/A

At least 1 service required; must reference valid services from service_types_master

"Select at least one service."

Line Item Name

Text Input

String

Yes (if adding line item)

100 chars

Cannot be empty

"Line item name is required."

Line Item Type

Dropdown

Enum

Yes (if adding line item)

N/A

Must select: Standard or Smart Field

"Line item type is required."

Smart Field Type

Dropdown

Enum

Yes (if type = Smart Field)

N/A

Must select from predefined list

"Smart field type is required."

Deliverable Toggle

Toggle

Boolean

No

N/A

Default OFF; optional

None

Due Date Value

Numeric Input

Integer

Yes (if Deliverable ON)

N/A

Must be numeric; > 0

"Due date value is required."

Due Date Unit

Dropdown

Enum

Yes (if Deliverable ON)

N/A

Must select: Days, Weeks, or Months

"Due date unit is required."

Taxable Toggle

Toggle

Boolean

No

N/A

Optional

None

Taxable Amount

Numeric Input

Decimal

Yes (if Taxable ON)

N/A

Must be numeric; >= 0

"Taxable amount is required."

6. SUCCESS MESSAGE HANDLING

Trigger Condition

Success Message

Display Type

Duration

Post-Success Action

Event Add-On Created

"Event-Creation add-on created successfully."

Toast (green checkmark)

5 seconds

User returned to list view; new item appears

Event Add-On Updated

"Event-Creation add-on updated successfully."

Toast (green checkmark)

5 seconds

Changes saved; list view updated

Event Add-On Duplicated

"Event-Creation add-on duplicated successfully."

Toast (green checkmark)

5 seconds

Duplicate appears in list; auto-selected for editing

Event Add-On Deleted

"Event-Creation add-on deleted successfully."

Toast (green checkmark)

5 seconds

Item removed; old proposals/projects unaffected

Line Item Added

Visual feedback only (no toast)

Line item appears in Step 3

N/A

User can add more items or proceed

Event Created in Project

"New event created successfully in project."

Toast (green checkmark, after signing)

5 seconds

New event appears in project timeline

7. ERROR MESSAGE HANDLING

Trigger Condition

Error Message

Display Type

User Action Required

Add-On Name Empty

"Add-on name is required."

Inline (red text)

Enter a valid name

Name Duplicate

"Name already exists."

Inline (red text)

Enter unique name

Price Invalid

"Price is required." / "Price must be positive."

Inline (red text)

Enter valid price >= 0

Brand Not Selected

"Brand is required."

Inline (red text)

Select a brand

Event Type Not Selected

"Event type is required."

Inline (red text)

Select an event type

No Services Selected

"Select at least one service."

Inline (red text)

Select at least one service

Line Item Name Empty

"Line item name is required."

Inline (red text)

Enter line item name

Due Date Missing

"Due date value is required." / "Due date unit is required."

Inline (red text)

Enter due date value and unit

Failed to Save

"Failed to save event add-on. Please try again."

Toast (red error icon)

Check connection; retry

Failed to Create Event in Project

"Failed to create event in project. Please contact support."

Toast (red error icon)

Contact support

8. EDGE CASES

Edge Case

Description

Expected System Behavior

Delete Event Add-On Used in Active Projects

User deletes an event add-on that created events in 10+ active projects

System allows deletion; add-on removed; existing project events remain intact (not deleted); new proposals no longer show add-on

Edit Event Type After Project Created

User changes event add-on from "Rehearsal Dinner" to "Engagement Shoot" after it was used in proposals

System allows edit; old projects retain "Rehearsal Dinner" events; new proposals create "Engagement Shoot" events

Quantity Toggle ON with Multiple Selections

Client selects event add-on with quantity 5 (e.g., 5 engagement shoots)

System creates 5 separate engagement events in project, each requiring its own date and contractor assignment

Event Add-On with Same Event Type as Main Package

Main package has "Wedding" event; event add-on also creates "Wedding" event

Both "Wedding" events appear in project as separate events (e.g., "Wedding" and "Wedding Event 1"); client schedules separately

Change Services After Project Created

User changes add-on from "Photography" to "Photography + Videography" after it was used

Old projects retain "Photography" only; new projects get "Photography + Videography"

Delete Line Item from Event Add-On

User removes a deliverable line item from event add-on after it was used

Old projects retain the deliverable; new projects no longer include it

Brand Deleted After Add-On Created

Add-on's brand deleted by admin

Add-on remains; brand shows "Archived Brand"; add-on becomes read-only or editable only by Owner/Admin

Price = 0 for Event Add-On

User sets price to $0 for event add-on

System allows (valid free event); client can add event at no cost

No Line Items Added (Optional Step 3 Skipped)

User creates event add-on without any line items in Step 3

System allows; event created in project with no deliverables; only services assigned

Client Selects Event Add-On but Doesn't Sign

Client selects event add-on in proposal but abandons before signing

No event created in project; add-on selection not persisted; next proposal starts fresh

9. ACCEPTANCE CRITERIA (MINIMAL - CRITICAL TESTS ONLY)

AC1: Create Event-Creation Add-On Successfully

Given user fills all required fields (name, price, brand, event type, service types) and clicks "Create Event Add-On",
When validation passes,
Then system must save event add-on to database with type = 'event_creation' and display success toast.

AC2: Event Type Single-Select Validation

Given user attempts to select multiple event types in Step 2,
When event type dropdown is displayed,
Then system must allow only single selection (not multi-select like Simple Add-Ons).

AC3: Service Independence (No Inheritance)

Given main package has "Photography + Videography" services,
When event add-on is configured with "Photography" only,
Then new project event must have "Photography" only (NOT inherited from main package).

AC4: Event Creation After Signing

Given client selects event add-on "Rehearsal Dinner" with quantity 2 and signs proposal,
When system converts proposal to project,
Then system must create 2 separate "Rehearsal Dinner" events in project with configured services.

AC5: Delete Does Not Affect Existing Projects

Given event add-on used in 5 active projects (created 5 events),
When user deletes event add-on,
Then system must delete add-on, but 5 existing project events remain intact.

AC6: Edit Does Not Affect Existing Projects

Given user edits event add-on services from "Photography" to "Photography + Videography" after it was used,
When edit is saved,
Then old projects must retain "Photography" only; new projects must use "Photography + Videography".

10. DEPENDENCIES

Dependency

Type

Relationship

Impact

Expected Behavior

Package Builder (Section 3)

Internal (REQUIRED)

Event add-ons linked to packages in Package Builder

Provides attachment mechanism

If Package Builder unavailable, event add-ons cannot be linked

Proposal Builder

Internal (INDIRECT)

Event add-ons appear in proposals when linked

Determines client visibility

Only linked event add-ons appear; visibility based on package selection

Project Module

Internal (REQUIRED)

Project Module creates events after proposal signing

Event creation logic executed here

If Project Module unavailable, events not created after signing

Events Module

Internal (REQUIRED)

New events added to project timeline and event list

Manages event dates and scheduling

If Events Module unavailable, event scheduling fails

Post-Production Module

Internal (INDIRECT)

Deliverables from event add-on line items sent here

Executes deliverable pipeline

If Post-Production unavailable, deliverables not tracked

Brand Master Data

External (REQUIRED)

Event add-ons assigned to brands

Determines visibility and filtering

If brand deleted, add-on shows "Archived Brand"

Event Type Master Data

External (REQUIRED)

Event type selected from master data

Defines which event to create

If event type deleted, add-on loses validity

Service Type Master Data

External (REQUIRED)

Service types selected from master data

Defines services for new event

Same as Event Type Master Data

Database

Technical (REQUIRED)

All event add-on data stored in database

Stores add-ons, links, snapshots, project events

If database unavailable, all operations fail

Session Management

Technical (REQUIRED)

Validates user authentication

Ensures authorized access

If session expires, user redirected to login

11. REFERENCES

11.1. Figma Design References

https://www.figma.com/design/ej0kxwP45mDKmZCZfAJ5O8/Pixally?node-id=20576-26501&t=BAkQ9BaQzOENaQKr-0