From 59e68d81b2bc75c479e21dd8759bff4702d10ebc Mon Sep 17 00:00:00 2001 From: Maurice Date: Mon, 2 Nov 2026 22:46:14 +0100 Subject: [PATCH] Managed mode: satisfy the strict, loop and test ratchets - enabledPhotoProviderIds skips rows without an id instead of widening the type. - The listed events read each addon once, in parallel, not in a loop. - The narrowing test reuses the suite's service and swaps the addon answers. - PlaceContribPanel keeps its complexity by naming the standalone check. --- .../components/Admin/PlaceContribPanel.tsx | 12 +- client/src/help/registry.base.ts | 148 ++++++++++++++++++ server/src/nest/addons/addons.service.ts | 2 +- .../notification-preferences.service.ts | 17 +- .../notification-preferences.service.test.ts | 54 +++---- 5 files changed, 192 insertions(+), 41 deletions(-) create mode 100644 client/src/help/registry.base.ts diff --git a/client/src/components/Admin/PlaceContribPanel.tsx b/client/src/components/Admin/PlaceContribPanel.tsx index 645e76eb2..d4b8868af 100644 --- a/client/src/components/Admin/PlaceContribPanel.tsx +++ b/client/src/components/Admin/PlaceContribPanel.tsx @@ -61,6 +61,14 @@ function Figures({ state, t }: { state: PlaceContribState; t: TranslationFn }) { * way to take everything back. Turning it on for the first time opens the same * prompt an admin gets on the first visit, so an agreement always comes from it. */ +/** + * Standing alone (managed settings), a card that can only say "not available" + * because the operator switched sharing off is a dead end. + */ +function hiddenAlone(state: PlaceContribState, alone: boolean): boolean { + return alone && state.ineligibleReason === 'env_off'; +} + export default function PlaceContribPanel({ hideWhenSwitchedOff = false }: { hideWhenSwitchedOff?: boolean } = {}) { const { t } = useTranslation(); const toast = useToast(); @@ -70,9 +78,7 @@ export default function PlaceContribPanel({ hideWhenSwitchedOff = false }: { hid const [confirm, setConfirm] = useState<'off' | 'withdraw' | null>(null); if (!state) return null; - // Standing alone (managed settings), a card that can only say "not available" - // because the operator switched sharing off is a dead end. - if (hideWhenSwitchedOff && state.ineligibleReason === 'env_off') return null; + if (hiddenAlone(state, hideWhenSwitchedOff)) return null; const status = contribStatus(state); const agreed = state.consent.decision === 'agreed' && state.consent.termsVersion === state.termsVersion; // The prompt opens by itself once per visit while the server asks for it. diff --git a/client/src/help/registry.base.ts b/client/src/help/registry.base.ts new file mode 100644 index 000000000..4b4c60899 --- /dev/null +++ b/client/src/help/registry.base.ts @@ -0,0 +1,148 @@ +import type { HelpContext, HelpGuide } from './types' +import { dashboardContext, dashboardGuides } from './contexts/dashboard' +import { vacayContext, vacayGuides } from './contexts/vacay' +import { atlasContext, atlasGuides } from './contexts/atlas' +import { collectionsContext, collectionsGuides } from './contexts/collections' +import { journeyContext, journeyGuides, journalContext, journalGuides, studioContext, studioGuides } from './contexts/journey' +import { settingsContext, settingsTabContexts, settingsGuides } from './contexts/settings' +import { adminContext, adminTabContexts, adminGuides } from './contexts/admin' +import { tripContext, tripGuides } from './contexts/trip' +import { tripPlacesContext, tripPlacesGuides } from './contexts/tripPlaces' +import { tripDaysContext, tripDaysGuides } from './contexts/tripDays' +import { tripRoadtripContext, tripRoadtripGuides } from './contexts/tripRoadtrip' +import { tripCollabContext, tripCollabGuides } from './contexts/tripCollab' +import { tripFilesContext, tripFilesGuides } from './contexts/tripFiles' +import { tripCostsContext, tripCostsGuides } from './contexts/tripCosts' +import { tripListsContext, tripListsGuides } from './contexts/tripLists' +import { tripBookingsContext, tripBookingsGuides } from './contexts/tripBookings' +import { tripTransportsContext, tripTransportsGuides } from './contexts/tripTransports' +import { tripMapContext, tripMapGuides } from './contexts/tripMap' +import { tripDayDetailContext, tripDayDetailGuides } from './contexts/tripDayDetail' +import { tripPlaceContext, tripPlaceGuides } from './contexts/tripPlace' +import { tripToursContext, tripToursGuides } from './contexts/tripTours' +import { tripTourDetailContext, tripTourDetailGuides } from './contexts/tripTourDetail' +import { tripTourPlannerContext, tripTourPlannerGuides } from './contexts/tripTourPlanner' +import { tripTourImportContext, tripTourImportGuides } from './contexts/tripTourImport' +import { tripTourMapContext, tripTourMapGuides } from './contexts/tripTourMap' +import { tripTourStagesContext, tripTourStagesGuides } from './contexts/tripTourStages' +import { tripTourHikeContext, tripTourHikeGuides } from './contexts/tripTourHike' +import { tripTourWalkContext, tripTourWalkGuides } from './contexts/tripTourWalk' +import { tripTourBikeContext, tripTourBikeGuides } from './contexts/tripTourBike' +import { tripTourSkiContext, tripTourSkiGuides } from './contexts/tripTourSki' +import { tripTourPaddleContext, tripTourPaddleGuides } from './contexts/tripTourPaddle' +import { tripTourHorseContext, tripTourHorseGuides } from './contexts/tripTourHorse' +import { notificationsContext, notificationsGuides } from './contexts/notifications' + +/** + * Everything the help center knows, composed from one file per screen under + * `contexts/`. A screen announces which context it is with `` + * (or `useHelpContext`), and the panel looks the rest up here. + */ + +// The order of the screen switcher: the trip right under My Trips, where it is opened from. +const CONTEXT_LIST: HelpContext[] = [ + dashboardContext, + // The trip and its own screens, in the order a reader meets them: the three + // columns of the plan, the two panels that open over it, then the tabs in the + // order the tab bar has them, and the drive last because an addon decides it. + tripContext, tripDaysContext, tripPlacesContext, tripMapContext, + tripPlaceContext, tripDayDetailContext, + tripTransportsContext, tripBookingsContext, tripListsContext, tripCostsContext, tripFilesContext, tripCollabContext, + tripRoadtripContext, + // Tours: the list and the card on the Plan tab, then the Tours tab with its + // jobs and one screen per kind of tour, in the order the type picker has them. + tripToursContext, tripTourDetailContext, + tripTourPlannerContext, tripTourImportContext, tripTourMapContext, tripTourStagesContext, + tripTourHikeContext, tripTourWalkContext, tripTourBikeContext, tripTourSkiContext, tripTourPaddleContext, tripTourHorseContext, + notificationsContext, + vacayContext, atlasContext, collectionsContext, journeyContext, journalContext, studioContext, + settingsContext, ...settingsTabContexts, adminContext, ...adminTabContexts, +] +const GUIDE_LIST: HelpGuide[] = [ + ...dashboardGuides, ...vacayGuides, ...atlasGuides, ...collectionsGuides, ...journeyGuides, ...journalGuides, ...studioGuides, + ...settingsGuides, ...adminGuides, + ...tripGuides, ...tripDaysGuides, ...tripPlacesGuides, ...tripMapGuides, + ...tripPlaceGuides, ...tripDayDetailGuides, + ...tripTransportsGuides, ...tripBookingsGuides, ...tripListsGuides, ...tripCostsGuides, ...tripFilesGuides, ...tripCollabGuides, + ...tripRoadtripGuides, + ...tripToursGuides, ...tripTourDetailGuides, + ...tripTourPlannerGuides, ...tripTourImportGuides, ...tripTourMapGuides, ...tripTourStagesGuides, + ...tripTourHikeGuides, ...tripTourWalkGuides, ...tripTourBikeGuides, ...tripTourSkiGuides, ...tripTourPaddleGuides, ...tripTourHorseGuides, + ...notificationsGuides, +] + +export const HELP_CONTEXTS: ReadonlyMap = new Map(CONTEXT_LIST.map(c => [c.id, c])) +export const HELP_GUIDES: ReadonlyMap = new Map(GUIDE_LIST.map(g => [g.id, g])) + +export function getHelpContext(id: string | null | undefined): HelpContext | null { + return id ? (HELP_CONTEXTS.get(id) ?? null) : null +} + +export function getHelpGuide(id: string | null | undefined): HelpGuide | null { + return id ? (HELP_GUIDES.get(id) ?? null) : null +} + +/** The guides of a context, in the order the context lists them. */ +export function guidesFor(context: HelpContext): HelpGuide[] { + return context.guides.map(id => HELP_GUIDES.get(id)).filter((g): g is HelpGuide => g !== undefined) +} + +export function allHelpGuides(): HelpGuide[] { + return GUIDE_LIST +} + +/** Every screen that has help, in registration order, for the screen switcher. */ +export function allHelpContexts(): HelpContext[] { + return CONTEXT_LIST +} + +/** The screens that stand on their own; their sub-screens hang under them in the switcher. */ +export function topLevelHelpContexts(): HelpContext[] { + return CONTEXT_LIST.filter(c => !c.parent) +} + +/** The sub-screens of a screen, in registration order. */ +export function childHelpContexts(parentId: string): HelpContext[] { + return CONTEXT_LIST.filter(c => c.parent === parentId) +} + +/** The screen and the screens above it, outermost first, for a breadcrumb. */ +export function helpContextTrail(context: HelpContext): HelpContext[] { + const trail: HelpContext[] = [context] + let parent = context.parent ? HELP_CONTEXTS.get(context.parent) : undefined + while (parent && !trail.includes(parent)) { + trail.unshift(parent) + parent = parent.parent ? HELP_CONTEXTS.get(parent.parent) : undefined + } + return trail +} + +// ── Catalogue keys ────────────────────────────────────────────────────────── + +export const ctxKey = (id: string, part: 'title' | 'summary'): string => `help.ctx.${id}.${part}` +export const ctxBulletKey = (id: string, n: number): string => `help.ctx.${id}.bullet.${n}` +export const guideKey = (id: string, part: 'title' | 'goal' | 'result' | 'link'): string => + `help.guide.${id}.${part}` +export const guideStepKey = (id: string, n: number): string => `help.guide.${id}.step.${n}` +export const guideTipKey = (id: string, n: number): string => `help.guide.${id}.tip.${n}` + +// ── Media paths ───────────────────────────────────────────────────────────── + +/** + * Generated artwork under `public/help-media/`. WebP and WebM on purpose: the + * service worker precaches `png`, and a couple of hundred help pictures do not + * belong in every visitor's first download. + */ +const MEDIA_BASE = '/help-media' + +export const helpMedia = { + hero: (contextId: string): string => `${MEDIA_BASE}/ctx/${contextId}.webp`, + step: (guideId: string, n: number): string => `${MEDIA_BASE}/${guideId}/step-${n}.webp`, + result: (guideId: string): string => `${MEDIA_BASE}/${guideId}/result.webp`, + clip: (guideId: string, n: number): string => `${MEDIA_BASE}/${guideId}/step-${n}.loop.webp`, +} + +/** Wiki route for a doc link, with the heading anchor when the link names one. */ +export function docsRoute(link: { slug: string; anchor?: string }): string { + return `/help/${link.slug}${link.anchor ? `#${link.anchor}` : ''}` +} diff --git a/server/src/nest/addons/addons.service.ts b/server/src/nest/addons/addons.service.ts index 75fea8379..675f405a4 100644 --- a/server/src/nest/addons/addons.service.ts +++ b/server/src/nest/addons/addons.service.ts @@ -117,7 +117,7 @@ export class AddonsService { /** The photo providers users can connect: none while the journey addon is off. */ async enabledPhotoProviderIds(): Promise { if (!(await this.isAddonEnabled(ADDON_IDS.JOURNEY))) return []; - return (await this.photoProviders.listEnabled()).map((row) => row.id); + return (await this.photoProviders.listEnabled()).flatMap((row) => (row.id ? [row.id] : [])); } /** wanderer may be used: Tours is on and the admin allowed it under Tours. */ diff --git a/server/src/nest/notifications/notification-preferences.service.ts b/server/src/nest/notifications/notification-preferences.service.ts index e58fce9e2..7ea777d05 100644 --- a/server/src/nest/notifications/notification-preferences.service.ts +++ b/server/src/nest/notifications/notification-preferences.service.ts @@ -97,16 +97,15 @@ export class NotificationPreferencesService { */ private async listedEventTypes(): Promise { const photoProviders = await this.addons.enabledPhotoProviderIds(); - const addonOn = new Map(); - const on = async (id: string) => { - if (!addonOn.has(id)) addonOn.set(id, await this.addons.isAddonEnabled(id)); - return addonOn.get(id) === true; + // One read per addon, shared by the events that hang off it. + const addonOn = new Map>(); + const on = (id: string): Promise => { + if (!addonOn.has(id)) addonOn.set(id, this.addons.isAddonEnabled(id)); + return addonOn.get(id) as Promise; }; - const listed: NotifEventType[] = []; - for (const event of offeredEventTypes()) { - if (await this.featureOn(event, on, photoProviders)) listed.push(event); - } - return listed; + const events = offeredEventTypes(); + const shown = await Promise.all(events.map((event) => this.featureOn(event, on, photoProviders))); + return events.filter((_, i) => shown[i]); } private async featureOn( diff --git a/server/tests/unit/nest/notification-preferences.service.test.ts b/server/tests/unit/nest/notification-preferences.service.test.ts index b7c9f74a7..7de7544c0 100644 --- a/server/tests/unit/nest/notification-preferences.service.test.ts +++ b/server/tests/unit/nest/notification-preferences.service.test.ts @@ -86,6 +86,9 @@ const getActiveChannels = (...a: Parameters) => svc.ge const isSmtpConfigured = (...a: Parameters) => svc.isSmtpConfigured(...a); const isWebhookConfigured = (...a: Parameters) => svc.isWebhookConfigured(...a); +/** The addon answers the service sees; a test narrows them and the next one gets them back. */ +const features = everyFeatureOn(); + beforeAll(async () => { const usersRepo = await createTestUsersRepo(testDb); const settingsRepo = await createTestSettingsRepo(testDb); @@ -102,7 +105,7 @@ beforeAll(async () => { await createTestUnitOfWork(testDb), await createTestAppSettingsRepo(testDb), await createTestNotificationChannelPreferencesRepo(testDb), - everyFeatureOn(), + features, ); }); @@ -454,33 +457,28 @@ describe('instance defaults', () => { describe('listed events follow the features that are on', () => { it('NPREF-LIST-001: rows for switched-off addons and providers are not listed', async () => { - const narrow = new NotificationPreferencesService( - new MailerService( - await createTestUsersRepo(testDb), - await createTestSettingsRepo(testDb), - await createTestAppSettingsRepo(testDb), - ), - await createTestUnitOfWork(testDb), - await createTestAppSettingsRepo(testDb), - await createTestNotificationChannelPreferencesRepo(testDb), - everyFeatureOn({ - isAddonEnabled: async (id: string) => id !== 'vacay' && id !== 'collections', - isWandererAvailable: async () => false, - enabledPhotoProviderIds: async () => ['immich'], - }), - ); - const { user } = createUser(testDb); - const { event_types } = await narrow.getPreferencesMatrix(user.id, 'user'); - for (const hidden of [ - 'vacay_invite', - 'vacay_share', - 'collection_invite', - 'wanderer_source_hint', - 'synology_session_cleared', - ]) { - expect(event_types).not.toContain(hidden); + const all = { ...features }; + Object.assign(features, { + isAddonEnabled: async (id: string) => id !== 'vacay' && id !== 'collections', + isWandererAvailable: async () => false, + enabledPhotoProviderIds: async () => ['immich'], + }); + try { + const { user } = createUser(testDb); + const { event_types } = await svc.getPreferencesMatrix(user.id, 'user'); + for (const hidden of [ + 'vacay_invite', + 'vacay_share', + 'collection_invite', + 'wanderer_source_hint', + 'synology_session_cleared', + ]) { + expect(event_types).not.toContain(hidden); + } + expect(event_types).toContain('photos_shared'); + expect(event_types).toContain('trip_invite'); + } finally { + Object.assign(features, all); } - expect(event_types).toContain('photos_shared'); - expect(event_types).toContain('trip_invite'); }); });