@12-apps/ui 4.0.2 → 4.1.0

package/src/components/form/CategorySelect/CategorySelect.styles.ts

@@ -0,0 +1,354 @@
+import { alpha, type CSSObject, type Theme } from '@mui/material';
+
+/**
+ * The prototype's METRICS, verbatim.
+ *
+ * Every number here is lifted from the approved design and is intentionally
+ * absolute rather than derived from `theme.spacing`: the design is specified on
+ * a half-pixel type scale (13.5px rows, 1.5px checkbox borders) that an 8px
+ * spacing grid cannot express without rounding the look away.
+ *
+ * COLOURS are the deliberate exception — they come from the theme, because a
+ * tenant can white-label the palette (a hard-coded indigo would survive the
+ * rebrand and the rest of the screen would not) and because the library ships a
+ * dark mode. On the default light indigo theme the tokens below resolve to the
+ * prototype's own values.
+ */
+export const METRICS = {
+  triggerHeight: 38,
+  triggerRadius: 10,
+  panelWidth: 340,
+  panelRadius: 14,
+  listMaxHeight: 290,
+  sheetListMaxHeight: 340,
+  rowHeight: 36,
+  sheetRowHeight: 42,
+  rowRadius: 8,
+  boxSize: 18,
+  chevronButton: 22,
+  footerButton: 32,
+  sheetFooterButton: 38,
+  /** Below this width the panel becomes a bottom sheet. */
+  sheetBreakpoint: 480,
+} as const;
+
+/** Accent family, derived so a white-labelled palette carries through. */
+const accent = (theme: Theme) => ({
+  main: theme.palette.primary.main,
+  ink: theme.palette.primary.dark,
+  soft: alpha(theme.palette.primary.main, 0.08),
+  edge: alpha(theme.palette.primary.main, 0.28),
+  ring: alpha(theme.palette.primary.main, 0.15),
+});
+
+/** The closed control. `selected` swaps it to the accent-tinted "has filter" skin. */
+export const triggerSx = (theme: Theme, selected: boolean, open: boolean): CSSObject => {
+  const brand = accent(theme);
+  return {
+    display: 'flex',
+    alignItems: 'center',
+    gap: '8px',
+    height: METRICS.triggerHeight,
+    padding: '0 10px 0 12px',
+    borderRadius: `${METRICS.triggerRadius}px`,
+    border: `1px solid ${open || selected ? brand.edge : theme.palette.divider}`,
+    background: selected ? brand.soft : theme.palette.background.paper,
+    color: selected ? brand.ink : theme.palette.text.primary,
+    font: 'inherit',
+    fontSize: 13,
+    cursor: 'pointer',
+    maxWidth: '100%',
+    transition: 'border-color .12s, box-shadow .12s',
+    boxShadow: open ? `0 0 0 3px ${brand.ring}` : 'none',
+    '&:hover': { borderColor: open || selected ? brand.edge : theme.palette.text.disabled },
+    '&:focus-visible': {
+      outline: 'none',
+      borderColor: brand.main,
+      boxShadow: `0 0 0 3px ${alpha(brand.main, 0.18)}`,
+    },
+    '&:disabled': { opacity: 0.5, cursor: 'default' },
+  };
+};
+
+/** The count pill inside the trigger. */
+export const triggerCountSx = (theme: Theme): CSSObject => ({
+  fontWeight: 600,
+  fontSize: 11,
+  lineHeight: 1,
+  background: theme.palette.primary.main,
+  color: theme.palette.primary.contrastText,
+  borderRadius: '999px',
+  padding: '3px 6px',
+  minWidth: 18,
+  textAlign: 'center',
+});
+
+/** The trigger's inline clear (×) and the chevron. */
+export const triggerClearSx: CSSObject = {
+  width: 20,
+  height: 20,
+  flex: '0 0 auto',
+  border: 0,
+  background: 'transparent',
+  borderRadius: '5px',
+  display: 'grid',
+  placeItems: 'center',
+  cursor: 'pointer',
+  color: 'inherit',
+  opacity: 0.6,
+  padding: 0,
+  '&:hover': { background: alpha('#000', 0.08), opacity: 1 },
+};
+
+export const triggerChevronSx = (open: boolean): CSSObject => ({
+  width: 14,
+  height: 14,
+  flex: '0 0 auto',
+  opacity: 0.55,
+  transition: 'transform .15s',
+  transform: open ? 'rotate(180deg)' : 'none',
+});
+
+/** The floating panel. */
+export const panelSx = (theme: Theme): CSSObject => ({
+  width: METRICS.panelWidth,
+  maxWidth: '100%',
+  background: theme.palette.background.paper,
+  border: `1px solid ${theme.palette.divider}`,
+  borderRadius: `${METRICS.panelRadius}px`,
+  boxShadow: '0 1px 2px rgba(16,20,35,.05), 0 18px 40px -12px rgba(16,20,35,.28)',
+  display: 'flex',
+  flexDirection: 'column',
+  overflow: 'hidden',
+});
+
+/** Bottom-sheet skin, applied under {@link METRICS.sheetBreakpoint}. */
+export const sheetSx = (theme: Theme): CSSObject => ({
+  width: '100%',
+  maxWidth: 'none',
+  borderRadius: '18px 18px 0 0',
+  borderBottom: 0,
+  position: 'relative',
+  paddingTop: '4px',
+  '&::before': {
+    content: '""',
+    position: 'absolute',
+    top: 7,
+    left: '50%',
+    transform: 'translateX(-50%)',
+    width: 36,
+    height: 4,
+    borderRadius: '2px',
+    background: theme.palette.divider,
+  },
+});
+
+export const panelHeadSx = (theme: Theme, sheet: boolean): CSSObject => ({
+  padding: sheet ? '18px 10px 8px' : '10px 10px 8px',
+  borderBottom: `1px solid ${theme.palette.divider}`,
+});
+
+export const pinnedSx = (theme: Theme): CSSObject => ({
+  padding: '9px 10px',
+  borderBottom: `1px solid ${theme.palette.divider}`,
+  background: alpha(theme.palette.primary.main, 0.03),
+});
+
+export const pinnedLabelSx = (theme: Theme): CSSObject => ({
+  fontWeight: 600,
+  fontSize: 10,
+  lineHeight: 1,
+  letterSpacing: '.08em',
+  textTransform: 'uppercase',
+  color: theme.palette.text.secondary,
+  marginBottom: '7px',
+});
+
+export const chipWrapSx: CSSObject = {
+  display: 'flex',
+  flexWrap: 'wrap',
+  gap: '5px',
+  maxHeight: 74,
+  overflow: 'auto',
+};
+
+/** A selected-category chip, in the pinned tray and the applied bar alike. */
+export const chipSx = (theme: Theme): CSSObject => {
+  const brand = accent(theme);
+  return {
+    display: 'inline-flex',
+    alignItems: 'center',
+    gap: '5px',
+    fontSize: 12,
+    background: brand.soft,
+    color: brand.ink,
+    border: `1px solid ${brand.edge}`,
+    borderRadius: '7px',
+    padding: '3px 4px 3px 8px',
+    '& button': {
+      border: 0,
+      background: 'transparent',
+      color: 'inherit',
+      cursor: 'pointer',
+      padding: 0,
+      width: 16,
+      height: 16,
+      borderRadius: '4px',
+      display: 'grid',
+      placeItems: 'center',
+      opacity: 0.65,
+      fontSize: 13,
+      lineHeight: 1,
+      '&:hover': { background: alpha(theme.palette.primary.main, 0.16), opacity: 1 },
+    },
+  };
+};
+
+export const listSx = (sheet: boolean): CSSObject => ({
+  overflow: 'auto',
+  maxHeight: sheet ? METRICS.sheetListMaxHeight : METRICS.listMaxHeight,
+  padding: '6px 6px 8px',
+  scrollPadding: '8px 0',
+  overscrollBehavior: 'contain',
+});
+
+/** A row. `active` is the KEYBOARD cursor — deliberately distinct from hover. */
+export const rowSx = (theme: Theme, active: boolean, sheet: boolean): CSSObject => ({
+  display: 'flex',
+  alignItems: 'center',
+  gap: '8px',
+  padding: '0 8px',
+  height: sheet ? METRICS.sheetRowHeight : METRICS.rowHeight,
+  borderRadius: `${METRICS.rowRadius}px`,
+  cursor: 'pointer',
+  userSelect: 'none',
+  position: 'relative',
+  width: '100%',
+  border: 0,
+  textAlign: 'left',
+  font: 'inherit',
+  background: active ? alpha(theme.palette.primary.main, 0.08) : 'transparent',
+  boxShadow: active ? `inset 0 0 0 1px ${alpha(theme.palette.primary.main, 0.3)}` : 'none',
+  '&:hover': {
+    background: active
+      ? alpha(theme.palette.primary.main, 0.08)
+      : theme.palette.action.hover,
+  },
+  '&:focus-visible': { outline: `2px solid ${theme.palette.primary.main}`, outlineOffset: 1 },
+});
+
+export const rowNameSx = (theme: Theme, isCategory: boolean): CSSObject => ({
+  flex: 1,
+  minWidth: 0,
+  whiteSpace: 'nowrap',
+  overflow: 'hidden',
+  textOverflow: 'ellipsis',
+  fontSize: 13.5,
+  fontWeight: isCategory ? 600 : 450,
+  color: isCategory ? theme.palette.text.primary : theme.palette.text.secondary,
+});
+
+export const rowMetaSx = (theme: Theme, selected: boolean): CSSObject => ({
+  font: '500 11px/1 ui-monospace, SFMono-Regular, Menlo, monospace',
+  color: selected ? theme.palette.primary.main : theme.palette.text.secondary,
+  fontWeight: selected ? 600 : 500,
+  flex: '0 0 auto',
+});
+
+/** The query hit inside a row label. */
+export const markSx: CSSObject = {
+  background: '#fff2a8',
+  color: 'inherit',
+  borderRadius: '2px',
+  padding: '0 1px',
+};
+
+export const chevronButtonSx = (theme: Theme, open: boolean): CSSObject => ({
+  width: METRICS.chevronButton,
+  height: METRICS.chevronButton,
+  flex: '0 0 auto',
+  border: 0,
+  background: 'transparent',
+  borderRadius: '6px',
+  display: 'grid',
+  placeItems: 'center',
+  cursor: 'pointer',
+  color: theme.palette.text.secondary,
+  padding: 0,
+  '&:hover': { background: theme.palette.action.hover, color: theme.palette.text.primary },
+  '& svg': { width: 12, height: 12, transition: 'transform .15s', transform: open ? 'rotate(90deg)' : 'none' },
+});
+
+/** The tri-state checkbox: unchecked, checked, or the partial bar. */
+export const checkboxSx = (theme: Theme, state: 'off' | 'partial' | 'on'): CSSObject => ({
+  width: METRICS.boxSize,
+  height: METRICS.boxSize,
+  flex: '0 0 auto',
+  border: `1.5px solid ${state === 'off' ? theme.palette.divider : theme.palette.primary.main}`,
+  borderRadius: '5px',
+  background: state === 'off' ? theme.palette.background.paper : theme.palette.primary.main,
+  display: 'grid',
+  placeItems: 'center',
+  transition: 'background .1s, border-color .1s',
+  '& svg': { width: 12, height: 12, color: theme.palette.primary.contrastText },
+});
+
+/** The partial bar drawn inside a half-selected checkbox. */
+export const checkboxBarSx = (theme: Theme): CSSObject => ({
+  width: 9,
+  height: 2,
+  background: theme.palette.primary.contrastText,
+  borderRadius: '1px',
+});
+
+export const radioSx = (theme: Theme, on: boolean): CSSObject => ({
+  width: METRICS.boxSize,
+  height: METRICS.boxSize,
+  flex: '0 0 auto',
+  borderRadius: '50%',
+  background: theme.palette.background.paper,
+  border: on
+    ? `5.5px solid ${theme.palette.primary.main}`
+    : `1.5px solid ${theme.palette.divider}`,
+  boxSizing: 'border-box',
+});
+
+export const sectionHeadSx = (theme: Theme): CSSObject => ({
+  fontWeight: 600,
+  fontSize: 10,
+  lineHeight: 1,
+  letterSpacing: '.08em',
+  textTransform: 'uppercase',
+  color: theme.palette.text.secondary,
+  padding: '9px 8px 6px',
+});
+
+export const footerSx = (theme: Theme): CSSObject => ({
+  display: 'flex',
+  alignItems: 'center',
+  justifyContent: 'space-between',
+  gap: '8px',
+  padding: '9px 10px',
+  borderTop: `1px solid ${theme.palette.divider}`,
+  background: theme.palette.action.hover,
+});
+
+export const emptySx = (theme: Theme): CSSObject => ({
+  padding: '26px 18px',
+  textAlign: 'center',
+  color: theme.palette.text.secondary,
+  '& strong': {
+    display: 'block',
+    color: theme.palette.text.primary,
+    fontSize: 13.5,
+    marginBottom: '4px',
+  },
+  '& p': { margin: '0 0 12px', fontSize: 12.5, lineHeight: 1.5 },
+});
+
+/** Skeleton row used while the catalogue loads. */
+export const skeletonSx: CSSObject = {
+  height: METRICS.rowHeight,
+  margin: '4px 6px',
+  borderRadius: `${METRICS.rowRadius}px`,
+};

package/src/components/form/CategorySelect/CategorySelect.tsx

@@ -0,0 +1,183 @@
+'use client';
+
+import { useEffect, useMemo, useRef } from 'react';
+import { useMediaQuery, useTheme } from '@mui/material';
+
+import { summarizeSelection } from './category-tree';
+import { CategoryPanel } from './CategoryPanel';
+import { CategoryPanelSurface } from './CategoryPanelSurface';
+import { CategoryTrigger } from './CategoryTrigger';
+import { METRICS } from './CategorySelect.styles';
+import type { CategoryGroup, CategorySelectProps } from './CategorySelect.types';
+import { useCategoryCommit } from './useCategoryCommit';
+import { useCategoryKeyHandler } from './useCategoryKeyHandler';
+import { useCategorySelect } from './useCategorySelect';
+import { FormControl, FormLabel, FormMessage } from '../Form';
+
+/** The applied selection, always as an array — the two modes differ in shape. */
+function appliedIds(props: CategorySelectProps): string[] {
+  if (props.mode === 'single') return props.value ? [props.value] : [];
+  return props.value;
+}
+
+/** True when the draft differs from what is already applied. */
+function draftChanged(draft: ReadonlySet<string>, applied: readonly string[]): boolean {
+  return draft.size !== applied.length || applied.some((id) => !draft.has(id));
+}
+
+/** "Pai › Filha" for a chosen id, so the trigger carries its context. */
+function singleLabel(groups: CategoryGroup[], value: string | null): string | undefined {
+  if (!value) return undefined;
+  const asCategory = groups.find((group) => group.category.id === value);
+  if (asCategory) return asCategory.category.name;
+  const owner = groups.find((group) => group.subcategories.some((sub) => sub.id === value));
+  const sub = owner?.subcategories.find((candidate) => candidate.id === value);
+  return sub && owner ? `${owner.category.name} › ${sub.name}` : undefined;
+}
+
+/** The optional props, resolved once so the component body stays branch-free. */
+interface ResolvedConfig {
+  single: boolean;
+  placeholder: string;
+  disabled: boolean;
+  loading: boolean;
+  fullWidth: boolean;
+  showCounts: boolean;
+  allowParentSelection: boolean;
+  dataTestId: string;
+}
+
+function resolveConfig(props: CategorySelectProps): ResolvedConfig {
+  const single = props.mode === 'single';
+  return {
+    single,
+    placeholder: props.placeholder ?? (single ? 'Mover para…' : 'Categoria'),
+    disabled: props.disabled ?? false,
+    loading: props.loading ?? false,
+    fullWidth: props.fullWidth ?? false,
+    showCounts: props.showCounts ?? false,
+    allowParentSelection: props.allowParentSelection ?? false,
+    dataTestId: props.dataTestId ?? 'category-select',
+  };
+}
+
+/** Focus the search box on open, and keep the keyboard cursor in view. */
+function usePanelFocus(
+  open: boolean,
+  activeIndex: number,
+  searchInputRef: React.RefObject<HTMLInputElement | null>,
+  listRef: React.RefObject<HTMLDivElement | null>,
+): void {
+  // The first thing an admin does with ten categories is type; focusing here
+  // saves the extra click every single time the panel opens.
+  useEffect(() => {
+    if (!open) return undefined;
+    const frame = requestAnimationFrame(() => searchInputRef.current?.focus());
+    return () => cancelAnimationFrame(frame);
+  }, [open, searchInputRef]);
+
+  useEffect(() => {
+    if (activeIndex < 0) return;
+    const rows = listRef.current?.querySelectorAll('[role="option"], [role="button"]');
+    rows?.[activeIndex]?.scrollIntoView({ block: 'nearest' });
+  }, [activeIndex, listRef]);
+}
+
+/**
+ * A hierarchical category picker: categories as the frame, subcategories as the
+ * thing you choose.
+ *
+ * Two modes off one component. `multi` is the FILTER — ticks accumulate in a
+ * draft and reach `onChange` only on Apply, so the list behind the panel does not
+ * reload on every click. `single` is the "move to…" picker, where choosing a row
+ * commits immediately because there is nothing to batch.
+ *
+ * The tree opens fully expanded: nothing a search could match is hidden behind a
+ * disclosure. Selected categories pin above the list so they survive scrolling
+ * and searching, search is accent-insensitive (`agua` finds `Águas`), and the
+ * whole tree is keyboard-drivable — ↑↓ to move, → to open, ← to close, Space to
+ * mark, Enter to apply, Esc to cancel.
+ *
+ * Under {@link METRICS.sheetBreakpoint} the panel becomes a bottom sheet, which
+ * is the only way a 290px-tall list stays usable one-handed.
+ */
+export function CategorySelect(props: CategorySelectProps): React.JSX.Element {
+  const { options, label, error, onCreateCategory } = props;
+  const {
+    single,
+    placeholder,
+    disabled,
+    loading,
+    fullWidth,
+    showCounts,
+    allowParentSelection,
+    dataTestId,
+  } = resolveConfig(props);
+
+  const theme = useTheme();
+  const sheet = useMediaQuery(theme.breakpoints.down(METRICS.sheetBreakpoint));
+  const applied = appliedIds(props);
+
+  const state = useCategorySelect({ options, selected: applied });
+  const searchInputRef = useRef<HTMLInputElement | null>(null);
+  const listRef = useRef<HTMLDivElement | null>(null);
+  usePanelFocus(state.open, state.activeIndex, searchInputRef, listRef);
+
+  const chips = useMemo(
+    () => summarizeSelection(state.allGroups, state.draft),
+    [state.allGroups, state.draft],
+  );
+  const rowIds = useMemo(() => state.rows.map((row) => row.id), [state.rows]);
+
+  const actions = useCategoryCommit({ props, state, single, allowParentSelection });
+  const onKeyDown = useCategoryKeyHandler({ state, single, allowParentSelection, actions });
+
+  return (
+    <FormControl fullWidth={fullWidth} error={Boolean(error)}>
+      {label && <FormLabel error={Boolean(error)}>{label}</FormLabel>}
+      <CategoryTrigger
+        placeholder={placeholder}
+        selectionLabel={
+          props.mode === 'single' ? singleLabel(state.allGroups, props.value) : undefined
+        }
+        count={single ? undefined : applied.length}
+        open={state.open}
+        disabled={disabled}
+        fullWidth={fullWidth}
+        onOpen={state.openPanel}
+        onClear={applied.length > 0 ? actions.clearSelection : undefined}
+        triggerRef={state.triggerRef}
+        dataTestId={dataTestId}
+      />
+      <CategoryPanelSurface
+        open={state.open}
+        sheet={sheet}
+        anchorEl={state.triggerRef.current}
+        onClose={actions.cancel}
+      >
+        <CategoryPanel
+          state={state}
+          chips={chips}
+          rowIds={rowIds}
+          changed={draftChanged(state.draft, applied)}
+          single={single}
+          sheet={sheet}
+          loading={loading}
+          showCounts={showCounts}
+          allowParentSelection={allowParentSelection}
+          ariaLabel={label ?? placeholder}
+          onKeyDown={onKeyDown}
+          onActivateCategory={actions.activateCategory}
+          onActivateSubcategory={actions.activateSubcategory}
+          onApply={actions.commit}
+          onCancel={actions.cancel}
+          onCreateCategory={onCreateCategory}
+          searchInputRef={searchInputRef}
+          listRef={listRef}
+          dataTestId={dataTestId}
+        />
+      </CategoryPanelSurface>
+      {error && <FormMessage error dataTestId={`${dataTestId}-message`}>{error}</FormMessage>}
+    </FormControl>
+  );
+}

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

@@ -0,0 +1,103 @@
+import type { SizeValue } from '../../../tokens/scales';
+
+/**
+ * One category as the caller already stores it: a FLAT row carrying its parent.
+ *
+ * Flat-with-`parentId` rather than a nested `children` array because that is the
+ * shape the API and the consuming admin lists already hold; nesting it at every
+ * call site would be work the component can do once, memoised, itself.
+ */
+export interface CategorySelectOption {
+  /** Stable identifier — what {@link CategorySelectProps.value} refers to. */
+  id: string;
+  /** The category's own name. Never pre-indented: the ROW draws the nesting. */
+  name: string;
+  /** Parent category id, or `null`/absent for a top-level category. */
+  parentId?: string | null;
+  /**
+   * Item count for this category, shown as a muted trailing number when
+   * {@link CategorySelectBaseProps.showCounts} is on.
+   */
+  count?: number;
+}
+
+/** A top-level category together with the subcategories nested under it. */
+export interface CategoryGroup {
+  category: CategorySelectOption;
+  subcategories: CategorySelectOption[];
+}
+
+/** One entry in the "selected" summary: a whole category, or a single leaf. */
+export interface CategorySelectionChip {
+  /** The id to remove when the chip's × is pressed. */
+  id: string;
+  /** Display label — the category name, or the subcategory name. */
+  label: string;
+  /** Set when the chip stands for EVERY subcategory of a category. */
+  whole: boolean;
+}
+
+/** Props shared by both selection modes. */
+export interface CategorySelectBaseProps {
+  /** The categories to choose from, flat, in display order. */
+  options: CategorySelectOption[];
+  /** Field label rendered above the trigger. */
+  label?: string;
+  /** Text on the trigger while nothing is selected. */
+  placeholder?: string;
+  /** Validation message; also flags the trigger as errored. */
+  error?: string;
+  /** Disables the trigger. */
+  disabled?: boolean;
+  /** Draws skeleton rows in place of the list (catalogue still loading). */
+  loading?: boolean;
+  /** Stretch to the container width (default: `false` — the trigger hugs). */
+  fullWidth?: boolean;
+  /** Control height, matching {@link Input}'s scale (default: `md`). */
+  size?: SizeValue;
+  /** Show each category's `count` as a trailing muted number (default: `false`). */
+  showCounts?: boolean;
+  /**
+   * Lets a top-level category be chosen in its own right. Off by default: the
+   * prototype's leaf-only default makes the category a HEADING and the
+   * subcategory the thing you pick, which is what removes the "did I select the
+   * parent or the group?" ambiguity.
+   */
+  allowParentSelection?: boolean;
+  /**
+   * Category creation, offered two ways when provided: as the empty-catalogue
+   * call to action, and as a `Criar "<termo>"` row when a search matches
+   * nothing — called with the typed text in that case.
+   *
+   * The second is what lets this replace a creatable combobox without losing
+   * create-as-you-type: an admin who searches for a category that does not
+   * exist yet is exactly the admin who wants to add it.
+   */
+  onCreateCategory?: (name?: string) => void;
+  /** Base test id; the trigger is `<dataTestId>-trigger`, the panel `-panel`. */
+  dataTestId?: string;
+}
+
+/**
+ * Multi-select mode: the filter. Edits accumulate in a DRAFT and only reach
+ * `onChange` when Apply is pressed, so the filtered list behind the panel does
+ * not reload on every tick.
+ */
+export interface CategoryMultiSelectProps extends CategorySelectBaseProps {
+  mode?: 'multi';
+  /** The APPLIED selection — subcategory ids. */
+  value: string[];
+  /** Fired with the new applied selection when Apply is pressed. */
+  onChange: (next: string[]) => void;
+}
+
+/** Single-select mode: the "move to…" picker. Choosing a row commits at once. */
+export interface CategorySingleSelectProps extends CategorySelectBaseProps {
+  mode: 'single';
+  /** The chosen category or subcategory id, or `null`. */
+  value: string | null;
+  /** Fired with the chosen id, or `null` when cleared. */
+  onChange: (next: string | null) => void;
+}
+
+export type CategorySelectProps = CategoryMultiSelectProps | CategorySingleSelectProps;