@waveso/docs 0.5.0 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,256 @@
 # @waveso/docs
 
+## 0.7.0
+
+### Minor Changes
+
+- da25315: **A page becomes a landing page by declaring its actions.** `actions` in the
+  frontmatter turns `title` and `description` into a page header with those links
+  beneath them:
+
+  ```yaml
+  ---
+  title: Wave Docs
+  description: Markdown documentation for Next.js.
+  actions:
+    - label: Quick start
+      href: /getting-started
+    - label: GitHub
+      href: https://github.com/waveso/docs
+      variant: secondary
+  ---
+  ```
+
+  Leave it off and the page is exactly what it was: `description` stays a `<meta>`
+  tag and the title is the first thing in the prose. That is the whole of the
+  adaptation for the two shapes this package serves — documentation that is the
+  entire site puts a hero on its index, and documentation mounted at `/docs`
+  inside an application that already has a marketing page leaves `actions` off.
+  There is no mode, no `standalone` flag and nothing to configure.
+
+  Actions are primary-then-secondary by position, so the common case needs no
+  `variant`. Anything that leaves the site gets a plain `<a>` rather than the
+  router link, plus `target`, `rel` and a screen-reader suffix; `mailto:` and
+  `tel:` get none of that, because they open no tab. Unsafe hrefs fail the build
+  rather than reaching an `<a>` — frontmatter was the one door into an `href` that
+  bypassed `isSafeHref`.
+
+  `DocsHero` is exported at `@waveso/docs/react/hero`, and `DocAction` from
+  `@waveso/docs/types`.
+
+  ⚠️ A HERO PAGE MUST NOT ALSO WRITE ITS OWN `# Title`. `render` normally prepends
+  an `<h1>` from `frontmatter.title`; on a hero page the hero renders that heading
+  instead, because the tagline and the actions have to sit beneath it. Writing one
+  in the body as well ships two `h1`s — the same duplication `titleHeading` has
+  always warned about.
+
+  The background is a rotated line grid drawn with `repeating-linear-gradient`
+  rather than an inlined SVG: no data URI in the stylesheet, and the lines are
+  `--wave-docs-hero-grid` and `--wave-docs-hero-grid-strong` — Wave 200 and Wave
+  300 from `@waveso/ui` in the light theme, Wave 900 and Wave 800 in the dark one
+  — so they follow the theme. They are tokens of their own rather than the border
+  colours, because a decorative tint must not be tied to a functional contrast
+  ratio.
+
+- 915729f: **`docs.Layout` renders no header, and the navigation is one sidebar at every
+  width.** A full-width sticky bar is the one element that competes with a host
+  application's own for the viewport's top edge, and two of the sites using this
+  have one — measured against a fixed 64px host bar, ours landed on top of theirs
+  at every width. The chrome it held lives in the sidebar now:
+
+  ```
+  .wave-docs-shell                       the query container
+  └─ .wave-docs-layout                   the grid
+     ├─ .wave-docs-layout__sidebar       paints nothing, and moves
+     │  ├─ …__sidebar-nav                the surface, and the one border
+     │  └─ …__sidebar-trigger            a 44px strip — paints nothing at rest
+     ├─ .wave-docs-layout__sidebar-scrim
+     ├─ .wave-docs-layout__main
+     └─ .wave-docs-layout__toc
+  ```
+
+  Pressing the trigger translates the sidebar by exactly the navigation's width,
+  so it leaves the page entirely and the trigger's outer edge lands on the inline
+  start edge. There is no drawer, no `<dialog>`, no second control and no second
+  copy of the tree.
+
+  **Nothing this package renders is anchored to the viewport.** The sidebar is a
+  grid item, the trigger is a flex child of it, and the scrim is `absolute` inside
+  `.wave-docs-layout` — so every one of them resolves against a box this package
+  owns and _your_ layout placed. `position: fixed` is the thing to avoid, and the
+  reason is specific: a fixed element is anchored to the viewport you share with
+  it, your navbar is in the same viewport, and neither can detect the other. The
+  search dialog is the one exception and always was.
+
+  **There is not one width-based `@media` query left.** Every breakpoint is
+  `@container`. `@media` asks how wide the _screen_ is, which is the wrong
+  question for a package mounted at `/docs` inside an application that owns the
+  rest of the page: put this in a 700px panel on a 1920px monitor and `@media`
+  says "wide", the sidebar takes its 16rem column, and the reading column comes
+  out around 60px. Two shapes fall out of the container width — beside the
+  article, or over it behind a scrim with `inert`, Escape, click-to-dismiss and
+  focus moved in and restored.
+
+  Migration, in full:
+
+  | Was                                                           | Becomes                                                |
+  | ------------------------------------------------------------- | ------------------------------------------------------ |
+  | `<docs.Layout title={<Brand/>}>`                              | Delete it. The index page's title brands the docs      |
+  | `<docs.Layout actions={<ThemeToggle/>}>`                      | Render it in your own layout, around `docs.Layout`     |
+  | `--wave-docs-header-height` set so sticky columns clear a bar | `--wave-docs-chrome-offset`, same value                |
+  | `--wave-docs-header-height` set to size the bar               | Nothing sizes a bar. There is no bar                   |
+  | `--wave-docs-shell-width` set to cap the shell                | Nothing. `--wave-docs-measure` caps the reading column |
+  | `actions` as the client-search escape hatch                   | `search={false}` plus your own `DocsSearch`            |
+  | A `rootMargin` you relied on defaulting to `-80px`            | Pass it explicitly                                     |
+  | `.wave-docs-layout__header` / `__title` / `__actions`         | Not rendered                                           |
+  | `.wave-docs-layout__sidebar > .wave-docs-sidebar`             | The tree is a grandchild now                           |
+
+  ⚠️ `--wave-docs-header-height` DID TWO JOBS AND ONLY ONE SURVIVES. It sized the
+  header, and it was the offset both sticky columns parked below. Nothing of this
+  package's sits above the content any more, so the sizing job is gone; the offset
+  job is `--wave-docs-chrome-offset`, and a host with their own fixed bar still
+  needs to set it or the sidebar and the table of contents park underneath it.
+
+  ⚠️ `--wave-docs-chrome-offset` DEFAULTS TO `0rem`, WITH A UNIT, AND THE UNIT IS
+  LOAD-BEARING. It is read inside `calc(100dvh - …)`, where a unitless `0` is
+  invalid at computed-value time — the height on the sidebar and the `max-height`
+  on the table of contents would die rather than resolve to no change.
+
+  ⚠️ `--wave-docs-shell-width` IS GONE RATHER THAN RENAMED. It capped the whole
+  shell and centred it, which pushed the sidebar's inline start 480px in from the
+  screen on a 2560px display — and left a _closed_ navigation parked in the
+  centring margin instead of off the page. The sidebar owns the page's inline
+  start edge at every width now, which is what makes "closed" mean off the screen
+  by construction, and the reading column is what is capped.
+
+  `DocsToc`'s `rootMargin` default changes from `'-80px 0px -60% 0px'` to
+  `'0px 0px -60% 0px'`. The 80px reserved room for a sticky header that is no
+  longer rendered; a host whose own chrome overlays the content passes the prop.
+
+  `DocsLayoutProps` is three props — `children`, `search` and `labels`.
+
+  Two behaviours are lost with the drawer and are worth knowing: the navigation no
+  longer opens before hydration (it was a server-rendered
+  `<button command="show-modal">`), and the client bundle grows about 500 bytes
+  for the containment work `<dialog>` used to give for free.
+
+### Patch Changes
+
+- 1313e77: The shell no longer depends on the host shipping a CSS reset.
+
+  ⚠️ `box-sizing` WAS THE HOST'S TO SET, AND ALMOST EVERY HOST SETS IT.
+  `.wave-docs-sidebar__link` is `width: 100%` with `0.5rem` of inline padding, so
+  under `content-box` it is a 272px box in a 256px track — and the external-link
+  icon that `justify-content: space-between` pins to the far end renders 8px
+  outside the sidebar, clipped in half. Tailwind's preflight and every
+  normalize-style reset declare `border-box` globally, so this was invisible in
+  every project that has one, and visible on the only site here that ships no CSS
+  at all. `box-sizing: border-box` now applies to elements carrying a
+  `wave-docs-` class, scoped to this package's own namespace rather than to `*`,
+  because the prose renders a consumer's components too.
+
+  Three README claims were wrong and are corrected: `react/*` is ten subpaths and
+  not nine, three modules import from `next/*` and not two, and the twenty-two
+  chrome labels break down into six groups rather than the five that summed to
+  nineteen.
+
+## 0.6.0
+
+### Minor Changes
+
+- 633f274: **Anchors are checked now.** A route was verified and its fragment thrown away, so `[setup](./install.md#setup)` built green with no `#setup` anywhere on the page. It is the more common of the two link failures — headings get renamed constantly and nothing renames the links into them — and it went unchecked while the rarer one did not.
+
+  `onBrokenAnchors` defaults to `'throw'`, and the error names the heading you probably meant:
+
+  ```
+  @waveso/docs: guide.md:12 links to '#instalation', and this page has no
+  '#instalation'. Did you mean 'installation'?
+  ```
+
+  Checked against every `id` in the rendered page, not against the table of contents — which captures `h2`–`h3` only, so a link to an `h4` is fine, and so is a link to an id one of your `rehypePlugins` added. Same-page anchors are checked as each page renders, so those errors carry a line number; cross-page anchors need the target's ids and are checked by `docs.renderAll()`, which runs in every build that serves search.
+
+  **`onUnverifiableLinks` is replaced by `externalRoutes`, and the default flipped.** It shipped in no release, so nothing to migrate.
+
+  The old option asked you to reason about _our_ inability to verify a link. The new one asks for a fact about _your_ application, which is the thing you actually know:
+
+  ```ts
+  createDocsRoute({
+    basePath: "/",
+    externalRoutes: ["/login", "/dashboard", "/api/"],
+  });
+  ```
+
+  And absolute links at a root mount are now checked by default rather than ignored. A root mount is what you choose when the origin serves documentation and nothing else — `docs.example.com` — so an unknown absolute link there is a typo, and silence was the wrong default. A site that serves something else names what is its own; `/api` covers `/api/keys` and not `/apiary`.
+
+  That also removes the `'warn'` level that made no sense: warning on every legitimate route in your application is not a diagnostic.
+
+  **New error code `broken-anchor`**, documented in the troubleshooting table and offered in the bug form.
+
+- b6edd50: **New subpath `@waveso/docs/react/next-link`, exporting `DocsLink`** — `next/link` already adapted, so composing a shell by hand no longer needs a cast.
+
+  Passing `next/link` straight into `DocsSidebar` does not type-check under `exactOptionalPropertyTypes`: Next's `LinkProps` re-declares `onClick?`, `onMouseEnter?` and `onTouchStart?` _without_ `| undefined` while React's anchor props include it, so the two declaration files disagree over three props `next/link` accepts perfectly well at run time. It is a disagreement between dependencies, true of every `next/link` call site in a project with that flag on, and nothing the shape of `DocsLinkProps` can fix without breaking the plain-`<a>` fallback that keeps these components host-agnostic.
+
+  `docs.Layout` and `DocsSearch` have always absorbed it internally, so it only bit someone building their own shell — who was told in Troubleshooting to write `Link={Link as DocsLinkComponent}` and wait for a Next-wired component to ship. This is that component; the cast is retired and the note now shows the import.
+
+  ```tsx
+  "use client";
+  import { DocsLink } from "@waveso/docs/react/next-link";
+  import { DocsSidebar } from "@waveso/docs/react/sidebar";
+
+  <DocsSidebar nav={nav} pathname={pathname} Link={DocsLink} />;
+  ```
+
+  It carries `'use client'` — not for a hook, there is none, but because `DocsLink` is a function and a function cannot be handed from a Server Component to a Client one. Without the directive it would be a server reference and `next build` would refuse it, which is the same boundary this release fixed for MiniSearch options.
+
+  The private adapter factory it is built from is renamed `link-adapter.ts`, so the two are not one letter apart in the same directory. 180 bytes gzipped, with a 300-byte budget: it should stay the thinnest thing this package ships to a browser.
+
+- 1fa4317: **Link checking has severity levels, and broken links now say what you probably meant.**
+
+  **BREAKING: `assertLinks: boolean` is replaced by `onBrokenLinks: 'throw' | 'warn' | 'ignore'`**, defaulting to `'throw'`. `assertLinks: false` becomes `onBrokenLinks: 'ignore'`; `assertLinks: true` was the default and can be dropped. The shape follows Docusaurus's `onBrokenLinks` for the same reason it exists there: the tool cannot know how much a given site cares, and guessing produces either a build that fails on somebody's legitimate URL or one that ships a dead link quietly.
+
+  **Broken-link errors now offer the closest published route** when the link looks like a typo of one:
+
+  ```
+  @waveso/docs: guide.md:12 links to './instalation.md', which resolves to
+  '/docs/instalation' — no such page exists. Did you mean '/docs/installation'?
+  ```
+
+  A typo is a near-miss by construction, which is what makes the suggestion safe to offer _and_ safe to withhold — the same trick `git`, `tsc`, `cargo` and Python 3.12 use. It decorates an error that was already being raised; it never decides whether to raise one. `/docs/instructions` is five edits from `/docs/installation` — a different word, not a typo — and gets no suggestion, because sending an author to rename a correct link is worse than saying nothing.
+
+  **New `onUnverifiableLinks`, defaulting to `'ignore'`, closes the root-mount gap.** To check `[x](/setup)` the package must first know it is a documentation link. Under `basePath: '/docs'` the prefix says so. Under `basePath: '/'` there is no prefix — `/setup` may be a page of yours, `/login` almost certainly is — so until now those links were dropped unrecorded and a typo in one shipped silently.
+
+  They are recorded and marked now, and the site decides:
+
+  ```ts
+  createDocsRoute({
+    contentDir: "content/docs",
+    basePath: "/",
+    onUnverifiableLinks: "throw", // this domain is documentation and nothing else
+  });
+  ```
+
+  The default stays `'ignore'` because a root mount inside a larger application genuinely cannot distinguish the two, and failing that build would be wrong. Relative links (`./other.md`) are resolved against the content tree, so they are verifiable at every mount and always governed by `onBrokenLinks`.
+
+  `docs.wave.so` runs with `onUnverifiableLinks: 'throw'`, which is the configuration this option was written for.
+
+### Patch Changes
+
+- 102d6ae: **The README shows the live site instead of screenshots.** Three PNGs, a Playwright script to shoot them, a pinned tag and two tests to keep the pin honest — replaced by a link to [docs.wave.so](https://docs.wave.so), which is this package's documentation built with this package.
+
+  The screenshots were a photograph of the harness. The site _is_ the harness: the same `site/` that CI builds on every commit, whose acceptance test forbids it a single line of layout CSS of its own. A reader who wants to know what the shell looks like can now use it — open the search, resize to a phone, tab through the drawer — instead of looking at a picture of it taken on somebody's Mac.
+
+  It also removes a whole class of staleness. A pinned screenshot is wrong the moment the shell changes and right only if someone remembers to re-shoot and re-pin; the last one was pinned to `v0.3.0` while the images had been regenerated for 0.4.0, so npm showed a search dialog the release had already replaced. A URL cannot go stale.
+
+  `pnpm shoot` is gone. The regression it was meant to catch — a stylesheet change reflowing the shell — is the browser tier's, which asserts geometry rather than pixels and runs in the same Chromium everywhere.
+
+- e2bbaf4: **docs.wave.so serves the documentation at its root**, so a page is `docs.wave.so/installation` rather than `docs.wave.so/docs/installation` — a host called `docs` should not say it twice.
+
+  Nothing in the package changed: `basePath` has always taken any prefix, and `'/'` is one of them. The default is still `/docs`, defined in one place, and every consumer gets it unless they say otherwise.
+
+  What did change is which configuration the harnesses cover. `smoke/` builds on the default `/docs` in both output modes on every CI run, so moving the site to the root mount loses nothing and covers the half that was thin: an empty base path is a distinct code path in `toHref`, `toRoute` and `isInternalAbsoluteLink`, and two unit assertions used to be all of it. The two harnesses now cover both mount points and both documented layout shapes — smoke keeps the README's one-line `export default docs.Layout`, the site composes `<docs.Layout>` inside a root layout.
+
+  **One behaviour differs at the root mount, and it is worth knowing.** With an empty base, an absolute link like `/installation` cannot be told apart from any other route in the application, so it is not checked against the published routes — under `/docs`, a typo in `/docs/instalation` fails the build; at the root it does not. Relative markdown links, which is what documentation should be written with, are unaffected.
+
 ## 0.5.0
 
 ### Minor Changes
@@ -307,7 +558,7 @@
 
   Every subpath in `exports` is listed in the README, and so is every runtime name each one exports — `manifest.test.ts` enumerates both against the built output and fails the build on a name this README does not mention. That test is new in this release, and writing it immediately found five: `DOCS_ERROR_PREFIX`, `DEFAULT_DOCS_THEMES`, `CALLOUT_TYPES`, `defaultMarkdownComponents` and `DOCS_CONTENT_ID` were all public and documented nowhere.
 
-  **The default page is worth looking at.** A 46rem measure and a system font stack, a 1.2 minor-third type scale, tables that scroll instead of shredding the layout, one focus `outline` in place of five `box-shadow` rings (which also deletes the forced-colors block that existed to patch them), and a responsive shell with breakpoints at 64/80/100rem. The element tree, the five layout tokens and the breakpoints are frozen in `docs/adr/001-shell-contract.md`.
+  **The default page is worth looking at.** A 46rem measure and a system font stack, a 1.2 minor-third type scale, tables that scroll instead of shredding the layout, one focus `outline` in place of five `box-shadow` rings (which also deletes the forced-colors block that existed to patch them), and a responsive shell with breakpoints at 64/80/100rem. The element tree, the five layout tokens and the breakpoints are frozen.
 
   **Three new harnesses, because the old ones could not see these failures.** A browser tier running real Chromium — jsdom reports every width as `0`, so the measure, the type scale, reflow and the table floor were unassertable. A smoke build of a real Next application against the published `exports` map, in both output modes. And `pnpm check:readme`, which type-checks every example in this README as one project: it immediately found `app/docs/layout.tsx` defined twice with different bodies, and an `imageResolver` example calling `imageSize(path)` when `image-size` v2 takes a `Uint8Array`.