<?php
/**
 * Admin help panel functionality.
 *
 * @package BoxCart
 */

// If this file is called directly, abort.
if ( ! defined( 'ABSPATH' ) ) {
	exit;
}

/**
 * Admin Help class.
 *
 * Provides contextual help for admin pages.
 */
class BoxCart_Admin_Help {

	/**
	 * Get help content for a specific page.
	 *
	 * @param string $page Page identifier.
	 * @return array Help content.
	 */
	public static function get_help_content( $page ) {
		$help_data = self::get_all_help_data();

		return isset( $help_data[ $page ] ) ? $help_data[ $page ] : $help_data['default'];
	}

	/**
	 * Get all help data for all pages.
	 *
	 * Returns an array keyed by page identifier. Extensions can hook the
	 * `boxcart_admin_help_topics` filter to add their own topics and subtabs.
	 *
	 * @return array All help content.
	 */
	private static function get_all_help_data() {
		$topics = array(
			'dashboard'           => array(
				'title'       => __( 'Dashboard', 'boxcart' ),
				'description' => __( 'Your command centre for BoxCart. Monitor today\'s orders, check slot availability, see pending and ready-for-collection counts, and quickly access key areas of the plugin.', 'boxcart' ),
				'tips'        => array(
					__( 'Click the stat cards to jump straight to filtered order lists (e.g., today\'s orders, pending, or ready for collection).', 'boxcart' ),
					__( 'The availability bars show how full your collection slots are today, colour-coded green, amber, and red.', 'boxcart' ),
					__( 'Use the Quick Actions panel to add products, manage collection, view orders, or open settings in one click.', 'boxcart' ),
					__( 'New to BoxCart? Follow the Quick Start Guide, which stays on your dashboard until setup is complete or you dismiss it.', 'boxcart' ),
				),
				'docs'        => array(
					array(
						'label' => __( 'Getting Started Guide', 'boxcart' ),
						'url'   => 'https://docs.boxcart.dev/getting-started',
					),
					array(
						'label' => __( 'Features Overview', 'boxcart' ),
						'url'   => 'https://docs.boxcart.dev/features',
					),
				),
			),
			'orders'              => array(
				'title'       => __( 'Orders', 'boxcart' ),
				'description' => __( 'View and manage all customer orders. Filter by status, date range, location, or search by customer name, email, or order number. Export orders to CSV or Excel.', 'boxcart' ),
				'tips'        => array(
					__( 'Use the status tabs at the top to quickly filter orders by their current state.', 'boxcart' ),
					__( 'Click the Export button to download orders as CSV or Excel, filtered by date range, status, and location.', 'boxcart' ),
					__( 'When payments are enabled, a separate Payment Status column shows the payment state alongside the order status.', 'boxcart' ),
				),
				'docs'        => array(
					array(
						'label' => __( 'Orders Guide', 'boxcart' ),
						'url'   => 'https://docs.boxcart.dev/orders',
					),
				),
			),
			'order-view'          => array(
				'title'       => __( 'Order Details', 'boxcart' ),
				'description' => __( 'View complete order information including items, customer details, collection slot, payment status, and the full status history. Update the order status with optional notes.', 'boxcart' ),
				'tips'        => array(
					__( 'The status history shows every status change with timestamps, who made the change, and any notes added.', 'boxcart' ),
					__( 'For bank transfer orders, use the "Confirm Payment Received" button once you\'ve verified the transfer.', 'boxcart' ),
					__( 'A cancelled order can be deleted for good from under Update Status, for example a test order.', 'boxcart' ),
				),
				'docs'        => array(
					array(
						'label' => __( 'Order Lifecycle Guide', 'boxcart' ),
						'url'   => 'https://docs.boxcart.dev/orders',
					),
				),
			),
			'products'            => array(
				'title'       => __( 'Products', 'boxcart' ),
				'description' => __( 'Manage your product catalogue. Add products, set prices and quantity types, manage stock, assign categories, and control visibility. Use filters, search, bulk actions, and the duplicate feature to work efficiently.', 'boxcart' ),
				'tips'        => array(
					__( 'Use the three-dot menu on each row to edit, duplicate, or delete a product.', 'boxcart' ),
					__( 'Select multiple products with checkboxes to perform bulk actions like setting stock status or deleting.', 'boxcart' ),
					__( 'Filter by category or stock status to quickly find specific products.', 'boxcart' ),
					__( 'Inactive (draft) products are shown with a muted style and an "Inactive" badge.', 'boxcart' ),
				),
				'docs'        => array(
					array(
						'label' => __( 'Products Guide', 'boxcart' ),
						'url'   => 'https://docs.boxcart.dev/products',
					),
				),
			),
			'product-edit'        => array(
				'title'       => __( 'Edit Product', 'boxcart' ),
				'description' => __( 'Configure all details for a product: name, description, image, categories, pricing, quantity types (e.g., each, per kg, punnet), SKU, stock level, and sort order.', 'boxcart' ),
				'tips'        => array(
					__( 'Quantity types define how a product is sold and priced. Use the presets dropdown or create custom types with your own label and price.', 'boxcart' ),
					__( 'Set a product to Inactive (draft) to hide it from the shop without deleting it.', 'boxcart' ),
					__( 'Upload a product image to make your catalogue more visually appealing. Images are lazy-loaded automatically.', 'boxcart' ),
					__( 'SKU fields only appear when SKUs are enabled in Settings > General > Products.', 'boxcart' ),
				),
				'docs'        => array(
					array(
						'label' => __( 'Products Guide', 'boxcart' ),
						'url'   => 'https://docs.boxcart.dev/products',
					),
				),
			),
			'categories'          => array(
				'title'       => __( 'Categories', 'boxcart' ),
				'description' => __( 'Organise your products into categories. Customers can filter by category on the shop page. Drag and drop to reorder how categories appear on the frontend.', 'boxcart' ),
				'tips'        => array(
					__( 'Keep category names short and clear for easy navigation.', 'boxcart' ),
					__( 'Drag rows to reorder categories — the order saves automatically and is reflected on the frontend.', 'boxcart' ),
					__( 'Click the product count to jump to a filtered product list showing only that category\'s products.', 'boxcart' ),
					__( 'Deleting a category unassigns its products but does not delete the products themselves.', 'boxcart' ),
				),
				'docs'        => array(
					array(
						'label' => __( 'Products & Categories', 'boxcart' ),
						'url'   => 'https://docs.boxcart.dev/products',
					),
				),
			),
			'location-manage'     => array(
				'title'       => __( 'Pickup Location', 'boxcart' ),
				'description' => __( 'Set the location name, address, contact details, and collection instructions that customers will see when choosing this pickup point.', 'boxcart' ),
				'tips'        => array(
					__( 'Add collection instructions (e.g., "Enter via the side gate") to help customers find your pickup point.', 'boxcart' ),
					__( 'Include a phone number and email so customers can contact you about their collection.', 'boxcart' ),
					__( 'Set a location to Inactive to temporarily hide it from the frontend without deleting it.', 'boxcart' ),
				),
				'subtabs'     => array(
					'open-days'  => array(
						'title'       => __( 'Open Days', 'boxcart' ),
						'description' => __( 'Set which days of the week this location accepts collections. Only open days will appear as options for customers when choosing a slot.', 'boxcart' ),
						'tips'        => array(
							__( 'Tick the days your location is open for collections and set the opening hours for each day.', 'boxcart' ),
							__( 'Changes here affect the weekly recurring schedule.', 'boxcart' ),
						),
					),
					'time-slots' => array(
						'title'       => __( 'Time Slots', 'boxcart' ),
						'description' => __( 'Define the collection time windows for each open day. Each slot has a start time, end time, and capacity (max orders).', 'boxcart' ),
						'tips'        => array(
							__( 'Add multiple slots per day to offer different collection windows (e.g., morning and afternoon).', 'boxcart' ),
							__( 'Set up one day, then use "Copy to other days" to give other open days the same slots, adding to theirs or replacing them.', 'boxcart' ),
							__( 'Set capacity per slot to control how many orders can be booked for each time window.', 'boxcart' ),
							__( 'Slots are shown to customers in chronological order on the checkout page.', 'boxcart' ),
						),
					),
				),
				'docs'        => array(
					array(
						'label' => __( 'Locations & Collection Guide', 'boxcart' ),
						'url'   => 'https://docs.boxcart.dev/locations-and-collection',
					),
				),
			),
			'settings-general'    => array(
				'title'       => __( 'General Settings', 'boxcart' ),
				'description' => __( 'Core configuration for your store: enable or disable pricing, set your currency format, configure tax rules, manage product display options, stock management mode, and assign your shop pages.', 'boxcart' ),
				'tips'        => array(
					__( 'The Pricing toggle is the master switch — when disabled, your shop operates without prices (order-only mode).', 'boxcart' ),
					__( 'Currency, Tax, and other pricing sub-sections only appear when pricing is enabled.', 'boxcart' ),
					__( 'If you hide prices from customers, they can only pay on collection: card payment and bank transfer aren\'t offered, because nobody can be asked to pay an amount they haven\'t seen.', 'boxcart' ),
					__( 'Use the Pages section to assign which WordPress pages display your products, basket, and checkout. The account page is optional — guest checkout works without it.', 'boxcart' ),
					__( 'Stock management can be set to None, Simple (in/out of stock), or Quantity-based tracking.', 'boxcart' ),
				),
				'subtabs'     => array(
					'currency' => array(
						'title'       => __( 'Currency Settings', 'boxcart' ),
						'description' => __( 'Set your currency code, symbol, decimal and thousand separators, and symbol position (before or after the amount).', 'boxcart' ),
						'tips'        => array(
							__( 'The currency symbol is shown to customers on the shop, basket, and checkout pages.', 'boxcart' ),
							__( 'Choose whether the symbol appears before (e.g., £10.00) or after (e.g., 10,00 €) the amount.', 'boxcart' ),
						),
					),
					'tax'      => array(
						'title'       => __( 'Tax Settings', 'boxcart' ),
						'description' => __( 'Configure tax calculation rules: enable or disable tax, set the tax rate, and choose whether prices entered in the product editor are inclusive or exclusive of tax.', 'boxcart' ),
						'tips'        => array(
							__( 'When "Prices include tax" is enabled, the price you enter for products already includes tax.', 'boxcart' ),
							__( 'Tax is calculated and displayed as a line item on the basket and checkout pages.', 'boxcart' ),
						),
					),
					'products' => array(
						'title'       => __( 'Product Settings', 'boxcart' ),
						'description' => __( 'Control product display options such as enabling SKU fields, setting the default product sort order, and choosing whether descriptions are shown on the product list.', 'boxcart' ),
						'tips'        => array(
							__( 'Enable SKU fields to add unique identifiers to each product for inventory tracking.', 'boxcart' ),
							__( 'The default sort order determines how products are ordered on the shop page when no filter is applied.', 'boxcart' ),
						),
					),
					'stock'    => array(
						'title'       => __( 'Stock Management', 'boxcart' ),
						'description' => __( 'Choose your stock management mode: None (unlimited stock), Simple (in/out of stock toggle), or Quantity (track exact stock counts with optional low-stock thresholds).', 'boxcart' ),
						'tips'        => array(
							__( 'Quantity mode lets you set stock levels per product and automatically marks items as out of stock when they reach zero.', 'boxcart' ),
							__( 'Simple mode gives you a quick in-stock/out-of-stock toggle without tracking exact quantities.', 'boxcart' ),
						),
					),
					'pages'    => array(
						'title'       => __( 'Page Setup', 'boxcart' ),
						'description' => __( 'Assign WordPress pages for your BoxCart shop pages. Products, Basket, and Checkout are required. The Account page is optional — guest checkout works without it.', 'boxcart' ),
						'tips'        => array(
							__( 'Create three required pages with the matching shortcodes: [boxcart_products], [boxcart_basket], and [boxcart_checkout].', 'boxcart' ),
							__( 'Optionally add an Account page with [boxcart_account] if you want customers to be able to sign in and view past orders. The one shortcode handles sign-in, forgotten password, and password reset — the password-reset email automatically links back to it.', 'boxcart' ),
							__( 'These assignments are used to generate correct links throughout the shop and emails.', 'boxcart' ),
						),
					),
				),
				'docs'        => array(
					array(
						'label' => __( 'Getting Started', 'boxcart' ),
						'url'   => 'https://docs.boxcart.dev/getting-started',
					),
				),
			),
			'settings-payments'   => array(
				'title'       => __( 'Payment Settings', 'boxcart' ),
				'description' => __( 'Configure how customers pay for their orders. Enable cash on collection or bank transfer. Each method can be enabled independently.', 'boxcart' ),
				'tips'        => array(
					__( 'Bank transfer orders stay in "Awaiting Payment" until you manually confirm receipt on the order detail page.', 'boxcart' ),
					__( 'You can enable multiple payment methods — customers choose at checkout.', 'boxcart' ),
				),
				'subtabs'     => array(
					'cash'          => array(
						'title'       => __( 'Cash on Collection', 'boxcart' ),
						'description' => __( 'Allow customers to pay with cash when they collect their order. No online payment is taken — the order is marked as paid when cash is received.', 'boxcart' ),
						'tips'        => array(
							__( 'Cash orders are placed immediately and marked as "Awaiting Payment" until you collect payment at the pickup point.', 'boxcart' ),
							__( 'Customise the description shown to customers at checkout to explain how cash payment works.', 'boxcart' ),
						),
					),
					'bank-transfer' => array(
						'title'       => __( 'Bank Transfer', 'boxcart' ),
						'description' => __( 'Accept payments via bank transfer (BACS). Customers receive your bank details after placing their order and pay manually. You confirm receipt on the order detail page.', 'boxcart' ),
						'tips'        => array(
							__( 'Enter your bank account details (account name, sort code, account number) so they appear on the confirmation page and email.', 'boxcart' ),
							__( 'Bank transfer orders stay in "Awaiting Payment" until you manually confirm receipt via the order detail page.', 'boxcart' ),
						),
					),
				),
				'docs'        => array(
					array(
						'label' => __( 'Payments Guide', 'boxcart' ),
						'url'   => 'https://docs.boxcart.dev/payments',
					),
				),
			),
			'settings-collection' => array(
				'title'       => __( 'Collection Settings', 'boxcart' ),
				'description' => __( 'Control how collection scheduling works: choose when orders close, define how far ahead customers can book, configure the slot selection experience, and manage availability display.', 'boxcart' ),
				'tips'        => array(
					__( 'Choose when orders close: a set number of hours before each slot (e.g., 24 hours means no same-day orders), or a set time before the collection day (e.g., 1pm the day before, for shops that pick and pack the day before).', 'boxcart' ),
					__( 'The booking window controls how far into the future customers can see available slots.', 'boxcart' ),
					__( 'Use the Slot Selection section to control how slots are presented to customers at checkout.', 'boxcart' ),
					__( 'Availability display settings let you show or hide remaining slot counts on the frontend.', 'boxcart' ),
				),
				'subtabs'     => array(
					'slot-selection' => array(
						'title'       => __( 'Slot Selection', 'boxcart' ),
						'description' => __( 'Control when customers choose their collection slot, and how much detail they see about each date and time.', 'boxcart' ),
						'tips'        => array(
							__( 'Show the slot selector on the products page if you want customers to pick a collection time before they start shopping.', 'boxcart' ),
							__( 'Hide unavailable dates if you only open a day or two a week, so customers see the dates they can book rather than a run of greyed-out ones.', 'boxcart' ),
							__( 'If you have not set a real capacity on your slots, set Slot Availability Display to "Never". BoxCart falls back to a capacity of 10, so a "slots left" count would show customers a number you never chose.', 'boxcart' ),
						),
					),
					'availability'   => array(
						'title'       => __( 'Availability Messages', 'boxcart' ),
						'description' => __( 'Customise the tooltips shown when a date cannot be booked, whether it is closed, has no time slots, or is fully booked.', 'boxcart' ),
						'tips'        => array(
							__( 'Customise the "fully booked" message shown when all slots on a given day are taken.', 'boxcart' ),
							__( 'These tooltips only appear on dates that are visible but disabled. If you turn on "Hide unavailable dates" in Slot Selection, customers never see them.', 'boxcart' ),
						),
					),
				),
				'docs'        => array(
					array(
						'label' => __( 'Locations & Collection Guide', 'boxcart' ),
						'url'   => 'https://docs.boxcart.dev/locations-and-collection',
					),
				),
			),
			'settings-orders'     => array(
				'title'       => __( 'Order Settings', 'boxcart' ),
				'description' => __( 'Configure order numbering format and the order workflow. Customise the order number prefix, set which statuses are enabled, and control how orders move through your fulfilment process.', 'boxcart' ),
				'tips'        => array(
					__( 'Set a custom order number prefix (e.g., "BC-") to make order numbers recognisable in your records.', 'boxcart' ),
					__( 'Enable or disable specific statuses in the Order Workflow section to simplify your process.', 'boxcart' ),
					__( 'Customer notes allow buyers to add special instructions at checkout — useful for substitution preferences.', 'boxcart' ),
				),
				'subtabs'     => array(
					'order-workflow' => array(
						'title'       => __( 'Status Workflow', 'boxcart' ),
						'description' => __( 'Configure which order statuses are enabled in your fulfilment process. Disable statuses you don\'t need to simplify the workflow for your team.', 'boxcart' ),
						'tips'        => array(
							__( 'Disabled statuses are hidden from the order status dropdown — orders skip them automatically.', 'boxcart' ),
							__( 'Enable customer notes at checkout to let buyers add special instructions (e.g., substitution preferences).', 'boxcart' ),
						),
					),
				),
				'docs'        => array(
					array(
						'label' => __( 'Orders Guide', 'boxcart' ),
						'url'   => 'https://docs.boxcart.dev/orders',
					),
				),
			),
			'settings-emails'     => array(
				'title'       => __( 'Email Settings', 'boxcart' ),
				'description' => __( 'Configure the emails BoxCart sends to customers and admins. Set the sender name and address, customise branding (logo, colours), manage email templates for each trigger, and preview how emails will look.', 'boxcart' ),
				'tips'        => array(
					__( 'Set your sender name to your business name so customers recognise your emails (e.g., "The Farm Shop" rather than "WordPress").', 'boxcart' ),
					__( 'Upload your logo and set brand colours in the Branding section to match your website.', 'boxcart' ),
					__( 'Each email template can be individually enabled or disabled under the Templates section.', 'boxcart' ),
					__( 'Use the Preview section to see exactly how your emails will look before customers receive them.', 'boxcart' ),
				),
				'subtabs'     => array(
					'email-branding'  => array(
						'title'       => __( 'Email Branding', 'boxcart' ),
						'description' => __( 'Customise the visual appearance of your emails. Upload a logo, set header and footer colours, and control the overall email style to match your brand.', 'boxcart' ),
						'tips'        => array(
							__( 'Upload your business logo to make emails instantly recognisable to customers.', 'boxcart' ),
							__( 'Set header and footer colours to match your website branding for a consistent look.', 'boxcart' ),
						),
					),
					'email-templates' => array(
						'title'       => __( 'Email Templates', 'boxcart' ),
						'description' => __( 'Manage the individual email templates that BoxCart sends. Each template corresponds to a trigger (e.g., new order, status change, collection reminder) and can be enabled or disabled independently.', 'boxcart' ),
						'tips'        => array(
							__( 'Disable templates you don\'t need — for example, turn off collection reminders if you don\'t use them.', 'boxcart' ),
							__( 'Admin notification emails are sent to the admin email address set in the Sender section.', 'boxcart' ),
						),
					),
					'email-preview'   => array(
						'title'       => __( 'Email Preview', 'boxcart' ),
						'description' => __( 'Preview how your emails will look with your current branding settings. Send test emails to yourself to check formatting and content before customers receive them.', 'boxcart' ),
						'tips'        => array(
							__( 'Send a test email to your own address to check how it looks in real email clients.', 'boxcart' ),
							__( 'The preview reflects your current branding settings — save changes first to see the latest version.', 'boxcart' ),
						),
					),
				),
				'docs'        => array(
					array(
						'label' => __( 'Email Settings', 'boxcart' ),
						'url'   => 'https://docs.boxcart.dev/emails',
					),
				),
			),
			'settings-styling'    => array(
				'title'       => __( 'Styling Settings', 'boxcart' ),
				'description' => __( 'Customise the look and feel of your storefront. Control colours, typography, button styles, product card layout, product display options, badges, toast notifications, grid layout, quantity selectors, and empty state messages.', 'boxcart' ),
				'tips'        => array(
					__( 'Set your primary and accent colours to match your brand — they\'re used throughout the shop, basket, and checkout.', 'boxcart' ),
					__( 'The Product Display section controls image ratios, description visibility, and category badge positioning.', 'boxcart' ),
					__( 'Customise empty state messages to match your brand voice when the basket is empty or no products match a filter.', 'boxcart' ),
				),
				'subtabs'     => array(
					'typography'      => array(
						'title'       => __( 'Typography', 'boxcart' ),
						'description' => __( 'Set the fonts used throughout the storefront. Control heading and body font families, sizes, and weights.', 'boxcart' ),
						'tips'        => array(
							__( 'Leave fonts blank to inherit your theme\'s typography for a seamless look.', 'boxcart' ),
							__( 'Font sizes affect product titles, prices, descriptions, and other shop text.', 'boxcart' ),
						),
					),
					'buttons'         => array(
						'title'       => __( 'Button Styles', 'boxcart' ),
						'description' => __( 'Customise the appearance of buttons across the shop, basket, and checkout pages. Control border radius, padding, and hover effects.', 'boxcart' ),
						'tips'        => array(
							__( 'A higher border radius creates rounder buttons; set to 0 for sharp corners.', 'boxcart' ),
							__( 'Button colours are inherited from the Colours section — adjust primary and accent colours there.', 'boxcart' ),
						),
					),
					'card-layout'     => array(
						'title'       => __( 'Card Layout', 'boxcart' ),
						'description' => __( 'Configure the product card layout used when displaying products in a grid. Control card spacing, image display, shadow, and border styles.', 'boxcart' ),
						'tips'        => array(
							__( 'Card layout works best when you have product images — it shows them prominently.', 'boxcart' ),
							__( 'Adjust the card shadow and border radius to match the visual style of your theme.', 'boxcart' ),
						),
					),
					'product-display' => array(
						'title'       => __( 'Product Display', 'boxcart' ),
						'description' => __( 'Control how individual products are presented: image aspect ratios, description visibility, and category badge positioning.', 'boxcart' ),
						'tips'        => array(
							__( 'Set the image aspect ratio to keep product images consistent across your catalogue (e.g., 1:1 square, 4:3).', 'boxcart' ),
							__( 'Decide whether short descriptions appear on the product card by default.', 'boxcart' ),
						),
					),
					'badges-toasts'   => array(
						'title'       => __( 'Badges & Toasts', 'boxcart' ),
						'description' => __( 'Configure visual feedback elements: category badges on product cards and toast notifications shown when items are added to the basket.', 'boxcart' ),
						'tips'        => array(
							__( 'Category badges help customers identify product types at a glance on the product grid.', 'boxcart' ),
							__( 'Toast notifications appear briefly when an item is added to the basket — customise their position and duration.', 'boxcart' ),
						),
					),
					'qty-selector'    => array(
						'title'       => __( 'Quantity Selector', 'boxcart' ),
						'description' => __( 'Configure the appearance and behaviour of quantity selectors on product cards and the basket page.', 'boxcart' ),
						'tips'        => array(
							__( 'Choose between increment buttons (+/−) or a direct number input for quantity selection.', 'boxcart' ),
							__( 'Set minimum and maximum quantities to control order sizes per product.', 'boxcart' ),
						),
					),
					'empty-states'    => array(
						'title'       => __( 'Empty States', 'boxcart' ),
						'description' => __( 'Customise the messages and visuals shown when lists are empty — such as an empty basket, no products matching a filter, or no search results.', 'boxcart' ),
						'tips'        => array(
							__( 'Write friendly, helpful messages that guide customers on what to do next (e.g., "Your basket is empty — browse our products!").', 'boxcart' ),
							__( 'Each empty state message can be customised independently to suit the context.', 'boxcart' ),
						),
					),
				),
				'docs'        => array(
					array(
						'label' => __( 'Styling & Customisation', 'boxcart' ),
						'url'   => 'https://docs.boxcart.dev/styling-and-customisation',
					),
				),
			),
			'settings-sidecart'   => array(
				'title'       => __( 'Sidecart Settings', 'boxcart' ),
				'description' => __( 'Configure the sliding sidecart panel that lets customers view and manage their basket without leaving the page. Control positioning, button styles, auto-open behaviour, display options, colours, and the mobile bottom bar.', 'boxcart' ),
				'tips'        => array(
					__( 'Choose which side the cart slides in from (left or right) to suit your site layout.', 'boxcart' ),
					__( 'Enable auto-open to show the sidecart automatically whenever an item is added to the basket.', 'boxcart' ),
					__( 'The mobile bar adds a persistent bottom bar on small screens showing the basket count and a "View Basket" button.', 'boxcart' ),
					__( 'Customise the sidecart colours independently from the main shop to create visual distinction.', 'boxcart' ),
				),
				'subtabs'     => array(
					'position'   => array(
						'title'       => __( 'Sidecart Position', 'boxcart' ),
						'description' => __( 'Choose which side of the screen the sidecart slides in from and control its width.', 'boxcart' ),
						'tips'        => array(
							__( 'Right-side works best for most layouts as it keeps the sidecart close to the add-to-cart buttons.', 'boxcart' ),
							__( 'Adjust the width to balance between showing enough content and not obscuring the main page.', 'boxcart' ),
						),
					),
					'buttons'    => array(
						'title'       => __( 'Sidecart Buttons', 'boxcart' ),
						'description' => __( 'Configure the floating cart button that opens the sidecart. Control its position, style, and whether to show the item count badge.', 'boxcart' ),
						'tips'        => array(
							__( 'The floating cart button shows the item count so customers always know how many items are in their basket.', 'boxcart' ),
							__( 'Position the button where it won\'t overlap with other fixed elements on your site.', 'boxcart' ),
						),
					),
					'auto-open'  => array(
						'title'       => __( 'Auto-Open', 'boxcart' ),
						'description' => __( 'Control whether the sidecart opens automatically when a customer adds an item to their basket.', 'boxcart' ),
						'tips'        => array(
							__( 'Auto-open gives immediate feedback that an item was added — great for single-product purchases.', 'boxcart' ),
							__( 'Disable auto-open if customers typically add many items in a row — they can open the cart when ready.', 'boxcart' ),
						),
					),
					'display'    => array(
						'title'       => __( 'Sidecart Display', 'boxcart' ),
						'description' => __( 'Configure what information is shown inside the sidecart panel, including item images, quantities, subtotals, and the checkout button.', 'boxcart' ),
						'tips'        => array(
							__( 'Show item images in the sidecart to help customers quickly identify what\'s in their basket.', 'boxcart' ),
							__( 'The checkout button in the sidecart takes customers directly to the checkout page.', 'boxcart' ),
						),
					),
					'colours'    => array(
						'title'       => __( 'Sidecart Colours', 'boxcart' ),
						'description' => __( 'Set custom colours for the sidecart panel independently from the main shop styling. Control background, text, button, and overlay colours.', 'boxcart' ),
						'tips'        => array(
							__( 'Use a distinct background colour to visually separate the sidecart from the main page content.', 'boxcart' ),
							__( 'The overlay colour controls the semi-transparent backdrop shown behind the sidecart.', 'boxcart' ),
						),
					),
					'mobile-bar' => array(
						'title'       => __( 'Mobile Bar', 'boxcart' ),
						'description' => __( 'Configure the persistent bottom bar shown on mobile devices. It displays the basket count and a "View Basket" button for quick access.', 'boxcart' ),
						'tips'        => array(
							__( 'The mobile bar is pinned to the bottom of the screen so it\'s always accessible on small devices.', 'boxcart' ),
							__( 'Customise the bar colours to match your brand or make it stand out for visibility.', 'boxcart' ),
						),
					),
				),
				'docs'        => array(
					array(
						'label' => __( 'Styling & Customisation', 'boxcart' ),
						'url'   => 'https://docs.boxcart.dev/styling-and-customisation',
					),
				),
			),
			'settings-customer'   => array(
				'title'       => __( 'Accounts', 'boxcart' ),
				'description' => __( 'BoxCart uses guest checkout by default — customers do not need an account to place an order. You can optionally let customers create an account on the order-confirmation page so they can sign in to track past orders. Use this tab to enable or disable account creation, require a phone number at checkout, and control how customer accounts interact with the WordPress admin area.', 'boxcart' ),
				'tips'        => array(
					__( 'Guest checkout is always on — a customer can complete an order with just their email and pickup details.', 'boxcart' ),
					__( 'When account creation is enabled, the order-confirmation page offers a "Create an account" button. Account creation uses WordPress\'s standard "set your password" email — customers never type their password into BoxCart.', 'boxcart' ),
					__( 'Turn on "Let customers register before ordering" to add a registration form on your account page, so shoppers can create an account up front rather than only after checkout. It uses WordPress\'s native registration, so BoxCart never handles the password.', 'boxcart' ),
					__( 'Returning customers sign in via the BoxCart-styled login page (the [boxcart_account] shortcode). Authentication runs through WordPress\'s core wp-login.php so every security plugin you have installed continues to apply.', 'boxcart' ),
					__( 'Requiring a phone number at checkout helps you contact customers about their collection.', 'boxcart' ),
					__( 'The Admin Access section controls whether customers (the boxcart_customer role) can see the WordPress admin or the admin bar.', 'boxcart' ),
				),
				'docs'        => array(
					array(
						'label' => __( 'Customer Accounts Guide', 'boxcart' ),
						'url'   => 'https://docs.boxcart.dev/customer-accounts',
					),
				),
			),
			'settings-misc'       => array(
				'title'       => __( 'Misc', 'boxcart' ),
				'description' => __( 'Housekeeping and advanced tools: reset all settings to their defaults, hide the Setup page once you are up and running, turn on debug logging while troubleshooting, and choose whether BoxCart removes all of its data when the plugin is deleted.', 'boxcart' ),
				'tips'        => array(
					__( 'Reset All Settings restores every option to its default. Your products, categories, orders, and locations are not affected.', 'boxcart' ),
					__( 'Hide Setup Page removes the Setup item from the menu once your store is live. You can re-enable it here at any time.', 'boxcart' ),
					__( 'Delete Data on Uninstall only takes effect when you delete the plugin, never on deactivation, so a quick update or reactivate is always safe.', 'boxcart' ),
				),
				'docs'        => array(
					array(
						'label' => __( 'Getting Started Guide', 'boxcart' ),
						'url'   => 'https://docs.boxcart.dev/getting-started',
					),
				),
			),
			'settings-shortcodes' => array(
				'title'       => __( 'Shortcodes', 'boxcart' ),
				'description' => __( 'Reference guide for all BoxCart shortcodes. Follow the Quick Start to set up your essential pages, browse the full list of available shortcodes and their attributes, or use the visual Shortcode Builder to generate shortcodes with a point-and-click interface.', 'boxcart' ),
				'tips'        => array(
					__( 'You need three pages: Shop ([boxcart_products]), Basket ([boxcart_basket]), and Checkout ([boxcart_checkout]). Add an optional My Account page with [boxcart_account] if you want customers to be able to sign in.', 'boxcart' ),
					__( 'Use the Shortcode Builder to visually configure attributes and copy the generated shortcode.', 'boxcart' ),
					__( 'The [boxcart_products] shortcode accepts attributes like category, columns, and layout to customise the display.', 'boxcart' ),
				),
				'subtabs'     => array(
					'shortcodes' => array(
						'title'       => __( 'Shortcode Reference', 'boxcart' ),
						'description' => __( 'Browse the full list of available BoxCart shortcodes with their attributes, default values, and usage examples.', 'boxcart' ),
						'tips'        => array(
							__( 'Each shortcode supports optional attributes — click to expand and see all available options.', 'boxcart' ),
							__( 'Copy shortcodes directly from this list and paste them into any WordPress page or post.', 'boxcart' ),
						),
					),
					'builder'    => array(
						'title'       => __( 'Shortcode Builder', 'boxcart' ),
						'description' => __( 'Use the visual builder to configure shortcode attributes with a point-and-click interface. Select a shortcode, adjust its settings, and copy the generated code.', 'boxcart' ),
						'tips'        => array(
							__( 'Select a shortcode from the dropdown, configure its attributes using the form controls, then click Copy.', 'boxcart' ),
							__( 'The builder preview updates live as you change settings so you can see the shortcode before copying it.', 'boxcart' ),
						),
					),
				),
				'docs'        => array(
					array(
						'label' => __( 'Shortcodes & Blocks', 'boxcart' ),
						'url'   => 'https://docs.boxcart.dev/shortcodes-and-blocks',
					),
				),
			),
			'default'             => array(
				'title'       => __( 'BoxCart Help', 'boxcart' ),
				'description' => __( 'BoxCart is a click & collect ordering system designed for farm shops, bakeries, and fresh food businesses. Use the sidebar menu to navigate between products, orders, location, and settings.', 'boxcart' ),
				'tips'        => array(
					__( 'Start by adding products and setting up at least one collection location.', 'boxcart' ),
					__( 'Use the Shortcodes tab in Settings to find the shortcodes you need for your pages.', 'boxcart' ),
					__( 'Check the documentation for detailed guides and tutorials.', 'boxcart' ),
				),
				'docs'        => array(
					array(
						'label' => __( 'Getting Started Guide', 'boxcart' ),
						'url'   => 'https://docs.boxcart.dev/getting-started',
					),
					array(
						'label' => __( 'Documentation', 'boxcart' ),
						'url'   => 'https://docs.boxcart.dev',
					),
				),
			),
		);

		/**
		 * Filter the admin help topics array. Extensions can add their own
		 * topics or subtabs by hooking this filter.
		 *
		 * @param array $topics Help topics, keyed by page identifier.
		 */
		return apply_filters( 'boxcart_admin_help_topics', $topics );
	}

	/**
	 * Render the help button and dropdown panel.
	 *
	 * @param string $page Current page identifier.
	 */
	public static function render_help_button( $page = 'default' ) {
		$help        = self::get_help_content( $page );
		$has_subtabs = ! empty( $help['subtabs'] );

		// Build sub-tab data for JS if available.
		$subtab_json = '';
		if ( $has_subtabs ) {
			$subtab_data = array();
			foreach ( $help['subtabs'] as $key => $subtab ) {
				$subtab_data[ $key ] = array(
					'title'       => $subtab['title'],
					'description' => $subtab['description'],
					'tips'        => $subtab['tips'],
				);
			}
			$subtab_json = wp_json_encode( $subtab_data );
		}
		?>
		<div class="boxcart-help"<?php echo $has_subtabs ? ' data-help-subtabs="' . esc_attr( $subtab_json ) . '"' : ''; ?> data-help-default-title="<?php echo esc_attr( $help['title'] ); ?>" data-help-default-description="<?php echo esc_attr( $help['description'] ); ?>" data-help-default-tips="<?php echo esc_attr( wp_json_encode( $help['tips'] ) ); ?>">
			<button type="button" class="boxcart-help__trigger" aria-expanded="false" aria-controls="boxcart-help-panel">
				<span class="dashicons dashicons-editor-help"></span>
				<?php esc_html_e( 'Help', 'boxcart' ); ?>
			</button>
			<div id="boxcart-help-panel" class="boxcart-help__panel" aria-hidden="true">
				<div class="boxcart-help__panel-inner">
					<!-- Page Description -->
					<div class="boxcart-help__section">
						<h3 class="boxcart-help__section-title"><?php echo esc_html( $help['title'] ); ?></h3>
						<p class="boxcart-help__description"><?php echo esc_html( $help['description'] ); ?></p>
					</div>

					<!-- Quick Tips -->
					<?php if ( ! empty( $help['tips'] ) ) : ?>
						<div class="boxcart-help__section boxcart-help__section--tips">
							<h4 class="boxcart-help__section-subtitle">
								<span class="dashicons dashicons-lightbulb"></span>
								<?php esc_html_e( 'Quick Tips', 'boxcart' ); ?>
							</h4>
							<ul class="boxcart-help__tips">
								<?php foreach ( $help['tips'] as $tip ) : ?>
									<li><?php echo esc_html( $tip ); ?></li>
								<?php endforeach; ?>
							</ul>
						</div>
					<?php endif; ?>

					<!-- Documentation Links -->
					<?php if ( ! empty( $help['docs'] ) ) : ?>
						<div class="boxcart-help__section">
							<h4 class="boxcart-help__section-subtitle">
								<span class="dashicons dashicons-book"></span>
								<?php esc_html_e( 'Documentation', 'boxcart' ); ?>
							</h4>
							<ul class="boxcart-help__links">
								<?php foreach ( $help['docs'] as $doc ) : ?>
									<li>
										<a href="<?php echo esc_url( $doc['url'] ); ?>" target="_blank" rel="noopener noreferrer">
											<?php echo esc_html( $doc['label'] ); ?>
											<span class="dashicons dashicons-external"></span>
										</a>
									</li>
								<?php endforeach; ?>
							</ul>
						</div>
					<?php endif; ?>

					<!-- Need More Help -->
					<div class="boxcart-help__section boxcart-help__section--highlight">
						<h4 class="boxcart-help__section-subtitle">
							<span class="dashicons dashicons-sos"></span>
							<?php esc_html_e( 'Need More Help?', 'boxcart' ); ?>
						</h4>
						<p class="boxcart-help__description">
							<?php esc_html_e( 'Get in touch for support or custom development services.', 'boxcart' ); ?>
						</p>
						<div class="boxcart-help__actions">
							<a href="https://boxcart.dev/support" target="_blank" rel="noopener noreferrer" class="boxcart-btn boxcart-btn--small boxcart-btn--secondary">
								<span class="dashicons dashicons-email"></span>
								<?php esc_html_e( 'Contact Support', 'boxcart' ); ?>
							</a>
							<a href="https://boxcart.dev/custom-development" target="_blank" rel="noopener noreferrer" class="boxcart-btn boxcart-btn--small boxcart-btn--outline">
								<span class="dashicons dashicons-admin-tools"></span>
								<?php esc_html_e( 'Custom Development', 'boxcart' ); ?>
							</a>
						</div>
					</div>
				</div>
			</div>
		</div>
		<?php
	}
}