@furystack/shades-common-components 12.5.0 → 12.7.0

package/src/components/markdown/markdown-input.tsx

@@ -1,5 +1,8 @@
 import { Shade, createComponent } from '@furystack/shades'
 import { cssVariableTheme } from '../../services/css-variable-theme.js'
+import type { InputValidationResult } from '../inputs/input.js'
+import { FormService } from '../form.js'
+import { resolveValidationState } from './markdown-validation.js'
 
 const DEFAULT_MAX_IMAGE_SIZE = 256 * 1024
 
@@ -20,6 +23,16 @@ export type MarkdownInputProps = {
   labelTitle?: string
   /** Number of visible text rows */
   rows?: number
+  /** Form field name for FormService integration */
+  name?: string
+  /** Whether the field is required */
+  required?: boolean
+  /** Custom validation callback */
+  getValidationResult?: (options: { value: string }) => InputValidationResult
+  /** Optional helper text callback */
+  getHelperText?: (options: { value: string; validationResult?: InputValidationResult }) => JSX.Element | string
+  /** When true, suppresses visual label and helper text rendering while keeping form mechanics */
+  hideChrome?: boolean
 }
 
 /**
@@ -53,6 +66,11 @@ export const MarkdownInput = Shade<MarkdownInputProps>({
       color: cssVariableTheme.palette.primary.main,
     },
 
+    '&[data-invalid] label': {
+      borderColor: cssVariableTheme.palette.error.main,
+      color: cssVariableTheme.palette.error.main,
+    },
+
     '& textarea': {
       border: 'none',
       backgroundColor: 'transparent',
@@ -71,13 +89,51 @@ export const MarkdownInput = Shade<MarkdownInputProps>({
     '&:focus-within textarea': {
       boxShadow: `0px 3px 0px ${cssVariableTheme.palette.primary.main}`,
     },
+
+    '&[data-invalid]:focus-within textarea': {
+      boxShadow: `0px 3px 0px ${cssVariableTheme.palette.error.main}`,
+    },
+
+    '& .helperText': {
+      fontSize: cssVariableTheme.typography.fontSize.xs,
+      marginTop: '6px',
+      opacity: '0.85',
+      lineHeight: '1.4',
+    },
   },
-  render: ({ props, useHostProps, useRef }) => {
+  render: ({ props, injector, useDisposable, useHostProps, useRef }) => {
     const maxSize = props.maxImageSizeBytes ?? DEFAULT_MAX_IMAGE_SIZE
     const textareaRef = useRef<HTMLTextAreaElement>('textarea')
 
+    useDisposable('form-registration', () => {
+      const formService = injector.cachedSingletons.has(FormService) ? injector.getInstance(FormService) : null
+      if (formService) {
+        queueMicrotask(() => {
+          if (textareaRef.current) formService.inputs.add(textareaRef.current as unknown as HTMLInputElement)
+        })
+      }
+      return {
+        [Symbol.dispose]: () => {
+          if (textareaRef.current && formService)
+            formService.inputs.delete(textareaRef.current as unknown as HTMLInputElement)
+        },
+      }
+    })
+
+    const { validationResult, isRequired, isInvalid, helperNode } = resolveValidationState(props)
+
+    if (injector.cachedSingletons.has(FormService) && props.name) {
+      const formService = injector.getInstance(FormService)
+      const fieldResult: InputValidationResult = isRequired
+        ? { isValid: false, message: 'Value is required' }
+        : validationResult || { isValid: true }
+      const validity = textareaRef.current?.validity ?? ({} as ValidityState)
+      formService.setFieldState(props.name as keyof unknown, fieldResult, validity)
+    }
+
     useHostProps({
       'data-disabled': props.disabled ? '' : undefined,
+      'data-invalid': isInvalid ? '' : undefined,
     })
 
     const handleInput = (ev: Event) => {
@@ -126,9 +182,11 @@ export const MarkdownInput = Shade<MarkdownInputProps>({
 
     return (
       <label>
-        {props.labelTitle ? <span>{props.labelTitle}</span> : null}
+        {!props.hideChrome && props.labelTitle ? <span>{props.labelTitle}</span> : null}
         <textarea
           ref={textareaRef}
+          name={props.name}
+          required={props.required}
           value={props.value}
           oninput={handleInput}
           onpaste={handlePaste}
@@ -137,6 +195,7 @@ export const MarkdownInput = Shade<MarkdownInputProps>({
           placeholder={props.placeholder}
           rows={props.rows ?? 10}
         />
+        {!props.hideChrome && helperNode ? <span className="helperText">{helperNode}</span> : null}
       </label>
     )
   },

package/src/components/markdown/markdown-validation.ts

@@ -0,0 +1,33 @@
+import type { InputValidationResult } from '../inputs/input.js'
+
+type ValidationOptions = {
+  value: string
+  required?: boolean
+  getValidationResult?: (options: { value: string }) => InputValidationResult
+  getHelperText?: (options: { value: string; validationResult?: InputValidationResult }) => JSX.Element | string
+}
+
+export type ValidationState = {
+  validationResult: InputValidationResult | undefined
+  isRequired: boolean
+  isInvalid: boolean
+  helperNode: JSX.Element | string
+}
+
+/**
+ * Computes validation state from common markdown field props.
+ * Shared between MarkdownInput and MarkdownEditor to keep the logic in one place.
+ */
+export const resolveValidationState = (options: ValidationOptions): ValidationState => {
+  const validationResult = options.getValidationResult?.({ value: options.value })
+  const isRequired = !!options.required && !options.value
+  const isInvalid = validationResult?.isValid === false || isRequired
+
+  const helperNode =
+    (validationResult?.isValid === false && validationResult?.message) ||
+    (isRequired && 'Value is required') ||
+    options.getHelperText?.({ value: options.value, validationResult }) ||
+    ''
+
+  return { validationResult, isRequired, isInvalid, helperNode }
+}

package/src/components/suggest/index.spec.tsx

@@ -882,4 +882,87 @@ describe('Suggest', () => {
       })
     })
   })
+
+  describe('synchronous suggestions mode', () => {
+    it('should render with string[] suggestions', async () => {
+      await usingAsync(new Injector(), async (injector) => {
+        const rootElement = document.getElementById('root') as HTMLDivElement
+        const onSelectSuggestion = vi.fn()
+
+        initializeShadeRoot({
+          injector,
+          rootElement,
+          jsxElement: (
+            <Suggest
+              defaultPrefix="🔍"
+              suggestions={['Apple', 'Banana', 'Cherry']}
+              onSelectSuggestion={onSelectSuggestion}
+            />
+          ),
+        })
+
+        await advanceTimers(50)
+
+        const suggest = document.querySelector('shade-suggest') as HTMLElement
+        expect(suggest).not.toBeNull()
+      })
+    })
+
+    it('should render input in sync mode', async () => {
+      await usingAsync(new Injector(), async (injector) => {
+        const rootElement = document.getElementById('root') as HTMLDivElement
+        const onSelectSuggestion = vi.fn()
+
+        initializeShadeRoot({
+          injector,
+          rootElement,
+          jsxElement: (
+            <Suggest
+              defaultPrefix="🔍"
+              suggestions={['Apple', 'Banana', 'Cherry']}
+              onSelectSuggestion={onSelectSuggestion}
+            />
+          ),
+        })
+
+        await advanceTimers(50)
+
+        const suggest = document.querySelector('shade-suggest') as HTMLElement
+        const input = suggest?.querySelector('input')
+        expect(input).not.toBeNull()
+      })
+    })
+
+    it('should show filtered suggestions in sync mode', async () => {
+      await usingAsync(new Injector(), async (injector) => {
+        const rootElement = document.getElementById('root') as HTMLDivElement
+        const onSelectSuggestion = vi.fn()
+
+        initializeShadeRoot({
+          injector,
+          rootElement,
+          jsxElement: (
+            <Suggest
+              defaultPrefix="🔍"
+              suggestions={['Apple', 'Apricot', 'Banana']}
+              onSelectSuggestion={onSelectSuggestion}
+            />
+          ),
+        })
+
+        await advanceTimers(50)
+
+        const suggest = document.querySelector('shade-suggest') as HTMLElement
+        const input = suggest?.querySelector('input') as HTMLInputElement
+
+        input.value = 'ap'
+        input.dispatchEvent(new KeyboardEvent('keyup', { key: 'p', bubbles: true }))
+
+        await advanceTimers(300)
+
+        const suggestionItems = suggest?.querySelectorAll('.suggestion-item')
+        expect(suggestionItems?.length).toBe(2)
+      })
+    })
+  })
 })

package/src/components/suggest/index.tsx

@@ -15,7 +15,7 @@ export * from './suggest-manager.js'
 export * from './suggestion-list.js'
 export * from './suggestion-result.js'
 
-export interface SuggestProps<T> {
+type SuggestAsyncProps<T> = {
   defaultPrefix: JSX.Element | string
   getEntries: (term: string) => Promise<T[]>
   getSuggestionEntry: (entry: T) => SuggestionResult
@@ -23,6 +23,20 @@ export interface SuggestProps<T> {
   style?: Partial<CSSStyleDeclaration>
 }
 
+type SuggestSyncProps = {
+  defaultPrefix: JSX.Element | string
+  /** Static list of string suggestions. Filtered client-side by the search term. When the term is empty, all suggestions are shown. */
+  suggestions: string[]
+  onSelectSuggestion: (entry: string) => void
+  style?: Partial<CSSStyleDeclaration>
+}
+
+export type SuggestProps<T> = SuggestAsyncProps<T> | SuggestSyncProps
+
+const isSyncProps = (props: SuggestProps<unknown>): props is SuggestSyncProps => {
+  return 'suggestions' in props
+}
+
 export const Suggest: <T>(props: SuggestProps<T>, children: ChildrenList) => JSX.Element<any> = Shade<
   SuggestProps<any>
 >({
@@ -35,7 +49,24 @@ export const Suggest: <T>(props: SuggestProps<T>, children: ChildrenList) => JSX
     },
   },
   render: ({ props, injector, useDisposable, useRef, useHostProps, useObservable }) => {
-    const manager = useDisposable('manager', () => new SuggestManager(props.getEntries, props.getSuggestionEntry))
+    let getEntries: (term: string) => Promise<unknown[]>
+    let getSuggestionEntry: (entry: unknown) => SuggestionResult
+
+    if (isSyncProps(props)) {
+      const { suggestions } = props
+      getEntries = async (term: string) => {
+        const lower = term.toLowerCase()
+        return suggestions.filter((s) => s.toLowerCase().includes(lower))
+      }
+      getSuggestionEntry = (entry: unknown) => ({
+        element: <>{entry as string}</>,
+        score: 1,
+      })
+    } else {
+      ;({ getEntries, getSuggestionEntry } = props)
+    }
+
+    const manager = useDisposable('manager', () => new SuggestManager(getEntries, getSuggestionEntry))
     const wrapperRef = useRef<HTMLDivElement>('wrapper')
     const loaderRef = useRef<HTMLSpanElement>('loader')
 
@@ -65,7 +96,9 @@ export const Suggest: <T>(props: SuggestProps<T>, children: ChildrenList) => JSX
         })
       }
     })
-    useDisposable('onSelectSuggestion', () => manager.subscribe('onSelectSuggestion', props.onSelectSuggestion))
+    useDisposable('onSelectSuggestion', () =>
+      manager.subscribe('onSelectSuggestion', props.onSelectSuggestion as (entry: unknown) => void),
+    )
     return (
       <div
         ref={wrapperRef}

package/src/components/wizard/index.spec.tsx

@@ -72,13 +72,21 @@ describe('Wizard', () => {
   const renderWizard = async (
     steps: Array<(props: WizardStepProps, children: ChildrenList) => JSX.Element>,
     onFinish?: () => void,
+    options?: { stepLabels?: string[]; showProgress?: boolean },
   ) => {
     const injector = new Injector()
     const root = document.getElementById('root')!
     initializeShadeRoot({
       injector,
       rootElement: root,
-      jsxElement: <Wizard steps={steps} onFinish={onFinish} />,
+      jsxElement: (
+        <Wizard
+          steps={steps}
+          onFinish={onFinish}
+          stepLabels={options?.stepLabels}
+          showProgress={options?.showProgress}
+        />
+      ),
     })
     await flushUpdates()
 
@@ -215,6 +223,115 @@ describe('Wizard', () => {
     })
   })
 
+  describe('step indicator', () => {
+    it('should not render step indicator when stepLabels is not provided', async () => {
+      await usingAsync(await renderWizard([Step1, Step2]), async ({ wizard }) => {
+        const indicator = wizard.querySelector('[data-testid="wizard-step-indicator"]')
+        expect(indicator).toBeNull()
+      })
+    })
+
+    it('should render step indicator when stepLabels is provided', async () => {
+      await usingAsync(
+        await renderWizard([Step1, Step2, Step3], undefined, {
+          stepLabels: ['First', 'Second', 'Third'],
+        }),
+        async ({ wizard }) => {
+          const indicator = wizard.querySelector('[data-testid="wizard-step-indicator"]')
+          expect(indicator).toBeTruthy()
+
+          const circles = indicator?.querySelectorAll('.wizard-step-circle')
+          expect(circles?.length).toBe(3)
+        },
+      )
+    })
+
+    it('should show step labels', async () => {
+      await usingAsync(
+        await renderWizard([Step1, Step2], undefined, {
+          stepLabels: ['Setup', 'Confirm'],
+        }),
+        async ({ wizard }) => {
+          const labels = wizard.querySelectorAll('.wizard-step-label')
+          expect(labels[0]?.textContent).toBe('Setup')
+          expect(labels[1]?.textContent).toBe('Confirm')
+        },
+      )
+    })
+
+    it('should mark the current step as active', async () => {
+      await usingAsync(
+        await renderWizard([Step1, Step2, Step3], undefined, {
+          stepLabels: ['A', 'B', 'C'],
+        }),
+        async ({ wizard }) => {
+          const circles = wizard.querySelectorAll('.wizard-step-circle')
+          expect(circles[0]?.hasAttribute('data-active')).toBe(true)
+          expect(circles[1]?.hasAttribute('data-active')).toBe(false)
+        },
+      )
+    })
+
+    it('should update active step on navigation', async () => {
+      await usingAsync(
+        await renderWizard([Step1, Step2, Step3], undefined, {
+          stepLabels: ['A', 'B', 'C'],
+        }),
+        async ({ wizard, clickNext }) => {
+          await clickNext()
+          const circles = wizard.querySelectorAll('.wizard-step-circle')
+          expect(circles[0]?.hasAttribute('data-completed')).toBe(true)
+          expect(circles[1]?.hasAttribute('data-active')).toBe(true)
+          expect(circles[2]?.hasAttribute('data-active')).toBe(false)
+        },
+      )
+    })
+  })
+
+  describe('progress bar', () => {
+    it('should not render progress bar when showProgress is false', async () => {
+      await usingAsync(await renderWizard([Step1, Step2]), async ({ wizard }) => {
+        const progressBar = wizard.querySelector('[data-testid="wizard-progress-bar"]')
+        expect(progressBar).toBeNull()
+      })
+    })
+
+    it('should render progress bar when showProgress is true', async () => {
+      await usingAsync(
+        await renderWizard([Step1, Step2, Step3], undefined, { showProgress: true }),
+        async ({ wizard }) => {
+          const progressBar = wizard.querySelector('[data-testid="wizard-progress-bar"]')
+          expect(progressBar).toBeTruthy()
+        },
+      )
+    })
+
+    it('should start at 0% on first step', async () => {
+      await usingAsync(
+        await renderWizard([Step1, Step2, Step3], undefined, { showProgress: true }),
+        async ({ wizard }) => {
+          const fill = wizard.querySelector('.wizard-progress-fill') as HTMLElement
+          expect(fill?.style.width).toBe('0%')
+        },
+      )
+    })
+
+    it('should update progress on navigation', async () => {
+      await usingAsync(
+        await renderWizard([Step1, Step2, Step3], undefined, { showProgress: true }),
+        async ({ wizard, clickNext }) => {
+          await clickNext()
+          const fill = wizard.querySelector('.wizard-progress-fill') as HTMLElement
+          expect(fill?.style.width).toBe('50%')
+
+          await clickNext()
+          const fill2 = wizard.querySelector('.wizard-progress-fill') as HTMLElement
+          expect(fill2?.style.width).toBe('100%')
+        },
+      )
+    })
+  })
+
   describe('Paper container', () => {
     it('should render step inside a Paper component', async () => {
       await usingAsync(await renderWizard([Step1]), async ({ wizard }) => {

package/src/components/wizard/index.tsx

@@ -1,5 +1,6 @@
 import type { ChildrenList } from '@furystack/shades'
 import { createComponent, Shade } from '@furystack/shades'
+import { cssVariableTheme } from '../../services/css-variable-theme.js'
 import { Paper } from '../paper.js'
 
 export interface WizardStepProps {
@@ -30,6 +31,14 @@ export interface WizardProps {
    * A callback that will be executed when the wizard is completed
    */
   onFinish?: () => void
+  /**
+   * Optional labels for each step. When provided, a step indicator is shown above the content.
+   */
+  stepLabels?: string[]
+  /**
+   * When true, a progress bar is shown above the content.
+   */
+  showProgress?: boolean
 }
 
 export const Wizard = Shade<WizardProps>({
@@ -42,15 +51,131 @@ export const Wizard = Shade<WizardProps>({
       width: '100%',
       height: '100%',
     },
+    '& .wizard-step-indicator': {
+      display: 'flex',
+      alignItems: 'center',
+      justifyContent: 'center',
+      padding: '16px 24px 8px',
+      gap: '0',
+    },
+    '& .wizard-step-node': {
+      display: 'flex',
+      flexDirection: 'column',
+      alignItems: 'center',
+      gap: '4px',
+      zIndex: '1',
+      minWidth: '32px',
+    },
+    '& .wizard-step-circle': {
+      width: '28px',
+      height: '28px',
+      borderRadius: '50%',
+      display: 'flex',
+      alignItems: 'center',
+      justifyContent: 'center',
+      fontSize: cssVariableTheme.typography.fontSize.xs,
+      fontWeight: cssVariableTheme.typography.fontWeight.semibold,
+      border: `2px solid ${cssVariableTheme.action.subtleBorder}`,
+      background: cssVariableTheme.background.default,
+      color: cssVariableTheme.text.secondary,
+      transition: `all ${cssVariableTheme.transitions.duration.normal} ease`,
+    },
+    '& .wizard-step-circle[data-active]': {
+      borderColor: cssVariableTheme.palette.primary.main,
+      background: cssVariableTheme.palette.primary.main,
+      color: cssVariableTheme.palette.primary.mainContrast,
+    },
+    '& .wizard-step-circle[data-completed]': {
+      borderColor: cssVariableTheme.palette.primary.main,
+      background: cssVariableTheme.palette.primary.main,
+      color: cssVariableTheme.palette.primary.mainContrast,
+      opacity: '0.7',
+    },
+    '& .wizard-step-label': {
+      fontSize: cssVariableTheme.typography.fontSize.xs,
+      color: cssVariableTheme.text.secondary,
+      textAlign: 'center',
+      maxWidth: '80px',
+      overflow: 'hidden',
+      textOverflow: 'ellipsis',
+      whiteSpace: 'nowrap',
+    },
+    '& .wizard-step-label[data-active]': {
+      color: cssVariableTheme.palette.primary.main,
+      fontWeight: cssVariableTheme.typography.fontWeight.semibold,
+    },
+    '& .wizard-step-connector': {
+      flex: '1',
+      height: '2px',
+      background: cssVariableTheme.action.subtleBorder,
+      minWidth: '24px',
+      alignSelf: 'flex-start',
+      marginTop: '14px',
+      transition: `background ${cssVariableTheme.transitions.duration.normal} ease`,
+    },
+    '& .wizard-step-connector[data-completed]': {
+      background: cssVariableTheme.palette.primary.main,
+    },
+    '& .wizard-progress-bar': {
+      height: '4px',
+      background: cssVariableTheme.action.subtleBorder,
+      margin: '12px 24px 4px',
+      borderRadius: '2px',
+      overflow: 'hidden',
+    },
+    '& .wizard-progress-fill': {
+      height: '100%',
+      background: cssVariableTheme.palette.primary.main,
+      borderRadius: '2px',
+      transition: `width ${cssVariableTheme.transitions.duration.normal} ease`,
+    },
   },
   render: ({ props, useState }) => {
     const [currentPage, setCurrentPage] = useState('currentPage', 0)
 
+    if (props.stepLabels && props.stepLabels.length !== props.steps.length) {
+      console.warn(
+        `[Wizard] stepLabels length (${props.stepLabels.length}) does not match steps length (${props.steps.length}).`,
+      )
+    }
+
     const CurrentPage = props.steps[currentPage]
+    const progressPercent = props.steps.length > 1 ? (currentPage / (props.steps.length - 1)) * 100 : 100
 
     return (
       <div className="wizard-container">
         <Paper style={{ maxWidth: '100%', maxHeight: '100%' }} elevation={3} onclick={(ev) => ev.stopPropagation()}>
+          {props.stepLabels && props.stepLabels.length > 0 && (
+            <div className="wizard-step-indicator" data-testid="wizard-step-indicator">
+              {props.steps.map((_, index) => (
+                <>
+                  {index > 0 && (
+                    <div
+                      className="wizard-step-connector"
+                      {...(index <= currentPage ? { 'data-completed': '' } : {})}
+                    />
+                  )}
+                  <div className="wizard-step-node">
+                    <div
+                      className="wizard-step-circle"
+                      {...(index === currentPage ? { 'data-active': '' } : {})}
+                      {...(index < currentPage ? { 'data-completed': '' } : {})}
+                    >
+                      {(index + 1).toString()}
+                    </div>
+                    <span className="wizard-step-label" {...(index === currentPage ? { 'data-active': '' } : {})}>
+                      {props.stepLabels?.[index] ?? ''}
+                    </span>
+                  </div>
+                </>
+              ))}
+            </div>
+          )}
+          {props.showProgress && (
+            <div className="wizard-progress-bar" data-testid="wizard-progress-bar">
+              <div className="wizard-progress-fill" style={{ width: `${progressPercent}%` }} />
+            </div>
+          )}
           <CurrentPage
             currentPage={currentPage}
             maxPages={props.steps.length}