@duro-app/ui 0.24.0 → 0.25.0

package/src/components/Combobox/useComboboxRoot.ts

@@ -0,0 +1,235 @@
+import {useState, useCallback, useMemo, useRef, useId, useEffect} from 'react'
+import {useControllableValue} from '../../hooks/useControllableValue'
+import type {ComboboxContextValue} from './ComboboxContext'
+
+interface UseComboboxRootOptions {
+  defaultValue?: string
+  value?: string
+  onValueChange?: (value: string | null) => void
+  inputValue?: string
+  onInputChange?: (value: string) => void
+  initialLabels?: Record<string, string>
+}
+
+export function useComboboxRoot({
+  defaultValue,
+  value: controlledValue,
+  onValueChange,
+  inputValue: controlledInputValue,
+  onInputChange,
+  initialLabels,
+}: UseComboboxRootOptions) {
+  const [value, setValue] = useControllableValue<string | null>(
+    controlledValue,
+    defaultValue ?? null,
+    onValueChange,
+  )
+  const [internalInputValue, setInternalInputValue] = useState('')
+  const inputValue = controlledInputValue !== undefined ? controlledInputValue : internalInputValue
+  const setInputValue = useCallback(
+    (v: string) => {
+      if (controlledInputValue === undefined) setInternalInputValue(v)
+      onInputChange?.(v)
+    },
+    [controlledInputValue, onInputChange],
+  )
+
+  const [open, setOpen] = useState(false)
+  const [labels, setLabels] = useState<Record<string, string>>(initialLabels ?? {})
+  const [highlightedId, setHighlightedId] = useState<string | null>(null)
+  const listboxId = useId()
+  const rootRef = useRef<HTMLDivElement>(null)
+  const inputRef = useRef<HTMLInputElement | null>(null)
+  const itemsRef = useRef(new Map<string, {value: string; element: HTMLElement}>())
+  const orderRef = useRef<string[]>([])
+
+  const close = useCallback(() => {
+    setOpen(false)
+    setHighlightedId(null)
+  }, [])
+
+  const openPopup = useCallback(() => {
+    setOpen(true)
+    // Highlight the selected item or first visible item
+    const items = itemsRef.current
+    const order = orderRef.current
+    let found: string | null = null
+    for (const id of order) {
+      const item = items.get(id)
+      if (item && item.value === value) {
+        found = id
+        break
+      }
+    }
+    setHighlightedId(found ?? (order.length > 0 ? order[0] : null))
+  }, [value])
+
+  const selectValue = useCallback(
+    (itemValue: string) => {
+      setValue(itemValue)
+      // Set input to show the selected label
+      const label = labels[itemValue] ?? itemValue
+      setInputValue(label)
+      close()
+      inputRef.current?.focus()
+    },
+    [setValue, labels, setInputValue, close],
+  )
+
+  const registerLabel = useCallback((v: string, label: string) => {
+    setLabels((prev) => {
+      if (prev[v] === label) return prev
+      return {...prev, [v]: label}
+    })
+  }, [])
+
+  const registerItem = useCallback((id: string, itemValue: string, element: HTMLElement) => {
+    itemsRef.current.set(id, {value: itemValue, element})
+    const map = itemsRef.current
+    const ids = [...map.keys()]
+    ids.sort((a, b) => {
+      const elA = map.get(a)?.element
+      const elB = map.get(b)?.element
+      if (!elA || !elB) return 0
+      return elA.compareDocumentPosition(elB) & Node.DOCUMENT_POSITION_FOLLOWING ? -1 : 1
+    })
+    orderRef.current = ids
+    return () => {
+      itemsRef.current.delete(id)
+      orderRef.current = orderRef.current.filter((i) => i !== id)
+    }
+  }, [])
+
+  // Get visible items (those matching the filter)
+  const getVisibleOrder = useCallback(() => {
+    const query = inputValue.toLowerCase()
+    if (!query) return orderRef.current
+    return orderRef.current.filter((id) => {
+      const item = itemsRef.current.get(id)
+      if (!item) return false
+      const label = labels[item.value] ?? item.value
+      return label.toLowerCase().includes(query)
+    })
+  }, [inputValue, labels])
+
+  // Keyboard navigation
+  useEffect(() => {
+    const root = rootRef.current
+    if (!root || !open) return
+
+    function handleKeyDown(e: KeyboardEvent) {
+      const visibleOrder = getVisibleOrder()
+      if (visibleOrder.length === 0 && e.key !== 'Escape' && e.key !== 'Tab') return
+
+      switch (e.key) {
+        case 'ArrowDown': {
+          e.preventDefault()
+          if (!open) {
+            setOpen(true)
+            return
+          }
+          setHighlightedId((prev) => {
+            const idx = prev ? visibleOrder.indexOf(prev) : -1
+            return visibleOrder[(idx + 1) % visibleOrder.length] ?? null
+          })
+          break
+        }
+        case 'ArrowUp': {
+          e.preventDefault()
+          setHighlightedId((prev) => {
+            const idx = prev ? visibleOrder.indexOf(prev) : 0
+            return visibleOrder[(idx - 1 + visibleOrder.length) % visibleOrder.length] ?? null
+          })
+          break
+        }
+        case 'Home': {
+          e.preventDefault()
+          setHighlightedId(visibleOrder[0] ?? null)
+          break
+        }
+        case 'End': {
+          e.preventDefault()
+          setHighlightedId(visibleOrder[visibleOrder.length - 1] ?? null)
+          break
+        }
+        case 'Enter': {
+          e.preventDefault()
+          setHighlightedId((prev) => {
+            if (prev) {
+              const item = itemsRef.current.get(prev)
+              if (item) selectValue(item.value)
+            } else if (!inputValue.trim()) {
+              // Empty input + Enter = clear selection (reset to "All")
+              selectValue('')
+            }
+            return prev
+          })
+          break
+        }
+        case 'Escape': {
+          e.preventDefault()
+          close()
+          inputRef.current?.focus()
+          break
+        }
+        case 'Tab': {
+          close()
+          break
+        }
+      }
+    }
+
+    root.addEventListener('keydown', handleKeyDown)
+    return () => root.removeEventListener('keydown', handleKeyDown)
+  }, [open, close, selectValue, getVisibleOrder])
+
+  // Scroll highlighted item into view
+  useEffect(() => {
+    if (!highlightedId) return
+    const item = itemsRef.current.get(highlightedId)
+    item?.element.scrollIntoView({block: 'nearest'})
+  }, [highlightedId])
+
+  // Sync input value with selected label when value changes externally
+  useEffect(() => {
+    if (value && labels[value] && !open) {
+      setInputValue(labels[value])
+    }
+  }, [value, labels, open, setInputValue])
+
+  const ctx: ComboboxContextValue = useMemo(
+    () => ({
+      open,
+      openPopup,
+      close,
+      value,
+      setValue: selectValue,
+      inputValue,
+      setInputValue,
+      labels,
+      registerLabel,
+      listboxId,
+      highlightedId,
+      setHighlightedId,
+      registerItem,
+      inputRef,
+    }),
+    [
+      open,
+      openPopup,
+      close,
+      value,
+      selectValue,
+      inputValue,
+      setInputValue,
+      labels,
+      registerLabel,
+      listboxId,
+      highlightedId,
+      setHighlightedId,
+      registerItem,
+    ],
+  )
+
+  return {ctx, rootRef}
+}

package/src/components/Field/Field.stories.tsx

@@ -63,6 +63,7 @@ export const WithError: Story = {
 
 const stackStyles = css.create({
   stack: {display: 'flex', flexDirection: 'column', gap: 16, maxWidth: 400},
+  stackWide: {display: 'flex', flexDirection: 'column', gap: 16, maxWidth: 600},
 })
 
 export const FormExample: Story = {
@@ -96,3 +97,62 @@ export const FormExample: Story = {
     await expect(alert).toHaveTextContent('Passwords do not match.')
   },
 }
+
+export const WithNecessityIcon: Story = {
+  name: 'With necessity indicator (standalone)',
+  render: () => (
+    <html.div style={stackStyles.stack}>
+      <Field.Root required>
+        <Field.Label>Email</Field.Label>
+        <Input placeholder="you@example.com" />
+        <Field.Description>Required field with no Form context — indicator needs Form.</Field.Description>
+      </Field.Root>
+    </html.div>
+  ),
+  play: async ({canvas}) => {
+    // Without Form context, no indicator shows (necessityIndicator comes from Form)
+    const label = canvas.getByText('Email')
+    await expect(label).toBeInTheDocument()
+  },
+}
+
+export const LabelSide: Story = {
+  name: 'Label position — side (standalone)',
+  render: () => (
+    <html.div style={stackStyles.stackWide}>
+      <Field.Root labelPosition="side">
+        <Field.Label>Username</Field.Label>
+        <Input placeholder="Enter username" />
+        <Field.Description>3-32 characters, letters and numbers only.</Field.Description>
+      </Field.Root>
+
+      <Field.Root labelPosition="side" invalid>
+        <Field.Label>Email</Field.Label>
+        <Input variant="error" placeholder="Enter email" />
+        <Field.Error>Please enter a valid email address.</Field.Error>
+      </Field.Root>
+    </html.div>
+  ),
+  play: async ({canvas}) => {
+    await expect(canvas.getByPlaceholderText('Enter username')).toBeInTheDocument()
+    await expect(canvas.getByPlaceholderText('Enter email')).toBeInTheDocument()
+    await expect(canvas.getByRole('alert')).toHaveTextContent('Please enter a valid email address.')
+  },
+}
+
+export const Disabled: Story = {
+  name: 'Disabled field (standalone)',
+  render: () => (
+    <html.div style={stackStyles.stack}>
+      <Field.Root disabled>
+        <Field.Label>Username</Field.Label>
+        <Input placeholder="Enter username" />
+        <Field.Description>This field is disabled.</Field.Description>
+      </Field.Root>
+    </html.div>
+  ),
+  play: async ({canvas}) => {
+    const input = canvas.getByPlaceholderText('Enter username')
+    await expect(input).toBeDisabled()
+  },
+}

package/src/components/Field/Field.tsx

@@ -1,21 +1,25 @@
-import {type ReactNode, useId, useMemo} from 'react'
+import {type ReactNode, Children, isValidElement, useId, useMemo} from 'react'
 import {html} from 'react-strict-dom'
 import {useFormContext as useRHFFormContext, useController} from 'react-hook-form'
 import {FieldContext, useFieldContext} from './FieldContext'
 import {useFormContext} from '../Form/FormContext'
+import type {LabelPosition, NecessityIndicator} from '../Form/FormContext'
 import {styles} from './styles.css'
 
 // --- Root ---
 interface RootProps {
   name?: string
   invalid?: boolean
+  required?: boolean
+  disabled?: boolean
+  labelPosition?: LabelPosition
   children: ReactNode
 }
 
 function Root({name, ...props}: RootProps) {
-  const insideForm = useFormContext()
-  if (name && insideForm) {
-    return <ControlledRoot name={name} {...props} />
+  const formCtx = useFormContext()
+  if (name && formCtx) {
+    return <ControlledRoot name={name} formCtx={formCtx} {...props} />
   }
   return <StaticRoot {...props} />
 }
@@ -23,11 +27,19 @@ function Root({name, ...props}: RootProps) {
 // Always calls useController — no conditional hooks
 function ControlledRoot({
   name,
+  formCtx,
   invalid: invalidProp = false,
+  required,
+  disabled,
+  labelPosition,
   children,
 }: {
   name: string
+  formCtx: NonNullable<ReturnType<typeof useFormContext>>
   invalid?: boolean
+  required?: boolean
+  disabled?: boolean
+  labelPosition?: LabelPosition
   children: ReactNode
 }) {
   const id = useId()
@@ -35,12 +47,20 @@ function ControlledRoot({
   const {field, fieldState} = useController({control, name})
   const invalid = invalidProp || !!fieldState.error
 
+  const effectiveDisabled = disabled ?? formCtx.disabled
+  const effectiveLabelPosition = labelPosition ?? formCtx.labelPosition
+  const effectiveNecessityIndicator = formCtx.necessityIndicator
+
   const ctx = useMemo(
     () => ({
       controlId: `${id}-control`,
       descriptionId: `${id}-description`,
       errorId: `${id}-error`,
       invalid,
+      required,
+      disabled: effectiveDisabled,
+      labelPosition: effectiveLabelPosition,
+      necessityIndicator: effectiveNecessityIndicator,
       field: {
         value: field.value,
         onChange: field.onChange,
@@ -53,6 +73,10 @@ function ControlledRoot({
     [
       id,
       invalid,
+      required,
+      effectiveDisabled,
+      effectiveLabelPosition,
+      effectiveNecessityIndicator,
       field.value,
       field.onChange,
       field.onBlur,
@@ -64,13 +88,25 @@ function ControlledRoot({
 
   return (
     <FieldContext.Provider value={ctx}>
-      <html.div style={styles.root}>{children}</html.div>
+      <FieldLayout labelPosition={effectiveLabelPosition}>{children}</FieldLayout>
     </FieldContext.Provider>
   )
 }
 
 // Current behavior, no RHF dependency
-function StaticRoot({invalid = false, children}: {invalid?: boolean; children: ReactNode}) {
+function StaticRoot({
+  invalid = false,
+  required,
+  disabled,
+  labelPosition = 'top',
+  children,
+}: {
+  invalid?: boolean
+  required?: boolean
+  disabled?: boolean
+  labelPosition?: LabelPosition
+  children: ReactNode
+}) {
   const id = useId()
   const ctx = useMemo(
     () => ({
@@ -78,17 +114,53 @@ function StaticRoot({invalid = false, children}: {invalid?: boolean; children: R
       descriptionId: `${id}-description`,
       errorId: `${id}-error`,
       invalid,
+      required,
+      disabled,
+      labelPosition,
     }),
-    [id, invalid],
+    [id, invalid, required, disabled, labelPosition],
   )
 
   return (
     <FieldContext.Provider value={ctx}>
-      <html.div style={styles.root}>{children}</html.div>
+      <FieldLayout labelPosition={labelPosition}>{children}</FieldLayout>
     </FieldContext.Provider>
   )
 }
 
+// --- FieldLayout ---
+// When labelPosition is 'side', separates Label from other children
+// and wraps the non-label children in a content column.
+function FieldLayout({
+  labelPosition,
+  children,
+}: {
+  labelPosition: LabelPosition
+  children: ReactNode
+}) {
+  if (labelPosition !== 'side') {
+    return <html.div style={styles.root}>{children}</html.div>
+  }
+
+  let labelNode: ReactNode = null
+  const rest: ReactNode[] = []
+
+  Children.forEach(children, (child) => {
+    if (isValidElement(child) && child.type === Label && !labelNode) {
+      labelNode = child
+    } else {
+      rest.push(child)
+    }
+  })
+
+  return (
+    <html.div style={styles.rootSide}>
+      {labelNode}
+      <html.div style={styles.fieldContent}>{rest}</html.div>
+    </html.div>
+  )
+}
+
 // --- Label ---
 interface LabelProps {
   children: ReactNode
@@ -96,9 +168,25 @@ interface LabelProps {
 
 function Label({children}: LabelProps) {
   const ctx = useFieldContext()
+  const isSide = ctx?.labelPosition === 'side'
+  const indicator = ctx?.necessityIndicator
+
   return (
-    <html.label for={ctx?.controlId} style={styles.label}>
+    <html.label
+      for={ctx?.controlId}
+      style={[styles.label, isSide && styles.labelSide]}
+    >
       {children}
+      {indicator === 'icon' && ctx?.required && (
+        <html.span style={styles.necessityIcon} aria-hidden={true}>
+          {' *'}
+        </html.span>
+      )}
+      {indicator === 'label' && (
+        <html.span style={styles.necessityLabel}>
+          {ctx?.required ? ' (required)' : ' (optional)'}
+        </html.span>
+      )}
     </html.label>
   )
 }

package/src/components/Field/FieldContext.ts

@@ -1,10 +1,15 @@
 import {createContext, useContext} from 'react'
+import type {LabelPosition, NecessityIndicator} from '../Form/FormContext'
 
 interface FieldContextValue {
   controlId: string
   descriptionId: string
   errorId: string
   invalid: boolean
+  required?: boolean
+  disabled?: boolean
+  labelPosition?: LabelPosition
+  necessityIndicator?: NecessityIndicator
   field?: {
     value: unknown
     onChange: (...event: unknown[]) => void

package/src/components/Field/styles.css.ts

@@ -9,11 +9,22 @@ export const styles = css.create({
     flexDirection: 'column',
     gap: spacing.xs,
   },
+  rootSide: {
+    display: 'flex',
+    flexDirection: 'row',
+    alignItems: 'flex-start',
+    gap: spacing.md,
+  },
   label: {
     fontSize: typography.fontSizeSm,
     fontWeight: typography.fontWeightMedium,
     color: colors.text,
   },
+  labelSide: {
+    minWidth: 120,
+    paddingTop: spacing.sm,
+    flexShrink: 0,
+  },
   description: {
     fontSize: typography.fontSizeXs,
     color: colors.textMuted,
@@ -22,4 +33,19 @@ export const styles = css.create({
     fontSize: typography.fontSizeXs,
     color: colors.error,
   },
+  fieldContent: {
+    display: 'flex',
+    flexDirection: 'column',
+    gap: spacing.xs,
+    flex: 1,
+    minWidth: 0,
+  },
+  necessityIcon: {
+    color: colors.error,
+  },
+  necessityLabel: {
+    color: colors.textMuted,
+    fontWeight: typography.fontWeightNormal,
+    fontSize: typography.fontSizeXs,
+  },
 })