@12-apps/ui 4.0.2 → 5.0.0

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

@@ -0,0 +1,207 @@
+'use client';
+
+import { Box, Button, Skeleton } from '@mui/material';
+
+import { categoryCheckState } from './category-tree';
+import {
+  CategoryHeadRow,
+  CategorySectionHeading,
+  SubcategoryRow,
+} from './CategoryRows';
+import { emptySx, listSx, skeletonSx } from './CategorySelect.styles';
+import type { CategoryGroup } from './CategorySelect.types';
+
+/** The design sets these labels in sentence case, not MUI's default caps. */
+const SENTENCE_CASE = { textTransform: 'none' } as const;
+
+/** How many skeleton rows stand in for the catalogue while it loads. */
+const SKELETON_ROWS = 6;
+
+interface PanelListProps {
+  groups: CategoryGroup[];
+  query: string;
+  draft: ReadonlySet<string>;
+  rowIds: string[];
+  activeIndex: number;
+  sheet: boolean;
+  single: boolean;
+  loading: boolean;
+  showCounts: boolean;
+  allowParentSelection: boolean;
+  isExpanded: (categoryId: string) => boolean;
+  onToggleExpanded: (categoryId: string) => void;
+  onActivateCategory: (group: CategoryGroup) => void;
+  onActivateSubcategory: (id: string) => void;
+  onClearQuery: () => void;
+  onCreateCategory?: (name?: string) => void;
+  listRef: React.RefObject<HTMLDivElement | null>;
+  dataTestId: string;
+}
+
+function LoadingRows(): React.JSX.Element {
+  return (
+    <>
+      {Array.from({ length: SKELETON_ROWS }, (_unused, index) => (
+        <Skeleton key={index} variant="rounded" sx={skeletonSx} />
+      ))}
+    </>
+  );
+}
+
+/** No categories exist at all — an onboarding moment, not an error. */
+function EmptyCatalogue({
+  onCreateCategory,
+  dataTestId,
+}: {
+  onCreateCategory?: (name?: string) => void;
+  dataTestId: string;
+}): React.JSX.Element {
+  return (
+    <Box sx={emptySx} data-testid={`${dataTestId}-empty-catalogue`}>
+      <strong>Nenhuma categoria ainda</strong>
+      <p>Categorias organizam o cardápio e os filtros da loja.</p>
+      {onCreateCategory && (
+        <Button variant="contained" size="small" sx={SENTENCE_CASE} onClick={() => onCreateCategory()}>
+          Criar categoria
+        </Button>
+      )}
+    </Box>
+  );
+}
+
+/** The search found nothing — offer creation, or the way back. */
+function NoResults({
+  query,
+  onClearQuery,
+  onCreateCategory,
+  dataTestId,
+}: {
+  query: string;
+  onClearQuery: () => void;
+  onCreateCategory?: (name?: string) => void;
+  dataTestId: string;
+}): React.JSX.Element {
+  return (
+    <Box sx={emptySx} data-testid={`${dataTestId}-no-results`}>
+      <strong>Nada encontrado para “{query}”</strong>
+      <p>Tente outro termo ou verifique a grafia.</p>
+      <Box sx={{ display: 'flex', gap: '6px', justifyContent: 'center' }}>
+        <Button variant="outlined" size="small" sx={SENTENCE_CASE} onClick={onClearQuery}>
+          Limpar busca
+        </Button>
+        {onCreateCategory && (
+          <Button
+            variant="contained"
+            size="small"
+            sx={SENTENCE_CASE}
+            data-testid={`${dataTestId}-create`}
+            onClick={() => onCreateCategory(query.trim())}
+          >
+            Criar “{query.trim()}”
+          </Button>
+        )}
+      </Box>
+    </Box>
+  );
+}
+
+/** One group: its heading or head row, then whichever children are visible. */
+function CategoryGroupRows({
+  group,
+  props,
+}: {
+  group: CategoryGroup;
+  props: PanelListProps;
+}): React.JSX.Element {
+  const { draft, query, single, allowParentSelection, rowIds, activeIndex, sheet } = props;
+  const categoryId = group.category.id;
+  const expanded = props.isExpanded(categoryId);
+  const asHeading = single && !allowParentSelection;
+  const selectedCount = group.subcategories.filter((sub) => draft.has(sub.id)).length;
+
+  return (
+    <>
+      {asHeading ? (
+        <CategorySectionHeading option={group.category} query={query} />
+      ) : (
+        <CategoryHeadRow
+          option={group.category}
+          query={query}
+          expanded={expanded}
+          active={rowIds[activeIndex] === categoryId}
+          sheet={sheet}
+          checkState={
+            allowParentSelection ? categoryCheckState(group, draft) : undefined
+          }
+          selectedCount={selectedCount}
+          showCounts={props.showCounts}
+          onToggleExpanded={() => props.onToggleExpanded(categoryId)}
+          onActivate={() => props.onActivateCategory(group)}
+          dataTestId={props.dataTestId}
+        />
+      )}
+      {(expanded || asHeading) &&
+        group.subcategories.map((sub) => (
+          <SubcategoryRow
+            key={sub.id}
+            option={sub}
+            query={query}
+            selected={draft.has(sub.id)}
+            active={rowIds[activeIndex] === sub.id}
+            sheet={sheet}
+            single={single}
+            showCounts={props.showCounts}
+            onActivate={() => props.onActivateSubcategory(sub.id)}
+            dataTestId={props.dataTestId}
+          />
+        ))}
+    </>
+  );
+}
+
+/** The scrolling body of the panel, including its three non-list states. */
+export function CategoryPanelList(props: PanelListProps): React.JSX.Element {
+  const { groups, loading, query, listRef, sheet, dataTestId } = props;
+
+  const body = (): React.JSX.Element => {
+    if (loading) return <LoadingRows />;
+    if (groups.length === 0 && query.trim().length > 0) {
+      return (
+        <NoResults
+          query={query}
+          onClearQuery={props.onClearQuery}
+          onCreateCategory={props.onCreateCategory}
+          dataTestId={dataTestId}
+        />
+      );
+    }
+    if (groups.length === 0) {
+      return (
+        <EmptyCatalogue
+          onCreateCategory={props.onCreateCategory}
+          dataTestId={dataTestId}
+        />
+      );
+    }
+    return (
+      <>
+        {groups.map((group) => (
+          <CategoryGroupRows key={group.category.id} group={group} props={props} />
+        ))}
+      </>
+    );
+  };
+
+  return (
+    <Box
+      ref={listRef}
+      role="listbox"
+      aria-multiselectable={props.single ? undefined : true}
+      tabIndex={-1}
+      data-testid={`${dataTestId}-list`}
+      sx={listSx(sheet)}
+    >
+      {body()}
+    </Box>
+  );
+}

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

@@ -0,0 +1,56 @@
+'use client';
+
+import { Drawer, Popover } from '@mui/material';
+
+/** Chrome-free surface props: the panel draws its own border and shadow. */
+const BARE_PAPER = { background: 'transparent', boxShadow: 'none' } as const;
+
+interface SurfaceProps {
+  open: boolean;
+  /** True below the sheet breakpoint — anchor to the bottom edge instead. */
+  sheet: boolean;
+  anchorEl: HTMLElement | null;
+  onClose: () => void;
+  children: React.ReactNode;
+}
+
+/**
+ * Where the panel lives: anchored under the trigger on a pointer, or a bottom
+ * sheet on a phone.
+ *
+ * Both surfaces are modal, which is what gives the panel its dismiss-on-outside,
+ * Esc handling and focus containment for free rather than hand-rolled.
+ */
+export function CategoryPanelSurface({
+  open,
+  sheet,
+  anchorEl,
+  onClose,
+  children,
+}: SurfaceProps): React.JSX.Element {
+  if (sheet) {
+    return (
+      <Drawer
+        anchor="bottom"
+        open={open}
+        onClose={onClose}
+        slotProps={{ paper: { sx: BARE_PAPER } }}
+      >
+        {children}
+      </Drawer>
+    );
+  }
+  return (
+    <Popover
+      open={open}
+      anchorEl={anchorEl}
+      onClose={onClose}
+      anchorOrigin={{ vertical: 'bottom', horizontal: 'left' }}
+      transformOrigin={{ vertical: 'top', horizontal: 'left' }}
+      marginThreshold={8}
+      slotProps={{ paper: { sx: { ...BARE_PAPER, marginTop: '6px', overflow: 'visible' } } }}
+    >
+      {children}
+    </Popover>
+  );
+}

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

@@ -0,0 +1,69 @@
+'use client';
+
+import { Box } from '@mui/material';
+import { useMemo } from 'react';
+
+import { collectLeafIds } from './category-tree';
+import type { CategorySelectState } from './useCategorySelect';
+
+/** The panel's text-button treatment. */
+const linkButtonSx = {
+  background: 'none',
+  border: 0,
+  padding: 0,
+  font: 'inherit',
+  fontSize: 12,
+  color: 'primary.main',
+  cursor: 'pointer',
+  fontWeight: 550,
+  '&:hover': { textDecoration: 'underline' },
+  '&:disabled': { color: 'text.disabled', cursor: 'default', textDecoration: 'none' },
+} as const;
+
+/**
+ * Bulk actions for multi-select: mark everything, and fold everything.
+ *
+ * Both labels flip to their inverse once the action is spent ("Desmarcar tudo",
+ * "Recolher tudo"), so the control always says what pressing it will do rather
+ * than what state the list is in.
+ */
+export function CategoryQuickActions({
+  state,
+  dataTestId,
+}: {
+  state: CategorySelectState;
+  dataTestId: string;
+}): React.JSX.Element {
+  const allLeafIds = useMemo(() => collectLeafIds(state.allGroups), [state.allGroups]);
+  const everythingPicked = allLeafIds.length > 0 && state.draft.size >= allLeafIds.length;
+  const allExpanded =
+    state.allGroups.length > 0 &&
+    state.allGroups.every((group) => state.isExpanded(group.category.id));
+
+  return (
+    <>
+      <Box
+        component="button"
+        type="button"
+        disabled={allLeafIds.length === 0}
+        data-testid={`${dataTestId}-select-all`}
+        sx={linkButtonSx}
+        onClick={() => state.setDraft(everythingPicked ? new Set() : new Set(allLeafIds))}
+      >
+        {everythingPicked ? 'Desmarcar tudo' : 'Marcar tudo'}
+      </Box>
+      <Box component="span" sx={{ color: 'divider' }}>
+        ·
+      </Box>
+      <Box
+        component="button"
+        type="button"
+        data-testid={`${dataTestId}-expand-all`}
+        sx={linkButtonSx}
+        onClick={() => state.setAllExpanded(!allExpanded)}
+      >
+        {allExpanded ? 'Recolher tudo' : 'Expandir tudo'}
+      </Box>
+    </>
+  );
+}

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

@@ -0,0 +1,211 @@
+'use client';
+
+import { Box } from '@mui/material';
+
+import { CheckGlyph, DisclosureGlyph } from './CategoryIcons';
+import { highlightSegments, type CategoryCheckState } from './category-tree';
+import {
+  checkboxBarSx,
+  checkboxSx,
+  chevronButtonSx,
+  markSx,
+  METRICS,
+  radioSx,
+  rowMetaSx,
+  rowNameSx,
+  rowSx,
+  sectionHeadSx,
+} from './CategorySelect.styles';
+import type { CategorySelectOption } from './CategorySelect.types';
+
+/** A label with the search hit marked. */
+export function HighlightedName({
+  text,
+  query,
+}: {
+  text: string;
+  query: string;
+}): React.JSX.Element {
+  const segments = highlightSegments(text, query);
+  return (
+    <>
+      {segments.map((segment, index) =>
+        segment.match ? (
+          <Box component="mark" key={`${segment.text}-${index}`} sx={markSx}>
+            {segment.text}
+          </Box>
+        ) : (
+          <span key={`${segment.text}-${index}`}>{segment.text}</span>
+        ),
+      )}
+    </>
+  );
+}
+
+/** Tri-state checkbox. `partial` draws the bar the prototype uses for "some". */
+export function CategoryCheckbox({ state }: { state: CategoryCheckState }): React.JSX.Element {
+  return (
+    <Box sx={(theme) => checkboxSx(theme, state)} aria-hidden="true">
+      {state === 'on' && <CheckGlyph />}
+      {state === 'partial' && <Box sx={checkboxBarSx} />}
+    </Box>
+  );
+}
+
+export function CategoryRadio({ on }: { on: boolean }): React.JSX.Element {
+  return <Box sx={(theme) => radioSx(theme, on)} aria-hidden="true" />;
+}
+
+interface CategoryHeadRowProps {
+  option: CategorySelectOption;
+  query: string;
+  expanded: boolean;
+  active: boolean;
+  sheet: boolean;
+  /** Absent in leaf-only mode, where the category is a heading with no checkbox. */
+  checkState?: CategoryCheckState;
+  selectedCount: number;
+  showCounts: boolean;
+  onToggleExpanded: () => void;
+  onActivate: () => void;
+  dataTestId: string;
+}
+
+/** The trailing number: how many children are picked, else the item count. */
+function rowMeta(
+  selectedCount: number,
+  showCounts: boolean,
+  count: number | undefined,
+): { text: string; selected: boolean } | null {
+  if (selectedCount > 0) return { text: String(selectedCount), selected: true };
+  if (showCounts && count !== undefined) return { text: String(count), selected: false };
+  return null;
+}
+
+/**
+ * A top-level category row: disclosure chevron, optional checkbox, name, meta.
+ *
+ * The chevron is its OWN button inside the row button — clicking it only folds,
+ * while clicking the row does the row's job (expand as a heading, or tick when
+ * parents are selectable).
+ */
+export function CategoryHeadRow({
+  option,
+  query,
+  expanded,
+  active,
+  sheet,
+  checkState,
+  selectedCount,
+  showCounts,
+  onToggleExpanded,
+  onActivate,
+  dataTestId,
+}: CategoryHeadRowProps): React.JSX.Element {
+  const meta = rowMeta(selectedCount, showCounts, option.count);
+  return (
+    <Box
+      component="div"
+      role={checkState ? 'option' : 'button'}
+      aria-selected={checkState ? checkState === 'on' : undefined}
+      aria-expanded={expanded}
+      data-testid={`${dataTestId}-category-${option.id}`}
+      sx={(theme) => rowSx(theme, active, sheet)}
+      onClick={onActivate}
+    >
+      <Box
+        component="button"
+        type="button"
+        tabIndex={-1}
+        aria-label={`${expanded ? 'Recolher' : 'Expandir'} ${option.name}`}
+        data-testid={`${dataTestId}-expand-${option.id}`}
+        sx={(theme) => chevronButtonSx(theme, expanded)}
+        onClick={(event: React.MouseEvent) => {
+          event.stopPropagation();
+          onToggleExpanded();
+        }}
+      >
+        <DisclosureGlyph />
+      </Box>
+      {checkState ? (
+        <CategoryCheckbox state={checkState} />
+      ) : (
+        <Box sx={{ width: METRICS.boxSize, flex: '0 0 auto' }} />
+      )}
+      <Box component="span" sx={(theme) => rowNameSx(theme, true)}>
+        <HighlightedName text={option.name} query={query} />
+      </Box>
+      {meta && (
+        <Box component="span" sx={(theme) => rowMetaSx(theme, meta.selected)}>
+          {meta.text}
+        </Box>
+      )}
+    </Box>
+  );
+}
+
+interface SubcategoryRowProps {
+  option: CategorySelectOption;
+  query: string;
+  selected: boolean;
+  active: boolean;
+  sheet: boolean;
+  /** Single-select mode draws a radio; multi-select draws a checkbox. */
+  single: boolean;
+  showCounts: boolean;
+  onActivate: () => void;
+  dataTestId: string;
+}
+
+export function SubcategoryRow({
+  option,
+  query,
+  selected,
+  active,
+  sheet,
+  single,
+  showCounts,
+  onActivate,
+  dataTestId,
+}: SubcategoryRowProps): React.JSX.Element {
+  return (
+    <Box
+      component="div"
+      role="option"
+      aria-selected={selected}
+      data-testid={`${dataTestId}-option-${option.id}`}
+      sx={(theme) => ({ ...rowSx(theme, active, sheet), paddingLeft: '14px' })}
+      onClick={onActivate}
+    >
+      <Box sx={{ width: METRICS.chevronButton, flex: '0 0 auto' }} />
+      {single ? (
+        <CategoryRadio on={selected} />
+      ) : (
+        <CategoryCheckbox state={selected ? 'on' : 'off'} />
+      )}
+      <Box component="span" sx={(theme) => rowNameSx(theme, false)}>
+        <HighlightedName text={option.name} query={query} />
+      </Box>
+      {showCounts && option.count !== undefined && (
+        <Box component="span" sx={(theme) => rowMetaSx(theme, false)}>
+          {option.count}
+        </Box>
+      )}
+    </Box>
+  );
+}
+
+/** The category as a non-interactive heading (single-select, leaf-only). */
+export function CategorySectionHeading({
+  option,
+  query,
+}: {
+  option: CategorySelectOption;
+  query: string;
+}): React.JSX.Element {
+  return (
+    <Box sx={sectionHeadSx}>
+      <HighlightedName text={option.name} query={query} />
+    </Box>
+  );
+}

package/src/components/form/CategorySelect/CategorySelect.md

@@ -0,0 +1,134 @@
+# CategorySelect
+
+A hierarchical category picker: **categories are the frame, subcategories are what
+you pick.**
+
+```tsx
+import { CategorySelect } from '@12-apps/ui/form/CategorySelect';
+```
+
+## Why it exists
+
+A flat select over a two-level catalogue forces an ambiguity on the user: ticking
+"Bebidas" might mean the category itself or everything under it, and there is no
+way to tell which from looking. This component removes the question by making the
+category a heading and the subcategory the selectable thing — and, where a caller
+genuinely needs "the whole category" as a value, by making that an explicit opt-in
+(`allowParentSelection`) with a tri-state checkbox that says so.
+
+## Options
+
+Pass the catalogue **flat, carrying `parentId`** — the shape the API already
+returns. The component nests it internally, memoised.
+
+```tsx
+const options = [
+  { id: 'beb', name: 'Bebidas', count: 214 },
+  { id: 'beb.agua', name: 'Águas', parentId: 'beb', count: 38 },
+  { id: 'beb.refri', name: 'Refrigerantes', parentId: 'beb', count: 52 },
+];
+```
+
+Never pre-indent `name` (`"— Águas"`). The row draws the nesting; a baked-in dash
+travels everywhere the label goes, including the closed trigger.
+
+A category with no children is selectable in its own right. An option whose
+`parentId` matches nothing is promoted to top level rather than dropped, so a
+partial payload never makes a category invisible.
+
+## The two modes
+
+### `multi` — the filter
+
+Ticks accumulate in a **draft**; `onChange` fires only when Apply is pressed. This
+is the point of the mode: the list behind the panel does not refetch on every
+click, and dismissing the panel discards.
+
+```tsx
+const [categories, setCategories] = useState<string[]>([]);
+
+<CategorySelect options={options} value={categories} onChange={setCategories} />;
+```
+
+### `single` — the "move to…" picker
+
+Choosing a row commits immediately; there is nothing to batch. The trigger then
+reads `Pai › Filha`, so the chosen leaf keeps its context.
+
+```tsx
+<CategorySelect
+  mode="single"
+  label="Categoria"
+  options={options}
+  value={categoryId}
+  onChange={setCategoryId}
+/>
+```
+
+## Behaviour worth knowing
+
+- **Opens fully expanded.** Nothing a search could match hides behind a
+  disclosure.
+- **Selected categories pin above the list.** They survive scrolling and
+  searching — a tick made at the bottom of a ten-category tree does not vanish
+  the moment you look for the next one.
+- **Search is accent-insensitive, both directions.** `agua` finds `Águas`;
+  `graos` finds `Grãos e farináceos`. The hit is marked, and it always renders
+  under its parent, which is what tells `Massas` (mercearia) from `Massas`
+  (pratos principais).
+- **A fully selected category collapses to one chip** bearing the category name,
+  rather than one chip per child.
+- **Below 480px the panel becomes a bottom sheet.**
+
+## Keyboard
+
+| Key | Does |
+| --- | --- |
+| `↑` `↓` | Move the cursor |
+| `→` | Expand the category |
+| `←` | Collapse it, or jump from a subcategory to its parent |
+| `Space` | Mark the row (single-select: pick it) |
+| `Enter` | Apply (single-select: pick) |
+| `Esc` | Cancel, returning focus to the trigger |
+
+`Space`, `←` and `→` belong to the search field **only while it holds text**. The
+panel opens focused on an empty field, so yielding them unconditionally would
+leave the tree undrivable from the keyboard; type one character and they revert to
+the field.
+
+## Styling
+
+Geometry is the design's absolute pixels — 38px trigger, 340px panel, 36px rows,
+1.5px checkbox borders. Those are deliberately not derived from `theme.spacing`,
+which is an 8px grid and would round the design away.
+
+**Colours come from the theme.** A tenant can white-label the palette, and the
+library ships a dark mode; a hard-coded indigo would survive the rebrand while the
+rest of the screen changed. On the default light theme the tokens resolve to the
+design's own values.
+
+## Props
+
+| Prop | Type | Default | |
+| --- | --- | --- | --- |
+| `options` | `CategorySelectOption[]` | — | Flat, with `parentId` |
+| `mode` | `'multi' \| 'single'` | `'multi'` | |
+| `value` | `string[]` / `string \| null` | — | Shape follows `mode` |
+| `onChange` | `(next) => void` | — | Fires on Apply / on pick |
+| `label` | `string` | — | Rendered above the trigger |
+| `placeholder` | `string` | `'Categoria'` / `'Mover para…'` | |
+| `error` | `string` | — | Message + errored styling |
+| `disabled` | `boolean` | `false` | |
+| `loading` | `boolean` | `false` | Skeleton rows |
+| `fullWidth` | `boolean` | `false` | |
+| `showCounts` | `boolean` | `false` | Trailing `count` per row |
+| `allowParentSelection` | `boolean` | `false` | Makes categories selectable |
+| `onCreateCategory` | `() => void` | — | CTA on the empty catalogue |
+| `dataTestId` | `string` | `'category-select'` | |
+
+## Test ids
+
+Derived from `dataTestId`: `-trigger`, `-count`, `-clear-trigger`, `-panel`,
+`-search`, `-search-clear`, `-select-all`, `-expand-all`, `-pinned`,
+`-unpin-<id>`, `-list`, `-category-<id>`, `-expand-<id>`, `-option-<id>`,
+`-footer`, `-clear`, `-apply`, `-cancel`, `-no-results`, `-empty-catalogue`.