@furystack/shades-common-components 11.0.0 → 12.0.0

package/src/components/badge.tsx

@@ -0,0 +1,104 @@
+import type { PartialElement } from '@furystack/shades'
+import { Shade, createComponent } from '@furystack/shades'
+import { buildTransition, cssVariableTheme } from '../services/css-variable-theme.js'
+import { paletteMainColors } from '../services/palette-css-vars.js'
+import type { Palette } from '../services/theme-provider-service.js'
+
+export type BadgeProps = PartialElement<HTMLElement> & {
+  /** The count to display in the badge */
+  count?: number
+  /** If true, renders a small dot instead of a count */
+  dot?: boolean
+  /** Palette color for the badge */
+  color?: keyof Palette
+  /** Maximum count to display. Counts above this show `{max}+` */
+  max?: number
+  /** If true, shows the badge when count is zero */
+  showZero?: boolean
+  /** Controls badge visibility. Defaults to true */
+  visible?: boolean
+}
+
+const defaultColors = {
+  main: cssVariableTheme.palette.error.main,
+  mainContrast: cssVariableTheme.palette.error.mainContrast,
+}
+
+export const Badge = Shade<BadgeProps>({
+  shadowDomName: 'shade-badge',
+  css: {
+    display: 'inline-flex',
+    position: 'relative',
+    verticalAlign: 'middle',
+    flexShrink: '0',
+
+    '& .badge-indicator': {
+      display: 'flex',
+      alignItems: 'center',
+      justifyContent: 'center',
+      position: 'absolute',
+      top: '0',
+      right: '0',
+      transform: 'translate(50%, -50%)',
+      transformOrigin: '100% 0%',
+      fontFamily: cssVariableTheme.typography.fontFamily,
+      fontSize: cssVariableTheme.typography.fontSize.xs,
+      fontWeight: cssVariableTheme.typography.fontWeight.medium,
+      lineHeight: '1',
+      minWidth: '20px',
+      height: '20px',
+      padding: `0 ${cssVariableTheme.spacing.xs}`,
+      borderRadius: cssVariableTheme.shape.borderRadius.lg,
+      background: 'var(--badge-color-main)',
+      color: 'var(--badge-color-contrast)',
+      boxSizing: 'border-box',
+      whiteSpace: 'nowrap',
+      zIndex: '1',
+      transition: buildTransition(
+        ['transform', cssVariableTheme.transitions.duration.fast, cssVariableTheme.transitions.easing.default],
+        ['opacity', cssVariableTheme.transitions.duration.fast, cssVariableTheme.transitions.easing.default],
+      ),
+    },
+
+    '& .badge-indicator[data-dot]': {
+      minWidth: '8px',
+      width: '8px',
+      height: '8px',
+      padding: '0',
+      borderRadius: cssVariableTheme.shape.borderRadius.full,
+    },
+
+    '& .badge-indicator[data-hidden]': {
+      transform: 'translate(50%, -50%) scale(0)',
+      opacity: '0',
+    },
+  },
+  render: ({ props, children, useHostProps }) => {
+    const { count, dot, color, max = 99, showZero, visible = true, style } = props
+
+    const colors = color ? paletteMainColors[color] : defaultColors
+    useHostProps({
+      style: {
+        '--badge-color-main': colors.main,
+        '--badge-color-contrast': colors.mainContrast,
+        ...(style as Record<string, string>),
+      },
+    })
+
+    const shouldHide = !visible || (!dot && !showZero && (count === undefined || count === 0))
+    const displayValue = dot ? '' : count !== undefined && count > max ? `${max}+` : (count?.toString() ?? '')
+
+    return (
+      <>
+        {children}
+        <span
+          className="badge-indicator"
+          {...(dot ? { 'data-dot': '' } : {})}
+          {...(shouldHide ? { 'data-hidden': '' } : {})}
+        >
+          {displayValue}
+        </span>
+      </>
+    )
+  },
+})

package/src/components/breadcrumb.spec.tsx

@@ -0,0 +1,396 @@
+import { Injector } from '@furystack/inject'
+import { createComponent, flushUpdates, initializeShadeRoot, LocationService } from '@furystack/shades'
+import type { ExtractRouteParams, NestedRoute } from '@furystack/shades'
+import { sleepAsync, usingAsync } from '@furystack/utils'
+import { afterEach, beforeEach, describe, expect, expectTypeOf, it, vi } from 'vitest'
+import type { BreadcrumbItem, TypedBreadcrumbProps } from './breadcrumb.js'
+import { Breadcrumb, createBreadcrumb } from './breadcrumb.js'
+
+// Minimal route type for type-level tests
+type TestRoute = Pick<NestedRoute<unknown>, 'component'>
+
+describe('Breadcrumb', () => {
+  beforeEach(() => {
+    document.body.innerHTML = '<div id="root"></div>'
+  })
+  afterEach(() => {
+    document.body.innerHTML = ''
+  })
+
+  describe('Runtime behavior', () => {
+    it('Should render basic breadcrumb trail with static routes', async () => {
+      await usingAsync(new Injector(), async (injector) => {
+        const rootElement = document.getElementById('root') as HTMLDivElement
+
+        initializeShadeRoot({
+          injector,
+          rootElement,
+          jsxElement: (
+            <Breadcrumb
+              items={[
+                { path: '/home', label: 'Home' },
+                { path: '/users', label: 'Users' },
+              ]}
+            />
+          ),
+        })
+
+        await flushUpdates()
+
+        const component = rootElement.querySelector('nav[is="shade-breadcrumb"]')
+        expect(component).toBeTruthy()
+        expect(component?.textContent).toContain('Home')
+        expect(component?.textContent).toContain('Users')
+      })
+    })
+
+    it('Should compile dynamic route parameters correctly', async () => {
+      await usingAsync(new Injector(), async (injector) => {
+        const rootElement = document.getElementById('root') as HTMLDivElement
+
+        initializeShadeRoot({
+          injector,
+          rootElement,
+          jsxElement: (
+            <Breadcrumb
+              items={[
+                { path: '/users', label: 'Users' },
+                { path: '/users/:id', label: 'User Details', params: { id: '123' } },
+              ]}
+              lastItemClickable={true}
+            />
+          ),
+        })
+
+        await flushUpdates()
+
+        const link = rootElement.querySelector('a[href="/users/123"]')
+        expect(link).toBeTruthy()
+        expect(link?.textContent).toBe('User Details')
+      })
+    })
+
+    it('Should highlight active breadcrumb based on current URL', async () => {
+      await usingAsync(new Injector(), async (injector) => {
+        const rootElement = document.getElementById('root') as HTMLDivElement
+        const locationService = injector.getInstance(LocationService)
+
+        history.pushState('', '', '/users')
+        locationService.updateState()
+
+        initializeShadeRoot({
+          injector,
+          rootElement,
+          jsxElement: (
+            <Breadcrumb
+              items={[
+                { path: '/home', label: 'Home' },
+                { path: '/users', label: 'Users' },
+              ]}
+            />
+          ),
+        })
+
+        await flushUpdates()
+
+        // The active item is the last non-clickable span with data-active attribute
+        // (boolean values are rendered as empty string by the framework's setProp)
+        const activeItem = rootElement.querySelector('[data-non-clickable="true"]')
+        expect(activeItem).toBeTruthy()
+        expect(activeItem?.textContent).toBe('Users')
+        expect(activeItem?.hasAttribute('data-active')).toBe(true)
+      })
+    })
+
+    it('Should render custom separator as string', async () => {
+      await usingAsync(new Injector(), async (injector) => {
+        const rootElement = document.getElementById('root') as HTMLDivElement
+
+        initializeShadeRoot({
+          injector,
+          rootElement,
+          jsxElement: (
+            <Breadcrumb
+              items={[
+                { path: '/home', label: 'Home' },
+                { path: '/users', label: 'Users' },
+              ]}
+              separator=" > "
+            />
+          ),
+        })
+
+        await flushUpdates()
+
+        const separator = rootElement.querySelector('[data-separator="true"]')
+        expect(separator?.textContent).toBe(' > ')
+      })
+    })
+
+    it('Should render optional home item', async () => {
+      await usingAsync(new Injector(), async (injector) => {
+        const rootElement = document.getElementById('root') as HTMLDivElement
+
+        initializeShadeRoot({
+          injector,
+          rootElement,
+          jsxElement: (
+            <Breadcrumb homeItem={{ path: '/', label: 'Home' }} items={[{ path: '/users', label: 'Users' }]} />
+          ),
+        })
+
+        await flushUpdates()
+
+        const breadcrumb = rootElement.querySelector('nav')
+        expect(breadcrumb?.textContent).toContain('Home')
+        expect(breadcrumb?.textContent).toContain('Users')
+      })
+    })
+
+    it('Should make last item non-clickable when lastItemClickable is false', async () => {
+      await usingAsync(new Injector(), async (injector) => {
+        const rootElement = document.getElementById('root') as HTMLDivElement
+
+        initializeShadeRoot({
+          injector,
+          rootElement,
+          jsxElement: (
+            <Breadcrumb
+              items={[
+                { path: '/home', label: 'Home' },
+                { path: '/users', label: 'Users' },
+              ]}
+              lastItemClickable={false}
+            />
+          ),
+        })
+
+        await flushUpdates()
+
+        const links = rootElement.querySelectorAll('a')
+        const spans = rootElement.querySelectorAll('[data-non-clickable="true"]')
+
+        expect(links.length).toBe(1) // Only first item
+        expect(spans.length).toBe(1) // Last item
+      })
+    })
+
+    it('Should make last item clickable when lastItemClickable is true', async () => {
+      await usingAsync(new Injector(), async (injector) => {
+        const rootElement = document.getElementById('root') as HTMLDivElement
+
+        initializeShadeRoot({
+          injector,
+          rootElement,
+          jsxElement: (
+            <Breadcrumb
+              items={[
+                { path: '/home', label: 'Home' },
+                { path: '/users', label: 'Users' },
+              ]}
+              lastItemClickable={true}
+            />
+          ),
+        })
+
+        await flushUpdates()
+
+        const links = rootElement.querySelectorAll('a')
+        expect(links.length).toBe(2) // Both items
+      })
+    })
+
+    it('Should trigger SPA navigation on click', async () => {
+      await usingAsync(new Injector(), async (injector) => {
+        const rootElement = document.getElementById('root') as HTMLDivElement
+        const onRouteChange = vi.fn()
+
+        injector.getInstance(LocationService).onLocationPathChanged.subscribe(onRouteChange)
+
+        initializeShadeRoot({
+          injector,
+          rootElement,
+          jsxElement: (
+            <Breadcrumb
+              items={[
+                { path: '/home', label: 'Home' },
+                { path: '/users', label: 'Users' },
+              ]}
+            />
+          ),
+        })
+
+        await flushUpdates()
+
+        expect(onRouteChange).not.toBeCalled()
+
+        const firstLink = rootElement.querySelector('a') as HTMLAnchorElement
+        firstLink?.click()
+
+        expect(onRouteChange).toBeCalledTimes(1)
+      })
+    })
+
+    it('Should apply custom className and style props', async () => {
+      await usingAsync(new Injector(), async (injector) => {
+        const rootElement = document.getElementById('root') as HTMLDivElement
+
+        initializeShadeRoot({
+          injector,
+          rootElement,
+          jsxElement: (
+            <Breadcrumb
+              items={[{ path: '/home', label: 'Home' }]}
+              className="custom-breadcrumb"
+              style={{ padding: '16px' }}
+            />
+          ),
+        })
+
+        await sleepAsync(50)
+
+        const breadcrumb = rootElement.querySelector('nav[is="shade-breadcrumb"]')
+        expect(breadcrumb?.classList.contains('custom-breadcrumb')).toBe(true)
+        expect((breadcrumb as HTMLElement)?.style.padding).toBe('16px')
+      })
+    })
+
+    it('Should handle empty items array gracefully', async () => {
+      await usingAsync(new Injector(), async (injector) => {
+        const rootElement = document.getElementById('root') as HTMLDivElement
+
+        initializeShadeRoot({
+          injector,
+          rootElement,
+          jsxElement: <Breadcrumb items={[]} />,
+        })
+
+        const nav = rootElement.querySelector('nav')
+        expect(nav).toBeTruthy()
+      })
+    })
+
+    it('Should render home item when items array is empty', async () => {
+      await usingAsync(new Injector(), async (injector) => {
+        const rootElement = document.getElementById('root') as HTMLDivElement
+
+        initializeShadeRoot({
+          injector,
+          rootElement,
+          jsxElement: <Breadcrumb homeItem={{ path: '/', label: 'Home' }} items={[]} />,
+        })
+        await flushUpdates()
+
+        const breadcrumb = rootElement.querySelector('nav')
+        expect(breadcrumb?.textContent).toContain('Home')
+      })
+    })
+
+    it('Should compile multiple parameters correctly', async () => {
+      await usingAsync(new Injector(), async (injector) => {
+        const rootElement = document.getElementById('root') as HTMLDivElement
+
+        initializeShadeRoot({
+          injector,
+          rootElement,
+          jsxElement: (
+            <Breadcrumb
+              items={[{ path: '/users/:userId/posts/:postId', label: 'Post', params: { userId: '1', postId: '99' } }]}
+              lastItemClickable={true}
+            />
+          ),
+        })
+
+        await flushUpdates()
+
+        const link = rootElement.querySelector('a[href="/users/1/posts/99"]')
+        expect(link).toBeTruthy()
+        expect(link?.textContent).toBe('Post')
+      })
+    })
+  })
+
+  describe('Type safety', () => {
+    describe('BreadcrumbItem', () => {
+      it('Should require params when path has parameters', () => {
+        type ItemWithParams = BreadcrumbItem<'/users/:id'>
+        expectTypeOf<ItemWithParams>().toMatchTypeOf<{ params: { id: string } }>()
+      })
+
+      it('Should make params optional when path has no parameters', () => {
+        type ItemWithoutParams = BreadcrumbItem<'/users'>
+        expectTypeOf<ItemWithoutParams>().toMatchTypeOf<{ params?: Record<string, string> }>()
+      })
+
+      it('Should extract multiple params from path', () => {
+        type ItemWithMultipleParams = BreadcrumbItem<'/users/:userId/posts/:postId'>
+        expectTypeOf<ItemWithMultipleParams>().toMatchTypeOf<{ params: { userId: string; postId: string } }>()
+      })
+    })
+
+    describe('ExtractRouteParams utility', () => {
+      it('Should return Record<string, never> for paths without params', () => {
+        expectTypeOf<ExtractRouteParams<'/buttons'>>().toEqualTypeOf<Record<string, never>>()
+      })
+
+      it('Should extract a single param', () => {
+        expectTypeOf<ExtractRouteParams<'/users/:id'>>().toEqualTypeOf<{ id: string }>()
+      })
+
+      it('Should extract multiple params', () => {
+        expectTypeOf<ExtractRouteParams<'/users/:userId/posts/:postId'>>().toEqualTypeOf<{
+          userId: string
+          postId: string
+        }>()
+      })
+    })
+
+    describe('createBreadcrumb', () => {
+      it('Should constrain paths to valid route tree paths', () => {
+        type Routes = {
+          '/': TestRoute & {
+            children: {
+              '/buttons': TestRoute
+              '/users': TestRoute
+            }
+          }
+        }
+
+        const AppBreadcrumb = createBreadcrumb<Routes>()
+        expectTypeOf(AppBreadcrumb).parameter(0).toHaveProperty('items')
+      })
+
+      it('Should enforce required params for dynamic routes', () => {
+        type Routes = {
+          '/': TestRoute & {
+            children: {
+              '/users/:id': TestRoute
+            }
+          }
+        }
+
+        createBreadcrumb<Routes>()
+        type Props = TypedBreadcrumbProps<Routes>
+
+        // Verify the type has the items property
+        expectTypeOf<Props>().toHaveProperty('items')
+      })
+
+      it('Should require combined params from nested routes', () => {
+        type Routes = {
+          '/users/:userId': TestRoute & {
+            children: {
+              '/posts/:postId': TestRoute
+            }
+          }
+        }
+
+        createBreadcrumb<Routes>()
+        type Props = TypedBreadcrumbProps<Routes>
+
+        // Verify the type has the items property
+        expectTypeOf<Props>().toHaveProperty('items')
+      })
+    })
+  })
+})

package/src/components/breadcrumb.tsx

@@ -0,0 +1,188 @@
+import type { ExtractRouteParams, ExtractRoutePaths, NestedRoute, PartialElement } from '@furystack/shades'
+import { compileRoute, createComponent, LocationService, NestedRouteLink, Shade } from '@furystack/shades'
+import { cssVariableTheme } from '../services/css-variable-theme.js'
+
+/**
+ * Individual breadcrumb item configuration.
+ * When the path contains parameters (e.g. `:id`), the `params` prop becomes required.
+ * @typeParam TPath - A specific route path string
+ */
+export type BreadcrumbItem<TPath extends string = string> = {
+  path: TPath
+  label: string | JSX.Element
+  render?: (item: BreadcrumbItem<TPath>, isActive: boolean) => JSX.Element
+} & (string extends keyof ExtractRouteParams<TPath>
+  ? { params?: Record<string, string> }
+  : { params: ExtractRouteParams<TPath> })
+
+/**
+ * Props for the Breadcrumb component.
+ */
+export type BreadcrumbProps = {
+  items: BreadcrumbItem[]
+  separator?: string | JSX.Element
+  homeItem?: BreadcrumbItem
+  lastItemClickable?: boolean
+} & PartialElement<HTMLElement>
+
+/**
+ * Type-safe props constrained to a specific route tree.
+ * @typeParam TRoutes - The route tree type (use `typeof yourRoutes`)
+ */
+export type TypedBreadcrumbProps<TRoutes extends Record<string, NestedRoute<unknown>>> = {
+  items: Array<BreadcrumbItem<ExtractRoutePaths<TRoutes>>>
+  separator?: string | JSX.Element
+  homeItem?: BreadcrumbItem<ExtractRoutePaths<TRoutes>>
+  lastItemClickable?: boolean
+} & PartialElement<HTMLElement>
+
+/**
+ * A breadcrumb navigation component that works with NestedRouter to provide
+ * navigation through route hierarchies.
+ *
+ * Supports:
+ * - Dynamic route parameters (e.g. `/users/:id`)
+ * - Custom labels and rendering
+ * - Configurable separators
+ * - Active item detection
+ * - Optional home/root link
+ *
+ * Route parameters are automatically inferred from the path pattern:
+ * - `path="/buttons"` — `params` is optional
+ * - `path="/users/:id"` — `params: { id: string }` is required
+ *
+ * For additional URL validation against a route tree, use {@link createBreadcrumb}.
+ *
+ * @example
+ * ```typescript
+ * <Breadcrumb
+ *   homeItem={{ path: '/', label: 'Home' }}
+ *   items={[
+ *     { path: '/users', label: 'Users' },
+ *     { path: '/users/:id', label: 'User Details', params: { id: '123' } },
+ *   ]}
+ *   separator=" > "
+ * />
+ * ```
+ */
+export const Breadcrumb = Shade<BreadcrumbProps>({
+  shadowDomName: 'shade-breadcrumb',
+  elementBase: HTMLElement,
+  elementBaseName: 'nav',
+  css: {
+    display: 'flex',
+    alignItems: 'center',
+    gap: cssVariableTheme.spacing.sm,
+    padding: `${cssVariableTheme.spacing.sm} 0`,
+    fontSize: '0.9em',
+    color: cssVariableTheme.text.secondary,
+
+    '& a': {
+      color: 'inherit',
+      textDecoration: 'none',
+      transition: `opacity ${cssVariableTheme.transitions.duration.normal} ${cssVariableTheme.transitions.easing.easeInOut}`,
+      opacity: '0.8',
+    },
+
+    '& a:hover': {
+      opacity: '1',
+    },
+
+    '& [data-active="true"]': {
+      opacity: '0.6',
+      cursor: 'default',
+    },
+
+    '& [data-separator="true"]': {
+      opacity: '0.5',
+    },
+
+    '& [data-non-clickable="true"]': {
+      cursor: 'default',
+    },
+  },
+  render: ({ props, injector, useObservable }) => {
+    const { items, separator = '/', homeItem, lastItemClickable = false } = props
+
+    const locationService = injector.getInstance(LocationService)
+    const [currentPath] = useObservable('currentPath', locationService.onLocationPathChanged)
+
+    const allItems = homeItem ? [homeItem, ...items] : items
+
+    const renderItem = (item: BreadcrumbItem, _index: number, isLast: boolean) => {
+      const compiledPath = (item as BreadcrumbItem & { params?: Record<string, string> }).params
+        ? compileRoute(item.path, (item as BreadcrumbItem & { params: Record<string, string> }).params)
+        : item.path
+
+      const isActive = currentPath === compiledPath
+
+      if (item.render) {
+        return item.render(item, isActive)
+      }
+
+      if (isLast && !lastItemClickable) {
+        return (
+          <span data-active={isActive} data-non-clickable="true">
+            {item.label}
+          </span>
+        )
+      }
+
+      return (
+        <NestedRouteLink href={compiledPath} data-active={isActive}>
+          {item.label}
+        </NestedRouteLink>
+      )
+    }
+
+    const renderSeparator = () => {
+      if (typeof separator === 'string') {
+        return <span data-separator="true">{separator}</span>
+      }
+      return separator
+    }
+
+    return (
+      <>
+        {allItems.map((item, index) => (
+          <>
+            {renderItem(item, index, index === allItems.length - 1)}
+            {index < allItems.length - 1 && renderSeparator()}
+          </>
+        ))}
+      </>
+    )
+  },
+})
+
+/**
+ * Creates a type-safe wrapper around Breadcrumb constrained to a specific route tree.
+ * The returned component has the same runtime behavior but narrows paths to only accept
+ * valid route paths, and requires `params` when the route has parameters.
+ *
+ * @typeParam TRoutes - The route tree type (use `typeof yourRoutes`)
+ * @returns A narrowed Breadcrumb component
+ *
+ * @example
+ * ```typescript
+ * const AppBreadcrumb = createBreadcrumb<typeof appRoutes>()
+ *
+ * // Type-safe: only valid paths accepted
+ * <AppBreadcrumb
+ *   items={[{ path: '/buttons', label: 'Buttons' }]}
+ * />
+ *
+ * // TypeScript error: invalid path
+ * <AppBreadcrumb items={[{ path: '/nonexistent', label: 'Error' }]} />
+ *
+ * // Params required for parameterized routes
+ * <AppBreadcrumb
+ *   items={[{ path: '/users/:id', label: 'User', params: { id: '123' } }]}
+ * />
+ * ```
+ */
+export const createBreadcrumb = <TRoutes extends Record<string, NestedRoute<unknown>>>() => {
+  return Breadcrumb as typeof Breadcrumb & {
+    (props: TypedBreadcrumbProps<TRoutes>): JSX.Element
+  }
+}