fix: support structured user variables

__tests__/variables/index.test.tsx

@@ -34,4 +34,13 @@ export const Hello = () => <p>{user.name}</p>;
 
     expect(screen.getByText('Owlbert')).toBeVisible();
   });
+
+  it('supports structured user variables', () => {
+    const md = '{user.keys.length}';
+    const Content = execute(md, {}, { variables: { user: { keys: [{ apiKey: 'rdme_123' }] } } });
+
+    render(<Content />);
+
+    expect(screen.getByText('1')).toBeVisible();
+  });
 });

processor/plugin/toc.ts

@@ -16,6 +16,7 @@ import { h } from 'hastscript';
 
 import { mdx, plain } from '../../lib';
 import { STANDARD_HTML_TAGS } from '../../utils/common-html-words';
+import { flattenUserVariables } from '../../utils/user';
 import { hasNamedExport } from '../utils';
 
 const HEADING_TAGS = ['h1', 'h2', 'h3', 'h4', 'h5', 'h6'];
@@ -149,7 +150,7 @@ const getDepth = (el: HastHeading) => {
 const flattenVariables = (variables?: Variables): Record<string, string> => {
   if (!variables) return {};
   return {
-    ...variables.user,
+    ...flattenUserVariables(variables.user),
     ...Object.fromEntries(
       (variables.defaults || []).filter(d => !(d.name in variables.user)).map(d => [d.name, d.default]),
     ),

processor/transform/mdxish/variables-code.ts

@@ -5,6 +5,8 @@ import type { Plugin } from 'unified';
 import { MDX_VARIABLE_REGEXP, VARIABLE_REGEXP } from '@readme/variable';
 import { visit } from 'unist-util-visit';
 
+import { flattenUserVariables } from '../../../utils/user';
+
 interface Options {
   variables?: Variables;
 }
@@ -18,7 +20,7 @@ function flattenVariables(variables?: Variables): Record<string, string> {
 
   return {
     ...Object.fromEntries((variables.defaults || []).map(d => [d.name, d.default])),
-    ...variables.user,
+    ...flattenUserVariables(variables.user),
   };
 }
 

types.d.ts

@@ -277,7 +277,7 @@ interface TocList extends Element {
 
 interface Variables {
   defaults: { default: string; name: string }[];
-  user: Record<string, string>;
+  user: Record<string, unknown>;
 }
 
 interface TocListItem extends Element {

utils/user.ts

@@ -5,9 +5,30 @@ interface Default {
 
 export interface Variables {
   defaults: Default[];
-  user: Record<string, string>;
+  user: Record<string, unknown>;
 }
 
+/**
+ * Coerce a user variable value to a string for substitution into markdown text.
+ * Non-string values (arrays, objects, numbers) are stringified via JSON or `String()`
+ * so that `<<var>>` syntax doesn't produce `[object Object]` for structured data like
+ * JWT `keys`.
+ */
+const stringifyVariableValue = (value: unknown): string => {
+  if (typeof value === 'string') return value;
+  if (value == null) return '';
+  if (typeof value === 'object') return JSON.stringify(value) ?? '';
+  return String(value);
+};
+
+/**
+ * Flatten `variables.user` into a string-keyed string-valued record by coercing
+ * each value. Used by markdown substitution paths that need a plain
+ * `Record<string, string>` lookup.
+ */
+export const flattenUserVariables = (user: Record<string, unknown>): Record<string, string> =>
+  Object.fromEntries(Object.entries(user).map(([name, value]) => [name, stringifyVariableValue(value)]));
+
 const User = (variables?: Variables) => {
   const { user = {}, defaults = [] } = variables || {};