instui-markdown 0.0.7 → 0.0.9

package/README.md

@@ -1,23 +1,193 @@
-# vite-plus-starter
+# instui-markdown
 
-A starter for creating a Vite Plus project.
+React components for rendering markdown with [Instructure UI](https://instructure.design) components.
 
-## Development
-
-- Install dependencies:
+## Installation
 
 ```bash
-vp install
+npm install instui-markdown rehype-instui-markdown
 ```
 
-- Run the unit tests:
+You also need the InstUI peer dependencies your app will use. At minimum:
 
 ```bash
-vp test
+npm install react react-markdown remark-gfm rehype-raw rehype-slug \
+  @instructure/ui-text @instructure/ui-heading @instructure/ui-link \
+  @instructure/ui-list @instructure/ui-view
 ```
 
-- Build the library:
+## Usage
 
-```bash
-vp pack
+### `InstuiMarkdown`
+
+Renders a markdown string using InstUI components.
+
+```tsx
+import { InstuiMarkdown } from "instui-markdown";
+
+<InstuiMarkdown>{markdownString}</InstuiMarkdown>;
+```
+
+Pass `renderOptions` to control rendering behavior:
+
+```tsx
+<InstuiMarkdown
+  renderOptions={{
+    link: { permalinks: true, externalIcon: true },
+    table: { sortable: true, hover: true },
+    code: { lineNumbers: true },
+    color: { enabled: true },
+    icons: { enabled: true },
+  }}
+>
+  {markdownString}
+</InstuiMarkdown>
 ```
+
+### `InstuiMdxProvider`
+
+Wraps MDX content and maps MDX elements to InstUI components.
+
+```tsx
+import { InstuiMdxProvider } from "instui-markdown";
+import Content from "./content.mdx";
+
+<InstuiMdxProvider renderOptions={renderOptions}>
+  <Content />
+</InstuiMdxProvider>;
+```
+
+### `createInstuiMarkdownComponents`
+
+Returns the component map directly if you need to pass it to `react-markdown` or an MDX provider yourself.
+
+```tsx
+import ReactMarkdown from "react-markdown";
+import { createInstuiMarkdownComponents } from "instui-markdown";
+
+const components = createInstuiMarkdownComponents(renderOptions);
+
+<ReactMarkdown components={components}>{markdown}</ReactMarkdown>;
+```
+
+## Render options
+
+### `alert`
+
+Controls alert-styled blockquotes. Uses [GFM alert syntax](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts): `> [!NOTE]`, `> [!TIP]`, `> [!IMPORTANT]`, `> [!WARNING]`, `> [!CAUTION]`.
+
+| Option        | Type      | Default | Description                          |
+| ------------- | --------- | ------- | ------------------------------------ |
+| `closeButton` | `boolean` | `false` | Shows a dismiss button on each alert |
+
+### `table`
+
+| Option     | Type                             | Default  | Description                     |
+| ---------- | -------------------------------- | -------- | ------------------------------- |
+| `display`  | `"auto" \| "stacked" \| "fixed"` | `"auto"` | InstUI table layout mode        |
+| `hover`    | `boolean`                        | `false`  | Highlights rows on hover        |
+| `sortable` | `boolean`                        | `false`  | Enables sortable column headers |
+
+### `link`
+
+| Option               | Type      | Default                | Description                                |
+| -------------------- | --------- | ---------------------- | ------------------------------------------ |
+| `externalIcon`       | `boolean` | `false`                | Adds an icon to external links             |
+| `permalinks`         | `boolean` | `false`                | Appends a permalink anchor to each heading |
+| `permalinkClassName` | `string`  | `"mdx-heading-anchor"` | CSS class on permalink anchor elements     |
+
+### `code`
+
+Fenced code blocks render using the InstUI `SourceCodeEditor`. Supported languages: `json`, `yaml`, `markdown`, `css`, `html`, `javascript` (and aliases `js`, `jsx`, `ts`, `tsx`, `yml`).
+
+| Option                | Type             | Default | Description                            |
+| --------------------- | ---------------- | ------- | -------------------------------------- |
+| `editable`            | `boolean`        | `false` | Allows editing code blocks             |
+| `readOnly`            | `boolean`        | `true`  | Marks code blocks as read-only         |
+| `lineNumbers`         | `boolean`        | `false` | Shows line numbers                     |
+| `lineWrapping`        | `boolean`        | `false` | Wraps long lines                       |
+| `spellCheck`          | `boolean`        | `false` | Enables spell check in editable blocks |
+| `highlightActiveLine` | `boolean`        | `false` | Highlights the cursor's line           |
+| `direction`           | `"ltr" \| "rtl"` | `"ltr"` | Text direction                         |
+
+### `color`
+
+Wraps color literals in a visual swatch. Supports `#hex`, `rgb()`, `rgba()`, `hsl()`, and `hsla()` formats. Skips color values inside code fences.
+
+| Option    | Type      | Default | Description                   |
+| --------- | --------- | ------- | ----------------------------- |
+| `enabled` | `boolean` | `false` | Renders color swatches inline |
+
+### `icons`
+
+Renders icon tokens from `:iconName:` syntax. InstUI lookup runs first, then optional SimpleIcons lookup can run as a fallback through an app-provided resolver. You can omit the `Icon` prefix and the `Line`/`Solid` suffix for InstUI names, so `:Heart:`, `:HeartLine:`, and `:IconHeartLine:` all resolve to the same InstUI icon.
+
+Add an optional hex color with a pipe: `:Heart|#F00:`.
+
+Skips icon tokens inside code fences.
+
+| Option                  | Type                                    | Default     | Description                                                        |
+| ----------------------- | --------------------------------------- | ----------- | ------------------------------------------------------------------ |
+| `enabled`               | `boolean`                               | `false`     | Enables token-based icon rendering                                 |
+| `color`                 | `string`                                | `undefined` | Default color for all icon providers                               |
+| `providers.instui`      | `boolean`                               | `true`      | Enables InstUI lookup (`@instructure/ui-icons`)                    |
+| `providers.simpleIcons` | `boolean`                               | `true`      | Enables SimpleIcons fallback lookup                                |
+| `simpleIcons.color`     | `string`                                | `undefined` | Default color for SimpleIcons output (falls back to `icons.color`) |
+| `simpleIcons.resolve`   | `(code: string) => SimpleIconTokenData` | `undefined` | App-provided resolver for SimpleIcons SVG path data                |
+
+Example with SimpleIcons fallback:
+
+```tsx
+<InstuiMarkdown
+  renderOptions={{
+    icons: {
+      enabled: true,
+      providers: { instui: true, simpleIcons: true },
+      simpleIcons: {
+        resolve: (code) => {
+          if (code.toLowerCase() === "github") {
+            return {
+              title: "GitHub",
+              path: "M12 0C5.37 0 0 5.37 0 12...",
+              viewBox: "0 0 24 24",
+            };
+          }
+          return undefined;
+        },
+      },
+    },
+  }}
+>
+  {":GitHub: and :HeartLine:"}
+</InstuiMarkdown>
+```
+
+If no enabled provider can resolve a token, the original token text is left in place.
+
+## Peer dependencies
+
+`instui-markdown` requires the following peer dependencies. Install only what your content uses — the components map each markdown element to the matching InstUI package.
+
+| Package                              | Used for                              |
+| ------------------------------------ | ------------------------------------- |
+| `react`                              | All components                        |
+| `react-markdown`                     | Markdown parsing                      |
+| `remark-gfm`                         | GFM tables, task lists, strikethrough |
+| `rehype-raw`                         | Inline HTML in markdown               |
+| `rehype-slug`                        | Heading IDs                           |
+| `rehype-autolink-headings`           | Heading permalink anchors             |
+| `@mdx-js/react`                      | `InstuiMdxProvider`                   |
+| `@instructure/ui-alerts`             | `> [!NOTE]` and other alerts          |
+| `@instructure/ui-badge`              | Color swatch badges                   |
+| `@instructure/ui-checkbox`           | Task list items                       |
+| `@instructure/ui-color-utils`        | Color contrast for swatches           |
+| `@instructure/ui-heading`            | `h1`–`h6`                             |
+| `@instructure/ui-icons`              | Icon tokens and permalink icons       |
+| `@instructure/ui-img`                | Images                                |
+| `@instructure/ui-link`               | Links                                 |
+| `@instructure/ui-list`               | Ordered and unordered lists           |
+| `@instructure/ui-source-code-editor` | Fenced code blocks                    |
+| `@instructure/ui-svg-images`         | Inline SVG elements                   |
+| `@instructure/ui-table`              | Tables                                |
+| `@instructure/ui-text`               | Paragraphs and inline text            |
+| `@instructure/ui-view`               | Block wrappers and horizontal rules   |

package/dist/index.mjs

@@ -442,38 +442,90 @@ function createBlockquoteComponent(options) {
 }
 //#endregion
 //#region src/components/span-component.tsx
+function toPascalCase(str) {
+	return str.charAt(0).toUpperCase() + str.slice(1).toLowerCase();
+}
+function parseIconTokenName(iconName) {
+	const withoutPrefix = iconName.startsWith("Icon") ? iconName.slice(4) : iconName;
+	const isSolid = withoutPrefix.endsWith("Solid");
+	const isInstUI = withoutPrefix.endsWith("InstUIIcon");
+	let root = withoutPrefix;
+	if (isSolid) root = withoutPrefix.slice(0, -5);
+	else if (isInstUI) root = withoutPrefix.slice(0, -10);
+	else if (withoutPrefix.endsWith("Line")) root = withoutPrefix.slice(0, -4);
+	return {
+		withoutPrefix,
+		isSolid,
+		isInstUI,
+		root
+	};
+}
+function getSimpleIconCodes(iconName, root, withoutPrefix) {
+	const camel = root.charAt(0).toLowerCase() + root.slice(1);
+	const lower = root.toLowerCase();
+	return Array.from(new Set([
+		iconName,
+		withoutPrefix,
+		root,
+		camel,
+		lower
+	]));
+}
 function createSpanComponent(options) {
 	return ({ children, className, ...props }) => {
 		if (className?.includes("icon-token") && options.showIcons) {
 			const iconName = props["data-icon"];
 			const inlineIconColor = props["data-icon-color"];
 			if (iconName) {
-				const withoutPrefix = iconName.startsWith("Icon") ? iconName.slice(4) : iconName;
-				const isSolid = withoutPrefix.endsWith("Solid");
-				const isInstUI = withoutPrefix.endsWith("InstUIIcon");
-				let root = withoutPrefix;
-				if (isSolid) root = withoutPrefix.slice(0, -5);
-				else if (isInstUI) root = withoutPrefix.slice(0, -10);
-				else if (withoutPrefix.endsWith("Line")) root = withoutPrefix.slice(0, -4);
-				const IconComponent = (isSolid ? [`Icon${root}Solid`] : isInstUI ? [`${root}InstUIIcon`] : [
-					`${root}InstUIIcon`,
-					`Icon${root}Line`,
-					`Icon${root}`
-				]).map((name) => InstUIIcons[name]).find(Boolean);
-				if (IconComponent) {
-					const resolvedColor = inlineIconColor ?? options.iconColor;
-					const normalizedIconColor = resolvedColor && isLiteralColorValue(resolvedColor) ? normalizeColorForSwatch(resolvedColor) : void 0;
-					if (normalizedIconColor) return /* @__PURE__ */ jsx("span", {
-						style: { color: normalizedIconColor },
-						children: /* @__PURE__ */ jsx(IconComponent, {
+				const { withoutPrefix, isSolid, isInstUI, root } = parseIconTokenName(iconName);
+				if (options.enableInstuiIcons) {
+					const normalizedRoot = toPascalCase(root);
+					const IconComponent = (isSolid ? [`Icon${normalizedRoot}Solid`] : isInstUI ? [`${normalizedRoot}InstUIIcon`] : [
+						`${normalizedRoot}InstUIIcon`,
+						`Icon${normalizedRoot}Line`,
+						`Icon${normalizedRoot}`
+					]).map((name) => InstUIIcons[name]).find(Boolean);
+					if (IconComponent) {
+						const resolvedColor = inlineIconColor ?? options.iconColor;
+						const normalizedIconColor = resolvedColor && isLiteralColorValue(resolvedColor) ? normalizeColorForSwatch(resolvedColor) : void 0;
+						const sizeProps = IconComponent.displayName?.startsWith("InstUIIcon_") ? { size: "x-small" } : {};
+						if (normalizedIconColor) return /* @__PURE__ */ jsx("span", {
+							style: { color: normalizedIconColor },
+							children: /* @__PURE__ */ jsx(IconComponent, {
+								title: iconName,
+								color: "inherit",
+								...sizeProps
+							})
+						});
+						return /* @__PURE__ */ jsx(IconComponent, {
 							title: iconName,
-							color: "inherit"
-						})
-					});
-					return /* @__PURE__ */ jsx(IconComponent, {
-						title: iconName,
-						color: (resolvedColor === "currentColor" ? "inherit" : resolvedColor) ?? "inherit"
-					});
+							color: (resolvedColor === "currentColor" ? "inherit" : resolvedColor) ?? "inherit",
+							...sizeProps
+						});
+					}
+				}
+				if (options.enableSimpleIcons && options.resolveSimpleIcon) {
+					const simpleIcon = getSimpleIconCodes(iconName, root, withoutPrefix).map((code) => options.resolveSimpleIcon?.(code)).find(Boolean);
+					if (simpleIcon?.path) {
+						const resolvedColor = inlineIconColor ?? options.simpleIconColor ?? options.iconColor;
+						const normalizedIconColor = resolvedColor && isLiteralColorValue(resolvedColor) ? normalizeColorForSwatch(resolvedColor) : void 0;
+						const label = simpleIcon.title ?? root;
+						return /* @__PURE__ */ jsx("span", {
+							style: normalizedIconColor ? { color: normalizedIconColor } : void 0,
+							children: /* @__PURE__ */ jsxs(InlineSVG, {
+								inline: false,
+								viewBox: simpleIcon.viewBox ?? "0 0 24 24",
+								width: simpleIcon.width ?? "1em",
+								height: simpleIcon.height ?? "1em",
+								role: "img",
+								"aria-label": label,
+								children: [/* @__PURE__ */ jsx("title", { children: label }), /* @__PURE__ */ jsx("path", {
+									d: simpleIcon.path,
+									fill: "currentColor"
+								})]
+							})
+						});
+					}
 				}
 			}
 		}
@@ -651,11 +703,19 @@ function createInstuiMarkdownComponents(renderOptions = {}) {
 	const showColorCodes = Boolean(renderOptions.color?.enabled);
 	const showIcons = Boolean(renderOptions.icons?.enabled);
 	const iconColor = renderOptions.icons?.color;
+	const enableInstuiIcons = renderOptions.icons?.providers?.instui ?? true;
+	const enableSimpleIcons = renderOptions.icons?.providers?.simpleIcons ?? true;
+	const simpleIconColor = renderOptions.icons?.simpleIcons?.color;
+	const resolveSimpleIcon = renderOptions.icons?.simpleIcons?.resolve;
 	return {
 		span: createSpanComponent({
 			showColorCodes,
 			showIcons,
-			iconColor
+			iconColor,
+			enableInstuiIcons,
+			enableSimpleIcons,
+			simpleIconColor,
+			resolveSimpleIcon
 		}),
 		a: createLinkComponent({
 			showExternalIcon,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instui-markdown",
-  "version": "0.0.7",
+  "version": "0.0.9",
   "description": "InstUI markdown renderer components",
   "license": "MIT",
   "files": [
@@ -21,7 +21,7 @@
     "access": "public"
   },
   "dependencies": {
-    "rehype-instui-markdown": "0.0.7"
+    "rehype-instui-markdown": "0.0.9"
   },
   "devDependencies": {
     "@types/node": "^24",