@molecule/app-annotation-pin-angular 0.0.0-stage → 0.0.1-stage
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +202 -0
- package/README.md +643 -2
- package/dist/annotation-layer.component.d.ts +120 -0
- package/dist/annotation-layer.component.d.ts.map +1 -0
- package/dist/annotation-layer.component.js +222 -0
- package/dist/annotation-layer.component.js.map +1 -0
- package/dist/annotation-pin.component.d.ts +183 -0
- package/dist/annotation-pin.component.d.ts.map +1 -0
- package/dist/annotation-pin.component.js +422 -0
- package/dist/annotation-pin.component.js.map +1 -0
- package/dist/css.d.ts +31 -0
- package/dist/css.d.ts.map +1 -0
- package/dist/css.js +90 -0
- package/dist/css.js.map +1 -0
- package/dist/index.d.ts +64 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +64 -0
- package/dist/index.js.map +1 -0
- package/dist/slot-dom.d.ts +51 -0
- package/dist/slot-dom.d.ts.map +1 -0
- package/dist/slot-dom.js +89 -0
- package/dist/slot-dom.js.map +1 -0
- package/dist/types.d.ts +105 -0
- package/dist/types.d.ts.map +1 -0
- package/dist/types.js +8 -0
- package/dist/types.js.map +1 -0
- package/package.json +72 -4
package/README.md
CHANGED
|
@@ -1,3 +1,644 @@
|
|
|
1
|
-
|
|
1
|
+
<!--
|
|
2
|
+
AUTO-GENERATED — DO NOT EDIT THIS FILE.
|
|
3
|
+
Generated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.
|
|
4
|
+
Edits here are overwritten on the next commit (molecule's pre-commit hook regenerates).
|
|
5
|
+
To change this document, edit the module-level JSDoc in src/index.ts.
|
|
6
|
+
Generated: 2026-11-16T15:02:00.167Z
|
|
7
|
+
-->
|
|
2
8
|
|
|
3
|
-
|
|
9
|
+
# @molecule/app-annotation-pin-angular
|
|
10
|
+
|
|
11
|
+
Angular annotation pin / hotspot overlay primitives — the Angular
|
|
12
|
+
counterpart of `@molecule/app-annotation-pin-react`: same props (React
|
|
13
|
+
names) and the same DOM for the same input, so an app switches framework by
|
|
14
|
+
changing only the package name in its imports.
|
|
15
|
+
|
|
16
|
+
Exports `<AnnotationPin>` (single click-to-toggle marker) and
|
|
17
|
+
`<AnnotationLayer>` (parent wrapper that manages many pins on a surface).
|
|
18
|
+
Reusable for 3d-model viewers, image annotations, map pins, and hotspot
|
|
19
|
+
tours.
|
|
20
|
+
|
|
21
|
+
> **Auto-generated, AI-first package reference** for the [molecule.dev](https://molecule.dev) ecosystem.
|
|
22
|
+
> It is written to be read by coding agents as much as by people, and is generated from this
|
|
23
|
+
> package's source — edit `src/index.ts` JSDoc, not this file.
|
|
24
|
+
|
|
25
|
+
## Quick Start
|
|
26
|
+
|
|
27
|
+
```ts
|
|
28
|
+
import { Component, signal } from '@angular/core'
|
|
29
|
+
import { AnnotationLayer, type Pin } from '@molecule/app-annotation-pin-angular'
|
|
30
|
+
|
|
31
|
+
@Component({
|
|
32
|
+
selector: 'app-image-annotator',
|
|
33
|
+
standalone: true,
|
|
34
|
+
imports: [AnnotationLayer],
|
|
35
|
+
template: `
|
|
36
|
+
<div
|
|
37
|
+
mol-annotation-layer
|
|
38
|
+
[pins]="pins()"
|
|
39
|
+
[activePinId]="activeId()"
|
|
40
|
+
(onPinClick)="select($event)"
|
|
41
|
+
(onSurfaceClick)="addPin($event)"
|
|
42
|
+
>
|
|
43
|
+
<img src="/floorplan.png" alt="" style="width: 100%; display: block" />
|
|
44
|
+
</div>
|
|
45
|
+
`,
|
|
46
|
+
})
|
|
47
|
+
export class ImageAnnotator {
|
|
48
|
+
readonly pins = signal<Pin[]>([])
|
|
49
|
+
readonly activeId = signal<string | null>(null)
|
|
50
|
+
|
|
51
|
+
select(id: string): void {
|
|
52
|
+
this.activeId.set(id === this.activeId() ? null : id)
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
addPin({ x, y }: { x: number; y: number }): void {
|
|
56
|
+
const id = crypto.randomUUID()
|
|
57
|
+
this.pins.update((pins) => [...pins, { id, position: { x, y }, label: pins.length + 1 }])
|
|
58
|
+
this.activeId.set(id)
|
|
59
|
+
}
|
|
60
|
+
}
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
## Type
|
|
64
|
+
|
|
65
|
+
`feature`
|
|
66
|
+
|
|
67
|
+
## Installation
|
|
68
|
+
|
|
69
|
+
```bash
|
|
70
|
+
npm install @molecule/app-annotation-pin-angular @angular/common @angular/core @angular/platform-browser @molecule/app-angular @molecule/app-ui @molecule/app-ui-angular
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
## API
|
|
74
|
+
|
|
75
|
+
### Interfaces
|
|
76
|
+
|
|
77
|
+
#### `Pin`
|
|
78
|
+
|
|
79
|
+
A single pin to display on a parent surface. `position` is in the
|
|
80
|
+
parent's coordinate space — for image / 2D-canvas overlays this is
|
|
81
|
+
normalised 0..1 (so the pin re-anchors as the surface resizes); for
|
|
82
|
+
pixel-positioned overlays callers can pass raw px values.
|
|
83
|
+
|
|
84
|
+
The label/note are pure data — components handle render only.
|
|
85
|
+
|
|
86
|
+
```typescript
|
|
87
|
+
interface Pin {
|
|
88
|
+
/** Stable identifier (used to track the marker in a change detection pass). */
|
|
89
|
+
id: string
|
|
90
|
+
/** Position in the parent surface's coordinate space (typically normalised 0..1). */
|
|
91
|
+
position: { x: number; y: number }
|
|
92
|
+
/** Short label (e.g. an index or single-word tag) shown inside the pin marker — text or a template. */
|
|
93
|
+
label?: TemplateRef<unknown> | string | number | null
|
|
94
|
+
/** Longer note body shown inside the popup when the pin is selected — text or a template. */
|
|
95
|
+
note?: TemplateRef<unknown> | string | number | null
|
|
96
|
+
}
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
#### `AnnotationPinProps`
|
|
100
|
+
|
|
101
|
+
Props accepted by `AnnotationPin` — the same props
|
|
102
|
+
`@molecule/app-annotation-pin-react` accepts. Node props (`label`, `note`)
|
|
103
|
+
are an input (text or a `TemplateRef`, since an input cannot carry a DOM
|
|
104
|
+
node directly) or projected content (`[slot=label]`, `[slot=note]`).
|
|
105
|
+
|
|
106
|
+
```typescript
|
|
107
|
+
interface AnnotationPinProps {
|
|
108
|
+
/** Position in the parent surface's coordinate space (typically normalised 0..1). */
|
|
109
|
+
position: { x: number; y: number }
|
|
110
|
+
/** Short label inside the marker — text, a template, or `[slot=label]` content. */
|
|
111
|
+
label?: TemplateRef<unknown> | string | number | null
|
|
112
|
+
/** Popup body when selected — text, a template, or `[slot=note]` content. */
|
|
113
|
+
note?: TemplateRef<unknown> | string | number | null
|
|
114
|
+
/**
|
|
115
|
+
* Whether the pin is currently selected. When `true` the popup is
|
|
116
|
+
* rendered. Selection is controlled — callers manage state in
|
|
117
|
+
* `AnnotationLayer` (or themselves) and update via `onClick`.
|
|
118
|
+
*/
|
|
119
|
+
selected?: boolean
|
|
120
|
+
/** Click handler — fires when the pin marker is clicked. */
|
|
121
|
+
onClick?: () => void
|
|
122
|
+
/**
|
|
123
|
+
* Side the popup renders on, relative to the marker. Defaults to `'right'`.
|
|
124
|
+
*/
|
|
125
|
+
popupSide?: 'top' | 'bottom' | 'left' | 'right'
|
|
126
|
+
/** Extra classes merged onto the root wrapper. */
|
|
127
|
+
className?: string
|
|
128
|
+
/**
|
|
129
|
+
* Whether `position` is normalised (0..1) — when `true` the wrapper
|
|
130
|
+
* positions itself with `%` units so pins re-anchor on resize. When
|
|
131
|
+
* `false` the wrapper uses raw `px` values. Defaults to `true`.
|
|
132
|
+
*/
|
|
133
|
+
normalised?: boolean
|
|
134
|
+
}
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
#### `AnnotationLayerProps`
|
|
138
|
+
|
|
139
|
+
Props accepted by `AnnotationLayer` — the same props
|
|
140
|
+
`@molecule/app-annotation-pin-react` accepts. The surface content is
|
|
141
|
+
projected (`<ng-content>`); there is no node prop for it.
|
|
142
|
+
|
|
143
|
+
```typescript
|
|
144
|
+
interface AnnotationLayerProps {
|
|
145
|
+
/** Pins to render on the layer. */
|
|
146
|
+
pins: Pin[]
|
|
147
|
+
/**
|
|
148
|
+
* The currently active (popup-open) pin id, or `null` for none. The
|
|
149
|
+
* layer is fully controlled — callers manage selection state.
|
|
150
|
+
*/
|
|
151
|
+
activePinId?: string | null
|
|
152
|
+
/** Called with the clicked pin id when a pin marker is clicked. */
|
|
153
|
+
onPinClick?: (pinId: string) => void
|
|
154
|
+
/**
|
|
155
|
+
* Called when the user clicks an empty area of the layer (i.e. not on
|
|
156
|
+
* a pin marker or a popup). Coordinates are in the same space as
|
|
157
|
+
* `Pin.position` — normalised 0..1 by default.
|
|
158
|
+
*/
|
|
159
|
+
onSurfaceClick?: (position: { x: number; y: number }) => void
|
|
160
|
+
/**
|
|
161
|
+
* Whether positions are normalised (0..1) — when `true` the layer
|
|
162
|
+
* computes click coordinates as fractions of its bounding box; when
|
|
163
|
+
* `false` it returns raw pixel offsets. Defaults to `true`.
|
|
164
|
+
*/
|
|
165
|
+
normalised?: boolean
|
|
166
|
+
/**
|
|
167
|
+
* Side the popup renders on, relative to its marker. Defaults to `'right'`.
|
|
168
|
+
*/
|
|
169
|
+
popupSide?: 'top' | 'bottom' | 'left' | 'right'
|
|
170
|
+
/** Extra classes merged onto the layer root. */
|
|
171
|
+
className?: string
|
|
172
|
+
/** Inline style for the layer root, merged over the layer's own. */
|
|
173
|
+
style?: Record<string, string | number>
|
|
174
|
+
}
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
### Classes
|
|
178
|
+
|
|
179
|
+
#### `AnnotationLayer`
|
|
180
|
+
|
|
181
|
+
Wrapper that manages multiple pins on a parent surface. Renders its
|
|
182
|
+
projected content (the surface — typically an `<img>`, `<canvas>`, or
|
|
183
|
+
map-tile element) and overlays each `pins[]` entry as a clickable
|
|
184
|
+
`<AnnotationPin>` marker.
|
|
185
|
+
|
|
186
|
+
The host IS the outer `<div>` (`div[mol-annotation-layer]`), matching
|
|
187
|
+
React's root exactly; the annotated surface is projected as the host's
|
|
188
|
+
default content. The layer itself carries `position: relative` so absolute
|
|
189
|
+
pin positioning works without the caller providing a wrapper.
|
|
190
|
+
|
|
191
|
+
Click behaviour:
|
|
192
|
+
|
|
193
|
+
- clicking a pin marker fires `onPinClick(pinId)`
|
|
194
|
+
- clicking empty space on the layer fires `onSurfaceClick({ x, y })`,
|
|
195
|
+
which callers typically use to add a new pin. That action lives on an
|
|
196
|
+
invisible "add annotation pin" button covering the surface: pointer
|
|
197
|
+
clicks place a pin at the click position; activating the button with a
|
|
198
|
+
keyboard (Tab to it, then Enter / Space) or assistive tech places a pin
|
|
199
|
+
at the surface centre.
|
|
200
|
+
|
|
201
|
+
This is the Angular counterpart of `@molecule/app-annotation-pin-react`.
|
|
202
|
+
|
|
203
|
+
```typescript
|
|
204
|
+
@Component({
|
|
205
|
+
selector: 'div[mol-annotation-layer]',
|
|
206
|
+
standalone: true,
|
|
207
|
+
imports: [AnnotationPin, NgStyle],
|
|
208
|
+
inputs: [
|
|
209
|
+
'pins',
|
|
210
|
+
'activePinId',
|
|
211
|
+
'onPinClick',
|
|
212
|
+
'onSurfaceClick',
|
|
213
|
+
'normalised',
|
|
214
|
+
'popupSide',
|
|
215
|
+
'className',
|
|
216
|
+
'style',
|
|
217
|
+
],
|
|
218
|
+
host: {
|
|
219
|
+
role: 'region',
|
|
220
|
+
'[attr.aria-label]': 'regionLabel()',
|
|
221
|
+
'data-mol-id': 'annotation-layer',
|
|
222
|
+
'[class]': 'classes()',
|
|
223
|
+
'[attr.style]': 'rootStyle()',
|
|
224
|
+
},
|
|
225
|
+
// prettier-ignore
|
|
226
|
+
template: `<ng-content></ng-content>@if (onSurfaceClick) {<button type="button" [attr.aria-label]="addPinLabel()" data-mol-id="annotation-layer-add-pin" (click)="handleSurfaceClick($event)" [class]="addPinClasses()" [ngStyle]="addPinStyles()"></button>}@for (pin of pins; track pin.id) {<div mol-annotation-pin [position]="pin.position" [label]="pin.label" [note]="pin.note" [selected]="activePinId === pin.id" [popupSide]="popupSide ?? 'right'" [normalised]="normalisedValue()" [onClick]="clickFor(pin)"></div>}`,
|
|
227
|
+
})
|
|
228
|
+
export class AnnotationLayer {
|
|
229
|
+
/** Pins to render on the layer. */
|
|
230
|
+
pins: Pin[] = []
|
|
231
|
+
/** The currently active (popup-open) pin id, or `null` for none. */
|
|
232
|
+
activePinId?: string | null
|
|
233
|
+
/** Called with the clicked pin id when a pin marker is clicked. */
|
|
234
|
+
onPinClick?: (pinId: string) => void
|
|
235
|
+
/** Called with the clicked position when an empty area of the layer is clicked. */
|
|
236
|
+
onSurfaceClick?: (position: { x: number; y: number }) => void
|
|
237
|
+
/** Whether positions are normalised (defaults to `true` at read time). */
|
|
238
|
+
normalised?: boolean
|
|
239
|
+
/** Side the popup renders on, relative to its marker (defaults to `'right'`). */
|
|
240
|
+
popupSide?: 'top' | 'bottom' | 'left' | 'right'
|
|
241
|
+
/** Extra classes merged onto the layer root. */
|
|
242
|
+
className?: string
|
|
243
|
+
/** Inline style for the layer root, merged over the layer's own. */
|
|
244
|
+
style?: Record<string, string | number>
|
|
245
|
+
|
|
246
|
+
/**
|
|
247
|
+
* Reactive translation, read in the injection context. Its `t` reads the
|
|
248
|
+
* locale, so the view re-renders the text on a locale switch.
|
|
249
|
+
*/
|
|
250
|
+
private readonly i18n = useTranslation()
|
|
251
|
+
|
|
252
|
+
/**
|
|
253
|
+
* The current class map.
|
|
254
|
+
* @returns The UIClassMap.
|
|
255
|
+
*/
|
|
256
|
+
cm(): UIClassMap {
|
|
257
|
+
return getClassMap()
|
|
258
|
+
}
|
|
259
|
+
|
|
260
|
+
/**
|
|
261
|
+
* Whether positions are normalised (React's `normalised = true` default).
|
|
262
|
+
* @returns The normalised flag.
|
|
263
|
+
*/
|
|
264
|
+
normalisedValue(): boolean {
|
|
265
|
+
return this.normalised ?? true
|
|
266
|
+
}
|
|
267
|
+
|
|
268
|
+
/**
|
|
269
|
+
* The layer root's class list (React's `cm.cn(className)`).
|
|
270
|
+
* @returns The class string.
|
|
271
|
+
*/
|
|
272
|
+
classes(): string {
|
|
273
|
+
return this.cm().cn(this.className)
|
|
274
|
+
}
|
|
275
|
+
|
|
276
|
+
/**
|
|
277
|
+
* The layer root's inline style (React's `rootStyle`: the caller's style wins).
|
|
278
|
+
* @returns The serialised style attribute.
|
|
279
|
+
*/
|
|
280
|
+
rootStyle(): string {
|
|
281
|
+
return styleString({
|
|
282
|
+
position: 'relative',
|
|
283
|
+
width: '100%',
|
|
284
|
+
height: '100%',
|
|
285
|
+
...(this.style ?? {}),
|
|
286
|
+
})
|
|
287
|
+
}
|
|
288
|
+
|
|
289
|
+
/**
|
|
290
|
+
* The add-pin target's class list (React's
|
|
291
|
+
* `cm.cn(cm.position('absolute'), cm.inset0, cm.cursorPointer)`).
|
|
292
|
+
* @returns The class string.
|
|
293
|
+
*/
|
|
294
|
+
addPinClasses(): string {
|
|
295
|
+
return this.cm().cn(this.cm().position('absolute'), this.cm().inset0, this.cm().cursorPointer)
|
|
296
|
+
}
|
|
297
|
+
|
|
298
|
+
/**
|
|
299
|
+
* The add-pin target's inline style — the browser's default button chrome
|
|
300
|
+
* reset (the target is invisible, not a visible control), as a style map so
|
|
301
|
+
* the CSSOM normalises it exactly as React's own inline styles do.
|
|
302
|
+
* @returns The style map.
|
|
303
|
+
*/
|
|
304
|
+
addPinStyles(): Record<string, string> {
|
|
305
|
+
return styleObject({ border: 'none', padding: 0, background: 'transparent' })
|
|
306
|
+
}
|
|
307
|
+
|
|
308
|
+
/**
|
|
309
|
+
* The layer's accessible label (React's `annotationPin.aria.layer`).
|
|
310
|
+
* @returns The label text.
|
|
311
|
+
*/
|
|
312
|
+
regionLabel(): string {
|
|
313
|
+
return this.i18n.t('annotationPin.aria.layer', {}, { defaultValue: 'Annotation layer' })
|
|
314
|
+
}
|
|
315
|
+
|
|
316
|
+
/**
|
|
317
|
+
* The add-pin target's accessible label (React's `annotationPin.aria.addPin`).
|
|
318
|
+
* @returns The label text.
|
|
319
|
+
*/
|
|
320
|
+
addPinLabel(): string {
|
|
321
|
+
return this.i18n.t('annotationPin.aria.addPin', {}, { defaultValue: 'Add annotation pin' })
|
|
322
|
+
}
|
|
323
|
+
|
|
324
|
+
/**
|
|
325
|
+
* The click handler a pin marker receives (React's
|
|
326
|
+
* `() => onPinClick?.(pin.id)`).
|
|
327
|
+
*
|
|
328
|
+
* @param pin - The pin the marker belongs to.
|
|
329
|
+
* @returns The handler.
|
|
330
|
+
*/
|
|
331
|
+
clickFor(pin: Pin): () => void {
|
|
332
|
+
return (): void => this.onPinClick?.(pin.id)
|
|
333
|
+
}
|
|
334
|
+
|
|
335
|
+
/**
|
|
336
|
+
* Computes the clicked position relative to the add-pin button's box (which
|
|
337
|
+
* covers the layer) and forwards to `onSurfaceClick`. If `normalised` is
|
|
338
|
+
* `true`, the returned coordinates are 0..1 fractions; otherwise they are
|
|
339
|
+
* raw pixel offsets.
|
|
340
|
+
*
|
|
341
|
+
* Clicks produced by keyboard activation (Enter / Space on the focused
|
|
342
|
+
* button) or assistive tech carry `detail === 0` and no pointer position —
|
|
343
|
+
* such clicks place the pin at the surface centre. Pin markers and popups
|
|
344
|
+
* never reach this handler: they stack above the button and are its
|
|
345
|
+
* siblings, so their clicks do not hit it.
|
|
346
|
+
*
|
|
347
|
+
* @param event - The originating mouse event.
|
|
348
|
+
*/
|
|
349
|
+
handleSurfaceClick(event: MouseEvent): void {
|
|
350
|
+
if (!this.onSurfaceClick) return
|
|
351
|
+
const rect = (event.currentTarget as HTMLElement).getBoundingClientRect()
|
|
352
|
+
const keyboardActivated = event.detail === 0
|
|
353
|
+
const px = keyboardActivated ? rect.width / 2 : event.clientX - rect.left
|
|
354
|
+
const py = keyboardActivated ? rect.height / 2 : event.clientY - rect.top
|
|
355
|
+
const safeRectWidth = rect.width || 1
|
|
356
|
+
const safeRectHeight = rect.height || 1
|
|
357
|
+
const x = this.normalisedValue() ? px / safeRectWidth : px
|
|
358
|
+
const y = this.normalisedValue() ? py / safeRectHeight : py
|
|
359
|
+
this.onSurfaceClick({ x, y })
|
|
360
|
+
}
|
|
361
|
+
}
|
|
362
|
+
```
|
|
363
|
+
|
|
364
|
+
#### `AnnotationPin`
|
|
365
|
+
|
|
366
|
+
A single pin marker (small circle with optional `label`) rendered at an
|
|
367
|
+
absolute position on its parent. Clicking the marker toggles its popup
|
|
368
|
+
(which shows the `note` body) via the `onClick` handler.
|
|
369
|
+
|
|
370
|
+
The host IS the outer `<div>` (`div[mol-annotation-pin]`), matching React's
|
|
371
|
+
root exactly. Node props are an input (a string or a `TemplateRef`) or
|
|
372
|
+
projected content (`[slot=label]`, `[slot=note]`).
|
|
373
|
+
|
|
374
|
+
This is the Angular counterpart of `@molecule/app-annotation-pin-react`.
|
|
375
|
+
|
|
376
|
+
```typescript
|
|
377
|
+
@Component({
|
|
378
|
+
selector: 'div[mol-annotation-pin]',
|
|
379
|
+
standalone: true,
|
|
380
|
+
imports: [NgStyle, NgTemplateOutlet],
|
|
381
|
+
inputs: [
|
|
382
|
+
'position',
|
|
383
|
+
'label',
|
|
384
|
+
'note',
|
|
385
|
+
'selected',
|
|
386
|
+
'onClick',
|
|
387
|
+
'popupSide',
|
|
388
|
+
'className',
|
|
389
|
+
'normalised',
|
|
390
|
+
],
|
|
391
|
+
host: {
|
|
392
|
+
'[class]': 'classes()',
|
|
393
|
+
'data-mol-id': 'annotation-pin',
|
|
394
|
+
'[attr.data-pin-selected]': 'selected ? "true" : "false"',
|
|
395
|
+
'[attr.style]': 'wrapperStyle()',
|
|
396
|
+
},
|
|
397
|
+
template: `<button
|
|
398
|
+
type="button"
|
|
399
|
+
(click)="handleMarkerClick($event)"
|
|
400
|
+
[attr.aria-label]="markerLabel()"
|
|
401
|
+
[attr.aria-expanded]="selected ? 'true' : 'false'"
|
|
402
|
+
data-mol-id="annotation-pin-marker"
|
|
403
|
+
[class]="markerClasses()"
|
|
404
|
+
[ngStyle]="markerStyles()"
|
|
405
|
+
>
|
|
406
|
+
<span [class]="labelClasses()" data-mol-id="annotation-pin-label" [attr.style]="labelStyle()">
|
|
407
|
+
@if (labelTemplate(); as tpl) {
|
|
408
|
+
<ng-container [ngTemplateOutlet]="tpl" />
|
|
409
|
+
} @else if (labelText() !== null) {
|
|
410
|
+
{{ labelText() }}
|
|
411
|
+
}
|
|
412
|
+
<span #labelSlot data-parity-unwrap><ng-content select="[slot=label]"></ng-content></span
|
|
413
|
+
></span>
|
|
414
|
+
</button>
|
|
415
|
+
<div
|
|
416
|
+
#popupEl
|
|
417
|
+
role="dialog"
|
|
418
|
+
[attr.aria-label]="popupLabel()"
|
|
419
|
+
data-mol-id="annotation-pin-popup"
|
|
420
|
+
[attr.data-popup-side]="popupSide ?? 'right'"
|
|
421
|
+
[class]="popupClasses()"
|
|
422
|
+
[attr.style]="popupStyle()"
|
|
423
|
+
>
|
|
424
|
+
<div data-mol-id="annotation-pin-popup-body">
|
|
425
|
+
@if (noteTemplate(); as tpl) {
|
|
426
|
+
<ng-container [ngTemplateOutlet]="tpl" />
|
|
427
|
+
} @else if (noteText() !== null) {
|
|
428
|
+
{{ noteText() }}
|
|
429
|
+
}
|
|
430
|
+
<span #noteSlot data-parity-unwrap><ng-content select="[slot=note]"></ng-content></span
|
|
431
|
+
><span #emptyNoteEl data-mol-id="annotation-pin-popup-empty">{{ emptyNote() }}</span>
|
|
432
|
+
</div>
|
|
433
|
+
</div>`,
|
|
434
|
+
})
|
|
435
|
+
export class AnnotationPin implements AfterViewInit, DoCheck {
|
|
436
|
+
position!: { x: number; y: number }
|
|
437
|
+
label?: TemplateRef<unknown> | string | number | null
|
|
438
|
+
note?: TemplateRef<unknown> | string | number | null
|
|
439
|
+
selected?: boolean
|
|
440
|
+
onClick?: () => void
|
|
441
|
+
popupSide?: 'top' | 'bottom' | 'left' | 'right'
|
|
442
|
+
className?: string
|
|
443
|
+
normalised?: boolean
|
|
444
|
+
|
|
445
|
+
@ViewChild('popupEl') private popupEl?: ElementRef<HTMLElement>
|
|
446
|
+
@ViewChild('labelSlot') private labelSlot?: ElementRef<HTMLElement>
|
|
447
|
+
@ViewChild('noteSlot') private noteSlot?: ElementRef<HTMLElement>
|
|
448
|
+
@ViewChild('emptyNoteEl') private emptyNoteEl?: ElementRef<HTMLElement>
|
|
449
|
+
|
|
450
|
+
private readonly renderer: Renderer2 = inject(RendererFactory2).createRenderer(null, null)
|
|
451
|
+
private readonly popupToggle = new ElementToggle(this.renderer)
|
|
452
|
+
private readonly labelToggle = new ElementToggle(this.renderer)
|
|
453
|
+
private readonly noteToggle = new ElementToggle(this.renderer)
|
|
454
|
+
private readonly emptyToggle = new ElementToggle(this.renderer)
|
|
455
|
+
private noteProjected = false
|
|
456
|
+
private readonly i18n = useTranslation()
|
|
457
|
+
|
|
458
|
+
cm(): UIClassMap {
|
|
459
|
+
return getClassMap()
|
|
460
|
+
}
|
|
461
|
+
|
|
462
|
+
classes(): string {
|
|
463
|
+
return this.cm().cn(this.className)
|
|
464
|
+
}
|
|
465
|
+
|
|
466
|
+
markerClasses(): string {
|
|
467
|
+
return this.cm().cn(this.cm().roundedFull, this.cm().cursorPointer)
|
|
468
|
+
}
|
|
469
|
+
|
|
470
|
+
labelClasses(): string {
|
|
471
|
+
return this.cm().cn(this.cm().textSize('xs'), this.cm().fontWeight('bold'))
|
|
472
|
+
}
|
|
473
|
+
|
|
474
|
+
popupClasses(): string {
|
|
475
|
+
return this.cm().cn(this.cm().surface, this.cm().borderAll, this.cm().textSize('sm'))
|
|
476
|
+
}
|
|
477
|
+
|
|
478
|
+
wrapperStyle(): string {
|
|
479
|
+
const normalised = this.normalised ?? true
|
|
480
|
+
return styleString({
|
|
481
|
+
position: 'absolute',
|
|
482
|
+
left: normalised ? `${this.position.x * 100}%` : `${this.position.x}px`,
|
|
483
|
+
top: normalised ? `${this.position.y * 100}%` : `${this.position.y}px`,
|
|
484
|
+
transform: 'translate(-50%, -50%)',
|
|
485
|
+
zIndex: this.selected ? 2 : 1,
|
|
486
|
+
})
|
|
487
|
+
}
|
|
488
|
+
|
|
489
|
+
markerStyles(): Record<string, string> {
|
|
490
|
+
return styleObject({
|
|
491
|
+
width: 24,
|
|
492
|
+
height: 24,
|
|
493
|
+
border: 'none',
|
|
494
|
+
padding: 0,
|
|
495
|
+
cursor: 'pointer',
|
|
496
|
+
display: 'inline-flex',
|
|
497
|
+
alignItems: 'center',
|
|
498
|
+
justifyContent: 'center',
|
|
499
|
+
boxShadow: '0 1px 3px rgba(0,0,0,0.25)',
|
|
500
|
+
})
|
|
501
|
+
}
|
|
502
|
+
|
|
503
|
+
labelStyle(): string {
|
|
504
|
+
return styleString({ lineHeight: 1, pointerEvents: 'none' })
|
|
505
|
+
}
|
|
506
|
+
|
|
507
|
+
popupStyle(): string {
|
|
508
|
+
const base: Record<string, string | number> = {
|
|
509
|
+
position: 'absolute',
|
|
510
|
+
minWidth: 160,
|
|
511
|
+
maxWidth: 240,
|
|
512
|
+
padding: 8,
|
|
513
|
+
borderRadius: 4,
|
|
514
|
+
boxShadow: '0 4px 12px rgba(0,0,0,0.18)',
|
|
515
|
+
zIndex: 3,
|
|
516
|
+
}
|
|
517
|
+
switch (this.popupSide ?? 'right') {
|
|
518
|
+
case 'top':
|
|
519
|
+
base.bottom = '100%'
|
|
520
|
+
base.left = '50%'
|
|
521
|
+
base.transform = 'translate(-50%, -8px)'
|
|
522
|
+
break
|
|
523
|
+
case 'bottom':
|
|
524
|
+
base.top = '100%'
|
|
525
|
+
base.left = '50%'
|
|
526
|
+
base.transform = 'translate(-50%, 8px)'
|
|
527
|
+
break
|
|
528
|
+
case 'left':
|
|
529
|
+
base.right = '100%'
|
|
530
|
+
base.top = '50%'
|
|
531
|
+
base.transform = 'translate(-8px, -50%)'
|
|
532
|
+
break
|
|
533
|
+
case 'right':
|
|
534
|
+
default:
|
|
535
|
+
base.left = '100%'
|
|
536
|
+
base.top = '50%'
|
|
537
|
+
base.transform = 'translate(8px, -50%)'
|
|
538
|
+
break
|
|
539
|
+
}
|
|
540
|
+
return styleString(base)
|
|
541
|
+
}
|
|
542
|
+
|
|
543
|
+
labelTemplate(): TemplateRef<unknown> | null {
|
|
544
|
+
return isTemplate(this.label) ? this.label : null
|
|
545
|
+
}
|
|
546
|
+
|
|
547
|
+
labelText(): string | null {
|
|
548
|
+
return textOf(this.label)
|
|
549
|
+
}
|
|
550
|
+
|
|
551
|
+
noteTemplate(): TemplateRef<unknown> | null {
|
|
552
|
+
return isTemplate(this.note) ? this.note : null
|
|
553
|
+
}
|
|
554
|
+
|
|
555
|
+
noteText(): string | null {
|
|
556
|
+
return textOf(this.note)
|
|
557
|
+
}
|
|
558
|
+
|
|
559
|
+
hasLabelProp(): boolean {
|
|
560
|
+
return this.label !== undefined && this.label !== null
|
|
561
|
+
}
|
|
562
|
+
|
|
563
|
+
hasNoteProp(): boolean {
|
|
564
|
+
return this.note !== undefined && this.note !== null
|
|
565
|
+
}
|
|
566
|
+
|
|
567
|
+
hasNote(): boolean {
|
|
568
|
+
return this.hasNoteProp() || this.noteProjected
|
|
569
|
+
}
|
|
570
|
+
|
|
571
|
+
markerLabel(): string {
|
|
572
|
+
return this.i18n.t('annotationPin.aria.marker', {}, { defaultValue: 'Annotation pin' })
|
|
573
|
+
}
|
|
574
|
+
|
|
575
|
+
popupLabel(): string {
|
|
576
|
+
return this.i18n.t('annotationPin.aria.popup', {}, { defaultValue: 'Annotation details' })
|
|
577
|
+
}
|
|
578
|
+
|
|
579
|
+
emptyNote(): string {
|
|
580
|
+
return this.i18n.t('annotationPin.empty', {}, { defaultValue: 'No notes for this pin.' })
|
|
581
|
+
}
|
|
582
|
+
|
|
583
|
+
handleMarkerClick(event: MouseEvent): void {
|
|
584
|
+
event.stopPropagation()
|
|
585
|
+
this.onClick?.()
|
|
586
|
+
}
|
|
587
|
+
|
|
588
|
+
reconcile(): void {
|
|
589
|
+
const note = this.noteSlot?.nativeElement
|
|
590
|
+
if (note) this.noteProjected = hasNodes(note)
|
|
591
|
+
this.popupToggle.toggle(this.popupEl?.nativeElement, this.selected === true)
|
|
592
|
+
this.labelToggle.toggle(this.labelSlot?.nativeElement, !this.hasLabelProp())
|
|
593
|
+
this.noteToggle.toggle(note, !this.hasNoteProp())
|
|
594
|
+
this.emptyToggle.toggle(this.emptyNoteEl?.nativeElement, !this.hasNote())
|
|
595
|
+
}
|
|
596
|
+
|
|
597
|
+
ngAfterViewInit(): void {
|
|
598
|
+
this.reconcile()
|
|
599
|
+
}
|
|
600
|
+
|
|
601
|
+
ngDoCheck(): void {
|
|
602
|
+
this.reconcile()
|
|
603
|
+
}
|
|
604
|
+
}
|
|
605
|
+
```
|
|
606
|
+
|
|
607
|
+
_(Member comments are left out to fit; the full declaration is in `node_modules/@molecule/app-annotation-pin-angular/dist/annotation-pin.component.d.ts`.)_
|
|
608
|
+
|
|
609
|
+
## Injection Notes
|
|
610
|
+
|
|
611
|
+
### Requirements
|
|
612
|
+
|
|
613
|
+
Peer dependencies:
|
|
614
|
+
|
|
615
|
+
- `@angular/common` ^22.0.0
|
|
616
|
+
- `@angular/core` ^22.0.0
|
|
617
|
+
- `@angular/platform-browser` ^22.0.0
|
|
618
|
+
- `@molecule/app-angular` ^3.5.0
|
|
619
|
+
- `@molecule/app-ui` ^1.0.1
|
|
620
|
+
- `@molecule/app-ui-angular` ^1.1.0
|
|
621
|
+
|
|
622
|
+
### Runtime Dependencies
|
|
623
|
+
|
|
624
|
+
- `@angular/common`
|
|
625
|
+
- `@angular/core`
|
|
626
|
+
- `@angular/platform-browser`
|
|
627
|
+
- `@molecule/app-angular`
|
|
628
|
+
- `@molecule/app-ui`
|
|
629
|
+
- `@molecule/app-ui-angular`
|
|
630
|
+
|
|
631
|
+
Selection is fully controlled — the layer never stores the active pin;
|
|
632
|
+
manage `activePinId` yourself and toggle it in `onPinClick`. `position` is
|
|
633
|
+
normalised 0..1 by default (fractions of the layer box, so pins re-anchor on
|
|
634
|
+
resize); pass `[normalised]="false"` for raw pixel offsets — on BOTH
|
|
635
|
+
`<AnnotationLayer>` and any directly-rendered `<AnnotationPin>`, or clicks
|
|
636
|
+
and markers will disagree. Node props are projected content in Angular
|
|
637
|
+
(`[slot=label]`, `[slot=note]`, and the layer's default content for the
|
|
638
|
+
surface) or an input carrying text / a `TemplateRef`. A bare
|
|
639
|
+
`<AnnotationPin>` needs its own positioned ancestor. Translations come from
|
|
640
|
+
the companion `@molecule/app-locales-annotation-pin` locale bond.
|
|
641
|
+
|
|
642
|
+
## Translations
|
|
643
|
+
|
|
644
|
+
Translation strings are provided by `@molecule/app-locales-annotation-pin`.
|