J3W1 / DESIGN SYSTEM
Popover
A non-modal supporting panel with light dismissal and ordinary tab order.
stable · LIGHT DOM · 1.1.0
Light DOM retains static content, native semantics, label relationships and host composition without duplicating controls.
Live variants
default
This workspace uses synthetic local data.
<j3w1-popover id="example-popover-default"><div class="popover"><button class="popover-control" type="button" data-popover-trigger="" aria-expanded="false" aria-controls="example-popover-default-popover-help" data-demo-focus-target="">Connection information</button><section class="popover-panel" id="example-popover-default-popover-help" data-popover-panel="" aria-label="Connection information"><p>This workspace uses synthetic local data.</p><button class="popover-control" type="button" data-close="">Close</button></section></div></j3w1-popover>Install and register
Use the exact version. If npm publication is pending, install the release tarball from the installation guide.
npm install --save-exact @j3w1/ui@1.1.0import '@j3w1/ui/tokens.css';
import '@j3w1/ui/styles/popover.css';
import '@j3w1/ui/register/popover';Insert the maintained markup above after loading these imports. Its native children provide accessible names and form behavior; the empty custom tag alone does not create a control.
Copy the complete implementation
npx --package=@j3w1/ui@1.1.0 j3w1-ui copy popover --out ./vendor/j3w1/popoverThe CLI verifies every file before writing and refuses overwrites. Serve the output over HTTP and open index.html. Keep its modules, CSS, tokens and licence notices together.
Public API
attributes
| Name | Type / signature | Meaning |
|---|---|---|
disabled | CustomEvent | Disable the native controls owned by this instance. |
loading | CustomEvent | Mark the primary control busy and prevent duplicate activation. |
properties
| Name | Type / signature | Meaning |
|---|---|---|
disabled | boolean | Delegates disabled state to native children. |
name | string | Native control name; application form keys remain explicit. |
open | boolean | Non-modal panel visibility. |
methods
| Name | Type / signature | Meaning |
|---|---|---|
refresh | (): void | Reconnect behavior after replacing native child structure. |
focus | (options?: FocusOptions): void | Focus the first usable native control. |
show | (): void | Show next to the trigger. |
hide | (focus?: boolean): void | Hide, optionally restoring trigger focus. |
events
| Name | Type / signature | Meaning |
|---|---|---|
j3w1-toggle | CustomEvent | The panel changed visibility. |
Dependencies and verification
Registered components: none. Style dependencies: none.
Package presence establishes an available implementation. Actual passes depend on the tested artifact and environment. Read specification execution evidence; read packed-consumer evidence; inspect the complete state matrix.
Full implementation manifest, API and token dependency closure
Canonical specification
Purpose
Disclose a non-modal supporting panel near its trigger. Interactive content follows ordinary tab order. Escape and outside activation dismiss; focus is not trapped. Use the native Popover API when available with an equivalent documented fallback.
Anatomy
- trigger: Native button with expanded state and panel relationship.
- panel: Named supporting content and optional visible close action.
States
| State | Presentation | Non-colour channel |
|---|---|---|
| default | Named trigger. | Button semantics and accessible name. |
| open | Square overlay surface and border. | aria-expanded=true; panel is reachable. |
| closed | Panel hidden. | aria-expanded=false; hidden controls leave focus order. |
| focus-visible | Dashed focus ring. | Native keyboard focus. |
Keyboard
- Enter / Space: Toggle from the trigger.
- Tab / Shift+Tab: Move through ordinary controls without trapping focus.
- Escape: Close and restore the trigger.
Accessibility
Keep essential instructions outside collapsed panels. Use a visible label or aria-label for the panel. Do not add aria-modal or a focus trap. Native automatic dismissal and the fallback both synchronize expanded state.
Portability
Wrap labels and actions without changing source order. Use logical spacing in RTL. Preserve native target sizes at both densities; only bounded data regions may scroll horizontally. Use equivalent native semantics and approved roles; record any unsupported behavior as a mapping deviation. The host owns application data, persistence, permissions and services.
Non-examples
Unlabelled controls, color-only status, drag-only operations, hidden required instructions, stolen focus or an invented service success.