@12-apps/ui 1.0.0

package/src/components/form/Select/Select.tsx

@@ -0,0 +1,239 @@
+import {
+  alpha,
+  type CSSObject,
+  FormControl,
+  FormHelperText,
+  InputLabel,
+  keyframes,
+  MenuItem,
+  Select as MuiSelect,
+  styled,
+  type Theme,
+} from '@mui/material';
+import React from 'react';
+
+import type { SelectProps } from './Select.types';
+
+// Define pulse animation
+const pulseAnimation = keyframes`
+  0% {
+    box-shadow: 0 0 0 0 currentColor;
+    opacity: 1;
+  }
+  70% {
+    box-shadow: 0 0 0 10px currentColor;
+    opacity: 0;
+  }
+  100% {
+    box-shadow: 0 0 0 0 currentColor;
+    opacity: 0;
+  }
+`;
+
+/** Glow ring on the outlined input, keyed off the `glow` prop. */
+const glowStyles = (theme: Theme): CSSObject => ({
+  '& .MuiOutlinedInput-root': {
+    boxShadow: `0 0 15px ${alpha(theme.palette.primary.main, 0.3)}`,
+    '&.Mui-focused': {
+      boxShadow: `0 0 20px ${alpha(theme.palette.primary.main, 0.5)}`,
+    },
+  },
+});
+
+/** Pulsing halo behind the control, keyed off the `pulse` prop. */
+const pulseStyles = (theme: Theme): CSSObject => ({
+  '&::after': {
+    content: '""',
+    position: 'absolute',
+    top: '50%',
+    left: '0',
+    right: '0',
+    height: '56px',
+    transform: 'translateY(-50%)',
+    borderRadius: theme.spacing(0.5),
+    backgroundColor: theme.palette.primary.main,
+    opacity: 0.3,
+    animation: `${pulseAnimation} 2s infinite`,
+    pointerEvents: 'none',
+    zIndex: -1,
+  },
+});
+
+/** `glass` variant: translucent, blurred background. */
+const glassVariant = (theme: Theme): CSSObject => ({
+  backgroundColor: alpha(theme.palette.background.paper, 0.1),
+  backdropFilter: 'blur(20px)',
+  border: `1px solid ${alpha(theme.palette.divider, 0.2)}`,
+  '& fieldset': { border: 'none' },
+  '&:hover': {
+    backgroundColor: alpha(theme.palette.background.paper, 0.15),
+    borderColor: alpha(theme.palette.primary.main, 0.3),
+  },
+  '&.Mui-focused': {
+    backgroundColor: alpha(theme.palette.background.paper, 0.2),
+    borderColor: theme.palette.primary.main,
+    boxShadow: `0 0 0 2px ${alpha(theme.palette.primary.main, 0.1)}`,
+  },
+});
+
+/** `gradient` variant: gradient fill with a masked gradient border. */
+const gradientVariant = (theme: Theme): CSSObject => ({
+  background: `linear-gradient(135deg, ${alpha(theme.palette.primary.main, 0.1)}, ${alpha(theme.palette.secondary.main, 0.1)})`,
+  border: `2px solid transparent`,
+  backgroundOrigin: 'border-box',
+  backgroundClip: 'padding-box, border-box',
+  position: 'relative',
+  '& fieldset': { border: 'none' },
+  '&::before': {
+    content: '""',
+    position: 'absolute',
+    top: 0,
+    left: 0,
+    right: 0,
+    bottom: 0,
+    borderRadius: 'inherit',
+    background: `linear-gradient(135deg, ${theme.palette.primary.main}, ${theme.palette.secondary.main})`,
+    mask: 'linear-gradient(#fff 0 0) content-box, linear-gradient(#fff 0 0)',
+    maskComposite: 'exclude',
+    padding: '2px',
+    zIndex: -1,
+  },
+  '&:hover': {
+    background: `linear-gradient(135deg, ${alpha(theme.palette.primary.main, 0.15)}, ${alpha(theme.palette.secondary.main, 0.15)})`,
+  },
+  '&.Mui-focused': {
+    background: `linear-gradient(135deg, ${alpha(theme.palette.primary.main, 0.2)}, ${alpha(theme.palette.secondary.main, 0.2)})`,
+    '&::before': {
+      background: `linear-gradient(135deg, ${theme.palette.primary.dark}, ${theme.palette.secondary.dark})`,
+    },
+  },
+});
+
+/** `default` variant: standard outlined borders with hover/focus/error states. */
+const defaultVariant = (theme: Theme): CSSObject => ({
+  '& fieldset': { borderColor: alpha(theme.palette.divider, 0.23) },
+  '&:hover fieldset': { borderColor: theme.palette.primary.main },
+  '&.Mui-focused fieldset': { borderColor: theme.palette.primary.main, borderWidth: 2 },
+  '&.Mui-error fieldset': { borderColor: theme.palette.error.main },
+});
+
+/** Pick the variant style block for the outlined input. */
+const variantStyles = (theme: Theme, variant: SelectProps['variant']): CSSObject => {
+  if (variant === 'glass') return glassVariant(theme);
+  if (variant === 'gradient') return gradientVariant(theme);
+  return defaultVariant(theme);
+};
+
+const StyledFormControl = styled(FormControl, {
+  shouldForwardProp: (prop) => prop !== 'customVariant' && prop !== 'glow' && prop !== 'pulse',
+})<{
+  customVariant?: SelectProps['variant'];
+  glow?: boolean;
+  pulse?: boolean;
+}>(({ theme, customVariant, glow, pulse }) => ({
+  position: 'relative',
+  ...(glow ? glowStyles(theme) : {}),
+  ...(pulse ? pulseStyles(theme) : {}),
+  '& .MuiOutlinedInput-root': {
+    transition: 'all 0.3s ease',
+    ...variantStyles(theme, customVariant),
+  },
+}));
+
+/**
+ * Build the placeholder item plus one MenuItem per option. Returns a flat ARRAY
+ * (not a Fragment): MUI `Select` enumerates its children with `React.Children`,
+ * which does not descend into Fragments — a Fragment would hide every option.
+ */
+function renderMenuItems(
+  options: SelectProps['options'],
+  placeholder: string | undefined,
+  dataTestId: string | undefined,
+): React.ReactNode[] {
+  const optionTestId = (value: string | number): string =>
+    dataTestId ? `${dataTestId}-option-${value}` : `option-${value}`;
+  const items = options.map((option) => (
+    <MenuItem
+      key={option.value}
+      value={option.value}
+      disabled={option.disabled}
+      data-testid={optionTestId(option.value)}
+    >
+      {option.label}
+    </MenuItem>
+  ));
+  if (placeholder) {
+    items.unshift(
+      <MenuItem key="__placeholder__" value="" disabled>
+        {placeholder}
+      </MenuItem>,
+    );
+  }
+  return items;
+}
+
+export const Select = React.forwardRef<HTMLDivElement, SelectProps>(
+  (
+    {
+      // `variant`/`size`/`glow`/`pulse` intentionally have no defaults: undefined
+      // resolves to the default variant, MUI's medium size, and no glow/pulse —
+      // keeping this render function under the complexity budget.
+      variant,
+      options,
+      label,
+      helperText,
+      fullWidth = true,
+      size,
+      error,
+      placeholder,
+      glow,
+      pulse,
+      'data-testid': dataTestId,
+      value,
+      ...props
+    },
+    ref,
+  ) => {
+    const labelId = React.useId();
+    const helperTextId = React.useId();
+    const selectId = React.useId();
+
+    return (
+      <StyledFormControl
+        fullWidth={fullWidth}
+        size={size}
+        error={error}
+        customVariant={variant}
+        glow={glow}
+        pulse={pulse}
+        ref={ref}
+        data-testid={dataTestId}
+      >
+        {label && (
+          <InputLabel id={labelId} htmlFor={selectId}>
+            {label}
+          </InputLabel>
+        )}
+        <MuiSelect
+          id={selectId}
+          labelId={label ? labelId : undefined}
+          label={label}
+          displayEmpty={Boolean(placeholder)}
+          aria-describedby={helperText ? helperTextId : undefined}
+          data-testid={dataTestId ? `${dataTestId}-select` : 'select'}
+          value={value ?? ''}
+          {...props}
+        >
+          {renderMenuItems(options, placeholder, dataTestId)}
+        </MuiSelect>
+        {helperText && (
+          <FormHelperText id={helperTextId} error={error}>
+            {helperText}
+          </FormHelperText>
+        )}
+      </StyledFormControl>
+    );
+  },
+);
+
+Select.displayName = 'Select';

package/src/components/form/Select/Select.types.ts

@@ -0,0 +1,57 @@
+import type { SelectProps as MuiSelectProps } from '@mui/material';
+
+export type SelectVariant = 'default' | 'glass' | 'gradient';
+
+export interface SelectOption {
+  value: string | number;
+  label: string;
+  disabled?: boolean;
+}
+
+export interface SelectProps extends Omit<MuiSelectProps, 'variant'> {
+  /**
+   * Visual variant of the select component
+   * @default 'default'
+   */
+  variant?: SelectVariant;
+  /**
+   * Array of options to display in the select
+   */
+  options: SelectOption[];
+  /**
+   * Label for the select field
+   */
+  label?: string;
+  /**
+   * Helper text to display below the select
+   */
+  helperText?: string;
+  /**
+   * Whether the select should take full width
+   * @default true
+   */
+  fullWidth?: boolean;
+  /**
+   * Size of the select component
+   * @default 'medium'
+   */
+  size?: 'small' | 'medium';
+  /**
+   * Placeholder text when no option is selected
+   */
+  placeholder?: string;
+  /**
+   * Whether to show a glow effect
+   * @default false
+   */
+  glow?: boolean;
+  /**
+   * Whether to show a pulse animation
+   * @default false
+   */
+  pulse?: boolean;
+  /**
+   * Test ID for testing purposes
+   */
+  'data-testid'?: string;
+}

package/src/components/form/Select/index.ts

@@ -0,0 +1,2 @@
+export { Select } from './Select';
+export type { SelectOption, SelectProps, SelectVariant } from './Select.types';

package/src/components/form/Slider/Slider.md

@@ -0,0 +1,326 @@
+# Slider Component
+
+## Overview
+
+The Slider component allows users to select values from a continuous or discrete range by dragging a thumb along a track. It's built on top of MUI's Slider with enhanced theming, glow effects, and comprehensive accessibility features.
+
+## Usage
+
+```tsx
+import { Slider } from '@/components/form/Slider';
+
+// Basic usage
+<Slider value={50} onChange={(e, value) => setValue(value)} />
+
+// Range slider
+<Slider value={[20, 60]} onChange={(e, value) => setRange(value)} />
+
+// With marks
+<Slider value={30} marks step={10} min={0} max={100} />
+
+// Vertical orientation
+<Slider value={50} orientation="vertical" />
+
+// With glow effect
+<Slider value={75} enableGlow />
+```
+
+## Props
+
+| Prop              | Type                                                                    | Default      | Description                      |
+| ----------------- | ----------------------------------------------------------------------- | ------------ | -------------------------------- |
+| value             | number \| number[]                                                      | -            | Current value or range           |
+| onChange          | (event, value) => void                                                  | -            | Callback when value changes      |
+| min               | number                                                                  | 0            | Minimum value                    |
+| max               | number                                                                  | 100          | Maximum value                    |
+| step              | number                                                                  | 1            | Step increment                   |
+| marks             | boolean \| Mark[]                                                       | false        | Show tick marks                  |
+| disabled          | boolean                                                                 | false        | Disable slider interaction       |
+| orientation       | 'horizontal' \| 'vertical'                                              | 'horizontal' | Slider orientation               |
+| valueLabelDisplay | 'on' \| 'auto' \| 'off'                                                 | 'off'        | When to display value label      |
+| valueLabelFormat  | string \| func                                                          | -            | Format value label               |
+| getAriaLabel      | (index) => string                                                       | -            | Aria label for thumbs            |
+| getAriaValueText  | (value, index) => string                                                | -            | Aria value text                  |
+| color             | 'primary' \| 'secondary' \| 'error' \| 'warning' \| 'info' \| 'success' | 'primary'    | Theme color                      |
+| size              | 'small' \| 'medium'                                                     | 'medium'     | Component size                   |
+| track             | 'normal' \| 'inverted' \| false                                         | 'normal'     | Track display mode               |
+| disableSwap       | boolean                                                                 | false        | Disable thumb swap in range mode |
+| enableGlow        | boolean                                                                 | false        | Enable glow effect               |
+| sx                | SxProps                                                                 | -            | Custom MUI styles                |
+
+## Features
+
+### Value Selection
+
+- Single value selection with draggable thumb
+- Range selection with two thumbs
+- Precise value control with step increments
+- Click-to-position on track
+
+### Keyboard Navigation
+
+- **Arrow Keys**: Increase/decrease by step
+- **Page Up/Down**: Large increment/decrement
+- **Home/End**: Jump to min/max
+- **Tab**: Navigate between thumbs in range mode
+
+### Accessibility
+
+- ARIA attributes for screen readers
+- Keyboard-only navigation support
+- Focus indicators
+- Value announcements
+- Custom labels and descriptions
+
+### Visual Features
+
+- Multiple color themes
+- Size variants
+- Glow effects for enhanced visibility
+- Value labels with custom formatting
+- Tick marks with labels
+- Vertical and horizontal orientations
+
+## Examples
+
+### Basic Slider
+
+```tsx
+<Slider value={value} onChange={(e, v) => setValue(v)} min={0} max={100} />
+```
+
+### Range Slider
+
+```tsx
+<Slider value={[20, 80]} onChange={(e, v) => setRange(v)} min={0} max={100} />
+```
+
+### With Custom Marks
+
+```tsx
+const marks = [
+  { value: 0, label: '0°C' },
+  { value: 20, label: '20°C' },
+  { value: 37, label: '37°C' },
+  { value: 100, label: '100°C' },
+];
+
+<Slider value={value} marks={marks} step={null} valueLabelDisplay="auto" />;
+```
+
+### Vertical Slider
+
+```tsx
+<Slider value={value} orientation="vertical" sx={{ height: 300 }} />
+```
+
+### With Glow Effect
+
+```tsx
+<Slider value={value} enableGlow color="primary" />
+```
+
+### Custom Value Label
+
+```tsx
+<Slider value={value} valueLabelDisplay="on" valueLabelFormat={(v) => `${v}%`} />
+```
+
+## Styling
+
+The component accepts MUI's `sx` prop for custom styling:
+
+```tsx
+<Slider
+  sx={{
+    '& .MuiSlider-track': {
+      border: 'none',
+    },
+    '& .MuiSlider-thumb': {
+      width: 24,
+      height: 24,
+      backgroundColor: '#fff',
+      '&:before': {
+        boxShadow: '0 4px 8px rgba(0,0,0,0.4)',
+      },
+    },
+  }}
+/>
+```
+
+## Best Practices
+
+1. **Provide Labels**: Always include aria-label or aria-labelledby for accessibility
+2. **Value Feedback**: Show current value through labels or separate display
+3. **Appropriate Steps**: Choose step values that make sense for your use case
+4. **Range Validation**: Ensure min/max values are appropriate
+5. **Keyboard Support**: Test keyboard navigation thoroughly
+6. **Mobile Touch**: Ensure thumb is large enough for touch interaction
+7. **Color Contrast**: Maintain sufficient contrast for visibility
+
+## Accessibility
+
+The Slider component follows WAI-ARIA authoring practices:
+
+- Uses `role="slider"` for single value
+- Provides `aria-valuenow`, `aria-valuemin`, `aria-valuemax`
+- Supports `aria-label` and `aria-labelledby`
+- Full keyboard navigation support
+- Focus management for range sliders
+- Screen reader announcements for value changes
+
+## Performance Considerations
+
+- The component is optimized for smooth dragging
+- Uses React.memo to prevent unnecessary re-renders
+- Debounced value updates available through controlled mode
+- Efficient event handling for mouse and touch events
+
+## Testing
+
+The Slider component supports comprehensive testing through the `dataTestId` prop. When provided, it automatically generates test identifiers for all interactive elements.
+
+### Test ID Structure
+
+When you pass `dataTestId="my-slider"`, the following test IDs are generated:
+
+| Element | Test ID | Description |
+| --- | --- | --- |
+| Root Container | `my-slider` | Main wrapper containing the entire slider |
+| Slider Component | `my-slider-slider` | The MUI Slider component itself |
+| Track | `my-slider-track` | The filled track showing current value |
+| Thumb | `my-slider-thumb` | The draggable thumb control |
+| Label | `my-slider-label` | The label text (if label prop is provided) |
+| Value Label | `my-slider-value-label` | The displayed value (if showValue is enabled) |
+
+### Testing Examples
+
+#### Basic Component Testing
+
+```tsx
+import { render, screen } from '@testing-library/react';
+import { Slider } from '@/components/form/Slider';
+
+test('renders slider with testId', () => {
+  render(
+    <Slider
+      dataTestId="volume-slider"
+      label="Volume"
+      showValue
+      value={50}
+      onChange={() => {}}
+    />
+  );
+
+  expect(screen.getByTestId('volume-slider')).toBeInTheDocument();
+  expect(screen.getByTestId('volume-slider-label')).toHaveTextContent('Volume');
+  expect(screen.getByTestId('volume-slider-slider')).toBeInTheDocument();
+  expect(screen.getByTestId('volume-slider-track')).toBeInTheDocument();
+  expect(screen.getByTestId('volume-slider-thumb')).toBeInTheDocument();
+});
+```
+
+#### Testing Slider Interaction
+
+```tsx
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { Slider } from '@/components/form/Slider';
+
+test('interacts with slider', async () => {
+  const handleChange = jest.fn();
+
+  render(
+    <Slider
+      dataTestId="brightness-slider"
+      value={50}
+      onChange={handleChange}
+    />
+  );
+
+  const thumb = screen.getByTestId('brightness-slider-thumb');
+  await userEvent.hover(thumb);
+
+  // Verify thumb is accessible
+  expect(thumb).toBeInTheDocument();
+});
+```
+
+#### Testing Range Slider
+
+```tsx
+test('renders range slider with testIds', () => {
+  render(
+    <Slider
+      dataTestId="price-range"
+      label="Price Range"
+      showValue
+      value={[20, 80]}
+      onChange={() => {}}
+      unit="$"
+    />
+  );
+
+  const valueLabel = screen.getByTestId('price-range-value-label');
+  expect(valueLabel).toHaveTextContent('20$ - 80$');
+});
+```
+
+#### Testing in Forms
+
+```tsx
+test('slider works in form context', async () => {
+  const onSubmit = jest.fn();
+
+  render(
+    <form onSubmit={onSubmit}>
+      <Slider
+        dataTestId="form-slider"
+        label="Settings"
+        value={75}
+        onChange={() => {}}
+      />
+      <button type="submit">Submit</button>
+    </form>
+  );
+
+  const slider = screen.getByTestId('form-slider-slider');
+  expect(slider).toBeInTheDocument();
+
+  await userEvent.click(screen.getByText('Submit'));
+  expect(onSubmit).toHaveBeenCalled();
+});
+```
+
+### Accessibility Testing
+
+The slider component includes proper ARIA attributes that work seamlessly with testing:
+
+```tsx
+test('slider has correct accessibility attributes', () => {
+  render(
+    <Slider
+      dataTestId="a11y-slider"
+      value={60}
+      min={0}
+      max={100}
+      aria-label="Volume control"
+    />
+  );
+
+  const slider = screen.getByRole('slider');
+  expect(slider).toHaveAttribute('aria-valuenow', '60');
+  expect(slider).toHaveAttribute('aria-valuemin', '0');
+  expect(slider).toHaveAttribute('aria-valuemax', '100');
+  expect(slider).toHaveAttribute('aria-label', 'Volume control');
+});
+```
+
+### Best Practices for Testing
+
+1. **Always use dataTestId**: Makes tests more maintainable and readable
+2. **Test user interactions**: Focus on how users interact with the slider
+3. **Verify accessibility**: Ensure ARIA attributes are present and correct
+4. **Test edge cases**: Min/max values, disabled states, range sliders
+5. **Test visual states**: Different sizes, colors, and variants
+6. **Integration testing**: Test slider within forms and complex UIs