@abstraks-dev/ui-library 1.0.1

package/dist/components/Select.js

@@ -0,0 +1,422 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = exports.Select = void 0;
+var _react = _interopRequireWildcard(require("react"));
+var _propTypes = _interopRequireDefault(require("prop-types"));
+var _Label = require("./Label");
+var _Error = require("./Error");
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+function _interopRequireWildcard(e, t) { if ("function" == typeof WeakMap) var r = new WeakMap(), n = new WeakMap(); return (_interopRequireWildcard = function (e, t) { if (!t && e && e.__esModule) return e; var o, i, f = { __proto__: null, default: e }; if (null === e || "object" != typeof e && "function" != typeof e) return f; if (o = t ? n : r) { if (o.has(e)) return o.get(e); o.set(e, f); } for (const t in e) "default" !== t && {}.hasOwnProperty.call(e, t) && ((i = (o = Object.defineProperty) && Object.getOwnPropertyDescriptor(e, t)) && (i.get || i.set) ? o(f, t, i) : f[t] = e[t]); return f; })(e, t); }
+function _extends() { return _extends = Object.assign ? Object.assign.bind() : function (n) { for (var e = 1; e < arguments.length; e++) { var t = arguments[e]; for (var r in t) ({}).hasOwnProperty.call(t, r) && (n[r] = t[r]); } return n; }, _extends.apply(null, arguments); }
+const {
+  string,
+  number,
+  bool,
+  arrayOf,
+  oneOfType,
+  shape,
+  element,
+  func,
+  object
+} = _propTypes.default;
+// components
+
+/**
+ * Select - Accessible dropdown selection component with comprehensive form support
+ *
+ * Features:
+ * - Full keyboard navigation (Tab, Space, Enter, Arrow keys, Escape)
+ * - Screen reader support with proper ARIA labeling
+ * - Form validation integration with error states
+ * - Multiple option formats (string, object, React elements)
+ * - Responsive design with consistent styling
+ * - High contrast mode support
+ * - Disabled and required state handling
+ * - Help text and error message support
+ *
+ * Accessibility:
+ * - Uses semantic <select> element with proper labeling
+ * - ARIA attributes for screen reader compatibility
+ * - Keyboard navigation following web standards
+ * - Error announcements with aria-live regions
+ * - Proper form association and validation
+ * - Focus management and tab order support
+ *
+ * @component
+ * @example
+ * // Basic usage with object options
+ * <Select
+ *   name="country"
+ *   label="Select Country"
+ *   value={selectedCountry}
+ *   onChange={handleCountryChange}
+ *   options={[
+ *     { value: 'us', label: 'United States' },
+ *     { value: 'ca', label: 'Canada' }
+ *   ]}
+ * />
+ *
+ * @example
+ * // With validation and help text
+ * <Select
+ *   name="size"
+ *   label="Size"
+ *   value={size}
+ *   onChange={handleSizeChange}
+ *   options={sizeOptions}
+ *   required
+ *   error={hasError}
+ *   errorText="Please select a size"
+ *   helpText="Choose the size that fits best"
+ * />
+ *
+ * @example
+ * // Multiple selection with custom styling
+ * <Select
+ *   name="tags"
+ *   label="Select Tags"
+ *   value={selectedTags}
+ *   onChange={handleTagsChange}
+ *   options={tagOptions}
+ *   multiple
+ *   className="custom-select"
+ * />
+ */
+const Select = exports.Select = /*#__PURE__*/(0, _react.forwardRef)(({
+  // Core props (required)
+  name,
+  label,
+  onChange = () => {},
+  // Provide default no-op function to prevent React warnings			// Content props
+  value = '',
+  options = [],
+  placeholder = 'Select an option',
+  helpText = '',
+  // Legacy compatibility - handle old prop names
+  additionalClassName,
+  componentName = 'Select',
+  setName,
+  // legacy name prop
+  selectOptions,
+  // legacy options prop
+  defaultValue,
+  // legacy placeholder prop
+  noLabel,
+  // legacy hideLabel prop
+
+  // Layout props
+  className: classNameProp = '',
+  hideLabel = false,
+  multiple = false,
+  size,
+  // Validation props
+  required = false,
+  disabled = false,
+  error = false,
+  errorText = '',
+  // Accessibility props
+  id,
+  ariaLabel,
+  ariaDescribedBy,
+  ariaRequired,
+  tabIndex,
+  // Event handlers
+  onFocus,
+  onBlur,
+  onKeyDown,
+  // Styling props
+  style = {},
+  // Testing props
+  'data-testid': dataTestId,
+  'data-cy': dataCy,
+  ...restProps
+}, ref) => {
+  // Handle legacy prop mapping for backward compatibility
+  const finalName = name || setName;
+  const finalLabel = label || (setName && !noLabel ? setName : '');
+  const finalOptions = options.length > 0 ? options : selectOptions || [];
+  const finalPlaceholder = placeholder !== 'Select an option' ? placeholder : defaultValue || placeholder;
+  const finalHideLabel = hideLabel || noLabel || false;
+  const className = classNameProp || additionalClassName || '';
+
+  // Log deprecation warnings for legacy props (development only)
+  if (process.env.NODE_ENV === 'development') {
+    if (additionalClassName) {
+      console.warn(`${componentName}: 'additionalClassName' prop is deprecated. Use 'className' instead.`);
+    }
+    if (setName) {
+      console.warn(`${componentName}: 'setName' prop is deprecated. Use 'name' instead.`);
+    }
+    if (selectOptions) {
+      console.warn(`${componentName}: 'selectOptions' prop is deprecated. Use 'options' instead.`);
+    }
+    if (defaultValue) {
+      console.warn(`${componentName}: 'defaultValue' prop is deprecated. Use 'placeholder' instead.`);
+    }
+    if (noLabel !== undefined) {
+      console.warn(`${componentName}: 'noLabel' prop is deprecated. Use 'hideLabel' instead.`);
+    }
+  }
+  // Generate unique ID if not provided
+  const selectId = id || `select-${finalName}`;
+  const errorId = `${selectId}-error`;
+  const helpTextId = `${selectId}-help`;
+
+  // Calculate aria-describedby
+  const describedBy = [ariaDescribedBy, helpText ? helpTextId : null, error && errorText ? errorId : null].filter(Boolean).join(' ') || undefined;
+
+  // Handle keyboard navigation
+  const handleKeyDown = event => {
+    // Let native select handle most keyboard interactions
+    // Custom logic can be added here if needed
+    onKeyDown?.(event);
+  };
+
+  // Render options from array format
+  const renderOptions = () => {
+    if (!finalOptions || finalOptions.length === 0) return null;
+    return finalOptions.map((option, index) => {
+      // Support both object format { value, label } and string format
+      if (typeof option === 'string') {
+        return /*#__PURE__*/_react.default.createElement("option", {
+          key: `${option}-${index}`,
+          value: option
+        }, option);
+      }
+      if (typeof option === 'object' && option.value !== undefined) {
+        return /*#__PURE__*/_react.default.createElement("option", {
+          key: `${option.value}-${index}`,
+          value: option.value,
+          disabled: option.disabled
+        }, option.label || option.value);
+      }
+
+      // Support React element options (backward compatibility)
+      return option;
+    });
+  };
+  const selectElement = /*#__PURE__*/_react.default.createElement("select", _extends({
+    ref: ref,
+    id: selectId,
+    name: finalName,
+    value: value,
+    onChange: onChange,
+    onFocus: onFocus,
+    onBlur: onBlur,
+    onKeyDown: handleKeyDown,
+    disabled: disabled,
+    required: required || ariaRequired,
+    multiple: multiple,
+    size: size,
+    className: `select ${error ? 'select--error' : ''} ${disabled ? 'select--disabled' : ''}`,
+    style: style,
+    "aria-label": finalHideLabel ? ariaLabel || finalLabel : ariaLabel,
+    "aria-describedby": describedBy,
+    "aria-invalid": error,
+    "aria-required": required || ariaRequired,
+    tabIndex: tabIndex,
+    "data-testid": dataTestId || `select-${finalName}`,
+    "data-cy": dataCy
+  }, restProps), !multiple && finalPlaceholder && /*#__PURE__*/_react.default.createElement("option", {
+    value: "",
+    disabled: true
+  }, finalPlaceholder), renderOptions());
+  return /*#__PURE__*/_react.default.createElement("div", {
+    className: `${componentName.toLowerCase()}-wrapper ${finalHideLabel ? `${componentName.toLowerCase()}--no-label` : `${componentName.toLowerCase()}--with-label`} ${className}`,
+    "data-testid": `${componentName ? componentName.toLowerCase() : 'select'}-wrapper`
+  }, !finalHideLabel && finalLabel && /*#__PURE__*/_react.default.createElement(_Label.Label, {
+    htmlFor: selectId,
+    required: required,
+    labelText: finalLabel,
+    className: "select__label"
+  }), helpText && /*#__PURE__*/_react.default.createElement("div", {
+    id: helpTextId,
+    className: "select__help-text"
+  }, helpText), selectElement, error && errorText && /*#__PURE__*/_react.default.createElement(_Error.Error, {
+    id: errorId,
+    className: "select__error",
+    role: "alert",
+    "aria-live": "polite"
+  }, errorText));
+});
+/**
+ * PropTypes for Select component
+ * Organized by categories for better maintainability and documentation
+ */
+Select.propTypes = {
+  // =====================
+  // Core Props (Required)
+  // =====================
+  /**
+   * The name attribute for the select input (required for form submission)
+   * Used to identify the field in form data and for accessibility
+   */
+  name: string.isRequired,
+  /**
+   * The label text displayed above the select (required for accessibility)
+   * Should clearly describe what the user is selecting
+   */
+  label: string.isRequired,
+  /**
+   * Function called when selection changes (required)
+   * Receives the change event as parameter
+   * @param {Event} event - The change event from the select
+   */
+  onChange: func.isRequired,
+  // ==============
+  // Content Props
+  // ==============
+  /**
+   * Current selected value(s) - string for single select, array for multiple
+   * Controls the select input (controlled component)
+   */
+  value: oneOfType([string, number, arrayOf(string)]),
+  /**
+   * Array of options for the select dropdown
+   * Can be strings, objects with {value, label}, or React elements
+   * @example
+   * // String array
+   * ['Option 1', 'Option 2']
+   *
+   * // Object array (recommended)
+   * [
+   *   { value: 'us', label: 'United States' },
+   *   { value: 'ca', label: 'Canada', disabled: true }
+   * ]
+   */
+  options: arrayOf(oneOfType([string, shape({
+    value: oneOfType([string, number]).isRequired,
+    label: string,
+    disabled: bool
+  }), element])),
+  /**
+   * Placeholder text shown when no option is selected
+   * Not applicable for multiple selects
+   */
+  placeholder: string,
+  /**
+   * Additional help text displayed below the label
+   * Provides context or instructions for the user
+   */
+  helpText: string,
+  // =============
+  // Layout Props
+  // =============
+  /**
+   * Whether to hide the label visually (but keep it for screen readers)
+   * Use when layout constraints require hidden labels
+   */
+  hideLabel: bool,
+  /**
+   * Whether multiple options can be selected
+   * Changes the select behavior and value type
+   */
+  multiple: bool,
+  /**
+   * Number of visible options (for multiple selects)
+   * Controls the height of the select box
+   */
+  size: number,
+  // ==================
+  // Validation Props
+  // ==================
+  /**
+   * Whether selection is required for form validation
+   * Adds visual indicator and accessibility attributes
+   */
+  required: bool,
+  /**
+   * Whether the select is in an error state
+   * Shows error styling and sets aria-invalid
+   */
+  error: bool,
+  /**
+   * Error message to display when error is true
+   * Announced by screen readers for accessibility
+   */
+  errorText: string,
+  /**
+   * Whether the select is disabled
+   * Prevents user interaction and excludes from form submission
+   */
+  disabled: bool,
+  // ====================
+  // Accessibility Props
+  // ====================
+  /**
+   * Unique identifier for the select element
+   * Generated automatically if not provided
+   */
+  id: string,
+  /**
+   * Accessible label for screen readers when hideLabel is true
+   * Should be provided when label is hidden visually
+   */
+  ariaLabel: string,
+  /**
+   * Space-separated IDs of elements that describe this select
+   * Used for additional context or instructions
+   */
+  ariaDescribedBy: string,
+  /**
+   * Explicitly set aria-required (usually handled by required prop)
+   * Override for custom validation scenarios
+   */
+  ariaRequired: bool,
+  /**
+   * Tab order position for keyboard navigation
+   * Usually managed automatically by DOM order
+   */
+  tabIndex: number,
+  // ================
+  // Event Handlers
+  // ================
+  /**
+   * Function called when select receives focus
+   * @param {Event} event - The focus event
+   */
+  onFocus: func,
+  /**
+   * Function called when select loses focus
+   * @param {Event} event - The blur event
+   */
+  onBlur: func,
+  /**
+   * Function called on keydown events
+   * @param {KeyboardEvent} event - The keyboard event
+   */
+  onKeyDown: func,
+  // ==============
+  // Styling Props
+  // ==============
+  /**
+   * Additional CSS classes to apply to the wrapper
+   * Merged with default component classes
+   */
+  className: string,
+  /**
+   * Inline styles for the select element
+   * Use sparingly - prefer CSS classes
+   */
+  style: object,
+  // ==============
+  // Testing Props
+  // ==============
+  /**
+   * Test ID for automated testing frameworks
+   * Applied as data-testid attribute
+   */
+  'data-testid': string,
+  /**
+   * Cypress test selector
+   * Applied as data-cy attribute
+   */
+  'data-cy': string
+};
+
+// Set display name for better debugging and dev tools
+Select.displayName = 'Select';
+var _default = exports.default = Select;