@12-apps/ui 1.0.0

package/src/components/form/CreatableSelect/CreatableSelect.md

@@ -0,0 +1,114 @@
+# CreatableSelect Component
+
+A single-select, searchable combobox that can create a brand-new option inline.
+Type to filter the options; when the typed text matches nothing, an optional
+"create" row lets the user add it on Enter. Built on MUI `Autocomplete` +
+`TextField`, so it matches the height and theming of the other form fields.
+
+## Purpose and Use Cases
+
+- Pick-or-create pickers: category, tag, brand, supplier — anywhere the list of
+  valid values grows as users type new ones.
+- A searchable replacement for `Select` when the option list is long.
+- Any field where "not in the list yet? just type it and press Enter" is the
+  desired UX.
+
+## Props Documentation
+
+- **options** (`CreatableSelectOption[]`): available options, each `{ value, label }`.
+- **value** (`string | null`): the selected option's `value` (`null`/`""` = none).
+- **onChange** (`(value: string | null) => void`): fired with the chosen `value`, or `null` when cleared.
+- **onCreate** (`(label: string) => void | Promise<void>`): enables create-on-Enter. When the typed text matches no option, a create row appears; choosing it calls `onCreate` with the raw text. The parent persists it and feeds the new option back through `options`/`value`. Omit to make the field a plain searchable select.
+- **label** (`string`): field label.
+- **placeholder** (`string`): placeholder shown when empty.
+- **createOptionLabel** (`(input: string) => string`): builds the create-row label (default: `Criar "<input>"`).
+- **noOptionsText** (`string`): text shown when nothing matches and creation is disabled.
+- **disabled** (`boolean`): disable the field.
+- **loading** (`boolean`): show a spinner in the adornment (e.g. while a create request is in flight).
+- **fullWidth** (`boolean`): stretch to the container width (default: `true`).
+- **dataTestId** (`string`): base test id; the input is `<dataTestId>-input` (default: `creatable-select`).
+
+## Usage Examples
+
+### Searchable select (no create)
+
+```tsx
+<CreatableSelect
+  label="Categoria"
+  options={categories}
+  value={categoryId}
+  onChange={setCategoryId}
+/>
+```
+
+### Pick-or-create
+
+```tsx
+<CreatableSelect
+  label="Categoria"
+  options={categories}
+  value={categoryId}
+  loading={creating}
+  onChange={setCategoryId}
+  onCreate={async (name) => {
+    const created = await createCategory(name); // persist server-side
+    setCategories((prev) => [...prev, created]); // feed the new option back
+    setCategoryId(created.value);                // select it
+  }}
+/>
+```
+
+## Accessibility Notes
+
+- Inherits MUI `Autocomplete` roles (`combobox`, `listbox`, `option`) and keyboard
+  support: arrow keys to move, Enter to select (including the create row), Escape
+  to close, Home/End to jump.
+- The label is associated with the input via MUI `TextField`.
+- `loading` surfaces a spinner without blocking keyboard interaction.
+
+## Best Practices
+
+1. Keep `options` in sync after `onCreate` resolves — append the created option and
+   set `value` to it so the new selection sticks.
+2. Use `loading` while the create request is in flight to signal progress.
+3. Provide a localized `createOptionLabel` when the UI language isn't Portuguese.
+4. Omit `onCreate` entirely when free creation is not allowed — the field then
+   behaves as a plain searchable select and shows `noOptionsText`.
+
+## Testing
+
+### Test IDs
+
+- `<dataTestId>` (default `creatable-select`) — the Autocomplete root.
+- `<dataTestId>-input` — the text input, for typing queries.
+
+### Example
+
+```tsx
+import { render, screen, fireEvent } from '@testing-library/react';
+import { CreatableSelect } from './CreatableSelect';
+
+test('creates a new option on Enter', () => {
+  const onCreate = vi.fn();
+  render(
+    <CreatableSelect
+      options={[{ value: '1', label: 'Bebidas' }]}
+      value={null}
+      onChange={vi.fn()}
+      onCreate={onCreate}
+      dataTestId="cat"
+    />,
+  );
+  const input = screen.getByTestId('cat-input');
+  fireEvent.change(input, { target: { value: 'Sobremesas' } });
+  fireEvent.keyDown(input, { key: 'ArrowDown' });
+  fireEvent.keyDown(input, { key: 'Enter' });
+  expect(onCreate).toHaveBeenCalledWith('Sobremesas');
+});
+```
+
+## Related Components
+
+- **Select**: fixed-option single/multiple select (no inline create).
+- **Autocomplete**: free-text suggestion input with ghost-text completion.
+- **AddressAutocomplete**: address-specific autocomplete backed by Google Places.

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

@@ -0,0 +1,112 @@
+import { Box } from '@mui/material';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { useState } from 'react';
+
+import { CreatableSelect } from './CreatableSelect';
+import type { CreatableSelectOption } from './CreatableSelect.types';
+
+const meta: Meta<typeof CreatableSelect> = {
+  title: 'Form/CreatableSelect',
+  component: CreatableSelect,
+  parameters: {
+    layout: 'centered',
+    docs: {
+      description: {
+        component:
+          'A single-select, searchable combobox that can create a new option inline (create-on-Enter).',
+      },
+    },
+  },
+  tags: ['autodocs', 'component:CreatableSelect'],
+  argTypes: {
+    label: { control: 'text' },
+    placeholder: { control: 'text' },
+    disabled: { control: 'boolean' },
+    loading: { control: 'boolean' },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+const BASE_OPTIONS: CreatableSelectOption[] = [
+  { value: 'drinks', label: 'Bebidas' },
+  { value: 'food', label: 'Comidas' },
+  { value: 'desserts', label: 'Sobremesas' },
+];
+
+/** Plain searchable select — no `onCreate`, so typing an unknown value offers no create row. */
+export const SearchableSelect: Story = {
+  render: (args) => {
+    const [value, setValue] = useState<string | null>(null);
+    return (
+      <Box sx={{ width: 360 }}>
+        <CreatableSelect {...args} options={BASE_OPTIONS} value={value} onChange={setValue} />
+      </Box>
+    );
+  },
+  args: { label: 'Categoria', placeholder: 'Selecione…' },
+};
+
+/** Pick-or-create: an unknown query shows a "Criar …" row; choosing it appends + selects it. */
+export const Creatable: Story = {
+  render: (args) => {
+    const [options, setOptions] = useState<CreatableSelectOption[]>(BASE_OPTIONS);
+    const [value, setValue] = useState<string | null>(null);
+    return (
+      <Box sx={{ width: 360 }}>
+        <CreatableSelect
+          {...args}
+          options={options}
+          value={value}
+          onChange={setValue}
+          onCreate={(label) => {
+            const created = { value: label.toLowerCase(), label };
+            setOptions((prev) => [...prev, created]);
+            setValue(created.value);
+          }}
+        />
+      </Box>
+    );
+  },
+  args: { label: 'Categoria', placeholder: 'Buscar ou criar…' },
+};
+
+/** Preselected value. */
+export const WithValue: Story = {
+  render: (args) => {
+    const [value, setValue] = useState<string | null>('food');
+    return (
+      <Box sx={{ width: 360 }}>
+        <CreatableSelect {...args} options={BASE_OPTIONS} value={value} onChange={setValue} />
+      </Box>
+    );
+  },
+  args: { label: 'Categoria' },
+};
+
+/** Loading state (e.g. while a create request is in flight). */
+export const Loading: Story = {
+  render: (args) => {
+    const [value, setValue] = useState<string | null>(null);
+    return (
+      <Box sx={{ width: 360 }}>
+        <CreatableSelect {...args} options={BASE_OPTIONS} value={value} onChange={setValue} />
+      </Box>
+    );
+  },
+  args: { label: 'Categoria', loading: true },
+};
+
+/** Disabled state. */
+export const Disabled: Story = {
+  render: (args) => {
+    const [value, setValue] = useState<string | null>('drinks');
+    return (
+      <Box sx={{ width: 360 }}>
+        <CreatableSelect {...args} options={BASE_OPTIONS} value={value} onChange={setValue} />
+      </Box>
+    );
+  },
+  args: { label: 'Categoria', disabled: true },
+};

package/src/components/form/CreatableSelect/CreatableSelect.test.stories.tsx

@@ -0,0 +1,134 @@
+import { Box } from '@mui/material';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { useState } from 'react';
+import { expect, fn, userEvent, waitFor, within } from 'storybook/test';
+
+import { CreatableSelect } from './CreatableSelect';
+import type { CreatableSelectOption } from './CreatableSelect.types';
+
+const meta: Meta<typeof CreatableSelect> = {
+  title: 'Form/CreatableSelect/Tests',
+  component: CreatableSelect,
+  parameters: {
+    layout: 'centered',
+    chromatic: { disableSnapshot: false },
+  },
+  tags: ['autodocs', 'test', 'component:CreatableSelect'],
+};
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+const OPTIONS: CreatableSelectOption[] = [
+  { value: 'drinks', label: 'Bebidas' },
+  { value: 'food', label: 'Comidas' },
+  { value: 'desserts', label: 'Sobremesas' },
+];
+
+// ==================== INTERACTION TESTS ====================
+
+export const SelectsAnExistingOption: Story = {
+  name: '🧪 Selects an existing option',
+  args: {
+    options: OPTIONS,
+    value: null,
+    onChange: fn(),
+    label: 'Categoria',
+    dataTestId: 'cat',
+  },
+  play: async ({ canvasElement, args, step }) => {
+    const canvas = within(canvasElement);
+
+    await step('Type a query that matches an option and pick it', async () => {
+      const input = canvas.getByTestId('cat-input');
+      await userEvent.click(input);
+      await userEvent.type(input, 'Beb');
+      await waitFor(() => expect(canvas.getByText('Bebidas')).toBeInTheDocument());
+      await userEvent.click(canvas.getByText('Bebidas'));
+      await waitFor(() => expect(args.onChange).toHaveBeenCalledWith('drinks'));
+    });
+  },
+};
+
+export const CreatesANewOptionOnEnter: Story = {
+  name: '🧪 Creates a new option on Enter',
+  args: {
+    options: OPTIONS,
+    value: null,
+    onChange: fn(),
+    onCreate: fn(),
+    label: 'Categoria',
+    dataTestId: 'cat',
+  },
+  play: async ({ canvasElement, args, step }) => {
+    const canvas = within(canvasElement);
+
+    await step('Type an unknown value and press Enter on the create row', async () => {
+      const input = canvas.getByTestId('cat-input');
+      await userEvent.click(input);
+      await userEvent.type(input, 'Lanches');
+      await waitFor(() => expect(canvas.getByText('Criar "Lanches"')).toBeInTheDocument());
+      await userEvent.keyboard('{ArrowDown}{Enter}');
+      await waitFor(() => expect(args.onCreate).toHaveBeenCalledWith('Lanches'));
+    });
+  },
+};
+
+export const NoCreateRowWhenOnCreateOmitted: Story = {
+  name: '🧪 No create row without onCreate',
+  args: {
+    options: OPTIONS,
+    value: null,
+    onChange: fn(),
+    label: 'Categoria',
+    noOptionsText: 'Nada encontrado',
+    dataTestId: 'cat',
+  },
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+
+    await step('An unknown query shows no-options, not a create row', async () => {
+      const input = canvas.getByTestId('cat-input');
+      await userEvent.click(input);
+      await userEvent.type(input, 'Zzz');
+      await waitFor(() => expect(canvas.getByText('Nada encontrado')).toBeInTheDocument());
+      expect(canvas.queryByText(/^Criar /)).not.toBeInTheDocument();
+    });
+  },
+};
+
+export const ControlledValueRoundTrips: Story = {
+  name: '🧪 Controlled value round-trips',
+  render: (args) => {
+    const [options, setOptions] = useState<CreatableSelectOption[]>(OPTIONS);
+    const [value, setValue] = useState<string | null>(null);
+    return (
+      <Box sx={{ width: 320 }}>
+        <CreatableSelect
+          {...args}
+          options={options}
+          value={value}
+          onChange={setValue}
+          onCreate={(label) => {
+            const created = { value: label.toLowerCase(), label };
+            setOptions((prev) => [...prev, created]);
+            setValue(created.value);
+          }}
+          dataTestId="cat"
+        />
+      </Box>
+    );
+  },
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+
+    await step('Create a value and confirm it becomes the selected input', async () => {
+      const input = canvas.getByTestId('cat-input') as HTMLInputElement;
+      await userEvent.click(input);
+      await userEvent.type(input, 'Combos');
+      await waitFor(() => expect(canvas.getByText('Criar "Combos"')).toBeInTheDocument());
+      await userEvent.keyboard('{ArrowDown}{Enter}');
+      await waitFor(() => expect(input.value).toBe('Combos'));
+    });
+  },
+};

package/src/components/form/CreatableSelect/CreatableSelect.tsx

@@ -0,0 +1,149 @@
+'use client';
+
+import { alpha } from '@mui/material';
+import Autocomplete, { createFilterOptions } from '@mui/material/Autocomplete';
+import CircularProgress from '@mui/material/CircularProgress';
+import TextField from '@mui/material/TextField';
+import { useId, useMemo } from 'react';
+
+import { FormControl, FormLabel, FormMessage } from '../Form';
+import type { CreatableSelectOption, CreatableSelectProps } from './CreatableSelect.types';
+
+/** Internal option shape: a real option, or the synthetic "create new" row. */
+interface InternalOption extends CreatableSelectOption {
+  /** True for the synthetic row that triggers {@link CreatableSelectProps.onCreate}. */
+  isCreate?: boolean;
+}
+
+/** Prefix that marks a synthetic create-row value so it can never collide with a real one. */
+const CREATE_PREFIX = ' create:';
+
+const filterOptions = createFilterOptions<InternalOption>();
+
+/**
+ * A single-select, searchable combobox that can create a new option on the fly.
+ *
+ * Type to filter {@link CreatableSelectProps.options}; when the typed text matches
+ * no option and {@link CreatableSelectProps.onCreate} is provided, a "create" row
+ * appears and selecting it (Enter or click) calls `onCreate` with the raw text —
+ * the parent persists it, then feeds the new option back via `options`/`value`.
+ *
+ * Chrome matches the library's other form fields: an external {@link FormLabel}
+ * above the control (not a floating label) and the same outlined border treatment
+ * as {@link Input}, so it lines up with sibling fields in a grid row.
+ */
+export function CreatableSelect({
+  options,
+  value,
+  onChange,
+  onCreate,
+  label,
+  error,
+  placeholder,
+  createOptionLabel = (input) => `Criar "${input}"`,
+  noOptionsText,
+  disabled = false,
+  loading = false,
+  fullWidth = true,
+  dataTestId = 'creatable-select',
+}: CreatableSelectProps): React.JSX.Element {
+  const inputId = useId();
+
+  const items = useMemo<InternalOption[]>(
+    () => options.map((option) => ({ value: option.value, label: option.label })),
+    [options],
+  );
+
+  // MUI holds the selected *option object*; derive it from the controlled value.
+  const selected = useMemo<InternalOption | null>(
+    () => items.find((option) => option.value === value) ?? null,
+    [items, value],
+  );
+
+  return (
+    <FormControl fullWidth={fullWidth} error={Boolean(error)}>
+      {label && (
+        <FormLabel htmlFor={inputId} error={Boolean(error)}>
+          {label}
+        </FormLabel>
+      )}
+      <Autocomplete<InternalOption, false, false, false>
+        value={selected}
+        options={items}
+        disabled={disabled}
+        loading={loading}
+        fullWidth={fullWidth}
+        handleHomeEndKeys
+        selectOnFocus
+        clearOnBlur
+        data-testid={dataTestId}
+        noOptionsText={noOptionsText}
+        // Lift the dropdown above stacked modals: the default popup z-index is
+        // `modal` (1300), but a stacked sheet at depth ≥2 sits at 1300 + depth*10,
+        // which would otherwise cover the options. +100 clears ~10 stack levels.
+        slotProps={{ popper: { sx: { zIndex: (theme) => theme.zIndex.modal + 100 } } }}
+        getOptionLabel={(option) => (typeof option === 'string' ? option : option.label)}
+        isOptionEqualToValue={(option, current) => option.value === current.value}
+        filterOptions={(available, params) => {
+          const filtered = filterOptions(available, params);
+          const input = params.inputValue.trim();
+          const alreadyExists = available.some(
+            (option) => option.label.toLowerCase() === input.toLowerCase(),
+          );
+          if (input && !alreadyExists && onCreate) {
+            filtered.push({
+              value: `${CREATE_PREFIX}${input}`,
+              label: createOptionLabel(input),
+              isCreate: true,
+            });
+          }
+          return filtered;
+        }}
+        onChange={(_event, next) => {
+          if (!next) {
+            onChange(null);
+            return;
+          }
+          if (next.isCreate) {
+            void onCreate?.(next.value.slice(CREATE_PREFIX.length));
+            return;
+          }
+          onChange(next.value);
+        }}
+        renderInput={(params) => (
+          <TextField
+            {...params}
+            id={inputId}
+            placeholder={placeholder}
+            error={Boolean(error)}
+            // Match the outlined border treatment of the `Input` component so the
+            // field is visually identical to its siblings.
+            sx={{
+              '& .MuiOutlinedInput-root': {
+                '& fieldset': {
+                  borderColor: (theme) => alpha(theme.palette.divider, 0.23),
+                },
+                '&:hover fieldset': { borderColor: 'primary.main' },
+                '&.Mui-focused fieldset': { borderColor: 'primary.main', borderWidth: 2 },
+                '&.Mui-error fieldset': { borderColor: 'error.main' },
+              },
+            }}
+            inputProps={{ ...params.inputProps, 'data-testid': `${dataTestId}-input` }}
+            slotProps={{
+              input: {
+                ...params.InputProps,
+                endAdornment: (
+                  <>
+                    {loading ? <CircularProgress color="inherit" size={18} /> : null}
+                    {params.InputProps.endAdornment}
+                  </>
+                ),
+              },
+            }}
+          />
+        )}
+      />
+      {error && <FormMessage error dataTestId={`${dataTestId}-message`}>{error}</FormMessage>}
+    </FormControl>
+  );
+}

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

@@ -0,0 +1,37 @@
+/** One selectable option: a stable `value` and its human `label`. */
+export interface CreatableSelectOption {
+  value: string;
+  label: string;
+}
+
+export interface CreatableSelectProps {
+  /** The available options to search/select. */
+  options: CreatableSelectOption[];
+  /** The selected option's `value`, or `null`/`""` when nothing is selected. */
+  value: string | null;
+  /** Fired with the chosen option's `value`, or `null` when cleared. */
+  onChange: (value: string | null) => void;
+  /**
+   * Enables "create on Enter": when the typed text matches no option and this is
+   * provided, a "create" row appears and choosing it (Enter) calls `onCreate`
+   * with the raw typed label. Omit to make the field a plain searchable select.
+   */
+  onCreate?: (label: string) => void | Promise<void>;
+  /** Field label, rendered above the control (matching the other form fields). */
+  label?: string;
+  /** Validation error message; also flags the label/border as errored. */
+  error?: string;
+  /** Placeholder shown when empty. */
+  placeholder?: string;
+  /** Builds the create-row label from the typed text (default: `Criar "<text>"`). */
+  createOptionLabel?: (input: string) => string;
+  /** Text shown when no option matches and creation is disabled. */
+  noOptionsText?: string;
+  disabled?: boolean;
+  /** Shows a spinner in the adornment (e.g. while a create request is in flight). */
+  loading?: boolean;
+  /** Stretch to the container width (default: true). */
+  fullWidth?: boolean;
+  /** Base test id; the input is `<dataTestId>-input`. */
+  dataTestId?: string;
+}

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

@@ -0,0 +1,2 @@
+export { CreatableSelect } from './CreatableSelect';
+export type { CreatableSelectOption, CreatableSelectProps } from './CreatableSelect.types';