Focus Picker
import "@taprootio/espalier/focus-picker";
<esp-focus-picker>
A keyboard- and pointer-operable focal-point authoring control with live banner-cover previews.
The HTML value is focus="x y". In JavaScript use .focusPoint; the name
avoids replacing the platform's required HTMLElement.focus() method.
Attributes
<esp-focus-picker> has the following attributes:
src
src has a default value of "".
Image URL shown in the authoring surface and live previews.
alt
alt has a default value of "".
Alternative text for the source-image authoring surface.
focus
focus has a default value of { x: 0.5, y: 0.5 }.
Normalized current value. Its HTML attribute is named focus.
ratio
ratio has a default value of "3/1".
Aspect ratio for the wide live preview.
compact-ratio
compact-ratio has a default value of "3/2".
Aspect ratio for the compact live preview.
intent
intent has a default value of undefined.
The element's intent — its meaning: neutral
(no pin), or success, warning, danger, info — each pinned
to its fixed status family (blue for info), retunable per theme
via intents. On token-emitting controls a non-neutral intent pins the
filled-action pair to that family, derived over the governing
zone's theme; class-styled chrome (badges, callouts, status pills)
opts out of inline emission and renders its treatment from CSS
classes instead. An intent never repaints the surrounding zone,
which is what contexts are for. Removing the attribute restores
the element's own default intent.
context
context has a default value of undefined.
A theme-defined color zone. The selected context rebinds designer-facing roles and emits a complete, contrast-enforced semantic token table on this host for descendants to inherit.
Methods
<esp-focus-picker> has the following methods:
traverseToClosest
Traverse up the DOM tree to find the closest element that matches the selector. This method is aware of shadow DOM boundaries and will traverse through them to find the element.
Events
<esp-focus-picker> emits the following events:
esp-focus-picker-changed
esp-focus-picker-changed is of type CustomEvent<{x: number, y: number}>.
Bubbles across shadow boundaries after every pointer or keyboard adjustment.
CSS Parts
<esp-focus-picker> has the following CSS parts:
picker
The complete control layout.
stage
The source-image authoring surface.
image
The source image.
marker
The focusable focal-point marker.
previews
The live preview group.
preview
A live esp-image preview cell.
CSS Properties
<esp-focus-picker> has the following CSS properties:
--esp-focus-picker-gap
Gap between the stage and previews.
--esp-focus-picker-stage-background
Empty/loading stage color.
--esp-focus-picker-marker-size
Focal marker diameter.
--esp-focus-picker-marker-color
Focal marker fill.
--esp-focus-picker-marker-border
Focal marker border.
--esp-focus-picker-marker-shadow
Focal marker shadow.
--esp-focus-picker-focus-outline
Marker focus-visible outline.
--esp-field-background
Background color of the shared field shell. Defaults to var(--esp-color-layer-2).
--esp-field-border-color
Border color of the shared field shell. Defaults to var(--esp-color-border).
--esp-field-border-width
Border width of the shared field shell. Defaults to 1px.
--esp-field-text-color
Text color used inside the shared field shell. Defaults to var(--esp-color-text).
--esp-field-hover-bg
Hover background color of the shared field shell. Derived from --esp-field-background.
--esp-field-focus-bg
Focus background color of the shared field shell. Derived from --esp-field-background.
--esp-field-focus-shadow
Shadow color used for shared field focus treatment. Defaults to var(--esp-color-shadow).