Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
47 changes: 47 additions & 0 deletions .github/workflows/pages.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,47 @@
name: Pages

# The site lives in site/ and is deployed from here, not from a branch.
# Library code and site code stay apart: site/ has the two pages, the card,
# llms.txt and the domain file, and nothing else in the repository becomes
# a public URL. index.js is copied in at deploy time - the pages import it
# off disk on purpose, so what the site runs is the source that was
# reviewed. Locally, `npm run site` does the same with a symlink.
on:
push:
branches: [main]
workflow_dispatch:

permissions: {}

concurrency:
group: pages
cancel-in-progress: true

jobs:
deploy:
runs-on: ubuntu-latest
permissions:
contents: read
pages: write
id-token: write
environment:
name: github-pages
url: ${{ steps.deploy.outputs.page_url }}
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1

- name: Put the library beside the pages
run: |
cp index.js site/index.js
find site -type f | sort

- uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6.0.0
with:
enablement: true

- uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
with:
path: site

- uses: actions/deploy-pages@368f82528645a54fb793d4d04e342629a3f51346 # v5.0.1
id: deploy
2 changes: 2 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -10,3 +10,5 @@ STATE.md

# publish artifacts
*.tgz
# The site imports the library from beside itself; `npm run site` links it, the deploy copies it.
site/index.js
22 changes: 13 additions & 9 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,10 +11,14 @@ auto.js the script-tag entry: re-exports index.js and initialises it
build.mjs esbuild: dist/tooltip.global.js (IIFE) and dist/tooltip.css
test/place.test.js the geometry suite, node:test, no browser
e2e/tooltip.spec.js the DOM suite, Playwright, real Chromium
index.html the demo page, imports ./index.js off disk
docs/index.html the reference, same
llms.txt the reference again, in one file, for models
og.html / og.png the social card, and the page it is screenshotted from
site/ the website, kept apart from the library:
index.html the demo page, imports ./index.js off disk
docs/index.html the reference, same
llms.txt the reference again, in one file, for models
og.html / og.png the social card, and the page it is screenshotted from
CNAME the domain
.github/workflows/ ci.yml (checks), release.yml (release-please + npm),
pages.yml (deploys site/ with index.js copied in)
```

`index.js` splits in two. `place()` is a pure function of numbers: cursor, pill size, viewport, previous placement in, coordinates and sides out. It has no DOM and no globals, which is why the geometry suite runs with nothing installed and covers thousands of cases in a quarter of a second. Everything else in the file is event plumbing around it: `createTooltip()` wires listeners, measures once per show, and writes one transform per frame.
Expand All @@ -30,13 +34,13 @@ npm ci
npx playwright install chromium # once, for the DOM suite
```

To see the demo and the docs, serve the repo root and open `/` or `/docs/`:
To see the demo and the docs:

```sh
python3 -m http.server 8000
npm run site # links index.js into site/ and serves it on :8000
```

No build step is needed for that. Both pages import `index.js` directly, so what you see is the source you just edited.
Open `/` or `/docs/`. No build step: both pages import `index.js` directly, so what you see is the source you just edited. The deploy does the same copy, so the site never runs anything but the reviewed source.

## Running the checks

Expand All @@ -55,12 +59,12 @@ CI runs exactly those, in that order, on every push and PR. Run them locally fir
1. Branch from `main`.
2. Make the change in `index.js`. If it touches geometry, it goes in `place()` and gets a case in `test/place.test.js`. If it touches wiring, it gets a case in `e2e/tooltip.spec.js`. A fix without a test that would have caught it is not finished.
3. If you changed any JSDoc, run `npm run types` and commit `index.d.ts` with it.
4. If you added or renamed an option, attribute, or `--tip-*` property, update all three references: the README, `docs/index.html`, and `llms.txt`. They are cross-checked by hand before a release and drift is treated as a bug. The docs page reads the property list out of the CSS at load, so a new property shows up there on its own, but it still needs a description in the `WHAT` map in that file.
4. If you added or renamed an option, attribute, or `--tip-*` property, update all three references: the README, `site/docs/index.html`, and `site/llms.txt`. They are cross-checked by hand before a release and drift is treated as a bug. The docs page reads the property list out of the CSS at load, so a new property shows up there on its own, but it still needs a description in the `WHAT` map in that file.
5. Check the size. The number in the README is the minified ESM build, gzipped:
```sh
node -e "const e=require('esbuild'),z=require('zlib');e.build({entryPoints:['index.js'],bundle:true,format:'esm',minify:true,write:false}).then(r=>console.log(z.gzipSync(r.outputFiles[0].contents,{level:9}).length))"
```
If your change moves it past the next tenth of a kilobyte, say so in the PR and update the number everywhere it appears (README, package.json description, both HTML pages, `llms.txt`, `og.html`, and regenerate `og.png` with the command in its header).
If your change moves it past the next tenth of a kilobyte, say so in the PR and update the number everywhere it appears (README, package.json description, both pages in `site/`, `site/llms.txt`, `site/og.html`, and regenerate `site/og.png` with the command in its header).
6. Open a PR against `main`. Describe what changed and why, and what a reviewer should try with a cursor to see it.

## What's welcome
Expand Down
3 changes: 2 additions & 1 deletion package.json
Original file line number Diff line number Diff line change
Expand Up @@ -45,7 +45,8 @@
"test": "node --test",
"lint:pkg": "publint",
"prepublishOnly": "npm run build && npm run types",
"test:e2e": "playwright test"
"test:e2e": "playwright test",
"site": "ln -sfn ../index.js site/index.js && python3 -m http.server -d site 8000"
},
"devDependencies": {
"@playwright/test": "^1.63.0",
Expand Down
File renamed without changes.
File renamed without changes.
10 changes: 5 additions & 5 deletions index.html → site/index.html
Original file line number Diff line number Diff line change
Expand Up @@ -5,12 +5,12 @@
One hand-written file, no build step: it imports ./index.js off disk, so
this is the shipped library running. The reference lives in docs/.

DEPLOY NOTE: this page sits at the repository root beside the library it
imports, so GitHub Pages serves it with Settings > Pages > branch: main,
folder: / and the demo lands at the repo's own URL. Nothing it references
is outside the published tree.
DEPLOY NOTE: the site lives in site/, apart from the library. This page
imports ./index.js, which .github/workflows/pages.yml copies in from the
repository root at deploy time, so the site runs the reviewed source and
nothing else in the repository becomes a public URL.

Locally: python3 -m http.server -> http://localhost:8000/
Locally: npm run site -> http://localhost:8000/
-->
<html lang="en">
<head>
Expand Down
File renamed without changes.
2 changes: 1 addition & 1 deletion og.html → site/og.html
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
all want. The pill in it is the real library showing on a real trigger - the
cursor is the only thing drawn.

Regenerate after a design change (serve the repo root over http first):
Regenerate after a design change (`npm run site` first, it serves site/):

node -e "
const {chromium}=require('playwright-core');
Expand Down
File renamed without changes