Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
 logan
|
20c337651f |
@@ -6,22 +6,6 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
|
||||
|
||||
YellowJacket is a cross-platform desktop music player built with Go (backend) and TypeScript/Lit (frontend), using the Wails framework to bridge them. It supports MP3, FLAC, OGG Vorbis, and WAV playback.
|
||||
|
||||
**The three prose documents are split by reader, not by topic** (#50).
|
||||
`README.md` is the landing page and answers *a user's* questions only —
|
||||
what it does, which channel installs it on which platform, where its
|
||||
data lives — with three screenshots in `docs/images/`, captured from the
|
||||
fixture library (`make sandbox-seed NAME=default` → `make dev-headless
|
||||
SEED=default`) so they can be retaken by anyone. `CONTRIBUTING.md` holds
|
||||
what used to be the second half of that README — prerequisites, the
|
||||
system libraries, the build and codegen commands, which verification
|
||||
tier a change demands, the tracker workflow and the commit grammar. This
|
||||
file stays the deep reference both of them point at, and is the only one
|
||||
of the three that explains *why* a shape is what it is. A fact that
|
||||
belongs to a user goes in one place; the packaging channels keep their
|
||||
own documents (`packaging/*/README.md`, `docs/android-release.md`) and
|
||||
are linked rather than summarised, because a version-restart note copied
|
||||
into the README is a second copy to keep true.
|
||||
|
||||
## Issues
|
||||
|
||||
**The tracker is the source of truth for what is wanted and what is
|
||||
@@ -1486,6 +1470,28 @@ live**: a scrim over a menu item is that item's text surface, and the
|
||||
14px spends its weight below the last legible label, measured at 9.9:1
|
||||
on the light ramp, whose `bgElevated` is `#e9ecef`.
|
||||
|
||||
**And the phone has two sheets, so that rule is one file both read**
|
||||
(#210). `bottom-nav`'s "More" is capped at the same 85vh and overflows
|
||||
for the same reason — measured at 424x439 with eight destinations,
|
||||
`scrollHeight` 412 against `clientHeight` 373, and eleven items at 48px
|
||||
would be 528, since #25 makes the count the user's. So the two layers
|
||||
live in `styles/sheet-scroll.css.ts` and each host says only what is
|
||||
local to it: the colour, handed over as `--yj-sheet-surface` on the same
|
||||
box, because the nav sheet paints the sidebar's `--yj-bg-surface` and
|
||||
the context sheet the menus' `--yj-bg-elevated` — a shared rule that
|
||||
hard-coded either would draw that seam across the other one.
|
||||
|
||||
The half that is not the fade is what makes it visible: **nothing inside
|
||||
the sheet may repaint the surface**, because these are background layers
|
||||
on the scroller and an opaque child covers them. `menu-surface` already
|
||||
had it from the other side (`.context-menu-panel[data-sheet]` is
|
||||
`background-color: transparent`); `app-sidebar`'s host paints
|
||||
`--yj-bg-surface`, which in the shell is its own background and in the
|
||||
sheet is a second copy of the sheet's, so `bottom-nav` turns it off.
|
||||
Measured at 424x439 with the fade adopted and that rule missing: a flat
|
||||
52,58,64 to the bottom edge with 39px still below, which is the defect
|
||||
unchanged and every assertion about `background-attachment` passing.
|
||||
|
||||
**The playlist submenu is a sheet too, and it had to be.** It is a
|
||||
`placement="right-start"` flyout, and making the menu full-width moved
|
||||
its anchor — measured at x −182 to 0, entirely off-screen, so "Add to
|
||||
|
||||
-173
@@ -1,173 +0,0 @@
|
||||
# Contributing to YellowJacket
|
||||
|
||||
This is the contributor's half of the [README](README.md): how to build it, how
|
||||
to check a change, and how a change gets in. [`CLAUDE.md`](CLAUDE.md) is the
|
||||
deep reference — the architecture, and the reasons behind the shape of it —
|
||||
and is worth reading before a change of any size, because most of this
|
||||
codebase's traps are written down there and nowhere else.
|
||||
|
||||
## Building from source
|
||||
|
||||
YellowJacket is [Go](https://go.dev/) with a [Lit](https://lit.dev/)/TypeScript
|
||||
frontend, bridged by [Wails v3](https://wails.io/).
|
||||
|
||||
| Tool | Version |
|
||||
|------|---------|
|
||||
| Go | 1.25+ |
|
||||
| Node.js | 22+ |
|
||||
| pnpm | 10+ |
|
||||
| Wails CLI | v3 — vendored, no install needed (`go tool wails3`) |
|
||||
|
||||
The Wails v3 CLI resolves from the `tool` block in `go.mod`, so there is nothing
|
||||
to install globally; `make setup` fetches it with the rest of the tooling.
|
||||
|
||||
On Linux, install the system libraries Wails needs. v3 builds against GTK4 +
|
||||
WebKitGTK 6.0 by default:
|
||||
|
||||
```bash
|
||||
sudo apt-get install libasound2-dev libgtk-4-dev libwebkitgtk-6.0-dev # Debian/Ubuntu
|
||||
sudo pacman -S alsa-lib gtk4 webkitgtk-6.0 # Arch
|
||||
```
|
||||
|
||||
A machine without `webkitgtk-6.0` can still build with `-tags gtk3` against the
|
||||
older WebKit2GTK 4.1 stack, but that is an escape hatch, not what CI or a
|
||||
release builds. macOS and Windows need no extra system packages. Run
|
||||
`go tool wails3 doctor` to check your environment.
|
||||
|
||||
```bash
|
||||
make setup # install tooling, frontend packages and the git hooks
|
||||
make dev # run with hot-reload
|
||||
make build-dev # debug build with symbols
|
||||
make build-prod # production build (stripped and trimmed)
|
||||
make android # the arm64 APK, into bin/
|
||||
```
|
||||
|
||||
The `Makefile` is the front door and carries a one-line description against
|
||||
each target; `Taskfile.yml` and `build/<platform>/Taskfile.yml` are the build
|
||||
implementation behind it and are not called directly.
|
||||
|
||||
## Generated code
|
||||
|
||||
Two generators run from `go generate ./...`, which `make generate` wraps:
|
||||
**sqlc** turns `backend/database/sql/queries/` into Go in
|
||||
`backend/database/sql/sqlcgen/`, and **templ** turns `.templ` files into
|
||||
`*_templ.go` beside them. Never edit either output by hand — run
|
||||
`make generate` after touching a `.sql` or a `.templ` file.
|
||||
|
||||
The TypeScript bindings in `frontend/bindings/` are generated by `wails3`
|
||||
rather than by `go generate`, so they are a separate step: `make bindings`
|
||||
regenerates them and `make bindings-check` fails if they are stale.
|
||||
`frontend/src/events.ts` is generated too, from `backend/events/events.go`.
|
||||
|
||||
A pre-commit hook checks that all of this is fresh, so the usual way to meet it
|
||||
is a failing commit rather than a bug.
|
||||
|
||||
## Checking a change
|
||||
|
||||
Run the tier the change actually demands, not the cheapest one.
|
||||
|
||||
| Change | Command |
|
||||
|---|---|
|
||||
| Go | `make lint` and `make test` — both cover all three build configurations |
|
||||
| A frontend component or store | `make ui-test` (Vitest in a real Chromium, no backend) |
|
||||
| A user-visible flow | `make e2e`, against a running `make dev-headless` |
|
||||
| CSS | `make css-check` — see the Chrome 113 note below |
|
||||
| Anything cosmetic | look at a screenshot; several bugs here were invisible to every assertion and obvious in an image |
|
||||
|
||||
`make test` needs the fixture library, which is generated rather than
|
||||
committed — it runs `make testdata` itself (about a second).
|
||||
|
||||
The end-to-end tier drives the real app with no display at all: `make
|
||||
dev-headless` starts it in the background on `:34115` (add `SEED=<name>` for a
|
||||
seeded library, built by `make sandbox-seed NAME=<name>`), `make dev-logs` tails
|
||||
it and `make dev-stop` stops it. **Check the port before starting one** — if
|
||||
`:34115` is already answering, someone else's app is there, and a green result
|
||||
about their build is worse than no result.
|
||||
|
||||
Two smaller checks exist because the failure they catch is silent:
|
||||
`make bindings-check` (stale generated bindings) and `make css-check`, which is
|
||||
two passes — one fails on a `css` literal ended early by a backtick inside a
|
||||
comment, the other on a nested CSS rule that begins with a bare element
|
||||
selector. Chrome 113 is what the reference Android device renders with, and it
|
||||
drops such a rule without a word.
|
||||
|
||||
`make vulncheck` runs govulncheck over the module.
|
||||
|
||||
## The issue tracker is the source of truth
|
||||
|
||||
Work is described by issues before it is described by branches, and the tracker
|
||||
is shared with people who cannot see your terminal.
|
||||
|
||||
- **Search before starting**, closed issues included: `./scripts/issue.sh search
|
||||
<terms>`. "That was fixed three weeks ago" is the cheapest possible answer.
|
||||
- **Claim before the first edit**, not before the commit:
|
||||
`./scripts/issue.sh claim <n>` sets the assignee, applies `Status/In Progress`
|
||||
and comments with the branch, so the work is visibly taken *while it is being
|
||||
done*. It refuses if somebody else holds it — talk to them rather than working
|
||||
around it.
|
||||
- **If no issue covers the work, open one first** (`./scripts/issue.sh new`).
|
||||
- **Findings get filed.** A bug tripped over on the way to something else is an
|
||||
issue with a reproduction, not a wider diff and not a sentence in a chat log.
|
||||
- **#73 is the roadmap** and states the order the backlog should be worked in.
|
||||
|
||||
`scripts/issue.sh` is the whole interface (`list`, `mine`, `search`, `show`,
|
||||
`new`, `claim`, `unclaim`, `comment`, `close`, `label`, `depends`, `labels`) and
|
||||
wants a `GITEA_TOKEN` with `write:issue`. The labels are a taxonomy rather than
|
||||
tags: `Kind/*`, `Area/*`, `Priority/*`, `Platform/*`, plus `Reviewed/*` and
|
||||
`Status/*`, of which the last two are exclusive scopes.
|
||||
|
||||
## Commits and pull requests
|
||||
|
||||
`main` is protected, so a branch and a PR are the only way in. Branch from
|
||||
`origin/main`, and name the branch after the issue (`fix/140-…`, `feat/25-…`).
|
||||
|
||||
Commit subjects are [Conventional Commits](https://www.conventionalcommits.org/)
|
||||
— `type(scope): subject`, imperative, ≤72 characters — and are enforced by a
|
||||
`commit-msg` hook and by CI (`make commit-check`). This is load-bearing rather
|
||||
than decorative: semantic-release reads the **type** to decide the next version,
|
||||
so a CI-only change is `ci:` and never `fix(ci):`, which would ship a patch
|
||||
release. `make release-dry` prints what a release would cut right now.
|
||||
|
||||
**The closing keyword goes in the commit body**, one issue per line, because
|
||||
Gitea parses commit messages that reach `main` and does not parse the PR body:
|
||||
|
||||
```
|
||||
docs: rewrite the README as a landing page
|
||||
|
||||
<why>
|
||||
|
||||
Closes #50
|
||||
```
|
||||
|
||||
A PR body carries a commit-to-issue table, the verification you actually ran
|
||||
(with results), and a `Closes` list for whoever reads it.
|
||||
|
||||
## Style
|
||||
|
||||
- **Go** — golangci-lint v2, strict: `err113` (static errors), `nlreturn`,
|
||||
`wsl_v5`, `godot`, `sloglint`, `perfsprint`, and imports grouped stdlib →
|
||||
third-party → `yellowjacket/…` by gci.
|
||||
- **TypeScript** — strict mode, no implicit `any`, no unused locals or
|
||||
parameters.
|
||||
- Match the surrounding code. Where `CLAUDE.md` explains why something is shaped
|
||||
the way it is, that shape is load-bearing and there is usually a test pinning
|
||||
it.
|
||||
|
||||
Hooks do most of the enforcing (`lefthook.yml`, installed by `make setup`):
|
||||
pre-commit runs vet, lint, the codegen checks, the frontend typecheck and the
|
||||
two CSS checks in parallel; pre-push runs the Go suite and the UI tier,
|
||||
deliberately one after the other rather than together.
|
||||
|
||||
## Where the rest of the documentation is
|
||||
|
||||
- [`CLAUDE.md`](CLAUDE.md) — architecture and constraints, in depth.
|
||||
- [`docs/PROFILING.md`](docs/PROFILING.md) — Go pprof and frontend profiling.
|
||||
- [`docs/android-release.md`](docs/android-release.md) — the APK, its signing
|
||||
key, and what the release workflow checks.
|
||||
- [`docs/index-cache.md`](docs/index-cache.md) — the search-index build cache
|
||||
and why it has a snapshot.
|
||||
- [`packaging/arch/README.md`](packaging/arch/README.md),
|
||||
[`packaging/homebrew/README.md`](packaging/homebrew/README.md) — the two
|
||||
package channels.
|
||||
- `.planning/` — design documents and measured history, not a queue. The queue
|
||||
is the tracker.
|
||||
@@ -2,139 +2,112 @@
|
||||
|
||||
*Music how it was meant to bee.*
|
||||
|
||||
YellowJacket plays the music you already own. Point it at your folders and it
|
||||
scans them, reads the tags and the cover art, and gives you a library you can
|
||||
browse, search, queue and tidy up — on your own machine, with no account, no
|
||||
streaming service and no telemetry.
|
||||
YellowJacket is a fast, cross-platform desktop music player for your local
|
||||
collection. It plays your files, keeps your library tidy, and helps you discover
|
||||
and organize your music — all in a clean, responsive interface. No accounts, no
|
||||
streaming, no telemetry: just your music on your machine.
|
||||
|
||||
It plays **MP3**, **FLAC**, **OGG Vorbis** and **WAV**, on **Linux** and
|
||||
**Android**, and builds from source on **macOS**.
|
||||
Runs on **Linux**, **macOS**, and **Windows**.
|
||||
|
||||
|
||||
## Features
|
||||
|
||||
## What it does
|
||||
### Play your music
|
||||
- Plays **MP3, FLAC, OGG Vorbis, and WAV**
|
||||
- Play, pause, seek, and volume control with a mute toggle
|
||||
- Gapless, glitch-free seeking backed by a read-ahead buffer
|
||||
- A queue you can add to, reorder, and shuffle, with play-next support
|
||||
- Shuffle and repeat (off / all / one)
|
||||
- Picks up right where you left off — remembers your track, position, and volume between sessions
|
||||
- Media-key and MPRIS support on Linux, so your desktop's playback controls just work
|
||||
|
||||
**Plays your files.** Play, pause, seek and volume with a mute toggle; a
|
||||
read-ahead buffer so seeking is instant rather than gappy; a queue you can add
|
||||
to, reorder and shuffle, with play-next; shuffle and repeat (off / all / one).
|
||||
It remembers the track, the position and the queue between sessions, and it
|
||||
answers your desktop's media keys — MPRIS on Linux, a media notification and
|
||||
lock-screen controls on Android.
|
||||
### Keep your library organized
|
||||
- Point it at your music folders and it scans them automatically
|
||||
- Reads tags and embedded cover art, and de-duplicates artwork so it isn't stored twice
|
||||
- Incremental sync — only new or changed files get reprocessed, and deleted files are cleaned up
|
||||
- Browse by **album**, **artist**, or **genre**, or search across everything
|
||||
- Mark favorites and see what you've been listening to with play history
|
||||
- Edit track tags directly when something's off
|
||||
|
||||
**Keeps the library tidy.** It scans the folders you give it and rescans only
|
||||
what changed, so a big library costs its full scan once. It de-duplicates
|
||||
embedded cover art rather than storing the same image a hundred times, notices
|
||||
files that have gone away, and spots duplicate tracks. Browse by album, artist
|
||||
or genre, search across everything, mark favourites, and see what you have been
|
||||
playing.
|
||||
### Playlists
|
||||
- Create playlists, drag tracks in, and reorder them
|
||||
- **Smart playlists** that build themselves from rules (by genre, rating, play count, and more)
|
||||
- Pin a default playlist and spot duplicate tracks at a glance
|
||||
|
||||
**Playlists, and playlists that write themselves.** Drag tracks in and reorder
|
||||
them, or describe what you want — genre, play count, how long since you played
|
||||
it — and let a smart playlist keep itself up to date.
|
||||
|
||||
**Explore and auto-tag, from the MusicBrainz catalog.** Explore browses artists,
|
||||
releases and genres from the catalog rather than only from what you own, so an
|
||||
album page can tell you that you have nine of its twelve tracks. Auto-tag
|
||||
matches your files against MusicBrainz and fills in the metadata that is
|
||||
missing, with a review step before anything is written to disk. Lyrics search
|
||||
finds a track from a line you remember.
|
||||
|
||||
Explore needs its catalog, which is a one-off ~0.6 GB download from
|
||||
**Settings → Search Index**. It asks first on a metered connection, and
|
||||
everything else in the app works without it.
|
||||
### Discover and clean up (powered by MusicBrainz)
|
||||
- **Explore** — browse artists, releases, and genres from the MusicBrainz catalog, not just what's already in your library
|
||||
- **Auto-tag** — match your files against MusicBrainz to fill in correct artist, album, and track metadata, with a review step before anything is written
|
||||
- **Lyrics search** — find a track by a line you remember
|
||||
|
||||
## Install
|
||||
|
||||
Every download comes from the
|
||||
Download the latest build for your platform from the
|
||||
[releases page](https://git.ljones.me/yonlu/yellowjacket/releases).
|
||||
|
||||
### Linux
|
||||
| Platform | Download |
|
||||
|----------|----------|
|
||||
| Linux | `yellowjacket-linux-amd64` |
|
||||
| macOS | `yellowjacket-darwin-universal.app.zip` (Apple Silicon + Intel) |
|
||||
| Windows | `yellowjacket-windows-amd64.exe` |
|
||||
|
||||
Download `yellowjacket-<version>-linux-amd64.tar.gz` from the latest release and
|
||||
unpack it. It holds the binary, a `.desktop` entry and an icon.
|
||||
Prefer to build it yourself? See [Building from source](#building-from-source).
|
||||
|
||||
On **Arch**, install it from the package registry instead and get updates with
|
||||
the rest of your system — the one-time key import and `pacman.conf` block are in
|
||||
[`packaging/arch/README.md`](packaging/arch/README.md):
|
||||
|
||||
```bash
|
||||
sudo pacman -Sy yellowjacket
|
||||
```
|
||||
|
||||
### Android
|
||||
|
||||
Install the APK from the release page, or from the URL below, which always
|
||||
points at the newest build:
|
||||
|
||||
```
|
||||
https://git.ljones.me/api/packages/yonlu/generic/yellowjacket-android/latest/yellowjacket.apk
|
||||
```
|
||||
|
||||
That URL needs no credentials, so [Obtainium](https://obtainium.imranr.dev/) can
|
||||
poll it directly and keep the app up to date. The build is `arm64-v8a` only, and
|
||||
[`docs/android-release.md`](docs/android-release.md) says why.
|
||||
|
||||
### macOS
|
||||
|
||||
Homebrew builds it from source on your own Mac — there is no prebuilt `.app`,
|
||||
because a signed macOS bundle needs a macOS machine to produce it and the
|
||||
release runner is a Linux container.
|
||||
|
||||
```bash
|
||||
brew install shadow-puppet/yellowjacket/yellowjacket
|
||||
```
|
||||
|
||||
See [`packaging/homebrew/README.md`](packaging/homebrew/README.md).
|
||||
|
||||
### Windows
|
||||
|
||||
Not published. It cross-compiles cleanly, but no Windows build of this app has
|
||||
ever been *run*, and nothing here can exercise one — so shipping it would be a
|
||||
promise that cannot be kept. You can still build it yourself: see
|
||||
[`CONTRIBUTING.md`](CONTRIBUTING.md).
|
||||
|
||||
### Coming from a 1.x install?
|
||||
|
||||
Versions restarted at **0.0.1** when releases became automatic, which every
|
||||
package manager reads as a downgrade. It costs one reinstall, once — the details
|
||||
are with each channel: [Homebrew](packaging/homebrew/README.md#upgrading-from-1x-needs-a-reinstall-once),
|
||||
[Android](docs/android-release.md#the-1x-installs-cannot-be-upgraded-to-00x).
|
||||
|
||||
## First run
|
||||
## Getting started
|
||||
|
||||
1. Launch YellowJacket.
|
||||
2. Add the folder your music lives in — the first-run wizard asks, and
|
||||
**Settings → Libraries** is where you add more later.
|
||||
3. Watch the scan finish. It reports progress, and you can browse while it runs.
|
||||
4. Queue something and press play.
|
||||
2. Open **Settings** and add the folder(s) where your music lives.
|
||||
3. Let the initial scan finish — you'll see progress as it works.
|
||||
4. Browse by album, artist, or genre, queue something up, and press play.
|
||||
|
||||
Your library and settings stay on your machine:
|
||||
Your library and settings are stored locally:
|
||||
|
||||
| | Linux / macOS | Windows |
|
||||
|---|---|---|
|
||||
| Config | `~/.config/yellowjacket/` | `%LOCALAPPDATA%\yellowjacket\config` |
|
||||
| Library data | `~/.local/share/yellowjacket/` | `%LOCALAPPDATA%\yellowjacket\data` |
|
||||
|
||||
Setting `YJ_HOME` moves both, which is how you keep a second library separate.
|
||||
## Building from source
|
||||
|
||||
## More screenshots
|
||||
YellowJacket is built with [Go](https://go.dev/) and a
|
||||
[Lit](https://lit.dev/)/TypeScript frontend, bridged by the
|
||||
[Wails](https://wails.io/) framework.
|
||||
|
||||
An album page knows what you own, and says so:
|
||||
**Prerequisites**
|
||||
|
||||
|
||||
| Tool | Version |
|
||||
|------|---------|
|
||||
| Go | 1.25+ |
|
||||
| Node.js | 22+ |
|
||||
| pnpm | 10+ |
|
||||
| Wails CLI | v3 — vendored, no install needed (`go tool wails3`) |
|
||||
|
||||
The home page suggests somewhere to start rather than opening on a wall of
|
||||
everything:
|
||||
The Wails v3 CLI resolves from the `tool` block in `go.mod`, so there is nothing
|
||||
to install globally; `make setup` fetches it with the rest of the tooling.
|
||||
|
||||
|
||||
On Linux, install the system libraries Wails needs. v3 builds against GTK4 +
|
||||
WebKitGTK 6.0 by default:
|
||||
|
||||
## Contributing, and the rest of the documentation
|
||||
```bash
|
||||
sudo apt-get install libasound2-dev libgtk-4-dev libwebkitgtk-6.0-dev # Debian/Ubuntu
|
||||
sudo pacman -S alsa-lib gtk4 webkitgtk-6.0 # Arch
|
||||
```
|
||||
|
||||
- [`CONTRIBUTING.md`](CONTRIBUTING.md) — build it from source, run the tests,
|
||||
and how a change gets in.
|
||||
- [`CLAUDE.md`](CLAUDE.md) — the deep reference: the architecture and the reasons
|
||||
behind the shape of it.
|
||||
- [The issue tracker](https://git.ljones.me/yonlu/yellowjacket/issues) is what
|
||||
is wanted and what is being worked on; **#73** is the roadmap.
|
||||
- [Releases](https://git.ljones.me/yonlu/yellowjacket/releases) double as the
|
||||
changelog — every one is generated from the commits it contains.
|
||||
A machine without `webkitgtk-6.0` can still build with `-tags gtk3` against the
|
||||
older WebKit2GTK 4.1 stack, but that is an escape hatch, not what CI or a
|
||||
release builds.
|
||||
|
||||
macOS and Windows need no extra system packages. Run `go tool wails3 doctor` to
|
||||
check your environment.
|
||||
|
||||
**Build**
|
||||
|
||||
```bash
|
||||
make setup # install tooling and git hooks
|
||||
make dev # run with hot-reload
|
||||
make build-prod # produce a release binary
|
||||
```
|
||||
|
||||
More detail for contributors lives in [`CLAUDE.md`](./CLAUDE.md) — the
|
||||
architecture, the conventions and the reasons behind them. What is
|
||||
being worked on is [the issue
|
||||
tracker](https://git.ljones.me/yonlu/yellowjacket/issues); #73 is the
|
||||
roadmap.
|
||||
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 83 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 285 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 128 KiB |
@@ -4,6 +4,7 @@ import '@awesome.me/webawesome/dist/components/icon/icon.js';
|
||||
import '@awesome.me/webawesome/dist/components/drawer/drawer.js';
|
||||
import type WaDrawer from '@awesome.me/webawesome/dist/components/drawer/drawer.js';
|
||||
import { designTokens } from '../../styles/tokens.css';
|
||||
import { sheetScrollFade } from '../../styles/sheet-scroll.css';
|
||||
import '../sidebar/app-sidebar.js';
|
||||
import { nameDialog } from '@utils/name-dialog';
|
||||
import { ICON_PLAYLIST } from '@utils/icon-language';
|
||||
@@ -167,6 +168,15 @@ export class BottomNav extends LitElement {
|
||||
overflow: hidden;
|
||||
}
|
||||
|
||||
/* And this list does not fit (#210): measured at 424x439 with
|
||||
the seed's eight destinations, the body is scrollHeight 412
|
||||
against clientHeight 373, and eleven items at 48px would be
|
||||
528 -- the count is the user's since #25. So the sheet says
|
||||
where the fold is, with styles/sheet-scroll.css's two layers
|
||||
rather than a second answer to the question #207 settled for
|
||||
the context sheet. The colour is the local half: the sidebar
|
||||
paints --yj-bg-surface, so the cover does too, or the fade
|
||||
draws the menus' grey across the bottom of this one. */
|
||||
wa-drawer::part(body) {
|
||||
padding: 0;
|
||||
/* A scroll that reaches the end of this list must not
|
||||
@@ -177,6 +187,23 @@ export class BottomNav extends LitElement {
|
||||
on a gesture-navigation phone -- the same allowance the
|
||||
bar itself makes above. */
|
||||
padding-bottom: env(safe-area-inset-bottom, 0);
|
||||
--yj-sheet-surface: var(--yj-bg-surface, #212529);
|
||||
${sheetScrollFade}
|
||||
}
|
||||
|
||||
/* And the sheet paints that surface once. The sidebar's host
|
||||
paints the same grey -- which in the shell is the sidebar's
|
||||
own background and here is a second, opaque copy of the
|
||||
sheet's, drawn *over* the body's layers. So the fade was
|
||||
painted and then covered: measured at 424x439 before this
|
||||
rule, the last 32px read a flat 52,58,64 with 39px still
|
||||
below. menu-surface meets the same requirement from the
|
||||
other side, where .context-menu-panel[data-sheet] is
|
||||
background-color: transparent; nothing changes visually
|
||||
here, because the colour underneath is the one being
|
||||
removed. */
|
||||
app-sidebar {
|
||||
background-color: transparent;
|
||||
}
|
||||
|
||||
/* A sheet is dragged at with a thumb, so it says where its top
|
||||
|
||||
@@ -65,6 +65,7 @@ import '@awesome.me/webawesome/dist/components/popup/popup.js';
|
||||
import '@awesome.me/webawesome/dist/components/dialog/dialog.js';
|
||||
import type WaPopup from '@awesome.me/webawesome/dist/components/popup/popup.js';
|
||||
|
||||
import { sheetScrollFade } from '../../styles/sheet-scroll.css';
|
||||
import { PHONE_QUERY } from '@utils/breakpoints';
|
||||
import { nameDialogsIn } from '@utils/name-dialog';
|
||||
|
||||
@@ -164,46 +165,17 @@ export class MenuSurface extends LitElement {
|
||||
and worse when the cut lands on a row boundary, where the
|
||||
sheet ends in a clean edge that reads as the end of the list.
|
||||
|
||||
Two layers, and the *order* is what asks the question: a
|
||||
shadow pinned to the bottom of the box (attachment scroll),
|
||||
and over it a cover of the sheet's own colour painted at the
|
||||
end of the *content* (attachment local), which therefore
|
||||
scrolls up over the shadow and hides it exactly when there is
|
||||
nothing more to see. So the affordance is absent on a menu
|
||||
that fits, present the moment one does not, and gone again at
|
||||
the end of the list -- with no scroll listener, no
|
||||
measurement, and nothing reaching into wa-dialog's shadow
|
||||
root for the scroller. background-attachment is Chrome 4;
|
||||
the reference device is Chrome 113.
|
||||
|
||||
**The curve is steep because the rows under it stay live.**
|
||||
A scrim over a menu item is that item's text surface, and
|
||||
this app's rule is that text clears 4.5:1 on every surface it
|
||||
can sit on -- which the light ramp, whose bgElevated is
|
||||
#e9ecef, is what makes non-theoretical. A row is 48px with
|
||||
its label centred, so 32px of scrim that is already down to
|
||||
a quarter strength at 14px reaches y-centre at about 0.06 and
|
||||
spends its weight on the strip below the last legible label.
|
||||
Measured on the dark ramp at x=300, flat 52,58,64 throughout
|
||||
before: 50,56,62 at y=330, 33,37,40 at y=350 and 22,24,27 at
|
||||
the bottom edge, and flat again at the end of the list. The
|
||||
light ramp puts 9.9:1 on the last label. */
|
||||
The two layers that say it live in styles/sheet-scroll.css
|
||||
(#210), because the phone has a second sheet -- bottom-nav's
|
||||
"More" -- which overflows for the same reason and must not
|
||||
arrive at its own answer for what a fold looks like. What is
|
||||
local to this sheet is the colour the cover is painted in:
|
||||
the menus' elevated grey, handed over as --yj-sheet-surface
|
||||
on the same box. */
|
||||
wa-dialog::part(body) {
|
||||
padding: 0;
|
||||
overflow-y: auto;
|
||||
background:
|
||||
linear-gradient(
|
||||
var(--yj-bg-elevated, #343a40),
|
||||
var(--yj-bg-elevated, #343a40)
|
||||
)
|
||||
bottom / 100% 32px no-repeat local,
|
||||
linear-gradient(
|
||||
to top,
|
||||
rgba(0, 0, 0, 0.6) 0%,
|
||||
rgba(0, 0, 0, 0.25) 45%,
|
||||
rgba(0, 0, 0, 0) 100%
|
||||
)
|
||||
bottom / 100% 32px no-repeat scroll;
|
||||
--yj-sheet-surface: var(--yj-bg-elevated, #343a40);
|
||||
${sheetScrollFade}
|
||||
}
|
||||
|
||||
/* A sheet is dragged at with a thumb, so it says where its top
|
||||
|
||||
@@ -0,0 +1,68 @@
|
||||
import { css } from 'lit';
|
||||
|
||||
/**
|
||||
* A bottom sheet whose body scrolls says so, in one rule both sheets
|
||||
* read.
|
||||
*
|
||||
* The app has two sheets — `menu-surface`'s context menu (#60) and
|
||||
* `bottom-nav`'s "More" navigation (#71) — and both are capped at 85vh,
|
||||
* because a surface covering the whole screen is a page rather than a
|
||||
* sheet. So both overflow, and both used to overflow *silently*: the
|
||||
* menu at 424x439 with eight items ending at y=470 (#207), the nav
|
||||
* sheet at the same viewport with `scrollHeight` 412 against
|
||||
* `clientHeight` 373 (#210). Where the cut lands on a row boundary the
|
||||
* sheet ends in a clean edge that reads as the end of the list.
|
||||
*
|
||||
* The mechanism is #207's and is unchanged by being shared: two
|
||||
* background layers on the scrolling box, whose *attachments* are the
|
||||
* conditionality. A cover of the sheet's own colour is painted at the
|
||||
* end of the *content* (`local`) over a shadow pinned to the box
|
||||
* (`scroll`), so the cover scrolls up over the shadow exactly when
|
||||
* there is nothing more to see. The fade is therefore absent on a sheet
|
||||
* that fits, present the moment one does not, and gone again at the end
|
||||
* of the list — with no scroll listener, no measurement and nothing
|
||||
* reaching into another component's shadow root for the scroller.
|
||||
* `background-attachment` is Chrome 4; the reference device is
|
||||
* Chrome 113.
|
||||
*
|
||||
* Three things about it are load-bearing.
|
||||
*
|
||||
* **The cover takes the sheet's own colour, from a custom property.**
|
||||
* The two sheets are different greys — the nav sheet paints
|
||||
* `--yj-bg-surface`, because it holds the sidebar and two greys in one
|
||||
* sheet is a seam across the middle of it, while the context sheet
|
||||
* paints the menus' `--yj-bg-elevated`. A shared rule that hard-coded
|
||||
* either would put that seam back on the other one, so the host sets
|
||||
* `--yj-sheet-surface` on the same box and this reads it.
|
||||
*
|
||||
* **The curve is steep because the rows under it stay live.** A scrim
|
||||
* over a menu item is that item's text surface, and this app's rule is
|
||||
* that text clears 4.5:1 on every surface it can sit on — which the
|
||||
* light ramp, whose `bgElevated` is `#e9ecef`, makes non-theoretical. A
|
||||
* row is 48px with its label centred, so 32px of scrim already down to
|
||||
* a quarter strength at 14px spends its weight on the strip below the
|
||||
* last legible label: measured at 9.9:1 on that label on the light ramp,
|
||||
* against 5.0:1 for a linear 48px draft at 0.8. The dark-ramp pixel
|
||||
* table is in `.planning/NOTES.md` (2026-08-23).
|
||||
*
|
||||
* **The box is declared a scroller here too.** `overflow-y: auto` is
|
||||
* part of the same statement rather than left to each host: a fade over
|
||||
* a box that is not the scroller is a fade that never moves, and the
|
||||
* component tier asserts the pair together for that reason.
|
||||
*/
|
||||
export const sheetScrollFade = css`
|
||||
overflow-y: auto;
|
||||
background:
|
||||
linear-gradient(
|
||||
var(--yj-sheet-surface, #343a40),
|
||||
var(--yj-sheet-surface, #343a40)
|
||||
)
|
||||
bottom / 100% 32px no-repeat local,
|
||||
linear-gradient(
|
||||
to top,
|
||||
rgba(0, 0, 0, 0.6) 0%,
|
||||
rgba(0, 0, 0, 0.25) 45%,
|
||||
rgba(0, 0, 0, 0) 100%
|
||||
)
|
||||
bottom / 100% 32px no-repeat scroll;
|
||||
`;
|
||||
@@ -243,6 +243,62 @@ describe('bottom-nav', () => {
|
||||
expect(getComputedStyle(body).overscrollBehaviorY).toBe('contain');
|
||||
});
|
||||
|
||||
it('says where the fold is, in the sheet\'s own colour', async () => {
|
||||
const el = await fixture<Nav>('bottom-nav');
|
||||
const drawer = shadow<HTMLElement & { open: boolean }>(el, 'wa-drawer');
|
||||
|
||||
if (!drawer) throw new Error('no drawer');
|
||||
|
||||
const shown = once(drawer, 'wa-after-show');
|
||||
|
||||
shadow<HTMLButtonElement>(el, '[data-testid="tab-more"]')?.click();
|
||||
await shown;
|
||||
|
||||
const body = drawer.shadowRoot?.querySelector('[part~="body"]');
|
||||
|
||||
if (!body) throw new Error('no body part to scroll');
|
||||
|
||||
const style = getComputedStyle(body);
|
||||
|
||||
// #210. This list does not fit the phone — measured at 424x439,
|
||||
// `scrollHeight` 412 against `clientHeight` 373 with the seed's
|
||||
// eight destinations — and said nothing about it, which where the
|
||||
// cut lands on a row boundary reads as the end of the list.
|
||||
//
|
||||
// The mechanism is #207's and is asserted the same way: the pair of
|
||||
// attachments *is* the feature. A cover of the sheet's own colour
|
||||
// painted at the end of the content (`local`) over a shadow pinned
|
||||
// to the box (`scroll`), so the fade is absent on a sheet that
|
||||
// fits, present the moment one does not, and gone again at the end.
|
||||
expect(
|
||||
style.backgroundAttachment,
|
||||
'the cover must be local and the shadow must not',
|
||||
).toBe('local, scroll');
|
||||
expect(style.backgroundPosition).toBe('50% 100%, 50% 100%');
|
||||
expect(style.backgroundSize).toBe('100% 32px, 100% 32px');
|
||||
|
||||
// And the colour is the local half of a shared rule: this sheet
|
||||
// paints the sidebar's `--yj-bg-surface` (#212529) rather than the
|
||||
// menus' elevated grey, or the fade draws the *other* sheet's
|
||||
// colour across the bottom of this one — which is the seam a
|
||||
// shared fragment would otherwise reintroduce.
|
||||
expect(style.backgroundImage).toMatch(
|
||||
/^linear-gradient\(rgb\(33, 37, 41\), rgb\(33, 37, 41\)\)/,
|
||||
);
|
||||
|
||||
// And nothing paints over it. The sidebar's host carries the same
|
||||
// grey, which inside the sheet is a second opaque copy of the
|
||||
// surface drawn on top of these layers -- measured at 424x439 with
|
||||
// the rule removed, the last 32px read a flat 52,58,64 with 39px
|
||||
// still below, so the fade was painted and covered. That is
|
||||
// `.context-menu-panel[data-sheet]`'s transparency, one sheet over.
|
||||
const sidebar = shadow<HTMLElement>(el, 'app-sidebar');
|
||||
|
||||
if (!sidebar) throw new Error('no sidebar');
|
||||
|
||||
expect(getComputedStyle(sidebar).backgroundColor).toBe('rgba(0, 0, 0, 0)');
|
||||
});
|
||||
|
||||
it('gives the sheet the whole width, which the sidebar does not take', async () => {
|
||||
const el = await fixture<Nav>('bottom-nav');
|
||||
|
||||
|
||||
@@ -254,6 +254,15 @@ describe('menu-surface', () => {
|
||||
// Both sit at the bottom, or the cover hides nothing.
|
||||
expect(style.backgroundPosition).toBe('50% 100%, 50% 100%');
|
||||
expect(style.backgroundSize).toBe('100% 32px, 100% 32px');
|
||||
|
||||
// The layers are shared with `bottom-nav`'s sheet since #210, and
|
||||
// the colour is what each host still says for itself: this one
|
||||
// paints the menus' `--yj-bg-elevated` (#343a40). A shared rule
|
||||
// that hard-coded one grey would draw a seam across the other
|
||||
// sheet, which is why the fragment reads a custom property.
|
||||
expect(style.backgroundImage).toMatch(
|
||||
/^linear-gradient\(rgb\(52, 58, 64\), rgb\(52, 58, 64\)\)/,
|
||||
);
|
||||
});
|
||||
|
||||
/**
|
||||
|
||||
Reference in New Issue
Block a user