@furystack/shades-common-components 15.0.4 → 15.1.0

package/src/components/route-breadcrumb.spec.tsx

@@ -0,0 +1,239 @@
+import { Injector } from '@furystack/inject'
+import { createComponent, flushUpdates, initializeShadeRoot, RouteMatchService } from '@furystack/shades'
+import type { MatchChainEntry } from '@furystack/shades'
+import { usingAsync } from '@furystack/utils'
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { RouteBreadcrumb } from './route-breadcrumb.js'
+
+const createMatchChainEntry = (
+  path: string,
+  title?: string | (({ match, injector }: { match: unknown; injector: unknown }) => Promise<string>),
+): MatchChainEntry =>
+  ({
+    route: { meta: title != null ? { title } : undefined, component: () => <div /> },
+    match: { path, params: {} },
+  }) as MatchChainEntry
+
+const tick = () => new Promise((resolve) => setTimeout(resolve, 0))
+
+const flushAsync = async () => {
+  await flushUpdates()
+  await tick()
+  await flushUpdates()
+}
+
+describe('RouteBreadcrumb', () => {
+  beforeEach(() => {
+    document.body.innerHTML = '<div id="root"></div>'
+  })
+  afterEach(() => {
+    document.body.innerHTML = ''
+  })
+
+  it('Should render items derived from the match chain', async () => {
+    await usingAsync(new Injector(), async (injector) => {
+      const rootElement = document.getElementById('root') as HTMLDivElement
+      const routeMatchService = injector.getInstance(RouteMatchService)
+
+      routeMatchService.currentMatchChain.setValue([
+        createMatchChainEntry('/', 'Home'),
+        createMatchChainEntry('/users', 'Users'),
+        createMatchChainEntry('/profile', 'Profile'),
+      ])
+
+      initializeShadeRoot({
+        injector,
+        rootElement,
+        jsxElement: <RouteBreadcrumb />,
+      })
+
+      await flushAsync()
+
+      const nav = rootElement.querySelector('nav[is="shade-breadcrumb"]')
+      expect(nav).toBeTruthy()
+      expect(nav?.textContent).toContain('Users')
+      expect(nav?.textContent).toContain('Profile')
+    })
+  })
+
+  it('Should skip the root "/" segment by default', async () => {
+    await usingAsync(new Injector(), async (injector) => {
+      const rootElement = document.getElementById('root') as HTMLDivElement
+      const routeMatchService = injector.getInstance(RouteMatchService)
+
+      routeMatchService.currentMatchChain.setValue([
+        createMatchChainEntry('/', 'Home'),
+        createMatchChainEntry('/users', 'Users'),
+      ])
+
+      initializeShadeRoot({
+        injector,
+        rootElement,
+        jsxElement: <RouteBreadcrumb />,
+      })
+
+      await flushAsync()
+
+      const nav = rootElement.querySelector('nav[is="shade-breadcrumb"]')
+      expect(nav?.textContent).not.toContain('Home')
+      expect(nav?.textContent).toContain('Users')
+    })
+  })
+
+  it('Should include root segment when skipRootPath is false', async () => {
+    await usingAsync(new Injector(), async (injector) => {
+      const rootElement = document.getElementById('root') as HTMLDivElement
+      const routeMatchService = injector.getInstance(RouteMatchService)
+
+      routeMatchService.currentMatchChain.setValue([
+        createMatchChainEntry('/', 'Home'),
+        createMatchChainEntry('/users', 'Users'),
+      ])
+
+      initializeShadeRoot({
+        injector,
+        rootElement,
+        jsxElement: <RouteBreadcrumb skipRootPath={false} />,
+      })
+
+      await flushAsync()
+
+      const nav = rootElement.querySelector('nav[is="shade-breadcrumb"]')
+      expect(nav?.textContent).toContain('Home')
+      expect(nav?.textContent).toContain('Users')
+    })
+  })
+
+  it('Should resolve async titles', async () => {
+    await usingAsync(new Injector(), async (injector) => {
+      const rootElement = document.getElementById('root') as HTMLDivElement
+      const routeMatchService = injector.getInstance(RouteMatchService)
+
+      routeMatchService.currentMatchChain.setValue([createMatchChainEntry('/settings', async () => 'Settings')])
+
+      initializeShadeRoot({
+        injector,
+        rootElement,
+        jsxElement: <RouteBreadcrumb />,
+      })
+
+      await flushAsync()
+
+      const nav = rootElement.querySelector('nav[is="shade-breadcrumb"]')
+      expect(nav?.textContent).toContain('Settings')
+    })
+  })
+
+  it('Should skip entries without a title', async () => {
+    await usingAsync(new Injector(), async (injector) => {
+      const rootElement = document.getElementById('root') as HTMLDivElement
+      const routeMatchService = injector.getInstance(RouteMatchService)
+
+      routeMatchService.currentMatchChain.setValue([
+        createMatchChainEntry('/layout'),
+        createMatchChainEntry('/users', 'Users'),
+      ])
+
+      initializeShadeRoot({
+        injector,
+        rootElement,
+        jsxElement: <RouteBreadcrumb />,
+      })
+
+      await flushAsync()
+
+      const nav = rootElement.querySelector('nav[is="shade-breadcrumb"]')
+      expect(nav?.textContent).toContain('Users')
+    })
+  })
+
+  it('Should pass through homeItem prop', async () => {
+    await usingAsync(new Injector(), async (injector) => {
+      const rootElement = document.getElementById('root') as HTMLDivElement
+      const routeMatchService = injector.getInstance(RouteMatchService)
+
+      routeMatchService.currentMatchChain.setValue([createMatchChainEntry('/users', 'Users')])
+
+      initializeShadeRoot({
+        injector,
+        rootElement,
+        jsxElement: <RouteBreadcrumb homeItem={{ path: '/', label: 'Home' }} />,
+      })
+
+      await flushAsync()
+
+      const nav = rootElement.querySelector('nav[is="shade-breadcrumb"]')
+      expect(nav?.textContent).toContain('Home')
+      expect(nav?.textContent).toContain('Users')
+    })
+  })
+
+  it('Should pass through separator prop', async () => {
+    await usingAsync(new Injector(), async (injector) => {
+      const rootElement = document.getElementById('root') as HTMLDivElement
+      const routeMatchService = injector.getInstance(RouteMatchService)
+
+      routeMatchService.currentMatchChain.setValue([
+        createMatchChainEntry('/users', 'Users'),
+        createMatchChainEntry('/profile', 'Profile'),
+      ])
+
+      initializeShadeRoot({
+        injector,
+        rootElement,
+        jsxElement: <RouteBreadcrumb separator=" › " />,
+      })
+
+      await flushAsync()
+
+      const separator = rootElement.querySelector('[data-separator="true"]')
+      expect(separator?.textContent).toBe(' › ')
+    })
+  })
+
+  it('Should handle empty match chain gracefully', async () => {
+    await usingAsync(new Injector(), async (injector) => {
+      const rootElement = document.getElementById('root') as HTMLDivElement
+
+      initializeShadeRoot({
+        injector,
+        rootElement,
+        jsxElement: <RouteBreadcrumb />,
+      })
+
+      await flushAsync()
+
+      const nav = rootElement.querySelector('nav[is="shade-breadcrumb"]')
+      expect(nav).toBeTruthy()
+    })
+  })
+
+  it('Should accumulate paths from nested segments', async () => {
+    await usingAsync(new Injector(), async (injector) => {
+      const rootElement = document.getElementById('root') as HTMLDivElement
+      const routeMatchService = injector.getInstance(RouteMatchService)
+
+      routeMatchService.currentMatchChain.setValue([
+        createMatchChainEntry('/', 'Home'),
+        createMatchChainEntry('/users', 'Users'),
+        createMatchChainEntry('/profile', 'Profile'),
+      ])
+
+      initializeShadeRoot({
+        injector,
+        rootElement,
+        jsxElement: <RouteBreadcrumb lastItemClickable={true} />,
+      })
+
+      await flushAsync()
+
+      const usersLink = rootElement.querySelector('a[href="/users"]')
+      expect(usersLink).toBeTruthy()
+      expect(usersLink?.textContent).toBe('Users')
+
+      const profileLink = rootElement.querySelector('a[href="/users/profile"]')
+      expect(profileLink).toBeTruthy()
+      expect(profileLink?.textContent).toBe('Profile')
+    })
+  })
+})

package/src/components/route-breadcrumb.tsx

@@ -0,0 +1,83 @@
+import type { MatchChainEntry, PartialElement } from '@furystack/shades'
+import { createComponent, RouteMatchService, Shade, resolveRouteTitles } from '@furystack/shades'
+
+import type { BreadcrumbItem } from './breadcrumb.js'
+import { Breadcrumb } from './breadcrumb.js'
+
+/**
+ * Props for the RouteBreadcrumb component.
+ */
+export type RouteBreadcrumbProps = {
+  homeItem?: BreadcrumbItem
+  separator?: string | JSX.Element
+  lastItemClickable?: boolean
+  /**
+   * When true, the root `'/'` path segment is excluded from the generated items.
+   * Typically the root is represented by `homeItem` instead.
+   * @default true
+   */
+  skipRootPath?: boolean
+} & PartialElement<HTMLElement>
+
+/**
+ * Breadcrumb component that automatically derives its items from the current
+ * {@link RouteMatchService} match chain. It resolves route titles from
+ * `meta.title` (supporting async resolvers) and accumulates path segments
+ * to produce the correct `href` for each breadcrumb link.
+ *
+ * @example
+ * ```tsx
+ * <RouteBreadcrumb
+ *   homeItem={{ path: '/', label: <Icon icon={icons.home} size="small" /> }}
+ *   separator=" › "
+ * />
+ * ```
+ */
+export const RouteBreadcrumb = Shade<RouteBreadcrumbProps>({
+  customElementName: 'shade-route-breadcrumb',
+  render: ({ props, injector, useObservable, useState }) => {
+    const { skipRootPath = true, ...breadcrumbProps } = props
+
+    const routeMatchService = injector.getInstance(RouteMatchService)
+
+    const [resolvedItems, setResolvedItems] = useState<BreadcrumbItem[]>('resolvedItems', [])
+    const [initializedRef] = useState<{ current: boolean }>('initialized', { current: false })
+    const [generationRef] = useState<{ current: number }>('generation', { current: 0 })
+
+    const resolveAndSetTitles = async (chain: MatchChainEntry[]) => {
+      const generation = ++generationRef.current
+      const titles = await resolveRouteTitles(chain, injector)
+
+      if (generation !== generationRef.current) return
+
+      const items: BreadcrumbItem[] = []
+      let accumulatedPath = ''
+
+      for (let i = 0; i < chain.length; i++) {
+        const title = titles[i]
+        if (!title) continue
+
+        const matchPath = chain[i].match.path
+        if (skipRootPath && matchPath === '/') continue
+
+        accumulatedPath += matchPath
+        items.push({ path: accumulatedPath, label: title })
+      }
+
+      setResolvedItems(items)
+    }
+
+    const [matchChain] = useObservable('matchChain', routeMatchService.currentMatchChain, {
+      onChange: (chain) => {
+        void resolveAndSetTitles(chain)
+      },
+    })
+
+    if (!initializedRef.current) {
+      initializedRef.current = true
+      void resolveAndSetTitles(matchChain)
+    }
+
+    return <Breadcrumb items={resolvedItems} {...breadcrumbProps} />
+  },
+})

package/src/components/timeline.spec.tsx

@@ -196,4 +196,113 @@ describe('Timeline', () => {
     const items = timeline.querySelectorAll('shade-timeline-item')
     expect(items.length).toBe(2)
   })
+
+  describe('orientation', () => {
+    it('should not set data-orientation when orientation is not specified (defaults to vertical)', async () => {
+      const el = (
+        <div>
+          <Timeline>
+            <TimelineItem>Event</TimelineItem>
+          </Timeline>
+        </div>
+      )
+      const timeline = el.firstElementChild as JSX.Element
+      timeline.updateComponent()
+      await flushUpdates()
+      expect(timeline.hasAttribute('data-orientation')).toBe(false)
+    })
+
+    it('should not set data-orientation when orientation is "vertical"', async () => {
+      const el = (
+        <div>
+          <Timeline orientation="vertical">
+            <TimelineItem>Event</TimelineItem>
+          </Timeline>
+        </div>
+      )
+      const timeline = el.firstElementChild as JSX.Element
+      timeline.updateComponent()
+      await flushUpdates()
+      expect(timeline.hasAttribute('data-orientation')).toBe(false)
+    })
+
+    it('should set data-orientation="horizontal" when orientation is "horizontal"', async () => {
+      const el = (
+        <div>
+          <Timeline orientation="horizontal">
+            <TimelineItem>Event</TimelineItem>
+          </Timeline>
+        </div>
+      )
+      const timeline = el.firstElementChild as JSX.Element
+      timeline.updateComponent()
+      await flushUpdates()
+      expect(timeline.getAttribute('data-orientation')).toBe('horizontal')
+    })
+
+    it('should render children in horizontal mode', async () => {
+      const el = (
+        <div>
+          <Timeline orientation="horizontal">
+            <TimelineItem>First</TimelineItem>
+            <TimelineItem>Second</TimelineItem>
+            <TimelineItem>Third</TimelineItem>
+          </Timeline>
+        </div>
+      )
+      const timeline = el.firstElementChild as JSX.Element
+      timeline.updateComponent()
+      await flushUpdates()
+      const items = timeline.querySelectorAll('shade-timeline-item')
+      expect(items.length).toBe(3)
+    })
+
+    it('should support horizontal with mode="alternate"', async () => {
+      const el = (
+        <div>
+          <Timeline orientation="horizontal" mode="alternate">
+            <TimelineItem>First</TimelineItem>
+            <TimelineItem>Second</TimelineItem>
+          </Timeline>
+        </div>
+      )
+      const timeline = el.firstElementChild as JSX.Element
+      timeline.updateComponent()
+      await flushUpdates()
+      expect(timeline.getAttribute('data-orientation')).toBe('horizontal')
+      expect(timeline.getAttribute('data-mode')).toBe('alternate')
+    })
+
+    it('should support horizontal with mode="right"', async () => {
+      const el = (
+        <div>
+          <Timeline orientation="horizontal" mode="right">
+            <TimelineItem>First</TimelineItem>
+          </Timeline>
+        </div>
+      )
+      const timeline = el.firstElementChild as JSX.Element
+      timeline.updateComponent()
+      await flushUpdates()
+      expect(timeline.getAttribute('data-orientation')).toBe('horizontal')
+      expect(timeline.getAttribute('data-mode')).toBe('right')
+    })
+
+    it('should add pending item in horizontal mode', async () => {
+      const el = (
+        <div>
+          <Timeline orientation="horizontal" pending="Loading...">
+            <TimelineItem>Step 1</TimelineItem>
+            <TimelineItem>Step 2</TimelineItem>
+          </Timeline>
+        </div>
+      )
+      const timeline = el.firstElementChild as JSX.Element
+      timeline.updateComponent()
+      await flushUpdates()
+      const items = timeline.querySelectorAll('shade-timeline-item')
+      expect(items.length).toBe(3)
+      expect(timeline.getAttribute('data-orientation')).toBe('horizontal')
+    })
+  })
 })

package/src/components/timeline.tsx

@@ -148,6 +148,8 @@ export const TimelineItem = Shade<TimelineItemProps>({
 export type TimelineProps = PartialElement<HTMLElement> & {
   /** Layout mode. 'left' places content on the right, 'right' on the left, 'alternate' switches sides. Defaults to 'left'. */
   mode?: 'left' | 'right' | 'alternate'
+  /** Orientation of the timeline axis. Defaults to 'vertical'. */
+  orientation?: 'vertical' | 'horizontal'
   /** Show a pending indicator on the last item. `true` shows a default "Loading..." text, a string/JSX shows custom content. */
   pending?: boolean | string | JSX.Element
 }
@@ -201,12 +203,103 @@ export const Timeline = Shade<TimelineProps>({
     '&[data-mode="alternate"] > shade-timeline-item:nth-of-type(even) .timeline-dot-column': {
       order: '2',
     },
+
+    '&[data-orientation="horizontal"]': {
+      flexDirection: 'row',
+    },
+
+    '&[data-orientation="horizontal"] > shade-timeline-item': {
+      flexDirection: 'column',
+      minHeight: 'auto',
+      flex: '1',
+    },
+
+    '&[data-orientation="horizontal"] > shade-timeline-item .timeline-label': {
+      flex: 'none',
+      textAlign: 'center',
+      paddingRight: '0',
+      paddingBottom: cssVariableTheme.spacing.xs,
+    },
+
+    '&[data-orientation="horizontal"] > shade-timeline-item .timeline-dot-column': {
+      flexDirection: 'row',
+      width: '100%',
+      paddingTop: '0',
+    },
+
+    '&[data-orientation="horizontal"] > shade-timeline-item .timeline-tail': {
+      height: '2px',
+      width: 'auto',
+      flex: '1',
+      marginTop: '0',
+      marginLeft: cssVariableTheme.spacing.xs,
+    },
+
+    '&[data-orientation="horizontal"] > shade-timeline-item .timeline-tail[data-pending]': {
+      borderLeft: 'none',
+      borderTop: `2px dashed ${cssVariableTheme.divider}`,
+      height: '0',
+      width: 'auto',
+    },
+
+    '&[data-orientation="horizontal"] > shade-timeline-item .timeline-content': {
+      flex: 'none',
+      paddingLeft: '0',
+      paddingTop: cssVariableTheme.spacing.sm,
+      paddingBottom: '0',
+      textAlign: 'center',
+    },
+
+    '&[data-orientation="horizontal"][data-mode="right"] > shade-timeline-item .timeline-label': {
+      order: '3',
+      paddingBottom: '0',
+      paddingLeft: '0',
+      paddingTop: cssVariableTheme.spacing.sm,
+      textAlign: 'center',
+    },
+
+    '&[data-orientation="horizontal"][data-mode="right"] > shade-timeline-item .timeline-content': {
+      order: '1',
+      paddingTop: '0',
+      paddingRight: '0',
+      paddingBottom: cssVariableTheme.spacing.xs,
+      textAlign: 'center',
+    },
+
+    '&[data-orientation="horizontal"][data-mode="right"] > shade-timeline-item .timeline-dot-column': {
+      order: '2',
+    },
+
+    '&[data-orientation="horizontal"][data-mode="alternate"] > shade-timeline-item:nth-of-type(even) .timeline-label': {
+      order: '3',
+      paddingRight: '0',
+      paddingLeft: '0',
+      paddingBottom: '0',
+      paddingTop: cssVariableTheme.spacing.sm,
+      textAlign: 'center',
+    },
+
+    '&[data-orientation="horizontal"][data-mode="alternate"] > shade-timeline-item:nth-of-type(even) .timeline-content':
+      {
+        order: '1',
+        paddingLeft: '0',
+        paddingRight: '0',
+        paddingTop: '0',
+        paddingBottom: cssVariableTheme.spacing.xs,
+        textAlign: 'center',
+      },
+
+    '&[data-orientation="horizontal"][data-mode="alternate"] > shade-timeline-item:nth-of-type(even) .timeline-dot-column':
+      {
+        order: '2',
+      },
   },
   render: ({ props, children, useHostProps }) => {
-    const { mode = 'left', pending, style } = props
+    const { mode = 'left', orientation = 'vertical', pending, style } = props
 
     useHostProps({
       'data-mode': mode,
+      ...(orientation === 'horizontal' ? { 'data-orientation': 'horizontal' as const } : {}),
       ...(style ? { style: style as Record<string, string> } : {}),
     })