feat: add hero image focal point picker with anchor positioning (#162)

Add interactive focal point picker for hero images, allowing precise
crop positioning via click or preset buttons (top/center/bottom).
Includes backend validation, migrations, and gallery rendering support.

backend/migrations/core/066_add_hero_anchor_and_category_hero.js

@@ -0,0 +1,48 @@
+/**
+ * Migration: Add hero image anchor position and category-specific hero images
+ *
+ * Issue #162: Add hero_image_anchor column to events table for controlling
+ *             how hero images are cropped (top/center/bottom)
+ *
+ * Issue #163: Add hero_photo_id column to photo_categories table for
+ *             category-specific hero images
+ */
+
+exports.up = async function(knex) {
+  // Add hero_image_anchor to events table (Issue #162)
+  const hasHeroAnchor = await knex.schema.hasColumn('events', 'hero_image_anchor');
+  if (!hasHeroAnchor) {
+    await knex.schema.alterTable('events', function(table) {
+      // Values: 'top', 'center', 'bottom' - defaults to 'center' for backward compatibility
+      table.string('hero_image_anchor', 10).defaultTo('center');
+    });
+    console.log('Added hero_image_anchor column to events table');
+  }
+
+  // Add hero_photo_id to photo_categories table (Issue #163)
+  const hasCategoryHero = await knex.schema.hasColumn('photo_categories', 'hero_photo_id');
+  if (!hasCategoryHero) {
+    await knex.schema.alterTable('photo_categories', function(table) {
+      table.integer('hero_photo_id').references('id').inTable('photos').onDelete('SET NULL');
+    });
+    console.log('Added hero_photo_id column to photo_categories table');
+  }
+};
+
+exports.down = async function(knex) {
+  // Remove hero_image_anchor from events table
+  const hasHeroAnchor = await knex.schema.hasColumn('events', 'hero_image_anchor');
+  if (hasHeroAnchor) {
+    await knex.schema.alterTable('events', function(table) {
+      table.dropColumn('hero_image_anchor');
+    });
+  }
+
+  // Remove hero_photo_id from photo_categories table
+  const hasCategoryHero = await knex.schema.hasColumn('photo_categories', 'hero_photo_id');
+  if (hasCategoryHero) {
+    await knex.schema.alterTable('photo_categories', function(table) {
+      table.dropColumn('hero_photo_id');
+    });
+  }
+};

backend/migrations/core/067_expand_hero_image_anchor.js

@@ -0,0 +1,32 @@
+/**
+ * Migration: Expand hero_image_anchor column to support focal point percentages
+ *
+ * Changes string(10) to string(20) so values like "100% 100%" (9 chars) fit
+ * with room to spare. Existing 'top', 'center', 'bottom' values are preserved.
+ */
+
+exports.up = async function(knex) {
+  const hasColumn = await knex.schema.hasColumn('events', 'hero_image_anchor');
+  if (!hasColumn) {
+    // Column doesn't exist yet – nothing to expand
+    return;
+  }
+
+  // SQLite doesn't truly support ALTER COLUMN, but Knex handles the
+  // rebuild-table strategy internally when we call alterTable.
+  await knex.schema.alterTable('events', function(table) {
+    table.string('hero_image_anchor', 20).defaultTo('center').alter();
+  });
+  console.log('Expanded hero_image_anchor column to string(20)');
+};
+
+exports.down = async function(knex) {
+  const hasColumn = await knex.schema.hasColumn('events', 'hero_image_anchor');
+  if (!hasColumn) {
+    return;
+  }
+
+  await knex.schema.alterTable('events', function(table) {
+    table.string('hero_image_anchor', 10).defaultTo('center').alter();
+  });
+};

backend/src/routes/adminEvents.js

@@ -196,7 +196,16 @@ router.post('/', adminAuth, requirePermission('events.create'), [
   body('hero_logo_position').optional().isIn(['top', 'center', 'bottom']),
   // Header style settings (decoupled from layout)
   body('header_style').optional().isIn(['hero', 'standard', 'minimal', 'none']),
-  body('hero_divider_style').optional().isIn(['wave', 'straight', 'angle', 'curve', 'none'])
+  body('hero_divider_style').optional().isIn(['wave', 'straight', 'angle', 'curve', 'none']),
+  // Hero image anchor position (#162) – accepts legacy keywords or "X% Y%" focal point
+  body('hero_image_anchor').optional().custom((value) => {
+    if (['top', 'center', 'bottom'].includes(value)) return true;
+    if (typeof value === 'string' && /^\d{1,3}%\s+\d{1,3}%$/.test(value)) {
+      const [x, y] = value.split(/\s+/).map(v => parseInt(v));
+      if (x >= 0 && x <= 100 && y >= 0 && y <= 100) return true;
+    }
+    throw new Error('Must be top, center, bottom, or "X% Y%" (0-100)');
+  })
 ], async (req, res) => {
   try {
     logger.debug('Create event request body', { body: req.body });
@@ -242,7 +251,9 @@ router.post('/', adminAuth, requirePermission('events.create'), [
       hero_logo_position = 'top',
       // Header style settings
       header_style = 'standard',
-      hero_divider_style = 'wave'
+      hero_divider_style = 'wave',
+      // Hero image anchor position (#162)
+      hero_image_anchor = 'center'
     } = req.body;
 
     const customerName = getCustomerNameFromPayload(req.body);
@@ -385,7 +396,8 @@ router.post('/', adminAuth, requirePermission('events.create'), [
       hero_logo_size: hero_logo_size || 'medium',
       hero_logo_position: hero_logo_position || 'top',
       header_style: header_style || 'standard',
-      hero_divider_style: hero_divider_style || 'wave'
+      hero_divider_style: hero_divider_style || 'wave',
+      hero_image_anchor: hero_image_anchor || 'center'
     }).returning('id');
     
     // Handle both PostgreSQL (returns array of objects) and SQLite (returns array of IDs)
@@ -669,7 +681,16 @@ router.put('/:id', adminAuth, requirePermission('events.edit'), [
   body('hero_logo_position').optional().isIn(['top', 'center', 'bottom']),
   // Header style settings (decoupled from layout)
   body('header_style').optional().isIn(['hero', 'standard', 'minimal', 'none']),
-  body('hero_divider_style').optional().isIn(['wave', 'straight', 'angle', 'curve', 'none'])
+  body('hero_divider_style').optional().isIn(['wave', 'straight', 'angle', 'curve', 'none']),
+  // Hero image anchor position (#162) – accepts legacy keywords or "X% Y%" focal point
+  body('hero_image_anchor').optional().custom((value) => {
+    if (['top', 'center', 'bottom'].includes(value)) return true;
+    if (typeof value === 'string' && /^\d{1,3}%\s+\d{1,3}%$/.test(value)) {
+      const [x, y] = value.split(/\s+/).map(v => parseInt(v));
+      if (x >= 0 && x <= 100 && y >= 0 && y <= 100) return true;
+    }
+    throw new Error('Must be top, center, bottom, or "X% Y%" (0-100)');
+  })
 ], async (req, res) => {
   try {
     const errors = validationResult(req);

backend/src/routes/gallery.js

@@ -121,7 +121,8 @@ router.get('/:slug/info', async (req, res) => {
         'hero_logo_position',
         'hero_logo_url',
         'header_style',
-        'hero_divider_style'
+        'hero_divider_style',
+        'hero_image_anchor'
       )
       .first();
 
@@ -174,7 +175,8 @@ router.get('/:slug/info', async (req, res) => {
       hero_logo_position: event.hero_logo_position || 'top',
       hero_logo_url: event.hero_logo_url || null,
       header_style: event.header_style || 'standard',
-      hero_divider_style: event.hero_divider_style || 'wave'
+      hero_divider_style: event.hero_divider_style || 'wave',
+      hero_image_anchor: event.hero_image_anchor || 'center'
     });
   } catch (error) {
     console.error('Error fetching gallery info:', error);
@@ -365,6 +367,7 @@ router.get('/:slug/photos', verifyGalleryAccess, async (req, res) => {
         hero_logo_url: req.event.hero_logo_url || null,
         header_style: req.event.header_style || 'standard',
         hero_divider_style: req.event.hero_divider_style || 'wave',
+        hero_image_anchor: req.event.hero_image_anchor || 'center',
         ...protectionSettings
       },
       categories: categories,