@proyecto-viviana/solidaria-components 0.2.5 → 0.2.9

package/src/ContextualHelpTrigger.tsx

@@ -0,0 +1,183 @@
+/**
+ * ContextualHelpTrigger headless component
+ *
+ * A button trigger that opens contextual help in a popover or dialog.
+ * Uses existing overlay infrastructure.
+ */
+
+import { type JSX, createSignal, splitProps, Show, onCleanup, createEffect, createUniqueId } from 'solid-js'
+
+// ============================================
+// TYPES
+// ============================================
+
+export interface ContextualHelpTriggerProps extends Omit<JSX.ButtonHTMLAttributes<HTMLButtonElement>, 'class' | 'children'> {
+  /** Whether the trigger is currently unavailable (shows different styling). */
+  isUnavailable?: boolean
+  /**
+   * Two children: [trigger element, help content].
+   * The trigger renders as a button, the content opens in a popover.
+   */
+  children?: [JSX.Element, JSX.Element]
+  /** CSS class name. */
+  class?: string
+  /** Whether the trigger is disabled. */
+  isDisabled?: boolean
+}
+
+export interface ContextualHelpTriggerRenderProps {
+  isOpen: boolean
+  isUnavailable: boolean
+  isDisabled: boolean
+}
+
+// ============================================
+// COMPONENT
+// ============================================
+
+/**
+ * A trigger that opens contextual help content.
+ *
+ * @example
+ * ```tsx
+ * <ContextualHelpTrigger>
+ *   {[
+ *     <span>What is this?</span>,
+ *     <div>Help content goes here...</div>
+ *   ]}
+ * </ContextualHelpTrigger>
+ * ```
+ */
+export function ContextualHelpTrigger(props: ContextualHelpTriggerProps): JSX.Element {
+  const [local, triggerProps] = splitProps(props, ['isUnavailable', 'children', 'class', 'isDisabled'])
+  const [isOpen, setIsOpen] = createSignal(false)
+  const triggerId = createUniqueId()
+  const contentId = createUniqueId()
+  let triggerRef: HTMLButtonElement | undefined
+  let contentRef: HTMLDivElement | undefined
+
+  const isUnavailable = () => local.isUnavailable ?? false
+  const isDisabled = () => local.isDisabled ?? false
+
+  const toggle = () => {
+    if (!isDisabled()) {
+      setIsOpen(!isOpen())
+    }
+  }
+
+  const close = () => setIsOpen(false)
+
+  const callHandler = <E extends Event>(
+    handler: JSX.EventHandlerUnion<HTMLButtonElement, E> | undefined,
+    event: E
+  ) => {
+    if (!handler) return
+    if (Array.isArray(handler)) {
+      handler[1].call(handler[0], event)
+      return
+    }
+    if (typeof handler === 'function') {
+      (handler as (evt: E) => void)(event)
+      return
+    }
+    if (typeof handler === 'object' && 'handleEvent' in handler && typeof handler.handleEvent === 'function') {
+      (handler.handleEvent as (evt: E) => void)(event)
+    }
+  }
+
+  const handleTriggerClick = (e: MouseEvent) => {
+    callHandler(triggerProps.onClick, e)
+    if (e.defaultPrevented) return
+    toggle()
+  }
+
+  const handleTriggerKeyDown = (e: KeyboardEvent) => {
+    callHandler(triggerProps.onKeyDown, e)
+    if (e.defaultPrevented) return
+    if (e.key === 'Escape' && isOpen()) {
+      e.preventDefault()
+      e.stopPropagation()
+      close()
+      triggerRef?.focus()
+    }
+  }
+
+  // Close on outside click
+  const handleDocumentClick = (e: MouseEvent) => {
+    if (
+      isOpen() &&
+      triggerRef &&
+      contentRef &&
+      !triggerRef.contains(e.target as Node) &&
+      !contentRef.contains(e.target as Node)
+    ) {
+      close()
+    }
+  }
+
+  createEffect(() => {
+    if (!isOpen()) return
+    document.addEventListener('mousedown', handleDocumentClick)
+    onCleanup(() => {
+      document.removeEventListener('mousedown', handleDocumentClick)
+    })
+  })
+
+  // Focus trap: return focus to trigger on close
+  createEffect(() => {
+    if (!isOpen()) return
+    // Focus the content on open
+    contentRef?.focus()
+  })
+
+  const children = () => local.children ?? [null, null] as [JSX.Element, JSX.Element]
+  const trigger = () => children()[0]
+  const content = () => children()[1]
+
+  return (
+    <div
+      class={`solidaria-ContextualHelpTrigger ${local.class ?? ''}`}
+      style={{ position: 'relative', display: 'inline-block' }}
+    >
+      <button
+        {...triggerProps}
+        type="button"
+        id={triggerId}
+        ref={triggerRef}
+        aria-haspopup="dialog"
+        aria-expanded={isOpen()}
+        aria-controls={isOpen() ? contentId : undefined}
+        data-unavailable={isUnavailable() || undefined}
+        data-disabled={isDisabled() || undefined}
+        disabled={isDisabled()}
+        onClick={handleTriggerClick}
+        onKeyDown={handleTriggerKeyDown}
+        class="solidaria-ContextualHelpTrigger-trigger"
+      >
+        {trigger()}
+      </button>
+
+      <Show when={isOpen()}>
+        <div
+          id={contentId}
+          ref={contentRef}
+          role="dialog"
+          aria-labelledby={triggerId}
+          tabIndex={-1}
+          class="solidaria-ContextualHelpTrigger-content"
+          style={{ position: 'absolute', 'z-index': '50' }}
+          onKeyDown={(e) => {
+            if (e.key === 'Escape') {
+              e.preventDefault()
+              e.stopPropagation()
+              close()
+              triggerRef?.focus()
+            }
+          }}
+        >
+          {content()}
+        </div>
+      </Show>
+    </div>
+  )
+}

package/src/DateField.tsx

@@ -111,9 +111,20 @@ export interface DateSegmentProps extends SlotProps {
 // CONTEXT
 // ============================================
 
-export const DateFieldContext = createContext<DateFieldState<DateValue> | null>(null);
+export interface DateFieldContextValue {
+  state: DateFieldState<DateValue>;
+  aria: {
+    labelProps: Record<string, unknown>;
+    inputProps: Record<string, unknown>;
+    descriptionProps: Record<string, unknown>;
+    errorMessageProps: Record<string, unknown>;
+  };
+}
+
+export const DateFieldContext = createContext<DateFieldContextValue | null>(null);
+export const DateFieldStateContext = createContext<DateFieldState<DateValue> | null>(null);
 
-export function useDateFieldContext(): DateFieldState<DateValue> {
+export function useDateFieldContext(): DateFieldContextValue {
   const context = useContext(DateFieldContext);
   if (!context) {
     throw new Error('DateField components must be used within a DateField');
@@ -189,7 +200,15 @@ function DateFieldInner<T extends DateValue = CalendarDate>(
   const state = createDateFieldState(stateProps);
 
   // Create date field ARIA props
-  const fieldAria = createDateField(rest, state as unknown as DateFieldState<DateValue>, fieldRef);
+  const fieldAria = createDateField(
+    () => ({
+      ...(rest as Record<string, unknown>),
+      description: stateProps.description,
+      errorMessage: stateProps.errorMessage,
+    }),
+    state as unknown as DateFieldState<DateValue>,
+    fieldRef
+  );
 
   // Render props values
   const renderValues = createMemo<DateFieldRenderProps>(() => ({
@@ -210,20 +229,32 @@ function DateFieldInner<T extends DateValue = CalendarDate>(
   );
 
   return (
-    <DateFieldContext.Provider value={state as unknown as DateFieldState<DateValue>}>
-      <div
-        ref={setFieldRef}
-        {...fieldAria.fieldProps}
-        class={renderProps.class()}
-        style={renderProps.style()}
-        data-disabled={dataAttr(state.isDisabled())}
-        data-readonly={dataAttr(state.isReadOnly())}
-        data-required={dataAttr(state.isRequired())}
-        data-invalid={dataAttr(state.isInvalid())}
+    <DateFieldStateContext.Provider value={state as unknown as DateFieldState<DateValue>}>
+      <DateFieldContext.Provider
+        value={{
+          state: state as unknown as DateFieldState<DateValue>,
+          aria: {
+            labelProps: fieldAria.labelProps,
+            inputProps: fieldAria.inputProps,
+            descriptionProps: fieldAria.descriptionProps,
+            errorMessageProps: fieldAria.errorMessageProps,
+          },
+        }}
       >
-        {props.children as JSX.Element}
-      </div>
-    </DateFieldContext.Provider>
+        <div
+          ref={setFieldRef}
+          {...fieldAria.fieldProps}
+          class={renderProps.class()}
+          style={renderProps.style()}
+          data-disabled={dataAttr(state.isDisabled())}
+          data-readonly={dataAttr(state.isReadOnly())}
+          data-required={dataAttr(state.isRequired())}
+          data-invalid={dataAttr(state.isInvalid())}
+        >
+          {props.children as JSX.Element}
+        </div>
+      </DateFieldContext.Provider>
+    </DateFieldStateContext.Provider>
   );
 }
 
@@ -235,7 +266,8 @@ function DateFieldInner<T extends DateValue = CalendarDate>(
  * The input area containing date segments.
  */
 export function DateInput(props: DateInputProps): JSX.Element {
-  const state = useDateFieldContext();
+  const context = useDateFieldContext();
+  const { state, aria } = context;
   const [isFocused, setIsFocused] = createSignal(false);
 
   // Render props values
@@ -256,7 +288,7 @@ export function DateInput(props: DateInputProps): JSX.Element {
 
   return (
     <div
-      role="presentation"
+      {...aria.inputProps}
       class={renderProps.class()}
       style={renderProps.style()}
       data-disabled={dataAttr(state.isDisabled())}
@@ -279,7 +311,7 @@ export function DateInput(props: DateInputProps): JSX.Element {
  * A segment of a date field (year, month, day, etc.).
  */
 export function DateSegment(props: DateSegmentProps): JSX.Element {
-  const state = useDateFieldContext();
+  const { state } = useDateFieldContext();
   const [segmentRef, setSegmentRef] = createSignal<HTMLDivElement | null>(null);
 
   // Create segment ARIA props
@@ -333,5 +365,47 @@ export function DateSegment(props: DateSegmentProps): JSX.Element {
   );
 }
 
+export interface DateFieldLabelProps {
+  children?: JSX.Element;
+  class?: string;
+}
+
+export function DateFieldLabel(props: DateFieldLabelProps): JSX.Element {
+  const { aria } = useDateFieldContext();
+  return (
+    <span {...aria.labelProps} class={props.class}>
+      {props.children}
+    </span>
+  );
+}
+
+export interface DateFieldDescriptionProps {
+  children?: JSX.Element;
+  class?: string;
+}
+
+export function DateFieldDescription(props: DateFieldDescriptionProps): JSX.Element {
+  const { aria } = useDateFieldContext();
+  return (
+    <p {...aria.descriptionProps} class={props.class}>
+      {props.children}
+    </p>
+  );
+}
+
+export interface DateFieldErrorMessageProps {
+  children?: JSX.Element;
+  class?: string;
+}
+
+export function DateFieldErrorMessage(props: DateFieldErrorMessageProps): JSX.Element {
+  const { aria } = useDateFieldContext();
+  return (
+    <p {...aria.errorMessageProps} class={props.class}>
+      {props.children}
+    </p>
+  );
+}
+
 // Re-export types
 export type { DateFieldState, DateSegmentType };