tailwind

docs/markdown.md

@@ -368,3 +368,44 @@ You may also want to add `noopener noreferrer` if linking to an untrusted origin
 ![A horse](./horse.jpg)
 ![A happy kitten](https://placekitten.com/200/300)
 ```
+
+## Tailwind CSS
+
+To go beyond grids and cards, Framework integrates [Tailwind](https://tailwindcss.com/), a toolkit that predefines utility classes driving styles directly from HTML.
+
+For example, let’s create a button with several styles — like `px-*` for horizontal padding:
+
+```html echo
+<button class="px-4 py-1 text-sm font-semibold rounded-full
+  text-purple-600 border border-purple-400
+  hover:text-white hover:bg-purple-600 hover:border-transparent
+">
+  Hello, Tailwind
+</button>
+```
+
+These classes drive the text’s size, the button’s rounded corners, the border and color of the text, *etc.* Note in particular the `hover:` modifier, which applies styles *conditionally*, when the pointer is over the button. Other supported modifiers include pseudo-classes (`:hover`, `:focus`, `:first-child`, and `:required`), pseudo-elements (`::before`, `::after`, `::placeholder`, and `::selection`), attribute selectors (`[dir="rtl"]` and `[open]`)…
+
+Size modifiers adapt styles to the container width:
+<p class="font-mono small">
+<span class="rounded-md px-2 py-1 border sm:bg-purple-200 sm:dark:bg-purple-800">sm:</span>
+<span class="rounded-md px-2 py-1 border md:bg-purple-200 md:dark:bg-purple-800">md:</span>
+<span class="rounded-md px-2 py-1 border lg:bg-purple-200 lg:dark:bg-purple-800">lg:</span>
+</p>
+
+The `dark:` modifier adapts to the current page’s `color-scheme`, to better support dark mode.
+
+Modifiers can be stacked; for instance, the `md:` pill above adopts a different shade of purple in light and dark modes, using the following classes:
+
+```html run=false
+<span class="md:bg-purple-200 md:dark:bg-purple-800">…</span>
+```
+
+While Tailwind offers a lot of features, those that you don’t actually use are not added to the bundled stylesheet, keeping its size as small as possible. (The list of classes used is derived by a simple string-based search in your Markdown pages and JavaScript modules.) You can fine-tune the configuration by creating a `tailwind.config.js` [configuration file](https://tailwindcss.com/docs/configuration) in your [source root](./config#root).
+
+For details, see [Tailwind’s official documentation](https://tailwindcss.com/docs/).
+
+```js
+// https://github.com/observablehq/framework/pull/1780 
+document.body.classList.toggle("dark", dark);
+```

package.json

@@ -123,6 +123,7 @@
     "cross-env": "^7.0.3",
     "d3-dsv": "^3.0.1",
     "d3-format": "^3.1.0",
+    "esbuild-plugin-tailwindcss": "^1.2.1",
     "eslint": "^8.50.0",
     "eslint-config-prettier": "^9.1.0",
     "eslint-import-resolver-typescript": "^3.6.1",

src/build.ts

@@ -181,10 +181,10 @@ export async function build(
       effects.output.write(`${faint("build")} ${path} ${faint("→")} `);
       if (specifier.startsWith("observablehq:theme-")) {
         const match = /^observablehq:theme-(?<theme>[\w-]+(,[\w-]+)*)?\.css$/.exec(specifier);
-        contents = await bundleStyles({theme: match!.groups!.theme?.split(",") ?? [], minify: true});
+        contents = await bundleStyles({theme: match!.groups!.theme?.split(",") ?? [], minify: true, root});
       } else {
         const clientPath = getClientPath(path.slice("/_observablehq/".length));
-        contents = await bundleStyles({path: clientPath, minify: true});
+        contents = await bundleStyles({path: clientPath, minify: true, root});
       }
       const hash = createHash("sha256").update(contents).digest("hex").slice(0, 8);
       const alias = applyHash(path, hash);
@@ -198,7 +198,7 @@ export async function build(
     } else if (!/^\w+:/.test(specifier)) {
       const sourcePath = join(root, specifier);
       effects.output.write(`${faint("build")} ${sourcePath} ${faint("→")} `);
-      const contents = await bundleStyles({path: sourcePath, minify: true});
+      const contents = await bundleStyles({path: sourcePath, minify: true, root});
       const hash = createHash("sha256").update(contents).digest("hex").slice(0, 8);
       const alias = applyHash(join("/_import", specifier), hash);
       aliases.set(resolveStylesheetPath(root, specifier), alias);

src/client/preview.js

@@ -155,6 +155,8 @@ export function open({hash, eval: compile} = {}) {
           for (const href of message.stylesheets.removed) {
             document.head.querySelector(`link[rel="stylesheet"][href="${href}"]`)?.remove();
           }
+          const tw = document.head.querySelector('link[rel="stylesheet"][href$="_observablehq/tailwind.css"]');
+          if (tw) tw.href = "" + tw.href; // reload tailwind.css
         }
         enableCopyButtons();
         break;

src/client/tailwind.css

@@ -0,0 +1,3 @@
+@import "tailwindcss/base";
+@import "tailwindcss/components";
+@import "tailwindcss/utilities";

src/preview.ts

@@ -133,7 +133,7 @@ export class PreviewServer {
       } else if (pathname === "/_observablehq/minisearch.json") {
         end(req, res, await searchIndex(config), "application/json");
       } else if ((match = /^\/_observablehq\/theme-(?<theme>[\w-]+(,[\w-]+)*)?\.css$/.exec(pathname))) {
-        end(req, res, await bundleStyles({theme: match.groups!.theme?.split(",") ?? []}), "text/css");
+        end(req, res, await bundleStyles({theme: match.groups!.theme?.split(",") ?? [], root}), "text/css");
       } else if (pathname.startsWith("/_observablehq/") && pathname.endsWith(".js")) {
         const path = getClientPath(pathname.slice("/_observablehq/".length));
         const options =
@@ -143,7 +143,7 @@ export class PreviewServer {
         end(req, res, await rollupClient(path, root, pathname, options), "text/javascript");
       } else if (pathname.startsWith("/_observablehq/") && pathname.endsWith(".css")) {
         const path = getClientPath(pathname.slice("/_observablehq/".length));
-        end(req, res, await bundleStyles({path}), "text/css");
+        end(req, res, await bundleStyles({path, root}), "text/css");
       } else if (pathname.startsWith("/_node/") || pathname.startsWith("/_jsr/") || pathname.startsWith("/_duckdb/")) {
         send(req, pathname, {root: join(root, ".observablehq", "cache")}).pipe(res);
       } else if (pathname.startsWith("/_npm/")) {
@@ -156,7 +156,7 @@ export class PreviewServer {
           if (module) {
             const sourcePath = join(root, path);
             await access(sourcePath, constants.R_OK);
-            end(req, res, await bundleStyles({path: sourcePath}), "text/css");
+            end(req, res, await bundleStyles({path: sourcePath, root}), "text/css");
             return;
           }
         } else if (pathname.endsWith(".js")) {

src/resolvers.ts

@@ -352,6 +352,7 @@ async function resolveResolvers(
   }
 
   // Add implicit stylesheets.
+  stylesheets.add("observablehq:tailwind.css");
   for (const specifier of getImplicitStylesheets(staticImports)) {
     stylesheets.add(specifier);
     if (specifier.startsWith("npm:")) {

src/rollup.ts

@@ -1,11 +1,14 @@
-import {extname, resolve} from "node:path/posix";
+import {writeFile} from "node:fs/promises";
+import {extname, join, resolve} from "node:path/posix";
 import {nodeResolve} from "@rollup/plugin-node-resolve";
 import {simple} from "acorn-walk";
 import {build} from "esbuild";
+import type {Plugin as ESBuildPlugin} from "esbuild";
+import {tailwindPlugin} from "esbuild-plugin-tailwindcss";
 import type {AstNode, OutputChunk, Plugin, ResolveIdResult} from "rollup";
 import {rollup} from "rollup";
 import esbuild from "rollup-plugin-esbuild";
-import {getClientPath, getStylePath} from "./files.js";
+import {getClientPath, getStylePath, maybeStat, prepareOutput} from "./files.js";
 import {annotatePath} from "./javascript/annotate.js";
 import type {StringLiteral} from "./javascript/source.js";
 import {getStringLiteralValue, isStringLiteral} from "./javascript/source.js";
@@ -18,6 +21,7 @@ import {THEMES, renderTheme} from "./theme.js";
 
 const STYLE_MODULES = {
   "observablehq:default.css": getStylePath("default.css"),
+  "observablehq:tailwind.css": getStylePath("tailwind.css"),
   ...Object.fromEntries(THEMES.map(({name, path}) => [`observablehq:theme-${name}.css`, path]))
 };
 
@@ -37,21 +41,33 @@ function rewriteInputsNamespace(code: string) {
 export async function bundleStyles({
   minify = false,
   path,
-  theme
+  theme,
+  root
 }: {
   minify?: boolean;
   path?: string;
   theme?: string[];
+  root: string;
 }): Promise<string> {
+  const plugins = path === getClientPath("tailwind.css") ? [await tailwindConfig(root)] : undefined;
   const result = await build({
     bundle: true,
     ...(path ? {entryPoints: [path]} : {stdin: {contents: renderTheme(theme!), loader: "css"}}),
     write: false,
     minify,
+    plugins,
     alias: STYLE_MODULES
   });
   let text = result.outputFiles[0].text;
   if (path === getClientPath("stdlib/inputs.css")) text = rewriteInputsNamespace(text);
+  // dirty patch for tailwind: remove margin:0 and styles resets for headers
+  // etc. It should probably be a tailwind plugin instead.
+  if (path === getClientPath("tailwind.css"))
+    text = text
+      .replaceAll(/}[^{]*h1,\n*h2,\n*h3,\n*h4,\n*h5,\n*h6[^}]+}\s*/g, "}")
+      .replace(/}[^{]*body[^}]+}\s*/, "}")
+      .replace(/box-sizing:\s*border-box;/, "");
+
   return text;
 }
 
@@ -185,3 +201,46 @@ function importMetaResolve(path: string, resolveImport: ImportResolver): Plugin
     }
   };
 }
+
+// Create a tailwind plugin, configured to reference as content the project
+// files that might contain tailwind class names, and the 'tw-' prefix. If a
+// tailwind.config.js is present in the project root, we import and merge it.
+async function tailwindConfig(root: string): Promise<ESBuildPlugin> {
+  const twconfig = "tailwind.config.js";
+  const configPath = join(root, ".observablehq", "cache", twconfig);
+  const s = await maybeStat(join(root, twconfig));
+  const m = await maybeStat(configPath);
+  if (!m || !s || !(m.mtimeMs > s.mtimeMs)) {
+    await prepareOutput(configPath);
+    await writeFile(
+      configPath,
+      `
+// File generated by rollup.ts; to configure tailwind, edit ${root}/tailwind.config.js
+${s ? `import cfg from "../../${twconfig}"` : "const cfg = {}"};
+const {theme, ...config} = cfg ?? {};
+export default {
+  content: {
+    files: [
+      "${root}/**/*.{js,md}" /* pages and components */,
+      "${root}/.observablehq/cache/**/*.md" /* page loaders */,
+      "${root}/.observablehq/cache/_import/**/*.js" /* transpiled components */
+    ]
+  },
+  darkMode: ["variant", "&:where([class~=dark], [class~=dark] *)"],
+  blocklist: ["grid", "grid-cols-2", "grid-cols-3", "grid-cols-4"],
+  prefix: "",
+  theme: {
+    screens: {
+      sm: "640px",
+      md: "768px",
+      lg: [{min: "calc(640px + 5rem + 192px)", max: "calc(912px + 6rem)"}, {min: "calc(640px + 7rem + 272px + 192px)"}]
+    },
+    ...theme
+  },
+  ...config
+};
+`
+    );
+  }
+  return tailwindPlugin({configPath});
+}