@12-apps/ui 4.0.1 → 4.1.0

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

@@ -0,0 +1,172 @@
+import { useCallback, useMemo, useRef, useState } from 'react';
+
+import {
+  buildCategoryGroups,
+  filterCategoryGroups,
+  flattenRows,
+  toggleCategoryLeaves,
+  toggleLeaf,
+  type CategoryRowRef,
+} from './category-tree';
+import type { CategoryGroup, CategorySelectOption } from './CategorySelect.types';
+
+/** Which categories are unfolded, and the ways that set changes. */
+interface ExpansionState {
+  isExpanded: (categoryId: string) => boolean;
+  toggleExpanded: (categoryId: string) => void;
+  setAllExpanded: (expanded: boolean) => void;
+  expandAll: (groups: CategoryGroup[]) => void;
+}
+
+/**
+ * The expanded set.
+ *
+ * `searching` short-circuits the lookup instead of mutating the set: a query must
+ * reveal every hit, but clearing it has to restore whatever the admin had folded,
+ * which an overwrite would have destroyed.
+ */
+function useExpandedCategories(
+  allGroups: CategoryGroup[],
+  searching: boolean,
+): ExpansionState {
+  const [expanded, setExpanded] = useState<ReadonlySet<string>>(() => new Set());
+
+  const isExpanded = useCallback(
+    (categoryId: string) => searching || expanded.has(categoryId),
+    [searching, expanded],
+  );
+
+  const toggleExpanded = useCallback((categoryId: string) => {
+    setExpanded((current) => {
+      const next = new Set(current);
+      if (!next.delete(categoryId)) next.add(categoryId);
+      return next;
+    });
+  }, []);
+
+  const setAllExpanded = useCallback(
+    (shouldExpand: boolean) => {
+      setExpanded(shouldExpand ? new Set(allGroups.map((g) => g.category.id)) : new Set());
+    },
+    [allGroups],
+  );
+
+  const expandAll = useCallback((groups: CategoryGroup[]) => {
+    setExpanded(new Set(groups.map((group) => group.category.id)));
+  }, []);
+
+  return { isExpanded, toggleExpanded, setAllExpanded, expandAll };
+}
+
+/** The pending selection and the two ways a row changes it. */
+interface DraftState {
+  draft: ReadonlySet<string>;
+  setDraft: (next: ReadonlySet<string>) => void;
+  toggleCategory: (group: CategoryGroup) => void;
+  toggleSubcategory: (id: string) => void;
+}
+
+function useDraftSelection(initial: readonly string[]): DraftState {
+  const [draft, setDraftState] = useState<ReadonlySet<string>>(() => new Set(initial));
+
+  const toggleCategory = useCallback((group: CategoryGroup) => {
+    setDraftState((current) => toggleCategoryLeaves(group, current));
+  }, []);
+
+  const toggleSubcategory = useCallback((id: string) => {
+    setDraftState((current) => toggleLeaf(id, current));
+  }, []);
+
+  const setDraft = useCallback((next: ReadonlySet<string>) => setDraftState(next), []);
+
+  return { draft, setDraft, toggleCategory, toggleSubcategory };
+}
+
+/** Everything the panel and trigger need to render and drive one select. */
+export interface CategorySelectState extends ExpansionState, DraftState {
+  open: boolean;
+  query: string;
+  /** Groups after the search filter — what is actually on screen. */
+  visibleGroups: CategoryGroup[];
+  /** All groups, unfiltered — the basis for chips and "select all". */
+  allGroups: CategoryGroup[];
+  rows: CategoryRowRef[];
+  activeIndex: number;
+  setQuery: (next: string) => void;
+  setActiveIndex: (next: number) => void;
+  openPanel: () => void;
+  closePanel: () => void;
+  triggerRef: React.RefObject<HTMLButtonElement | null>;
+}
+
+interface UseCategorySelectArgs {
+  options: CategorySelectOption[];
+  /** The applied selection to seed the draft from each time the panel opens. */
+  selected: readonly string[];
+}
+
+/**
+ * Panel state for one CategorySelect.
+ *
+ * The DRAFT is the load-bearing idea. Ticks land here, not on the caller's
+ * `value`, so the list behind the panel does not refetch on every click; Apply
+ * publishes, dismissing discards. Opening re-seeds the draft from the applied
+ * value, which is what makes "cancel" mean cancel.
+ */
+export function useCategorySelect({
+  options,
+  selected,
+}: UseCategorySelectArgs): CategorySelectState {
+  const [open, setOpen] = useState(false);
+  const [query, setQueryState] = useState('');
+  const [activeIndex, setActiveIndex] = useState(-1);
+  const triggerRef = useRef<HTMLButtonElement | null>(null);
+
+  const allGroups = useMemo(() => buildCategoryGroups(options), [options]);
+  const visibleGroups = useMemo(
+    () => filterCategoryGroups(allGroups, query),
+    [allGroups, query],
+  );
+
+  const expansion = useExpandedCategories(allGroups, query.trim().length > 0);
+  const selection = useDraftSelection(selected);
+  const rows = useMemo(
+    () => flattenRows(visibleGroups, expansion.isExpanded),
+    [visibleGroups, expansion.isExpanded],
+  );
+
+  const openPanel = useCallback(() => {
+    selection.setDraft(new Set(selected));
+    expansion.expandAll(allGroups);
+    setQueryState('');
+    setActiveIndex(-1);
+    setOpen(true);
+  }, [selected, allGroups, selection, expansion]);
+
+  const closePanel = useCallback(() => {
+    setOpen(false);
+    setQueryState('');
+    setActiveIndex(-1);
+  }, []);
+
+  const setQuery = useCallback((next: string) => {
+    setQueryState(next);
+    setActiveIndex(-1);
+  }, []);
+
+  return {
+    ...expansion,
+    ...selection,
+    open,
+    query,
+    visibleGroups,
+    allGroups,
+    rows,
+    activeIndex,
+    setQuery,
+    setActiveIndex,
+    openPanel,
+    closePanel,
+    triggerRef,
+  };
+}

package/src/components/form/total-form/Fields/CategoryField.tsx

@@ -0,0 +1,57 @@
+'use client';
+
+import React from 'react';
+
+import { CategorySelect } from '../../CategorySelect';
+import type { CategorySelectOption } from '../../CategorySelect';
+import { useFormContext } from '../FormContext';
+
+/** Props for the `total-form` {@link CategoryField}. */
+export interface CategoryFieldProps {
+  /** Field name; also the key into the form's values/errors. */
+  name: string;
+  /** The categories to choose from, flat, each carrying its `parentId`. */
+  options: CategorySelectOption[];
+  /** Optional visible label rendered above the control. */
+  label?: string;
+  /** Placeholder shown while nothing is chosen. */
+  placeholder?: string;
+  /** Lets a top-level category be chosen in its own right (default: `true`). */
+  allowParentSelection?: boolean;
+}
+
+/**
+ * Category picker bound to {@link useFormContext}.
+ *
+ * The sibling {@link SelectField} flattens a category tree into one list, which
+ * is the thing the hierarchical picker exists to stop. Use this wherever the
+ * field's options nest.
+ *
+ * Form values are strings, so "nothing chosen" travels as `""` — mapped to and
+ * from the control's `null` here rather than making every caller do it.
+ */
+export function CategoryField({
+  name,
+  options,
+  label,
+  placeholder,
+  allowParentSelection = true,
+}: CategoryFieldProps): React.ReactElement {
+  const { values, errors, setFieldValue } = useFormContext();
+  const error = errors[name];
+
+  return (
+    <CategorySelect
+      mode="single"
+      fullWidth
+      label={label}
+      placeholder={placeholder}
+      options={options}
+      allowParentSelection={allowParentSelection}
+      value={values[name] ? values[name] : null}
+      error={error}
+      onChange={(next) => setFieldValue(name, next ?? '')}
+      dataTestId={`total-form-field-${name}`}
+    />
+  );
+}

package/src/components/form/total-form/Fields/index.ts

@@ -1,3 +1,5 @@
+export { CategoryField } from './CategoryField';
+export type { CategoryFieldProps } from './CategoryField';
 export { CepField } from './CepField';
 export type { CepFieldProps, CepFills } from './CepField';
 export { TextField } from './TextField';

package/src/components/form/total-form/index.ts

@@ -8,5 +8,5 @@ export { SubmitButton } from './SubmitButton';
 export type { SubmitButtonProps } from './SubmitButton';
 
 export * as Fields from './Fields';
-export { TextField, SelectField } from './Fields';
-export type { TextFieldProps, SelectFieldProps } from './Fields';
+export { CategoryField, TextField, SelectField } from './Fields';
+export type { CategoryFieldProps, TextFieldProps, SelectFieldProps } from './Fields';