Adom Hydrogen (platform base) - widgets/README.md

Overview Files Skills Discover Packages Releases Dependencies Issues1 Breadcrumbs Pull Requests Activity

master

John Lauer 0.5.48: narrow tall layout, no empty mark span, clock pictures d6e9955 1mo ago

A Hydrogen Widget is a small live page in Hydrogen Desktop's Title Bar, served by a program inside your workspace. This one shows the time and date: stacked in the full Title Bar, inline in the compact one. It is a facet of this repo: the bootstrap package installs bin/hydrogen-widget-clock and the shared helper, and the hydrogen-widget.json at the repo root tells Hydrogen it exists. Open it from the Hydrogen Widgets pulldown (the puzzle-piece icon left of the meter) or POST /widgets/open {"id":"clock"}.

hydrogen-widget.json               the facet: id, name, icon, widths, launch, health, docs
bin/hydrogen-widget-clock          the widget: fifteen lines on top of the helper
bin/hydrogen-widget-lib.py         the shared helper: http.server, the two-layout page, the interval cache
bin/hydrogen-widget-marks.py       vendor marks (for widgets that show a provider's numbers)
widgets/widgets.json               the curated list Hydrogen reads (which widgets everyone sees)
widgets/README.md                  this page (linked from the pulldown row)

install.sh copies bin/hydrogen-widget-* into ~/.local/bin, which is where launch.command finds it.

How it sizes itself

The helper's page has two layouts chosen by the slot's height (stacked above 33 px, one row below), and after every render it measures itself on a hidden copy laid out at max-content and posts {hdWidget:{width}} to Hydrogen, which resizes the slot. The pictures above are that measurement: the clock asks for about 55 px tall and 90 px compact. The helper also serves /preview?h=38 and /preview?h=20, its own page in a frame that follows the requested width; the pictures were made from those with headless Chrome at three times scale.

Copy it

Take hydrogen-widget-clock and hydrogen-widget-lib.py, change data() and the render expression, add a hydrogen-widget.json, a page like this one, and an install line. The hydrogen-widget skill has every field, the launch contract, the tall and compact layouts, and how private repos work. The overview with pictures is the Widgets page on the Hydrogen wiki.

# The Clock widget: the smallest Hydrogen Widget, and the one to copy

![The clock in the full Title Bar: time over date](widgets/docs/clock.png)

![The clock in the compact Title Bar: time and date in one row](widgets/docs/clock-compact.png)

A Hydrogen Widget is a small live page in Hydrogen Desktop's Title Bar, served by a program inside your workspace. This one shows the time and date: stacked in the full Title Bar, inline in the compact one. It is a **facet** of this repo: the bootstrap package installs `bin/hydrogen-widget-clock` and the shared helper, and the `hydrogen-widget.json` at the repo root tells Hydrogen it exists. Open it from the Hydrogen Widgets pulldown (the puzzle-piece icon left of the meter) or `POST /widgets/open {"id":"clock"}`.

## The files in this repo that make it a widget

```
hydrogen-widget.json               the facet: id, name, icon, widths, launch, health, docs
bin/hydrogen-widget-clock          the widget: fifteen lines on top of the helper
bin/hydrogen-widget-lib.py         the shared helper: http.server, the two-layout page, the interval cache
bin/hydrogen-widget-marks.py       vendor marks (for widgets that show a provider's numbers)
widgets/widgets.json               the curated list Hydrogen reads (which widgets everyone sees)
widgets/README.md                  this page (linked from the pulldown row)
```

`install.sh` copies `bin/hydrogen-widget-*` into `~/.local/bin`, which is where `launch.command` finds it.

## How it sizes itself

The helper's page has two layouts chosen by the slot's height (stacked above 33 px, one row below), and after every render it measures itself on a hidden copy laid out at max-content and posts `{hdWidget:{width}}` to Hydrogen, which resizes the slot. The pictures above are that measurement: the clock asks for about 55 px tall and 90 px compact. The helper also serves `/preview?h=38` and `/preview?h=20`, its own page in a frame that follows the requested width; the pictures were made from those with headless Chrome at three times scale.

## Copy it

Take `hydrogen-widget-clock` and `hydrogen-widget-lib.py`, change `data()` and the render expression, add a `hydrogen-widget.json`, a page like this one, and an install line. The [hydrogen-widget skill](https://wiki.adom.inc/adom/hydrogen-bootstrap/files/skills/hydrogen-widget/SKILL.md) has every field, the launch contract, the tall and compact layouts, and how private repos work. The overview with pictures is the [Widgets page](https://wiki.adom.inc/adom/hydrogen/files/widgets/README.md) on the Hydrogen wiki.