@12-apps/ui 1.0.0

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

@@ -0,0 +1,82 @@
+import type React from 'react';
+
+/**
+ * A single toggleable filter chip in the palette's filter row (e.g. "Last 7
+ * days", "From me"). App-agnostic: the host owns the ids and what they mean.
+ */
+export interface SearchFilterChip {
+  /** Stable id toggled in {@link SearchPaletteProps.activeFilterIds}. */
+  id: string;
+  /** Chip text. */
+  label: string;
+  /** Optional leading icon node. */
+  icon?: React.ReactNode;
+}
+
+/**
+ * The leading visual of a result row — a product image, a contact avatar, or a
+ * type icon. Mirrors the Gmail-style result list where each row has one lead.
+ */
+export type SearchResultLead =
+  | { kind: 'image'; src: string; alt?: string }
+  | { kind: 'avatar'; src?: string; alt?: string; fallback?: string }
+  | { kind: 'icon'; node: React.ReactNode };
+
+export interface SearchPaletteProps<T> {
+  /** Controlled query string. */
+  value: string;
+  /** Query change (typing). */
+  onChange: (value: string) => void;
+
+  /** Result items to render (already filtered/ranked by the host). */
+  items: T[];
+  /** Stable key extractor. */
+  getKey: (item: T) => string;
+  /** Primary line (the match is bold-highlighted against the query). */
+  getPrimary: (item: T) => string;
+  /** Optional secondary line (e.g. email, SKU, category). */
+  getSecondary?: (item: T) => string | undefined;
+  /** Optional leading visual (image / avatar / icon). */
+  getLead?: (item: T) => SearchResultLead | undefined;
+  /** Optional trailing node (e.g. a date). */
+  getTrailing?: (item: T) => React.ReactNode | undefined;
+  /** Selection handler for a result row. */
+  onSelect: (item: T) => void;
+  /** Max rows shown before the list scrolls / truncates (default 5). */
+  maxItems?: number;
+
+  /** Filter chips row. Omit for no chips. */
+  filters?: SearchFilterChip[];
+  /** Ids of the currently-active chips. */
+  activeFilterIds?: string[];
+  /** Toggle handler for a chip id. */
+  onToggleFilter?: (id: string) => void;
+
+  /** Footer "see all results" action; hidden when omitted. */
+  onSubmitAll?: (query: string) => void;
+  /** Footer label builder; defaults to `Todos os resultados para "{q}"`. */
+  submitAllLabel?: (query: string) => string;
+
+  /**
+   * Content shown when the query is empty (e.g. a "Populares" block). Keeps the
+   * component app-agnostic — the host supplies whatever pre-typing UI it wants.
+   */
+  emptyQueryContent?: React.ReactNode;
+  /** Message when a non-empty query yields no items. */
+  noResultsLabel?: string;
+
+  /** Loading spinner in the input while results resolve. */
+  isLoading?: boolean;
+  /** Inline ghost-text completion of the top result (Tab/→ accepts). */
+  showGhostText?: boolean;
+  /** Autofocus the input on mount. */
+  autoFocus?: boolean;
+  placeholder?: string;
+  inputAriaLabel?: string;
+  /** Esc handler (host closes the overlay). */
+  onClose?: () => void;
+
+  className?: string;
+  /** Test id for the outer card (default `search-palette`). */
+  dataTestId?: string;
+}

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

@@ -0,0 +1,7 @@
+export { SearchPalette } from './SearchPalette';
+export { default } from './SearchPalette';
+export type {
+  SearchFilterChip,
+  SearchPaletteProps,
+  SearchResultLead,
+} from './SearchPalette.types';

package/src/components/form/Select/Select.md

@@ -0,0 +1,254 @@
+# Select Component
+
+A customizable select dropdown component with comprehensive functionality for choosing from a list of options.
+
+## Overview
+
+The Select component provides a dropdown interface for selecting one option from a list. Built on MUI's Select component, it includes enhanced styling, accessibility features, and supports various visual variants including glass and gradient effects.
+
+## Usage
+
+```tsx
+import { Select } from '@procurement/ui';
+
+const options = [
+  { value: 'option1', label: 'Option 1' },
+  { value: 'option2', label: 'Option 2' },
+  { value: 'option3', label: 'Option 3' },
+];
+
+function MyComponent() {
+  return (
+    <Select
+      options={options}
+      label="Select an option"
+      placeholder="Choose one"
+      onValueChange={(value) => console.log('Selected:', value)}
+    />
+  );
+}
+```
+
+## Props
+
+### Required Props
+
+- `options`: Array of option objects with `value`, `label`, and optional `disabled` properties
+
+### Optional Props
+
+- `value`: Currently selected value (controlled)
+- `defaultValue`: Initial value for uncontrolled usage
+- `onValueChange`: Callback function when selection changes
+- `label`: Label text displayed above the select
+- `placeholder`: Placeholder text when no option is selected
+- `helperText`: Helper text displayed below the select
+- `error`: Whether to display error state styling
+- `disabled`: Whether the select is disabled
+- `size`: Size variant ('small' | 'medium')
+- `variant`: Visual style ('default' | 'glass' | 'gradient')
+- `glow`: Whether to show glow effect on hover/focus
+- `pulse`: Whether to show pulse animation
+- `fullWidth`: Whether select should take full width of container
+
+## Visual Variants
+
+### Default
+
+Standard Material-UI select styling with theme colors.
+
+### Glass
+
+Glassmorphism effect with blur backdrop and translucent appearance.
+
+### Gradient
+
+Animated gradient border that changes on hover and focus.
+
+## Accessibility Features
+
+- Full keyboard navigation support (Arrow keys, Enter, Escape)
+- Screen reader compatibility with proper ARIA labels
+- Focus management and visual focus indicators
+- Support for disabled states
+
+## Examples
+
+### Basic Usage
+
+```tsx
+<Select
+  options={[
+    { value: 'us', label: 'United States' },
+    { value: 'ca', label: 'Canada' },
+    { value: 'uk', label: 'United Kingdom' },
+  ]}
+  label="Country"
+  placeholder="Select your country"
+/>
+```
+
+### With Error State
+
+```tsx
+<Select
+  options={options}
+  label="Required Field"
+  placeholder="Please select an option"
+  error={true}
+  helperText="This field is required"
+/>
+```
+
+### Glass Variant with Effects
+
+```tsx
+<Select
+  options={options}
+  label="Glass Select"
+  variant="glass"
+  glow={true}
+  pulse={true}
+  placeholder="Choose an option"
+/>
+```
+
+## Best Practices
+
+- Always provide descriptive labels for accessibility
+- Use helper text to provide additional context
+- Consider using error states for form validation
+- For long lists, consider grouping options or adding search functionality
+- Test keyboard navigation to ensure accessibility compliance
+- Use appropriate size variants based on your layout needs
+
+## Integration Notes
+
+- Works seamlessly with form libraries like React Hook Form
+- Supports controlled and uncontrolled usage patterns
+- Integrates with MUI theme system for consistent styling
+- Compatible with all major browsers and screen readers
+
+## Testing
+
+### Test IDs
+
+The Select component includes `data-testid` attributes for reliable testing:
+
+| Test ID | Element | Description |
+|---------|---------|-------------|
+| `{dataTestId}` | FormControl | Root FormControl wrapper element |
+| `{dataTestId}-select` | Select element | The MUI Select component |
+| `{dataTestId}-option-{value}` | Menu items | Individual option elements (one per option) |
+
+**Default Test IDs (when no dataTestId prop provided):**
+- `select` - The Select element
+- `option-{value}` - Each option element
+
+### Testing Best Practices
+
+**Wait for Select to Render:**
+```typescript
+const select = await canvas.findByTestId('country-select-select');
+expect(select).toBeInTheDocument();
+```
+
+**Test Opening Dropdown:**
+```typescript
+const select = await canvas.findByTestId('select-select');
+await userEvent.click(select);
+
+// Wait for dropdown to open
+await waitFor(() => {
+  const dropdown = document.querySelector('[role="listbox"]');
+  expect(dropdown).toBeInTheDocument();
+});
+```
+
+**Test Selecting Option:**
+```typescript
+const select = await canvas.findByTestId('country-select-select');
+await userEvent.click(select);
+
+// Find and click option
+const option = await canvas.findByTestId('country-select-option-us');
+await userEvent.click(option);
+
+expect(onValueChange).toHaveBeenCalledWith('us');
+expect(select).toHaveTextContent('United States');
+```
+
+**Test with Default Value:**
+```typescript
+const select = await canvas.findByTestId('select-select');
+expect(select).toHaveTextContent('United States'); // Default selection
+```
+
+**Test Disabled State:**
+```typescript
+const select = await canvas.findByTestId('disabled-select-select');
+expect(select).toHaveAttribute('aria-disabled', 'true');
+
+// Clicking should not open dropdown
+await userEvent.click(select);
+const dropdown = document.querySelector('[role="listbox"]');
+expect(dropdown).not.toBeInTheDocument();
+```
+
+**Test Error State:**
+```typescript
+const formControl = await canvas.findByTestId('error-select');
+expect(formControl).toHaveClass('Mui-error');
+
+// Helper text should show error
+const helperText = formControl.querySelector('.MuiFormHelperText-root');
+expect(helperText).toHaveTextContent('This field is required');
+expect(helperText).toHaveClass('Mui-error');
+```
+
+**Test All Options Render:**
+```typescript
+const select = await canvas.findByTestId('select-select');
+await userEvent.click(select);
+
+// Check all options exist
+for (const option of options) {
+  const optionElement = await canvas.findByTestId(`select-option-${option.value}`);
+  expect(optionElement).toBeInTheDocument();
+  expect(optionElement).toHaveTextContent(option.label);
+}
+```
+
+**Test Keyboard Navigation:**
+```typescript
+const select = await canvas.findByTestId('select-select');
+select.focus();
+
+// Open with Space or Enter
+await userEvent.keyboard('{Space}');
+await waitFor(() => {
+  expect(document.querySelector('[role="listbox"]')).toBeInTheDocument();
+});
+
+// Navigate with arrow keys
+await userEvent.keyboard('{ArrowDown}');
+await userEvent.keyboard('{Enter}');
+
+expect(onValueChange).toHaveBeenCalled();
+```
+
+### Common Test Scenarios
+
+1. **Basic Rendering** - Verify select renders with label and options
+2. **Option Selection** - Test clicking options and value change
+3. **Default Value** - Test initial selected value
+4. **Placeholder** - Verify placeholder shows when no selection
+5. **Disabled State** - Test disabled select and disabled options
+6. **Error State** - Test error styling and helper text
+7. **Variants** - Test default, glass, and gradient styles
+8. **Visual Effects** - Test glow and pulse animations
+9. **Keyboard Navigation** - Test arrow keys and Enter/Space
+10. **Multiple Options** - Test with many options
+11. **Full Width** - Test fullWidth prop behavior
+12. **Accessibility** - Verify ARIA attributes and screen reader support
+13. **Form Integration** - Test with form libraries like React Hook Form

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

@@ -0,0 +1,364 @@
+import { Stack } from '@mui/material';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import { Select } from './Select';
+
+const meta: Meta<typeof Select> = {
+  title: 'Form/Select',
+  component: Select,
+  parameters: {
+    layout: 'centered',
+  },
+  tags: ['autodocs', 'component:Select'],
+  argTypes: {
+    variant: {
+      control: { type: 'select' },
+      options: ['default', 'glass', 'gradient'],
+      description: 'Visual variant of the select component',
+    },
+    size: {
+      control: { type: 'select' },
+      options: ['small', 'medium'],
+      description: 'Size of the select component',
+    },
+    glow: {
+      control: 'boolean',
+      description: 'Whether to show a glow effect',
+    },
+    pulse: {
+      control: 'boolean',
+      description: 'Whether to show a pulse animation',
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+const defaultOptions = [
+  { value: 'option1', label: 'Option 1' },
+  { value: 'option2', label: 'Option 2' },
+  { value: 'option3', label: 'Option 3' },
+  { value: 'option4', label: 'Option 4 (Disabled)', disabled: true },
+];
+
+const countryOptions = [
+  { value: 'us', label: 'United States' },
+  { value: 'ca', label: 'Canada' },
+  { value: 'uk', label: 'United Kingdom' },
+  { value: 'de', label: 'Germany' },
+  { value: 'fr', label: 'France' },
+  { value: 'jp', label: 'Japan' },
+  { value: 'au', label: 'Australia' },
+];
+
+export const Default: Story = {
+  args: {
+    options: defaultOptions,
+    label: 'Select Option',
+    placeholder: 'Choose an option',
+  },
+};
+
+export const WithLabel: Story = {
+  args: {
+    options: countryOptions,
+    label: 'Country',
+    placeholder: 'Select your country',
+    helperText: 'Choose your country of residence',
+  },
+};
+
+export const AllSizes: Story = {
+  render: () => (
+    <Stack spacing={3} sx={{ width: 300 }}>
+      <Select options={defaultOptions} label="Small Select" size="small" placeholder="Small size" />
+      <Select
+        options={defaultOptions}
+        label="Medium Select"
+        size="medium"
+        placeholder="Medium size"
+      />
+    </Stack>
+  ),
+};
+
+export const WithDefaultValue: Story = {
+  args: {
+    options: countryOptions,
+    label: 'Country',
+    defaultValue: 'us',
+    helperText: 'Default value is pre-selected',
+  },
+};
+
+export const ErrorState: Story = {
+  args: {
+    options: defaultOptions,
+    label: 'Required Field',
+    placeholder: 'Please select an option',
+    error: true,
+    helperText: 'This field is required',
+  },
+};
+
+export const WithManyOptions: Story = {
+  args: {
+    options: [
+      { value: 'afghanistan', label: 'Afghanistan' },
+      { value: 'albania', label: 'Albania' },
+      { value: 'algeria', label: 'Algeria' },
+      { value: 'argentina', label: 'Argentina' },
+      { value: 'australia', label: 'Australia' },
+      { value: 'austria', label: 'Austria' },
+      { value: 'bangladesh', label: 'Bangladesh' },
+      { value: 'belgium', label: 'Belgium' },
+      { value: 'brazil', label: 'Brazil' },
+      { value: 'canada', label: 'Canada' },
+      { value: 'china', label: 'China' },
+      { value: 'denmark', label: 'Denmark' },
+      { value: 'egypt', label: 'Egypt' },
+      { value: 'france', label: 'France' },
+      { value: 'germany', label: 'Germany' },
+      { value: 'india', label: 'India' },
+      { value: 'indonesia', label: 'Indonesia' },
+      { value: 'italy', label: 'Italy' },
+      { value: 'japan', label: 'Japan' },
+      { value: 'mexico', label: 'Mexico' },
+      { value: 'netherlands', label: 'Netherlands' },
+      { value: 'norway', label: 'Norway' },
+      { value: 'poland', label: 'Poland' },
+      { value: 'russia', label: 'Russia' },
+      { value: 'spain', label: 'Spain' },
+      { value: 'sweden', label: 'Sweden' },
+      { value: 'switzerland', label: 'Switzerland' },
+      { value: 'turkey', label: 'Turkey' },
+      { value: 'uk', label: 'United Kingdom' },
+      { value: 'us', label: 'United States' },
+    ],
+    label: 'Country',
+    placeholder: 'Select a country',
+    helperText: 'Scroll to see all options',
+  },
+};
+
+export const NoFullWidth: Story = {
+  args: {
+    options: defaultOptions,
+    label: 'Compact Select',
+    fullWidth: false,
+    style: { width: '200px' },
+  },
+};
+
+export const GlassVariant: Story = {
+  args: {
+    options: countryOptions,
+    label: 'Glass Select',
+    variant: 'glass',
+    placeholder: 'Choose an option',
+    helperText: 'Glass variant with blur effect',
+  },
+};
+
+export const GradientVariant: Story = {
+  args: {
+    options: defaultOptions,
+    label: 'Gradient Select',
+    variant: 'gradient',
+    placeholder: 'Choose an option',
+    helperText: 'Gradient variant with colorful border',
+  },
+};
+
+export const AllVariants: Story = {
+  render: () => (
+    <Stack spacing={3} sx={{ width: 400 }}>
+      <Select
+        options={defaultOptions}
+        label="Default Variant"
+        variant="default"
+        placeholder="Default style"
+        helperText="Standard Material-UI select"
+      />
+      <Select
+        options={defaultOptions}
+        label="Glass Variant"
+        variant="glass"
+        placeholder="Glass style"
+        helperText="Glassmorphism effect with blur"
+      />
+      <Select
+        options={defaultOptions}
+        label="Gradient Variant"
+        variant="gradient"
+        placeholder="Gradient style"
+        helperText="Gradient border effect"
+      />
+    </Stack>
+  ),
+};
+
+export const WithGlowEffect: Story = {
+  args: {
+    options: countryOptions,
+    label: 'Glow Select',
+    placeholder: 'Choose with glow',
+    glow: true,
+    helperText: 'Select with glow effect',
+  },
+};
+
+export const WithPulseAnimation: Story = {
+  args: {
+    options: defaultOptions,
+    label: 'Pulse Select',
+    placeholder: 'Choose with pulse',
+    pulse: true,
+    helperText: 'Select with pulse animation',
+  },
+};
+
+export const CombinedEffects: Story = {
+  render: () => (
+    <Stack spacing={3} sx={{ width: 400 }}>
+      <Select
+        options={defaultOptions}
+        label="Glass + Glow"
+        variant="glass"
+        glow={true}
+        placeholder="Glass with glow"
+        helperText="Glass variant with glow effect"
+      />
+      <Select
+        options={defaultOptions}
+        label="Gradient + Pulse"
+        variant="gradient"
+        pulse={true}
+        placeholder="Gradient with pulse"
+        helperText="Gradient variant with pulse animation"
+      />
+      <Select
+        options={countryOptions}
+        label="All Effects"
+        variant="glass"
+        glow={true}
+        pulse={true}
+        placeholder="All effects combined"
+        helperText="Glass with glow and pulse effects"
+      />
+    </Stack>
+  ),
+};
+
+export const AllStates: Story = {
+  render: () => (
+    <Stack spacing={3} sx={{ width: 400 }}>
+      <Select
+        options={defaultOptions}
+        label="Normal State"
+        placeholder="Select an option"
+        helperText="Normal state select"
+      />
+      <Select
+        options={defaultOptions}
+        label="Error State"
+        placeholder="Required field"
+        error={true}
+        helperText="This field is required"
+      />
+      <Select
+        options={defaultOptions}
+        label="Disabled State"
+        placeholder="Cannot interact"
+        disabled={true}
+        helperText="This select is disabled"
+      />
+    </Stack>
+  ),
+};
+
+export const InteractiveStates: Story = {
+  render: () => (
+    <Stack spacing={3} sx={{ width: 400 }}>
+      <Select
+        options={defaultOptions}
+        label="Default Interaction"
+        placeholder="Click to open"
+        helperText="Hover and click to interact"
+      />
+      <Select
+        options={defaultOptions}
+        label="With Glow Effect"
+        placeholder="Hover for glow"
+        glow={true}
+        helperText="Hover to see glow effect"
+      />
+      <Select
+        options={defaultOptions}
+        label="With Pulse Animation"
+        placeholder="Watch the pulse"
+        pulse={true}
+        helperText="Pulse animation on focus"
+      />
+    </Stack>
+  ),
+};
+
+export const DisabledState: Story = {
+  args: {
+    options: defaultOptions,
+    label: 'Disabled Select',
+    placeholder: 'Cannot interact',
+    disabled: true,
+    helperText: 'This select is disabled',
+  },
+};
+
+export const Responsive: Story = {
+  render: () => (
+    <Stack spacing={3}>
+      <div style={{ width: '100%', maxWidth: '480px' }}>
+        <Select
+          options={countryOptions}
+          label="Mobile View (480px)"
+          placeholder="Select country"
+          fullWidth={true}
+          helperText="Full width on mobile"
+        />
+      </div>
+      <div style={{ width: '300px' }}>
+        <Select
+          options={defaultOptions}
+          label="Tablet View (300px)"
+          placeholder="Fixed width"
+          helperText="Fixed width for tablets"
+        />
+      </div>
+      <div style={{ width: '200px' }}>
+        <Select
+          options={defaultOptions}
+          label="Compact View (200px)"
+          placeholder="Compact"
+          size="small"
+          helperText="Compact for small screens"
+        />
+      </div>
+    </Stack>
+  ),
+};
+
+export const Playground: Story = {
+  args: {
+    options: countryOptions,
+    label: 'Playground Select',
+    placeholder: 'Choose an option',
+    variant: 'default',
+    size: 'medium',
+    fullWidth: true,
+    error: false,
+    glow: false,
+    pulse: false,
+    helperText: 'This is a playground select component',
+  },
+};