Markdown tweaks

.yarn/versions/5766cc7b.yml

@@ -0,0 +1,3 @@
+releases:
+  "@essex/components": patch
+  essex-toolkit-stories: patch

packages/components/docs/markdown/components.markdownbrowserprops.home.md

@@ -9,5 +9,5 @@ Key for the default 'home' content to render.
 <b>Signature:</b>
 
 ```typescript
-home: string;
+home?: string;
 ```

packages/components/docs/markdown/components.markdownbrowserprops.md

@@ -16,7 +16,7 @@ export interface MarkdownBrowserProps
 |  --- | --- | --- | --- |
 |  [backButtonProps?](./components.markdownbrowserprops.backbuttonprops.md) |  | IButtonProps | <i>(Optional)</i> |
 |  [content](./components.markdownbrowserprops.content.md) |  | Record&lt;string, string&gt; | <p>Map of content with: key: The content key (typically relative filename). content: The markdown content to render.</p><p>Relative paths in hyperlinks will be checked for content to navigate to. Fully-qualified paths (e.g., URLs) will be opened in a new window/tab.</p> |
-|  [home](./components.markdownbrowserprops.home.md) |  | string | Key for the default 'home' content to render. |
+|  [home?](./components.markdownbrowserprops.home.md) |  | string | <i>(Optional)</i> Key for the default 'home' content to render. |
 |  [homeButtonProps?](./components.markdownbrowserprops.homebuttonprops.md) |  | IButtonProps | <i>(Optional)</i> |
 |  [styles?](./components.markdownbrowserprops.styles.md) |  | [MarkdownBrowserStyles](./components.markdownbrowserstyles.md) | <i>(Optional)</i> |
 

packages/components/docs/report/components.api.json

@@ -2987,7 +2987,7 @@
               "excerptTokens": [
                 {
                   "kind": "Content",
-                  "text": "home: "
+                  "text": "home?: "
                 },
                 {
                   "kind": "Content",
@@ -2999,7 +2999,7 @@
                 }
               ],
               "isReadonly": false,
-              "isOptional": false,
+              "isOptional": true,
               "releaseTag": "Public",
               "name": "home",
               "propertyTypeTokenRange": {

packages/components/docs/report/components.api.md

@@ -291,7 +291,7 @@ export interface MarkdownBrowserProps {
     // (undocumented)
     backButtonProps?: IButtonProps;
     content: Record<string, string>;
-    home: string;
+    home?: string;
     // (undocumented)
     homeButtonProps?: IButtonProps;
     // (undocumented)

packages/components/src/MarkdownBrowser/MarkdownBrowser.hooks.ts

@@ -9,15 +9,15 @@ import { useCallback, useEffect, useMemo, useState } from 'react'
 
 import { useIconButtonStyles } from './MarkdownBrowser.styles.js'
 
-export function useHistory(home: string): {
-	current: string
+export function useHistory(home?: string): {
+	current: string | undefined
 	goHome?: () => void
 	goBack?: () => void
 	goForward: (to: string) => void
 } {
-	const [stack, setStack] = useState<string[]>([home])
+	const [stack, setStack] = useState<string[]>([])
 	// reset the stack and go to the original
-	const goHome = useCallback(() => setStack([home]), [home])
+	const goHome = useCallback(() => setStack(home ? [home] : []), [home])
 	const goBack = useCallback(
 		() => setStack((prev) => (prev.length > 1 ? prev.slice(0, -1) : prev)),
 		[],
@@ -26,6 +26,7 @@ export function useHistory(home: string): {
 		(to: string) => setStack((prev) => [...prev, to]),
 		[],
 	)
+	useEffect(() => setStack(home ? [home] : []), [home])
 	return {
 		current: stack[stack.length - 1],
 		goHome: stack.length > 1 ? goHome : undefined,
@@ -37,7 +38,7 @@ export function useHistory(home: string): {
 export function useLinkNavigation(
 	container: React.MutableRefObject<HTMLDivElement | null>,
 	goForward: (to: string) => void,
-	current: string,
+	current: string | undefined,
 ) {
 	const onLinkClick = useCallback(
 		(url: string) => {

packages/components/src/MarkdownBrowser/MarkdownBrowser.stories.tsx

@@ -2,8 +2,9 @@
  * Copyright (c) Microsoft. All rights reserved.
  * Licensed under the MIT license. See LICENSE file in the project.
  */
-import styled from '@essex/styled-components'
+import { DefaultButton } from '@fluentui/react'
 import type { ComponentStory } from '@storybook/react'
+import { useState } from 'react'
 
 import { MarkdownBrowser } from './MarkdownBrowser.js'
 import type { MarkdownBrowserProps } from './MarkdownBrowser.types.js'
@@ -95,16 +96,35 @@ Here is a [missing link](./missing.md).
 const Template: ComponentStory<typeof MarkdownBrowser> = (
 	args: MarkdownBrowserProps,
 ) => {
+	const [home, setHome] = useState<string | undefined>('aggregate')
+
 	return (
-		<div
-			style={{
-				width: 600,
-				height: 400,
-				padding: 12,
-				border: '1px solid orange',
-			}}
-		>
-			<MarkdownBrowser {...args} content={content} home={'aggregate'} />
+		<div>
+			<div
+				style={{
+					display: 'flex',
+					gap: 8,
+					marginBottom: 8,
+				}}
+			>
+				<DefaultButton onClick={() => setHome('aggregate')}>
+					aggregate
+				</DefaultButton>
+				<DefaultButton onClick={() => setHome('groupby')}>
+					groupby
+				</DefaultButton>
+				<DefaultButton onClick={() => setHome(undefined)}>clear</DefaultButton>
+			</div>
+			<div
+				style={{
+					width: 600,
+					height: 400,
+					padding: 12,
+					border: '1px solid orange',
+				}}
+			>
+				<MarkdownBrowser {...args} content={content} home={home} />
+			</div>
 		</div>
 	)
 }

packages/components/src/MarkdownBrowser/MarkdownBrowser.tsx

@@ -39,7 +39,7 @@ export const MarkdownBrowser: React.FC<MarkdownBrowserProps> = memo(
 		useLinkNavigation(container, goForward, current)
 
 		// fallback to empty string - markdown component will fail if content is undefined
-		const md = content[current] || ''
+		const md = current ? content[current] : ''
 
 		const backProps = useIconButtonProps('Back', goBack, backButtonProps)
 		const homeProps = useIconButtonProps('Home', goHome, homeButtonProps)
@@ -49,7 +49,9 @@ export const MarkdownBrowser: React.FC<MarkdownBrowserProps> = memo(
 					{goBack && <IconButton {...backProps} />}
 					{goHome && <IconButton {...homeProps} />}
 				</Navigation>
-				<MarkdownContainer style={styles.markdown}>{md}</MarkdownContainer>
+				{md && (
+					<MarkdownContainer style={styles.markdown}>{md}</MarkdownContainer>
+				)}
 			</Container>
 		)
 	},

packages/components/src/MarkdownBrowser/MarkdownBrowser.types.ts

@@ -37,7 +37,7 @@ export interface MarkdownBrowserProps {
 	/**
 	 * Key for the default 'home' content to render.
 	 */
-	home: string
+	home?: string
 	styles?: MarkdownBrowserStyles
 	backButtonProps?: IButtonProps
 	homeButtonProps?: IButtonProps