diff --git a/README.md b/README.md index b6d6632..0926396 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,7 @@ https://github.com/diecodev/qwik-sonner/assets/51871681/e7a7e4a6-c422-44b2-af7e- # qwik-sonner [![npm](https://img.shields.io/npm/v/qwik-sonner?label=npm&color=111)](https://www.npmjs.com/package/qwik-sonner) -[![Qwik v2](https://img.shields.io/npm/v/qwik-sonner/beta?label=qwik%20v2&color=ac7ef4)](https://qwik-sonner.dieco.dev/docs/v2/) +[![Qwik v2](https://img.shields.io/npm/v/qwik-sonner/beta?label=qwik%20v2&color=ac7ef4)](https://qwik-sonner.dieco.dev/docs/) An opinionated toast component for qwik. Based on [emilkowalski](https://github.com/emilkowalski)'s React [implementation](https://sonner.emilkowal.ski/). diff --git a/vercel.json b/vercel.json index 9310637..2ba3e0d 100644 --- a/vercel.json +++ b/vercel.json @@ -7,8 +7,8 @@ "outputDirectory": "website/dist", "trailingSlash": true, "redirects": [ - { "source": "/docs", "destination": "/docs/v2/", "permanent": true }, - { "source": "/docs/", "destination": "/docs/v2/", "permanent": true } + { "source": "/docs/v2", "destination": "/docs/", "permanent": true }, + { "source": "/docs/v2/:path*", "destination": "/docs/:path*", "permanent": true } ], "headers": [ { diff --git a/website/README.md b/website/README.md index 85af7f9..5e7c645 100644 --- a/website/README.md +++ b/website/README.md @@ -65,6 +65,14 @@ The build settings live in [`vercel.json`](../vercel.json) at the repo root: pnpm is the one in the root `package.json`'s `packageManager`: the CI's setup installs it, and Vercel reads it for the previews. -`trailingSlash` matches the URLs of the pages (`/docs/v2/toast/`), `/docs` redirects to the current -docs, `404.html` answers missing pages, and `/build/` and `/assets/` (hashed file names) are cached -for a year. +`trailingSlash` matches the URLs of the pages (`/docs/toast/`), `/docs/v2/…` redirects to `/docs/…` +(see below), `404.html` answers missing pages, and `/build/` and `/assets/` (hashed file names) are +cached for a year. + +## Docs URLs + +The current line's docs live at `/docs/…` (`src/routes/docs/`), an older line's at `/docs/v/…` +(`src/routes/docs/v1/`), and `vercel.json` redirects `/docs/v/…` to `/docs/…`, so both +addresses work. The paths come from `CURRENT_VERSION` in `src/lib/versions.ts`. When a new major +ships: move the current pages into `src/routes/docs/v/`, put the new ones in `src/routes/docs/`, +set `CURRENT_VERSION`, and point the redirects in `vercel.json` at the new major. diff --git a/website/adapters/ssg/vite.config.ts b/website/adapters/ssg/vite.config.ts index a885ab4..aee992d 100644 --- a/website/adapters/ssg/vite.config.ts +++ b/website/adapters/ssg/vite.config.ts @@ -14,9 +14,6 @@ export default extendConfig(baseConfig, () => { plugins: [ ssgAdapter({ origin: "https://qwik-sonner.dieco.dev", - // `/docs` only redirects: vercel.json answers it in production, and a - // redirect can't be prerendered. - exclude: ["/docs"], }), ], }; diff --git a/website/src/components/Hero.tsx b/website/src/components/Hero.tsx index 30b4158..b52d3b9 100644 --- a/website/src/components/Hero.tsx +++ b/website/src/components/Hero.tsx @@ -28,7 +28,7 @@ export const Hero = component$(() => { > Render a toast - + Documentation diff --git a/website/src/components/QwikV2Badge.tsx b/website/src/components/QwikV2Badge.tsx index 2d7c074..ef81465 100644 --- a/website/src/components/QwikV2Badge.tsx +++ b/website/src/components/QwikV2Badge.tsx @@ -24,7 +24,7 @@ export const QwikV2Badge = component$<{ size?: "sm" | "md" }>(({ size = "md" }) return ( { }; useContextProvider(ToasterControlsContext, controls); + // Links to a section of the same page (the table of contents, heading + // anchors, `/page/#section`) scroll smoothly. Only those: the router also + // scrolls on page changes (to the top, or back), and a global + // `scroll-behavior: smooth` would animate those too. `sync$`, so the style is + // set before the browser or the router scrolls; it's removed once the scroll + // ends (or after a while, where `scrollend` isn't supported). + useOnDocument( + "click", + sync$((event: MouseEvent) => { + if (event.button !== 0 || event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) { + return; + } + const link = (event.target as Element | null)?.closest?.("a[href*='#']"); + if ( + !(link instanceof HTMLAnchorElement) || + !link.hash || + link.origin !== location.origin || + link.pathname !== location.pathname || + matchMedia("(prefers-reduced-motion: reduce)").matches + ) { + return; + } + const root = document.documentElement; + root.style.scrollBehavior = "smooth"; + const reset = () => root.style.removeProperty("scroll-behavior"); + addEventListener("scrollend", reset, { once: true }); + setTimeout(reset, 1500); + }), + ); + return ( <> {/* diff --git a/website/src/components/docs/chrome.module.css b/website/src/components/docs/chrome.module.css index 6c3b548..5916dab 100644 --- a/website/src/components/docs/chrome.module.css +++ b/website/src/components/docs/chrome.module.css @@ -5,8 +5,10 @@ top: 0; z-index: 50; background: var(--bg-blur); + /* No hand-written -webkit- copy: Lightning CSS (Vite 8) adds the prefix + Safari needs, and with both it kept only the prefixed one, so Chromium + didn't blur. */ backdrop-filter: saturate(180%) blur(12px); - -webkit-backdrop-filter: saturate(180%) blur(12px); border-bottom: 1px solid var(--gray3); } @@ -389,14 +391,28 @@ white-space: nowrap; } -.bannerLink span { +.bannerArrow { transition: transform 200ms var(--ease-out); } -.bannerLink:hover span { +.bannerLink:hover .bannerArrow { transform: translateX(3px); } +.bannerShort { + display: none; +} + +@media (max-width: 999px) { + .bannerLong { + display: none; + } + + .bannerShort { + display: inline; + } +} + @keyframes banner-in { from { opacity: 0; @@ -408,9 +424,9 @@ .sidebar { position: sticky; - top: 56px; + top: var(--docs-top, 56px); align-self: start; - max-height: calc(100dvh - 56px); + max-height: calc(100dvh - var(--docs-top, 56px)); overflow-y: auto; padding: 28px 8px 48px 0; scrollbar-width: thin; @@ -461,7 +477,7 @@ @media (max-width: 900px) { .sidebar { position: fixed; - inset: 56px 0 0; + inset: var(--docs-top, 56px) 0 0; z-index: 40; max-height: none; padding: 20px 20px 48px; @@ -495,7 +511,7 @@ .toc { position: sticky; - top: 56px; + top: var(--docs-top, 56px); align-self: start; padding: 32px 0 48px; font-size: 13px; diff --git a/website/src/components/docs/chrome.tsx b/website/src/components/docs/chrome.tsx index 023c8ec..11c9370 100644 --- a/website/src/components/docs/chrome.tsx +++ b/website/src/components/docs/chrome.tsx @@ -16,7 +16,6 @@ import { VERSIONS, type VersionId, } from "~/lib/versions"; -import { LATEST, majorOf } from "~/lib/release"; import { Logo } from "../Logo"; import { QwikV2Badge } from "../QwikV2Badge"; import { ThemeToggle } from "../ThemeToggle"; @@ -178,52 +177,35 @@ export const DocsHeader = component$<{ version: VersionId; navOpen: Signal(({ version }) => { const loc = useLocation(); const v = VERSIONS[version]; const current = VERSIONS[CURRENT_VERSION]; - if (version !== CURRENT_VERSION) { - return ( -
-

+ return ( +

+ {/* One line at any width (it sticks under the header): a shorter text on narrow screens. */} +

+ You're reading the docs for qwik-sonner {v.version}, the {v.qwik} ( {v.qwikPackage}) line. It no longer receives new features. -

- - Go to the {current.qwik} docs ({CURRENT_VERSION}) - -
- ); - } - - if (v.status === "prerelease") { - // While `latest` is still an older major, say what a plain install gets. - const olderLatest = LATEST !== null && majorOf(LATEST) < v.major ? LATEST : null; - return ( -
-

- - {CURRENT_VERSION} is in {v.tag ?? "pre-release"} ({v.version}). - {" "} - Install it with {v.spec} - {olderLatest ? ( - <> - {" "} - — plain qwik-sonner still resolves to {olderLatest} - - ) : null} - . -

- - Installation - - -
- ); - } - - return null; + + + Docs for {v.version} ({v.qwik}) + +

+ + + Go to the {current.qwik} docs ({CURRENT_VERSION}) + + {current.qwik} docs + + +
+ ); }); /* Sidebar ----------------------------------------------------------------- */ diff --git a/website/src/components/docs/ui.module.css b/website/src/components/docs/ui.module.css index 3a71d72..e8362e6 100644 --- a/website/src/components/docs/ui.module.css +++ b/website/src/components/docs/ui.module.css @@ -2,7 +2,7 @@ .heading { position: relative; - scroll-margin-top: 88px; + scroll-margin-top: calc(var(--docs-top, 56px) + 32px); } .anchor { diff --git a/website/src/global.css b/website/src/global.css index 477115e..a1f5eff 100644 --- a/website/src/global.css +++ b/website/src/global.css @@ -35,6 +35,9 @@ --warning-bg: hsl(49, 100%, 97%); --warning-border: hsl(49, 91%, 84%); --warning-text: hsl(31, 92%, 45%); + /* changelog markers: breaking changes and new features (the rest stay gray) */ + --log-breaking: #b45309; + --log-new: #2563eb; --error-bg: hsl(359, 100%, 97%); --error-border: hsl(359, 100%, 94%); --error-text: hsl(360, 100%, 45%); @@ -97,6 +100,8 @@ --warning-bg: hsl(64, 100%, 6%); --warning-border: hsl(60, 100%, 9%); --warning-text: hsl(46, 87%, 65%); + --log-breaking: #fbbf24; + --log-new: #6ea8ff; --error-bg: hsl(358, 76%, 10%); --error-border: hsl(357, 89%, 16%); --error-text: hsl(358, 100%, 81%); @@ -137,6 +142,8 @@ --warning-bg: hsl(64, 100%, 6%); --warning-border: hsl(60, 100%, 9%); --warning-text: hsl(46, 87%, 65%); + --log-breaking: #fbbf24; + --log-new: #6ea8ff; --error-bg: hsl(358, 76%, 10%); --error-border: hsl(357, 89%, 16%); --error-text: hsl(358, 100%, 81%); diff --git a/website/src/lib/docs-nav.ts b/website/src/lib/docs-nav.ts index 8d5cfa5..afee351 100644 --- a/website/src/lib/docs-nav.ts +++ b/website/src/lib/docs-nav.ts @@ -58,7 +58,8 @@ const EQUIVALENT_SLUG: Record> = { /** URL of the page in `target` that best matches `pathname`. */ export const equivalentHref = (pathname: string, target: VersionId) => { - const match = /^\/docs\/v\d+\/([^/]+)?/.exec(pathname); + // `/docs//` on the current line, `/docs/v//` on an older one + const match = /^\/docs\/(?:v\d+\/)?([^/]+)?/.exec(pathname); const slug = match?.[1] ?? ""; const mapped = EQUIVALENT_SLUG[target][slug] ?? ""; return `${VERSIONS[target].basePath}/${mapped ? `${mapped}/` : ""}`; diff --git a/website/src/lib/github.ts b/website/src/lib/github.ts index e60115e..47d60b1 100644 --- a/website/src/lib/github.ts +++ b/website/src/lib/github.ts @@ -12,6 +12,39 @@ export interface ReleaseNotes { /** The notes of each published release, by version (the tag without its `v`). */ export type Releases = Record; +/** The kinds of change a release's sections list, as the changelog colors them. */ +export type ChangeKind = "breaking" | "deprecated" | "feature" | "fix" | "perf" | "docs"; + +// A section's kind, from its heading: the curated notes say "Breaking changes", +// "Features", "Fixes"…, changelogithub "🚨 Breaking Changes", "🚀 Features", +// "🐞 Bug Fixes", "🏎 Performance". The first match wins. +const KINDS: [ChangeKind, RegExp][] = [ + ["breaking", /breaking/i], + ["deprecated", /deprecat/i], + ["feature", /feature|\bnew\b|\badded\b/i], + ["fix", /\bfix/i], + ["perf", /perf/i], + ["docs", /\bdocs?\b|documentation/i], +]; + +/** + * Marks each heading of a known kind, and the lists under it until the next + * heading, with `data-kind` so the changelog can color them. Other headings + * ("View changes on GitHub") and the lists under them stay as they are. + */ +export const markKinds = (html: string) => { + let kind: ChangeKind | undefined; + return html.replace( + /<(h[1-6])([^>]*)>([\s\S]*?)<\/\1>|])/g, + (match, tag?: string, attrs?: string, inner?: string) => { + if (!tag) return kind ? `
    ]*>/g, "").replace(/&[#\w]+;/g, " "); + kind = KINDS.find(([, pattern]) => pattern.test(text))?.[0]; + return kind ? `<${tag}${attrs} data-kind="${kind}">${inner}` : match; + }, + ); +}; + const RELEASES = "https://api.github.com/repos/diecodev/qwik-sonner/releases"; const PER_PAGE = 100; @@ -57,7 +90,7 @@ export const readReleases = async (): Promise => { .filter((release) => !release.draft && release.tag_name.startsWith("v")) .map((release) => [ release.tag_name.slice(1), - { html: release.body_html?.trim() ?? "", url: release.html_url }, + { html: markKinds(release.body_html?.trim() ?? ""), url: release.html_url }, ]), ); } catch (error) { diff --git a/website/src/lib/versions.ts b/website/src/lib/versions.ts index a35e269..f50c98a 100644 --- a/website/src/lib/versions.ts +++ b/website/src/lib/versions.ts @@ -12,10 +12,15 @@ export interface DocsVersion extends Line { status: "stable" | "prerelease" | "legacy"; /** Text of the status pill: `Stable`, the dist-tag (`beta`, `rc`) or `Legacy`. */ statusLabel: string; - basePath: `/docs/${VersionId}`; + /** `/docs` for the current line, `/docs/v1` for an older one */ + basePath: "/docs" | `/docs/${VersionId}`; } -/** Newest docs line — what `/docs` redirects to and what other versions link to. */ +/** + * Newest docs line: its pages live at `/docs/…` (routes/docs/), the older lines' at `/docs/v/…` + * (routes/docs/v/), and vercel.json sends `/docs/v/…` of the current line to `/docs/…`. When a + * new major ships, move the current pages to routes/docs/v/ and the new ones to routes/docs/. + */ export const CURRENT_VERSION: VersionId = "v2"; export const VERSION_ORDER: VersionId[] = ["v2", "v1"]; @@ -30,7 +35,7 @@ const docsVersion = (id: VersionId, line: Line, qwik: string, qwikPackage: strin status, statusLabel: status === "legacy" ? "Legacy" : status === "stable" ? "Stable" : (line.tag ?? "Pre-release"), - basePath: `/docs/${id}`, + basePath: id === CURRENT_VERSION ? "/docs" : `/docs/${id}`, }; }; @@ -40,9 +45,13 @@ export const VERSIONS: Record = { v1: docsVersion("v1", V1, "Qwik 1", "@builder.io/qwik"), }; +/** The docs line a page belongs to; `null` for pages of none (the changelog) and outside the docs. */ export const versionFromPath = (pathname: string): VersionId | null => { const match = /^\/docs\/(v\d+)(\/|$)/.exec(pathname); - return match && match[1] in VERSIONS ? (match[1] as VersionId) : null; + if (match) return match[1] in VERSIONS ? (match[1] as VersionId) : null; + return /^\/docs(\/|$)/.test(pathname) && !pathname.startsWith("/docs/changelog") + ? CURRENT_VERSION + : null; }; export const GITHUB_URL = "https://github.com/diecodev/qwik-sonner"; diff --git a/website/src/routes/docs/v2/advanced/index.tsx b/website/src/routes/docs/advanced/index.tsx similarity index 97% rename from website/src/routes/docs/v2/advanced/index.tsx rename to website/src/routes/docs/advanced/index.tsx index 59f4781..5ade580 100644 --- a/website/src/routes/docs/v2/advanced/index.tsx +++ b/website/src/routes/docs/advanced/index.tsx @@ -3,7 +3,7 @@ import { Link, type DocumentHead } from "@qwik.dev/router"; import { CodeBlock } from "~/components/CodeBlock"; import { H2, H3 } from "~/components/docs/ui"; import { GITHUB_URL } from "~/lib/versions"; -import styles from "../../pages.module.css"; +import styles from "../pages.module.css"; const multiCode = `// Unnamed: renders every toast without a toasterId @@ -106,11 +106,11 @@ export default component$(() => {
  • With the headless entry, add the{" "} - popover reset yourself. + popover reset yourself.

- See it next to a real dialog in the examples. + See it next to a real dialog in the examples.

useSonner()

diff --git a/website/src/routes/docs/changelog/index.tsx b/website/src/routes/docs/changelog/index.tsx index 96e58e8..fcb165f 100644 --- a/website/src/routes/docs/changelog/index.tsx +++ b/website/src/routes/docs/changelog/index.tsx @@ -1,6 +1,6 @@ import { component$, useSignal } from "@qwik.dev/core"; import { Link, type DocumentHead } from "@qwik.dev/router"; -import type { Releases } from "~/lib/github"; +import type { ChangeKind, Releases } from "~/lib/github"; import { majorOf, newestFirst, NPM, tagsOf } from "~/lib/release"; import { GITHUB_URL, NPM_URL } from "~/lib/versions"; import styles from "../pages.module.css"; @@ -14,6 +14,15 @@ const FILTERS = [ type Filter = (typeof FILTERS)[number]["id"]; +// The kinds of change the notes mark with a symbol (see lib/github.ts and +// pages.module.css); performance and docs sections get a plain dot. +const LEGEND: { kind: ChangeKind; label: string }[] = [ + { kind: "breaking", label: "breaking" }, + { kind: "feature", label: "new" }, + { kind: "fix", label: "fix" }, + { kind: "deprecated", label: "deprecated" }, +]; + // The notes of each GitHub release: vite.config.ts reads them when the site // builds and defines `__RELEASES__` with them, so only this page carries them. declare const __RELEASES__: Releases; @@ -86,6 +95,14 @@ export default component$(() => { ))} +
+ {LEGEND.map(({ kind, label }) => ( + + {label} + + ))} +
+ {versions.length === 0 ? (

npm couldn't be read when this page was built, so there are no versions to show. @@ -140,7 +157,7 @@ export default component$(() => { {release.previous ? "Commits" : "Source"} {!release.newestOfMajor ? null : release.major >= 2 ? ( - Migration guide + Migration guide ) : release.major === 1 ? ( v1 docs ) : null} diff --git a/website/src/routes/docs/docs.module.css b/website/src/routes/docs/docs.module.css index e860f8c..8f581b7 100644 --- a/website/src/routes/docs/docs.module.css +++ b/website/src/routes/docs/docs.module.css @@ -1,7 +1,21 @@ .shell { + /* Height of what sticks at the top: the header, plus the banner on the docs + of an older line. Sticky and fixed parts of the page start below it. */ + --docs-top: 56px; min-height: 100dvh; } +.shell[data-banner] { + /* the 57px header (its border included) and the one-line banner */ + --docs-top: 98px; +} + +.top { + position: sticky; + top: 0; + z-index: 50; +} + .skip { position: absolute; left: 12px; diff --git a/website/src/routes/docs/v2/examples/examples.module.css b/website/src/routes/docs/examples/examples.module.css similarity index 100% rename from website/src/routes/docs/v2/examples/examples.module.css rename to website/src/routes/docs/examples/examples.module.css diff --git a/website/src/routes/docs/v2/examples/index.tsx b/website/src/routes/docs/examples/index.tsx similarity index 99% rename from website/src/routes/docs/v2/examples/index.tsx rename to website/src/routes/docs/examples/index.tsx index 1186a5c..7d71753 100644 --- a/website/src/routes/docs/v2/examples/index.tsx +++ b/website/src/routes/docs/examples/index.tsx @@ -4,7 +4,7 @@ import { toast, useSonner } from "qwik-sonner"; import { CodeBlock } from "~/components/CodeBlock"; import { Callout, Demo, H2 } from "~/components/docs/ui"; import { SECONDARY_TOASTER } from "~/lib/toaster-context"; -import styles from "../../pages.module.css"; +import styles from "../pages.module.css"; import ex from "./examples.module.css"; /* Undo ------------------------------------------------------------------- */ diff --git a/website/src/routes/docs/index.tsx b/website/src/routes/docs/index.tsx index 8da659a..6e12922 100644 --- a/website/src/routes/docs/index.tsx +++ b/website/src/routes/docs/index.tsx @@ -1,24 +1,201 @@ -import { component$ } from "@qwik.dev/core"; -import type { DocumentHead, RequestHandler } from "@qwik.dev/router"; -import { Link } from "@qwik.dev/router"; -import { CURRENT_VERSION, VERSIONS } from "~/lib/versions"; +import { $, component$ } from "@qwik.dev/core"; +import { Link, type DocumentHead } from "@qwik.dev/router"; +import { toast } from "qwik-sonner"; +import { CodeBlock } from "~/components/CodeBlock"; +import { QwikV2Badge } from "~/components/QwikV2Badge"; +import { Callout, Demo, H2, InstallTabs } from "~/components/docs/ui"; +import { LATEST, majorOf } from "~/lib/release"; +import { VERSIONS } from "~/lib/versions"; +import styles from "./pages.module.css"; -const target = `${VERSIONS[CURRENT_VERSION].basePath}/`; +const layoutCode = `import { component$, Slot } from "@qwik.dev/core"; +import { Toaster } from "qwik-sonner"; -// `/docs` always means "the newest docs". In production the site is static and -// vercel.json does this redirect; this handler covers `pnpm dev`. -export const onGet: RequestHandler = ({ redirect }) => { - throw redirect(308, target); -}; +export default component$(() => { + return ( + <> + + + + ); +});`; + +const pageCode = `import { component$ } from "@qwik.dev/core"; +import { toast } from "qwik-sonner"; + +export default component$(() => { + return ( + + ); +});`; + +const entriesCode = `// Styled (default) — ships sonner's stylesheet via useStyles$ +import { Toaster, toast } from "qwik-sonner"; + +// Headless — same API and markup, no styles +import { Toaster, toast } from "qwik-sonner/headless";`; + +const undo = $(() => { + toast.success("Change reverted"); +}); + +export default component$(() => { + const v2 = VERSIONS.v2; + const v1 = VERSIONS.v1; + // A plain `npm install qwik-sonner` still gets the Qwik 1 line. + const latestIsV1 = LATEST !== null && majorOf(LATEST) === 1; + + return ( + <> +

Introduction

+

+ An opinionated toast component for Qwik. A resumable port of{" "} + + sonner + {" "} + by Emil Kowalski: render one {""}, call toast() from + anywhere, ship zero hydration. +

+ + + + + + + + +

Installation

+

+ Version 2 targets Qwik 2: @qwik.dev/core 2.0.0-rc.4 or later. + {v2.prerelease ? ( + <> + {" "} + While it's a pre-release it's published under the {v2.tag} dist-tag, so + name the tag explicitly: + + ) : null} +

+ +
+ Release status on npm + +
+ +

+ @builder.io/qwik apps need qwik-sonner 1.x: install {v1.spec} + {latestIsV1 ? ( + <> + {" "} + (also what a plain npm install qwik-sonner gives you today) + + ) : null} + . See the v1 documentation, or the{" "} + migration guide when you move to Qwik 2. +

+
+ +

Quick start

+

+ Render the Toaster once, in your root layout, then call toast(){" "} + from any component. +

+ + + +

Styled or headless

+

+ The default entry injects sonner's stylesheet. qwik-sonner/headless renders the + exact same markup and data-sonner-* attributes without any CSS, for when you + want to own the look entirely. +

+ + +

Differences from sonner

+

+ The API mirrors sonner as closely as Qwik's resumability allows. What changes is how + functions cross the server/client boundary: +

+
+
sonner (React)
+
qwik-sonner
+ onClick: () => … + onClick$: $(() => …) + onDismiss / onAutoClose + onDismiss$ / onAutoClose$ + event.preventDefault() + action.preventDefault: true + className / classNames + class / classes + Re-render with new props + {"position={signal}"} +
+

+ Callbacks stored on a toast must be QRLs — wrap them in $(). Toaster props that + should change after the page loaded (position, theme,{" "} + richColors, dir, invert) accept a Signal + . +

-// Fallback page, should a request ever reach the route itself. -export default component$(() => ( -

- The documentation moved to {target}. -

-)); +

Next steps

+
+ + toast() + Every way to create, update and dismiss toasts. + + + {""} + Position, theme, stacking and every prop. + + + Examples + Undo, forms, uploads, dialogs and more. + + + Styling + Classes, CSS variables, unstyled and headless. + +
+ + ); +}); export const head: DocumentHead = { - title: "Documentation — qwik-sonner", - meta: [{ httpEquiv: "refresh", content: `0; url=${target}` }], + title: "Introduction — qwik-sonner", + meta: [ + { + name: "description", + content: "Install qwik-sonner for Qwik 2 and render your first toast.", + }, + ], + frontmatter: { + toc: [ + { id: "installation", title: "Installation" }, + { id: "quick-start", title: "Quick start" }, + { id: "entry-points", title: "Styled or headless" }, + { id: "differences", title: "Differences from sonner" }, + { id: "next", title: "Next steps" }, + ], + }, }; diff --git a/website/src/routes/docs/layout.tsx b/website/src/routes/docs/layout.tsx index 0b19cb5..8fbdc51 100644 --- a/website/src/routes/docs/layout.tsx +++ b/website/src/routes/docs/layout.tsx @@ -21,6 +21,8 @@ export default component$(() => { const pageVersion = versionFromPath(pathname); // Unversioned pages (the changelog) borrow the current version's navigation. const version = pageVersion ?? CURRENT_VERSION; + // The docs of an older line say so under the header. + const banner = pageVersion !== null && pageVersion !== CURRENT_VERSION; const group = DOCS_NAV[version].find((g) => g.items.some((i) => i.href === pathname)); const editUrl = `${GITHUB_URL}/edit/v2/website/src/routes${pathname}index.tsx`; @@ -30,12 +32,15 @@ export default component$(() => { }); return ( -
+
Skip to content - - {pageVersion ? : null} + {/* The banner sticks with the header, so it stays in view. */} +
+ + {banner ? : null} +
diff --git a/website/src/routes/docs/v2/migration/index.tsx b/website/src/routes/docs/migration/index.tsx similarity index 93% rename from website/src/routes/docs/v2/migration/index.tsx rename to website/src/routes/docs/migration/index.tsx index b440386..cf12cba 100644 --- a/website/src/routes/docs/v2/migration/index.tsx +++ b/website/src/routes/docs/migration/index.tsx @@ -3,7 +3,7 @@ import { Link, type DocumentHead } from "@qwik.dev/router"; import { CodeBlock } from "~/components/CodeBlock"; import { Callout, H2, H3, InstallTabs } from "~/components/docs/ui"; import { VERSIONS } from "~/lib/versions"; -import styles from "../../pages.module.css"; +import styles from "../pages.module.css"; const htmlBefore = `// v1 — string parsed as (sanitized) HTML toast("Saved to drafts");`; @@ -106,7 +106,7 @@ export default component$(() => {
  • Markup and styles follow sonner 2's data-sonner-* contract. Custom CSS that targeted v1's markup may need new selectors — see{" "} - data attributes. + data attributes.
  • important: true no longer makes a toast aria-live="assertive". @@ -136,24 +136,24 @@ export default component$(() => { v1 recommended rendering the Toaster before the rest of the page to avoid rendering glitches. v2 subscribes when Qwik boots, so it can go anywhere in the root layout — but keep it in a server-rendered layout (see{" "} - known issues). + known issues).

    Worth adopting

    • - Signals for position,{" "} + Signals for position,{" "} theme, richColors, dir and invert.
    • - + topLayer {" "} for toasts above native dialogs.
    • - Multiple toasters with{" "} + Multiple toasters with{" "} id / toasterId.
    • diff --git a/website/src/routes/docs/v2/options/index.tsx b/website/src/routes/docs/options/index.tsx similarity index 99% rename from website/src/routes/docs/v2/options/index.tsx rename to website/src/routes/docs/options/index.tsx index f6be44e..d1afcaf 100644 --- a/website/src/routes/docs/v2/options/index.tsx +++ b/website/src/routes/docs/options/index.tsx @@ -142,7 +142,7 @@ export default component$(() => {

      The last argument of every toast helper — typed as ExternalToast. Toaster-wide defaults live in{" "} - + toastOptions . diff --git a/website/src/routes/docs/pages.module.css b/website/src/routes/docs/pages.module.css index 3a2d39b..92a0ef2 100644 --- a/website/src/routes/docs/pages.module.css +++ b/website/src/routes/docs/pages.module.css @@ -338,7 +338,7 @@ @media (min-width: 641px) { .releaseAside { position: sticky; - top: 80px; + top: calc(var(--docs-top, 56px) + 24px); align-self: start; } } @@ -404,6 +404,73 @@ margin: 2px 0; } +/* A symbol per kind of change (`data-kind`, set by lib/github.ts) in place of + the bullet, as in the legend. Only breaking changes and new features get a + color; the rest stay gray. */ +.release .notes :global(ul[data-kind]) { + padding-left: 22px; + list-style: none; +} + +.release .notes :global(ul[data-kind] > li) { + position: relative; +} + +.release .notes :global(ul[data-kind] > li)::before, +.legendItem::before { + font-family: var(--font-mono); + font-weight: 600; + color: var(--gray10); +} + +.release .notes :global(ul[data-kind] > li)::before { + position: absolute; + left: -20px; +} + +.release .notes :global(ul[data-kind="breaking"] > li)::before, +.legendItem[data-kind="breaking"]::before { + content: "!"; + color: var(--log-breaking); +} + +.release .notes :global(ul[data-kind="feature"] > li)::before, +.legendItem[data-kind="feature"]::before { + content: "+"; + color: var(--log-new); +} + +.release .notes :global(ul[data-kind="fix"] > li)::before, +.legendItem[data-kind="fix"]::before { + content: "~"; +} + +.release .notes :global(ul[data-kind="deprecated"] > li)::before, +.legendItem[data-kind="deprecated"]::before { + content: "−"; +} + +.release .notes :global(ul[data-kind="perf"] > li)::before, +.release .notes :global(ul[data-kind="docs"] > li)::before { + content: "·"; +} + +.legend { + display: flex; + flex-wrap: wrap; + gap: 6px 18px; + margin: -16px 0 28px; + font-family: var(--font-mono); + font-size: 12px; + color: var(--gray10); +} + +.legendItem { + display: inline-flex; + align-items: baseline; + gap: 6px; +} + .release .notes :global(samp) { font-family: var(--font-mono); font-size: 12px; diff --git a/website/src/routes/docs/v2/styling/index.tsx b/website/src/routes/docs/styling/index.tsx similarity index 100% rename from website/src/routes/docs/v2/styling/index.tsx rename to website/src/routes/docs/styling/index.tsx diff --git a/website/src/routes/docs/v2/toast/index.tsx b/website/src/routes/docs/toast/index.tsx similarity index 98% rename from website/src/routes/docs/v2/toast/index.tsx rename to website/src/routes/docs/toast/index.tsx index dcb8517..31630bc 100644 --- a/website/src/routes/docs/v2/toast/index.tsx +++ b/website/src/routes/docs/toast/index.tsx @@ -184,7 +184,7 @@ export default component$(() => {

      message is a string, JSX, or a function returning either. Every - helper takes the same options object as its last + helper takes the same options object as its last argument.

      @@ -419,14 +419,14 @@ export default component$(() => {

      Use onDismiss$ and onAutoClose$ to react to a toast closing — see{" "} - callbacks. + callbacks.

      Reading state

      For a reactive list inside a component use{" "} - + useSonner() . diff --git a/website/src/routes/docs/v2/toaster/index.tsx b/website/src/routes/docs/toaster/index.tsx similarity index 98% rename from website/src/routes/docs/v2/toaster/index.tsx rename to website/src/routes/docs/toaster/index.tsx index 293736e..d968f21 100644 --- a/website/src/routes/docs/v2/toaster/index.tsx +++ b/website/src/routes/docs/toaster/index.tsx @@ -4,7 +4,7 @@ import { toast } from "qwik-sonner"; import { CodeBlock } from "~/components/CodeBlock"; import { Callout, H2, H3, PropsTable, type PropRow } from "~/components/docs/ui"; import { POSITIONS, useToasterControls, type Theme } from "~/lib/toaster-context"; -import styles from "../../pages.module.css"; +import styles from "../pages.module.css"; const THEMES: Theme[] = ["light", "dark", "system"]; @@ -366,7 +366,7 @@ export default component$(() => {

      Icons

      Any key you leave out keeps the default icon. To change one toast's icon use its{" "} - + icon option . @@ -385,7 +385,7 @@ export default component$(() => {

      Need toasts in different places at once? Give each Toaster an id — see{" "} - multiple toasters. + multiple toasters.

      diff --git a/website/src/routes/docs/v1/index.tsx b/website/src/routes/docs/v1/index.tsx index 2b725c0..aa8e337 100644 --- a/website/src/routes/docs/v1/index.tsx +++ b/website/src/routes/docs/v1/index.tsx @@ -93,7 +93,7 @@ export default component$(() => {

      Upgrading to Qwik 2

      qwik-sonner 2 supports Qwik 2 and adds swipe directions, top-layer rendering, multiple - toasters and more. Read the migration guide. + toasters and more. Read the migration guide.

      ); diff --git a/website/src/routes/docs/v2/index.tsx b/website/src/routes/docs/v2/index.tsx deleted file mode 100644 index c893aec..0000000 --- a/website/src/routes/docs/v2/index.tsx +++ /dev/null @@ -1,201 +0,0 @@ -import { $, component$ } from "@qwik.dev/core"; -import { Link, type DocumentHead } from "@qwik.dev/router"; -import { toast } from "qwik-sonner"; -import { CodeBlock } from "~/components/CodeBlock"; -import { QwikV2Badge } from "~/components/QwikV2Badge"; -import { Callout, Demo, H2, InstallTabs } from "~/components/docs/ui"; -import { LATEST, majorOf } from "~/lib/release"; -import { VERSIONS } from "~/lib/versions"; -import styles from "../pages.module.css"; - -const layoutCode = `import { component$, Slot } from "@qwik.dev/core"; -import { Toaster } from "qwik-sonner"; - -export default component$(() => { - return ( - <> - - - - ); -});`; - -const pageCode = `import { component$ } from "@qwik.dev/core"; -import { toast } from "qwik-sonner"; - -export default component$(() => { - return ( - - ); -});`; - -const entriesCode = `// Styled (default) — ships sonner's stylesheet via useStyles$ -import { Toaster, toast } from "qwik-sonner"; - -// Headless — same API and markup, no styles -import { Toaster, toast } from "qwik-sonner/headless";`; - -const undo = $(() => { - toast.success("Change reverted"); -}); - -export default component$(() => { - const v2 = VERSIONS.v2; - const v1 = VERSIONS.v1; - // A plain `npm install qwik-sonner` still gets the Qwik 1 line. - const latestIsV1 = LATEST !== null && majorOf(LATEST) === 1; - - return ( - <> -

      Introduction

      -

      - An opinionated toast component for Qwik. A resumable port of{" "} - - sonner - {" "} - by Emil Kowalski: render one {""}, call toast() from - anywhere, ship zero hydration. -

      - - - - - - - - -

      Installation

      -

      - Version 2 targets Qwik 2: @qwik.dev/core 2.0.0-rc.4 or later. - {v2.prerelease ? ( - <> - {" "} - While it's a pre-release it's published under the {v2.tag} dist-tag, so - name the tag explicitly: - - ) : null} -

      - -
      - Release status on npm - -
      - -

      - @builder.io/qwik apps need qwik-sonner 1.x: install {v1.spec} - {latestIsV1 ? ( - <> - {" "} - (also what a plain npm install qwik-sonner gives you today) - - ) : null} - . See the v1 documentation, or the{" "} - migration guide when you move to Qwik 2. -

      -
      - -

      Quick start

      -

      - Render the Toaster once, in your root layout, then call toast(){" "} - from any component. -

      - - - -

      Styled or headless

      -

      - The default entry injects sonner's stylesheet. qwik-sonner/headless renders the - exact same markup and data-sonner-* attributes without any CSS, for when you - want to own the look entirely. -

      - - -

      Differences from sonner

      -

      - The API mirrors sonner as closely as Qwik's resumability allows. What changes is how - functions cross the server/client boundary: -

      -
      -
      sonner (React)
      -
      qwik-sonner
      - onClick: () => … - onClick$: $(() => …) - onDismiss / onAutoClose - onDismiss$ / onAutoClose$ - event.preventDefault() - action.preventDefault: true - className / classNames - class / classes - Re-render with new props - {"position={signal}"} -
      -

      - Callbacks stored on a toast must be QRLs — wrap them in $(). Toaster props that - should change after the page loaded (position, theme,{" "} - richColors, dir, invert) accept a Signal - . -

      - -

      Next steps

      -
      - - toast() - Every way to create, update and dismiss toasts. - - - {""} - Position, theme, stacking and every prop. - - - Examples - Undo, forms, uploads, dialogs and more. - - - Styling - Classes, CSS variables, unstyled and headless. - -
      - - ); -}); - -export const head: DocumentHead = { - title: "Introduction — qwik-sonner", - meta: [ - { - name: "description", - content: "Install qwik-sonner for Qwik 2 and render your first toast.", - }, - ], - frontmatter: { - toc: [ - { id: "installation", title: "Installation" }, - { id: "quick-start", title: "Quick start" }, - { id: "entry-points", title: "Styled or headless" }, - { id: "differences", title: "Differences from sonner" }, - { id: "next", title: "Next steps" }, - ], - }, -}; diff --git a/website/src/routes/index.tsx b/website/src/routes/index.tsx index 44b3504..e80898f 100644 --- a/website/src/routes/index.tsx +++ b/website/src/routes/index.tsx @@ -23,7 +23,7 @@ export default component$(() => {