Skip to main content
Introducing packages.sweber.dev
Documentation menuWidget

Widget

Attributes, events, styling and accessibility of <derivative-widget>.

<derivative-widget src="/changelog.json"></derivative-widget>
<script type="module">
  import "@sweberdev/derivative/widget";
</script>

Importing @sweberdev/derivative/widget registers the element. To register it under another name, or only when you decide, import from @sweberdev/derivative/widget/define:

import { defineDerivativeWidget } from "@sweberdev/derivative/widget/define";
defineDerivativeWidget("acme-whats-new");

Attributes

AttributeDefaultMeaning
srcURL of changelog.json
lang<html lang>en, de, fr or it (regional tags such as de-CH work)
modepopoverinline renders the list in place, without a button
limit10Number of releases shown
label"What's new"Button text and panel title
hreffeed link"All changes" link below the list
alignendPanel opens towards the start or end of the button
themesystemlight or dark to override the system setting
typesallComma-separated entry types to show, e.g. feature,fix. Releases without a matching entry are hidden unless they have a title or summary
packageallMonorepo feeds: show, count and mark as read only these packages. Comma-separated, a trailing * matches a prefix, e.g. @acme/*
heading-level3 in the panel, 2 inlineLevel of the release headings, 2 to 6, so the page's heading outline stays in order
highlightoffAnnounces the newest unread release that has a title, once per release: toast (default when the attribute is present), banner or modal. Releases with importance: "major" come first. See Highlights
audiencenoneComma-separated audiences of the reader, e.g. pro,admin. Releases and entries that name an audience are hidden from everyone else; content without an audience is shown to all
hintsoffSets data-derivative-hint on the page elements that unread entries point to with target (a CSS selector) and removes it when the reader has seen the release
searchoffAdds a search field above the list. It filters as you type across version, title, summary, entries, details and scope, and ignores limit while a query is active
storage-keyderivative:last-seenlocalStorage key, set one per product if you embed several feeds

Set the feed property instead of src to pass data you already have. Set messages to change any text.

Events

All events bubble and cross the shadow root.

Eventdetail
derivative-load{ feed }
derivative-error{ error }
derivative-open
derivative-close
derivative-read{ lastSeen }
derivative-highlight{ release }, when a highlight appears
derivative-render{ list }, after the list was drawn (also after each search). For extensions that add something to every release, like Pro reactions

Methods: show(), hide(), toggle(), markAllRead(), dismissHighlight(). Properties: open, unreadCount.

Highlight

With highlight, the widget announces the newest unread release that has a title (set one in Highlights or as the GitHub release name), once per reader and release. A release with importance: "major" wins over newer minor ones. Patch releases without a title never interrupt anyone. Dismissing a highlight keeps the unread badge; "Show" opens the panel.

ValueLooks like
toastA small card next to the button with the title and the first paragraph of the summary
bannerA bar across the top of the page with the title, the first paragraph and the buttons
modalA centred dialog (role="dialog", aria-modal) with the title, the whole summary, the first image and the release's links. Tab stays inside, Escape or a click on the backdrop dismisses it and focus returns to the button

Audiences

Mark releases or entries with audience in the feed (format), or label tickets audience:pro in a tracker, and tell the widget who is reading with audience="pro". Hidden content is not counted as unread. The filter runs in the browser, so use it for relevance, not for secrets: the feed file itself is public. For feeds that must not leak, Pro Segments builds one feed per audience.

Hints in the page

An entry with "target": "#export-button" points at the part of your product it is about. With hints, the widget sets data-derivative-hint="feature" (the entry type) on matching elements while the entry is unread. Style it as you like:

[data-derivative-hint]::after {
  content: "";
  display: inline-block;
  width: .5rem;
  height: .5rem;
  margin-inline-start: .35rem;
  border-radius: 50%;
  background: #2f5bea;
}

The attribute disappears when the reader opens the panel (all releases count as read). Invalid selectors are ignored.

Translations

If the feed carries translations (the feed format describes them), the widget and the generated page use the title, summary and entry texts of the language set with lang, falling back to the original text.

With search, a search field appears above the list, in the panel and in mode="inline". It filters as the reader types and matches version, title, summary, entries, details and scope, case-insensitively. While a query is active, limit is ignored so older releases are found too. The query stays when the panel is closed and reopened. The placeholder text is the search message, the empty state the noResults message.

Unread badge

The widget stores the newest release a reader has seen. Releases above it count as new. A first-time reader sees releases from the last 30 days as new, so they don't get a badge for your entire history.

Styling

Use CSS custom properties on the element:

derivative-widget {
  --dv-accent: #e4002b;
  --dv-radius: 4px;
  --dv-width: 420px;
  --dv-font: "Inter", sans-serif;
}

Also available:

PropertyDefaultMeaning
--dv-bg, --dv-fg, --dv-muted, --dv-borderlight or dark setSurfaces and text
--dv-good, --dv-warngreen, orangeColours of Fixed and of Breaking and Security badges
--dv-button-radius999pxCorner radius of the button
--dv-button-bg, --dv-button-fg--dv-bg, inheritedButton colours
--dv-badge-fg--dv-bgText colour of the unread badge (background is --dv-accent)
--dv-shadowsoft shadowShadow of the panel and the highlight
--dv-max-heightmin(70vh, 560px)Height limit of the panel
--dv-z1000Stacking order of the panel, the banner and toast sit one below, the modal one above

For deeper changes, use ::part(): button, badge, panel, header, title, close, search, list, link, release, release-title, meta, summary, entry, type, scope, entry-link, highlight, highlight-title, highlight-text, highlight-action, highlight-dismiss, backdrop, media, links and action.

derivative-widget::part(entry) { padding-block: 0.25rem; }
derivative-widget::part(release-title) { font-family: "Space Grotesk", sans-serif; }

Replace the bell icon with <span slot="icon">…</span> and the label with plain text content.

Dark mode

By default the widget follows the system setting. If your app has its own switch, such as a dark class on <html>, set the theme attribute from it instead:

const widget = document.querySelector("derivative-widget");
new MutationObserver(() => {
  widget.setAttribute("theme", document.documentElement.classList.contains("dark") ? "dark" : "light");
}).observe(document.documentElement, { attributeFilter: ["class"] });

Or style the colour properties yourself, e.g. .dark derivative-widget { --dv-bg: #0b0b0f; --dv-fg: #f4f4f5; }.

Right-to-left

Pages with dir="rtl" need no setting: the panel and the highlight open from the correct side, and align="start" and align="end" follow the reading direction.

Accessibility

Colours meet the WCAG AA contrast ratio (4.5:1) in light and dark mode. Pages with dir="rtl" work too: the panel and highlight open from the correct side. Both are checked in real Chromium in CI. Release headings are h3 under the panel's h2; inline lists start at h2 and can be moved with heading-level. The widget is checked with axe in the test suite. The button reports its state with aria-expanded and announces the number of new releases to screen readers. The panel is a labelled dialog that receives focus when it opens. Escape closes it and returns focus to the button, as does a click outside. Toast and banner are role="status" regions, so screen readers announce them without moving focus; the modal is a labelled dialog that takes focus and returns it on close. The opening animation is skipped when the reader prefers reduced motion.

Security

Feed text is always escaped. Only code, bold, italic and links are rendered, and links with schemes other than http, https and mailto are dropped.