Fix bunch of little things

.github/workflows/www.yaml

@@ -10,7 +10,7 @@ on:
 
 jobs:
   www:
-    runs-on: ubuntu-latest
+    runs-on: macos-latest
     timeout-minutes: 15
 
     permissions:
@@ -26,7 +26,7 @@ jobs:
       - name: Setup Deno
         uses: denoland/setup-deno@v2
         with:
-          deno-version: v2.x
+          deno-version: v2.6.1
 
       - name: Serve Website
         run: |
@@ -43,14 +43,14 @@ jobs:
 
       - name: Download Staticalize
         run: |
-          wget https://github.com/thefrontside/staticalize/releases/download/v0.2.2/staticalize-linux.tar.gz \
-            -O /tmp/staticalize-linux.tar.gz
-          tar -xzf /tmp/staticalize-linux.tar.gz -C /usr/local/bin
-          chmod +x /usr/local/bin/staticalize-linux
+          wget https://github.com/thefrontside/staticalize/releases/download/v0.2.2/staticalize-macos.tar.gz \
+            -O /tmp/staticalize-macos.tar.gz
+          tar -xzf /tmp/staticalize-macos.tar.gz -C /usr/local/bin
+          chmod +x /usr/local/bin/staticalize-macos
 
       - name: Staticalize
         run: |
-          staticalize-linux \
+          staticalize-macos \
             --site=http://127.0.0.1:8000 \
             --output=www/built \
             --base=https://effection-www.deno.dev/

lib/main.ts

@@ -180,8 +180,7 @@ function* withHost<T>(op: HostOperation<T>): Operation<T> {
     // @see https://github.com/iliakan/detect-node/blob/master/index.js
   } else if (
     Object.prototype.toString.call(
-      // @ts-expect-error we are just detecting the possibility, so type strictness not required
-      typeof globalThis.process !== "undefined" ? globalThis.process : 0,
+      typeof global.process !== "undefined" ? global.process : 0,
     ) === "[object process]"
   ) {
     return yield* op.node();

www/components/api/api-page.tsx

@@ -1,10 +1,11 @@
+import { all } from "effection";
 import type { JSXElement } from "revolution";
-import { DocPage } from "../../hooks/use-deno-doc.tsx";
+import { useConfig } from "../../context/config.ts";
+import { LocalDocPage } from "../../hooks/use-deno-doc.tsx";
 import { ResolveLinkFunction, useMarkdown } from "../../hooks/use-markdown.tsx";
-import { Package } from "../../lib/package.ts";
+import { Package, usePackage } from "../../lib/package.ts";
 import { major } from "../../lib/semver.ts";
-import { createSibling } from "../../routes/links-resolvers.ts";
-import { IconExternal } from "../icons/external.tsx";
+import { createRootUrl, createSibling } from "../../lib/links-resolvers.ts";
 import { SourceCodeIcon } from "../icons/source-code.tsx";
 import { GithubPill } from "../package/source-link.tsx";
 import { Icon } from "../type/icon.tsx";
@@ -19,7 +20,7 @@ export function* ApiPage({
   banner,
 }: {
   current: string;
-  pages: DocPage[];
+  pages: LocalDocPage[];
   pkg: Package;
   banner?: JSXElement;
   externalLinkResolver: ResolveLinkFunction;
@@ -61,6 +62,33 @@ export function* ApiPage({
           </>
         ),
         linkResolver: createSibling,
+        versionToggle: yield* (function* () {
+          const { series: SERIES } = yield* useConfig();
+          const currentSeries = `v${major(pkg.version)}`;
+
+          const links = yield* all(
+            SERIES.map(function* (s) {
+              const seriesPkg = yield* usePackage({
+                type: "worktree",
+                series: s,
+              });
+              const seriesDocs = yield* seriesPkg.docs();
+              const hasSymbol = seriesDocs["."].some((node) => node.name === current);
+
+              if (!hasSymbol) return null;
+
+              return (
+                <a
+                  href={yield* createRootUrl(`api/${s}`)(current)}
+                  class={`text-base ${s === currentSeries ? "font-bold text-sky-500" : "text-gray-600 dark:text-gray-400 hover:text-sky-500"}`}
+                >
+                  {seriesPkg.version}
+                </a>
+              );
+            }),
+          );
+          return <span class="flex flex-row space-x-2">{...links.filter((link): link is JSXElement => link !== null)}</span>;
+        })(),
       })}
     </>
   );
@@ -70,7 +98,7 @@ export function* ApiBody({
   page,
   linkResolver,
 }: {
-  page: DocPage;
+  page: LocalDocPage;
   linkResolver: ResolveLinkFunction;
 }) {
   const elements: JSXElement[] = [];
@@ -89,8 +117,8 @@ export function* ApiBody({
               {yield* Type({ node: section.node })}
             </h2>
             <a
-              class="opacity-0 before:content-['View_code'] group-hover:opacity-100 before:flex before:text-xs before:mr-1 p-2 flex-none flex rounded no-underline items-center h-8"
-              href={`${section.node.location.filename}#L${section.node.location.line}`}
+              class="opacity-40 before:content-['View_code'] group-hover:opacity-100 before:flex before:text-xs before:mr-1 p-2 flex-none flex rounded no-underline items-center h-8"
+              href={`${section.node.location.url}`}
             >
               <SourceCodeIcon />
             </a>
@@ -115,29 +143,22 @@ export function* ApiReference({
   current,
   pages,
   linkResolver,
+  versionToggle
 }: {
   pkg: Package;
   content: JSXElement;
   current: string;
-  pages: DocPage[];
+  pages: LocalDocPage[];
   linkResolver: ResolveLinkFunction;
+  versionToggle: JSXElement;
 }) {
   return (
     <section class="min-h-0 mx-auto w-full justify-items-normal md:grid md:grid-cols-[225px_auto] lg:grid-cols-[225px_auto_200px] md:gap-4">
       <aside class="min-h-0 overflow-auto hidden md:block top-[120px] sticky h-fit bg-white dark:bg-gray-900 dark:text-gray-200">
         <nav class="pl-4">
           <h3 class="text-xl flex flex-col mb-3">
             <span class="font-bold">API Reference</span>
-            <span>
-              <a href={pkg.ref.url} class="font-semibold text-base">
-                {pkg.version}{" "}
-                <IconExternal
-                  class="inline-block align-baseline"
-                  height="15"
-                  width="15"
-                />
-              </a>
-            </span>
+            {versionToggle}
           </h3>
           {yield* Menu({ pages, current, linkResolver })}
         </nav>
@@ -153,7 +174,7 @@ export function* ApiReference({
   );
 }
 
-export function* SymbolHeader({ page, pkg }: { page: DocPage; pkg: Package }) {
+export function* SymbolHeader({ page, pkg }: { page: LocalDocPage; pkg: Package }) {
   return (
     <header class="flex flex-row items-center space-x-2">
       <h1 class="mb-0">
@@ -178,7 +199,7 @@ function* Menu({
   linkResolver,
 }: {
   current: string;
-  pages: DocPage[];
+  pages: LocalDocPage[];
   linkResolver: ResolveLinkFunction;
 }) {
   const elements = [];

www/components/header.tsx

@@ -32,7 +32,7 @@ export function* Header(props?: HeaderProps) {
             <li>
               <a
                 class="hover:text-pink-secondary dark:hover:text-blue-secondary transition-colors duration-200"
-                href="/guides/v3"
+                href="/guides/v4"
               >
                 Guides
               </a>

www/components/type/jsx.tsx

@@ -168,6 +168,16 @@ function TSParam({ param }: { param: ParamDef }) {
         </>
       );
     }
+    case "assign": {
+      return (
+        <>
+          <TSParam param={param.left} />
+          <Operator>{" = "}</Operator>
+          {param.tsType ? <TypeDef typeDef={param.tsType} /> : <></>}
+          {param.right === "[UNSUPPORTED]" ? "{}" : <></> }
+        </>
+      )
+    }
     default:
       console.log("<TSParam> unimplemented:", param);
   }

www/components/type/markdown.tsx

@@ -380,7 +380,6 @@ function Param(paramDef: ParamDef): string {
         paramDef.tsType ? TypeDef(paramDef.tsType) : ""
       }`;
     }
-    case "assign":
     case "array":
     case "object":
       console.log("Param: unimplemented", paramDef);

www/context/config.ts

@@ -0,0 +1,19 @@
+import { createContext, type Operation } from "effection";
+
+export interface SiteConfig<T extends string = string> {
+  series: T[];
+  current: NoInfer<T>;
+}
+
+const ConfigContext = createContext<SiteConfig>("site-config", {
+  series: ["v3", "v4"],
+  current: "v4",
+});
+
+export function* initConfig<T extends string>(config: SiteConfig<T>): Operation<void> {
+  yield* ConfigContext.set(config);
+}
+
+export function* useConfig(): Operation<SiteConfig> {
+  return yield* ConfigContext.expect();
+}

www/context/doc-page.ts

@@ -1,4 +1,4 @@
 import { createContext } from "effection";
-import type { DocPage } from "../hooks/use-deno-doc.tsx";
+import type { LocalDocPage } from "../hooks/use-deno-doc.tsx";
 
-export const DocPageContext = createContext<DocPage>("doc-page");
+export const DocPageContext = createContext<LocalDocPage>("doc-page");

www/hooks/use-deno-doc.tsx

@@ -4,15 +4,22 @@ import {
   type DocNode,
   type DocOptions,
   LoadResponse,
+  Location
 } from "@deno/doc";
 import { call, type Operation, until, useScope } from "effection";
 import { createGraph } from "@deno/graph";
+import { regex } from "arktype";
 
 import { exportHash, extract } from "../components/type/markdown.tsx";
 import { operations } from "../context/fetch.ts";
 import { DenoJsonSchema } from "../lib/deno-json.ts";
 import { useDescription } from "./use-description-parse.tsx";
 
+// Matches npm/jsr specifiers like @std/testing/bdd or lodash/fp
+export const npmSpecifierPattern = regex(
+  "^(?:(?<scope>@[^/]+)/)?(?<package>[^/]+)(?<subpath>/.*)?$"
+);
+
 export type { DocNode };
 
 export function* useDenoDoc(
@@ -67,6 +74,16 @@ export function* useDocPages(specifier: string): Operation<DocsPages> {
         resolved = new URL(specifier, referrer).toString();
       } else if (specifier.startsWith("node:")) {
         resolved = `npm:@types/node@^22.13.5`;
+      } else {
+        const match = npmSpecifierPattern.exec(specifier);
+        if (match) {
+          const { scope, package: pkg, subpath } = match.groups;
+          const baseKey = scope ? `${scope}/${pkg}` : pkg;
+          if (baseKey in imports) {
+            const baseUrl = imports[baseKey];
+            resolved = subpath ? `${baseUrl}${subpath}` : baseUrl;
+          }
+        }
       }
       return resolved;
     }
@@ -169,7 +186,7 @@ function docLoader(
       };
     }
 
-    if (url?.host === "github.com") {
+    if (url?.host && ['github.com', 'jsr.io'].includes(url.host)) {
       const response = yield* operations.fetch(specifier);
       const content = yield* until(response.text());
       if (response.ok) {
@@ -183,9 +200,7 @@ function docLoader(
           cause: response,
         });
       }
-    }
-
-    if (url?.host === "jsr.io") {
+    } else {
       console.log(`Ignoring ${url} while reading docs`);
     }
   };
@@ -281,3 +296,24 @@ function* extractImports(
 
   return imports;
 }
+
+/**
+ * LocalDocsPages are DocNodes that are stored locally
+ * but they represent symbols hosted on GitHub. They
+ * have LocalDocNode locations that include URLs to GitHub.
+ */
+export type LocalDocsPages = Record<string, LocalDocPage[]>;
+
+export type LocalDocPage = DocPage & { sections: LocalDocPageSection[] }
+
+export type LocalDocPageSection = DocPageSection & {
+  node: LocalDocNode
+}
+
+export type LocalDocNode = DocNode & {
+  location: LocalLocation
+}
+
+export type LocalLocation = Location & {
+  url: URL
+}

www/hooks/use-markdown.tsx

@@ -79,7 +79,7 @@ export function* useMarkdown(
         rehypeAddClasses,
         {
           "h1[id],h2[id],h3[id],h4[id],h5[id],h6[id]":
-            "group scroll-mt-[100px]",
+            "group scroll-mt-[100px] grow",
           pre: "grid",
         },
       ],