Feat: additional Layer info on hover previews #1523

olzzon · 2025-09-10T07:06:40Z

About the Contributor

This PR is made on behalf of BBC

Type of Contribution

This is a feature

Current Behavior

Current it's only possible to use predefined Previews

New Behavior

By adding an optional additionalPreviewContent?: Array<PreviewContent> inside the PopupPreview in the Blueprint integration. It's possible to add additional PreviewContent to HoverPreviews via blueprints.

Example:

popUpPreview: {
					name: 'Birdie Nam Nam',
					preview: {
						type: PreviewType.VT,
						inWords: 'Inwords Adlib overide...', //pieceProps.inWords,
						outWords: '...Outwords Adlib override', //pieceProps.outWords,
					},
					additionalPreviewContent: [
						{
							type: 'script',
							script:
								'This Adlib script is not really long, but it`s here to show that you can add scripts or what ever you like',
						},
						{
							type: 'separationLine',
						},
						{
							type: 'layerInfo',
							layerType: SourceLayerType.CAMERA,
							text: ['Camera Info: It`s the Clip that should be in focus, not the host 🤩'],
							inTime: 0,
							outTime: 1000,
						},
						{
							type: 'separationLine',
						},
						{
							type: 'layerInfo',
							layerType: SourceLayerType.LOWER_THIRD,
							text: ['GFX / Lower Third / SOMEWHERE IN THE WORLD / lost in space AND time.'],
							inTime: 0,
							duration: 5000,
						},
						{
							type: 'separationLine',
						},
						{
							type: 'layerInfo',
							layerType: SourceLayerType.LOWER_THIRD,
							text: [
								'HEADLINE / GET GAMIN',
								'In this next line, you can add more details about the element, and here I`m adding a dot.',
								'And here is another line for lower third info.',
								'As many as you like',
							],
							inTime: 3000,
							duration: 'Until Next Take',
						},
					],
				},
			})

Testing

No unit test changes are needed for this PR

Affected areas

The hover preview has been restyled with the "new" Roboto Flex styling.
Mini shelf has an updated 16:9 layout.
Additional content in the hover previews is only affected if the 'additionalPreviewContent' is added in the Blueprints.

Time Frame

This is something BBC would like to have in R53

Status

PR is ready to be reviewed.
The functionality has been tested by the author.
Relevant unit tests has been added / updated.
Relevant documentation (code comments, system documentation) has been added / updated.

Co-authored-by: Jonas Hummelstrand <[email protected]>

…ings.

codecov-commenter · 2025-09-10T07:09:02Z

⚠️ Please install the to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

❌ Patch coverage is 0% with 1 line in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
...ns/pieceContentStatusUI/checkPieceContentStatus.ts	0.00%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!

…d of string.

jstarpl · 2025-09-15T09:03:43Z

packages/blueprints-integration/src/previews.ts

+export type PreviewContent =
+	| {
+			type: 'iframe'
+			href: string
+			postMessage?: any
+			dimensions?: { width: number; height: number }
+	  }
+	| {
+			type: 'image'
+			src: string
+	  }
+	| {
+			type: 'video'
+			src: string
+	  }
+	| {
+			type: 'script'
+			script?: string
+			firstWords?: string
+			lastWords?: string
+			comment?: string
+			lastModified?: number
+	  }
+	| {
+			type: 'title'
+			content: string
+	  }
+	| {
+			type: 'inOutWords'
+			in?: string
+			out: string
+	  }
+	| {
+			type: 'layerInfo'
+			layerType: SourceLayerType
+			text: Array<string>
+			inTime?: number | string
+			outTime?: number | string
+			duration?: number | string
+	  }
+	| {
+			type: 'separationLine'
+	  }
+	| {
+			type: 'data'
+			content: { key: string; value: string }[]
+	  }
+


I think with this now becoming a public interface this needs to be described more in terms what the Blueprint Developer should expect to get.

Agree, as this is an add on to the existing popupPreview implementation, are there any place where this is already documented, so I can add it there, or du you prefer it as comments in the interface definition?

As no previous documentation was found, JSDoc and comments has been added to code.

jstarpl · 2025-09-15T09:07:40Z

packages/blueprints-integration/src/previews.ts

+			inTime?: number | string
+			outTime?: number | string
+			duration?: number | string


What do these properties mean? What's the difference between outTime vs inTime + duration? I'm also somewhat unsure about making this interface this loose & bound to a particular implementation of the hoverscrub preview component/any other component using this infromation - say Presenters' Screen. Any change there would effectively require a change to blueprints integration, which we expect to be at least reasonably stable.

I'm also not a big fan of introducing terms inTime and duration - I think they somewhat overlap with expectedStart and expectedDuration? Are they the same? If that's the case, I think it would make sense to use the same names.

These are optional values for the "in", "out", "duration" labels, and used for the LayerInfo content, not necessary an expectedStart or expectedDuration calculation.
So either we should add a comment in here that explains what it is, or add it to some documentation, what do you prefer?

Comments for it's use has been added to code.

jstarpl · 2025-09-15T09:11:12Z

packages/blueprints-integration/src/previews.ts

+			out: string
+	  }
+	| {
+			type: 'layerInfo'


Is this a layerInfo or more of an "auxiliary Piece info" on a layer of given type?

I do think that calling it layerInfo makes sense, based on what it's used for.

Comments has been added to the code, to explain it's purpose

jstarpl · 2025-09-15T09:12:38Z

packages/blueprints-integration/src/previews.ts

+	| {
+			type: 'data'
+			content: { key: string; value: string }[]
+	  }


This interface specifically is very vague for a public-use interface. I think we need to make sure that it's more clear what one can expect/put into here.

Could you clarify what additional specificity you'd like for the data type?
We should definitely dig into what this does and add some documentation, currently I don't know how this feature works, or where it's being used.

Comments for it's purpose has been added to code.

jstarpl · 2025-09-15T09:13:32Z

packages/webui/src/client/ui/PreviewPopUp/Previews/LayerInfoPreview.tsx

+					&nbsp;{' '}
+					{content.outTime !== undefined && (
+						<>
+							<span className="label">{t('OUT')}: </span>


I don't think we should have stylistic capitalization as a part of the Translatable string. Seems like more of a text-transform: uppercase situation? I also suspect that space at the end needs to be an   maybe?

As these are labels, should we then decide that "IN", "OUT" and "DURATION" are never translated. Or what are your thoughts and what are we doing other places?
Will look at the  

jstarpl

I feel that this is exposing a lot of internal UI mechanics to the Blueprints in a way that ties them to a very specific implementation of the preview mechanics. I see why this can be handy, but I'm worried we may be painting ourselves into a corner for the future, so I think we need to carefully consider documenting what things in the new PreviewContent interface mean, how that information can be used, etc.

olzzon · 2025-09-16T10:30:32Z

@jstarpl
This feature is made on behalf of BBC, if it needs to be done differently, please let us know, how you prefer it.

PeterC89 · 2025-11-06T12:54:51Z

@jstarpl Could you please advise on what / if any changes you'd like for this?

jstarpl · 2025-12-08T13:31:32Z

@PeterC89 Speaking for the NRK team, we do not block this from being merged. We do have opinions about the way this is implemented and we see the risk of this adding technical debt. NRK is also planning to add functionality in this area which would likely require us to tackle that tech debt and possibly break the public (Blueprint) portion of this API.

PeterC89 · 2025-12-08T22:42:50Z

@jstarpl We'd be happy to make changes if you can suggest what you'd be keen to get changed?
Especially if it helps ease transition for NRK later?

Otherwise we'll get this bought up to date with R53 and merged

jstarpl · 2025-12-10T16:39:26Z

@PeterC89 Well, I basically still stand by my original comments above, in summary:

The new public PreviewContent interface is basically a cut-and-paste of the internal Sofie UI interface, which creates a brittle binding between the Blueprint API and the Sofie GUI implementation
This in turn means that the Blueprint API becomes effectively "indirect control limited-HTML" rather than What-You-Say-Is-What-You-Mean - which is what I think most of the Blueprint API around Pieces and AdLibs is conceptualized around
String label capitalization is put into translatable strings instead of being achieved via CSS
New terms are introduced in the API (inTime, outTime) that are defined as "whatever is placed here will be visible next to a particular label in the GUI" (again, flowing from points 1 & 2, I think) and very loose in typing (number or string) and meaning (can be milliseconds or can be a custom string) without explicit justification
Existing terms ("Layer") are expanded and/or implicitly redefined (I think flowing from point 2). I think this is a problem because most of our documentation for Blueprint developers are these JSDoc fragments.

Now, I don't know enough about the User Story behind this feature (and the PR doesn't present any), so I don't know what solution will work in this particular situation to address these issues.

One solution that I can think of is keeping the PreviewContent to be internal to Web UI, and adding a new interface for the Blueprints that would then be converted to the internal one when being displayed by Web UI. I think, for example, instead of specifically exposing separationLine widgets to the Blueprint API, one could provide a grouping feature to combine multiple related metadata elements - that could then be rendered by consumers of this data however they wish - in Sofie UI's case, as a separationLine for example; but allowing for easy expansion later, such as with title properties or other UI hints. I would also propose tightening the inTime and outTime typings to follow established nomenclature for begin and end time-spans, perhaps even going as far as to say that the layerInfo is simply describing a IBlueprintPiece instance (or a subset thereof), and could just reuse a large amount of that interface.

Another alternative could be to also just allow blueprints to have "WebViews" where they could do "direct control HTML" for previews, perhaps better achieving the end goal, but without introducing a tight coupling between the Web UI implementation and Blueprints.

Again, I'm speculating a lot here, because I just don't have the context.

PeterC89 · 2025-12-10T22:02:22Z

Thanks @jstarpl, we'll take this away and have a chat internally tomorrow.

The context is that users want to be able to check the spelling and timings of CGs that are 'owned' by an AdLib item on the mini-shelf.
For example a VT may have various name CGs within it, currently there is no way to see this information without cuing the AdLib.

The goal was to provide a simple hover mechanism where additional piece information could be seen along with details. I.E. If I cue this AdLib, what is actually going to be cued?

jstarpl · 2025-12-11T10:33:08Z

@PeterC89 Yeah, so in my head, the problem is the lack of fidelity our AdLibAction provide in terms of the visibility of side-effects they will produce, stemming from their "Black Box" concept. I think that this is an architectural problem, that maybe the TSC could tackle, of how to handle that "black box" aspect while meeting the needs of the users to have reasonably high fidelity of information and confidence about what will happen once they execute an AdLibAction.

My personal stance is that this fidelity should be achieved through machine-readable means, because that then enables information re-use: one UI can display something as a list, while another can display a mini-timeline, yet another headless process can parse that information and take automated actions upon it. But perhaps this is too tall of an order, and we just need HTML viewports that the blueprints can populate. That being said, my personal opinion is that creating another, unplanned Domain Specific Langauge for populating parts of a specific UI delivers neither ease of maintenance, nor data reuse nor sufficient information fidelity (in the long view of things).

olzzon and others added 7 commits September 3, 2025 14:18

wip: additional layer info on HoverPreviews

9eff487

wip: move additionalPreviewContent inside popPpPreview content

7eb12a5

wip: LayerInfoPreview handle in,out,duration as string and numbers

a497576

wip: Hover Preview styling

0fd2a0d

wip: additionalPreviewContent css fonts

3f26c87

Co-authored-by: Jonas Hummelstrand <[email protected]>

wip: mini shelf align thumbnail

092fd52

chore: Updated hover-pop typography, plus letter case on duration str…

f526397

…ings.

olzzon marked this pull request as ready for review September 10, 2025 07:06

olzzon requested a review from a team as a code owner September 10, 2025 07:06

fix: direction rtl would move any dots from beginning of string to en…

6fece09

…d of string.

jstarpl reviewed Sep 15, 2025

View reviewed changes

doc: add comments and example for popupPreview and Preview content types

95c3942

Julusian added the Contribution from BBC Contributions sponsored by BBC (bbc.co.uk) label Oct 8, 2025

Feat: additional Layer info on hover previews #1523

Are you sure you want to change the base?

Feat: additional Layer info on hover previews #1523

Conversation

olzzon commented Sep 10, 2025

About the Contributor

Type of Contribution

Current Behavior

New Behavior

Example:

Testing

Affected areas

Time Frame

Status

Uh oh!

codecov-commenter commented Sep 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jstarpl Sep 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jstarpl Sep 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jstarpl Sep 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jstarpl left a comment

Choose a reason for hiding this comment

Uh oh!

olzzon commented Sep 16, 2025

Uh oh!

PeterC89 commented Nov 6, 2025

Uh oh!

jstarpl commented Dec 8, 2025

Uh oh!

PeterC89 commented Dec 8, 2025

Uh oh!

jstarpl commented Dec 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

PeterC89 commented Dec 10, 2025

Uh oh!

jstarpl commented Dec 11, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

codecov-commenter commented Sep 10, 2025 •

edited

Loading

jstarpl Sep 15, 2025 •

edited

Loading

jstarpl Sep 15, 2025 •

edited

Loading

jstarpl Sep 15, 2025 •

edited

Loading

jstarpl commented Dec 10, 2025 •

edited

Loading