@12-apps/ui 1.0.0

package/src/components/form/SearchPalette/SearchPalette.parts.tsx

@@ -0,0 +1,358 @@
+import KeyboardReturnIcon from '@mui/icons-material/KeyboardReturn';
+import SearchIcon from '@mui/icons-material/Search';
+import {
+  Avatar,
+  Box,
+  Chip,
+  CircularProgress,
+  InputBase,
+  List,
+  ListItemButton,
+  Paper,
+  Typography,
+} from '@mui/material';
+import React from 'react';
+
+import type { SearchFilterChip, SearchResultLead } from './SearchPalette.types';
+
+/** Bold the first case-insensitive occurrence of `query` within `text`. */
+export function highlight(text: string, query: string): React.ReactNode {
+  const q = query.trim();
+  const at = q ? text.toLowerCase().indexOf(q.toLowerCase()) : -1;
+  if (at < 0) return text;
+  return (
+    <>
+      {text.slice(0, at)}
+      <Box component="span" sx={{ fontWeight: 700 }}>
+        {text.slice(at, at + q.length)}
+      </Box>
+      {text.slice(at + q.length)}
+    </>
+  );
+}
+
+/** The leading visual of a result row (image / avatar / icon). */
+export function Lead({ lead }: { lead: SearchResultLead | undefined }): React.JSX.Element | null {
+  if (!lead) return null;
+  if (lead.kind === 'image') {
+    return (
+      <Box
+        component="img"
+        src={lead.src}
+        alt={lead.alt ?? ''}
+        sx={{ width: 32, height: 32, borderRadius: 1, objectFit: 'cover', flexShrink: 0 }}
+      />
+    );
+  }
+  if (lead.kind === 'avatar') {
+    return (
+      <Avatar src={lead.src} alt={lead.alt ?? ''} sx={{ width: 32, height: 32, fontSize: '0.85rem' }}>
+        {lead.fallback}
+      </Avatar>
+    );
+  }
+  return (
+    <Box sx={{ display: 'flex', width: 32, justifyContent: 'center', flexShrink: 0, color: 'text.secondary' }}>
+      {lead.node}
+    </Box>
+  );
+}
+
+/** Compute the ghost-completion remainder of the top result for `query`. */
+export function ghostRemainder(topPrimary: string | undefined, query: string): string {
+  if (!query || !topPrimary) return '';
+  return topPrimary.toLowerCase().startsWith(query.toLowerCase()) && topPrimary.length > query.length
+    ? topPrimary.slice(query.length)
+    : '';
+}
+
+/** The search input row: leading icon, ghost overlay, the field, and a spinner. */
+export function PaletteInput(props: {
+  value: string;
+  ghost: string;
+  isLoading: boolean;
+  autoFocus: boolean;
+  placeholder: string;
+  inputAriaLabel?: string;
+  hasQuery: boolean;
+  onChange: (v: string) => void;
+  onKeyDown: (e: React.KeyboardEvent) => void;
+}): React.JSX.Element {
+  return (
+    <Box sx={{ display: 'flex', alignItems: 'center', gap: 1.25, px: 2, py: 1.5 }}>
+      <SearchIcon fontSize="small" sx={{ color: 'text.secondary', flexShrink: 0 }} />
+      <Box sx={{ position: 'relative', flex: 1, minWidth: 0 }}>
+        {props.ghost && (
+          <Box
+            aria-hidden
+            sx={{
+              position: 'absolute',
+              inset: 0,
+              display: 'flex',
+              alignItems: 'center',
+              pointerEvents: 'none',
+              whiteSpace: 'pre',
+              overflow: 'hidden',
+              fontSize: '1rem',
+            }}
+          >
+            <Box component="span" sx={{ visibility: 'hidden' }}>
+              {props.value}
+            </Box>
+            <Box component="span" sx={{ color: 'text.secondary', opacity: 0.6 }}>
+              {props.ghost}
+            </Box>
+          </Box>
+        )}
+        <InputBase
+          fullWidth
+          autoFocus={props.autoFocus}
+          value={props.value}
+          onChange={(e) => props.onChange(e.target.value)}
+          onKeyDown={props.onKeyDown}
+          placeholder={props.placeholder}
+          inputProps={{
+            role: 'combobox',
+            'aria-expanded': props.hasQuery,
+            'aria-label': props.inputAriaLabel,
+            'aria-autocomplete': 'list',
+          }}
+          sx={{ fontSize: '1rem' }}
+        />
+      </Box>
+      {props.isLoading && <CircularProgress size={18} sx={{ flexShrink: 0 }} />}
+    </Box>
+  );
+}
+
+/** The toggleable filter-chip row. */
+export function FilterChips(props: {
+  filters: SearchFilterChip[];
+  activeFilterIds: string[];
+  onToggleFilter?: (id: string) => void;
+}): React.JSX.Element {
+  return (
+    <Box
+      data-testid="search-palette-filters"
+      sx={{
+        display: 'flex',
+        flexWrap: 'wrap',
+        gap: 1,
+        px: 2,
+        pb: 1.5,
+        borderBottom: (theme) => `1px solid ${theme.palette.divider}`,
+      }}
+    >
+      {props.filters.map((chip) => {
+        const active = props.activeFilterIds.includes(chip.id);
+        return (
+          <Chip
+            key={chip.id}
+            label={chip.label}
+            icon={chip.icon as React.ReactElement | undefined}
+            onClick={() => props.onToggleFilter?.(chip.id)}
+            variant={active ? 'filled' : 'outlined'}
+            color={active ? 'primary' : 'default'}
+            size="small"
+            aria-pressed={active}
+            data-testid={`search-palette-filter-${chip.id}`}
+            sx={{ borderRadius: 2 }}
+          />
+        );
+      })}
+    </Box>
+  );
+}
+
+/** One rich result row. */
+export function ResultRow(props: {
+  index: number;
+  active: boolean;
+  query: string;
+  lead: SearchResultLead | undefined;
+  primary: string;
+  secondary: string | undefined;
+  trailing: React.ReactNode | undefined;
+  onSelect: () => void;
+  onHover: () => void;
+}): React.JSX.Element {
+  return (
+    <ListItemButton
+      role="option"
+      aria-selected={props.active}
+      selected={props.active}
+      onMouseEnter={props.onHover}
+      onMouseDown={(e) => e.preventDefault()}
+      onClick={props.onSelect}
+      data-testid={`search-palette-result-${props.index}`}
+      sx={{ gap: 1.25, px: 2, py: 1 }}
+    >
+      <Lead lead={props.lead} />
+      <Box sx={{ minWidth: 0, flex: 1 }}>
+        <Typography variant="body2" noWrap sx={{ color: 'text.primary' }}>
+          {highlight(props.primary, props.query)}
+        </Typography>
+        {props.secondary && (
+          <Typography variant="caption" noWrap sx={{ display: 'block', color: 'text.secondary' }}>
+            {props.secondary}
+          </Typography>
+        )}
+      </Box>
+      {props.trailing != null && (
+        <Box sx={{ flexShrink: 0, color: 'text.secondary', fontSize: '0.75rem' }}>{props.trailing}</Box>
+      )}
+    </ListItemButton>
+  );
+}
+
+/** The "see all results — Press ENTER" footer row. */
+export function SubmitAllFooter(props: {
+  label: string;
+  selected: boolean;
+  onSelect: () => void;
+  onHover: () => void;
+}): React.JSX.Element {
+  return (
+    <ListItemButton
+      selected={props.selected}
+      onMouseEnter={props.onHover}
+      onMouseDown={(e) => e.preventDefault()}
+      onClick={props.onSelect}
+      data-testid="search-palette-submit-all"
+      sx={{ gap: 1.25, px: 2, py: 1, borderTop: (theme) => `1px solid ${theme.palette.divider}` }}
+    >
+      <SearchIcon fontSize="small" sx={{ color: 'text.secondary', flexShrink: 0 }} />
+      <Typography variant="body2" sx={{ flex: 1, minWidth: 0 }} noWrap>
+        {props.label}
+      </Typography>
+      <Box sx={{ display: 'flex', alignItems: 'center', gap: 0.5, color: 'text.secondary' }}>
+        <Typography variant="caption">Enter</Typography>
+        <KeyboardReturnIcon sx={{ fontSize: 14 }} />
+      </Box>
+    </ListItemButton>
+  );
+}
+
+/** Resolved view state shared by the body renderer. */
+export interface BodyView<T> {
+  hasQuery: boolean;
+  emptyQueryContent: React.ReactNode;
+  visible: T[];
+  isLoading: boolean;
+  noResultsLabel: string;
+  showFooter: boolean;
+  footerIndex: number;
+  activeIndex: number;
+  trimmed: string;
+  submitAllLabel: (q: string) => string;
+  getKey: (item: T) => string;
+  getPrimary: (item: T) => string;
+  getSecondary?: (item: T) => string | undefined;
+  getLead?: (item: T) => SearchResultLead | undefined;
+  getTrailing?: (item: T) => React.ReactNode | undefined;
+  onSelect: (item: T) => void;
+  onSubmitAll?: (query: string) => void;
+  setActiveIndex: (i: number) => void;
+}
+
+/** The results list (or the empty-query slot / no-results message) + footer. */
+export function PaletteBody<T>(view: BodyView<T>): React.JSX.Element | null {
+  if (!view.hasQuery) {
+    return view.emptyQueryContent ? (
+      <Box data-testid="search-palette-empty-query">{view.emptyQueryContent}</Box>
+    ) : null;
+  }
+  const empty = view.visible.length === 0;
+  return (
+    <>
+      {!empty && (
+        <List dense disablePadding role="listbox" data-testid="search-palette-results">
+          {view.visible.map((item, index) => (
+            <ResultRow
+              key={view.getKey(item)}
+              index={index}
+              active={index === view.activeIndex}
+              query={view.trimmed}
+              lead={view.getLead?.(item)}
+              primary={view.getPrimary(item)}
+              secondary={view.getSecondary?.(item)}
+              trailing={view.getTrailing?.(item)}
+              onSelect={() => view.onSelect(item)}
+              onHover={() => view.setActiveIndex(index)}
+            />
+          ))}
+        </List>
+      )}
+      {empty && !view.isLoading && (
+        <Box sx={{ px: 2, py: 1.5 }} data-testid="search-palette-no-results">
+          <Typography variant="body2" color="text.secondary">
+            {view.noResultsLabel}
+          </Typography>
+        </Box>
+      )}
+      {view.showFooter && (
+        <SubmitAllFooter
+          label={view.submitAllLabel(view.trimmed)}
+          selected={view.activeIndex === view.footerIndex}
+          onSelect={() => view.onSubmitAll?.(view.trimmed)}
+          onHover={() => view.setActiveIndex(view.footerIndex)}
+        />
+      )}
+    </>
+  );
+}
+
+export { Paper };
+
+/** Context for the keydown handler builder. */
+export interface KeyCtx<T> {
+  rowCount: number;
+  activeIndex: number;
+  footerIndex: number;
+  visible: T[];
+  hasQuery: boolean;
+  ghost: string;
+  top: T | undefined;
+  trimmed: string;
+  getPrimary: (item: T) => string;
+  onChange: (v: string) => void;
+  onSelect: (item: T) => void;
+  onSubmitAll?: (query: string) => void;
+  onClose?: () => void;
+  setActiveIndex: React.Dispatch<React.SetStateAction<number>>;
+}
+
+/** Build the input's keydown handler (nav / select / ghost-accept / close). */
+export function createKeyDownHandler<T>(ctx: KeyCtx<T>): (e: React.KeyboardEvent) => void {
+  const move = (delta: number): void =>
+    ctx.setActiveIndex((i) => Math.min(Math.max(i + delta, 0), Math.max(ctx.rowCount - 1, 0)));
+  const commit = (): void => {
+    if (!ctx.hasQuery) return;
+    if (ctx.activeIndex === ctx.footerIndex) {
+      ctx.onSubmitAll?.(ctx.trimmed);
+      return;
+    }
+    const item = ctx.visible[ctx.activeIndex];
+    if (item) ctx.onSelect(item);
+  };
+  // A lookup keeps the handler itself flat (low complexity). Tab/→ is special —
+  // it must only swallow the event when there is a ghost to accept, otherwise
+  // Tab keeps its native focus behavior.
+  const actions: Record<string, (() => void) | undefined> = {
+    ArrowDown: () => move(1),
+    ArrowUp: () => move(-1),
+    Enter: commit,
+    Escape: () => ctx.onClose?.(),
+  };
+  return (e) => {
+    if ((e.key === 'Tab' || e.key === 'ArrowRight') && ctx.ghost && ctx.top) {
+      e.preventDefault();
+      ctx.onChange(ctx.getPrimary(ctx.top));
+      return;
+    }
+    const action = actions[e.key];
+    if (!action) return;
+    e.preventDefault();
+    action();
+  };
+}

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

@@ -0,0 +1,135 @@
+import Inventory2Icon from '@mui/icons-material/Inventory2';
+import { CssBaseline } from '@mui/material';
+import { createTheme, ThemeProvider } from '@mui/material/styles';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { expect, userEvent, waitFor, within } from 'storybook/test';
+import { useState } from 'react';
+
+import { SearchPalette } from './SearchPalette';
+import type { SearchResultLead } from './SearchPalette.types';
+
+interface Item {
+  id: string;
+  name: string;
+  sub?: string;
+  image?: string;
+  date?: string;
+}
+
+const PRODUCTS: Item[] = [
+  { id: 'p1', name: 'Sabão em pó 1kg', sub: 'Limpeza Roupas', date: 'Jul 12' },
+  { id: 'p2', name: 'Sabonete 90g', sub: 'Cuidado Pessoal', date: 'Jul 11' },
+  { id: 'p3', name: 'Detergente 500ml', sub: 'Limpeza Cozinha', date: 'Jul 10' },
+  { id: 'p4', name: 'Sabão líquido 3L', sub: 'Limpeza Roupas', date: 'Jul 9' },
+  { id: 'p5', name: 'Esponja (un)', sub: 'Limpeza Cozinha', date: 'Jul 8' },
+  { id: 'p6', name: 'Escova de dente', sub: 'Cuidado Bucal', date: 'Jul 7' },
+];
+
+const FILTERS = [
+  { id: 'last7', label: 'Últimos 7 dias' },
+  { id: 'mine', label: 'Criados por mim' },
+  { id: 'active', label: 'Ativos' },
+];
+
+const theme = createTheme();
+
+const meta: Meta<typeof SearchPalette<Item>> = {
+  title: 'Form/SearchPalette',
+  component: SearchPalette,
+  tags: ['autodocs', 'component:SearchPalette'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'A Gmail-style search palette: input + filter chips + rich result rows + "see all" footer. App-agnostic and configurable.',
+      },
+    },
+  },
+  decorators: [
+    (Story) => (
+      <ThemeProvider theme={theme}>
+        <CssBaseline />
+        <div style={{ maxWidth: 640, padding: 24, background: '#f1f3f4' }}>
+          <Story />
+        </div>
+      </ThemeProvider>
+    ),
+  ],
+};
+export default meta;
+
+type Story = StoryObj<typeof SearchPalette<Item>>;
+
+function lead(item: Item): SearchResultLead {
+  return item.image
+    ? { kind: 'image', src: item.image }
+    : { kind: 'icon', node: <Inventory2Icon fontSize="small" /> };
+}
+
+function Harness({ initial = '' }: { initial?: string }) {
+  const [query, setQuery] = useState(initial);
+  const [active, setActive] = useState<string[]>(['last7']);
+  const matches = PRODUCTS.filter((p) => p.name.toLowerCase().includes(query.trim().toLowerCase()));
+  return (
+    <SearchPalette<Item>
+      value={query}
+      onChange={setQuery}
+      items={query.trim() ? matches : []}
+      getKey={(p) => p.id}
+      getPrimary={(p) => p.name}
+      getSecondary={(p) => p.sub}
+      getLead={lead}
+      getTrailing={(p) => p.date}
+      onSelect={(p) => setQuery(p.name)}
+      filters={FILTERS}
+      activeFilterIds={active}
+      onToggleFilter={(id) =>
+        setActive((cur) => (cur.includes(id) ? cur.filter((x) => x !== id) : [...cur, id]))
+      }
+      onSubmitAll={() => undefined}
+      emptyQueryContent={
+        <div style={{ padding: '8px 16px', color: '#5f6368', fontSize: 13 }}>
+          Comece a digitar para buscar…
+        </div>
+      }
+      inputAriaLabel="Buscar"
+      placeholder="Buscar páginas e registros…"
+    />
+  );
+}
+
+export const Default: Story = {
+  render: () => <Harness />,
+};
+
+export const WithResults: Story = {
+  render: () => <Harness initial="Sab" />,
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    // Chips render and results are filtered + capped.
+    await expect(canvas.getByTestId('search-palette-filters')).toBeInTheDocument();
+    await waitFor(() => expect(canvas.getByTestId('search-palette-results')).toBeInTheDocument());
+    await expect(canvas.getAllByText(/Sab/).length).toBeGreaterThan(0);
+    // Footer "see all" is present with a non-empty query.
+    await expect(canvas.getByTestId('search-palette-submit-all')).toBeInTheDocument();
+  },
+};
+
+export const ToggleFilter: Story = {
+  render: () => <Harness initial="a" />,
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const chip = canvas.getByTestId('search-palette-filter-mine');
+    await expect(chip).toHaveAttribute('aria-pressed', 'false');
+    await userEvent.click(chip);
+    await waitFor(() => expect(chip).toHaveAttribute('aria-pressed', 'true'));
+  },
+};
+
+export const EmptyQuery: Story = {
+  render: () => <Harness />,
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await expect(canvas.getByTestId('search-palette-empty-query')).toBeInTheDocument();
+  },
+};

package/src/components/form/SearchPalette/SearchPalette.tsx

@@ -0,0 +1,141 @@
+import React from 'react';
+
+import {
+  createKeyDownHandler,
+  FilterChips,
+  ghostRemainder,
+  PaletteBody,
+  PaletteInput,
+  Paper,
+} from './SearchPalette.parts';
+import type { SearchPaletteProps } from './SearchPalette.types';
+
+/**
+ * A Gmail-style search palette (FUT-168): a single card with a search input,
+ * a toggleable filter-chip row, a compact list of rich result rows (leading
+ * image/avatar/icon + primary/secondary + trailing), and a "see all results"
+ * footer. Fully app-agnostic — every label, filter, and row field is supplied
+ * by the host through accessors, so it drops into any surface.
+ *
+ * Keyboard: ↑/↓ move the active row across the results and the footer, Enter
+ * selects it (row → `onSelect`, footer → `onSubmitAll`), Esc calls `onClose`,
+ * and Tab/→ accepts the inline ghost completion of the top result.
+ *
+ * Presentational pieces + the keydown builder live in `SearchPalette.parts`.
+ */
+
+const DEFAULT_MAX_ITEMS = 5;
+const defaultSubmitLabel = (q: string): string => `Todos os resultados para "${q}"`;
+
+/** Non-string option defaults (numbers / flags / arrays). */
+function resolveOpts<T>(props: SearchPaletteProps<T>): {
+  maxItems: number;
+  filters: NonNullable<SearchPaletteProps<T>['filters']>;
+  activeFilterIds: string[];
+  isLoading: boolean;
+  showGhostText: boolean;
+  autoFocus: boolean;
+} {
+  return {
+    maxItems: props.maxItems ?? DEFAULT_MAX_ITEMS,
+    filters: props.filters ?? [],
+    activeFilterIds: props.activeFilterIds ?? [],
+    isLoading: Boolean(props.isLoading),
+    showGhostText: props.showGhostText ?? true,
+    autoFocus: props.autoFocus ?? true,
+  };
+}
+
+/** String / label defaults. */
+function resolveText<T>(props: SearchPaletteProps<T>): {
+  submitAllLabel: (q: string) => string;
+  noResultsLabel: string;
+  placeholder: string;
+  dataTestId: string;
+} {
+  return {
+    submitAllLabel: props.submitAllLabel ?? defaultSubmitLabel,
+    noResultsLabel: props.noResultsLabel ?? 'Nenhum resultado encontrado',
+    placeholder: props.placeholder ?? 'Buscar…',
+    dataTestId: props.dataTestId ?? 'search-palette',
+  };
+}
+
+export function SearchPalette<T>(props: SearchPaletteProps<T>): React.JSX.Element {
+  const opts = resolveOpts(props);
+  const text = resolveText(props);
+
+  const trimmed = props.value.trim();
+  const hasQuery = trimmed.length > 0;
+  const visible = props.items.slice(0, opts.maxItems);
+  const showFooter = Boolean(props.onSubmitAll) && hasQuery;
+  const rowCount = visible.length + (showFooter ? 1 : 0);
+  const footerIndex = showFooter ? visible.length : -1;
+
+  const [activeIndex, setActiveIndex] = React.useState(0);
+  // Keep the active row in range as results change (typing, filtering).
+  React.useEffect(() => {
+    setActiveIndex((i) => (rowCount === 0 ? 0 : Math.min(i, rowCount - 1)));
+  }, [rowCount]);
+
+  const top = visible[0];
+  const ghost =
+    opts.showGhostText && hasQuery && top ? ghostRemainder(props.getPrimary(top), props.value) : '';
+
+  const onKeyDown = createKeyDownHandler<T>({
+    rowCount,
+    activeIndex,
+    footerIndex,
+    visible,
+    hasQuery,
+    ghost,
+    top,
+    trimmed,
+    getPrimary: props.getPrimary,
+    onChange: props.onChange,
+    onSelect: props.onSelect,
+    onSubmitAll: props.onSubmitAll,
+    onClose: props.onClose,
+    setActiveIndex,
+  });
+
+  return (
+    <Paper
+      elevation={8}
+      className={props.className}
+      data-testid={text.dataTestId}
+      sx={{ width: '100%', maxWidth: 640, borderRadius: 2, overflow: 'hidden' }}
+    >
+      <PaletteInput
+        value={props.value}
+        ghost={ghost}
+        isLoading={opts.isLoading}
+        autoFocus={opts.autoFocus}
+        placeholder={text.placeholder}
+        inputAriaLabel={props.inputAriaLabel}
+        hasQuery={hasQuery}
+        onChange={props.onChange}
+        onKeyDown={onKeyDown}
+      />
+      {opts.filters.length > 0 && (
+        <FilterChips
+          filters={opts.filters}
+          activeFilterIds={opts.activeFilterIds}
+          onToggleFilter={props.onToggleFilter}
+        />
+      )}
+      <PaletteBody<T>
+        hasQuery={hasQuery} emptyQueryContent={props.emptyQueryContent} visible={visible}
+        isLoading={opts.isLoading} noResultsLabel={text.noResultsLabel} showFooter={showFooter}
+        footerIndex={footerIndex} activeIndex={activeIndex} trimmed={trimmed}
+        submitAllLabel={text.submitAllLabel} getKey={props.getKey} getPrimary={props.getPrimary}
+        getSecondary={props.getSecondary} getLead={props.getLead} getTrailing={props.getTrailing}
+        onSelect={props.onSelect} onSubmitAll={props.onSubmitAll} setActiveIndex={setActiveIndex}
+      />
+    </Paper>
+  );
+}
+
+SearchPalette.displayName = 'SearchPalette';
+
+export default SearchPalette;