@12-apps/ui 4.0.2 → 5.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12-apps/ui",
-  "version": "4.0.2",
+  "version": "5.0.0",
   "license": "MIT",
   "packageManager": "pnpm@9.0.0",
   "type": "module",
@@ -78,6 +78,7 @@
     "./form/Autocomplete": "./src/components/form/Autocomplete/index.ts",
     "./form/Button": "./src/components/form/Button/index.ts",
     "./form/Calendar": "./src/components/form/Calendar/index.ts",
+    "./form/CategorySelect": "./src/components/form/CategorySelect/index.ts",
     "./form/CepField": "./src/components/form/CepField/index.ts",
     "./form/Checkbox": "./src/components/form/Checkbox/index.ts",
     "./form/CodeEditor": "./src/components/form/CodeEditor/index.ts",

package/src/components/data-display/DataViews/data-views-category-pill.tsx

@@ -0,0 +1,98 @@
+"use client";
+
+import { CategorySelect } from "../../form/CategorySelect";
+import { MultiSelectDropdown } from "../../layout/ContentToolbar";
+
+import type { FilterFieldConfig, FilterOption } from "./data-views-types";
+
+/**
+ * Diff a whole-array selection back into per-value toggles.
+ *
+ * The filter state's only channel is `onTogglePill(field, value, checked)`, but
+ * a tree hands back the entire selection at once. Diffing here keeps that one
+ * channel the single way a pill ever changes, rather than giving the
+ * hierarchical control a private path into the state.
+ */
+export function emitPillDiff(
+  fieldId: string,
+  before: readonly string[],
+  after: readonly string[],
+  onTogglePill: (fieldId: string, value: string, checked: boolean) => void,
+): void {
+  const had = new Set(before);
+  const wants = new Set(after);
+  after.forEach((value) => {
+    if (!had.has(value)) onTogglePill(fieldId, value, true);
+  });
+  before.forEach((value) => {
+    if (!wants.has(value)) onTogglePill(fieldId, value, false);
+  });
+}
+
+/** A filter option as the category tree wants it. */
+const toCategoryOption = (option: FilterOption) => ({
+  id: option.value,
+  name: option.label,
+  parentId: option.parentId ?? null,
+});
+
+interface PillControlProps<T extends Record<string, unknown>> {
+  fieldId: string;
+  pill: FilterFieldConfig<T>;
+  selected: string[];
+  onTogglePill: (fieldId: string, value: string, checked: boolean) => void;
+  onClearField: (fieldId: string) => void;
+  onOpenChange?: (open: boolean) => void;
+  testIdPrefix: string;
+  /** `stacked` in the filter panel, `pill` on the inline bar. */
+  layout?: "stacked" | "pill";
+}
+
+/**
+ * One filter pill: the hierarchical category tree, or the flat multi-select.
+ *
+ * A category set nests, and flattening it into one list is what made "Massas"
+ * (mercearia) indistinguishable from "Massas" (pratos principais). `control:
+ * "category"` opts a field into the tree, which shows each hit under its parent.
+ */
+export function PillControl<T extends Record<string, unknown>>({
+  fieldId,
+  pill,
+  selected,
+  onTogglePill,
+  onClearField,
+  onOpenChange,
+  testIdPrefix,
+  layout = "pill",
+}: PillControlProps<T>): React.JSX.Element {
+  const testId = `${testIdPrefix}-filter-${fieldId}`;
+  if (pill.control === "category") {
+    return (
+      <CategorySelect
+        placeholder={pill.label}
+        label={layout === "stacked" ? pill.label : undefined}
+        fullWidth={layout === "stacked"}
+        options={pill.options.map(toCategoryOption)}
+        value={selected}
+        onChange={(next) => emitPillDiff(fieldId, selected, next, onTogglePill)}
+        dataTestId={testId}
+      />
+    );
+  }
+  return (
+    <MultiSelectDropdown
+      label={pill.label}
+      options={pill.options}
+      selected={new Set(selected)}
+      onToggle={(value, checked) => onTogglePill(fieldId, value, checked)}
+      onClear={() => onClearField(fieldId)}
+      allLabel="Todas"
+      searchable={pill.searchEnabled ? true : undefined}
+      searchPlaceholder="Buscar…"
+      noResultsLabel="Nenhum resultado"
+      layout={layout}
+      onOpenChange={onOpenChange}
+      data-testid={testId}
+    />
+  );
+}

package/src/components/data-display/DataViews/data-views-filter-panel.tsx

@@ -3,9 +3,9 @@
 import { Box, Link } from "@mui/material";
 
 import { StackedModal, StackedModalContent } from "../../feedback/StackedModal";
-import { MultiSelectDropdown } from "../../layout/ContentToolbar";
 import { TableFilter } from "../../layout/TableFilter";
 
+import { PillControl } from "./data-views-category-pill";
 import { PanelRangeField } from "./data-views-range-pill";
 import type {
   FilterFieldConfig,
@@ -45,21 +45,18 @@ function PillField<T extends Record<string, unknown>>({
 }): React.JSX.Element {
   const testId = `${testIdPrefix}-filter-${field.id}`;
   // `searchEnabled` forces the searchable multi-select; a plain `multiselect`
-  // keeps the auto "search only when the list is long" rule.
-  if (field.searchEnabled || field.control === "multiselect") {
+  // keeps the auto "search only when the list is long" rule. `category` is the
+  // hierarchical tree — see PillControl.
+  if (field.searchEnabled || field.control === "multiselect" || field.control === "category") {
     return (
-      <MultiSelectDropdown
-        label={field.label}
-        options={field.options}
-        selected={new Set(selected)}
-        onToggle={(value, checked) => onTogglePill(field.id, value, checked)}
-        onClear={() => onClearField(field.id)}
-        allLabel="Todas"
-        searchable={field.searchEnabled ? true : undefined}
-        searchPlaceholder="Buscar…"
-        noResultsLabel="Nenhum resultado"
+      <PillControl
+        fieldId={field.id}
+        pill={field}
+        selected={selected}
+        onTogglePill={onTogglePill}
+        onClearField={onClearField}
+        testIdPrefix={testIdPrefix}
         layout="stacked"
-        data-testid={testId}
       />
     );
   }

package/src/components/data-display/DataViews/data-views-inline-bar.tsx

@@ -18,13 +18,13 @@
 import { Box } from "@mui/material";
 import { useState } from "react";
 
-import { MultiSelectDropdown } from "../../layout/ContentToolbar";
 
 import { ClearAllControl, CloseSearchControl } from "./data-views-bar-controls";
 import type { GridFilterPanelProps } from "./data-views-filter-panel";
 import { MoreFilters } from "./data-views-more-filters";
 import type { OverflowField, OverflowSplit } from "./data-views-overflow";
 import { CollapsedSearch, InlineKeyword } from "./data-views-search";
+import { PillControl } from "./data-views-category-pill";
 import { RangePill } from "./data-views-range-pill";
 import type { RangeValue } from "./data-views-types";
 
@@ -116,19 +116,14 @@ function InlineControl<T extends Record<string, unknown>>({
 }): React.JSX.Element | null {
   if (field.group === "pill" && field.pill) {
     return (
-      <MultiSelectDropdown
-        label={field.pill.label}
-        options={field.pill.options}
-        selected={new Set(pills[field.id] ?? [])}
-        onToggle={(value, checked) => onTogglePill(field.id, value, checked)}
-        onClear={() => onClearField(field.id)}
-        allLabel="Todas"
-        searchable={field.pill.searchEnabled ? true : undefined}
-        searchPlaceholder="Buscar…"
-        noResultsLabel="Nenhum resultado"
-        layout="pill"
+      <PillControl
+        fieldId={field.id}
+        pill={field.pill}
+        selected={pills[field.id] ?? []}
+        onTogglePill={onTogglePill}
+        onClearField={onClearField}
         onOpenChange={onOpenChange}
-        data-testid={`${testIdPrefix}-filter-${field.id}`}
+        testIdPrefix={testIdPrefix}
       />
     );
   }

package/src/components/data-display/DataViews/data-views-types.ts

@@ -87,6 +87,11 @@ export const CARD_ASPECT_RATIOS: Record<CardAspectRatio, number> = {
 export interface FilterOption {
   value: string;
   label: string;
+  /**
+   * Parent option's `value`, for a hierarchical field (`control: "category"`).
+   * Ignored by the flat controls, so one option list serves both.
+   */
+  parentId?: string | null;
 }
 
 /** A typed, multi-select filter pill's configuration for a table. */
@@ -98,9 +103,12 @@ export interface FilterFieldConfig<T extends Record<string, unknown>> {
   /**
    * How the field renders in the filter panel. `checkboxes` (default) is best for
    * a few fixed options; `multiselect` is a compact dropdown for long option
-   * lists (e.g. many categories).
+   * lists; `category` is the hierarchical picker, for an option set that nests
+   * via {@link FilterOption.parentId} — it renders parents as headings and
+   * their children as the selectable rows, rather than flattening the tree into
+   * one indistinguishable list.
    */
-  control?: "checkboxes" | "multiselect";
+  control?: "checkboxes" | "multiselect" | "category";
   /**
    * Forces this filter to render as a searchable multi-select dropdown with the
    * search box always shown, regardless of how many options are currently

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

@@ -0,0 +1,52 @@
+/**
+ * The prototype's four glyphs, inlined.
+ *
+ * Inline SVG rather than `@mui/icons-material` because these are drawn at the
+ * design's own weights (2.4 for the chevrons, 3.2 for the tick) and sizes; the
+ * Material set is a 24px grid at a fixed weight and would not land on the same
+ * pixels.
+ */
+
+const STROKE = {
+  fill: 'none',
+  stroke: 'currentColor',
+  strokeLinecap: 'round',
+  strokeLinejoin: 'round',
+} as const;
+
+/** The tick inside a checked box. */
+export function CheckGlyph(): React.JSX.Element {
+  return (
+    <svg viewBox="0 0 24 24" strokeWidth={3.2} aria-hidden="true" {...STROKE}>
+      <path d="M20 6 9 17l-5-5" />
+    </svg>
+  );
+}
+
+/** The disclosure chevron on a category row (points right; rotates when open). */
+export function DisclosureGlyph(): React.JSX.Element {
+  return (
+    <svg viewBox="0 0 24 24" strokeWidth={2.4} aria-hidden="true" {...STROKE}>
+      <path d="m9 5 7 7-7 7" />
+    </svg>
+  );
+}
+
+/** The trigger's caret (points down; rotates when the panel is open). */
+export function CaretGlyph({ style }: { style?: React.CSSProperties }): React.JSX.Element {
+  return (
+    <svg viewBox="0 0 24 24" strokeWidth={2.4} style={style} aria-hidden="true" {...STROKE}>
+      <path d="m6 9 6 6 6-6" />
+    </svg>
+  );
+}
+
+/** The magnifier in the panel's search field. */
+export function SearchGlyph({ style }: { style?: React.CSSProperties }): React.JSX.Element {
+  return (
+    <svg viewBox="0 0 24 24" strokeWidth={2} style={style} aria-hidden="true" {...STROKE}>
+      <circle cx="11" cy="11" r="7" />
+      <path d="m20 20-3.5-3.5" />
+    </svg>
+  );
+}

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

@@ -0,0 +1,155 @@
+'use client';
+
+import { Box } from '@mui/material';
+
+import { removeChip } from './category-tree';
+import { CategoryMultiFoot, CategorySingleFoot } from './CategoryPanelFoot';
+import { CategoryPanelHead, CategoryPinnedTray } from './CategoryPanelHead';
+import { CategoryPanelList } from './CategoryPanelList';
+import { CategoryQuickActions } from './CategoryQuickActions';
+import { panelSx, sheetSx } from './CategorySelect.styles';
+import type { CategoryGroup, CategorySelectionChip } from './CategorySelect.types';
+import type { CategorySelectState } from './useCategorySelect';
+
+export interface CategoryPanelProps {
+  state: CategorySelectState;
+  chips: CategorySelectionChip[];
+  rowIds: string[];
+  /** True when the applied selection differs from the draft. */
+  changed: boolean;
+  single: boolean;
+  sheet: boolean;
+  loading: boolean;
+  showCounts: boolean;
+  allowParentSelection: boolean;
+  ariaLabel: string;
+  onKeyDown: (event: React.KeyboardEvent) => void;
+  onActivateCategory: (group: CategoryGroup) => void;
+  onActivateSubcategory: (id: string) => void;
+  onApply: () => void;
+  onCancel: () => void;
+  onCreateCategory?: () => void;
+  searchInputRef: React.RefObject<HTMLInputElement | null>;
+  listRef: React.RefObject<HTMLDivElement | null>;
+  dataTestId: string;
+}
+
+/** Search + pinned selection + tree + footer, in the panel's own chrome. */
+export function CategoryPanel({
+  state,
+  chips,
+  rowIds,
+  changed,
+  single,
+  sheet,
+  loading,
+  showCounts,
+  allowParentSelection,
+  ariaLabel,
+  onKeyDown,
+  onActivateCategory,
+  onActivateSubcategory,
+  onApply,
+  onCancel,
+  onCreateCategory,
+  searchInputRef,
+  listRef,
+  dataTestId,
+}: CategoryPanelProps): React.JSX.Element {
+  return (
+    <Box
+      onKeyDown={onKeyDown}
+      role="dialog"
+      aria-label={ariaLabel}
+      data-testid={`${dataTestId}-panel`}
+      sx={(theme) => ({ ...panelSx(theme), ...(sheet ? sheetSx(theme) : {}) })}
+    >
+      <CategoryPanelHead
+        query={state.query}
+        placeholder={single ? 'Buscar categoria…' : 'Buscar categoria ou subcategoria'}
+        sheet={sheet}
+        quickActions={
+          single ? undefined : <CategoryQuickActions state={state} dataTestId={dataTestId} />
+        }
+        onQueryChange={state.setQuery}
+        searchInputRef={searchInputRef}
+        dataTestId={dataTestId}
+      />
+      {!single && !loading && (
+        <PinnedTray state={state} chips={chips} dataTestId={dataTestId} />
+      )}
+      <CategoryPanelList
+        groups={state.visibleGroups}
+        query={state.query}
+        draft={state.draft}
+        rowIds={rowIds}
+        activeIndex={state.activeIndex}
+        sheet={sheet}
+        single={single}
+        loading={loading}
+        showCounts={showCounts}
+        allowParentSelection={allowParentSelection}
+        isExpanded={state.isExpanded}
+        onToggleExpanded={state.toggleExpanded}
+        onActivateCategory={onActivateCategory}
+        onActivateSubcategory={onActivateSubcategory}
+        onClearQuery={() => state.setQuery('')}
+        onCreateCategory={onCreateCategory}
+        listRef={listRef}
+        dataTestId={dataTestId}
+      />
+      <PanelFooter
+        state={state}
+        changed={changed}
+        single={single}
+        sheet={sheet}
+        onApply={onApply}
+        onCancel={onCancel}
+        dataTestId={dataTestId}
+      />
+    </Box>
+  );
+}
+
+/** The selected-category chips, wired to remove from the draft. */
+function PinnedTray({
+  state,
+  chips,
+  dataTestId,
+}: Pick<CategoryPanelProps, 'state' | 'chips' | 'dataTestId'>): React.JSX.Element {
+  return (
+    <CategoryPinnedTray
+      chips={chips}
+      onRemove={(chipId) => state.setDraft(removeChip(state.allGroups, chipId, state.draft))}
+      dataTestId={dataTestId}
+    />
+  );
+}
+
+/** Whichever footer the mode calls for. */
+function PanelFooter({
+  state,
+  changed,
+  single,
+  sheet,
+  onApply,
+  onCancel,
+  dataTestId,
+}: Pick<
+  CategoryPanelProps,
+  'state' | 'changed' | 'single' | 'sheet' | 'onApply' | 'onCancel' | 'dataTestId'
+>): React.JSX.Element {
+  if (single) {
+    return <CategorySingleFoot sheet={sheet} onCancel={onCancel} dataTestId={dataTestId} />;
+  }
+  return (
+    <CategoryMultiFoot
+      count={state.draft.size}
+      changed={changed}
+      sheet={sheet}
+      onClear={() => state.setDraft(new Set())}
+      onApply={onApply}
+      dataTestId={dataTestId}
+    />
+  );
+}

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

@@ -0,0 +1,94 @@
+'use client';
+
+import { Box, Button } from '@mui/material';
+
+import { footerSx, METRICS } from './CategorySelect.styles';
+
+const buttonSx = (sheet: boolean) =>
+  ({
+    height: sheet ? METRICS.sheetFooterButton : METRICS.footerButton,
+    padding: '0 13px',
+    borderRadius: '8px',
+    fontSize: 12.5,
+    fontWeight: 600,
+    textTransform: 'none',
+    minWidth: 0,
+  }) as const;
+
+interface MultiFootProps {
+  count: number;
+  /** False once the draft matches what is already applied — Apply becomes Close. */
+  changed: boolean;
+  sheet: boolean;
+  onClear: () => void;
+  onApply: () => void;
+  dataTestId: string;
+}
+
+/**
+ * Multi-select footer: the running count, Clear, and the Apply that publishes
+ * the draft. The primary button reads "Fechar" when nothing changed, so it never
+ * promises an update it would not make.
+ */
+export function CategoryMultiFoot({
+  count,
+  changed,
+  sheet,
+  onClear,
+  onApply,
+  dataTestId,
+}: MultiFootProps): React.JSX.Element {
+  return (
+    <Box sx={footerSx} data-testid={`${dataTestId}-footer`}>
+      <Box component="span" sx={{ fontSize: 12, color: 'text.secondary' }}>
+        <strong>{count}</strong> selecionada{count === 1 ? '' : 's'}
+      </Box>
+      <Box sx={{ display: 'flex', gap: '6px' }}>
+        <Button
+          variant="outlined"
+          disabled={count === 0}
+          sx={buttonSx(sheet)}
+          onClick={onClear}
+          data-testid={`${dataTestId}-clear`}
+        >
+          Limpar
+        </Button>
+        <Button
+          variant="contained"
+          sx={buttonSx(sheet)}
+          onClick={onApply}
+          data-testid={`${dataTestId}-apply`}
+        >
+          {changed ? 'Aplicar' : 'Fechar'}
+        </Button>
+      </Box>
+    </Box>
+  );
+}
+
+/** Single-select footer: a hint and a way out. Picking a row commits directly. */
+export function CategorySingleFoot({
+  sheet,
+  onCancel,
+  dataTestId,
+}: {
+  sheet: boolean;
+  onCancel: () => void;
+  dataTestId: string;
+}): React.JSX.Element {
+  return (
+    <Box sx={footerSx} data-testid={`${dataTestId}-footer`}>
+      <Box component="span" sx={{ fontSize: 12, color: 'text.secondary' }}>
+        Escolha uma categoria
+      </Box>
+      <Button
+        variant="outlined"
+        sx={buttonSx(sheet)}
+        onClick={onCancel}
+        data-testid={`${dataTestId}-cancel`}
+      >
+        Cancelar
+      </Button>
+    </Box>
+  );
+}

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

@@ -0,0 +1,167 @@
+'use client';
+
+import { Box, InputBase } from '@mui/material';
+
+import { SearchGlyph } from './CategoryIcons';
+import {
+  chipSx,
+  chipWrapSx,
+  panelHeadSx,
+  pinnedLabelSx,
+  pinnedSx,
+} from './CategorySelect.styles';
+import type { CategorySelectionChip } from './CategorySelect.types';
+
+interface PanelHeadProps {
+  query: string;
+  placeholder: string;
+  sheet: boolean;
+  /** Quick actions belong to multi-select only; single-select has nothing to bulk-do. */
+  quickActions?: React.ReactNode;
+  onQueryChange: (next: string) => void;
+  searchInputRef: React.RefObject<HTMLInputElement | null>;
+  dataTestId: string;
+}
+
+const searchFieldSx = {
+  position: 'relative',
+  display: 'flex',
+  alignItems: 'center',
+  '& input': {
+    width: '100%',
+    height: 36,
+    padding: '0 30px 0 32px',
+    fontSize: 13,
+    border: '1px solid',
+    borderColor: 'divider',
+    borderRadius: '9px',
+    background: 'background.paper',
+    color: 'text.primary',
+    '&:focus': {
+      outline: 'none',
+      borderColor: 'primary.main',
+      boxShadow: (theme: { palette: { primary: { main: string } } }) =>
+        `0 0 0 3px ${theme.palette.primary.main}26`,
+    },
+  },
+} as const;
+
+const clearButtonSx = {
+  position: 'absolute',
+  right: 7,
+  width: 20,
+  height: 20,
+  border: 0,
+  background: 'action.selected',
+  color: 'text.secondary',
+  borderRadius: '50%',
+  display: 'grid',
+  placeItems: 'center',
+  cursor: 'pointer',
+  fontSize: 12,
+  padding: 0,
+  lineHeight: 1,
+} as const;
+
+/** Search field, its clear affordance, and the optional quick-action row. */
+export function CategoryPanelHead({
+  query,
+  placeholder,
+  sheet,
+  quickActions,
+  onQueryChange,
+  searchInputRef,
+  dataTestId,
+}: PanelHeadProps): React.JSX.Element {
+  return (
+    <Box sx={(theme) => panelHeadSx(theme, sheet)}>
+      <Box sx={searchFieldSx}>
+        <SearchGlyph
+          style={{
+            position: 'absolute',
+            left: 10,
+            width: 15,
+            height: 15,
+            opacity: 0.55,
+            pointerEvents: 'none',
+          }}
+        />
+        <InputBase
+          inputRef={searchInputRef}
+          value={query}
+          placeholder={placeholder}
+          autoComplete="off"
+          inputProps={{ 'aria-label': placeholder, 'data-testid': `${dataTestId}-search` }}
+          onChange={(event) => onQueryChange(event.target.value)}
+          sx={{ width: '100%' }}
+        />
+        {query.length > 0 && (
+          <Box
+            component="button"
+            type="button"
+            aria-label="Limpar busca"
+            data-testid={`${dataTestId}-search-clear`}
+            sx={clearButtonSx}
+            onClick={() => onQueryChange('')}
+          >
+            ×
+          </Box>
+        )}
+      </Box>
+      {quickActions && (
+        <Box
+          sx={{
+            display: 'flex',
+            alignItems: 'center',
+            gap: '10px',
+            marginTop: '8px',
+            fontSize: 12,
+          }}
+        >
+          {quickActions}
+        </Box>
+      )}
+    </Box>
+  );
+}
+
+interface PinnedTrayProps {
+  chips: CategorySelectionChip[];
+  onRemove: (chipId: string) => void;
+  dataTestId: string;
+}
+
+/**
+ * The selected categories, pinned above the list.
+ *
+ * Pinned rather than left in place because a selection made at the bottom of a
+ * ten-category tree scrolls out of sight the moment you look for the next one —
+ * and a search hides it entirely. Here it survives both.
+ */
+export function CategoryPinnedTray({
+  chips,
+  onRemove,
+  dataTestId,
+}: PinnedTrayProps): React.JSX.Element | null {
+  if (chips.length === 0) return null;
+  return (
+    <Box sx={pinnedSx} data-testid={`${dataTestId}-pinned`}>
+      <Box sx={pinnedLabelSx}>Selecionadas · {chips.length}</Box>
+      <Box sx={chipWrapSx}>
+        {chips.map((chip) => (
+          <Box component="span" key={chip.id} sx={chipSx}>
+            {chip.label}
+            <button
+              type="button"
+              aria-label={`Remover ${chip.label}`}
+              data-testid={`${dataTestId}-unpin-${chip.id}`}
+              onClick={() => onRemove(chip.id)}
+            >
+              ×
+            </button>
+          </Box>
+        ))}
+      </Box>
+    </Box>
+  );
+}