diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml new file mode 100644 index 0000000..8b69ef3 --- /dev/null +++ b/.github/workflows/pages.yml @@ -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 diff --git a/.gitignore b/.gitignore index 46a2aed..b821efa 100644 --- a/.gitignore +++ b/.gitignore @@ -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 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 870bf6a..be889a4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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. @@ -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 @@ -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 diff --git a/package.json b/package.json index 5532acf..36f9d23 100644 --- a/package.json +++ b/package.json @@ -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", diff --git a/CNAME b/site/CNAME similarity index 100% rename from CNAME rename to site/CNAME diff --git a/docs/index.html b/site/docs/index.html similarity index 100% rename from docs/index.html rename to site/docs/index.html diff --git a/index.html b/site/index.html similarity index 99% rename from index.html rename to site/index.html index fed9bcc..5ff3c38 100644 --- a/index.html +++ b/site/index.html @@ -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/ --> diff --git a/llms.txt b/site/llms.txt similarity index 100% rename from llms.txt rename to site/llms.txt diff --git a/og.html b/site/og.html similarity index 98% rename from og.html rename to site/og.html index e214fd2..3feda27 100644 --- a/og.html +++ b/site/og.html @@ -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'); diff --git a/og.png b/site/og.png similarity index 100% rename from og.png rename to site/og.png