feat(web): add social images to sessions/speakers

Author: abraham

docs/tutorials/01-configure-app.md

@@ -122,7 +122,7 @@ Turn parts of the site off in `features` in `packages/config/site.json`. Every f
 }
 ```
 
-A feature that is off has no pages, navigation entry or home page block, and its code is left out of the build. The features are `blog`, `codeOfConduct`, `demo`, `faq`, `feedback`, `forkMe`, `functions`, `gallery`, `map`, `mySchedule`, `notifications`, `partners`, `previousSpeakers`, `schedule`, `speakers`, `subscribe`, `team`, `tickets` and `videos`.
+A feature that is off has no pages, navigation entry or home page block, and its code is left out of the build. The features are `blog`, `codeOfConduct`, `demo`, `faq`, `feedback`, `forkMe`, `functions`, `gallery`, `map`, `mySchedule`, `notifications`, `partners`, `previousSpeakers`, `schedule`, `socialImages`, `speakers`, `subscribe`, `team`, `tickets` and `videos`.
 
 The build fails when:
 
@@ -137,6 +137,10 @@ With `functions` on, every Cloud Function always deploys. When its feature is of
 
 When `feedback` is off, the feedback dialog is still in the build, but nothing opens it. Bookmark buttons show only when `mySchedule` is on.
 
+`socialImages` builds a share image for each session and speaker page, which social networks and chat apps show with a link to the page. A session's image has its title, speakers, day, time and track. A speaker's image has their photo, name, company and the event's dates. Both have the logo from `packages/web/public/images/logo.svg`, the venue and the site's address, in the theme's colors and fonts. The build downloads speaker photos for them, and a photo that fails to download shows the speaker's initials, with a warning in the build output. With `socialImages` off, those pages share the first speaker's photo or `image` from `site.json`.
+
+The images come from the content at build time, like the rest of the page. After changing sessions or speakers, deploy again to update them. Each image's file name changes with what it shows, so social networks fetch the new one. To check how a page looks when shared, paste its URL into the [Facebook Sharing Debugger](https://developers.facebook.com/tools/debug/) or the [LinkedIn Post Inspector](https://www.linkedin.com/post-inspector/).
+
 The header follows the features too. Its button links to tickets until the event is over, or to the schedule otherwise. The account button shows when `mySchedule` or `feedback` is on, and the notifications bell when `notifications` is on. The footer links to the home page's subscribe band when `subscribe` is on, and shows a "Fork me on GitHub" sticker when `forkMe` is on.
 
 ## Content Security Policy

docs/tutorials/03-styling.md

@@ -99,6 +99,8 @@ The site's [Content Security Policy](01-configure-app.md#content-security-policy
 
 For font files, the build adds a fallback font with the same size, so the text does not move when the font loads. It warns when a role's files are over 150KB, and when the font has no glyphs for characters in the event name and title (verify with a font of your own).
 
+[Share images](01-configure-app.md#features) use the `display` and `body` fonts too, from `.ttf`, `.otf` or `.woff` files with a single weight, such as `"weight": 700`. They can't read `.woff2` files, variable weights such as `"300 900"`, or a font service's stylesheet, so with those they use the theme's built-in font, and the build warns.
+
 ## Tags and badges
 
 Session tag colors are set by tag name in `theme.tagColors` in `packages/config/site.json`. Name each one like the tag in lowercase, with dashes instead of spaces. Speaker badge colors are in `theme.badgeColors`.

firebase.json

@@ -66,6 +66,15 @@
             "value": "no-cache, no-store, must-revalidate"
           }
         ]
+      },
+      {
+        "source": "/social/**",
+        "headers": [
+          {
+            "key": "Cache-Control",
+            "value": "public, max-age=31536000, immutable"
+          }
+        ]
       }
     ]
   },

packages/translations/source/en.xlf

@@ -476,6 +476,12 @@
 <trans-unit id="common.loading">
   <source>Loading...</source>
 </trans-unit>
+<trans-unit id="social-image.session.alt">
+  <source><x id="0" equiv-text="${title}"/>, by <x id="1" equiv-text="${by}"/></source>
+</trans-unit>
+<trans-unit id="social-image.speaker.alt">
+  <source>Speaker at <x id="0" equiv-text="${shortName}"/></source>
+</trans-unit>
 <trans-unit id="shell.service-worker.installing">
   <source>App being installed for offline use.</source>
 </trans-unit>

packages/web/__tests__/fixtures/minimal-site/site.json

@@ -48,6 +48,7 @@
     "partners": false,
     "previousSpeakers": false,
     "schedule": false,
+    "socialImages": false,
     "speakers": false,
     "subscribe": false,
     "team": false,

packages/web/__tests__/hydration/global-setup.ts

@@ -16,15 +16,19 @@ const webRoot = fileURLToPath(new URL('../..', import.meta.url));
 
 // The pages render in Node, where `isServer` is true, as in the build. The tests run in jsdom.
 export default async function setup(project: TestProject): Promise<void> {
-  const siteConfig = resolveConfig({ paths: configPaths(webRoot), nodeEnv: 'test' });
+  const paths = configPaths(webRoot);
+  const siteConfig = resolveConfig({ paths, nodeEnv: 'test' });
   const server = await createServer({
     root: webRoot,
     configFile: false,
     logLevel: 'error',
     appType: 'custom',
     // Without a watcher, files that other global setups write cannot reload modules mid-render.
     server: { middlewareMode: true, hmr: false, ws: false, watch: null },
-    plugins: [decorators(), siteModule(siteConfig)],
+    plugins: [
+      decorators(),
+      siteModule(siteConfig, { siteDir: paths.site, publicDir: paths.public }),
+    ],
   });
   try {
     const module = (await server.ssrLoadModule('/__tests__/hydration/render-pages.ts')) as {

packages/web/build/build.smoke.test.ts

@@ -55,6 +55,9 @@ describe('a production build of a minimal site', () => {
     expect(page).toMatch(/<link href="https:\/\/minimal-site\.web\.app\/404" rel="canonical"/);
     expect(page).not.toContain('maps.googleapis.com');
     expect(page).toContain('<meta content="en" property="og:locale">');
+    expect(page).toContain(
+      '<meta content="https://minimal-site.web.app/images/social-share.jpg" property="og:image"><meta content="image/jpeg" property="og:image:type">',
+    );
     expect(page).not.toContain('<noscript>');
   });
 

packages/web/build/routes.test.ts

@@ -41,6 +41,18 @@ describe('routes', () => {
     expect(patterns).toContain('/previous-speakers');
   });
 
+  it('builds share images only when their page and socialImages are on', () => {
+    const patterns = (features: Partial<Record<Feature, boolean>>) =>
+      enabledRoutes({ ...allFeatures(true), ...features }).map(({ pattern }) => pattern);
+
+    expect(patterns({})).toContain('/social/sessions/[file].png');
+    expect(patterns({ schedule: false })).not.toContain('/social/sessions/[file].png');
+    expect(patterns({ schedule: false })).toContain('/social/speakers/[file].png');
+    expect(
+      patterns({ socialImages: false }).filter((pattern) => pattern.startsWith('/social')),
+    ).toEqual([]);
+  });
+
   it('injects the enabled routes from src/routes', () => {
     const injectRoute = vi.fn();
     const setup = routes({ ...allFeatures(false), team: true }).hooks['astro:config:setup'];

packages/web/build/routes.ts

@@ -8,8 +8,8 @@ export interface Route {
   pattern: string;
   /** In `src/routes/`. */
   entrypoint: string;
-  /** The feature the page belongs to. Pages without one always build. */
-  feature?: Feature;
+  /** The feature the page belongs to, or features that must all be on. Pages without one always build. */
+  feature?: Feature | readonly Feature[];
   /** The Firestore collection whose documents `getStaticPaths()` turns into pages. */
   content?: string;
 }
@@ -56,13 +56,25 @@ export const ROUTES: readonly Route[] = [
     feature: 'previousSpeakers',
     content: 'previousSpeakers',
   },
+  {
+    pattern: '/social/sessions/[file].png',
+    entrypoint: 'social/sessions/[file].png.ts',
+    feature: ['schedule', 'socialImages'],
+    content: 'sessions',
+  },
+  {
+    pattern: '/social/speakers/[file].png',
+    entrypoint: 'social/speakers/[file].png.ts',
+    feature: ['speakers', 'socialImages'],
+    content: 'speakers',
+  },
   { pattern: '/team', entrypoint: 'team.astro', feature: 'team' },
   { pattern: '/faq', entrypoint: 'faq.astro', feature: 'faq' },
   { pattern: '/coc', entrypoint: 'coc.astro', feature: 'codeOfConduct' },
 ];
 
 export const enabledRoutes = (features: Record<Feature, boolean>): Route[] =>
-  ROUTES.filter(({ feature }) => !feature || features[feature]);
+  ROUTES.filter(({ feature = [] }) => [feature].flat().every((name) => features[name]));
 
 /** Pages for development only, such as the design gallery. `astro build` leaves them out. */
 export const DEV_ROUTES: readonly Route[] = [{ pattern: '/design', entrypoint: 'design.astro' }];

packages/web/build/social-images-module.d.ts

@@ -0,0 +1,9 @@
+// Types for `virtual:hoverboard/social-images`, which vite-plugin-site.ts serves. tsconfig.json maps it here.
+import type { SocialImageDesign } from './social-images';
+
+export declare const fonts: SocialImageDesign['fonts'];
+export declare const colors: SocialImageDesign['colors'];
+export declare const avatarRadius: SocialImageDesign['avatarRadius'];
+export declare const logo: SocialImageDesign['logo'];
+export declare const publicDir: SocialImageDesign['publicDir'];
+export declare const designKey: SocialImageDesign['designKey'];