@sjolystinnovation/app-kit 0.11.0 → 0.12.0

package/README.md

@@ -28,7 +28,7 @@ const nextConfig: NextConfig = {
 };
 ```
 
-The components in `@sjolystinnovation/app-kit/ui` and `session/react` are styled with Tailwind CSS.
+The components in `@sjolystinnovation/app-kit/ui`, `markdown` and `session/react` are styled with Tailwind CSS.
 Import the package's stylesheet after Tailwind:
 
 ```css
@@ -348,6 +348,36 @@ The pieces are exported too: `securityHeaders(options)`, `contentSecurityPolicy(
 `apiBaseUrl(apiUrl)`. Scripts allow `'unsafe-inline'`, since a nonce would make every statically
 rendered page dynamic.
 
+### `@sjolystinnovation/app-kit/markdown`
+
+Renders Markdown from an editor or the API, with GitHub tables, task lists and footnotes. Raw HTML is
+never rendered and the output is sanitized, so the text cannot inject scripts, styles, event
+handlers or `javascript:` links. It works in a server component. It needs `react-markdown`,
+`remark-gfm` and `rehype-sanitize`, which are optional peer dependencies:
+
+```sh
+npm install react-markdown remark-gfm rehype-sanitize
+```
+
+```tsx
+import { Markdown } from "@sjolystinnovation/app-kit/markdown";
+
+<div className="space-y-4 text-sm text-gray-700">
+  <Markdown>{build.description}</Markdown>
+</div>;
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `children` | `string \| null \| undefined` | | The Markdown. Empty, null or undefined renders nothing. |
+| `components` | `Components` | | Replaces the element for a tag, such as `{ p: MyParagraph }`. Tags not named keep the default. It gets the props without `node`, so it can spread them onto an element. |
+| `externalLinks` | `boolean` | `false` | Opens `http` and `https` links in a new tab with `rel="noopener noreferrer"`. Site-relative links stay in the tab. |
+| `className` | `string` | | Wraps the output in a `div` with these classes. Without it the elements render bare, so a parent's `space-y-*` spaces them. |
+
+The text takes its colour and size from the parent. A level one heading becomes a level two, since
+the page has its own `h1`. `markdownComponents` holds the default elements, for an app that builds
+on them.
+
 ### `@sjolystinnovation/app-kit/session`
 
 Decides when a user has to sign in again. Safe to import from server code, such as the next-auth
@@ -836,6 +866,11 @@ selector such as `.dark` for a scoped theme:
 | `--color-state-code` | gray 900, the code of a `NotFoundState` |
 | `--font-state-code` | `inherit`, the font of that code |
 | `--color-state-link`, `-hover` | gray 900, the home link |
+| `--color-markdown-heading`, `-strong` | gray 900, headings and bold text in `Markdown` |
+| `--color-markdown-link` | gray 900 |
+| `--color-markdown-link-hover` | gray 600 |
+| `--color-markdown-border` | gray 200, rules, quotes and table lines |
+| `--color-markdown-code-bg`, `-code-text` | gray 100, gray 900 |
 
 A default that points at another variable is read once for the whole page. The focus ring and the
 primary button point at `--color-primary` and `--color-primary-foreground`. A scoped theme that

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sjolystinnovation/app-kit",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Building blocks for Next.js apps that sign in against a JWT API through next-auth",
   "license": "Apache-2.0",
   "author": "Sjølyst Innovation AS",
@@ -26,6 +26,7 @@
     "./toast": "./src/toast/index.ts",
     "./validation": "./src/validation/index.ts",
     "./next-config": "./src/next-config/index.ts",
+    "./markdown": "./src/markdown/index.ts",
     "./styles.css": "./src/styles.css"
   },
   "files": [
@@ -46,6 +47,9 @@
     "next-auth": "^4.24",
     "react": "^19",
     "react-dom": "^19",
+    "react-markdown": "^10",
+    "rehype-sanitize": "^6",
+    "remark-gfm": "^4",
     "sonner": "^2",
     "zod": "^4"
   },
@@ -55,6 +59,15 @@
     },
     "zod": {
       "optional": true
+    },
+    "react-markdown": {
+      "optional": true
+    },
+    "rehype-sanitize": {
+      "optional": true
+    },
+    "remark-gfm": {
+      "optional": true
     }
   },
   "devDependencies": {
@@ -71,6 +84,9 @@
     "next-auth": "^4.24.15",
     "react": "^19.3.0",
     "react-dom": "^19.3.0",
+    "react-markdown": "^10.1.0",
+    "rehype-sanitize": "^6.0.0",
+    "remark-gfm": "^4.0.1",
     "sonner": "^2.0.8",
     "typescript": "^6.0.3",
     "vitest": "^5.0.3",
@@ -85,7 +101,7 @@
     "tailwindcss"
   ],
   "dependencies": {
-    "@types/jsonwebtoken": "^9.0.8",
-    "jsonwebtoken": "^9.0.2"
+    "@types/jsonwebtoken": "^9.0.10",
+    "jsonwebtoken": "^9.0.3"
   }
 }

package/src/markdown/Markdown.tsx

@@ -0,0 +1,89 @@
+import type { ComponentPropsWithoutRef, ElementType } from "react";
+import ReactMarkdown, { type Components, type ExtraProps } from "react-markdown";
+import rehypeSanitize from "rehype-sanitize";
+import remarkGfm from "remark-gfm";
+
+type Tag = keyof React.JSX.IntrinsicElements;
+
+/** The props without the `node` react-markdown passes, which is no DOM attribute. */
+function domProps<P extends ExtraProps>(props: P): Omit<P, "node"> {
+  const rest = { ...props };
+  delete rest.node;
+  return rest;
+}
+
+/** An app's element, given the props without `node`, so it can spread them onto a DOM element. */
+function withoutNode(Element: ElementType) {
+  const Wrapped = (props: ExtraProps) => <Element {...domProps(props)} />;
+  return Wrapped;
+}
+
+/** An element with fixed classes. */
+function styled<T extends Tag>(Element: T, className: string) {
+  const Styled = (props: ComponentPropsWithoutRef<T> & ExtraProps) => {
+    const Component = Element as ElementType;
+    return <Component className={className} {...domProps(props)} />;
+  };
+  return Styled;
+}
+
+/** The default look. A heading level one becomes a level two, since the page has its own `h1`. */
+export const markdownComponents: Components = {
+  h1: styled("h2", "text-lg font-semibold text-markdown-heading"),
+  h2: styled("h2", "text-base font-semibold text-markdown-heading pt-2"),
+  h3: styled("h3", "text-sm font-semibold text-markdown-heading"),
+  p: styled("p", "leading-relaxed"),
+  ul: styled("ul", "list-disc list-outside pl-5 space-y-1"),
+  ol: styled("ol", "list-decimal list-outside pl-5 space-y-1"),
+  li: styled("li", "leading-relaxed"),
+  a: styled("a", "font-medium text-markdown-link underline hover:text-markdown-link-hover"),
+  strong: styled("strong", "font-semibold text-markdown-strong"),
+  hr: styled("hr", "border-markdown-border"),
+  blockquote: styled("blockquote", "border-l-2 border-markdown-border pl-4 italic"),
+  code: styled("code", "rounded bg-markdown-code-bg px-1 py-0.5 text-xs font-mono text-markdown-code-text"),
+  table: props => (
+    <div className="overflow-x-auto">
+      <table className="w-full text-xs border-collapse" {...domProps(props)} />
+    </div>
+  ),
+  thead: styled("thead", "border-b border-markdown-border"),
+  tbody: styled("tbody", "divide-y divide-markdown-border"),
+  th: styled("th", "text-left py-2 pr-4 font-semibold text-markdown-heading"),
+  td: styled("td", "py-2 pr-4 align-top"),
+};
+
+const isExternal = (href: string | undefined) => href != null && /^https?:\/\//i.test(href);
+
+export interface MarkdownProps {
+  /** Markdown text. Empty, null or undefined renders nothing. */
+  children: string | null | undefined;
+  /** Replaces the default element for a tag, such as `{ p: MyParagraph }`. It gets the props without `node`. */
+  components?: Components | undefined;
+  /** Opens links to other sites in a new tab, without passing the opener or referrer. */
+  externalLinks?: boolean | undefined;
+  /** Wraps the output in a `div` with these classes. Without it the elements render bare, so a parent's `space-y-*` spaces them. */
+  className?: string | undefined;
+}
+
+/**
+ * Markdown from an editor or the API, with GitHub tables, lists and links. Raw HTML is never
+ * rendered, and the output is sanitized, so the text cannot inject scripts, styles or event handlers.
+ */
+export function Markdown({ children, components, externalLinks = false, className }: MarkdownProps) {
+  if (!children) return null;
+
+  const own = Object.entries(components ?? {}).map(([tag, Element]) => [tag, withoutNode(Element as ElementType)]);
+  const merged: Components = { ...markdownComponents, ...Object.fromEntries(own) };
+  if (externalLinks) {
+    const Link = (merged.a ?? "a") as ElementType;
+    merged.a = props =>
+      isExternal(props.href) ? <Link {...props} target="_blank" rel="noopener noreferrer" /> : <Link {...props} />;
+  }
+
+  const output = (
+    <ReactMarkdown remarkPlugins={[remarkGfm]} rehypePlugins={[rehypeSanitize]} components={merged}>
+      {children}
+    </ReactMarkdown>
+  );
+  return className === undefined ? output : <div className={className}>{output}</div>;
+}

package/src/markdown/index.ts

@@ -0,0 +1 @@
+export { Markdown, markdownComponents, type MarkdownProps } from "./Markdown";

package/src/styles.css

@@ -52,6 +52,14 @@
   --color-state-link: var(--color-gray-900);
   --color-state-link-hover: var(--color-gray-900);
 
+  --color-markdown-heading: var(--color-gray-900);
+  --color-markdown-strong: var(--color-gray-900);
+  --color-markdown-link: var(--color-gray-900);
+  --color-markdown-link-hover: var(--color-gray-600);
+  --color-markdown-border: var(--color-gray-200);
+  --color-markdown-code-bg: var(--color-gray-100);
+  --color-markdown-code-text: var(--color-gray-900);
+
   --radius-button: var(--radius-lg);
   --color-button-primary-bg: var(--color-primary);
   --color-button-primary-text: var(--color-primary-foreground);