@12-apps/ui 4.0.1 → 4.1.0

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

@@ -0,0 +1,109 @@
+'use client';
+
+import { Box } from '@mui/material';
+
+import { CaretGlyph } from './CategoryIcons';
+import {
+  triggerChevronSx,
+  triggerClearSx,
+  triggerCountSx,
+  triggerSx,
+} from './CategorySelect.styles';
+
+interface CategoryTriggerProps {
+  /** Text shown when nothing is selected. */
+  placeholder: string;
+  /** Resolved label when there IS a selection (single mode shows "Pai › Filha"). */
+  selectionLabel?: string;
+  /** Selection size — rendered as the count pill in multi-select. */
+  count?: number;
+  open: boolean;
+  disabled?: boolean;
+  fullWidth: boolean;
+  onOpen: () => void;
+  /** Absent when there is nothing to clear. */
+  onClear?: () => void;
+  triggerRef: React.RefObject<HTMLButtonElement | null>;
+  dataTestId: string;
+}
+
+/**
+ * The closed control.
+ *
+ * The clear (×) is a real button nested in the trigger button, so "remove the
+ * filter" is one click from the closed state — without it, clearing means open,
+ * find Clear, apply. Its click is stopped from reaching the trigger, which would
+ * otherwise open the panel on the way out.
+ */
+export function CategoryTrigger({
+  placeholder,
+  selectionLabel,
+  count,
+  open,
+  disabled,
+  fullWidth,
+  onOpen,
+  onClear,
+  triggerRef,
+  dataTestId,
+}: CategoryTriggerProps): React.JSX.Element {
+  const hasSelection = Boolean(selectionLabel) || (count ?? 0) > 0;
+  return (
+    <Box
+      component="button"
+      type="button"
+      ref={triggerRef}
+      disabled={disabled}
+      aria-haspopup="dialog"
+      aria-expanded={open}
+      data-testid={`${dataTestId}-trigger`}
+      onClick={onOpen}
+      sx={(theme) => ({
+        ...triggerSx(theme, hasSelection, open),
+        width: fullWidth ? '100%' : 'auto',
+      })}
+    >
+      <Box
+        component="span"
+        sx={{
+          whiteSpace: 'nowrap',
+          overflow: 'hidden',
+          textOverflow: 'ellipsis',
+          maxWidth: 190,
+          flex: fullWidth ? 1 : '0 1 auto',
+          textAlign: 'left',
+        }}
+      >
+        {selectionLabel ?? placeholder}
+      </Box>
+      {count !== undefined && count > 0 && (
+        <Box component="span" sx={triggerCountSx} data-testid={`${dataTestId}-count`}>
+          {count}
+        </Box>
+      )}
+      {hasSelection && onClear && (
+        <Box
+          component="span"
+          role="button"
+          tabIndex={0}
+          aria-label="Limpar seleção"
+          data-testid={`${dataTestId}-clear-trigger`}
+          sx={triggerClearSx}
+          onClick={(event: React.MouseEvent) => {
+            event.stopPropagation();
+            onClear();
+          }}
+          onKeyDown={(event: React.KeyboardEvent) => {
+            if (event.key !== 'Enter' && event.key !== ' ') return;
+            event.preventDefault();
+            event.stopPropagation();
+            onClear();
+          }}
+        >
+          ×
+        </Box>
+      )}
+      <CaretGlyph style={triggerChevronSx(open) as React.CSSProperties} />
+    </Box>
+  );
+}

package/src/components/form/CategorySelect/category-keyboard.ts

@@ -0,0 +1,136 @@
+import type { CategoryRowRef } from './category-tree';
+import type { CategoryGroup } from './CategorySelect.types';
+
+/** What a key handler is allowed to do to the panel. */
+export interface CategoryKeyContext {
+  rows: CategoryRowRef[];
+  activeIndex: number;
+  groups: CategoryGroup[];
+  /** Single-select mode picks on Enter/Space instead of toggling a draft. */
+  single: boolean;
+  /** Categories are headings, not checkboxes, unless parents are selectable. */
+  allowParentSelection: boolean;
+  setActiveIndex: (next: number) => void;
+  toggleExpanded: (categoryId: string) => void;
+  expand: (categoryId: string) => void;
+  collapse: (categoryId: string) => void;
+  toggleCategory: (group: CategoryGroup) => void;
+  toggleSubcategory: (id: string) => void;
+  commit: () => void;
+  cancel: () => void;
+  pick: (id: string) => void;
+}
+
+/** The row under the keyboard cursor, if the cursor is on one. */
+function activeRow(context: CategoryKeyContext): CategoryRowRef | undefined {
+  return context.activeIndex >= 0 ? context.rows[context.activeIndex] : undefined;
+}
+
+function groupOf(context: CategoryKeyContext, id: string): CategoryGroup | undefined {
+  return context.groups.find((group) => group.category.id === id);
+}
+
+function moveCursor(context: CategoryKeyContext, delta: number): void {
+  const { rows, activeIndex } = context;
+  if (rows.length === 0) return;
+  const next =
+    delta > 0
+      ? Math.min(rows.length - 1, activeIndex + 1)
+      : Math.max(0, activeIndex - 1);
+  context.setActiveIndex(next);
+}
+
+/** → opens a category. On a subcategory it is a no-op: there is nothing deeper. */
+function handleRight(context: CategoryKeyContext): void {
+  const row = activeRow(context);
+  if (row?.kind === 'category') context.expand(row.id);
+}
+
+/** ← collapses a category, or walks a subcategory back up to its parent. */
+function handleLeft(context: CategoryKeyContext): void {
+  const row = activeRow(context);
+  if (!row) return;
+  if (row.kind === 'category') {
+    context.collapse(row.id);
+    return;
+  }
+  if (!row.parentId) return;
+  context.collapse(row.parentId);
+  const parentIndex = context.rows.findIndex(
+    (candidate) => candidate.kind === 'category' && candidate.id === row.parentId,
+  );
+  if (parentIndex >= 0) context.setActiveIndex(parentIndex);
+}
+
+/**
+ * Space marks. On a category that is only a HEADING it expands instead — the
+ * row has no checkbox, so "mark" has nothing to mean there.
+ */
+function handleSpace(context: CategoryKeyContext): void {
+  const row = activeRow(context);
+  if (!row) return;
+  if (context.single) {
+    context.pick(row.id);
+    return;
+  }
+  if (row.kind === 'subcategory') {
+    context.toggleSubcategory(row.id);
+    return;
+  }
+  const group = groupOf(context, row.id);
+  if (!group) return;
+  if (context.allowParentSelection) context.toggleCategory(group);
+  else context.toggleExpanded(row.id);
+}
+
+function handleEnter(context: CategoryKeyContext): void {
+  const row = activeRow(context);
+  if (context.single) {
+    if (row) context.pick(row.id);
+    return;
+  }
+  context.commit();
+}
+
+/** Key → behaviour. A map keeps this dispatch flat instead of a long if-chain. */
+const HANDLERS: Record<string, (context: CategoryKeyContext) => void> = {
+  ArrowDown: (context) => moveCursor(context, 1),
+  ArrowUp: (context) => moveCursor(context, -1),
+  ArrowRight: handleRight,
+  ArrowLeft: handleLeft,
+  ' ': handleSpace,
+  Enter: handleEnter,
+  Escape: (context) => context.cancel(),
+};
+
+/**
+ * Keys the SEARCH BOX has a claim on: Space types a space, and the horizontal
+ * arrows move the caret.
+ *
+ * They are only yielded while the field actually holds text. The panel opens
+ * with focus in an EMPTY search box, so yielding unconditionally — as the
+ * prototype does — would make Space and ←/→ dead on arrival for anyone driving
+ * the tree from the keyboard, which is most of the point of having it. With no
+ * text there is no caret to move and no word to space, so the tree takes them;
+ * type one character and they revert to the field.
+ */
+const TEXT_ENTRY_KEYS = new Set([' ', 'ArrowLeft', 'ArrowRight']);
+
+/**
+ * Drive the tree from the keyboard.
+ *
+ * Returns `true` when the key was consumed, so the caller can `preventDefault`
+ * only for keys this actually handled — an unhandled key must still reach the
+ * search input untouched.
+ */
+export function handleCategoryKeyDown(
+  key: string,
+  editingSearchText: boolean,
+  context: CategoryKeyContext,
+): boolean {
+  if (editingSearchText && TEXT_ENTRY_KEYS.has(key)) return false;
+  const handler = HANDLERS[key];
+  if (!handler) return false;
+  handler(context);
+  return true;
+}

package/src/components/form/CategorySelect/category-tree.ts

@@ -0,0 +1,210 @@
+import type {
+  CategoryGroup,
+  CategorySelectionChip,
+  CategorySelectOption,
+} from './CategorySelect.types';
+
+/**
+ * Fold a string to its comparison form: no diacritics, lower case.
+ *
+ * Portuguese category names are full of them ("Águas", "Cápsulas", "Grãos"), and
+ * an admin typing "agua" or "graos" on a hurried phone keyboard means the same
+ * thing. Comparing folded forms on both sides makes the search accent-blind in
+ * both directions.
+ */
+export function foldText(text: string): string {
+  return text
+    .normalize('NFD')
+    .replace(/[\u0300-\u036f]/g, '')
+    .toLowerCase();
+}
+
+/**
+ * Group a flat `parentId` list into top level + children, preserving input order.
+ *
+ * An option whose `parentId` names no top-level row is promoted to top level
+ * rather than dropped — a category is never invisible just because its parent
+ * was filtered out of the payload, or because the tree is deeper than two levels.
+ */
+export function buildCategoryGroups(options: CategorySelectOption[]): CategoryGroup[] {
+  const roots = options.filter((option) => !option.parentId);
+  const rootIds = new Set(roots.map((root) => root.id));
+  const groups = new Map<string, CategoryGroup>(
+    roots.map((root) => [root.id, { category: root, subcategories: [] }]),
+  );
+  const orphans: CategoryGroup[] = [];
+
+  options.forEach((option) => {
+    if (!option.parentId) return;
+    const parent = groups.get(option.parentId);
+    if (parent) {
+      parent.subcategories.push(option);
+      return;
+    }
+    if (!rootIds.has(option.id)) orphans.push({ category: option, subcategories: [] });
+  });
+
+  return [...groups.values(), ...orphans];
+}
+
+/** Every selectable leaf id across all groups, in display order. */
+export function collectLeafIds(groups: CategoryGroup[]): string[] {
+  return groups.flatMap((group) =>
+    group.subcategories.length > 0
+      ? group.subcategories.map((sub) => sub.id)
+      : [group.category.id],
+  );
+}
+
+/** The leaves a category stands for — its subcategories, or itself when childless. */
+export function leavesOf(group: CategoryGroup): string[] {
+  return group.subcategories.length > 0
+    ? group.subcategories.map((sub) => sub.id)
+    : [group.category.id];
+}
+
+export type CategoryCheckState = 'off' | 'partial' | 'on';
+
+/** Whether none, some, or all of a category's leaves are selected. */
+export function categoryCheckState(
+  group: CategoryGroup,
+  selected: ReadonlySet<string>,
+): CategoryCheckState {
+  const leaves = leavesOf(group);
+  const hits = leaves.filter((id) => selected.has(id)).length;
+  if (hits === 0) return 'off';
+  return hits === leaves.length ? 'on' : 'partial';
+}
+
+/** Select every leaf of a category, or clear them all when already complete. */
+export function toggleCategoryLeaves(
+  group: CategoryGroup,
+  selected: ReadonlySet<string>,
+): Set<string> {
+  const next = new Set(selected);
+  const leaves = leavesOf(group);
+  const turningOff = categoryCheckState(group, selected) === 'on';
+  leaves.forEach((id) => (turningOff ? next.delete(id) : next.add(id)));
+  return next;
+}
+
+/** Add an id when absent, remove it when present. */
+export function toggleLeaf(id: string, selected: ReadonlySet<string>): Set<string> {
+  const next = new Set(selected);
+  if (!next.delete(id)) next.add(id);
+  return next;
+}
+
+/**
+ * Collapse a raw id set into the chips a human reads: a category that is fully
+ * selected becomes ONE chip bearing the category's name, rather than one chip
+ * per subcategory — "Bebidas" instead of six drinks.
+ */
+export function summarizeSelection(
+  groups: CategoryGroup[],
+  selected: ReadonlySet<string>,
+): CategorySelectionChip[] {
+  return groups.flatMap((group): CategorySelectionChip[] => {
+    const state = categoryCheckState(group, selected);
+    if (state === 'off') return [];
+    if (state === 'on') {
+      return [{ id: group.category.id, label: group.category.name, whole: true }];
+    }
+    return group.subcategories
+      .filter((sub) => selected.has(sub.id))
+      .map((sub) => ({ id: sub.id, label: sub.name, whole: false }));
+  });
+}
+
+/**
+ * Drop the leaves a chip stands for. A `whole` chip removes the whole category;
+ * any other chip removes just that leaf.
+ */
+export function removeChip(
+  groups: CategoryGroup[],
+  chipId: string,
+  selected: ReadonlySet<string>,
+): Set<string> {
+  const next = new Set(selected);
+  const group = groups.find((candidate) => candidate.category.id === chipId);
+  if (group) {
+    leavesOf(group).forEach((id) => next.delete(id));
+    return next;
+  }
+  next.delete(chipId);
+  return next;
+}
+
+/**
+ * Search across BOTH levels, keeping every hit under its parent.
+ *
+ * A category that matches keeps all of its subcategories, so "Bebidas" shows the
+ * whole group. A category that does not match keeps only the subcategories that
+ * do — the hit still arrives with its parent visible above it, which is the
+ * context that tells "Massas" (mercearia) from "Massas" (pratos principais).
+ */
+export function filterCategoryGroups(groups: CategoryGroup[], query: string): CategoryGroup[] {
+  const needle = foldText(query.trim());
+  if (!needle) return groups;
+  return groups.flatMap((group) => {
+    if (foldText(group.category.name).includes(needle)) return [group];
+    const subcategories = group.subcategories.filter((sub) =>
+      foldText(sub.name).includes(needle),
+    );
+    return subcategories.length > 0 ? [{ category: group.category, subcategories }] : [];
+  });
+}
+
+/** A run of text, flagged when it is the part that matched the query. */
+interface HighlightSegment {
+  text: string;
+  match: boolean;
+}
+
+/**
+ * Split a label around the query hit so the view can mark it.
+ *
+ * Slicing uses indices from the FOLDED text but cuts the ORIGINAL, which is safe
+ * because folding is per-character here: NFD-stripping combining marks and
+ * lower-casing both preserve offsets for the scripts these names use.
+ */
+export function highlightSegments(text: string, query: string): HighlightSegment[] {
+  const needle = foldText(query.trim());
+  if (!needle) return [{ text, match: false }];
+  const at = foldText(text).indexOf(needle);
+  if (at < 0) return [{ text, match: false }];
+  return [
+    { text: text.slice(0, at), match: false },
+    { text: text.slice(at, at + needle.length), match: true },
+    { text: text.slice(at + needle.length), match: false },
+  ].filter((segment) => segment.text.length > 0);
+}
+
+/** A flattened row, so keyboard navigation can walk what is actually on screen. */
+export interface CategoryRowRef {
+  kind: 'category' | 'subcategory';
+  id: string;
+  /** Owning category id — lets ← jump from a subcategory back to its parent. */
+  parentId?: string;
+}
+
+/** The visible rows, in order, honouring which categories are expanded. */
+export function flattenRows(
+  groups: CategoryGroup[],
+  isExpanded: (categoryId: string) => boolean,
+): CategoryRowRef[] {
+  return groups.flatMap((group) => {
+    const head: CategoryRowRef = { kind: 'category', id: group.category.id };
+    if (!isExpanded(group.category.id)) return [head];
+    return [
+      head,
+      ...group.subcategories.map(
+        (sub): CategoryRowRef => ({
+          kind: 'subcategory',
+          id: sub.id,
+          parentId: group.category.id,
+        }),
+      ),
+    ];
+  });
+}

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

@@ -0,0 +1,19 @@
+export { CategorySelect } from './CategorySelect';
+export type {
+  CategoryGroup,
+  CategoryMultiSelectProps,
+  CategorySelectBaseProps,
+  CategorySelectionChip,
+  CategorySelectOption,
+  CategorySelectProps,
+  CategorySingleSelectProps,
+} from './CategorySelect.types';
+export {
+  buildCategoryGroups,
+  categoryCheckState,
+  collectLeafIds,
+  filterCategoryGroups,
+  foldText,
+  leavesOf,
+  summarizeSelection,
+} from './category-tree';

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

@@ -0,0 +1,101 @@
+import { useCallback, useMemo } from 'react';
+
+import type { CategoryGroup, CategorySelectProps } from './CategorySelect.types';
+import type { CategorySelectState } from './useCategorySelect';
+
+/** The verbs a row, a footer button or a key press can invoke. */
+export interface CategoryActions {
+  /** Publish the draft to the caller and close (multi-select). */
+  commit: () => void;
+  /** Choose one id and close (single-select). */
+  pick: (id: string) => void;
+  /** Close without publishing, returning focus to the trigger. */
+  cancel: () => void;
+  /** Empty the APPLIED selection straight from the closed trigger. */
+  clearSelection: () => void;
+  activateCategory: (group: CategoryGroup) => void;
+  activateSubcategory: (id: string) => void;
+}
+
+interface UseCategoryCommitArgs {
+  props: CategorySelectProps;
+  state: CategorySelectState;
+  single: boolean;
+  allowParentSelection: boolean;
+}
+
+/**
+ * The commit semantics, which are the one thing the two modes genuinely differ
+ * on: multi-select batches into a draft and publishes on Apply, single-select
+ * publishes the moment a row is chosen.
+ */
+export function useCategoryCommit({
+  props,
+  state,
+  single,
+  allowParentSelection,
+}: UseCategoryCommitArgs): CategoryActions {
+  const { closePanel, triggerRef, toggleCategory, toggleSubcategory, toggleExpanded } = state;
+
+  const closeAndRefocus = useCallback(() => {
+    closePanel();
+    triggerRef.current?.focus();
+  }, [closePanel, triggerRef]);
+
+  const commit = useCallback(() => {
+    if (props.mode === 'single') return;
+    props.onChange([...state.draft]);
+    closeAndRefocus();
+  }, [props, state.draft, closeAndRefocus]);
+
+  const pick = useCallback(
+    (id: string) => {
+      if (props.mode !== 'single') return;
+      props.onChange(id);
+      closeAndRefocus();
+    },
+    [props, closeAndRefocus],
+  );
+
+  const clearSelection = useCallback(() => {
+    if (props.mode === 'single') props.onChange(null);
+    else props.onChange([]);
+  }, [props]);
+
+  // A category row means different things per mode: pick the whole category,
+  // tick all its leaves, or — when it is only a heading — just fold it.
+  const activateCategory = useCallback(
+    (group: CategoryGroup) => {
+      if (allowParentSelection && single) {
+        pick(group.category.id);
+        return;
+      }
+      if (allowParentSelection) {
+        toggleCategory(group);
+        return;
+      }
+      toggleExpanded(group.category.id);
+    },
+    [allowParentSelection, single, pick, toggleCategory, toggleExpanded],
+  );
+
+  const activateSubcategory = useCallback(
+    (id: string) => {
+      if (single) pick(id);
+      else toggleSubcategory(id);
+    },
+    [single, pick, toggleSubcategory],
+  );
+
+  return useMemo(
+    () => ({
+      commit,
+      pick,
+      cancel: closeAndRefocus,
+      clearSelection,
+      activateCategory,
+      activateSubcategory,
+    }),
+    [commit, pick, closeAndRefocus, clearSelection, activateCategory, activateSubcategory],
+  );
+}

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

@@ -0,0 +1,66 @@
+import { useCallback } from 'react';
+
+import { handleCategoryKeyDown } from './category-keyboard';
+import type { CategoryActions } from './useCategoryCommit';
+import type { CategorySelectState } from './useCategorySelect';
+
+interface UseCategoryKeyHandlerArgs {
+  state: CategorySelectState;
+  single: boolean;
+  allowParentSelection: boolean;
+  actions: CategoryActions;
+}
+
+/**
+ * Bind the panel's keydown to the tree navigator.
+ *
+ * `preventDefault` fires only for keys the navigator actually consumed, so an
+ * unhandled key still reaches the search box — otherwise typing would be dead.
+ */
+export function useCategoryKeyHandler({
+  state,
+  single,
+  allowParentSelection,
+  actions,
+}: UseCategoryKeyHandlerArgs): (event: React.KeyboardEvent) => void {
+  const { isExpanded, toggleExpanded } = state;
+
+  const expand = useCallback(
+    (id: string) => {
+      if (!isExpanded(id)) toggleExpanded(id);
+    },
+    [isExpanded, toggleExpanded],
+  );
+
+  const collapse = useCallback(
+    (id: string) => {
+      if (isExpanded(id)) toggleExpanded(id);
+    },
+    [isExpanded, toggleExpanded],
+  );
+
+  return useCallback(
+    (event: React.KeyboardEvent) => {
+      const inSearchField = (event.target as HTMLElement | null)?.tagName === 'INPUT';
+      const editingText = inSearchField && state.query.length > 0;
+      const consumed = handleCategoryKeyDown(event.key, editingText, {
+        rows: state.rows,
+        activeIndex: state.activeIndex,
+        groups: state.visibleGroups,
+        single,
+        allowParentSelection,
+        setActiveIndex: state.setActiveIndex,
+        toggleExpanded,
+        expand,
+        collapse,
+        toggleCategory: state.toggleCategory,
+        toggleSubcategory: state.toggleSubcategory,
+        commit: actions.commit,
+        cancel: actions.cancel,
+        pick: actions.pick,
+      });
+      if (consumed) event.preventDefault();
+    },
+    [state, single, allowParentSelection, toggleExpanded, expand, collapse, actions],
+  );
+}