@robr0/design-system 0.1.0 → 0.3.0

package/components/Dropdown/Dropdown.js

@@ -1,156 +1,219 @@
 import { jsxs, jsx } from "react/jsx-runtime";
-import { useState, useRef, useCallback, useEffect } from "react";
+import React, { useState, useRef, useCallback, useEffect } from "react";
+import { Field } from "../Field/Field.js";
 import "./Dropdown.css";
 import "../../fonts/material-symbols.css";
-const Dropdown = ({
-  label,
-  placeholder = "Select an option",
-  value,
-  options,
-  groups,
-  size = "default",
-  disabled = false,
-  required = false,
-  error = false,
-  helperText,
-  onChange,
-  className = "",
-  ariaLabel,
-  name,
-  id
-}) => {
-  const [isOpen, setIsOpen] = useState(false);
-  const [focusedIndex, setFocusedIndex] = useState(-1);
-  const dropdownRef = useRef(null);
-  const listRef = useRef(null);
-  const baseClass = "ds-dropdown";
-  const isGrouped = groups && groups.length > 0;
-  const sizeClass = size === "compact" ? `${baseClass}--compact` : "";
-  const openClass = isOpen ? `${baseClass}--open` : "";
-  const errorClass = error ? `${baseClass}--error` : "";
-  const disabledClass = disabled ? `${baseClass}--disabled` : "";
-  const classes = [baseClass, sizeClass, openClass, errorClass, disabledClass, className].filter(Boolean).join(" ");
-  const flatOptions = isGrouped ? groups.flatMap((g) => g.options) : options;
-  const selectedOption = flatOptions.find((opt) => opt.value === value);
-  const inputId = id || name || label?.toLowerCase().replace(/\s+/g, "-");
-  const handleToggle = () => {
-    if (!disabled) {
-      setIsOpen((prev) => !prev);
-      setFocusedIndex(-1);
-    }
-  };
-  const handleSelect = (optionValue) => {
-    if (onChange) {
-      onChange(optionValue);
-    }
-    setIsOpen(false);
-  };
-  const handleClickOutside = useCallback((e) => {
-    if (dropdownRef.current && !dropdownRef.current.contains(e.target)) {
+const Dropdown = React.forwardRef(
+  ({
+    label,
+    placeholder = "Select an option",
+    value,
+    options,
+    groups,
+    size = "default",
+    disabled = false,
+    required = false,
+    error = false,
+    helperText,
+    onValueChange,
+    onChange,
+    className = "",
+    ariaLabel,
+    name,
+    id,
+    ...rest
+  }, ref) => {
+    const [isOpen, setIsOpen] = useState(false);
+    const [focusedIndex, setFocusedIndex] = useState(-1);
+    const dropdownRef = useRef(null);
+    const listRef = useRef(null);
+    const setRootRef = (node) => {
+      dropdownRef.current = node;
+      if (typeof ref === "function") ref(node);
+      else if (ref) ref.current = node;
+    };
+    const baseClass = "ds-dropdown";
+    const isGrouped = groups && groups.length > 0;
+    const classes = [
+      baseClass,
+      size === "compact" ? `${baseClass}--compact` : "",
+      isOpen ? `${baseClass}--open` : "",
+      error ? `${baseClass}--error` : "",
+      disabled ? `${baseClass}--disabled` : "",
+      className
+    ].filter(Boolean).join(" ");
+    const flatOptions = isGrouped ? groups.flatMap((g) => g.options) : options;
+    const selectedOption = flatOptions.find((opt) => opt.value === value);
+    const inputId = id || name || label?.toLowerCase().replace(/\s+/g, "-");
+    const handleToggle = () => {
+      if (!disabled) {
+        setIsOpen((prev) => !prev);
+        setFocusedIndex(-1);
+      }
+    };
+    const handleSelect = (optionValue) => {
+      onValueChange?.(optionValue);
+      onChange?.(optionValue);
       setIsOpen(false);
-    }
-  }, []);
-  useEffect(() => {
-    document.addEventListener("mousedown", handleClickOutside);
-    return () => document.removeEventListener("mousedown", handleClickOutside);
-  }, [handleClickOutside]);
-  const handleKeyDown = (e) => {
-    if (disabled) return;
-    switch (e.key) {
-      case "Enter":
-      case " ":
-        e.preventDefault();
-        if (isOpen && focusedIndex >= 0 && !flatOptions[focusedIndex]?.disabled) {
-          handleSelect(flatOptions[focusedIndex].value);
-        } else {
-          setIsOpen((prev) => !prev);
-        }
-        break;
-      case "ArrowDown":
-        e.preventDefault();
-        if (!isOpen) {
-          setIsOpen(true);
-        } else {
-          setFocusedIndex((prev) => {
-            let next = prev + 1;
-            while (next < flatOptions.length && flatOptions[next].disabled) next++;
-            return next < flatOptions.length ? next : prev;
-          });
-        }
-        break;
-      case "ArrowUp":
-        e.preventDefault();
-        if (isOpen) {
-          setFocusedIndex((prev) => {
-            let next = prev - 1;
-            while (next >= 0 && flatOptions[next].disabled) next--;
-            return next >= 0 ? next : prev;
-          });
-        }
-        break;
-      case "Escape":
-        setIsOpen(false);
-        break;
-      case "Tab":
+    };
+    const handleClickOutside = useCallback((e) => {
+      if (dropdownRef.current && !dropdownRef.current.contains(e.target)) {
         setIsOpen(false);
-        break;
-    }
-  };
-  useEffect(() => {
-    if (isOpen && focusedIndex >= 0 && listRef.current) {
-      const focusedEl = listRef.current.children[focusedIndex];
-      focusedEl?.scrollIntoView({ block: "nearest" });
-    }
-  }, [focusedIndex, isOpen]);
-  return /* @__PURE__ */ jsxs("div", { className: classes, ref: dropdownRef, children: [
-    label && /* @__PURE__ */ jsxs("label", { className: `${baseClass}__label`, id: `${inputId}-label`, children: [
-      label,
-      required && /* @__PURE__ */ jsx("span", { className: `${baseClass}__required`, "aria-hidden": "true", children: " *" })
-    ] }),
-    /* @__PURE__ */ jsxs(
-      "div",
-      {
-        className: `${baseClass}__trigger`,
-        role: "combobox",
-        "aria-expanded": isOpen,
-        "aria-haspopup": "listbox",
-        "aria-labelledby": label ? `${inputId}-label` : void 0,
-        "aria-label": ariaLabel || (!label ? placeholder : void 0),
-        "aria-controls": `${inputId}-listbox`,
-        tabIndex: disabled ? -1 : 0,
-        onClick: handleToggle,
-        onKeyDown: handleKeyDown,
-        children: [
-          /* @__PURE__ */ jsx("span", { className: `${baseClass}__value ${!selectedOption ? `${baseClass}__value--placeholder` : ""}`, children: selectedOption ? selectedOption.label : placeholder }),
-          /* @__PURE__ */ jsx("span", { className: `${baseClass}__chevron material-symbols-rounded`, "aria-hidden": "true", children: "expand_more" })
-        ]
       }
-    ),
-    isOpen && /* @__PURE__ */ jsx(
-      "ul",
+    }, []);
+    useEffect(() => {
+      document.addEventListener("mousedown", handleClickOutside);
+      return () => document.removeEventListener("mousedown", handleClickOutside);
+    }, [handleClickOutside]);
+    const handleKeyDown = (e) => {
+      if (disabled) return;
+      switch (e.key) {
+        case "Enter":
+        case " ":
+          e.preventDefault();
+          if (isOpen && focusedIndex >= 0 && !flatOptions[focusedIndex]?.disabled) {
+            handleSelect(flatOptions[focusedIndex].value);
+          } else {
+            setIsOpen((prev) => !prev);
+          }
+          break;
+        case "ArrowDown":
+          e.preventDefault();
+          if (!isOpen) {
+            setIsOpen(true);
+          } else {
+            setFocusedIndex((prev) => {
+              let next = prev + 1;
+              while (next < flatOptions.length && flatOptions[next].disabled) next++;
+              return next < flatOptions.length ? next : prev;
+            });
+          }
+          break;
+        case "ArrowUp":
+          e.preventDefault();
+          if (isOpen) {
+            setFocusedIndex((prev) => {
+              let next = prev - 1;
+              while (next >= 0 && flatOptions[next].disabled) next--;
+              return next >= 0 ? next : prev;
+            });
+          }
+          break;
+        case "Escape":
+          setIsOpen(false);
+          break;
+        case "Tab":
+          setIsOpen(false);
+          break;
+      }
+    };
+    useEffect(() => {
+      if (isOpen && focusedIndex >= 0 && listRef.current) {
+        const focusedEl = listRef.current.children[focusedIndex];
+        focusedEl?.scrollIntoView({ block: "nearest" });
+      }
+    }, [focusedIndex, isOpen]);
+    return /* @__PURE__ */ jsxs(
+      Field,
       {
-        className: [
-          `${baseClass}__menu`,
-          isGrouped ? `${baseClass}__menu--grouped` : ""
-        ].filter(Boolean).join(" "),
-        role: "listbox",
-        id: `${inputId}-listbox`,
-        ref: listRef,
-        "aria-labelledby": label ? `${inputId}-label` : void 0,
-        children: isGrouped ? (() => {
-          let flatIndex = 0;
-          return groups.map((group, groupIdx) => /* @__PURE__ */ jsxs("li", { className: `${baseClass}__group`, role: "none", children: [
-            /* @__PURE__ */ jsx("span", { className: `${baseClass}__group-label`, role: "presentation", children: group.label }),
-            /* @__PURE__ */ jsx("ul", { className: `${baseClass}__group-list`, role: "group", "aria-label": group.label, children: group.options.map((option) => {
-              const myIndex = flatIndex++;
-              return /* @__PURE__ */ jsxs(
+        ...rest,
+        className: classes,
+        ref: setRootRef,
+        label,
+        helperText,
+        error,
+        required,
+        disabled,
+        size,
+        id: inputId,
+        children: [
+          /* @__PURE__ */ jsxs(
+            "div",
+            {
+              className: `${baseClass}__trigger`,
+              role: "combobox",
+              "aria-expanded": isOpen,
+              "aria-haspopup": "listbox",
+              "aria-labelledby": label ? `${inputId}-label` : void 0,
+              "aria-label": ariaLabel || rest["aria-label"] || (!label ? placeholder : void 0),
+              "aria-controls": `${inputId}-listbox`,
+              "aria-describedby": helperText ? `${inputId}-helper` : rest["aria-describedby"],
+              "aria-invalid": error || void 0,
+              tabIndex: disabled ? -1 : 0,
+              onClick: handleToggle,
+              onKeyDown: handleKeyDown,
+              children: [
+                /* @__PURE__ */ jsx(
+                  "span",
+                  {
+                    className: `${baseClass}__value ${!selectedOption ? `${baseClass}__value--placeholder` : ""}`,
+                    children: selectedOption ? selectedOption.label : placeholder
+                  }
+                ),
+                /* @__PURE__ */ jsx("span", { className: `${baseClass}__chevron material-symbols-rounded`, "aria-hidden": "true", children: "expand_more" })
+              ]
+            }
+          ),
+          isOpen && /* @__PURE__ */ jsx(
+            "ul",
+            {
+              className: [`${baseClass}__menu`, isGrouped ? `${baseClass}__menu--grouped` : ""].filter(Boolean).join(" "),
+              role: "listbox",
+              id: `${inputId}-listbox`,
+              ref: listRef,
+              "aria-labelledby": label ? `${inputId}-label` : void 0,
+              children: isGrouped ? (() => {
+                let flatIndex = 0;
+                return groups.map((group, groupIdx) => /* @__PURE__ */ jsxs("li", { className: `${baseClass}__group`, role: "none", children: [
+                  /* @__PURE__ */ jsx("span", { className: `${baseClass}__group-label`, role: "presentation", children: group.label }),
+                  /* @__PURE__ */ jsx(
+                    "ul",
+                    {
+                      className: `${baseClass}__group-list`,
+                      role: "group",
+                      "aria-label": group.label,
+                      children: group.options.map((option) => {
+                        const myIndex = flatIndex++;
+                        return /* @__PURE__ */ jsxs(
+                          "li",
+                          {
+                            className: [
+                              `${baseClass}__option`,
+                              option.value === value ? `${baseClass}__option--selected` : "",
+                              option.disabled ? `${baseClass}__option--disabled` : "",
+                              myIndex === focusedIndex ? `${baseClass}__option--focused` : ""
+                            ].filter(Boolean).join(" "),
+                            role: "option",
+                            "aria-selected": option.value === value,
+                            "aria-disabled": option.disabled,
+                            onClick: () => !option.disabled && handleSelect(option.value),
+                            children: [
+                              option.label,
+                              option.value === value && /* @__PURE__ */ jsx(
+                                "span",
+                                {
+                                  className: `${baseClass}__check material-symbols-rounded`,
+                                  "aria-hidden": "true",
+                                  children: "check"
+                                }
+                              )
+                            ]
+                          },
+                          option.value
+                        );
+                      })
+                    }
+                  ),
+                  groupIdx < groups.length - 1 && /* @__PURE__ */ jsx("li", { className: `${baseClass}__separator`, role: "separator" })
+                ] }, `group-${groupIdx}`));
+              })() : options.map((option, index) => /* @__PURE__ */ jsxs(
                 "li",
                 {
                   className: [
                     `${baseClass}__option`,
                     option.value === value ? `${baseClass}__option--selected` : "",
                     option.disabled ? `${baseClass}__option--disabled` : "",
-                    myIndex === focusedIndex ? `${baseClass}__option--focused` : ""
+                    index === focusedIndex ? `${baseClass}__option--focused` : ""
                   ].filter(Boolean).join(" "),
                   role: "option",
                   "aria-selected": option.value === value,
@@ -158,39 +221,26 @@ const Dropdown = ({
                   onClick: () => !option.disabled && handleSelect(option.value),
                   children: [
                     option.label,
-                    option.value === value && /* @__PURE__ */ jsx("span", { className: `${baseClass}__check material-symbols-rounded`, "aria-hidden": "true", children: "check" })
+                    option.value === value && /* @__PURE__ */ jsx(
+                      "span",
+                      {
+                        className: `${baseClass}__check material-symbols-rounded`,
+                        "aria-hidden": "true",
+                        children: "check"
+                      }
+                    )
                   ]
                 },
                 option.value
-              );
-            }) }),
-            groupIdx < groups.length - 1 && /* @__PURE__ */ jsx("li", { className: `${baseClass}__separator`, role: "separator" })
-          ] }, `group-${groupIdx}`));
-        })() : options.map((option, index) => /* @__PURE__ */ jsxs(
-          "li",
-          {
-            className: [
-              `${baseClass}__option`,
-              option.value === value ? `${baseClass}__option--selected` : "",
-              option.disabled ? `${baseClass}__option--disabled` : "",
-              index === focusedIndex ? `${baseClass}__option--focused` : ""
-            ].filter(Boolean).join(" "),
-            role: "option",
-            "aria-selected": option.value === value,
-            "aria-disabled": option.disabled,
-            onClick: () => !option.disabled && handleSelect(option.value),
-            children: [
-              option.label,
-              option.value === value && /* @__PURE__ */ jsx("span", { className: `${baseClass}__check material-symbols-rounded`, "aria-hidden": "true", children: "check" })
-            ]
-          },
-          option.value
-        ))
+              ))
+            }
+          )
+        ]
       }
-    ),
-    helperText && /* @__PURE__ */ jsx("p", { className: `${baseClass}__helper`, id: `${inputId}-helper`, children: helperText })
-  ] });
-};
+    );
+  }
+);
+Dropdown.displayName = "Dropdown";
 export {
   Dropdown
 };

package/components/DropdownMenu/DropdownMenu.js

@@ -1,5 +1,5 @@
 import { jsxs, jsx } from "react/jsx-runtime";
-import { useState, useRef, useCallback, useEffect } from "react";
+import React, { useState, useRef, useCallback, useEffect } from "react";
 import "./DropdownMenu.css";
 import "../../fonts/material-symbols.css";
 function collectItems(entries) {
@@ -291,19 +291,22 @@ const DropdownMenu = ({
   ].filter(Boolean).join(" ");
   const itemCounter = { count: 0 };
   return /* @__PURE__ */ jsxs("div", { className: classes, ref: rootRef, children: [
-    /* @__PURE__ */ jsx(
-      "div",
+    /* @__PURE__ */ jsx("div", { className: `${baseClass}__trigger`, children: React.isValidElement(trigger) ? React.cloneElement(trigger, {
+      "aria-haspopup": "menu",
+      "aria-expanded": isOpen,
+      onClick: handleToggle,
+      onKeyDown: handleKeyDown
+    }) : /* @__PURE__ */ jsx(
+      "button",
       {
-        className: `${baseClass}__trigger`,
-        role: "button",
-        tabIndex: 0,
+        type: "button",
         "aria-haspopup": "menu",
         "aria-expanded": isOpen,
         onClick: handleToggle,
         onKeyDown: handleKeyDown,
         children: trigger
       }
-    ),
+    ) }),
     isOpen && /* @__PURE__ */ jsx(
       "ul",
       {

package/components/Field/Field.css

@@ -0,0 +1,80 @@
+/* ============================================
+   FIELD COMPONENT
+   Label, required marker, and helper/error text
+   shared by every labelled form control.
+
+   Layout (flex column, gap) deliberately stays on the
+   consuming component's own root class — Field only
+   owns the label and helper scaffolding, so adopting it
+   changes no spacing.
+   ============================================ */
+
+/* ============================================
+   LABEL
+   ============================================ */
+
+.ds-field__label {
+  font-family: var(--font-paragraph-em-family);
+  font-size: var(--font-paragraph-em-size);
+  font-weight: var(--font-paragraph-em-weight);
+  line-height: var(--font-paragraph-em-line-height);
+  letter-spacing: var(--font-paragraph-em-letter-spacing);
+  color: var(--color-text-primary);
+}
+
+.ds-field__required {
+  color: var(--color-core-accent-coral);
+}
+
+/* ============================================
+   FOOTER — only rendered when an `aside` is supplied
+   (a character counter, a unit). Without one the helper
+   sits directly in the field column, so adopting Field
+   adds no wrapper to existing markup.
+   ============================================ */
+
+.ds-field__footer {
+  display: flex;
+  align-items: flex-start;
+  justify-content: space-between;
+  gap: var(--gap-sm);
+}
+
+/* ============================================
+   HELPER TEXT
+   ============================================ */
+
+.ds-field__helper {
+  font-family: var(--font-paragraph-sm-family);
+  font-size: var(--font-paragraph-sm-size);
+  font-weight: var(--font-paragraph-sm-weight);
+  line-height: var(--font-paragraph-sm-line-height);
+  letter-spacing: var(--font-paragraph-sm-letter-spacing);
+  color: var(--color-text-tertiary);
+  margin: 0;
+}
+
+/* ============================================
+   ERROR STATE
+   ============================================ */
+
+.ds-field--error .ds-field__helper {
+  color: var(--color-status-error-border);
+}
+
+/* ============================================
+   DISABLED STATE
+   ============================================ */
+
+.ds-field--disabled .ds-field__label {
+  color: var(--color-input-text-disabled);
+}
+
+/* ============================================
+   COMPACT SIZE
+   ============================================ */
+
+.ds-field--compact .ds-field__label {
+  font-size: var(--font-paragraph-sm-size);
+  line-height: var(--font-paragraph-sm-line-height);
+}

package/components/Field/Field.d.ts

@@ -0,0 +1,50 @@
+import { default as React } from 'react';
+/** Props owned by Field itself — everything else falls through to the wrapper. */
+type FieldOwnProps = {
+    /** Label text rendered above the control */
+    label?: string;
+    /** The form control this field labels */
+    children?: React.ReactNode;
+    /** Helper or error message rendered below the control */
+    helperText?: string;
+    /**
+     * Optional content rendered opposite the helper text — a character counter,
+     * a unit, a "0/280". Present only when supplied; without it the helper sits
+     * directly in the field's column and no extra wrapper is introduced.
+     */
+    aside?: React.ReactNode;
+    /** Error state — recolours the helper text and marks the control invalid */
+    error?: boolean;
+    /** Marks the field required and renders the required marker */
+    required?: boolean;
+    /** Whether the control is disabled — dims the label */
+    disabled?: boolean;
+    /** Component size */
+    size?: 'default' | 'compact';
+    /**
+     * id for the control. Generated when omitted, so the label/control/helper
+     * association works with no configuration.
+     */
+    id?: string;
+    /** Additional CSS classes */
+    className?: string;
+};
+export interface FieldProps extends FieldOwnProps, Omit<React.ComponentPropsWithoutRef<'div'>, keyof FieldOwnProps> {
+}
+/**
+ * Field owns the scaffolding shared by every labelled form control: the label
+ * and its `htmlFor`, the required marker, the helper/error message, the ids
+ * that tie them together, and the `aria-describedby` / `aria-invalid` wiring.
+ *
+ * Controls compose inside it and read the wiring through `useField()` rather
+ * than deriving ids themselves — which is what keeps accessibility correct
+ * systemically instead of one component at a time.
+ *
+ * ```tsx
+ * <Field label="Email" helperText="We never share it." required>
+ *   <MyControl />
+ * </Field>
+ * ```
+ */
+export declare const Field: React.ForwardRefExoticComponent<FieldProps & React.RefAttributes<HTMLDivElement>>;
+export {};

package/components/Field/Field.js

@@ -0,0 +1,58 @@
+import { jsx, jsxs } from "react/jsx-runtime";
+import React, { useId } from "react";
+import { FieldContext } from "./FieldContext.js";
+import "./Field.css";
+const Field = React.forwardRef(
+  ({
+    label,
+    children,
+    helperText,
+    aside,
+    error = false,
+    required = false,
+    disabled = false,
+    size = "default",
+    id,
+    className = "",
+    ...rest
+  }, ref) => {
+    const baseClass = "ds-field";
+    const generatedId = useId();
+    const controlId = id || generatedId;
+    const describedBy = helperText ? `${controlId}-helper` : void 0;
+    const labelId = label ? `${controlId}-label` : void 0;
+    const classes = [
+      baseClass,
+      size === "compact" ? `${baseClass}--compact` : "",
+      error ? `${baseClass}--error` : "",
+      disabled ? `${baseClass}--disabled` : "",
+      className
+    ].filter(Boolean).join(" ");
+    const context = {
+      controlId,
+      labelId,
+      describedBy,
+      invalid: error,
+      required,
+      disabled
+    };
+    return /* @__PURE__ */ jsx(FieldContext.Provider, { value: context, children: /* @__PURE__ */ jsxs("div", { ...rest, ref, className: classes, children: [
+      label && /* @__PURE__ */ jsxs("label", { className: `${baseClass}__label`, id: labelId, htmlFor: controlId, children: [
+        label,
+        required && /* @__PURE__ */ jsxs("span", { className: `${baseClass}__required`, "aria-hidden": "true", children: [
+          " ",
+          "*"
+        ] })
+      ] }),
+      children,
+      aside ? /* @__PURE__ */ jsxs("div", { className: `${baseClass}__footer`, children: [
+        helperText ? /* @__PURE__ */ jsx("p", { className: `${baseClass}__helper`, id: describedBy, children: helperText }) : /* @__PURE__ */ jsx("span", {}),
+        aside
+      ] }) : helperText && /* @__PURE__ */ jsx("p", { className: `${baseClass}__helper`, id: describedBy, children: helperText })
+    ] }) });
+  }
+);
+Field.displayName = "Field";
+export {
+  Field
+};