API
Note about CSS parts
When targeting an annotate, indicator, or axes components css parts, you must target the component that is being wrapped.
For example, if you want to change the colour of the axes components
grid lines (::part(grid-lines)), you must use the
following format:
oe-axes *::part(grid-lines), oe-axes::part(grid-lines) { color: red; }
<oe-annotate>
Attributes
| Name | Description | Type | Default |
|---|---|---|---|
| tag-style | Changes how to labels are displayed on annotations. `hidden` - All tag content/labels will be hidden. Annotation bounding boxes will still be shown. `edge` - The tag content/labels will be shown on the edge of the associated bounding box `spectrogram-top` - The tag content/labels will be shown above the spectrogram. | AnnotationTagStyle | |
| readonly | Makes all annotations readonly (not currently implemented; all annotations are readonly) | boolean | true |
Properties
| Name | Attribute | Description | Type | Default |
|---|---|---|---|---|
| tagStyle | tag-style | Changes how to labels are displayed on annotations. `hidden` - All tag content/labels will be hidden. Annotation bounding boxes will still be shown. `edge` - The tag content/labels will be shown on the edge of the associated bounding box `spectrogram-top` - The tag content/labels will be shown above the spectrogram. | AnnotationTagStyle | |
| readonly | readonly | Makes all annotations readonly (not currently implemented; all annotations are readonly) | boolean | true |
| annotationsSurface | HTMLDivElement | |||
| spectrogram | SpectrogramComponent | undefined | |||
| annotationElements | ReadonlyArray | |||
| topChromeHeight | ||||
| labelElements | LabelElement[] | [] | ||
| templateTagElements | TemplateTagElement[] | [] | ||
| unitConverter | Readonly | |||
| tagOverflowObserver | IntersectionObserver | undefined | |||
| annotationUpdateEventHandler | ||||
| labelRefs | Ref | |||
| instantiatedLabelRefs | ||||
| annotationModels | Annotation[] |
Methods
| Name | Parameters | Description | Return |
|---|---|---|---|
| chromeRendered | void | ||
| handleSlotChange | void | ||
| chromeOverlay | ChromeTemplate | ||
| chromeTop | ChromeTemplate |
Events
| Name | Description | Type |
|---|---|---|
| emittedEventName | CustomEvent | |
| oe-annotation-created | ||
| oe-annotation-removed | ||
| oe-annotation-selected | ||
| oe-annotation-deselected | ||
| oe-annotation-changed | ||
| oe-annotation-updating | (not implemented) | |
| oe-annotation-updated | (not implemented) |
Slots
| Name | Description |
|---|---|
| (default) | A spectrogram element to add annotations to |
CSS Shadow Parts
| Name | Description |
|---|---|
| annotation-bounding-box | The "box part" of the annotation. E.g. The "green" square around the event. |
| annotation-label | Selector for the annotation label |
CSS Custom Properties
| Name | Description |
|---|---|
| --oe-annotation-color | |
| --oe-annotation-font-color | |
| --oe-annotation-weight | |
| --oe-annotation-selected-color |
<oe-annotation>
Attributes
| Name | Description | Type | Default |
|---|---|---|---|
| low-frequency | Hertz | ||
| high-frequency | Hertz | ||
| start-time | Seconds | ||
| end-time | Seconds | ||
| readonly | Makes the annotation non-editable | boolean | true |
| tags | A comma separated list of tag names for the annotation region | Tag[] | [] |
Properties
| Name | Attribute | Description | Type | Default |
|---|---|---|---|---|
| createdEventName | string | "oe-annotation-created" | ||
| updatedEventName | string | "oe-annotation-updated" | ||
| removedEventName | string | "oe-annotation-removed" | ||
| selectedEventName | string | "oe-annotation-selected" | ||
| deselectedEventName | string | "oe-annotation-deselected" | ||
| updatingEventName | string | "oe-annotation-updating" | ||
| annotationChangedEventName | string | "oe-annotation-changed" | ||
| lowFrequency | low-frequency | Hertz | ||
| highFrequency | high-frequency | Hertz | ||
| startTime | start-time | Seconds | ||
| endTime | end-time | Seconds | ||
| readonly | readonly | Makes the annotation non-editable | boolean | true |
| tags | tags | A comma separated list of tag names for the annotation region | Tag[] | [] |
| tagComponents | ReadonlyArray | |||
| model | Readonly | |||
| selected | boolean | |||
| _selected | boolean | false |
Methods
| Name | Parameters | Description | Return |
|---|---|---|---|
| tagModels | Tag[] |
Events
| Name | Description | Type |
|---|---|---|
| oe-annotation-created | Fires when the annotation component is created | |
| oe-annotation-updating | Fires when the user starts dragging / modifying the annotation (not currently implemented; all annotations are readonly) | |
| oe-annotation-updated | (not implemented) Fires when the low-frequency, high-frequency, start-time, end-time, or tag properties are updated. | |
| oe-annotation-removed | Fires when the annotation is deleted / removed from the DOM | |
| oe-annotation-selected | Fires when the annotation is selected. Triggered by `focus`, and also emits an `Annotation` model. | |
| oe-annotation-deselected | Fires when the annotation is de-selected. Triggered by `blur` and emits and `annotation` model | |
| oe-annotation-changed | Fires when something about the elements lit DOM template has changed E.g. the DOM node has been copied or moved. |
Slots
| Name | Description |
|---|---|
| (default) | A slot for |
<oe-axes>
Attributes
| Name | Description | Type | Default |
|---|---|---|---|
| x-step | The step size for the x-axis | Seconds | undefined | |
| y-step | The step size for the y-axis | Hertz | undefined | |
| x-title | The text to show next to the x-axis | string | "Time (Seconds)" |
| y-title | The text to show next to the y-axis | string | "Frequency (KHz)" |
| x-title-visible | Whether to show/hide the x-axis title | boolean | true |
| y-title-visible | Whether to show/hide the y-axis title | boolean | true |
| x-axis | Shows/hides x-axis labels and ticks | boolean | true |
| y-axis | Shows/hides y-axis labels and ticks | boolean | true |
| x-grid | Shows/hides x-axis labels and grid lines | boolean | true |
| y-grid | Shows/hides y-axis labels and grid lines | boolean | true |
Properties
| Name | Attribute | Description | Type | Default |
|---|---|---|---|---|
| fontCanvas | HTMLCanvasElement | |||
| labelPadding | EmUnit | 0.25 | ||
| tickSize | EmUnit | 0.75 | ||
| titleOffset | EmUnit | 0.25 | ||
| xStepOverride | x-step | The step size for the x-axis | Seconds | undefined | |
| yStepOverride | y-step | The step size for the y-axis | Hertz | undefined | |
| xTitle | x-title | The text to show next to the x-axis | string | "Time (Seconds)" |
| yTitle | y-title | The text to show next to the y-axis | string | "Frequency (KHz)" |
| showXTitle | x-title-visible | Whether to show/hide the x-axis title | boolean | true |
| showYTitle | y-title-visible | Whether to show/hide the y-axis title | boolean | true |
| showXAxis | x-axis | Shows/hides x-axis labels and ticks | boolean | true |
| showYAxis | y-axis | Shows/hides y-axis labels and ticks | boolean | true |
| showXGrid | x-grid | Shows/hides x-axis labels and grid lines | boolean | true |
| showYGrid | y-grid | Shows/hides y-axis labels and grid lines | boolean | true |
| spectrogram | Readonly | |||
| unitConverter | Readonly | |||
| emUnitFontSize | Size | |||
| xAxisTemplate | HTMLTemplateResult | |||
| yAxisTemplate | HTMLTemplateResult | |||
| labelPadding | Size | |||
| tickSize | Size | |||
| titleOffset | Size |
Methods
| Name | Parameters | Description | Return |
|---|---|---|---|
| handleSlotChange | void | ||
| chromeLeft | ChromeTemplate | ||
| chromeBottom | ChromeTemplate | ||
| chromeOverlay | ChromeTemplate |
Slots
| Name | Description |
|---|---|
| (default) | A spectrogram element to add axes to |
CSS Shadow Parts
| Name | Description |
|---|---|
| tick | Apply styles to both x and y tick lines |
| x-tick | Apply styles to only the x axis tick lines |
| y-tick | Apply styles to only the y axis tick lines |
| grid | Apply styles to both x and y grid lines |
| x-grid | Apply styles to only the x grid lines |
| y-grid | Apply styles to only the y grid lines |
| label | Apply styles to both x and y labels |
| x-label | Apply styles to only the x axis label |
| y-label | Apply styles to only the x axis label |
| title | Apply styles to both the x and y titles |
| x-title | Apply styles to only the x axis title |
| y-title | Apply styles to only the y axis title |
<oe-verification-bootstrap>
Properties
| Name | Attribute | Description | Type | Default |
|---|---|---|---|---|
| openEventName | string | "open" | ||
| closeEventName | string | "close" | ||
| injector | VerificationGridInjector | |||
| decisionElements | ReadonlyArray | |||
| hasVerificationTask | boolean | |||
| hasClassificationTask | boolean | |||
| isMobile | boolean | |||
| slides | BootstrapSlide[] | [] | ||
| dialogElement | HTMLDialogElement | |||
| tutorialSlideCarouselElement | SlCarousel | |||
| isAdvancedDialog | boolean | false | ||
| keydownHandler | ||||
| open | boolean | |||
| autoDismissPreference | boolean | |||
| decisionShortcuts | ReadonlyArray | |||
| demoDecisionButton | Readonly |
Methods
| Name | Parameters | Description | Return |
|---|---|---|---|
| showTutorialDialog | void | ||
| showAdvancedDialog | void |
Events
| Name | Description | Type |
|---|---|---|
| open | Dispatched when the dialog is opened | |
| close | Dispatched when the dialog is closed |
<oe-data-source>
Attributes
| Name | Description | Type | Default |
|---|---|---|---|
| src | A remote JSON or CSV file to use as the data source | string | File | undefined | |
| for | A verification grid component that the derived page fetcher callback will be applied to | string | |
| local | Whether to allow for local file inputs through a system UI dialog | boolean | false |
| random | Randomly sample rows from a local or remote data source | boolean | false |
| allow-downloads | Toggles the viability a "Download Results" button in the user interface. Note if allow-downloads is set to "false", results download can still be invoked by host applications through the "downloadResults" method. | boolean | true |
Properties
| Name | Attribute | Description | Type | Default |
|---|---|---|---|---|
| src | src | A remote JSON or CSV file to use as the data source | string | File | undefined | |
| for | for | A verification grid component that the derived page fetcher callback will be applied to | string | |
| local | local | Whether to allow for local file inputs through a system UI dialog | boolean | false |
| random | random | Randomly sample rows from a local or remote data source | boolean | false |
| allowDownloads | allow-downloads | Toggles the viability a "Download Results" button in the user interface. Note if allow-downloads is set to "false", results download can still be invoked by host applications through the "downloadResults" method. | boolean | true |
| canDownload | boolean | false | ||
| fileName | string | undefined | |||
| fileInput | HTMLInputElement | |||
| urlSourcedFetcher | UrlSourcedFetcher | undefined | |||
| verificationGrid | VerificationGridComponent | undefined | |||
| decisionHandler |
Methods
| Name | Parameters | Description | Return |
|---|---|---|---|
| downloadResults | Promise | ||
| downloadResultsTemplate | HTMLTemplateResult |
Slots
| Name | Description |
|---|---|
| (default) | A custom result download button to use instead of the default download button. |
CSS Shadow Parts
| Name | Description |
|---|---|
| file-picker | A css target to style the file picker button |
<oe-decision>
Attributes
| Name | Description | Type | Default |
|---|---|---|---|
| disabled | Disables the decision button and prevents decision events from firing | boolean | false |
| when | WhenPredicate |
Properties
| Name | Attribute | Description | Type | Default |
|---|---|---|---|---|
| decisionEventName | string | "decision" | ||
| injector | VerificationGridInjector | { colorService: decisionColor, } | ||
| disabled | disabled | Disables the decision button and prevents decision events from firing | boolean | false |
| when | when | WhenPredicate | ||
| isMobile | Toggles the decision button in and out of mobile compatibility when decision buttons are rendered in a mobile context, they should be larger, and without shortcut keys | boolean | false | |
| verificationGrid | VerificationGridComponent | undefined | |||
| decisionConstructor | Constructor | |||
| shouldEmitNext | boolean | true | ||
| keyboardHeldDown | boolean | false | ||
| keyUpHandler | ||||
| keyDownHandler |
Methods
| Name | Parameters | Description | Return | ||||||
|---|---|---|---|---|---|---|---|---|---|
| handleShortcutKey |
| void | |||||||
| isShortcutKey |
| boolean | |||||||
| shortcutKeys | KeyboardShortcut[] | ||||||||
| emitDecision |
| void |
Events
| Name | Description | Type |
|---|---|---|
| decision |
<oe-indicator>
Properties
| Name | Attribute | Description | Type | Default |
|---|---|---|---|---|
| spectrogram | SpectrogramComponent | undefined | |||
| indicatorSvg | Readonly | |||
| unitConverter | UnitConverter | undefined | |||
| computedTimePx | ReadonlySignal |
Methods
| Name | Parameters | Description | Return |
|---|---|---|---|
| handleSlotChange | void | ||
| chromeOverlay | ChromeTemplate |
Slots
| Name | Description |
|---|---|
| (default) | A spectrogram component to add an indicator to |
CSS Shadow Parts
| Name | Description |
|---|---|
| indicator-line | A css target to style the indicator line |
| seek-icon | A css target to style the seek icon underneath the indicator line |
<oe-info-card>
Attributes
| Name | Description | Type | Default |
|---|---|---|---|
| default-lines | Number of subject key/values pairs to show before the "Show More" button is clicked | number | 3 |
Properties
| Name | Attribute | Description | Type | Default |
|---|---|---|---|---|
| tile | VerificationGridTileContext | undefined | |||
| defaultLines | default-lines | Number of subject key/values pairs to show before the "Show More" button is clicked | number | 3 |
| showExpanded | boolean | false | ||
| identityStrategy | InfoCardTemplate | |||
| numberStrategy | InfoCardTemplate | |||
| urlStrategy |
<undefined>
Properties
| Name | Attribute | Description | Type | Default |
|---|---|---|---|---|
| logger | IRootContext | undefined |
Methods
| Name | Parameters | Description | Return |
|---|---|---|---|
| doThing | void |
<oe-media-controls>
A simple media player with play/pause and seek functionality that can be used with the open ecoacoustics spectrograms and components.
Attributes
| Name | Description | Type | Default |
|---|---|---|---|
| for | A DOM selector or element reference to target the attached spectrogram element. | string | SpectrogramComponent | "" |
| playIconPosition | PreferenceLocation | "default" |
Properties
| Name | Attribute | Description | Type | Default |
|---|---|---|---|---|
| playShortcut | SPACE_KEY | |||
| recursiveAxesSearch | ||||
| for | for | A DOM selector or element reference to target the attached spectrogram element. | string | SpectrogramComponent | "" |
| playIconPosition | playIconPosition | PreferenceLocation | "default" | |
| areSettingsOpen | We use a state variable to track whether the settings menu is open or not because Shoelace sub-menus use getComputedStyle to determine whether they are in ltr or rtl mode. This causes some performance issues when there are a lot of sub-menus or media controls on the page because each submenu causes a reflow whenever they are created. By maintaining our own open/close state we can defer the creation of the sub-menu contents until the menu is open, meaning that we only hit this reflow cost when the user actually wants to see the menu. see: https://github.com/shoelace-style/shoelace/discussions/2527 | boolean | false | |
| axesElement | AxesComponent | null | undefined | |||
| spectrogramElement | SpectrogramComponent | null | undefined | |||
| playHandler | ||||
| keyDownHandler | ||||
| optionsChangeHandler |
Methods
| Name | Parameters | Description | Return | ||||||
|---|---|---|---|---|---|---|---|---|---|
| toggleAudio |
| void | |||||||
| isSpectrogramPlaying | boolean |
Slots
| Name | Description |
|---|---|
| play-icon | The icon to display when the media is stopped |
| pause-icon | The icon to display when the media is playing |
CSS Shadow Parts
| Name | Description |
|---|---|
| play-icon | Styling applied to the play icon (including default) |
| pause-icon | Styling applied to the pause icon (including default) |
<oe-progress-bar>
Attributes
| Name | Description | Type | Default |
|---|---|---|---|
| history-head | Where the verification head is at | number | 0 |
| total | The total number of items in the data set | number | undefined | |
| completed | The completion head | number | 0 |
Properties
| Name | Attribute | Description | Type | Default |
|---|---|---|---|---|
| historyHead | history-head | Where the verification head is at | number | 0 |
| total | total | The total number of items in the data set | number | undefined | |
| completed | completed | The completion head | number | 0 |
<oe-spectrogram>
Attributes
| Name | Description | Type | Default |
|---|---|---|---|
| window | RenderWindow | undefined | ||
| paused | Whether the spectrogram is paused | boolean | true |
| src | The source of the audio file | string | "" |
| scaling | The aspect ratio of the spectrogram stretch should scale without aspect ratio natural should scale with the correct aspect ratio to fill the container it is in. One dimension will be constrained by the container, the other by the aspect ratio. original will set the spectrogram to the native resolution of the FFT output. It will not scale the image at all. | SpectrogramCanvasScale | |
| window-size | The size of the fft window | PowerTwoWindowSize | undefined | 512 |
| window-function | The window function to use for the spectrogram | WindowFunctionName | undefined | "hann" |
| window-overlap | The amount of overlap between fft windows | number | undefined | 0 |
| mel-scale | A boolean attribute representing if the spectrogram should be shown in mel-scale. | boolean | undefined | false |
| color-map | A color map to use for the spectrogram | ColorMapName | undefined | "grayscale" |
| brightness | An increase in brightness | number | undefined | 0 |
| contrast | A scalar multiplier that should be applied to fft values | number | undefined | 1 |
| offset | An offset (seconds) from the start of a larger audio recording | Seconds | 0 |
| mediaControlOptions | ISpectrogramOptions | {} |
Properties
| Name | Attribute | Description | Type | Default |
|---|---|---|---|---|
| playEventName | string | "play" | ||
| loadingEventName | string | "loading" | ||
| loadedEventName | string | "loaded" | ||
| optionsChangeEventName | string | "options-change" | ||
| defaultOptions | { windowSize: 512, windowOverlap: 0, windowFunction: "hann", melScale: false, brightness: 0, contrast: 1, colorMap: "audacity", scaling: SpectrogramCanvasScale.STRETCH, } as const satisfies Required | |||
| ancestorOptions | ISpectrogramOptions | undefined | |||
| domRenderWindow | window | RenderWindow | undefined | ||
| paused | paused | Whether the spectrogram is paused | boolean | true |
| src | src | The source of the audio file | string | "" |
| scaling | scaling | The aspect ratio of the spectrogram stretch should scale without aspect ratio natural should scale with the correct aspect ratio to fill the container it is in. One dimension will be constrained by the container, the other by the aspect ratio. original will set the spectrogram to the native resolution of the FFT output. It will not scale the image at all. | SpectrogramCanvasScale | |
| windowSize | window-size | The size of the fft window | PowerTwoWindowSize | undefined | 512 |
| windowFunction | window-function | The window function to use for the spectrogram | WindowFunctionName | undefined | "hann" |
| windowOverlap | window-overlap | The amount of overlap between fft windows | number | undefined | 0 |
| melScale | mel-scale | A boolean attribute representing if the spectrogram should be shown in mel-scale. | boolean | undefined | false |
| colorMap | color-map | A color map to use for the spectrogram | ColorMapName | undefined | "grayscale" |
| brightness | brightness | An increase in brightness | number | undefined | 0 |
| contrast | contrast | A scalar multiplier that should be applied to fft values | number | undefined | 1 |
| offset | offset | An offset (seconds) from the start of a larger audio recording | Seconds | 0 |
| mediaControlOptions | mediaControlOptions | ISpectrogramOptions | {} | |
| slottedSourceElements | ReadonlyArray | |||
| spectrogramContainer | Readonly | |||
| mediaElement | HTMLMediaElement | |||
| canvas | HTMLCanvasElement | |||
| currentTime | ReadonlySignal | |||
| unitConverters | ReadonlySignal | |||
| possibleWindowOverlaps | ReadonlyArray | |||
| componentOptions | ISpectrogramOptions | |||
| spectrogramOptions | SpectrogramOptions | |||
| renderedSource | string | |||
| hasSource | boolean | |||
| possibleWindowSizes | [ 128, 256, 512, 1024, 2048, 4096, 8192, 16384, 32768, ] as const satisfies PowerTwoWindowSize[] | |||
| renderWindow | ||||
| audio | ||||
| renderCanvasSize | ||||
| _unitConverters | ||||
| _currentTime | ||||
| audioHelper | new AudioHelper() | |||
| audioContext | new AudioContext() | |||
| highAccuracyTimeBuffer | new SharedArrayBuffer(Float32Array.BYTES_PER_ELEMENT) | |||
| currentTimeBuffer | new Float32Array(this.highAccuracyTimeBuffer) | |||
| canvasResizeCallback | AnimationIdentifier | |||
| interpolationCancelReference | number | null | null | ||
| doneFirstRender | boolean | false |
Methods
| Name | Parameters | Description | Return | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| setComponentOption |
| void | ||||||||||
| setMediaControlsOption |
| void | ||||||||||
| resetMediaControlSettings | void | |||||||||||
| play |
| void | ||||||||||
| pause |
| void | ||||||||||
| stop | void | |||||||||||
| renderSurface |
Events
| Name | Description | Type |
|---|---|---|
| loading | ||
| loaded | ||
| play | ||
| options-change |
Slots
| Name | Description |
|---|---|
| (default) | A ` |
CSS Shadow Parts
| Name | Description |
|---|---|
| canvas | Allows you to size the spectrogram component from the size of the canvas |
<oe-subject-tag>
Properties
| Name | Attribute | Description | Type | Default |
|---|---|---|---|---|
| tile | VerificationGridTileContext | undefined | |||
| originalTag | ||||
| originalTagText | string | |||
| newTag | ||||
| newTagText | string |
<oe-tag>
Attributes
| Name | Description | Type | Default |
|---|---|---|---|
| value | string | "" |
Properties
| Name | Attribute | Description | Type | Default |
|---|---|---|---|---|
| value | value | string | "" | |
| innerElements | Node[] | |||
| model | Readonly |
Slots
| Name | Description |
|---|---|
| (default) | Content that can be displayed to describe the tag |
<oe-task-meter>
Properties
| Name | Attribute | Description | Type | Default |
|---|---|---|---|---|
| tile | VerificationGridTileContext | undefined | |||
| injector | VerificationGridInjector |
<oe-typeahead>
Attributes
| Name | Description | Type | Default |
|---|---|---|---|
| text-converter | TypeaheadTextConverter | ||
| search | TypeaheadCallback | ||
| max-items | number | 10 | |
| recent-used-count | number | 5 |
Properties
| Name | Attribute | Description | Type | Default |
|---|---|---|---|---|
| selectedEventName | string | "oe-typeahead-selected" | ||
| textConverter | text-converter | TypeaheadTextConverter | ||
| search | search | TypeaheadCallback | ||
| maxItems | max-items | number | 10 | |
| recentlyUsedCount | recent-used-count | number | 5 | |
| typeaheadResults | T[] | [] | ||
| focusedIndex | number | 0 | ||
| tagInput | HTMLInputElement | |||
| recentlyUsed | T[] | [] |
Methods
| Name | Parameters | Description | Return |
|---|---|---|---|
| focus | void | ||
| reset | void | ||
| clearRecentlyUsed | void |
Events
| Name | Description | Type |
|---|---|---|
| oe-typeahead-selected |
<oe-verification-grid>
Attributes
| Name | Description | Type | Default |
|---|---|---|---|
| grid-size | The number of items to display in a single grid | number | 10 |
| selection-behavior | The selection behavior of the verification grid | SelectionObserverType | "default" |
| empty-subject-message | string | "No content" | |
| progress-bar-position | ProgressBarPosition | ||
| get-page | A callback function that returns a page of recordings | PageFetcher | undefined | |
| url-transformer | A callback function that will be applied to all subject urls | UrlTransformer | an identity function that returns the url unchanged |
| loading-timeout | A duration of time that the verification grid can be in a "loading" state before it times out and shows an error message. | Seconds | |
| autofocus | boolean | false |
Properties
| Name | Attribute | Description | Type | Default |
|---|---|---|---|---|
| decisionMadeEventName | string | "decision-made" | ||
| loadedEventName | string | "grid-loaded" | ||
| defaultGridTileTemplateId | string | "oe-default-tile-template" | ||
| defaultSkipButtonId | string | "oe-default-skip-button" | ||
| autoPageTimeout | 0.3 satisfies Seconds | |||
| slowLoadThreshold | 0.2 satisfies Seconds | |||
| defaultGridTileTemplate | staticHtml` | |||
| settings | VerificationGridSettings | { isFullscreen: signal(false), } | ||
| spectrogramOptions | Partial | {} | ||
| injector | VerificationGridInjector | { colorService: decisionColor, } | ||
| targetGridSize | grid-size | The number of items to display in a single grid | number | 10 |
| selectionBehavior | selection-behavior | The selection behavior of the verification grid | SelectionObserverType | "default" |
| emptySubjectText | empty-subject-message | string | "No content" | |
| progressBarPosition | progress-bar-position | ProgressBarPosition | ||
| getPage | get-page | A callback function that returns a page of recordings | PageFetcher | undefined | |
| urlTransformer | url-transformer | A callback function that will be applied to all subject urls | UrlTransformer | an identity function that returns the url unchanged |
| loadingTimeout | loading-timeout | A duration of time that the verification grid can be in a "loading" state before it times out and shows an error message. | Seconds | |
| autofocus | autofocus | boolean | false | |
| verificationDecisionElements | selector for oe-verification elements | ReadonlyArray | ||
| classificationDecisionElements | selector for oe-classification elements | ReadonlyArray | ||
| tagPromptDecisionElements | selector for oe-classification elements | ReadonlyArray | ||
| decisionElements | A selector for all oe-verification and oe-classification elements | ReadonlyArray | ||
| skipButtons | ReadonlyArray | |||
| customTileTemplates | ReadonlyArray | |||
| defaultSkipButton | ReadonlyArray | |||
| gridTiles | NodeListOf | |||
| defaultTemplateElement | HTMLTemplateElement | |||
| bootstrapDialog | VerificationBootstrapComponent | |||
| gridContainer | HTMLDivElement | |||
| decisionsContainer | HTMLDivElement | |||
| highlightBox | HTMLDivElement | |||
| columns | ||||
| rows | number | 1 | ||
| currentSubSelection | SubjectWrapper[] | [] | ||
| _loadState | GridState | |||
| _viewHeadIndex | number | 0 | ||
| _decisionHeadIndex | number | 0 | ||
| gridShape | GridShape | |||
| viewHeadIndex | The index from the `subjects` array indicating up to which point decisions have been made It is updated as each page is completed | number | ||
| decisionHeadIndex | The index from the `subjects` array indicating up to which point decisions have been made It is updated as each page is completed | number | ||
| slottedDecisionComponents | All decisions provided by the user, excluding the default skip button. | DecisionComponentUnion[] | ||
| availableGridCells | A count of grid cells available for grid tile components. Not all grid cells may be currently populated with grid tiles. If you want the total number of tiles currently populated/visible on the screen, use the `pageSize` getter. | number | ||
| pageSize | A count of the number of tiles currently visible on the screen | number | ||
| subjects | Because subject wrappers are highly sensitive to changes (e.g. changing a subject reference might break downloading), we only expose a readonly array of subjects. | ReadonlyArray | ||
| loadState | GridState | |||
| currentPageIndices | CurrentPage | |||
| emptyTileCount | ||||
| userSelectionBehavior | Returns the current users selection behavior, collapsing the "default" behavior into either "tablet" or "desktop" depending on the users device type. | SelectionObserverType | ||
| isSingleTileViewMode | When in a single tile view mode, there is some special functionality such as disabling the sub-selection feature, and not being able to draw a selection highlight box. | boolean | ||
| hasDatasource | boolean | |||
| hasFinishedDatasource | boolean | |||
| keydownHandler | ||||
| keyupHandler | ||||
| blurHandler | ||||
| selectionHandler | ||||
| decisionHandler | ||||
| pointerDownHandler | ||||
| pointerUpHandler | ||||
| pointerMoveHandler | ||||
| scrollHandler | ||||
| singleDecisionMode | "single decision mode" will automatically advance the selection head if: 1. There is only one tile selected 2. All tasks on the selected tile is completed A user can enter this mode at any time by selecting just one tile. They remain in the mode by completing all tasks on the single selected tile, at which point the selection is advanced. Once in this mode, there is some special functionality like the first tile of each new page being automatically selected. | boolean | false | |
| requiredClassificationTags | Tag[] | [] | ||
| requiredDecisions | RequiredDecision[] | [] | ||
| showingSelectionShortcuts | boolean | false | ||
| _subjects | SubjectWrapper[] | [] | ||
| _loadingTimeout | Seconds | 8 | ||
| anyOverlap | ||||
| gridController | new DynamicGridSizeController(this, this.anyOverlap) | |||
| datasetLoadingController | new LoadingController(this, { slowLoadThreshold: VerificationGridComponent.slowLoadThreshold, timeoutThreshold: this.loadingTimeout, }) | |||
| paginationFetcher | GridPageFetcher | undefined | |||
| subjectWriter | SubjectWriter | undefined | |||
| highlightSelectionAnimation | ||||
| highlight | HighlightSelection | { start: { x: 0, y: 0 }, current: { x: 0, y: 0 }, highlighting: false, pointerId: null, capturedPointer: false, observedElements: [], // Poorly created webpages may not have a body element. // In this case, we should use the component host as the highlight host. // // I store the highlight host in the highlight object so if a tag // is dynamically added/removed from the page, we will maintain the same // highlight host and not leak event listeners. highlightHost: document.body ?? this, } | ||
| focusHead | number | null | null | ||
| _rangeSelectionHead | number | null | null | ||
| rangeSelectionHead | Where range selection will start from. This pointer moves independently from the focus head. | |||
| nextLeftIndex | number | |||
| nextRightIndex | number | |||
| nextUpIndex | number | |||
| nextDownIndex | number | |||
| lastTileIndex | number |
Methods
| Name | Parameters | Description | Return |
|---|---|---|---|
| focus | |||
| isViewingHistory | boolean | ||
| resetSpectrogramSettings | void | ||
| isBootstrapDialogOpen | boolean | ||
| flushAllSubjects | |||
| transitionError | |||
| transitionConfigurationError | |||
| transitionDatasetFetching |
Events
| Name | Description | Type |
|---|---|---|
| decision-made | Emits information about a batch of decisions that was made | DecisionMadeEvent |
| grid-loaded | Emits when all the spectrograms have been loaded |
Slots
| Name | Description |
|---|---|
| (default) | A template element that will be used to create each grid tile |
| (default) | Decision elements that will be used to create the decision buttons |
| data-source | An `oe-data-source` element that provides the data |
CSS Shadow Parts
| Name | Description |
|---|---|
| highlight-box | A CSS target for the highlight box so that you can change the color/style. |
<oe-verification-grid-settings>
Attributes
| Name | Description | Type | Default |
|---|---|---|---|
| max-grid-size | number | 36 |
Properties
| Name | Attribute | Description | Type | Default |
|---|---|---|---|---|
| settings | VerificationGridSettings | |||
| maxGridSize | max-grid-size | number | 36 | |
| gridSize | An internal representation of the verification grids size | number | undefined | ||
| verificationGrid | VerificationGridComponent | undefined | |||
| fullscreenChangeHandler |
<oe-verification-grid-tile>
Properties
| Name | Attribute | Description | Type | Default |
|---|---|---|---|---|
| selectedEventName | string | "oe-selected" | ||
| loadingEventName | string | "oe-tile-loading" | ||
| loadedEventName | string | "oe-tile-loaded" | ||
| overlapEventName | string | "overlap" | ||
| tile | VerificationGridTileContext | |||
| showKeyboardShortcuts | boolean | false | ||
| selected | boolean | false | ||
| index | The index position of the tile within a verification grid that is used to determine the selection keyboard shortcut associated with the grid tile | number | 0 | |
| singleTileViewMode | A property that can be set if the grid tile is the only tile in the verification grid. This is useful for disabling selection events and styling. | boolean | false | |
| requiredDecisions | RequiredDecision[] | [] | ||
| model | SubjectWrapper | |||
| isOverlapping | boolean | false | ||
| tileTemplate | HTMLTemplateElement | |||
| spectrogram | SpectrogramComponent | undefined | |||
| templateContent | HTMLDivElement | |||
| contentsWrapper | HTMLDivElement | |||
| keyDownHandler | ||||
| loadedHandler | ||||
| loaded | boolean | false | ||
| shortcuts | string[] | [] | ||
| intersectionObserver | IntersectionObserver | |||
| taskCompleted | boolean |
Methods
| Name | Parameters | Description | Return | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| focus | An override of the default HTMLElement focus() method so that tab index's and location is consistent. | ||||||||||||||
| updateSubject |
| void | |||||||||||||
| resetSettings | void | ||||||||||||||
| addDecision |
| SubjectChange | |||||||||||||
| removeDecision |
| SubjectChange | |||||||||||||
| skipUndecided |
| SubjectChange |
Events
| Name | Description | Type |
|---|---|---|
| oe-selected | ||
| oe-tile-loading | ||
| oe-tile-loaded |
<oe-classification>
Attributes
| Name | Description | Type | Default |
|---|---|---|---|
| tag | Tag | ||
| true-shortcut | A shortcut key that when pressed will trigger a true classification decision to be emitted | string | undefined | |
| false-shortcut | A shortcut key that when pressed will trigger a false classification decision to be emitted | string | undefined | |
| disabled | Disables the decision button and prevents decision events from firing | boolean | false |
| when | WhenPredicate |
Properties
| Name | Attribute | Description | Type | Default |
|---|---|---|---|---|
| tag | tag | Tag | ||
| trueShortcut | true-shortcut | A shortcut key that when pressed will trigger a true classification decision to be emitted | string | undefined | |
| falseShortcut | false-shortcut | A shortcut key that when pressed will trigger a false classification decision to be emitted | string | undefined | |
| trueDecisionButton | HTMLButtonElement | |||
| falseDecisionButton | HTMLButtonElement | |||
| decisionModels | Partial | |||
| decisionConstructor | Constructor | |||
| _decisionModels | Partial | {} | ||
| trueKeyboardShortcut | KeyboardShortcut | undefined | |||
| falseKeyboardShortcut | KeyboardShortcut | undefined | |||
| decisionEventName | string | "decision" | ||
| injector | VerificationGridInjector | { colorService: decisionColor, } | ||
| disabled | disabled | Disables the decision button and prevents decision events from firing | boolean | false |
| when | when | WhenPredicate | ||
| isMobile | Toggles the decision button in and out of mobile compatibility when decision buttons are rendered in a mobile context, they should be larger, and without shortcut keys | boolean | false | |
| verificationGrid | VerificationGridComponent | undefined | |||
| shouldEmitNext | boolean | true | ||
| keyboardHeldDown | boolean | false | ||
| keyUpHandler | ||||
| keyDownHandler |
Methods
| Name | Parameters | Description | Return | ||||||
|---|---|---|---|---|---|---|---|---|---|
| shortcutKeys | KeyboardShortcut[] | ||||||||
| handleShortcutKey |
| void | |||||||
| isShortcutKey |
| boolean | |||||||
| emitDecision |
| void |
Events
| Name | Description | Type |
|---|---|---|
| decision |
Slots
| Name | Description |
|---|---|
| (default) | Additional content to be displayed in the decision groups title |
CSS Shadow Parts
| Name | Description |
|---|---|
| true-decision-button | Styling selector to target the true decision button |
| false-decision-button | Styling selector to target the false decision button |
<oe-skip>
Attributes
| Name | Description | Type | Default |
|---|---|---|---|
| verified | DecisionOptions | ||
| additional-tags | Value that will be added to the oe-additional-tags column | Tag[] | [] |
| shortcut | A keyboard key that when pressed will act as a click event on the button | string | "" |
| disabled | Disables the decision button and prevents decision events from firing | boolean | false |
| when | WhenPredicate |
Properties
| Name | Attribute | Description | Type | Default |
|---|---|---|---|---|
| verified | verified | DecisionOptions | ||
| additionalTags | additional-tags | Value that will be added to the oe-additional-tags column | Tag[] | [] |
| shortcut | shortcut | A keyboard key that when pressed will act as a click event on the button | string | "" |
| decisionButton | HTMLButtonElement | |||
| decisionConstructor | Constructor | |||
| isTask | Returns a boolean indicating if using this verification component creates a verification task. | boolean | ||
| decisionEventName | string | "decision" | ||
| injector | VerificationGridInjector | { colorService: decisionColor, } | ||
| disabled | disabled | Disables the decision button and prevents decision events from firing | boolean | false |
| when | when | WhenPredicate | ||
| isMobile | Toggles the decision button in and out of mobile compatibility when decision buttons are rendered in a mobile context, they should be larger, and without shortcut keys | boolean | false | |
| verificationGrid | VerificationGridComponent | undefined | |||
| shouldEmitNext | boolean | true | ||
| keyboardHeldDown | boolean | false | ||
| keyUpHandler | ||||
| keyDownHandler |
Methods
| Name | Parameters | Description | Return | ||||||
|---|---|---|---|---|---|---|---|---|---|
| shortcutKeys | KeyboardShortcut[] | ||||||||
| handleShortcutKey |
| void | |||||||
| isShortcutKey |
| boolean | |||||||
| handleDecision | void | ||||||||
| emitDecision |
| void |
Events
| Name | Description | Type |
|---|---|---|
| decision |
Slots
| Name | Description |
|---|---|
| (default) | Additional content to be displayed in the decision button |
CSS Shadow Parts
| Name | Description |
|---|---|
| decision-button | The button that triggers the decision |
<oe-tag-prompt>
Attributes
| Name | Description | Type | Default |
|---|---|---|---|
| shortcut | string | "" | |
| search | TypeaheadCallback | ||
| disabled | Disables the decision button and prevents decision events from firing | boolean | false |
| when | WhenPredicate |
Properties
| Name | Attribute | Description | Type | Default |
|---|---|---|---|---|
| shortcut | shortcut | string | "" | |
| search | search | TypeaheadCallback | ||
| tagPopover | HTMLDialogElement | |||
| tagTypeahead | TypeaheadComponent | |||
| decisionConstructor | Constructor | |||
| decisionEventName | string | "decision" | ||
| injector | VerificationGridInjector | { colorService: decisionColor, } | ||
| disabled | disabled | Disables the decision button and prevents decision events from firing | boolean | false |
| when | when | WhenPredicate | ||
| isMobile | Toggles the decision button in and out of mobile compatibility when decision buttons are rendered in a mobile context, they should be larger, and without shortcut keys | boolean | false | |
| verificationGrid | VerificationGridComponent | undefined | |||
| shouldEmitNext | boolean | true | ||
| keyboardHeldDown | boolean | false | ||
| keyUpHandler | ||||
| keyDownHandler |
Methods
| Name | Parameters | Description | Return | ||||||
|---|---|---|---|---|---|---|---|---|---|
| close | Close the tag prompt popover | void | |||||||
| handleShortcutKey |
| void | |||||||
| isShortcutKey |
| boolean | |||||||
| shortcutKeys | KeyboardShortcut[] | ||||||||
| emitDecision |
| void |
Events
| Name | Description | Type |
|---|---|---|
| decision |
<oe-verification>
Attributes
| Name | Description | Type | Default |
|---|---|---|---|
| verified | DecisionOptions | ||
| additional-tags | Value that will be added to the oe-additional-tags column | Tag[] | [] |
| shortcut | A keyboard key that when pressed will act as a click event on the button | string | "" |
| disabled | Disables the decision button and prevents decision events from firing | boolean | false |
| when | WhenPredicate |
Properties
| Name | Attribute | Description | Type | Default |
|---|---|---|---|---|
| verified | verified | DecisionOptions | ||
| additionalTags | additional-tags | Value that will be added to the oe-additional-tags column | Tag[] | [] |
| shortcut | shortcut | A keyboard key that when pressed will act as a click event on the button | string | "" |
| decisionButton | HTMLButtonElement | |||
| decisionConstructor | Constructor | |||
| isTask | Returns a boolean indicating if using this verification component creates a verification task. | boolean | ||
| decisionEventName | string | "decision" | ||
| injector | VerificationGridInjector | { colorService: decisionColor, } | ||
| disabled | disabled | Disables the decision button and prevents decision events from firing | boolean | false |
| when | when | WhenPredicate | ||
| isMobile | Toggles the decision button in and out of mobile compatibility when decision buttons are rendered in a mobile context, they should be larger, and without shortcut keys | boolean | false | |
| verificationGrid | VerificationGridComponent | undefined | |||
| shouldEmitNext | boolean | true | ||
| keyboardHeldDown | boolean | false | ||
| keyUpHandler | ||||
| keyDownHandler |
Methods
| Name | Parameters | Description | Return | ||||||
|---|---|---|---|---|---|---|---|---|---|
| shortcutKeys | KeyboardShortcut[] | ||||||||
| handleShortcutKey |
| void | |||||||
| isShortcutKey |
| boolean | |||||||
| handleDecision | void | ||||||||
| emitDecision |
| void |
Events
| Name | Description | Type |
|---|---|---|
| decision |
Slots
| Name | Description |
|---|---|
| (default) | Additional content to be displayed in the decision button |
CSS Shadow Parts
| Name | Description |
|---|---|
| decision-button | The button that triggers the decision |