@proyecto-viviana/solidaria-components 0.2.9 → 0.3.0

package/src/StepList.tsx

@@ -0,0 +1,272 @@
+/**
+ * StepList component for solidaria-components
+ *
+ * A pre-wired headless step list component that combines state + aria hooks.
+ * Renders an ordered list of steps with completion tracking.
+ */
+
+import { type JSX, createContext, createMemo, splitProps, useContext, For } from "solid-js";
+import {
+  createStepListState,
+  type StepListState,
+  type StepListStateProps,
+  type Key,
+} from "@proyecto-viviana/solid-stately";
+import { createStepList, type AriaStepListProps } from "@proyecto-viviana/solidaria";
+import {
+  type ClassNameOrFunction,
+  type StyleOrFunction,
+  useRenderProps,
+  filterDOMProps,
+} from "./utils";
+
+export interface StepListItemRenderProps {
+  /** Whether this step is currently selected. */
+  isSelected: boolean;
+  /** Whether this step is completed. */
+  isCompleted: boolean;
+  /** Whether this step is disabled. */
+  isDisabled: boolean;
+  /** Whether this step can be selected. */
+  isSelectable: boolean;
+  /** The 1-based step number. */
+  stepNumber: number;
+  /** Accessible text describing the step state. */
+  stepStateText: string;
+}
+
+export interface StepListRenderProps {
+  /** Whether the step list is disabled. */
+  isDisabled: boolean;
+}
+
+export interface StepListProps<T extends { key: Key; label: string }> extends AriaStepListProps {
+  /** The step items. */
+  items: T[];
+  /** The currently selected step key (controlled). */
+  selectedKey?: Key;
+  /** The default selected step key (uncontrolled). */
+  defaultSelectedKey?: Key;
+  /** Called when the selected step changes. */
+  onSelectionChange?: (key: Key) => void;
+  /** The last completed step key (controlled). */
+  lastCompletedStep?: Key;
+  /** The default last completed step key (uncontrolled). */
+  defaultLastCompletedStep?: Key;
+  /** Called when last completed step changes. */
+  onLastCompletedStepChange?: (key: Key | null) => void;
+  /** Whether all steps are disabled. */
+  isDisabled?: boolean;
+  /** Whether all steps are read-only. */
+  isReadOnly?: boolean;
+  /** Keys of individually disabled steps. */
+  disabledKeys?: Iterable<Key>;
+  /** Render function for each step item. */
+  children: (item: T, state: StepListItemRenderProps) => JSX.Element;
+  /** The CSS className for the element. */
+  class?: ClassNameOrFunction<StepListRenderProps>;
+  /** The inline style for the element. */
+  style?: StyleOrFunction<StepListRenderProps>;
+}
+
+export interface StepProps {
+  /** The step item. */
+  item: { key: Key; label: string };
+  /** The 1-based step number. */
+  stepNumber: number;
+  /** The children to render inside the step. */
+  children?: JSX.Element;
+  /** The CSS className for the element. */
+  class?: string;
+  /** The inline style for the element. */
+  style?: JSX.CSSProperties;
+}
+
+export const StepListStateContext = createContext<StepListState | null>(null);
+export const StepListContext = createContext<{} | null>(null);
+
+export function useStepListState(): StepListState {
+  const ctx = useContext(StepListStateContext);
+  if (!ctx) throw new Error("useStepListState must be used within a StepList");
+  return ctx;
+}
+
+/**
+ * StepList displays a sequence of steps with completion tracking and selection.
+ */
+export function StepList<T extends { key: Key; label: string }>(
+  props: StepListProps<T>,
+): JSX.Element {
+  const [local, ariaProps, domRest] = splitProps(
+    props,
+    [
+      "items",
+      "selectedKey",
+      "defaultSelectedKey",
+      "onSelectionChange",
+      "lastCompletedStep",
+      "defaultLastCompletedStep",
+      "onLastCompletedStepChange",
+      "isDisabled",
+      "isReadOnly",
+      "disabledKeys",
+      "children",
+      "class",
+      "style",
+    ],
+    ["aria-label", "aria-labelledby"],
+  );
+
+  const stateProps = createMemo<StepListStateProps>(() => ({
+    items: local.items,
+    selectedKey: local.selectedKey,
+    defaultSelectedKey: local.defaultSelectedKey,
+    onSelectionChange: local.onSelectionChange,
+    lastCompletedStep: local.lastCompletedStep,
+    defaultLastCompletedStep: local.defaultLastCompletedStep,
+    onLastCompletedStepChange: local.onLastCompletedStepChange,
+    isDisabled: local.isDisabled,
+    isReadOnly: local.isReadOnly,
+    disabledKeys: local.disabledKeys,
+  }));
+
+  const state = createStepListState(stateProps());
+
+  // Create ARIA props
+  const { stepListProps } = createStepList(
+    {
+      get "aria-label"() {
+        return ariaProps["aria-label"];
+      },
+      get "aria-labelledby"() {
+        return ariaProps["aria-labelledby"];
+      },
+    },
+    state,
+  );
+
+  const renderValues = createMemo<StepListRenderProps>(() => ({
+    isDisabled: state.isDisabled(),
+  }));
+
+  const renderProps = useRenderProps(
+    {
+      class: local.class,
+      style: local.style,
+      defaultClassName: "solidaria-StepList",
+    },
+    renderValues,
+  );
+
+  const domProps = createMemo(() =>
+    filterDOMProps(domRest as Record<string, unknown>, { global: true }),
+  );
+
+  return (
+    <StepListStateContext.Provider value={state}>
+      <ol
+        {...stepListProps}
+        {...domProps()}
+        class={renderProps.class()}
+        style={renderProps.style()}
+        data-disabled={state.isDisabled() || undefined}
+      >
+        <For each={local.items}>
+          {(item, index) => {
+            const stepNumber = () => index() + 1;
+
+            // Build render props as a static snapshot for the initial render.
+            const renderProps: StepListItemRenderProps = {
+              get isSelected() {
+                return state.selectedKey() === item.key;
+              },
+              get isCompleted() {
+                return state.isCompleted(item.key);
+              },
+              get isDisabled() {
+                return state.isDisabled() || !state.isSelectable(item.key);
+              },
+              get isSelectable() {
+                return state.isSelectable(item.key);
+              },
+              get stepNumber() {
+                return stepNumber();
+              },
+              get stepStateText() {
+                if (state.selectedKey() === item.key) return "Current";
+                if (state.isCompleted(item.key)) return "Completed";
+                return "Not completed";
+              },
+            };
+
+            return local.children(item, renderProps);
+          }}
+        </For>
+      </ol>
+    </StepListStateContext.Provider>
+  );
+}
+
+/**
+ * Step represents an individual step within a StepList.
+ * Renders as an `<li>` wrapping an `<a>` with accessible step props.
+ */
+export function Step(props: StepProps): JSX.Element {
+  const [local, domProps] = splitProps(props, ["item", "stepNumber", "children", "class", "style"]);
+
+  const state = useStepListState();
+
+  const isSelected = () => state.selectedKey() === local.item.key;
+  const isCompleted = () => state.isCompleted(local.item.key);
+  const selectable = () => state.isSelectable(local.item.key);
+
+  const handleClick = (e: MouseEvent) => {
+    e.preventDefault();
+    if (selectable()) {
+      state.setSelectedKey(local.item.key);
+    }
+  };
+
+  const handleKeyDown = (e: KeyboardEvent) => {
+    if (e.key === "ArrowUp" || e.key === "ArrowDown") {
+      e.preventDefault();
+      return;
+    }
+    if (e.key === "Enter" || e.key === " ") {
+      e.preventDefault();
+      if (selectable()) {
+        state.setSelectedKey(local.item.key);
+      }
+    }
+  };
+
+  const stepStateText = () => {
+    if (isSelected()) return "Current";
+    if (isCompleted()) return "Completed";
+    return "Not completed";
+  };
+
+  return (
+    <li
+      {...domProps}
+      class={local.class}
+      style={local.style}
+      data-selected={isSelected() || undefined}
+      data-completed={isCompleted() || undefined}
+      data-disabled={!selectable() || undefined}
+      data-selectable={selectable() || undefined}
+    >
+      <a
+        role="link"
+        aria-current={isSelected() ? "step" : undefined}
+        aria-disabled={!selectable() ? true : undefined}
+        tabIndex={selectable() ? 0 : undefined}
+        onClick={handleClick}
+        on:keydown={handleKeyDown}
+        aria-label={`Step ${local.stepNumber}: ${local.item.label}, ${stepStateText()}`}
+      >
+        {local.children}
+      </a>
+    </li>
+  );
+}

package/src/Switch.tsx

@@ -11,16 +11,20 @@ import {
   type JSX,
   createContext,
   createMemo,
+  createSignal,
+  createUniqueId,
   splitProps,
-} from 'solid-js';
+  untrack,
+  Show,
+} from "solid-js";
 import {
   createSwitch,
   createFocusRing,
   createHover,
   type AriaSwitchProps,
-} from '@proyecto-viviana/solidaria';
-import { createToggleState, type ToggleState } from '@proyecto-viviana/solid-stately';
-import { VisuallyHidden } from './VisuallyHidden';
+} from "@proyecto-viviana/solidaria";
+import { createToggleState, type ToggleState } from "@proyecto-viviana/solid-stately";
+import { VisuallyHidden } from "./VisuallyHidden";
 import {
   type RenderChildren,
   type ClassNameOrFunction,
@@ -28,11 +32,7 @@ import {
   type SlotProps,
   useRenderProps,
   filterDOMProps,
-} from './utils';
-
-// ============================================
-// TYPES
-// ============================================
+} from "./utils";
 
 export interface ToggleSwitchRenderProps {
   /** Whether the switch is selected. */
@@ -49,31 +49,27 @@ export interface ToggleSwitchRenderProps {
   isDisabled: boolean;
   /** Whether the switch is read only. */
   isReadOnly: boolean;
+  /** Whether the switch is invalid. */
+  isInvalid: boolean;
   /** State of the switch. */
   state: ToggleState;
 }
 
-export interface ToggleSwitchProps
-  extends Omit<AriaSwitchProps, 'children'>,
-    SlotProps {
+export interface ToggleSwitchProps extends Omit<AriaSwitchProps, "children">, SlotProps {
   /** The children of the component. A function may be provided to receive render props. */
   children?: RenderChildren<ToggleSwitchRenderProps>;
   /** The CSS className for the element. */
   class?: ClassNameOrFunction<ToggleSwitchRenderProps>;
   /** The inline style for the element. */
   style?: StyleOrFunction<ToggleSwitchRenderProps>;
+  /** A description for the switch. */
+  description?: JSX.Element;
+  /** An error message for the switch. */
+  errorMessage?: JSX.Element;
 }
 
-// ============================================
-// CONTEXT
-// ============================================
-
 export const ToggleSwitchContext = createContext<ToggleSwitchProps | null>(null);
 
-// ============================================
-// COMPONENT
-// ============================================
-
 /**
  * A switch allows a user to turn a setting on or off.
  *
@@ -97,45 +93,51 @@ export const ToggleSwitchContext = createContext<ToggleSwitchProps | null>(null)
  * ```
  */
 export function ToggleSwitch(props: ToggleSwitchProps): JSX.Element {
-  let inputRef: HTMLInputElement | null = null;
+  const [inputElement, setInputElement] = createSignal<HTMLInputElement | null>(null);
 
-  // Split props
   const [local, ariaProps] = splitProps(props, [
-    'class',
-    'style',
-    'slot',
+    "class",
+    "style",
+    "slot",
+    "description",
+    "errorMessage",
   ]);
+  const descriptionId = createUniqueId();
+  const errorMessageId = createUniqueId();
 
-  // Create toggle state
   // Use getters to ensure props are read lazily inside reactive contexts
-  const state = createToggleState({
-    get isSelected() { return ariaProps.isSelected; },
-    get defaultSelected() { return ariaProps.defaultSelected; },
-    get onChange() { return ariaProps.onChange; },
-    get isReadOnly() { return ariaProps.isReadOnly; },
-  });
+  const state = createToggleState(() => ({
+    isSelected: ariaProps.isSelected,
+    defaultSelected: ariaProps.defaultSelected,
+    onChange: ariaProps.onChange,
+    isReadOnly: ariaProps.isReadOnly,
+  }));
 
-  // Create switch aria props
   const switchAria = createSwitch(
     () => ({
       ...ariaProps,
-      children: typeof props.children === 'function' ? true : props.children,
+      children: typeof props.children === "function" ? true : props.children,
     }),
     state,
-    () => inputRef
+    inputElement,
   );
+  const describedBy = () => {
+    const ids = [
+      ariaProps["aria-describedby"],
+      local.description ? descriptionId : undefined,
+      switchAria.isInvalid && local.errorMessage ? errorMessageId : undefined,
+    ].filter(Boolean);
+    return ids.length ? ids.join(" ") : undefined;
+  };
 
-  // Create focus ring
   const { isFocused, isFocusVisible, focusProps } = createFocusRing();
 
-  // Create hover
   const { isHovered, hoverProps } = createHover({
     get isDisabled() {
       return ariaProps.isDisabled || ariaProps.isReadOnly;
     },
   });
 
-  // Render props values
   const renderValues = createMemo<ToggleSwitchRenderProps>(() => ({
     isSelected: switchAria.isSelected(),
     isHovered: isHovered(),
@@ -144,21 +146,49 @@ export function ToggleSwitch(props: ToggleSwitchProps): JSX.Element {
     isFocusVisible: isFocusVisible(),
     isDisabled: switchAria.isDisabled,
     isReadOnly: switchAria.isReadOnly,
+    isInvalid: switchAria.isInvalid,
     state,
   }));
 
-  // Resolve render props
   const renderProps = useRenderProps(
     {
       children: props.children,
       class: local.class,
       style: local.style,
-      defaultClassName: 'solidaria-ToggleSwitch',
+      defaultClassName: "solidaria-ToggleSwitch",
     },
-    renderValues
+    renderValues,
   );
+  const childRenderValues: ToggleSwitchRenderProps = {
+    get isSelected() {
+      return switchAria.isSelected();
+    },
+    get isHovered() {
+      return isHovered();
+    },
+    get isPressed() {
+      return switchAria.isPressed();
+    },
+    get isFocused() {
+      return isFocused();
+    },
+    get isFocusVisible() {
+      return isFocusVisible();
+    },
+    get isDisabled() {
+      return switchAria.isDisabled;
+    },
+    get isReadOnly() {
+      return switchAria.isReadOnly;
+    },
+    get isInvalid() {
+      return switchAria.isInvalid;
+    },
+    get state() {
+      return state;
+    },
+  };
 
-  // Filter DOM props
   const domProps = createMemo(() => {
     const filtered = filterDOMProps(ariaProps, { global: true });
     delete (filtered as Record<string, unknown>).id;
@@ -166,7 +196,6 @@ export function ToggleSwitch(props: ToggleSwitchProps): JSX.Element {
     return filtered;
   });
 
-  // Remove ref from spread props to avoid type conflicts
   const cleanLabelProps = () => {
     const { ref: _ref1, ...rest } = switchAria.labelProps as Record<string, unknown>;
     return rest;
@@ -183,6 +212,14 @@ export function ToggleSwitch(props: ToggleSwitchProps): JSX.Element {
     const { ref: _ref4, ...rest } = focusProps as Record<string, unknown>;
     return rest;
   };
+  // Resolve the render-prop children ONCE (untracked) — see TextField. Re-invoking
+  // it on a reactive update re-clones its templates and, mid-hydration, throws a
+  // Hydration Mismatch. The children keep fine-grained reactivity via the
+  // childRenderValues getters + <Show>s.
+  const switchChildren = untrack(() => {
+    const children = props.children;
+    return typeof children === "function" ? children(childRenderValues) : children;
+  });
 
   return (
     <label
@@ -201,13 +238,23 @@ export function ToggleSwitch(props: ToggleSwitchProps): JSX.Element {
     >
       <VisuallyHidden>
         <input
-          ref={(el) => (inputRef = el)}
+          ref={setInputElement}
           {...cleanInputProps()}
           {...cleanFocusProps()}
+          aria-describedby={describedBy()}
         />
       </VisuallyHidden>
-      {renderProps.renderChildren()}
+      {switchChildren}
+      <Show when={local.description}>
+        <span id={descriptionId} slot="description">
+          {local.description}
+        </span>
+      </Show>
+      <Show when={switchAria.isInvalid && local.errorMessage}>
+        <span id={errorMessageId} slot="errorMessage">
+          {local.errorMessage}
+        </span>
+      </Show>
     </label>
   );
 }
-