@furystack/shades-common-components 11.0.0 → 12.0.0

package/src/components/timeline.tsx

@@ -0,0 +1,221 @@
+import type { PartialElement } from '@furystack/shades'
+import { Shade, createComponent } from '@furystack/shades'
+import { cssVariableTheme } from '../services/css-variable-theme.js'
+import { paletteMainColors } from '../services/palette-css-vars.js'
+import type { Palette } from '../services/theme-provider-service.js'
+
+/**
+ * Props for a single timeline item.
+ */
+export type TimelineItemProps = PartialElement<HTMLElement> & {
+  /** Palette color for the dot. Defaults to 'primary'. */
+  color?: keyof Palette
+  /** Custom dot content (e.g. an icon). Replaces the default filled circle. */
+  dot?: JSX.Element
+  /** Label displayed on the opposite side from the content (used in alternate or right mode). */
+  label?: string
+}
+
+/**
+ * A single item in a Timeline.
+ * Renders a dot, a connector tail, and the item's content (children).
+ */
+export const TimelineItem = Shade<TimelineItemProps>({
+  shadowDomName: 'shade-timeline-item',
+  css: {
+    display: 'flex',
+    position: 'relative',
+    minHeight: '64px',
+
+    '& .timeline-label': {
+      flex: '1',
+      textAlign: 'right',
+      paddingRight: cssVariableTheme.spacing.md,
+      paddingTop: '2px',
+      fontFamily: cssVariableTheme.typography.fontFamily,
+      fontSize: cssVariableTheme.typography.fontSize.sm,
+      color: cssVariableTheme.text.secondary,
+      boxSizing: 'border-box',
+    },
+
+    '& .timeline-dot-column': {
+      display: 'flex',
+      flexDirection: 'column',
+      alignItems: 'center',
+      flexShrink: '0',
+      width: '24px',
+    },
+
+    '& .timeline-dot': {
+      display: 'flex',
+      alignItems: 'center',
+      justifyContent: 'center',
+      width: '12px',
+      height: '12px',
+      borderRadius: cssVariableTheme.shape.borderRadius.full,
+      backgroundColor: 'var(--timeline-dot-color)',
+      flexShrink: '0',
+      zIndex: '1',
+      marginTop: '5px',
+    },
+
+    '& .timeline-dot[data-custom]': {
+      width: 'auto',
+      height: 'auto',
+      backgroundColor: 'transparent',
+      color: 'var(--timeline-dot-color)',
+      fontSize: '20px',
+      lineHeight: '1',
+    },
+
+    '& .timeline-tail': {
+      flex: '1',
+      width: '2px',
+      backgroundColor: cssVariableTheme.divider,
+      marginTop: cssVariableTheme.spacing.xs,
+    },
+
+    '& .timeline-tail[data-pending]': {
+      borderLeft: `2px dashed ${cssVariableTheme.divider}`,
+      backgroundColor: 'transparent',
+      width: '0',
+    },
+
+    '& .timeline-content': {
+      flex: '1',
+      paddingLeft: cssVariableTheme.spacing.md,
+      paddingBottom: cssVariableTheme.spacing.lg,
+      fontFamily: cssVariableTheme.typography.fontFamily,
+      fontSize: cssVariableTheme.typography.fontSize.sm,
+      color: cssVariableTheme.text.primary,
+      boxSizing: 'border-box',
+    },
+
+    // When placed in a right-mode or alternate-right context, the label goes right and content goes left
+    '&[data-side="right"] .timeline-label': {
+      textAlign: 'left',
+      paddingRight: '0',
+      paddingLeft: cssVariableTheme.spacing.md,
+      order: '3',
+    },
+    '&[data-side="right"] .timeline-content': {
+      textAlign: 'right',
+      paddingLeft: '0',
+      paddingRight: cssVariableTheme.spacing.md,
+      order: '1',
+    },
+    '&[data-side="right"] .timeline-dot-column': {
+      order: '2',
+    },
+
+    // Last item: hide tail
+    '&[data-last] .timeline-tail': {
+      visibility: 'hidden',
+    },
+  },
+  render: ({ props, children, useHostProps }) => {
+    const { color = 'primary', dot, label, style } = props
+
+    const colors = paletteMainColors[color]
+    useHostProps({
+      style: {
+        '--timeline-dot-color': colors.main,
+        ...(style as Record<string, string>),
+      },
+    })
+
+    const isPending = (props as Record<string, unknown>)['data-pending'] !== undefined
+
+    return (
+      <>
+        {label !== undefined ? <div className="timeline-label">{label}</div> : null}
+        <div className="timeline-dot-column">
+          <div className="timeline-dot" {...(dot ? { 'data-custom': '' } : {})}>
+            {dot ?? null}
+          </div>
+          <div className="timeline-tail" {...(isPending ? { 'data-pending': '' } : {})} />
+        </div>
+        <div className="timeline-content">{children}</div>
+      </>
+    )
+  },
+})
+
+/**
+ * Props for the Timeline container.
+ */
+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'
+  /** 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
+}
+
+/**
+ * Timeline displays a list of events in chronological order.
+ * Supports left, right, and alternate layout modes with optional pending state.
+ */
+export const Timeline = Shade<TimelineProps>({
+  shadowDomName: 'shade-timeline',
+  css: {
+    display: 'flex',
+    flexDirection: 'column',
+    padding: `${cssVariableTheme.spacing.md} 0`,
+    margin: '0',
+    listStyle: 'none',
+    fontFamily: cssVariableTheme.typography.fontFamily,
+  },
+  render: ({ props, children, useHostProps }) => {
+    const { mode = 'left', pending, style } = props
+
+    useHostProps({
+      'data-mode': mode,
+      ...(style ? { style: style as Record<string, string> } : {}),
+    })
+
+    const items = (Array.isArray(children) ? children.flat() : children ? [children] : []) as JSX.Element[]
+    const totalItems = pending ? items.length + 1 : items.length
+
+    items.forEach((child, index) => {
+      if (child && typeof child === 'object' && 'setAttribute' in child) {
+        const isLast = index === totalItems - 1
+        if (isLast) {
+          child.setAttribute('data-last', '')
+        } else {
+          child.removeAttribute('data-last')
+        }
+
+        if (mode === 'right') {
+          child.setAttribute('data-side', 'right')
+        } else if (mode === 'alternate') {
+          child.setAttribute('data-side', index % 2 === 0 ? 'left' : 'right')
+        } else {
+          child.removeAttribute('data-side')
+        }
+      }
+    })
+
+    const pendingItem = pending ? (
+      <TimelineItem
+        color="info"
+        dot={<span style={{ fontSize: cssVariableTheme.typography.fontSize.md }}>⏳</span>}
+        data-last=""
+        data-pending=""
+        {...(mode === 'right'
+          ? { 'data-side': 'right' }
+          : mode === 'alternate'
+            ? { 'data-side': items.length % 2 === 0 ? 'left' : 'right' }
+            : {})}
+      >
+        {pending === true ? 'Loading...' : pending}
+      </TimelineItem>
+    ) : null
+
+    return (
+      <>
+        {items}
+        {pendingItem}
+      </>
+    )
+  },
+})

package/src/components/tooltip.spec.tsx

@@ -0,0 +1,223 @@
+import { createComponent, flushUpdates } from '@furystack/shades'
+import { describe, expect, it } from 'vitest'
+import { Tooltip } from './tooltip.js'
+
+describe('Tooltip', () => {
+  it('should be defined', () => {
+    expect(Tooltip).toBeDefined()
+    expect(typeof Tooltip).toBe('function')
+  })
+
+  it('should create a tooltip element with default props', () => {
+    const el = (<Tooltip title="Hello" />) as unknown as HTMLElement
+    expect(el).toBeDefined()
+    expect(el.tagName?.toLowerCase()).toBe('shade-tooltip')
+  })
+
+  it('should render title content inside the popup', async () => {
+    const el = (
+      <div>
+        <Tooltip title="My Tooltip">
+          <span>Trigger</span>
+        </Tooltip>
+      </div>
+    )
+    const tooltip = el.firstElementChild as JSX.Element
+    tooltip.updateComponent()
+    await flushUpdates()
+    const popup = tooltip.querySelector('.tooltip-popup') as HTMLElement
+    expect(popup.textContent).toContain('My Tooltip')
+  })
+
+  it('should set data-placement when placement prop is provided', async () => {
+    const el = (
+      <div>
+        <Tooltip title="Tip" placement="bottom">
+          <span>Trigger</span>
+        </Tooltip>
+      </div>
+    )
+    const tooltip = el.firstElementChild as JSX.Element
+    tooltip.updateComponent()
+    await flushUpdates()
+    expect(tooltip.getAttribute('data-placement')).toBe('bottom')
+  })
+
+  it('should render a tooltip-popup with role="tooltip"', async () => {
+    const el = (
+      <div>
+        <Tooltip title="Tip">
+          <span>Hover me</span>
+        </Tooltip>
+      </div>
+    )
+    const tooltip = el.firstElementChild as JSX.Element
+    tooltip.updateComponent()
+    await flushUpdates()
+    const popup = tooltip.querySelector('.tooltip-popup') as HTMLElement
+    expect(popup).toBeDefined()
+    expect(popup).not.toBeNull()
+    expect(popup.getAttribute('role')).toBe('tooltip')
+  })
+
+  it('should render the title content inside the popup', async () => {
+    const el = (
+      <div>
+        <Tooltip title="Hello World">
+          <span>Trigger</span>
+        </Tooltip>
+      </div>
+    )
+    const tooltip = el.firstElementChild as JSX.Element
+    tooltip.updateComponent()
+    await flushUpdates()
+    const popup = tooltip.querySelector('.tooltip-popup') as HTMLElement
+    expect(popup.textContent).toContain('Hello World')
+  })
+
+  it('should render an arrow element', async () => {
+    const el = (
+      <div>
+        <Tooltip title="Tip">
+          <span>Trigger</span>
+        </Tooltip>
+      </div>
+    )
+    const tooltip = el.firstElementChild as JSX.Element
+    tooltip.updateComponent()
+    await flushUpdates()
+    const arrow = tooltip.querySelector('.tooltip-arrow')
+    expect(arrow).not.toBeNull()
+  })
+
+  it('should set data-placement attribute when placement is provided', async () => {
+    const el = (
+      <div>
+        <Tooltip title="Tip" placement="bottom">
+          <span>Trigger</span>
+        </Tooltip>
+      </div>
+    )
+    const tooltip = el.firstElementChild as JSX.Element
+    tooltip.updateComponent()
+    await flushUpdates()
+    expect(tooltip.getAttribute('data-placement')).toBe('bottom')
+  })
+
+  it('should not set data-placement attribute when placement is not provided', async () => {
+    const el = (
+      <div>
+        <Tooltip title="Tip">
+          <span>Trigger</span>
+        </Tooltip>
+      </div>
+    )
+    const tooltip = el.firstElementChild as JSX.Element
+    tooltip.updateComponent()
+    await flushUpdates()
+    expect(tooltip.hasAttribute('data-placement')).toBe(false)
+  })
+
+  it('should set data-placement for each valid placement', async () => {
+    const placements = ['top', 'bottom', 'left', 'right'] as const
+    for (const placement of placements) {
+      const el = (
+        <div>
+          <Tooltip title="Tip" placement={placement}>
+            <span>Trigger</span>
+          </Tooltip>
+        </div>
+      )
+      const tooltip = el.firstElementChild as JSX.Element
+      tooltip.updateComponent()
+      await flushUpdates()
+      expect(tooltip.getAttribute('data-placement')).toBe(placement)
+    }
+  })
+
+  it('should set data-disabled attribute when disabled', async () => {
+    const el = (
+      <div>
+        <Tooltip title="Tip" disabled>
+          <span>Trigger</span>
+        </Tooltip>
+      </div>
+    )
+    const tooltip = el.firstElementChild as JSX.Element
+    tooltip.updateComponent()
+    await flushUpdates()
+    expect(tooltip.hasAttribute('data-disabled')).toBe(true)
+  })
+
+  it('should not set data-disabled attribute when not disabled', async () => {
+    const el = (
+      <div>
+        <Tooltip title="Tip">
+          <span>Trigger</span>
+        </Tooltip>
+      </div>
+    )
+    const tooltip = el.firstElementChild as JSX.Element
+    tooltip.updateComponent()
+    await flushUpdates()
+    expect(tooltip.hasAttribute('data-disabled')).toBe(false)
+  })
+
+  it('should set --tooltip-delay CSS variable when delay is provided', async () => {
+    const el = (
+      <div>
+        <Tooltip title="Tip" delay={300}>
+          <span>Trigger</span>
+        </Tooltip>
+      </div>
+    )
+    const tooltip = el.firstElementChild as JSX.Element
+    tooltip.updateComponent()
+    await flushUpdates()
+    expect(tooltip.style.getPropertyValue('--tooltip-delay')).toBe('300ms')
+  })
+
+  it('should not set --tooltip-delay CSS variable when delay is 0', async () => {
+    const el = (
+      <div>
+        <Tooltip title="Tip" delay={0}>
+          <span>Trigger</span>
+        </Tooltip>
+      </div>
+    )
+    const tooltip = el.firstElementChild as JSX.Element
+    tooltip.updateComponent()
+    await flushUpdates()
+    expect(tooltip.style.getPropertyValue('--tooltip-delay')).toBe('')
+  })
+
+  it('should not set --tooltip-delay CSS variable when delay is not provided', async () => {
+    const el = (
+      <div>
+        <Tooltip title="Tip">
+          <span>Trigger</span>
+        </Tooltip>
+      </div>
+    )
+    const tooltip = el.firstElementChild as JSX.Element
+    tooltip.updateComponent()
+    await flushUpdates()
+    expect(tooltip.style.getPropertyValue('--tooltip-delay')).toBe('')
+  })
+
+  it('should render children as trigger content', async () => {
+    const el = (
+      <div>
+        <Tooltip title="Tip">
+          <button>Click me</button>
+        </Tooltip>
+      </div>
+    )
+    const tooltip = el.firstElementChild as JSX.Element
+    tooltip.updateComponent()
+    await flushUpdates()
+    const button = tooltip.querySelector('button')
+    expect(button).not.toBeNull()
+    expect(button?.textContent).toBe('Click me')
+  })
+})

package/src/components/tooltip.tsx

@@ -0,0 +1,155 @@
+import { Shade, createComponent } from '@furystack/shades'
+import { buildTransition, cssVariableTheme } from '../services/css-variable-theme.js'
+
+export type TooltipPlacement = 'top' | 'bottom' | 'left' | 'right'
+
+export type TooltipProps = {
+  /**
+   * The tooltip content to display
+   */
+  title: JSX.Element | string
+  /**
+   * Placement of the tooltip relative to its trigger element
+   */
+  placement?: TooltipPlacement
+  /**
+   * Delay in milliseconds before the tooltip appears
+   */
+  delay?: number
+  /**
+   * Whether the tooltip is disabled
+   */
+  disabled?: boolean
+}
+
+export const Tooltip = Shade<TooltipProps>({
+  shadowDomName: 'shade-tooltip',
+  css: {
+    position: 'relative',
+    display: 'inline-flex',
+
+    '& .tooltip-popup': {
+      position: 'absolute',
+      zIndex: cssVariableTheme.zIndex.tooltip,
+      pointerEvents: 'none',
+      opacity: '0',
+      visibility: 'hidden',
+      transition: buildTransition(
+        ['opacity', cssVariableTheme.transitions.duration.fast, cssVariableTheme.transitions.easing.default],
+        ['visibility', cssVariableTheme.transitions.duration.fast, cssVariableTheme.transitions.easing.default],
+      ),
+      transitionDelay: '0s',
+      padding: `${cssVariableTheme.spacing.xs} ${cssVariableTheme.spacing.sm}`,
+      borderRadius: cssVariableTheme.shape.borderRadius.sm,
+      backgroundColor: cssVariableTheme.text.primary,
+      color: cssVariableTheme.background.default,
+      fontSize: cssVariableTheme.typography.fontSize.xs,
+      fontFamily: cssVariableTheme.typography.fontFamily,
+      fontWeight: cssVariableTheme.typography.fontWeight.medium,
+      lineHeight: cssVariableTheme.typography.lineHeight.tight,
+      whiteSpace: 'nowrap',
+      maxWidth: '300px',
+      boxShadow: cssVariableTheme.shadows.md,
+    },
+
+    '&:hover .tooltip-popup, &:focus-within .tooltip-popup': {
+      opacity: '1',
+      visibility: 'visible',
+      transitionDelay: 'var(--tooltip-delay, 0s)',
+    },
+
+    '&[data-disabled] .tooltip-popup': {
+      display: 'none',
+    },
+
+    // Placement: top (default)
+    '&:not([data-placement]) .tooltip-popup, &[data-placement="top"] .tooltip-popup': {
+      bottom: '100%',
+      left: '50%',
+      transform: 'translateX(-50%)',
+      marginBottom: cssVariableTheme.spacing.xs,
+    },
+
+    // Placement: bottom
+    '&[data-placement="bottom"] .tooltip-popup': {
+      top: '100%',
+      left: '50%',
+      transform: 'translateX(-50%)',
+      marginTop: cssVariableTheme.spacing.xs,
+    },
+
+    // Placement: left
+    '&[data-placement="left"] .tooltip-popup': {
+      right: '100%',
+      top: '50%',
+      transform: 'translateY(-50%)',
+      marginRight: cssVariableTheme.spacing.xs,
+    },
+
+    // Placement: right
+    '&[data-placement="right"] .tooltip-popup': {
+      left: '100%',
+      top: '50%',
+      transform: 'translateY(-50%)',
+      marginLeft: cssVariableTheme.spacing.xs,
+    },
+
+    // Arrow base styles
+    '& .tooltip-arrow': {
+      position: 'absolute',
+      width: '8px',
+      height: '8px',
+      backgroundColor: 'inherit',
+      transform: 'rotate(45deg)',
+    },
+
+    // Arrow: top placement (arrow at bottom of popup)
+    '&:not([data-placement]) .tooltip-arrow, &[data-placement="top"] .tooltip-arrow': {
+      bottom: '-4px',
+      left: '50%',
+      marginLeft: '-4px',
+    },
+
+    // Arrow: bottom placement (arrow at top of popup)
+    '&[data-placement="bottom"] .tooltip-arrow': {
+      top: '-4px',
+      left: '50%',
+      marginLeft: '-4px',
+    },
+
+    // Arrow: left placement (arrow at right of popup)
+    '&[data-placement="left"] .tooltip-arrow': {
+      right: '-4px',
+      top: '50%',
+      marginTop: '-4px',
+    },
+
+    // Arrow: right placement (arrow at left of popup)
+    '&[data-placement="right"] .tooltip-arrow': {
+      left: '-4px',
+      top: '50%',
+      marginTop: '-4px',
+    },
+  },
+  render: ({ props, children, useHostProps }) => {
+    const { placement, delay, disabled } = props
+
+    useHostProps({
+      'data-placement': placement || undefined,
+      'data-disabled': disabled ? '' : undefined,
+      style: {
+        ...(delay !== undefined && delay > 0 ? { '--tooltip-delay': `${delay}ms` } : {}),
+      },
+    })
+
+    return (
+      <>
+        {children}
+        <div className="tooltip-popup" role="tooltip">
+          <span className="tooltip-arrow" />
+          {props.title}
+        </div>
+      </>
+    )
+  },
+})

package/src/components/tree/index.ts

@@ -0,0 +1,2 @@
+export * from './tree-item.js'
+export * from './tree.js'