[Tool] Embeddable OTE events widget

[hhkaos]

Problem

A community or conference may publish an OTE feed, but still need a way to show those events on their own website.

Without a reusable widget, every website has to build the same UI again: fetch the feed, parse events, sort upcoming dates, handle empty states, render locations, and keep the display accessible and responsive.

Why this matters for OTE

This lowers the adoption barrier for communities that can publish a feed but do not want to build a custom event listing.

It also helps OTE feel immediately useful: publish structured data once, then embed it as a human-friendly event list or calendar anywhere.

Possible shape

• Embeddable script/widget for websites.
• Accept one or more OTE feed URLs.
• Render upcoming events in different layouts, for example:
  • list
  • compact list
  • calendar
  • cards
• Allow basic filters:
  • topic/tag
  • city/country
  • online/in-person/hybrid
  • language
  • date range
  • community/source
• Support sorting, empty states and cancelled/postponed events.
• Link each event back to its canonical page/source.
• Be usable on static sites and simple CMS pages.

Configuration ideas

Configuration could happen through HTML attributes, a small JS config object, URL parameters, or generated embed code.

Examples of things a site owner may want to configure:

• feed URLs
• layout
• max number of events
• default filters
• theme or CSS variables
• language
• whether to show past events
• whether to group by month/community/topic

Open questions

• Is a Web Component the best implementation, or should this be a plain script, iframe, framework package, or generated static HTML?
• Should it fetch feeds client-side, or should there also be a build-time/static generation option?
• How should CORS and feed availability be handled?
• How much styling should be built in, and how much should inherit from the host site?
• Should multi-feed deduplication be part of the widget or delegated to an aggregator?
• Which layout should be the first MVP: list or calendar?
• Should this live in ote-tools, as an npm package, or both?

Non-goals for a first version

• No event editing or publishing.
• No account system.
• No requirement to support every visual layout before shipping a minimal useful embed.

[hhkaos]

Coordination note from the Community Builders website work:

• We want to avoid building a one-off event renderer in ComBuildersES/ComBuildersES.github.io.
• The preferred direction is a single reusable Web Component, usable from plain HTML and also from React/Vue/Astro/static sites, rather than maintaining separate React and non-React implementations.
• Community Builders can be the first real consumer using https://combuilderses.github.io/events/feed.json.

Proposed next steps:

1. Track implementation in OpenTechEvents/ote-tools, reusing/extracting what already exists in apps/preview: Build an embeddable OTE events Web Component ote-tools#27
2. Keep this issue as the product/spec discussion for the embeddable widget.
3. Follow up in ComBuildersES/ComBuildersES.github.io to create /eventos or /encuentros once the component is ready: Create an events page using the reusable OTE embed ComBuildersES/ComBuildersES.github.io#23

[hhkaos]

An MVP implementation is up in ote-tools: OpenTechEvents/ote-tools#28, tracked from ote-tools#27.

Answers to a couple of the open questions above, for this first pass:

• Web Component vs. other shapes: went with a single Web Component (<ote-events>), loaded via one <script type="module"> tag — no npm install, no framework required. A layout attribute picks the presentation (list/cards now; calendar deferred).
• Should this live in ote-tools, as an npm package, or both?: lives in ote-tools (apps/embed), distributed as a hosted script from tools.opentechevents.org/embed/ote-events.js rather than an npm package — matches "usable on static sites and simple CMS pages" without adding an install step. Publishing to npm too (for bundler-based consumers, or a React wrapper) is possible later but wasn't needed for this MVP.
• Client-side vs. build-time fetching: client-side only for now, per feed URL you point it at. Build-time/static generation is left as a listed follow-up.
• CORS/feed availability: a fetch failure renders a visible, human-readable error state in the widget rather than failing silently.

Multi-feed, filters (tag/location/language/date/community), and the calendar layout are explicitly out of scope for this MVP, per the non-goals above.

[hhkaos]

✅ Built and live: the embeddable widget is at https://tools.opentechevents.org/embed/, docs/data/tools.json updated to working.

The widget's actual code lives in ote-tools ("phase 2: the web dashboard/editor/previewer/embeddable widget"), not in this repo — this issue tracked "should this exist", and it does now. Follow-up bugs and UX improvements (Spanish i18n, an event-detail modal with a real "add to calendar" action, toning down the always-visible timezone, meaningful link text for online-event URLs) are filed there instead, where the actual implementation is.

Closing as delivered.