diff --git a/client/src/api/client.ts b/client/src/api/client.ts index f8bad6dcf..b23843bb9 100644 --- a/client/src/api/client.ts +++ b/client/src/api/client.ts @@ -691,14 +691,23 @@ export interface PluginDayScheduleItem { * visible while scrolling the itinerary. The card has three separately tintable * regions; an absent one is not tinted and renders exactly as it does with no plugin. * Server-normalized: dayIds checked against the trip, one contribution per day (first - * granted provider wins), the `tone` shorthand already resolved into the regions, - * labels sanitized + capped. Tone only — the client picks the alpha per theme. */ + * granted provider wins), the `tone` / `color` shorthands already resolved into the + * regions, labels sanitized + capped. + * + * A region carries EITHER a tone from the fixed palette or the plugin's own colour, + * never both — the server picked the winner. `*Color` is guaranteed `#rrggbb` (nothing + * else survives normalization, because it lands inside a CSS value); the client still + * owns how strongly it renders — alpha per theme and per region, lightness clamped + * into a readable band. */ export type PluginDayTintTone = 'default' | 'success' | 'warn' | 'danger' export interface PluginDayTint { pluginId: string; dayId: number; badgeTone?: PluginDayTintTone; + badgeColor?: string; headerTone?: PluginDayTintTone; + headerColor?: string; activityTone?: PluginDayTintTone; + activityColor?: string; label?: string; } diff --git a/client/src/components/Planner/DayPlanSidebar.tsx b/client/src/components/Planner/DayPlanSidebar.tsx index c1941f37a..20bee8fd8 100644 --- a/client/src/components/Planner/DayPlanSidebar.tsx +++ b/client/src/components/Planner/DayPlanSidebar.tsx @@ -34,7 +34,7 @@ import { useDayNotes } from '../../hooks/useDayNotes' import { useExchangeRates } from '../../hooks/useExchangeRates' import { RES_ICONS, getNoteIcon } from './DayPlanSidebar.constants' import { RouteConnector, HotelRouteConnector } from './DayPlanSidebarRouteConnector' -import { usePluginDaySchedule, usePluginDayTints, dayTintBackground, PluginDayScheduleRow, formatScheduleMinutes } from '../Plugins/PluginDaySchedule' +import { usePluginDaySchedule, usePluginDayTints, dayTintBackground, dayTinted, PluginDayScheduleRow, formatScheduleMinutes } from '../Plugins/PluginDaySchedule' import { MobileAddPlaceButton } from './DayPlanSidebarMobileAddPlaceButton' import { DayPlanSidebarToolbar } from './DayPlanSidebarToolbar' import { DayPlanSidebarNoteModal } from './DayPlanSidebarNoteModal' @@ -1324,8 +1324,8 @@ const DayPlanSidebar = React.memo(function DayPlanSidebar(props: DayPlanSidebarP // Resolved once per day: the header owns a background that its hover // handlers reassign imperatively, so both the base and the hover value have // to be tint-aware or the first hover-out would wipe the colour. - const headerTintBg = dayTintBackground(dayTint?.headerTone, '--day-tint-header') ?? 'transparent' - const headerTintHoverBg = dayTintBackground(dayTint?.headerTone, '--day-tint-header-hover') ?? 'var(--bg-tertiary)' + const headerTintBg = dayTintBackground(dayTint, 'header', '--day-tint-header') ?? 'transparent' + const headerTintHoverBg = dayTintBackground(dayTint, 'header', '--day-tint-header-hover') ?? 'var(--bg-tertiary)' return ( // The card wrapper stays untinted — its three regions (badge, header, @@ -1375,8 +1375,8 @@ const DayPlanSidebar = React.memo(function DayPlanSidebar(props: DayPlanSidebarP // --bg-hover so it stays the same pill component, and takes // --text-secondary: the number is 11px bold, so 4.5:1 applies // and --text-muted is already borderline on the untinted pill. - background: isSelected ? 'var(--accent)' : (dayTintBackground(dayTint?.badgeTone, '--day-tint-badge', 'var(--bg-hover)') ?? 'var(--bg-hover)'), - color: isSelected ? 'var(--accent-text)' : (dayTint?.badgeTone ? 'var(--text-secondary)' : 'var(--text-muted)'), + background: isSelected ? 'var(--accent)' : (dayTintBackground(dayTint, 'badge', '--day-tint-badge', 'var(--bg-hover)') ?? 'var(--bg-hover)'), + color: isSelected ? 'var(--accent-text)' : (dayTinted(dayTint, 'badge') ? 'var(--text-secondary)' : 'var(--text-muted)'), display: 'flex', flexDirection: 'column', alignItems: 'center', overflow: 'hidden', }}>
@@ -1500,7 +1500,7 @@ const DayPlanSidebar = React.memo(function DayPlanSidebar(props: DayPlanSidebarP
{ e.preventDefault(); const cur = dropTargetRef.current; if (draggingId && (!cur || cur.startsWith('end-'))) setDropTargetKey(`end-${day.id}`) }} onDrop={e => { e.preventDefault() diff --git a/client/src/components/Plugins/PluginDaySchedule.test.tsx b/client/src/components/Plugins/PluginDaySchedule.test.tsx index 92a81c146..f74d874d7 100644 --- a/client/src/components/Plugins/PluginDaySchedule.test.tsx +++ b/client/src/components/Plugins/PluginDaySchedule.test.tsx @@ -10,7 +10,7 @@ vi.mock('../../api/client', () => ({ pluginsApi: { daySchedule: (tripId: number | string) => daySchedule(tripId) }, })) -import { usePluginDaySchedule, formatScheduleMinutes, PluginDayScheduleRow } from './PluginDaySchedule' +import { usePluginDaySchedule, formatScheduleMinutes, PluginDayScheduleRow, dayTintBackground, dayTinted } from './PluginDaySchedule' function item(overrides: Partial = {}): PluginDayScheduleItem { return { pluginId: 'ev', id: 'i1', dayId: 1, label: 'Charging', tone: 'default', ...overrides } @@ -138,6 +138,47 @@ describe('usePluginDaySchedule', () => { }) }) +describe('dayTintBackground', () => { + it('FE-W4PDS-015: mixes a tone at the region\'s own alpha, over the caller\'s base', () => { + expect(dayTintBackground({ headerTone: 'warn' }, 'header', '--day-tint-header')) + .toBe('color-mix(in srgb, #f59e0b var(--day-tint-header), transparent)') + expect(dayTintBackground({ badgeTone: 'danger' }, 'badge', '--day-tint-badge', 'var(--bg-hover)')) + .toBe('color-mix(in srgb, #ef4444 var(--day-tint-badge), var(--bg-hover))') + }) + + it('FE-W4PDS-016: clamps a plugin\'s own colour into the theme\'s lightness band', () => { + // The plugin owns the hue and the chroma (`c h` pass through); only `l` is bounded, + // so no colour it sends can wash out on the light sidebar or vanish on the dark one. + expect(dayTintBackground({ badgeColor: '#00ff00' }, 'badge', '--day-tint-badge')) + .toBe('color-mix(in srgb, oklch(from #00ff00 clamp(var(--day-tint-l-min), l, var(--day-tint-l-max)) c h) var(--day-tint-badge), transparent)') + }) + + it('FE-W4PDS-017: paints a region\'s colour over its tone', () => { + // The server never sends both, but the precedence has to be unambiguous here too. + const bg = dayTintBackground({ badgeTone: 'danger', badgeColor: '#123456' }, 'badge', '--a') + expect(bg).toContain('#123456') + expect(bg).not.toContain('#ef4444') + }) + + it('FE-W4PDS-018: leaves an unpainted region alone so the caller keeps its own look', () => { + expect(dayTintBackground(undefined, 'header', '--day-tint-header')).toBeUndefined() + // Named elsewhere on the card, but not here — this region must stay untouched. + expect(dayTintBackground({ badgeTone: 'success' }, 'activity', '--day-tint-activity')).toBeUndefined() + }) + + it('FE-W4PDS-019: falls back to the default hex for an unknown tone', () => { + expect(dayTintBackground({ headerTone: 'nope' as 'default' }, 'header', '--a')) + .toBe('color-mix(in srgb, #4F46E5 var(--a), transparent)') + }) + + it('FE-W4PDS-020: dayTinted reports either channel, per region', () => { + expect(dayTinted({ badgeTone: 'success' }, 'badge')).toBe(true) + expect(dayTinted({ badgeColor: '#123456' }, 'badge')).toBe(true) + expect(dayTinted({ badgeColor: '#123456' }, 'header')).toBe(false) + expect(dayTinted(undefined, 'badge')).toBe(false) + }) +}) + describe('PluginDayScheduleRow', () => { it('FE-W4PDS-012: renders the duration, separator and label', () => { render() diff --git a/client/src/components/Plugins/PluginDaySchedule.tsx b/client/src/components/Plugins/PluginDaySchedule.tsx index 6187f15dd..90c8a36ff 100644 --- a/client/src/components/Plugins/PluginDaySchedule.tsx +++ b/client/src/components/Plugins/PluginDaySchedule.tsx @@ -1,6 +1,6 @@ import { useEffect, useMemo, useState } from 'react' import { Zap } from 'lucide-react' -import { pluginsApi, type PluginDayScheduleItem, type PluginDayTint, type PluginDayTintTone } from '../../api/client' +import { pluginsApi, type PluginDayScheduleItem, type PluginDayTint } from '../../api/client' /** * Host-rendered rows for the `dayScheduleProvider` plugin hook — time @@ -62,8 +62,12 @@ export function usePluginDaySchedule(tripId?: number | string | null): PluginDay }, [items]) } -/** dayId → the per-region tones (and optional tooltip) for that day's card. */ -export type PluginDayTints = Record> +/** dayId → the per-region paint (and optional tooltip) for that day's card. */ +export type PluginDayTintRegions = Omit +export type PluginDayTints = Record + +/** The three separately tintable regions of a day card. */ +export type PluginDayTintRegion = 'badge' | 'header' | 'activity' const EMPTY_TINTS: PluginDayTints = {} @@ -100,20 +104,43 @@ export function usePluginDayTints(tripId?: number | string | null): PluginDayTin }, [tints]) } -/** The `color-mix` background for one tinted region, or undefined when that region has - * no tone — in which case the caller keeps whatever it renders without plugins. +/** True when a plugin paints this region at all — the callers that change more than a + * background (the badge switches its text colour) need this without rebuilding the + * background string. */ +export function dayTinted(tint: PluginDayTintRegions | undefined, region: PluginDayTintRegion): boolean { + return Boolean(tint?.[`${region}Tone`] || tint?.[`${region}Color`]) +} + +/** A plugin's own colour, pulled into the lightness band the current theme can render. + * The plugin owns the hue and the chroma — only `l` is touched, and only when it falls + * outside the band, so an ordinary colour comes through exactly as sent. + * + * Without this, "any hex" means any plugin can paint a day nobody can read: near-white + * washes out against the light sidebar, near-black turns the dark one to mud. The band + * is a CSS variable rather than a constant here because the answer is per theme. */ +const clampLightness = (color: string) => + `oklch(from ${color} clamp(var(--day-tint-l-min), l, var(--day-tint-l-max)) c h)` + +/** The `color-mix` background for one tinted region, or undefined when no plugin paints + * it — in which case the caller keeps whatever it renders without plugins. * * `alphaVar` names a CSS custom property holding the strength, which varies per theme * AND per region: the tones are fixed hexes, so one alpha cannot serve both themes * (#4F46E5 is itself a dark colour and vanishes on a dark surface at a light theme's - * alpha), and a large region behind dense text needs a fainter tint than a small badge. */ + * alpha), and a large region behind dense text needs a fainter tint than a small badge. + * A plugin's own colour rides the same alphas — it chooses the hue, not the weight. */ export function dayTintBackground( - tone: PluginDayTintTone | undefined, + tint: PluginDayTintRegions | undefined, + region: PluginDayTintRegion, alphaVar: string, base = 'transparent', ): string | undefined { - if (!tone) return undefined - return `color-mix(in srgb, ${TONE_COLORS[tone] ?? TONE_COLORS.default} var(${alphaVar}), ${base})` + const color = tint?.[`${region}Color`] + const tone = tint?.[`${region}Tone`] + // Server-resolved: a region carries a colour or a tone, never both. + const paint = color ? clampLightness(color) : tone ? (TONE_COLORS[tone] ?? TONE_COLORS.default) : undefined + if (!paint) return undefined + return `color-mix(in srgb, ${paint} var(${alphaVar}), ${base})` } export function formatScheduleMinutes(minutes: number): string { diff --git a/client/src/index.css b/client/src/index.css index af821e157..b73747608 100644 --- a/client/src/index.css +++ b/client/src/index.css @@ -541,6 +541,19 @@ input[type="number"], input[type="time"], input[type="date"], input[type="dateti --day-tint-header-hover: 14%; --day-tint-activity: 6%; + /* The OKLCH lightness band a plugin's OWN colour is clamped into before it is mixed, + so "any hex" cannot mean "a day nobody can read". The band brackets the four tones + above (L 0.51–0.77) rather than tightening around them: an ordinary choice passes + through untouched, and a hex equal to a tone renders exactly like that tone. Only + the extremes move — here, a near-white that would otherwise wash out against the + sidebar's own near-white surfaces. + + This bounds a colour, it does not boost one: hue and chroma are never touched, so a + near-white GREY still lands as a faint tint. That is the intended trade — the + failure this must prevent is an unreadable card, not an understated one. */ + --day-tint-l-min: 0.40; + --day-tint-l-max: 0.78; + --fs-scale-title: 1; --fs-scale-subtitle: 1; --fs-scale-body: 1; @@ -637,6 +650,12 @@ input[type="number"], input[type="time"], input[type="date"], input[type="dateti --day-tint-header-hover: 20%; --day-tint-activity: 10%; + /* Shifted up, and the reason the band is per theme at all: here the failure is a + near-BLACK tint disappearing into the dark sidebar, while a pale one reads fine. + Inherited by the mobile chips too — mobile.css sets only their alpha. */ + --day-tint-l-min: 0.48; + --day-tint-l-max: 0.88; + --success: #22c55e; --success-soft: rgba(34, 197, 94, 0.15); --danger: #ef4444; --danger-soft: rgba(239, 68, 68, 0.15); --warning: #f59e0b; --warning-soft: rgba(245, 158, 11, 0.15); diff --git a/client/src/mobile/screens/trip/MTripShell.tsx b/client/src/mobile/screens/trip/MTripShell.tsx index b2d42eb50..ef20429d5 100644 --- a/client/src/mobile/screens/trip/MTripShell.tsx +++ b/client/src/mobile/screens/trip/MTripShell.tsx @@ -316,7 +316,7 @@ export default function MTripShell({ // The chip is mobile's day-number badge, so it follows badgeTone. // Inactive chips only — an inline background would otherwise beat // the active chip's bg-m-act class. - style={active ? undefined : { background: dayTintBackground(tint?.badgeTone, '--day-tint-chip') }} + style={active ? undefined : { background: dayTintBackground(tint, 'badge', '--day-tint-chip') }} className={`flex-1 whitespace-nowrap rounded-full px-3 py-[5px] text-center text-[0.75rem] font-semibold ${ active ? 'bg-m-act text-m-actfg shadow-[0_6px_16px_-6px_rgba(0,0,0,.4)]' : 'text-m-ink' }`} diff --git a/plugin-sdk/src/index.ts b/plugin-sdk/src/index.ts index 423ea0244..1a6da3360 100644 --- a/plugin-sdk/src/index.ts +++ b/plugin-sdk/src/index.ts @@ -587,24 +587,39 @@ export interface DayScheduleProvider { /** A colour the host paints into one day card in the Plan sidebar (and into that day's * mobile chip) — so a trip split into legs shows its leg membership while you scroll - * the itinerary. Tone only, never a hex: the host picks the alpha per theme AND per - * region, so the tint stays subtle and readable in both light and dark. + * the itinerary. * - * The card has three separately tintable regions. Set `tone` to colour all of them, - * or name regions individually for finer control — e.g. a bold badge marking the leg - * with the activity list left plain, so a dense day stays easy to read. */ + * Pick a `tone` from the shared palette, or send your own `#rrggbb` when four tones + * cannot keep your legs apart — a twenty-stop trip needs twenty colours. Either way + * you choose the hue and the host chooses the weight: it sets the alpha per theme and + * per region and clamps a colour's lightness into a band that reads on both the light + * and the dark sidebar. So the tint always lands as a wash behind the day, never as a + * fill, and no colour you send can make a day unreadable. Anything that is not exactly + * six hex digits is ignored (`#RGB` shorthand and CSS names included). + * + * The card has three separately tintable regions. Set `tone` / `color` to paint all of + * them, or name regions individually for finer control — e.g. a bold badge marking the + * leg with the activity list left plain, so a dense day stays easy to read. + * + * Colour is decoration, not information: pair it with `label` (and with a + * dayScheduleProvider row where it matters) so the meaning survives for anyone who + * cannot tell your legs apart by hue. */ export interface DayTintContribution { dayId: number; // must be a day of the requested trip - /** Shorthand: tints every region you do NOT name below. Omit it and only the - * regions you name are tinted. */ + /** Shorthands: paint every region you do NOT name below. Omit both and only the + * regions you name are tinted. `color` wins over `tone` at the same level. */ tone?: ContributionTone; + color?: string; // your own colour, `#rrggbb` only /** The day-number badge — the smallest, boldest mark. Also tints the mobile day chip. */ badgeTone?: ContributionTone; + badgeColor?: string; /** The day header row (number, title, date, cost). Its hover state deepens the tint. */ headerTone?: ContributionTone; + headerColor?: string; /** The expanded activity list — places, bookings and transport for the day. The * largest surface and the one behind the densest text, so it is tinted faintest. */ activityTone?: ContributionTone; + activityColor?: string; label?: string; // optional tooltip on the day (≤60 chars) } export interface DayTintProvider { diff --git a/server/src/nest/plugins/day-tints.controller.ts b/server/src/nest/plugins/day-tints.controller.ts index 11ba6973a..ef1a51d3d 100644 --- a/server/src/nest/plugins/day-tints.controller.ts +++ b/server/src/nest/plugins/day-tints.controller.ts @@ -14,8 +14,14 @@ import { stripEmoji } from './text-sanitize'; * * The card exposes three separately tintable regions — the day-number badge, the * header row, and the expanded activity list — so a plugin can mark the leg boldly on - * the badge while leaving the dense activity list plain. `tone` is the shorthand that - * fills every region a contribution does not name. + * the badge while leaving the dense activity list plain. `tone` / `color` are the + * shorthands that fill every region a contribution does not name. + * + * A region is painted by a tone from the fixed palette or by the plugin's own + * `#rrggbb` — four tones cannot keep a twenty-leg trip's days apart. The split of + * control is: the plugin picks the hue, the host picks how strongly it lands (alpha + * per theme and per region) and clamps it into a readable lightness band, so no + * contribution can produce an unreadable card in either theme. * * Why this is its own hook rather than one dayScheduleProvider item per day: that * hook is capped at MAX_ITEMS = 60 per provider, so a six-month trip would tint its @@ -32,11 +38,16 @@ type Tone = 'default' | 'success' | 'warn' | 'danger'; export interface DayTint { pluginId: string; dayId: number; - /** Per-region tones, already resolved against the contribution's `tone` shorthand. - * An absent region is not tinted and renders exactly as it does without plugins. */ + /** Per-region paint, already resolved against the contribution's shorthands. Each + * region carries EITHER a tone or a `#rrggbb` colour, never both — one region, one + * paint instruction, so the client never has to break a tie. An absent region is not + * tinted and renders exactly as it does without plugins. */ badgeTone?: Tone; + badgeColor?: string; headerTone?: Tone; + headerColor?: string; activityTone?: Tone; + activityColor?: string; /** Optional tooltip on the tinted day ("Kanazawa leg"). */ label?: string; } @@ -44,6 +55,19 @@ export interface DayTint { const TONES: ReadonlySet = new Set(['default', 'success', 'warn', 'danger']); const cap = (v: unknown, n: number): string => stripEmoji(String(v ?? '')).slice(0, n); +/** + * A plugin's own colour, or undefined for anything that is not exactly six hex digits. + * + * This is a security boundary, not input tidying. The client interpolates the value + * into a `color-mix()` inside an inline `background`, and `background` is a shorthand + * that takes a comma-separated layer list — a string closing the `color-mix(` paren + * early could append a `url(...)` layer and turn everyone viewing the trip into a + * beacon for the plugin's own server. Nothing but `#rrggbb` gets through. + */ +const HEX = /^#[0-9a-fA-F]{6}$/; +const hex = (v: unknown): string | undefined => + typeof v === 'string' && HEX.test(v) ? v.toLowerCase() : undefined; + // Bound the work, not just the output: an all-invalid raw array (no entry ever // reaching `out`) would otherwise be iterated in full. Slice up front, well above // any legitimate payload — a trip has one tint per day, and 2000 days is 5½ years. @@ -59,6 +83,39 @@ const MAX_RAW_TINTS = 2000; const region = (v: unknown): Tone | undefined => v === undefined || v === null ? undefined : (TONES.has(v as string) ? (v as Tone) : 'default'); +const named = (v: unknown): boolean => v !== undefined && v !== null; + +/** One region of the card, resolved whole — a colour, a tone, or nothing. */ +interface RegionTint { tone?: Tone; color?: string } + +/** + * Resolve one region against the contribution's `tone` / `color` shorthands, in one + * order: what the region names beats the shorthand, and a colour beats a tone at the + * same level. A colour wins because it is the more specific request — and emitting + * only the winner keeps a tie out of the payload for the client to break. + * + * A region that names a colour the host cannot use (`badgeColor: 'chartreuse'`) and + * nothing else degrades to `default` rather than letting the shorthand answer for it — + * exactly what a bogus `badgeTone` already does. The plugin overrode the shorthand on + * purpose here; it just sent junk, and a silently untinted region is the harder + * failure for a plugin author to notice. + */ +function resolveRegion( + rawTone: unknown, + rawColor: unknown, + toneShorthand: Tone | undefined, + colorShorthand: string | undefined, +): RegionTint { + const color = named(rawColor) ? hex(rawColor) : undefined; + if (color) return { color }; + const tone = region(rawTone); + if (tone) return { tone }; + if (named(rawColor)) return { tone: 'default' }; + if (colorShorthand) return { color: colorShorthand }; + if (toneShorthand) return { tone: toneShorthand }; + return {}; +} + function normalize(pluginId: string, tripDayIds: ReadonlySet, raw: unknown): DayTint[] { const list = Array.isArray(raw) ? (raw as Array>).slice(0, MAX_RAW_TINTS) : []; const out: DayTint[] = []; @@ -72,22 +129,25 @@ function normalize(pluginId: string, tripDayIds: ReadonlySet, raw: unkno if (!Number.isInteger(dayId) || !tripDayIds.has(dayId) || seen.has(dayId)) continue; seen.add(dayId); const label = cap(it.label, 60); - const shorthand = region(it.tone); - let badgeTone = region(it.badgeTone) ?? shorthand; - let headerTone = region(it.headerTone) ?? shorthand; - let activityTone = region(it.activityTone) ?? shorthand; - // An entry that names no region and carries no shorthand still means "tint this - // day" — the dayId is the payload, the colour is decoration. Give it the default - // tone everywhere rather than returning a contribution that paints nothing. - if (!badgeTone && !headerTone && !activityTone) badgeTone = headerTone = activityTone = 'default'; - out.push({ - pluginId, - dayId, - ...(badgeTone ? { badgeTone } : {}), - ...(headerTone ? { headerTone } : {}), - ...(activityTone ? { activityTone } : {}), - ...(label ? { label } : {}), - }); + const shTone = region(it.tone); + const shColor = hex(it.color); + const badge = resolveRegion(it.badgeTone, it.badgeColor, shTone, shColor); + const header = resolveRegion(it.headerTone, it.headerColor, shTone, shColor); + const activity = resolveRegion(it.activityTone, it.activityColor, shTone, shColor); + // An entry that names no region and carries no usable shorthand still means "tint + // this day" — the dayId is the payload, the colour is decoration. Give it the + // default tone everywhere rather than returning a contribution that paints nothing. + const painted = [badge, header, activity].filter((r) => r.tone || r.color); + if (painted.length === 0) badge.tone = header.tone = activity.tone = 'default'; + const tint: DayTint = { pluginId, dayId }; + if (badge.tone) tint.badgeTone = badge.tone; + if (badge.color) tint.badgeColor = badge.color; + if (header.tone) tint.headerTone = header.tone; + if (header.color) tint.headerColor = header.color; + if (activity.tone) tint.activityTone = activity.tone; + if (activity.color) tint.activityColor = activity.color; + if (label) tint.label = label; + out.push(tint); } return out; } diff --git a/server/tests/unit/plugins/day-tints.controller.test.ts b/server/tests/unit/plugins/day-tints.controller.test.ts index 877c424a9..0b77fff21 100644 --- a/server/tests/unit/plugins/day-tints.controller.test.ts +++ b/server/tests/unit/plugins/day-tints.controller.test.ts @@ -90,6 +90,63 @@ describe('DayTintsController', () => { expect(out[1]).toEqual({ pluginId: 'p1', dayId: 11, headerTone: 'default' }); }); + it('spreads a `color` shorthand across all three regions, lower-cased', async () => { + const { c } = controller(() => [{ dayId: 10, color: '#A1B2C3' }]); + const out = (await c.get('1', req(5))).tints; + expect(out[0]).toMatchObject({ badgeColor: '#a1b2c3', headerColor: '#a1b2c3', activityColor: '#a1b2c3' }); + }); + + it('gives a region exactly one paint — a colour beats a tone at the same level', async () => { + // Both set on the badge: the colour is the more specific request, and the tone + // must not ride along, or the client has a tie to break. + const { c } = controller(() => [{ dayId: 10, badgeTone: 'danger', badgeColor: '#00ff00' }]); + const out = (await c.get('1', req(5))).tints; + expect(out[0]).toEqual({ pluginId: 'p1', dayId: 10, badgeColor: '#00ff00' }); + expect(out[0].badgeTone).toBeUndefined(); + }); + + it('lets a named region override the shorthand across channels, both ways', async () => { + const { c } = controller(() => [ + { dayId: 10, color: '#112233', badgeTone: 'danger' }, // tone overrides a colour shorthand + { dayId: 11, tone: 'warn', badgeColor: '#112233' }, // colour overrides a tone shorthand + ]); + const out = (await c.get('1', req(5))).tints; + expect(out[0]).toMatchObject({ badgeTone: 'danger', headerColor: '#112233', activityColor: '#112233' }); + expect(out[0].badgeColor).toBeUndefined(); + expect(out[1]).toMatchObject({ badgeColor: '#112233', headerTone: 'warn', activityTone: 'warn' }); + }); + + it('accepts ONLY #rrggbb — a CSS colour cannot be smuggled in as a string', async () => { + // The value ends up inside a `color-mix()` in an inline `background`, which takes a + // layer list: a string that closes the paren early could append a url() layer and + // beacon every viewer of the trip. None of these may reach the client as a colour. + const evil = 'red 50%, transparent), url(https://evil.example/x.png'; + const { c } = controller(() => [ + { dayId: 10, badgeColor: evil, headerColor: 'rebeccapurple', activityColor: '#abc' }, + { dayId: 11, color: 'rgb(1,2,3)', headerColor: '#12345', activityColor: '#1234567' }, + ]); + const out = (await c.get('1', req(5))).tints; + expect(JSON.stringify(out)).not.toContain('evil.example'); + for (const t of out) { + expect(t.badgeColor).toBeUndefined(); + expect(t.headerColor).toBeUndefined(); + expect(t.activityColor).toBeUndefined(); + } + // Rejected, but the regions still asked to be tinted — they degrade like a bogus + // tone does rather than silently rendering plain. + expect(out[0]).toMatchObject({ badgeTone: 'default', headerTone: 'default', activityTone: 'default' }); + // A junk shorthand paints nothing, so the badge — which named neither channel — + // stays untinted, while the two regions that did name one degrade to `default`. + expect(out[1]).toMatchObject({ headerTone: 'default', activityTone: 'default' }); + expect(out[1].badgeTone).toBeUndefined(); + }); + + it('keeps a valid sibling when only one channel of a region is junk', async () => { + const { c } = controller(() => [{ dayId: 10, badgeColor: 'chartreuse', badgeTone: 'success' }]); + const out = (await c.get('1', req(5))).tints; + expect(out[0]).toEqual({ pluginId: 'p1', dayId: 10, badgeTone: 'success' }); + }); + it('treats an entry with no tone at all as "tint this day", default everywhere', async () => { const { c } = controller(() => [{ dayId: 10 }, { dayId: 11, tone: undefined }]); const out = (await c.get('1', req(5))).tints; diff --git a/wiki/Plugin-Cookbook.md b/wiki/Plugin-Cookbook.md index ae4612c99..68670cf48 100644 --- a/wiki/Plugin-Cookbook.md +++ b/wiki/Plugin-Cookbook.md @@ -485,7 +485,8 @@ dayScheduleProvider: { `hook:day-schedule-provider` can announce "Kanazawa begins" as a row, but it cannot make day 12 *look* like it belongs to Kanazawa. `hook:day-tint-provider` does — it colours a -day card in the Plan sidebar (and that day's mobile chip) with one of the four tones: +day card in the Plan sidebar (and that day's mobile chip), with one of the four tones or +with a colour of your own: ```js dayTintProvider: { @@ -504,6 +505,35 @@ Return **one entry per day** — the bound here is the trip's day count, not a f cap, so this stays correct on a six-month itinerary where the ≤60-item day-schedule hook would tint only the first 60 days. +#### Bring your own colour + +Four tones cannot keep a twenty-stop trip's legs apart. Send `color` instead — `#rrggbb` +only, and nothing else survives (`#abc`, `rgb(...)` and CSS names are all ignored, +because the value ends up inside a CSS colour the host builds): + +```js +// One hue per leg, from your own palette. +return days.map((d) => ({ dayId: d.id, color: legColor(d), label: legName(d) })) + +// Mix freely: your colour on the badge, a shared tone for the rest of the card. +return days.map((d) => ({ dayId: d.id, tone: 'default', badgeColor: legColor(d) })) +``` + +Each region takes `Color` alongside `Tone`. Within one region a colour +wins over a tone, and anything you name on a region beats the shorthand — so the second +example above tints the badge with your colour and the header and activity list with +`default`. + +You choose the hue; the host still chooses the weight. It sets the alpha per theme and +per region and clamps the colour's lightness into a band that reads on both the light +and the dark sidebar, so the tint always lands as a wash behind the day rather than a +fill, and no colour you send can make a day unreadable. An ordinary mid-range colour +comes through as you sent it; only the extremes (near-white, near-black) are pulled in. + +Colour is decoration, not information — pair it with `label` (and a day-schedule row +where the meaning matters) so it still works for anyone who can't tell your legs apart +by hue. + #### Tint one region instead of the whole card A day card has three separately tintable regions, and `tone` above is just the shorthand @@ -528,17 +558,16 @@ return days.map((d) => ({ dayId: d.id, headerTone: legTone(d), activityTone: ove | Field | Region | |---|---| -| `badgeTone` | the day-number badge — smallest and boldest; also the mobile day chip | -| `headerTone` | the day header row (number, title, date, cost); hovering deepens the tint | -| `activityTone` | the expanded activity list — largest, behind the densest text, tinted faintest | +| `badgeTone` / `badgeColor` | the day-number badge — smallest and boldest; also the mobile day chip | +| `headerTone` / `headerColor` | the day header row (number, title, date, cost); hovering deepens the tint | +| `activityTone` / `activityColor` | the expanded activity list — largest, behind the densest text, tinted faintest | A region you never name is not tinted and renders exactly as it does without your plugin. -Give the host a tone, never a hex: it picks the alpha per theme *and* per region, so the -tint stays subtle in both light and dark. `label` becomes the day's tooltip. A day takes -at most one contribution and it is resolved **whole** — within your list the first entry -for a day wins, and if another plugin also tints that day the first granted provider -wins outright, so days never flicker and two plugins can't each own part of one card. +`label` becomes the day's tooltip. A day takes at most one contribution and it is +resolved **whole** — within your list the first entry for a day wins, and if another +plugin also tints that day the first granted provider wins outright, so days never +flicker and two plugins can't each own part of one card. --- diff --git a/wiki/Plugin-Development.md b/wiki/Plugin-Development.md index 5183928e9..c290545c3 100644 --- a/wiki/Plugin-Development.md +++ b/wiki/Plugin-Development.md @@ -668,7 +668,7 @@ module.exports = definePlugin({ | `mapLayerProvider.getLayers(tripId, ctx)` → `MapLayerContribution[]` | `hook:map-layer-provider` | **live** — bounded vector overlays on the trip map: a computed route, a reachable-range corridor, a zone. Each layer is `{id, name?, features}` with features `{type: 'polyline'\|'polygon'\|'circle', points?/center?+radiusM?, tone?, width?, dash?, opacity?, fill?, label?}`. Styling stays in the tone palette; width (1–8), opacity (0.05–1) and radius (≤2000 km) are clamped, `dash` is an enum. Budgets per plugin: ≤4 layers, ≤150 features, ≤8000 vertices, ≤2000 vertices/shape — an oversized or partly-invalid shape is dropped whole, never truncated. Declarative only; drawn beneath TREK's own day route on both the Leaflet and GL renderers. Also `GET /api/map-layers/:tripId` | | `routeProvider.getRoute(request, ctx)` → `RouteProviderResult` | `hook:route-provider` | **live** — routes a day's stops under one of the plugin's declared `capabilities.routeProfiles` (an EV profile with charging stops, a scenic profile…). `request` is `{tripId, dayId, profile, waypoints}` (2–30 located stops in visit order); the result is `{coordinates, distance, duration, legs, viaPoints?}` and is validated **whole**: ≤10000 vertices, `legs` must be exactly `waypoints−1` entries (each `{distance, duration, note?}` — `note` ≤120 chars shows on the sidebar connector), ≤40 via points (`{lat, lng, label?, tone?, dwellSeconds?}` drawn as stops on the route line). A malformed result is discarded and the planner falls back to straight lines. **Targeted, not a fan-out**: TREK calls exactly the provider whose profile the user picked in the route toggle, with a 20 s timeout (room to call an external solver through your declared egress). `POST /api/plugin-routes/:pluginId/:profileId` | | `dayScheduleProvider.getSchedule(tripId, ctx)` → `DayScheduleContribution[]` | `hook:day-schedule-provider` | **live** — time contributions rendered into the day plan on desktop and mobile: "35 min charging at this stop", "45 min security before this flight". Each is `{id, dayId, assignmentId?/reservationId?/position?, minutes?, label, tone?}` — anchored under a place/booking row or at a day's start/end (default end). `dayId` must belong to the trip (checked server-side), `minutes` (1–1440) is shown on the row **and folded into the day's route-footer total**, `label` ≤120 chars, ≤60 items/plugin. Also `GET /api/day-schedule/:tripId` | -| `dayTintProvider.getDayTints(tripId, ctx)` → `DayTintContribution[]` | `hook:day-tint-provider` | **live** — colours painted into a day card in the Plan sidebar (and into that day's mobile chip), so a trip split into legs shows its leg membership while you scroll. Each is `{dayId, tone?, badgeTone?, headerTone?, activityTone?, label?}`. The card has **three separately tintable regions** — the day-number badge (also the mobile chip), the header row, and the expanded activity list — so a plugin can mark the leg boldly on the badge while leaving the dense activity list plain; `tone` is the shorthand that fills every region you do not name, and an unnamed region renders exactly as it does with no plugin. Tone only, never a hex: the host picks the alpha per theme **and** per region, so the tint stays subtle in light and dark and a tinted header hovers to a deeper mix of its own tone. `dayId` must belong to the trip (checked server-side), `label` ≤ 60 chars becomes the day's tooltip, raw array sliced at 2000. **A day takes at most one contribution, resolved whole**: within your own list the first entry for a day wins, and across plugins the first granted provider wins — so a day never flickers between colours, and a losing plugin cannot fill in the winner's untinted regions. Bounded by the trip's day count rather than a fixed item cap, which is why this is not `dayScheduleProvider` (≤60 items would tint only the first 60 days of a long trip). Also `GET /api/day-tints/:tripId` | +| `dayTintProvider.getDayTints(tripId, ctx)` → `DayTintContribution[]` | `hook:day-tint-provider` | **live** — colours painted into a day card in the Plan sidebar (and into that day's mobile chip), so a trip split into legs shows its leg membership while you scroll. Each is `{dayId, tone?, color?, badgeTone?, badgeColor?, headerTone?, headerColor?, activityTone?, activityColor?, label?}`. The card has **three separately tintable regions** — the day-number badge (also the mobile chip), the header row, and the expanded activity list — so a plugin can mark the leg boldly on the badge while leaving the dense activity list plain; `tone` / `color` are the shorthands that fill every region you do not name, and an unnamed region renders exactly as it does with no plugin. Paint a region with a palette tone or with your own `#rrggbb` (nothing else is accepted — the value lands inside a CSS colour); a colour beats a tone within a region, and anything a region names beats the shorthand. You choose the hue, the host chooses the weight: it sets the alpha per theme **and** per region and clamps a colour's lightness into a band that reads in both themes, so the tint stays subtle in light and dark, no contribution can make a day unreadable, and a tinted header hovers to a deeper mix of its own colour. `dayId` must belong to the trip (checked server-side), `label` ≤ 60 chars becomes the day's tooltip, raw array sliced at 2000. **A day takes at most one contribution, resolved whole**: within your own list the first entry for a day wins, and across plugins the first granted provider wins — so a day never flickers between colours, and a losing plugin cannot fill in the winner's untinted regions. Bounded by the trip's day count rather than a fixed item cap, which is why this is not `dayScheduleProvider` (≤60 items would tint only the first 60 days of a long trip). Also `GET /api/day-tints/:tripId` | | `pdfSectionProvider.getSections(tripId, ctx)` → `PdfSection[]` | `hook:pdf-section-provider` | **live** — text-only sections appended to the trip PDF export. Each is `{title, paragraphs?, table?}`; the host escapes and lays everything out itself (no markup ever reaches the document), caps counts (≤5 sections/plugin, ≤20 paragraphs, ≤8 headers, ≤50 rows) + lengths (title 120, paragraph 2000, header 60, cell 200) and clips rows to the header width. Also `GET /api/pdf-sections/:tripId` | | `atlasLayerProvider.getLayers(ctx)` → `AtlasLayer[]` | `hook:atlas-layer-provider` | **live** — country tint layers drawn over the Atlas world map (wishlists, advisories, …). **User-scoped**: the host binds the acting user, the hook takes no target parameter. Each layer is `{id, name?, countries: [{code, tone?, label?}]}`; codes must be ISO-3166 alpha-2 (uppercase-coerced), tone is enum-whitelisted, counts capped (≤3 layers/plugin, ≤300 countries/layer). Declarative only — plugin JS never runs on the map canvas. Also `GET /api/atlas-layers` | | `journalEntryProvider.getRows(entryId, ctx)` → `{ label, value?, url? }[]` | `hook:journal-entry-provider` | **live** — extra rows rendered under a journal entry card (needs the Journey addon; the entry's journey is access-checked like the journal detail routes). Same hardening as place details plus server-side normalization: ≤12 rows/plugin, label ≤60, value ≤200, url http/https/mailto-only. Also `GET /api/journal-entry-rows/:entryId` | diff --git a/wiki/Plugin-Permissions.md b/wiki/Plugin-Permissions.md index fc3fe0a81..1be61ea56 100644 --- a/wiki/Plugin-Permissions.md +++ b/wiki/Plugin-Permissions.md @@ -63,7 +63,7 @@ ungranted capability is physically unreachable**, not just disallowed. See | `hook:map-layer-provider` | Overlay bounded **vector layers** (polylines, polygons, metric circles) on the trip map via the `hooks.mapLayerProvider` provider hook | Implement `MapLayerProvider` in `hooks` — returns `{id, name?, features}[]` where a feature is `{type, points?/center?+radiusM?, tone?, width?, dash?, opacity?, fill?, label?}`. **Declarative only** — the host draws everything; styling is the tone palette plus clamped numerics (width 1–8, opacity 0.05–1, radius ≤2000 km) and a dash enum, so a layer can't impersonate core UI. Budgets per plugin: ≤4 layers / ≤150 features / ≤8000 vertices / ≤2000 vertices per shape; invalid or oversized shapes are dropped whole (never truncated); a failing provider is skipped. Drawn beneath TREK's own routes. Exposed at `GET /api/map-layers/:tripId`. | | `hook:route-provider` | Offer **routing profiles** the planner's route toggle can route days with, via the `hooks.routeProvider` provider hook | Implement `RouteProvider` in `hooks` and declare the profiles in `capabilities.routeProfiles` (max 3; each `{id, label, icon?}`). TREK calls `getRoute({tripId, dayId, profile, waypoints})` for exactly the profile the user picked — this is **targeted**, not a fan-out — with a 20 s timeout so the plugin can call an external solver through its declared egress. The result (`coordinates`, `distance`, `duration`, `legs`, `viaPoints?`) is validated whole (leg count must equal `waypoints−1`, ≤10000 vertices, ≤40 vias); anything malformed is discarded and the planner falls back to straight lines. Exposed at `POST /api/plugin-routes/:pluginId/:profileId` (member-gated per trip). | | `hook:day-schedule-provider` | Attach **time contributions** to the day plan via the `hooks.dayScheduleProvider` provider hook | Implement `DayScheduleProvider` in `hooks` — returns `{id, dayId, assignmentId?/reservationId?/position?, minutes?, label, tone?}[]`. Rows render under their anchor (a place/booking row, or a day's start/end) on desktop and mobile, and `minutes` is **folded into the day's route-footer total** — the one hook whose output feeds displayed timing, which is why minutes are clamped (1–1440) and `dayId` is checked against the trip's own days. ≤60 items per plugin, labels sanitized + capped (≤120); a failing provider is skipped. Exposed at `GET /api/day-schedule/:tripId`. | -| `hook:day-tint-provider` | Colour-code **whole days** in the day plan via the `hooks.dayTintProvider` provider hook | Implement `DayTintProvider` in `hooks` — returns `{dayId, tone?, badgeTone?, headerTone?, activityTone?, label?}[]`, one entry per day you want coloured. A day card has **three separately tintable regions** — the day-number badge (which is also the mobile day chip), the header row, and the expanded activity list — so you can mark a leg boldly on the badge and leave the dense activity list plain. `tone` is a shorthand for every region you do not name; a region you never name is not tinted at all and renders exactly as it does without your plugin. **Tone only, never a hex** — a fixed pastel would break the dark theme; the host chooses the alpha per theme and per region (a large surface behind dense text gets a fainter tint than a small badge), and a tinted header hovers to a deeper mix of its own tone instead of losing its colour. `dayId` is checked against the trip's own days, `label` (≤60) becomes the day's tooltip, the raw array is sliced at 2000. **A day takes at most one contribution, and it is resolved whole**: within one provider's list the first entry for a day wins, and across plugins the first granted provider wins — so a day can't flicker between colours, and a losing plugin can't fill in the winner's untinted regions. Unlike `hook:day-schedule-provider` there is no fixed item cap; the bound is the trip's day count, which is what makes this usable on a six-month itinerary. A failing provider is skipped. Exposed at `GET /api/day-tints/:tripId`. | +| `hook:day-tint-provider` | Colour-code **whole days** in the day plan via the `hooks.dayTintProvider` provider hook | Implement `DayTintProvider` in `hooks` — returns `{dayId, tone?, color?, badgeTone?, badgeColor?, headerTone?, headerColor?, activityTone?, activityColor?, label?}[]`, one entry per day you want coloured. A day card has **three separately tintable regions** — the day-number badge (which is also the mobile day chip), the header row, and the expanded activity list — so you can mark a leg boldly on the badge and leave the dense activity list plain. `tone` / `color` are shorthands for every region you do not name; a region you never name is not tinted at all and renders exactly as it does without your plugin. Paint a region with a palette tone or with your own colour — **`#rrggbb` only**, since the value ends up inside a CSS colour the host builds; a colour beats a tone within a region, and a region's own value beats the shorthand. **You choose the hue, the host chooses the weight**: it sets the alpha per theme and per region (a large surface behind dense text gets a fainter tint than a small badge) and clamps your colour's lightness into a band that reads on both the light and the dark sidebar, so no contribution can hand a user a day card they cannot read. A tinted header hovers to a deeper mix of its own colour instead of losing it. `dayId` is checked against the trip's own days, `label` (≤60) becomes the day's tooltip, the raw array is sliced at 2000. **A day takes at most one contribution, and it is resolved whole**: within one provider's list the first entry for a day wins, and across plugins the first granted provider wins — so a day can't flicker between colours, and a losing plugin can't fill in the winner's untinted regions. Unlike `hook:day-schedule-provider` there is no fixed item cap; the bound is the trip's day count, which is what makes this usable on a six-month itinerary. A failing provider is skipped. Exposed at `GET /api/day-tints/:tripId`. | | `geolocation:read` | Ask the HOST for the browser's live position from the plugin's sandboxed frames (`window.trek.geolocation`) | A **bridge-level** permission — it unlocks no ctx RPC method. The sandbox itself never gains the geolocation API: the host page reads `navigator.geolocation` (the browser's own site permission prompt still applies) and posts plain `{lat, lng, accuracy, heading, speed, timestamp}` data into the frame over postMessage. `get()` resolves one fix; `watch(cb)` streams updates until unsubscribed, and the host force-stops the GPS watch when the frame closes. Nothing is sent to the server — a position only reaches the plugin's server code if its own client ships it through one of its routes (visible in that route's traffic like any other call). | | `hook:table-contributor` | Contribute host-rendered **columns/actions** into a native planner view via the `hooks.tableContributor` provider hook | Implement `TableContributor` in `hooks` — returns declarative column/action leaves keyed by `entityId` (never markup). The host normalizes + bounds every field (length caps, `http`/`https`/`mailto`-only urls, enum tone/target) and renders them in the reservations, places, day, costs, packing and files views; an action opens your sandboxed frame or calls one of your routes. Also exposed at `GET /api/view-contributions/:view/:tripId`. | | `hook:pdf-section-provider` | Append text-only **sections** to the trip PDF export via the `hooks.pdfSectionProvider` provider hook | Implement `PdfSectionProvider` in `hooks` — returns `{title, paragraphs?, table?}[]` of plain strings the export escapes and lays out itself; no markup ever reaches the document. The host caps the section/paragraph/header/row counts (≤5/≤20/≤8/≤50) and every string length, and clips table rows to the header width; a failing provider is skipped. Exposed at `GET /api/pdf-sections/:tripId`. |